Reference for stage 3 resizablearraybuffer

files/en-us/web/javascript/reference/global_objects/arraybuffer/arraybuffer/index.md

@@ -15,6 +15,7 @@ The **`ArrayBuffer()`** constructor is used to create {{jsxref("ArrayBuffer")}}
 
 ```js-nolint
 new ArrayBuffer(length)
+new ArrayBuffer(length, options)
 ```
 
 > **Note:** `ArrayBuffer()` can only be constructed with [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new). Attempting to call it without `new` throws a {{jsxref("TypeError")}}.
@@ -23,16 +24,21 @@ new ArrayBuffer(length)
 
 - `length`
   - : The size, in bytes, of the array buffer to create.
+- `options` {{optional_inline}} {{experimental_inline}}
+  - : An object, which can contain the following properties:
+    - `maxByteLength` {{optional_inline}} {{experimental_inline}}
+      - : The maximum size, in bytes, that the array buffer can be resized to.
 
 ### Return value
 
-A new `ArrayBuffer` object of the specified size. Its contents are
-initialized to 0.
+A new `ArrayBuffer` object of the specified size, with its {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}} property set to the specified `maxByteLength` if one was specified. Its contents are initialized to 0.
 
 ### Exceptions
 
 - {{jsxref("RangeError")}}
-  - : Thrown if the `length` is larger than {{jsxref("Number.MAX_SAFE_INTEGER")}} (≥ 2<sup>53</sup>) or negative.
+  - : Thrown if one of the following is true:
+    - `length` or `maxByteLength` is larger than {{jsxref("Number.MAX_SAFE_INTEGER")}} (≥ 2<sup>53</sup>) or negative.
+    - `length` is larger than `maxByteLength`.
 
 ## Examples
 
@@ -46,6 +52,18 @@ const buffer = new ArrayBuffer(8);
 const view = new Int32Array(buffer);
 ```
 
+### Creating a resizable ArrayBuffer
+
+In this example, we create a 8-byte buffer that is resizable to a max length of 16 bytes, then {{jsxref("ArrayBuffer/resize", "resize()")}} it to 12 bytes:
+
+```js
+const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
+
+buffer.resize(12);
+```
+
+> **Note:** It is recommended that `maxByteLength` is set to the smallest value possible for your use case. It should never exceed `1073741824` (1GB) to reduce the risk of out-of-memory errors.
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/javascript/reference/global_objects/arraybuffer/index.md

@@ -7,14 +7,20 @@ browser-compat: javascript.builtins.ArrayBuffer
 
 {{JSRef}}
 
-The **`ArrayBuffer`** object is used to represent a generic, fixed-length raw binary data buffer.
+The **`ArrayBuffer`** object is used to represent a generic raw binary data buffer.
 
 It is an array of bytes, often referred to in other languages as a "byte array". You cannot directly manipulate the contents of an `ArrayBuffer`; instead, you create one of the [typed array objects](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) or a {{jsxref("DataView")}} object which represents the buffer in a specific format, and use that to read and write the contents of the buffer.
 
 The [`ArrayBuffer()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/ArrayBuffer) constructor creates a new `ArrayBuffer` of the given length in bytes. You can also get an array buffer from existing data, for example, from a [Base64](/en-US/docs/Glossary/Base64) string or [from a local file](/en-US/docs/Web/API/FileReader/readAsArrayBuffer).
 
 `ArrayBuffer` is a [transferable object](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects).
 
+### Resizing ArrayBuffers
+
+`ArrayBuffer`s can be made resizable by including the `maxByteLength` option when calling the {{jsxref("ArrayBuffer.ArrayBuffer", "constructor", "", "nocode")}}. You can query whether an `ArrayBuffer` is resizable and what its maximum size is by accessing its {{jsxref("ArrayBuffer.prototype.resizable", "resizable")}} and {{jsxref("ArrayBuffer.prototype.maxByteLength", "maxByteLength")}} properties, respectively. You can assign a new size to a resizable `ArrayBuffer` with a {{jsxref("ArrayBuffer.prototype.resize()", "resize()")}} call.
+
+These additions have made resizing `ArrayBuffer`s more efficient — previously you had to make a copy with a new size. It also gives JavaScript parity with WebAssembly in this regard (WASM linear memory can be resized with [`WebAssembly.Memory.prototype.grow()`](/en-US/docs/WebAssembly/JavaScript_interface/Memory/grow)).
+
 ## Constructor
 
 - {{jsxref("ArrayBuffer.ArrayBuffer", "ArrayBuffer()")}}
@@ -35,7 +41,11 @@ The [`ArrayBuffer()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayB
 These properties are defined on `ArrayBuffer.prototype` and shared by all `ArrayBuffer` instances.
 
 - {{jsxref("ArrayBuffer.prototype.byteLength")}}
-  - : The read-only size, in bytes, of the `ArrayBuffer`. This is established when the array is constructed and cannot be changed.
+  - : The size, in bytes, of the `ArrayBuffer`. This is established when the array is constructed and can be changed using the {{jsxref("ArrayBuffer.prototype.resize()")}} method.
+- {{jsxref("ArrayBuffer.prototype.maxByteLength")}} {{experimental_inline}}
+  - : The read-only maximum length, in bytes, that the `ArrayBuffer` can be resized to. This is established when the array is constructed and cannot be changed.
+- {{jsxref("ArrayBuffer.prototype.resizable")}} {{experimental_inline}}
+  - : Read-only. Returns `true` if the `ArrayBuffer` can be resized, or `false` if not.
 - {{jsxref("Object/constructor", "ArrayBuffer.prototype.constructor")}}
   - : The constructor function that created the instance object. For `ArrayBuffer` instances, the initial value is the {{jsxref("ArrayBuffer/ArrayBuffer", "ArrayBuffer")}} constructor.
 - `ArrayBuffer.prototype[@@toStringTag]`
@@ -45,6 +55,8 @@ These properties are defined on `ArrayBuffer.prototype` and shared by all `Array
 
 - {{jsxref("ArrayBuffer.prototype.slice()")}}
   - : Returns a new `ArrayBuffer` whose contents are a copy of this `ArrayBuffer`'s bytes from `begin` (inclusive) up to `end` (exclusive). If either `begin` or `end` is negative, it refers to an index from the end of the array, as opposed to from the beginning.
+- {{jsxref("ArrayBuffer.prototype.resize()")}} {{experimental_inline}}
+  - : Resizes the `ArrayBuffer` to the specified size, in bytes.
 
 ## Examples
 

files/en-us/web/javascript/reference/global_objects/arraybuffer/maxbytelength/index.md

@@ -0,0 +1,46 @@
+---
+title: ArrayBuffer.prototype.maxByteLength
+slug: Web/JavaScript/Reference/Global_Objects/ArrayBuffer/maxByteLength
+page-type: javascript-instance-accessor-property
+status:
+  - experimental
+browser-compat: javascript.builtins.ArrayBuffer.maxByteLength
+---
+
+{{JSRef}}{{SeeCompatTable}}
+
+The **`maxByteLength`** accessor property of {{jsxref("ArrayBuffer")}} instances represents the maximum length, in bytes, that the `ArrayBuffer` can be resized to.
+
+{{EmbedInteractiveExample("pages/js/arraybuffer-maxbytelength.html")}}
+
+## Description
+
+The `maxByteLength` property is an accessor property whose set accessor function is `undefined`, meaning that you can only read this property. The value is established when the array is constructed, set via the `maxByteLength` option of the {{jsxref("ArrayBuffer/ArrayBuffer", "ArrayBuffer()")}} constructor, and cannot be changed.
+
+This property returns 0 if this `ArrayBuffer` has been detached. If this `ArrayBuffer` was constructed without specifying a `maxByteLength` value, this property returns a value equal to the value of the `ArrayBuffer`'s {{jsxref("ArrayBuffer/byteLength", "byteLength")}}.
+
+## Examples
+
+### Using maxByteLength
+
+In this example, we create an 8-byte buffer that is resizable to a max length of 16 bytes, then return its `maxByteLength`:
+
+```js
+const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
+
+buffer.maxByteLength; // 16
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("ArrayBuffer")}}
+- {{jsxref("ArrayBuffer.prototype.byteLength")}}
+- {{jsxref("ArrayBuffer.prototype.resize()")}}

files/en-us/web/javascript/reference/global_objects/arraybuffer/resizable/index.md

@@ -0,0 +1,47 @@
+---
+title: ArrayBuffer.prototype.resizable
+slug: Web/JavaScript/Reference/Global_Objects/ArrayBuffer/resizable
+page-type: javascript-instance-accessor-property
+status:
+  - experimental
+browser-compat: javascript.builtins.ArrayBuffer.resizable
+---
+
+{{JSRef}}{{SeeCompatTable}}
+
+The **`resizable`** accessor property of {{jsxref("ArrayBuffer")}} instances represents whether the `ArrayBuffer` can be resized or not.
+
+{{EmbedInteractiveExample("pages/js/arraybuffer-resizable.html")}}
+
+## Description
+
+The `resizable` property is an accessor property whose set accessor function is `undefined`, meaning that you can only read this property. The value is established when the array is constructed. If the `maxByteLength` option was set in the constructor, `resizable` will return `true`; if not, it will return `false`.
+
+## Examples
+
+### Using resizable
+
+In this example, we create a 8-byte buffer that is resizable to a max length of 16 bytes, then check its `resizable` property, resizing it if `resizable` returns `true`:
+
+```js
+const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
+
+if (buffer.resizable) {
+  console.log("Buffer is resizable!");
+  buffer.resize(12);
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("ArrayBuffer")}}
+- {{jsxref("ArrayBuffer.prototype.maxByteLength")}}
+- {{jsxref("ArrayBuffer.prototype.resize()")}}

files/en-us/web/javascript/reference/global_objects/arraybuffer/resize/index.md

@@ -0,0 +1,71 @@
+---
+title: ArrayBuffer.prototype.resize()
+slug: Web/JavaScript/Reference/Global_Objects/ArrayBuffer/resize
+page-type: javascript-instance-method
+status:
+  - experimental
+browser-compat: javascript.builtins.ArrayBuffer.resize
+---
+
+{{JSRef}}{{SeeCompatTable}}
+
+The **`resize()`** method of {{jsxref("ArrayBuffer")}} instances resizes the `ArrayBuffer` to the specified size, in bytes.
+
+{{EmbedInteractiveExample("pages/js/arraybuffer-resize.html")}}
+
+## Syntax
+
+```js-nolint
+resize(newLength)
+```
+
+### Parameters
+
+- `newLength`
+  - : The new length, in bytes, to resize the `ArrayBuffer` to.
+
+### Return value
+
+{{jsxref("undefined")}}.
+
+### Exceptions
+
+- {{jsxref("TypeError")}}
+  - : Thrown if the `ArrayBuffer` is detached or is not resizable.
+- {{jsxref("RangeError")}}
+  - : Thrown if `newLength` is larger than the {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}} of the `ArrayBuffer`.
+
+## Description
+
+The `resize()` method resizes an `ArrayBuffer` to the size specified by the `newLength` parameter, provided that the `ArrayBuffer` is [resizable](/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/resizable) and the new size is less than or equal to the {{jsxref("ArrayBuffer/maxByteLength", "maxByteLength")}} of the `ArrayBuffer`.
+
+Note that you can use `resize()` to shrink as well as grow an `ArrayBuffer` — it is permissible for `newLength` to be smaller than the `ArrayBuffer`'s current {{jsxref("ArrayBuffer/byteLength", "byteLength")}}.
+
+## Examples
+
+### Using resize()
+
+In this example, we create a 8-byte buffer that is resizable to a max length of 16 bytes, then check its `resizable` property, resizing it if `resizable` returns `true`:
+
+```js
+const buffer = new ArrayBuffer(8, { maxByteLength: 16 });
+
+if (buffer.resizable) {
+  console.log("Buffer is resizable!");
+  buffer.resize(12);
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("ArrayBuffer")}}
+- {{jsxref("ArrayBuffer.prototype.resizable")}}
+- {{jsxref("ArrayBuffer.prototype.maxByteLength")}}

files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/grow/index.md

@@ -0,0 +1,67 @@
+---
+title: SharedArrayBuffer.prototype.grow()
+slug: Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/grow
+page-type: javascript-instance-method
+status:
+  - experimental
+browser-compat: javascript.builtins.SharedArrayBuffer.grow
+---
+
+{{JSRef}}{{SeeCompatTable}}
+
+The **`grow()`** method of {{jsxref("SharedArrayBuffer")}} instances grows the `SharedArrayBuffer` to the specified size, in bytes.
+
+## Syntax
+
+```js-nolint
+grow(newLength)
+```
+
+### Parameters
+
+- `newLength`
+  - : The new length, in bytes, to resize the `SharedArrayBuffer` to.
+
+### Return value
+
+{{jsxref("undefined")}}.
+
+### Exceptions
+
+- {{jsxref("TypeError")}}
+  - : Thrown if the `SharedArrayBuffer` is not growable.
+- {{jsxref("RangeError")}}
+  - : Thrown if `newLength` is larger than the {{jsxref("SharedArrayBuffer/maxByteLength", "maxByteLength")}} of the `SharedArrayBuffer` or smaller than the {{jsxref("SharedArrayBuffer/byteLength", "byteLength")}}.
+
+## Description
+
+The `grow()` method grows a `SharedArrayBuffer` to the size specified by the `newLength` parameter, provided that the `SharedArrayBuffer` is [resizable](/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/growable) and the new size is less than or equal to the {{jsxref("SharedArrayBuffer/maxByteLength", "maxByteLength")}} of the `SharedArrayBuffer`.
+
+## Examples
+
+### Using grow()
+
+In this example, we create a 8-byte buffer that is growable to a max length of 16 bytes, then check its {{jsxref("SharedArrayBuffer/growable", "growable")}} property, growing it if `growable` returns `true`:
+
+```js
+const buffer = new SharedArrayBuffer(8, { maxByteLength: 16 });
+
+if (buffer.growable) {
+  console.log("SAB is growable!");
+  buffer.grow(12);
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("SharedArrayBuffer")}}
+- {{jsxref("SharedArrayBuffer.prototype.growable")}}
+- {{jsxref("SharedArrayBuffer.prototype.maxByteLength")}}

files/en-us/web/javascript/reference/global_objects/sharedarraybuffer/growable/index.md

@@ -0,0 +1,45 @@
+---
+title: SharedArrayBuffer.prototype.growable
+slug: Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/growable
+page-type: javascript-instance-accessor-property
+status:
+  - experimental
+browser-compat: javascript.builtins.SharedArrayBuffer.growable
+---
+
+{{JSRef}}{{SeeCompatTable}}
+
+The **`growable`** accessor property of {{jsxref("SharedArrayBuffer")}} instances represents whether the {{jsxref("SharedArrayBuffer")}} can be grow or not.
+
+## Description
+
+The `growable` property is an accessor property whose set accessor function is `undefined`, meaning that you can only read this property. The value is established when the array is constructed. If a `maxByteLength` option was set in the constructor, `growable` will return `true`; if not, it will return `false`.
+
+## Examples
+
+### Using growable
+
+In this example, we create a 8-byte buffer that is growable to a max length of 16 bytes, then check its {{jsxref("SharedArrayBuffer/growable", "growable")}} property, growing it if `growable` returns `true`:
+
+```js
+const buffer = new SharedArrayBuffer(8, { maxByteLength: 16 });
+
+if (buffer.growable) {
+  console.log("SAB is growable!");
+  buffer.grow(12);
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("SharedArrayBuffer")}}
+- {{jsxref("SharedArrayBuffer.prototype.grow()")}}
+- {{jsxref("SharedArrayBuffer.prototype.maxByteLength")}}