Skip to content

docs: document binary data support #359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
xianjianlf2 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document binary data support #359

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 40 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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']] } }

@greptile-apps greptile-apps Bot Aug 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Include the metadata version field

The equality example presents the complete meta result, but serialize always adds v: 1 when metadata exists. Exact comparisons based on this documented shape therefore fail.

Suggested change
// meta === { values: { bytes: [['typed-array', 'Uint8Array']] } }
// meta === { values: { bytes: [['typed-array', 'Uint8Array']] }, v: 1 }
Prompt To Fix With AI 
This is a comment left during a code review.
Path: README.md
Line: 283

Comment:
**Include the metadata version field**

The equality example presents the complete `meta` result, but `serialize` always adds `v: 1` when metadata exists. Exact comparisons based on this documented shape therefore fail.

```suggestion
// meta === { values: { bytes: [['typed-array', 'Uint8Array']] }, v: 1 }
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.


const restored = superjson.deserialize({ json, meta });

// restored.bytes instanceof Uint8Array
```

## Recipes

Expand Down