Extended Serializer

Install

npm install extended-serializer

About

• link to documentation
• Extends JSON serialization to support almost all data types.
• Validates all input data to ensure that it is serializable.
• Doesn't rely on a nonce like other solutions, so no chance of collisions.
• Never calls toJSON methods.
• Well tested with 100% coverage.

Transforms

This is an exhastive list of all possible values in JavaScript, and the applicable transforms to make them serializable.

| Type | Values | Applicable transform | Notes | | --------------------------------------- | --------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------- | | null value | null | none needed | | | boolean primitive type | true or false | none needed | | | string primitive type | e.g. "hello" | none needed | | | number primitive type | e.g. 5 | none needed | except NaN, Infinity, -0 | | Object instance | e.g. {a: 1, b: 2, c: 3} | none needed | except complex Object instances or repeated references | | Array instance | e.g. [1, 2, 3] | none needed | except complex Array instances or repeated references | | -0 value | -0 | negativeZeroTransform | | | NaN value | NaN | nanTransform | | | Infinity value | Infinity or -Infinity | infinityTransform | | | undefined primitive type | undefined | undefinedTransform | | | bigint primitive type | e.g. 5n | bigIntTransform | | | complex Object instance | e.g. {[Symbol.toStringTag]: "something"} | complexObjectTransform | an object with symbol keys, or non standard property descriptors | | complex Array instance | e.g. Object.assign([1, 2, 3], {a: 1, b: 2, c: 3}) | complexArrayTransform | an array with extra or missing properties | | ~~repeated and circular references~~ | ~~e.g. [value, value]~~ | ~~repeatedReferencesTransform~~ | NOT FINISHED ~~should be first transform included~~ | | global registry symbol primitive type | e.g. Symbol.for("something") | registrySymbolTransform | you may want to omit this transform if encoding and decoding in different environments | | well known symbol primitive type | e.g. Symbol.iterator | wellKnownSymbolTransform | | | local symbol primitive type | e.g. Symbol("something") | requires custom transform | | | function primitive type | e.g. () => true | requires custom transform | | | class instance | e.g. new CustomClass() | requires custom transform | |

JS built-in class instances

| Class | Transform | Notes | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------ | | Set | setTransform | | | Map | mapTransform | | | Date | dateTransform | | | RegExp | regExpTransform | | | ArrayBuffer | arrayBufferTransform | | | DataView | dataViewTransform | | | Boolean, Number, String | primitiveClassTransform | | | Error, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError, AggregateError | errorClassTransform | won't encode not standard properties | | Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array, BigInt64Array, BigUint64Array | typedArrayTransform | will need arrayBufferTransform |

Notes

• Proxies will be flattened, without being flagged by the validator as these can only be detected in node, see example for custom validator to reject proxies in node.
• When writing custom transforms, to test for custom class instances, use isInstanceOf instead of instanceof to prevent capturing instances of subclasses.

Example

import util from "node:util";
import {
	type Serializable,
	transforms,
	transform,
	classTransform,
	classGroupTransform,
	stringify,
	parse
} from "extended-serializer";

const options = {
	validate: value => !util.types.isProxy(value),
	transforms: [
		...transforms,
		customSymbol: makeTransform({
			test: (value) => value === customSymbol,
			decode: () => customSymbol,
		}),
		customFunction: makeTransform({
			test: (value) => value === customFunction,
			decode: () => customFunction,
		}),
		customClass: makeClassTransform({
			constructor: CustomClass,
			encode: ({ a, b }) => [a, b],
		}),
		customClassGroup: makeClassGroupTransform({
			key: "customClassGroup",
			classes: [IntVector, FloatVector, BooleanVector],
			encode: ({ x, y, z }) => [x, y, z],
		}),
	],
} satisfies SerializeOptions;

type Primitive = Serializable<typeof options>;

const value = {
  a: NaN,
  b: Infinity,
  c: new Set([1, 2, 3]),
  d: customSymbol,
  e: customFunction,
  f: new CustomClass(1, 2),
} satisfies Primitive;

const str = stringify(value, options);
const clone = parse(encoded, options);

//clone is now a deep clone of value

//or can use clone
const clone = clone(value, options);

Alternative Work

devalue

https://github.com/Rich-Harris/devalue

• Can't pick and choose transforms
• Doesn't fully validate serializable values
• Unflexible custom transforms

oson

https://github.com/KnorpelSenf/oson?tab=readme-ov-file

• Only supports class instances custom transforms
• Doesn't support NaN, Infinity, -0
• Doesn't support well known symbols or symbols in global registry
• Doesn't fully validate serializable values

superjson

https://github.com/flightcontrolhq/superjson

• Globally defined transforms
• Doesn't fully validate serializable values

next-json

https://github.com/iccicci/next-json?tab=readme-ov-file

• Non JSON output
• Doesn't support ArrayBuffer or TypedArrays
• Doesn't support well known symbols or symbols in global registry
• Doesn't support Error instances
• Doesn't support complex objects

arson

https://github.com/benjamn/arson

• Doesn't fully validate serializable values
• Doesn't fully restore serialized values (e.g RegExp missing lastIndex)

tRPC/tupleSON

https://github.com/trpc/tupleson

• Relies on a nonce to prevent collisions
• Doesn't support NaN or Infinity
• Archived

ScaleForge/joser

https://github.com/ScaleForge/joser

• Relies on a nonce to prevent collisions
• Only supports class types, that must be in global scope
• Doesn't fully validate serializable values

tosource

https://github.com/marcello3d/node-tosource

• Non JSON output
• Not extendable
• Doesn't fully validate serializable values (by design, e.g. attempts to serialize functions with toString)

serialize-javascript

https://github.com/yahoo/serialize-javascript

• Creates a JS script requiring dangerous eval

Lave

https://github.com/jed/lave

• Creates a JS script requiring dangerous eval
• Archived