Skip to content
Merged
Changes from all commits
Commits
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
109 changes: 44 additions & 65 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,20 @@
</a>
</p>

> [!IMPORTANT]
> **This is a fork of [superjson](https://github.com/blitz-js/superjson).** It is maintained in
> [eridu-tech/superjson](https://github.com/eridu-tech/superjson) and published to npm as
> `@eridu-tech/superjson`.
>
> **In this fork the API is asynchronous:** `stringify`, `parse`, `serialize` and `deserialize` return
> Promises and must be `await`ed. See [Async API](#async-api).

## Key features

- 🍱 Reliable serialization and deserialization
- 🔐 Type safety with autocompletion
- 🐾 Negligible runtime footprint
- 💫 Framework agnostic
- 🛠 Perfect fix for Next.js's serialisation limitations in `getServerSideProps` and `getInitialProps`

## Backstory

Expand All @@ -55,27 +62,50 @@ Superjson logo by [NUMI](https://github.com/numi-hq/open-design):
Install the library with your package manager of choice, e.g.:

```
yarn add superjson
yarn add @eridu-tech/superjson
```

## Async API

Unlike upstream [superjson](https://github.com/blitz-js/superjson), the public API in this fork is
**asynchronous**. `stringify`, `parse`, `serialize` and `deserialize` all return Promises:

| Method | Returns |
| -------------------------------- | -------------------------- |
| `serialize(value)` | `Promise<SuperJSONResult>` |
| `deserialize(payload, options?)` | `Promise<T>` |
| `stringify(value)` | `Promise<string>` |
| `parse(string)` | `Promise<T>` |

```ts
import superjson from '@eridu-tech/superjson';

const json = await superjson.stringify({ date: new Date(0) });
const value = await superjson.parse<{ date: Date }>(json);
```

The registration methods (`registerClass`, `registerSymbol`, `registerCustom`, `allowErrorProps`) remain
synchronous. Custom transformers may be asynchronous too: `isApplicable`, `serialize` and `deserialize`
can return either a value or a Promise.

## Basic Usage

The easiest way to use Superjson is with its `stringify` and `parse` functions. If you know how to use `JSON.stringify`, you already know Superjson!

Easily stringify any expression you’d like:

```js
import superjson from 'superjson';
import superjson from '@eridu-tech/superjson';

const jsonString = superjson.stringify({ date: new Date(0) });
const jsonString = await superjson.stringify({ date: new Date(0) });

// jsonString === '{"json":{"date":"1970-01-01T00:00:00.000Z"},"meta":{"values":{date:"Date"}}}'
```

And parse your JSON like so:

```js
const object = superjson.parse<
const object = await superjson.parse<
{ date: Date }
>(jsonString);

Expand All @@ -97,7 +127,7 @@ const object = {
test: /superjson/,
};

const { json, meta } = superjson.serialize(object);
const { json, meta } = await superjson.serialize(object);

/*
json = {
Expand All @@ -116,61 +146,10 @@ meta = {
*/
```

## Using with Next.js

The `getServerSideProps`, `getInitialProps`, and `getStaticProps` data hooks provided by Next.js do not allow you to transmit Javascript objects like Dates. It will error unless you convert Dates to strings, etc.

Thankfully, Superjson is a perfect tool to bypass that limitation!

### Next.js SWC Plugin (experimental, v13 or above)

Next.js SWC plugins are [experimental](https://nextjs.org/docs/advanced-features/compiler#swc-plugins-experimental), but promise a significant speedup.
To use the [SuperJSON SWC plugin](https://github.com/blitz-js/next-superjson-plugin), install it and add it to your `next.config.js`:

```sh
yarn add next-superjson-plugin
```

```js
// next.config.js
module.exports = {
experimental: {
swcPlugins: [
[
'next-superjson-plugin',
{
excluded: [],
},
],
],
},
};
```

### Next.js (stable Babel transform)

Install the library with your package manager of choice, e.g.:

```sh
yarn add babel-plugin-superjson-next
```

Add the plugin to your .babelrc. If you don't have one, create it.

```js
{
"presets": ["next/babel"],
"plugins": [
...
"superjson-next" // 👈
]
}
```

Done! Now you can safely use all JS datatypes in your `getServerSideProps` / etc. .

## API

> All of the methods below are **asynchronous** and return Promises. See [Async API](#async-api).

### serialize

Serializes any JavaScript value into a JSON-compatible object.
Expand All @@ -184,7 +163,7 @@ const object = {
test: /superjson/,
};

const { json, meta } = serialize(object);
const { json, meta } = await serialize(object);
```

Returns **`json` and `meta`, both JSON-compatible values.**
Expand All @@ -196,9 +175,9 @@ Deserializes the output of Superjson back into your original value.
#### Examples

```js
const { json, meta } = serialize(object);
const { json, meta } = await serialize(object);

deserialize({ json, meta }, { inPlace: true });
await deserialize({ json, meta }, { inPlace: true });
```

Options
Expand All @@ -223,7 +202,7 @@ const object = {
test: /superjson/,
};

const jsonString = stringify(object);
const jsonString = await stringify(object);
```

Returns **`string`**.
Expand All @@ -235,9 +214,9 @@ Parses and then deserializes the JSON string returned by `stringify`.
#### Examples

```js
const jsonString = stringify(object);
const jsonString = await stringify(object);

parse(jsonString);
await parse(jsonString);
```

Returns **`your original value`**.
Expand Down
Loading