From 260a0d16eb769d5442bb55c15f42ce2934140a60 Mon Sep 17 00:00:00 2001 From: Kevin Gibbons Date: Thu, 19 Sep 2024 13:36:08 -0700 Subject: [PATCH] docs: Add new methods to binary-data.md (#14044) --- docs/api/binary-data.md | 36 +++++++++++++++++++++++++++++++----- 1 file changed, 31 insertions(+), 5 deletions(-) diff --git a/docs/api/binary-data.md b/docs/api/binary-data.md index 46bd6be3bd3ad..e0820d44f38a3 100644 --- a/docs/api/binary-data.md +++ b/docs/api/binary-data.md @@ -382,6 +382,16 @@ Refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/Ja It's worth specifically highlighting `Uint8Array`, as it represents a classic "byte array"—a sequence of 8-bit unsigned integers between 0 and 255. This is the most common typed array you'll encounter in JavaScript. +In Bun, and someday in other JavaScript engines, it has methods available for converting between byte arrays and serialized representations of those arrays as base64 or hex strings. + +```ts +new Uint8Array([1, 2, 3, 4, 5]).toBase64(); // "AQIDBA==" +Uint8Array.fromBase64("AQIDBA=="); // Uint8Array(4) [1, 2, 3, 4, 5] + +new Uint8Array([255, 254, 253, 252, 251]).toHex(); // "fffefdfcfb==" +Uint8Array.fromHex("fffefdfcfb"); // Uint8Array(5) [255, 254, 253, 252, 251] +``` + It is the return value of [`TextEncoder#encode`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder), and the input type of [`TextDecoder#decode`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder), two utility classes designed to translate strings and various binary encodings, most notably `"utf-8"`. ```ts @@ -442,6 +452,7 @@ The contents of a `Blob` can be asynchronously read in various formats. ```ts await blob.text(); // => hello +await blob.bytes(); // => Uint8Array (copies contents) await blob.arrayBuffer(); // => ArrayBuffer (copies contents) await blob.stream(); // => ReadableStream ``` @@ -545,6 +556,7 @@ Buffer.from(buf, 0, 10); #### To `string` +As UTF-8: ```ts new TextDecoder().decode(buf); ``` @@ -625,6 +637,7 @@ Buffer.from(arr); #### To `string` +As UTF-8: ```ts new TextDecoder().decode(arr); ``` @@ -638,6 +651,7 @@ Array.from(arr); #### To `Blob` ```ts +// only if arr is a view of its entire backing TypedArray new Blob([arr.buffer], { type: "text/plain" }); ``` @@ -701,6 +715,7 @@ Buffer.from(view.buffer, view.byteOffset, view.byteLength); #### To `string` +As UTF-8: ```ts new TextDecoder().decode(view); ``` @@ -772,9 +787,18 @@ new DataView(buf.buffer, buf.byteOffset, buf.byteLength); #### To `string` +As UTF-8: ```ts buf.toString(); ``` +As base64: +```ts +buf.toString('base64'); +``` +As hex: +```ts +buf.toString('hex'); +``` #### To `number[]` @@ -834,7 +858,7 @@ await blob.arrayBuffer(); #### To `TypedArray` ```ts -new Uint8Array(await blob.arrayBuffer()); +await blob.bytes(); ``` #### To `DataView` @@ -851,6 +875,7 @@ Buffer.from(await blob.arrayBuffer()); #### To `string` +As UTF-8: ```ts await blob.text(); ``` @@ -858,7 +883,7 @@ await blob.text(); #### To `number[]` ```ts -Array.from(new Uint8Array(await blob.arrayBuffer())); +Array.from(await blob.bytes()); ``` #### To `ReadableStream` @@ -936,9 +961,10 @@ Buffer.from(Bun.readableStreamToArrayBuffer(stream)); #### To `string` +As UTF-8: ```ts // with Response -new Response(stream).text(); +await new Response(stream).text(); // with Bun function await Bun.readableStreamToText(stream); @@ -948,8 +974,8 @@ await Bun.readableStreamToText(stream); ```ts // with Response -const buf = await new Response(stream).arrayBuffer(); -Array.from(new Uint8Array(buf)); +const arr = await new Response(stream).bytes(); +Array.from(arr); // with Bun function Array.from(new Uint8Array(Bun.readableStreamToArrayBuffer(stream)));