├── .gitattributes ├── .github └── workflows │ └── build.yml ├── .gitignore ├── .npmrc ├── LICENSE ├── README.md ├── design.md ├── index.html ├── package.json └── spec.emu /.gitattributes: -------------------------------------------------------------------------------- 1 | index.html -diff merge=ours 2 | spec.js -diff merge=ours 3 | spec.css -diff merge=ours 4 | -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: Deploy spec 2 | 3 | on: [push] 4 | 5 | jobs: 6 | build: 7 | runs-on: ubuntu-latest 8 | 9 | steps: 10 | - uses: actions/checkout@v2 11 | - uses: actions/setup-node@v1 12 | with: 13 | node-version: '12.x' 14 | - run: npm install 15 | - run: npm run build 16 | - name: commit changes 17 | uses: elstudio/actions-js-build/commit@v3 18 | with: 19 | commitMessage: "fixup: [spec] `npm run build`" 20 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | 6 | # Runtime data 7 | pids 8 | *.pid 9 | *.seed 10 | 11 | # Directory for instrumented libs generated by jscoverage/JSCover 12 | lib-cov 13 | 14 | # Coverage directory used by tools like istanbul 15 | coverage 16 | 17 | # nyc test coverage 18 | .nyc_output 19 | 20 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 21 | .grunt 22 | 23 | # node-waf configuration 24 | .lock-wscript 25 | 26 | # Compiled binary addons (http://nodejs.org/api/addons.html) 27 | build/Release 28 | 29 | # Dependency directories 30 | node_modules 31 | jspm_packages 32 | 33 | # Optional npm cache directory 34 | .npm 35 | 36 | # Optional REPL history 37 | .node_repl_history 38 | 39 | # Only apps should have lockfiles 40 | yarn.lock 41 | package-lock.json 42 | npm-shrinkwrap.json 43 | pnpm-lock.yaml 44 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | package-lock=false 2 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 ECMA TC39 and contributors 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Limited ArrayBuffer 2 | 3 | ## Status 4 | 5 | Champion(s): *[Jack Works](https://github.com/Jack-Works)* 6 | 7 | Author(s): *Jack Works* 8 | 9 | Stage: 1 10 | 11 | ## Presentations 12 | 13 | - [For stage 1 on 82th tc39 meeting (Apr 2021)](https://docs.google.com/presentation/d/1TGLvflOG63C5iHush597ffKTenoYowc3MivQEhAM20w/edit?usp=sharing) 14 | - [TC39 meeting notes on 82th tc39 meeting](https://github.com/tc39/notes/blob/master/meetings/2021-04/apr-21.md#read-only-arraybuffer-and-fixed-view-of-arraybuffer-for-stage-1) 15 | 16 | ## Problem to be resolved 17 | 18 | All of the following are helpful to archive the minimal permission/information principle. 19 | 20 | 1. Cannot make an `ArrayBuffer` read-only. 21 | 2. Cannot give others a read-only view to the `ArrayBuffer` and keep the read-write permission internally. 22 | 3. Cannot give others a view that range limited (only a small area of the whole buffer is visible). 23 | 24 | ## Design goal 25 | 26 | 1. Freeze the `ArrayBuffer`. 27 | 1. Like `Object.freeze`, there is no way back once frozen. 28 | 2. Any `TypedArray`/`DataView` to the freezed `ArrayBuffer` is read-only too. 29 | 3. [Optional] Keep frozen when sent across Realm (HTML intergration). 30 | 2. Read-only `TypedArray`/`DataView` to a read-write `ArrayBuffer`. 31 | 1. Must not be able to construct a read-write view from a read-only view. 32 | 3. [Optional] Range-limited `TypedArray`/`DataView` to a read-write `ArrayBuffer` ([CrimsonCodes0](https://github.com/CrimsonCodes0)'s [use case on WebAssembly](https://github.com/tc39/proposal-limited-arraybuffer/issues/11)). 33 | 1. Must not be able to construct a bigger view range from a smaller view range. 34 | 4. Not adding too much complexity to the implementor. 35 | 36 | ## Pros 37 | 38 | 1. Minimal permission/information principle works on `ArrayBuffer`. 39 | 2. Embedded JS engines can represent ROMs as read-only `ArrayBuffer`. 40 | 41 | ## API design 42 | 43 | See [design.md](./design.md) 44 | -------------------------------------------------------------------------------- /design.md: -------------------------------------------------------------------------------- 1 | The current design is tried to match the 2 | [Readonly Collections proposal](https://github.com/tc39/proposal-readonly-collections). But `ArrayBuffer` is not a 3 | a collection so the design won't be the same. 4 | 5 | # Design goal 6 | 7 | 1. Freeze the `ArrayBuffer`. 8 | 2. Read-only `TypedArray`/`DataView` to an `ArrayBuffer`. 9 | 3. Unescapable slice of `TypedArray`/`DataView` to an `ArrayBuffer`. 10 | 4. Not creating new code branches on a hot path when it is unnecessary. 11 | 5. Have similar API design with [Readonly collections proposal](https://github.com/tc39/proposal-readonly-collections) 12 | 13 | # ArrayBuffer.prototype.freeze() 14 | 15 | Note: [issue #9](https://github.com/tc39/proposal-limited-arraybuffer/issues/9), suggests removing this function based on the following reasoning: **If all read-write view to an ArrayBuffer has been GC, the engine can assume the underlying buffer is read-only.** But I'm not favoring this because it is an implicit opt-in. 16 | 17 | After calling this function on **ArrayBuffer** _A_: 18 | 19 | ## Any TypedArray _T_ where it's [[ViewedArrayBuffer]] is _A_ 20 | 21 | 1. [[[GetOwnProperty]]](https://tc39.es/ecma262/multipage/ordinary-and-exotic-objects-behaviours.html#sec-integer-indexed-exotic-objects-getownproperty-p): 22 | Return `[[Writable]]: false, [[Configurable]]: false` for existing numeric keys. 23 | 2. [[[DefineOwnProperty]]](https://tc39.es/ecma262/multipage/ordinary-and-exotic-objects-behaviours.html#sec-integer-indexed-exotic-objects-defineownproperty-p-desc): 24 | Change the behavior to accept descriptor with `[[Writable]]: false` or `[[Configurable]]: false`; Throw when trying to 25 | define a different `[[Value]]`. 26 | 3. [[[Set]]](https://tc39.es/ecma262/multipage/ordinary-and-exotic-objects-behaviours.html#sec-integer-indexed-exotic-objects-set-p-v-receiver): 27 | Throw. 28 | 4. [[[Delete]]](https://tc39.es/ecma262/multipage/ordinary-and-exotic-objects-behaviours.html#sec-integer-indexed-exotic-objects-delete-p): 29 | Throw. 30 | 31 | ## Any DataView _V_ where it's [[ViewedArrayBuffer]] is _A_ 32 | 33 | 1. **setBigInt64, setBigUint64, setFloat32, setFloat64, setInt8, setInt16, setInt32, setUint8, setUint16, setUint32**: 34 | Throw. 35 | 36 | ## Host integration 37 | 38 | 1. If a Host API need to write an **ArrayBuffer** _A_, 39 | 1. if _A_ is frozen, throws. 40 | 2. Prevent _A_ to be frozen. 41 | 3. Host may re-allow freeze _A_ after the host no longer needs the write access. 42 | 43 | ## SharedArrayBuffer integration 44 | 45 | Possible choices: 46 | 47 | 1. Throw? (do not allow freeze on SABs). 48 | 2. Froze the SAB? (May impact usability). 49 | 50 | ## ResizableArrayBuffer integration 51 | 52 | 1. Freeze the **ResizableArrayBuffer**. 53 | 2. Throw when trying to resize. 54 | 55 | # get ArrayBuffer.prototype.isFrozen() 56 | 57 | 1. Return **true** if the **this** value has been frozen. 58 | 59 | # %TypedArray%.prototype.readOnlyView() 60 | 61 | This API design is trying to match the 62 | [Readonly collection proposal](https://github.com/tc39/proposal-readonly-collections#snapshotdivergereadonlyview-methods-for-all-collections). 63 | 64 | Note: It provides a read-only view to a possibly mutable **ArrayBuffer**. 65 | 66 | 1. `%TypedArray%.prototype.readOnlyView()` returns a new `%TypedArray%` object with same **offset** and **length**. (Or 67 | we can create a new `ReadonlyTypedArray` type for it). 68 | 2. If a `%TypedArray%` is already a readonly view, calling `readonlyView()` on it will return it self. 69 | 3. `[[GetOwnProperty]]`: Return `[[Writable]]: false, [[Configurable]]: true` for existing numeric keys. (**NOT SAME** 70 | as `[[GetOwnProperty]]` above.) 71 | 4. `[[DefineOwnProperty]]`: Throw. 72 | 5. `[[Set]]`: Throw. 73 | 6. `[[Delete]]`: Throw. 74 | 7. get `%TypedArray%.prototype.buffer`: Return undefine or throw. (If we have `ArrayBufferSlice`, return a new slice that is read-only). 75 | 8. Any new `%TypedArray%` created based on this one is also read-only. 76 | 77 | # DataView.prototype.readOnlyView() 78 | 79 | Same design as `%TypedArray%.prototype.readOnlyView()`. 80 | 81 | # ArrayBuffer.prototype.snapshot() 82 | 83 | This API design is trying to match the 84 | [Readonly collection proposal](https://github.com/tc39/proposal-readonly-collections#snapshotdivergereadonlyview-methods-for-all-collections). 85 | 86 | Clone a new read-only `ArrayBuffer`. If the current `ArrayBuffer` is already read-only, it will return itself. 87 | 88 | # %TypedArray%.prototype.snapshot() 89 | 90 | This API is required if we do not have `ArrayBufferSlice` because `%TypedArray%.prototype.buffer` will return undefined/throw therefore it's impossible to create a snaphost on a read-only typed array view. 91 | 92 | ```js 93 | readonlyU8Array.buffer.snapshot() 94 | // Throw: Cannot read property snapshot of undefined 95 | ``` 96 | 97 | # ArrayBuffer.prototype.diverge() 98 | 99 | This API design is trying to match the 100 | [Readonly collection proposal](https://github.com/tc39/proposal-readonly-collections#snapshotdivergereadonlyview-methods-for-all-collections). 101 | 102 | Clone a new mutable `ArrayBuffer` (even if the current `ArrayBuffer` is read-only). 103 | 104 | # %TypedArray%.prototype.diverge() 105 | 106 | This API is required if we do not have `ArrayBufferSlice` because `%TypedArray%.prototype.buffer` will return undefined/throw therefore it's impossible to create a diverge on a read-only typed array view. 107 | 108 | ```js 109 | readonlyU8Array.buffer.diverge() 110 | // Throw: Cannot read property snapshot of undefined 111 | ``` 112 | 113 | ## Why not have `readonlyView` on `ArrayBuffer`? 114 | 115 | `ArrayBuffer` itself is not a view to a collection. It needs to be viewed with `TypedArray` or `DataView`. 116 | 117 | # (Possible) New primitive type 118 | 119 | 1. New primitive type `arraybuffer`. 120 | 2. Always immutable. 121 | 3. Can generate from `ArrayBuffer.prototype.toPrimitive()` 122 | 4. Has prototype `ArrayBuffer.prototype`. 123 | 5. `ToObject` make it an `ArrayBuffer` object. 124 | 125 | # (Possible) ArrayBufferSlice 126 | 127 | This part is intended to resolve the use case of [issue #11](https://github.com/tc39/proposal-limited-arraybuffer/issues/11). 128 | 129 | > One wants the slice to be read-only in order to prevent writing to the memory, and one doesn't want to move around the entire ArrayBuffer object, as that would allow reading into the memory at practically arbitrary locations. 130 | 131 | 1. Can be created by `ArrayBuffer.prototype.placeholder_name_to_create_a_new_slice(offset, length)` 132 | 1. Calling `.freeze()` on an `ArrayBufferSlice` will throw. 133 | 1. `%TypedArray%`, `DataView` and host APIs can also accept `ArrayBufferSlice` when `ArrayBuffer` is accepted. 134 | 1. Cannot get the wider view based on the `ArrayBufferSlice`. 135 | 1. Can create a read-only slice and keep the underlying `ArrayBuffer` mutable. 136 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Proposal Title Goes Here
2409 |

Stage -1 Draft / February 7, 2022

Proposal Title Goes Here

2418 | 2419 | 2420 |

1 This is an emu-clause

2421 |

This is an algorithm:

2422 |
  1. Let proposal be undefined.
  2. If IsAccepted(proposal),
    1. Let stage be 0.
  3. Else,
    1. Let stage be -1.
  4. Return ? ToString(proposal).
2423 |
2424 |

A Copyright & Software License

2425 | 2426 |

Copyright Notice

2427 |

© 2022 Your Name(s) Here

2428 | 2429 |

Software License

2430 |

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

2431 | 2432 |

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

2433 | 2434 |
    2435 |
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. 2436 |
  3. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  4. 2437 |
  5. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.
  6. 2438 |
2439 | 2440 |

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

2441 | 2442 |
2443 |
-------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "name": "template-for-proposals", 4 | "description": "A repository template for ECMAScript proposals.", 5 | "scripts": { 6 | "start": "npm run build-loose -- --watch", 7 | "build": "npm run build-loose -- --strict", 8 | "build-loose": "ecmarkup --verbose spec.emu index.html" 9 | }, 10 | "homepage": "https://github.com/Jack-Works/proposal-freeze-arraybuffer-and-readonly-view#readme", 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/Jack-Works/proposal-freeze-arraybuffer-and-readonly-view.git" 14 | }, 15 | "license": "MIT", 16 | "devDependencies": { 17 | "ecmarkup": "^9.6.1" 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /spec.emu: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 |
 7 | title: Proposal Title Goes Here
 8 | stage: -1
 9 | contributors: Your Name(s) Here
10 | 
11 | 12 | 13 |

This is an emu-clause

14 |

This is an algorithm:

15 | 16 | 1. Let _proposal_ be *undefined*. 17 | 1. If IsAccepted(_proposal_), 18 | 1. Let _stage_ be *0*. 19 | 1. Else, 20 | 1. Let _stage_ be *-1*. 21 | 1. Return ? ToString(_proposal_). 22 | 23 |
24 | --------------------------------------------------------------------------------