Merge pull request lxsmnsyc#11 from lxsmnsyc/next

0.6.0

Author: lxsmnsyc

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`:
@@ -232,7 +263,10 @@ The following values are the only values accepted by `seroval`:
 - `Promise` (with `serializeAsync`)
 - [`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)
+- [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
+- [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
 - Cyclic references (both self and mutual)
+- Isomorphic references (a reference that exist on both the serializer and deserializer side)
 
 ## Compat
 
@@ -318,6 +352,10 @@ 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)
 
 ## Sponsors
 

packages/seroval/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`:
@@ -232,7 +263,10 @@ The following values are the only values accepted by `seroval`:
 - `Promise` (with `serializeAsync`)
 - [`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)
+- [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
+- [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
 - Cyclic references (both self and mutual)
+- Isomorphic references (a reference that exist on both the serializer and deserializer side)
 
 ## Compat
 
@@ -318,6 +352,10 @@ 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)
 
 ## Sponsors
 

packages/seroval/src/compat.ts

@@ -19,6 +19,7 @@ export const enum Feature {
   Symbol = 0x400,
   TypedArray = 0x800,
   BigIntTypedArray = 0x1000,
+  WebAPI = 0x2000,
 }
 
-export const ALL_ENABLED = 0x1FFF;
+export const ALL_ENABLED = 0x2FFF;

packages/seroval/src/context.ts

@@ -1,6 +1,5 @@
 import { ALL_ENABLED } from './compat';
 import getIdentifier from './get-identifier';
-import { AsyncServerValue } from './types';
 
 interface IndexAssignment {
   t: 'index';
@@ -49,7 +48,7 @@ export interface SerializationContext {
   // Supported features
   features: number;
 
-  valueMap: Map<number, AsyncServerValue>;
+  valueMap: Map<number, unknown>;
 }
 
 export interface Options {
@@ -118,9 +117,9 @@ export function getRefParam(ctx: SerializationContext, index: number) {
   return identifier;
 }
 
-export function getRootID(
+export function getRootID<T>(
   ctx: ParserContext,
-  current: AsyncServerValue,
+  current: T,
 ) {
   const ref = ctx.refs.get(current);
   if (ref == null) {
@@ -129,9 +128,9 @@ export function getRootID(
   return ref;
 }
 
-export function createRef(
+export function createIndexedValue<T>(
   ctx: ParserContext,
-  current: AsyncServerValue,
+  current: T,
 ) {
   const ref = ctx.refs.get(current);
   if (ref == null) {

packages/seroval/src/index.ts

@@ -12,14 +12,6 @@ import deserializeTree from './tree/deserialize';
 import serializeTree, { resolvePatches } from './tree/serialize';
 import parseSync from './tree/sync';
 import { SerovalNode } from './tree/types';
-import {
-  AsyncServerValue,
-  PrimitiveValue,
-  ServerValue,
-  CommonServerValue,
-  SemiPrimitiveValue,
-  ErrorValue,
-} from './types';
 
 export {
   AsyncServerValue,
@@ -28,8 +20,8 @@ export {
   CommonServerValue,
   SemiPrimitiveValue,
   ErrorValue,
-  Feature,
-};
+} from './types';
+export { Feature } from './compat';
 
 function finalize(
   ctx: SerializationContext,
@@ -67,7 +59,7 @@ function finalize(
   return result;
 }
 
-export function serialize<T extends ServerValue>(
+export function serialize<T>(
   source: T,
   options?: Partial<Options>,
 ) {
@@ -78,7 +70,7 @@ export function serialize<T extends ServerValue>(
   return finalize(serial, rootID, isObject, result);
 }
 
-export async function serializeAsync<T extends AsyncServerValue>(
+export async function serializeAsync<T>(
   source: T,
   options?: Partial<Options>,
 ) {
@@ -89,7 +81,7 @@ export async function serializeAsync<T extends AsyncServerValue>(
   return finalize(serial, rootID, isObject, result);
 }
 
-export function deserialize<T extends AsyncServerValue>(source: string): T {
+export function deserialize<T>(source: string): T {
   // eslint-disable-next-line no-eval
   return (0, eval)(source) as T;
 }
@@ -102,7 +94,7 @@ export interface SerovalJSON {
   m: number[],
 }
 
-export function toJSON<T extends ServerValue>(
+export function toJSON<T>(
   source: T,
   options?: Partial<Options>,
 ): SerovalJSON {
@@ -117,7 +109,7 @@ export function toJSON<T extends ServerValue>(
   };
 }
 
-export async function toJSONAsync<T extends AsyncServerValue>(
+export async function toJSONAsync<T>(
   source: T,
   options?: Partial<Options>,
 ): Promise<SerovalJSON> {
@@ -141,7 +133,7 @@ export function compileJSON(source: SerovalJSON): string {
   return finalize(serial, source.r, source.i, result);
 }
 
-export function fromJSON<T extends AsyncServerValue>(source: SerovalJSON): T {
+export function fromJSON<T>(source: SerovalJSON): T {
   const serial = createSerializationContext({
     features: source.f,
     markedRefs: source.m,
@@ -150,3 +142,5 @@ export function fromJSON<T extends AsyncServerValue>(source: SerovalJSON): T {
 }
 
 export default serialize;
+
+export { createReference } from './tree/reference';