seroval 0.5.1 → 0.7.0

package/README.md

@@ -186,6 +186,37 @@ console.log(await deserialize(result)); // 100
 > **Note**
 > `seroval` can only serialize the resolved value and so the output will always be using `Promise.resolve`. If the Promise fulfills with rejection, the rejected value is thrown before serialization happens.
 
+## Serializable references
+
+There are values that has no way to be serializable at all, i.e. functions, but usually in an isomorphic code, functions can exist on both client and server-side. What if we can serialize these functions in such a way we can refer to their counterparts?
+
+`seroval` has `createReference` that you can use to map user-defined strings to their references.
+
+```js
+import { createReference } from 'seroval';
+
+const thisIsAnIsomorphicFunction = createReference(
+  // This is (ideally) a unique identifier
+  // that is used to map the serialized value
+  // to its actual reference (and vice versa)
+  'my-function',
+  () => {
+    // Ideally this function should exist on both
+    // server and client, but we want to add the ability
+    // to serialize and deserialize this reference on
+    // both sides
+  }
+);
+
+// we can now serialize this
+const serialized = toJSON(thisIsAnIsomorphicFunction); // or any of the serializer
+thisIsAnIsomorphicFunction === fromJSON(serialized); // true
+```
+
+> **Note**
+> It can only accept objects, functions and symbols and it doesn't actually
+> serialize their values but only the string you used to identify the reference
+
 ## Supports
 
 The following values are the only values accepted by `seroval`:
@@ -209,6 +240,8 @@ The following values are the only values accepted by `seroval`:
   - `Map`
   - `Set`
   - `Object.create(null)`
+- `ArrayBuffer`
+- `DataView`
 - `TypedArray`
   - `Int8Array`
   - `Int16Array`
@@ -229,10 +262,19 @@ The following values are the only values accepted by `seroval`:
   - `SyntaxError`
   - `TypeError`
   - `URIError`
-- `Promise` (with `serializeAsync`)
+- `Promise` (with `serializeAsync` and `toJSONAsync`)
 - [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol)
 - [Well-known symbols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#static_properties)
+- Web API
+  - [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
+  - [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+  - [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) (with `serializeAsync` and `toJSONAsync`)
+  - [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) (with `serializeAsync` and `toJSONAsync`)
+  - [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+  - [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
+    - If `FormData` has a `Blob`/`File` entry, it can only be serialized with `serializeAsync` and `toJSONAsync`
 - Cyclic references (both self and mutual)
+- Isomorphic references (a reference that exist on both the serializer and deserializer side)
 
 ## Compat
 
@@ -318,6 +360,14 @@ By default, all feature flags are enabled. The following are the feature flags a
   - Throws when attempted to use
   - Also throws if `BigInt` is disabled.
   - Disables serialization of `BigInt64Array` and `BigUint64Array`
+- `WebAPI`
+  - Throws and disables the following usage:
+    - [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
+    - [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+    - [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
+    - [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File)
+    - [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+    - [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
 
 ## Sponsors