diff --git a/README.md b/README.md index 9ff5d32..47d15d5 100644 --- a/README.md +++ b/README.md @@ -28,13 +28,20 @@

+> [!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 @@ -55,9 +62,32 @@ 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` | +| `deserialize(payload, options?)` | `Promise` | +| `stringify(value)` | `Promise` | +| `parse(string)` | `Promise` | + +```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! @@ -65,9 +95,9 @@ The easiest way to use Superjson is with its `stringify` and `parse` functions. 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"}}}' ``` @@ -75,7 +105,7 @@ const jsonString = superjson.stringify({ date: new Date(0) }); And parse your JSON like so: ```js -const object = superjson.parse< +const object = await superjson.parse< { date: Date } >(jsonString); @@ -97,7 +127,7 @@ const object = { test: /superjson/, }; -const { json, meta } = superjson.serialize(object); +const { json, meta } = await superjson.serialize(object); /* json = { @@ -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. @@ -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.** @@ -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 @@ -223,7 +202,7 @@ const object = { test: /superjson/, }; -const jsonString = stringify(object); +const jsonString = await stringify(object); ``` Returns **`string`**. @@ -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`**.