From afc1e3f618f0d66c7ecb8eea198c255533221eae Mon Sep 17 00:00:00 2001
From: MarkXian <mark-xian@foxmail.com>
Date: Sat, 1 Aug 2026 17:03:23 +0800
Subject: [PATCH] docs: document binary data support

---
 README.md | 56 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 40 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 9ff5d329..bff09296 100644
--- a/README.md
+++ b/README.md
@@ -246,22 +246,46 @@ Returns **`your original value`**.
 
 Superjson supports many extra types which JSON does not. You can serialize all these:
 
-| type        | supported by standard JSON? | supported by Superjson? |
-| ----------- | --------------------------- | ----------------------- |
-| `string`    | ✅                          | ✅                      |
-| `number`    | ✅                          | ✅                      |
-| `boolean`   | ✅                          | ✅                      |
-| `null`      | ✅                          | ✅                      |
-| `Array`     | ✅                          | ✅                      |
-| `Object`    | ✅                          | ✅                      |
-| `undefined` | ❌                          | ✅                      |
-| `bigint`    | ❌                          | ✅                      |
-| `Date`      | ❌                          | ✅                      |
-| `RegExp`    | ❌                          | ✅                      |
-| `Set`       | ❌                          | ✅                      |
-| `Map`       | ❌                          | ✅                      |
-| `Error`     | ❌                          | ✅                      |
-| `URL`       | ❌                          | ✅                      |
+| type           | supported by standard JSON? | supported by Superjson? |
+| -------------- | --------------------------- | ----------------------- |
+| `string`       | ✅                          | ✅                      |
+| `number`       | ✅                          | ✅                      |
+| `boolean`      | ✅                          | ✅                      |
+| `null`         | ✅                          | ✅                      |
+| `Array`        | ✅                          | ✅                      |
+| `Object`       | ✅                          | ✅                      |
+| `undefined`    | ❌                          | ✅                      |
+| `bigint`       | ❌                          | ✅                      |
+| `Date`         | ❌                          | ✅                      |
+| `RegExp`       | ❌                          | ✅                      |
+| `Set`          | ❌                          | ✅                      |
+| `Map`          | ❌                          | ✅                      |
+| `Error`        | ❌                          | ✅                      |
+| `URL`          | ❌                          | ✅                      |
+| `typed arrays` | ❌                          | ✅                      |
+
+### Binary data
+
+Superjson supports binary data when it is represented as a typed array, such as
+`Uint8Array`, `Int16Array`, `Float32Array`, `BigInt64Array`, or
+`BigUint64Array`.
+
+Typed arrays are serialized to JSON-compatible arrays and annotated with their
+constructor name in `meta`, so deserialization restores the original typed array
+type:
+
+```js
+const bytes = new Uint8Array([1, 2, 3]);
+
+const { json, meta } = superjson.serialize({ bytes });
+
+// json === { bytes: [1, 2, 3] }
+// meta === { values: { bytes: [['typed-array', 'Uint8Array']] } }
+
+const restored = superjson.deserialize({ json, meta });
+
+// restored.bytes instanceof Uint8Array
+```
 
 ## Recipes