docs: Add new methods to binary-data.md (#14044)

oven-sh · Sep 19, 2024 · 260a0d1 · 260a0d1
1 parent 47e4b82
commit 260a0d1
Showing 1 changed file with 31 additions and 5 deletions.
diff --git 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(); // => <html><body>hello</body></html>
+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,14 +875,15 @@ Buffer.from(await blob.arrayBuffer());
 
 #### To `string`
 
+As UTF-8:
 ```ts
 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)));