seroval

Seroval automatically handles object references. If the same object instance is encountered multiple times, it is deduped in the output. It also natively supports cyclic references (objects referencing themselves) and mutual cycles (objects referencing each other), as well as detecting potential temporal dead zones during serialization.

import { serialize } from 'seroval';

// Deduping
const parent = {};
const a = { parent };
const b = { parent };
console.log(serialize([a, b])); // (h=>([{parent:h={}},{parent:h}]) )()

// Cyclic
const cyclic = {};
cyclic.self = cyclic;
console.log(serialize(cyclic)); // (h=>(h={},h.self=h,h))()

The seroval-plugins/web module provides support or polyfills for standard Web APIs. This is useful when running seroval in environments where these APIs might be missing or need specific handling. Supported APIs include:

• AbortSignal
• Blob
• CustomEvent
• DOMException
• Event
• File
• FormData
• ImageData
• Headers
• ReadableStream
• Request
• Response
• URLSearchParams
• URL

You can install seroval using npm, yarn, or pnpm to add stringification capabilities for complex JavaScript values to your project.

npm install --save seroval

yarn add seroval

pnpm add seroval

Install the seroval-plugins package using your preferred package manager to access additional plugin capabilities for seroval.

npm install --save seroval-plugins

yarn add seroval-plugins

pnpm add seroval-plugins

You can control how seroval processes and emits values by passing a disabledFeatures option to the serialize function. This option uses bit flags to disable specific JavaScript features or behaviors during the serialization process.

To disable multiple features simultaneously, use the bitwise OR operator (|). By default, all feature flags are enabled.

import { serialize, Feature } from 'seroval';

// Disabling multiple features using bitwise OR
const DISABLED_FEATURES = Feature.AggregateError | Feature.BigIntTypedArray;

const result = serialize(myValue, {
  disabledFeatures: DISABLED_FEATURES,
});

SerovalAsyncNode represents nodes involved in asynchronous operations. These are distinct from synchronous nodes and include:

• SerovalPromiseNode: Represents a Promise, including its state (s: 0 or 1) and its fulfilled value (f).
• SerovalPromiseConstructorNode: Represents the Promise constructor.
• SerovalPromiseResolveNode / SerovalPromiseRejectNode: Represent the resolution or rejection of a promise, containing the resolver/rejecter and the resolved/rejected value.
• SerovalStreamConstructorNode: Represents a Stream constructor.
• SerovalStreamNextNode / SerovalStreamThrowNode / SerovalStreamReturnNode: Represent the lifecycle steps of a stream (next value, error thrown, or return value).

createStream is a specialized primitive for handling data that resolves to multiple values over time (unlike a standard Promise). It supports buffering and provides an event-based listener for next, throw, and return events. createStream instances are themselves serializable and compatible with crossSerializeStream.

import { createStream, crossSerializeStream } from 'seroval';

const stream = createStream();

stream.on({
  next(data) { console.log('NEXT', data); },
  throw(data) { console.log('THROW', data); },
  return(data) { console.log('RETURN', data); },
});

stream.next('foo');
stream.next('bar');
stream.return('baz');

// Also works with streaming serialization
crossSerializeStream(stream, {
  onSerialize(data) { console.log(data); }
});

Use serialize for synchronous data and serializeAsync when your data contains asynchronous values like Promise instances. Both methods return a serialized string representation of the input object.

import { serialize, serializeAsync } from 'seroval';

// Synchronous
console.log(serialize({ foo: 'bar' })); // {foo:"bar"}

// Asynchronous
console.log(await serializeAsync(Promise.resolve({ foo: 'bar'}))); // Promise.resolve({foo:"bar"})

Import serialize from seroval to convert JavaScript values into a string representation. Unlike standard JSON, seroval supports complex types including Map, Set, RegExp, Date, BigInt, and values with circular or mutual references.

import { serialize } from 'seroval';

const object = {
  number: [Math.random(), -0, NaN, Infinity, -Infinity],
  string: ['hello world', '<script>Hello World</script>'],
  boolean: [true, false],
  null: null,
  undefined: undefined,
  bigint: 9007199254740991n,
  array: [,,,], // holes
  regexp: /[a-z0-9]+/i,
  date: new Date(),
  map: new Map([['hello', 'world']]),
  set: new Set(['hello', 'world']),
};

// Handle circular/recursive references
object.self = object;
object.array.push(object.array);

const result = serialize(object);
console.log(result);

When using crossSerialize or crossSerializeAsync, you can provide a scopeId string. This allows the $R global variable to be scoped (e.g., $R['A']), preventing different serialization contexts from colliding. You can initialize specific scopes using getCrossReferenceHeader(scopeId).

import { crossSerialize, getCrossReferenceHeader } from 'seroval';

const refsA = new Map();
const refsB = new Map();

// Scoped to 'A'
console.log(crossSerialize(nodeA, { refs: refsA, scopeId: 'A' }));

// Scoped to 'B'
console.log(crossSerialize(nodeA, { refs: refsB, scopeId: 'B' }));

// Initialize a specific scope
console.log(getCrossReferenceHeader('A')); // (self.$R=self.$R||{})["A"]=[]