diff options
Diffstat (limited to 'docs/guides/binary')
23 files changed, 454 insertions, 0 deletions
diff --git a/docs/guides/binary/arraybuffer-to-array.md b/docs/guides/binary/arraybuffer-to-array.md new file mode 100644 index 000000000..688030b0a --- /dev/null +++ b/docs/guides/binary/arraybuffer-to-array.md @@ -0,0 +1,27 @@ +--- +name: Convert an ArrayBuffer to an array of numbers +--- + +To retrieve the contents of an `ArrayBuffer` as an array of numbers, create a [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) over of the buffer. and use the [`Array.from()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) method to convert it to an array. + +```ts +const buf = new ArrayBuffer(64); +const arr = new Uint8Array(buf); +arr.length; // 64 +arr[0]; // 0 (instantiated with all zeros) +``` + +--- + +The `Uint8Array` class supports array indexing and iteration. However if you wish to convert the instance to a regular `Array`, use `Array.from()`. (This will likely be slower than using the `Uint8Array` directly.) + +```ts +const buf = new ArrayBuffer(64); +const uintArr = new Uint8Array(buf); +const regularArr = Array.from(uintArr); +// number[] +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/arraybuffer-to-blob.md b/docs/guides/binary/arraybuffer-to-blob.md new file mode 100644 index 000000000..53795282e --- /dev/null +++ b/docs/guides/binary/arraybuffer-to-blob.md @@ -0,0 +1,24 @@ +--- +name: Convert an ArrayBuffer to a Blob +--- + +A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) can be constructed from an array of "chunks", where each chunk is a string, binary data structure, or another `Blob`. + +```ts +const buf = new ArrayBuffer(64); +const blob = new Blob([buf]); +``` + +--- + +By default the `type` of the resulting `Blob` will be unset. This can be set manually. + +```ts +const buf = new ArrayBuffer(64); +const blob = new Blob([buf], { type: "application/octet-stream" }); +blob.type; // => "application/octet-stream" +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/arraybuffer-to-buffer.md b/docs/guides/binary/arraybuffer-to-buffer.md new file mode 100644 index 000000000..2737ebb4e --- /dev/null +++ b/docs/guides/binary/arraybuffer-to-buffer.md @@ -0,0 +1,25 @@ +--- +name: Convert an ArrayBuffer to a Uint8Array +--- + +The Node.js [`Buffer`](https://nodejs.org/api/buffer.html) API predates the introduction of `ArrayBuffer` into the JavaScript language. Bun implements both. + +Use the static `Buffer.from()` method to create a `Buffer` from an `ArrayBuffer`. + +```ts +const arrBuffer = new ArrayBuffer(64); +const nodeBuffer = Buffer.from(arrBuffer); +``` + +--- + +To create a `Buffer` that only views a portion of the underlying buffer, pass the offset and length to the constructor. + +```ts +const arrBuffer = new ArrayBuffer(64); +const nodeBuffer = Buffer.from(arrBuffer, 0, 16); // view first 16 bytes +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/arraybuffer-to-string.md b/docs/guides/binary/arraybuffer-to-string.md new file mode 100644 index 000000000..13bb83122 --- /dev/null +++ b/docs/guides/binary/arraybuffer-to-string.md @@ -0,0 +1,15 @@ +--- +name: Convert an ArrayBuffer to a string +--- + +Bun implements the Web-standard [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) class for converting between binary data types and strings. + +```ts +const buf = new ArrayBuffer(64); +const decoder = new TextDecoder(); +const str = decoder.decode(buf); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/arraybuffer-to-typedarray.md b/docs/guides/binary/arraybuffer-to-typedarray.md new file mode 100644 index 000000000..a4e823d8f --- /dev/null +++ b/docs/guides/binary/arraybuffer-to-typedarray.md @@ -0,0 +1,39 @@ +--- +name: Convert an ArrayBuffer to a Uint8Array +--- + +A `Uint8Array` is a _typed array_, meaning it is a mechanism for viewing the data in an underlying `ArrayBuffer`. + +```ts +const buffer = new ArrayBuffer(64); +const arr = new Uint8Array(buffer); +``` + +--- + +Instances of other typed arrays can be created similarly. + +```ts +const buffer = new ArrayBuffer(64); + +const arr1 = new Uint8Array(buffer); +const arr2 = new Uint16Array(buffer); +const arr3 = new Uint32Array(buffer); +const arr4 = new Float32Array(buffer); +const arr5 = new Float64Array(buffer); +const arr6 = new BigInt64Array(buffer); +const arr7 = new BigUint64Array(buffer); +``` + +--- + +To create a typed array that only views a portion of the underlying buffer, pass the offset and length to the constructor. + +```ts +const buffer = new ArrayBuffer(64); +const arr = new Uint8Array(buffer, 0, 16); // view first 16 bytes +``` + +--- + +See [Docs > API > Utils](/docs/api/utils) for more useful utilities. diff --git a/docs/guides/binary/blob-to-arraybuffer.md b/docs/guides/binary/blob-to-arraybuffer.md new file mode 100644 index 000000000..18e3f1235 --- /dev/null +++ b/docs/guides/binary/blob-to-arraybuffer.md @@ -0,0 +1,14 @@ +--- +name: Convert a Blob to an ArrayBuffer +--- + +The [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) class provides a number of methods for consuming its contents in different formats, including `.arrayBuffer()`. + +```ts +const blob = new Blob(["hello world"]); +const buf = await blob.arrayBuffer(); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/blob-to-dataview.md b/docs/guides/binary/blob-to-dataview.md new file mode 100644 index 000000000..7d874c1f6 --- /dev/null +++ b/docs/guides/binary/blob-to-dataview.md @@ -0,0 +1,14 @@ +--- +name: Convert a Blob to a DataView +--- + +The [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) class provides a number of methods for consuming its contents in different formats. This snippets reads the contents to an `ArrayBuffer`, then creates a `DataView` from the buffer. + +```ts +const blob = new Blob(["hello world"]); +const arr = new DataView(await blob.arrayBuffer()); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/blob-to-stream.md b/docs/guides/binary/blob-to-stream.md new file mode 100644 index 000000000..37a916ab3 --- /dev/null +++ b/docs/guides/binary/blob-to-stream.md @@ -0,0 +1,14 @@ +--- +name: Convert a Blob to a ReadableStream +--- + +The [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) class provides a number of methods for consuming its contents in different formats, inluding `.stream()`. This returns `Promise<ReadableStream>`. + +```ts +const blob = new Blob(["hello world"]); +const stream = await blob.stream(); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/blob-to-string.md b/docs/guides/binary/blob-to-string.md new file mode 100644 index 000000000..05692c32e --- /dev/null +++ b/docs/guides/binary/blob-to-string.md @@ -0,0 +1,15 @@ +--- +name: Convert a Blob to a string +--- + +The [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) class provides a number of methods for consuming its contents in different formats, inluding `.text()`. + +```ts +const blob = new Blob(["hello world"]); +const str = await blob.text(); +// => "hello world" +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/blob-to-typedarray.md b/docs/guides/binary/blob-to-typedarray.md new file mode 100644 index 000000000..efedad02f --- /dev/null +++ b/docs/guides/binary/blob-to-typedarray.md @@ -0,0 +1,14 @@ +--- +name: Convert a Blob to a Uint8Array +--- + +The [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) class provides a number of methods for consuming its contents in different formats. This snippets reads the contents to an `ArrayBuffer`, then creates a `Uint8Array` from the buffer. + +```ts +const blob = new Blob(["hello world"]); +const arr = new Uint8Array(await blob.arrayBuffer()); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/buffer-to-arraybuffer.md b/docs/guides/binary/buffer-to-arraybuffer.md new file mode 100644 index 000000000..56ba78a00 --- /dev/null +++ b/docs/guides/binary/buffer-to-arraybuffer.md @@ -0,0 +1,14 @@ +--- +name: Convert a Buffer to an ArrayBuffer +--- + +The Node.js [`Buffer`](https://nodejs.org/api/buffer.html) class provides a way to view and manipulate data in an underlying `ArrayBuffer`, which is available via the `buffer` property. + +```ts +const nodeBuf = Buffer.alloc(64); +const arrBuf = nodeBuf.buffer; +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/buffer-to-blob.md b/docs/guides/binary/buffer-to-blob.md new file mode 100644 index 000000000..9f59c9f68 --- /dev/null +++ b/docs/guides/binary/buffer-to-blob.md @@ -0,0 +1,14 @@ +--- +name: Convert a Buffer to a blob +--- + +A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) can be constructed from an array of "chunks", where each chunk is a string, binary data structure (including `Buffer`), or another `Blob`. + +```ts +const buf = Buffer.from("hello"); +const blob = new Blob([buf]); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/buffer-to-readablestream.md b/docs/guides/binary/buffer-to-readablestream.md new file mode 100644 index 000000000..fbb03df50 --- /dev/null +++ b/docs/guides/binary/buffer-to-readablestream.md @@ -0,0 +1,41 @@ +--- +name: Convert a Buffer to a ReadableStream +--- + +The naive approach to creating a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) from a [`Buffer`](https://nodejs.org/api/buffer.html) is to use the `ReadableStream` constructor and enqueue the entire array as a single chunk. For a large buffer, this may be undesirable as this approach does not "streaming" the data in smaller chunks. + +```ts +const buf = Buffer.from("hello world"); +const stream = new ReadableStream({ + start(controller) { + controller.enqueue(buf); + controller.close(); + }, +}); +``` + +--- + +To stream the data in smaller chunks, first create a `Blob` instance from the `Buffer`. Then use the [`Blob.stream()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/stream) method to create a `ReadableStream` that streams the data in chunks of a specified size. + +```ts +const buf = Buffer.from("hello world"); +const blob = new Blob([buf]); +const stream = blob.stream(); +``` + +--- + +The chunk size can be set by passing a number to the `.stream()` method. + +```ts +const buf = Buffer.from("hello world"); +const blob = new Blob([buf]); + +// set chunk size of 1024 bytes +const stream = blob.stream(1024); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/buffer-to-string.md b/docs/guides/binary/buffer-to-string.md new file mode 100644 index 000000000..f900cd6a3 --- /dev/null +++ b/docs/guides/binary/buffer-to-string.md @@ -0,0 +1,25 @@ +--- +name: Convert a Buffer to a string +--- + +The [`Buffer`](https://nodejs.org/api/buffer.html) class provides a built-in `.toString()` method that converts a `Buffer` to a string. + +```ts +const buf = Buffer.from("hello"); +const str = buf.toString(); +// => "hello" +``` + +--- + +You can optionally specify an encoding and byte range. + +```ts +const buf = Buffer.from("hello world!"); +const str = buf.toString("utf8", 0, 5); +// => "hello" +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/buffer-to-typedarray.md b/docs/guides/binary/buffer-to-typedarray.md new file mode 100644 index 000000000..c59d77218 --- /dev/null +++ b/docs/guides/binary/buffer-to-typedarray.md @@ -0,0 +1,14 @@ +--- +name: Convert a Buffer to a Uint8Array +--- + +The Node.js [`Buffer`](https://nodejs.org/api/buffer.html) class extends [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array), so no conversion is needed. All properties and methods on `Uint8Array` are available on `Buffer`. + +```ts +const buf = Buffer.alloc(64); +buf instanceof Uint8Array; // => true +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/dataview-to-string.md b/docs/guides/binary/dataview-to-string.md new file mode 100644 index 000000000..0151eaa58 --- /dev/null +++ b/docs/guides/binary/dataview-to-string.md @@ -0,0 +1,15 @@ +--- +name: Convert a Uint8Array to a string +--- + +If a [`DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) contains ASCII-encoded text, you can convert it to a string using the [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) class. + +```ts +const dv: DataView = ...; +const decoder = new TextDecoder(); +const str = decoder.decode(dv); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/index.json b/docs/guides/binary/index.json new file mode 100644 index 000000000..0ddf3da49 --- /dev/null +++ b/docs/guides/binary/index.json @@ -0,0 +1,4 @@ +{ + "name": "Binary data", + "description": "A collection of guides for converting between binary data formats with Bun" +} diff --git a/docs/guides/binary/typedarray-to-arraybuffer.md b/docs/guides/binary/typedarray-to-arraybuffer.md new file mode 100644 index 000000000..2458b21c0 --- /dev/null +++ b/docs/guides/binary/typedarray-to-arraybuffer.md @@ -0,0 +1,25 @@ +--- +name: Convert a Uint8Array to an ArrayBuffer +--- + +A [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) is a _typed array_ class, meaning it is a mechanism for viewing data in an underlying `ArrayBuffer`. The underlying `ArrayBuffer` is accessible via the `buffer` property. + +```ts +const arr = new Uint8Array(64); +arr.buffer; // => ArrayBuffer(64) +``` + +--- + +The `Uint8Array` may be a view over a _subset_ of the data in the underlying `ArrayBuffer`. In this case, the `buffer` property will return the entire buffer, and the `byteOffset` and `byteLength` properties will indicate the subset. + +```ts +const arr = new Uint8Array(64, 16, 32); +arr.buffer; // => ArrayBuffer(64) +arr.byteOffset; // => 16 +arr.byteLength; // => 32 +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/typedarray-to-blob.md b/docs/guides/binary/typedarray-to-blob.md new file mode 100644 index 000000000..e2ca301b8 --- /dev/null +++ b/docs/guides/binary/typedarray-to-blob.md @@ -0,0 +1,16 @@ +--- +name: Convert a Uint8Array to a Blob +--- + +A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) can be constructed from an array of "chunks", where each chunk is a string, binary data structure (including `Uint8Array`), or another `Blob`. + +```ts +const arr = new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f]); +const blob = new Blob([arr]); +console.log(await blob.text()); +// => "hello" +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/typedarray-to-buffer.md b/docs/guides/binary/typedarray-to-buffer.md new file mode 100644 index 000000000..e4013644a --- /dev/null +++ b/docs/guides/binary/typedarray-to-buffer.md @@ -0,0 +1,14 @@ +--- +name: Convert a Uint8Array to a Buffer +--- + +The [`Buffer`](https://nodejs.org/api/buffer.html) class extends [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) with a number of additional methods. Use `Buffer.from()` to create a `Buffer` instance from a `Uint8Array`. + +```ts +const arr: Uint8Array = ... +const buf = Buffer.from(arr); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/typedarray-to-dataview.md b/docs/guides/binary/typedarray-to-dataview.md new file mode 100644 index 000000000..dfef2166b --- /dev/null +++ b/docs/guides/binary/typedarray-to-dataview.md @@ -0,0 +1,14 @@ +--- +name: Convert a Uint8Array to a DataView +--- + +A [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) is a _typed array_ class, meaning it is a mechanism for viewing data in an underlying `ArrayBuffer`. The following snippet creates a [`DataView`] instance over the same range of data as the `Uint8Array`. + +```ts +const arr: Uint8Array = ... +const dv = new DataView(arr.buffer, arr.byteOffset, arr.byteLength); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/typedarray-to-readablestream.md b/docs/guides/binary/typedarray-to-readablestream.md new file mode 100644 index 000000000..e60b6df2e --- /dev/null +++ b/docs/guides/binary/typedarray-to-readablestream.md @@ -0,0 +1,41 @@ +--- +name: Convert a Uint8Array to a ReadableStream +--- + +The naive approach to creating a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) from a [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) is to use the [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) constructor and enqueue the entire array as a single chunk. For larger chunks, this may be undesirable as it isn't actually "streaming" the data. + +```ts +const arr = new Uint8Array(64); +const stream = new ReadableStream({ + start(controller) { + controller.enqueue(arr); + controller.close(); + }, +}); +``` + +--- + +To stream the data in smaller chunks, first create a `Blob` instance from the `Uint8Array`. Then use the [`Blob.stream()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/stream) method to create a `ReadableStream` that streams the data in chunks of a specified size. + +```ts +const arr = new Uint8Array(64); +const blob = new Blob([arr]); +const stream = blob.stream(); +``` + +--- + +The chunk size can be set by passing a number to the `.stream()` method. + +``` +const arr = new Uint8Array(64); +const blob = new Blob([arr]); + +// set chunk size of 1024 bytes +const stream = blob.stream(1024); +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. diff --git a/docs/guides/binary/typedarray-to-string.md b/docs/guides/binary/typedarray-to-string.md new file mode 100644 index 000000000..9c5703420 --- /dev/null +++ b/docs/guides/binary/typedarray-to-string.md @@ -0,0 +1,16 @@ +--- +name: Convert a Uint8Array to a string +--- + +Bun implements the Web-standard [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) class for converting from binary data types like `Uint8Array` and strings. + +```ts +const arr = new Uint8Array([104, 101, 108, 108, 111]); +const decoder = new TextDecoder(); +const str = decoder.decode(buf); +// => "hello" +``` + +--- + +See [Docs > API > Binary Data](/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun. |