structured-clone-es

structured-clone-es

An env-agnostic serializer and deserializer with recursion ability and types beyond JSON, based on the HTML structured clone algorithm.

Ported from @ungap/structured-clone by Andrea Giammarchi, with TypeScript support and modern ESM packaging.

[!NOTE] If you are targeting modern environments, the native structuredClone() is available in all major browsers and Node.js 17+. Use it directly for better performance.

The main value of this package is the serialize / deserialize and stringify / parse utilities, which allow you to convert complex and recursive objects into JSON-safe representations — useful for sending structured data across processes or over the network (e.g. client-server RPC communication).

Used by Nuxt DevTools, Vite DevTools, Node Modules Inspector, ESLint Config Inspector, and more.

Install

npm i structured-clone-es

Usage

Serialize / Deserialize

The result of serialize can be safely stringified as JSON, even if the original data contains recursive references, BigInt values, typed arrays, and so on.

import { deserialize, serialize } from 'structured-clone-es'

// serialize any value into a JSON-compatible array of records
const serialized = serialize({ any: 'serializable' })

// reconstruct the original object
const deserialized = deserialize(serialized)

Stringify / Parse

A convenience wrapper that combines serialize + JSON.stringify and JSON.parse + deserialize:

import { parse, stringify } from 'structured-clone-es'

const str = stringify({ any: 'serializable' })
const obj = parse(str)

structuredClone

A pure structuredClone implementation is also exported. It always uses the serialize/deserialize path without relying on the runtime's native structuredClone.

import { structuredClone } from 'structured-clone-es'

const cloned = structuredClone({ any: 'serializable' })

If you need polyfill globalThis.structuredClone, you can attach it manually:

import { structuredClone } from 'structured-clone-es'

if (!('structuredClone' in globalThis)) {
  globalThis.structuredClone = structuredClone
}

Supported Types

• Primitives: string, number, boolean, null, undefined, BigInt
• Collections: Array, Object, Map, Set
• Typed Arrays: Uint8Array, Uint16Array, Uint32Array, Int8Array, Int16Array, Int32Array, ArrayBuffer, DataView
• Date, RegExp, Error
• Boxed primitives: Boolean, Number, String
• Circular / recursive references

See the MDN documentation for the full structured clone algorithm spec. Note that browser-specific types (Blob, File, ImageBitmap, etc.) are not supported by this library.

Lossy Mode

By default, serialize throws on incompatible types like function or symbol. Use the lossy option to silently replace them with null instead:

import { structuredClone } from 'structured-clone-es'

const cloned = structuredClone(
  {
    method() { /* ignored */ },
    special: Symbol('also ignored'),
  },
  { lossy: true },
)

JSON Mode

The json option implies lossy and additionally checks for toJSON() methods on objects:

import { structuredClone } from 'structured-clone-es'

const cloned = structuredClone(
  {
    date: {
      toJSON() {
        return '2024-01-01'
      },
    },
  },
  { json: true },
)

The stringify / parse exports use both json and lossy by default.

Credits

This project is a TypeScript port of @ungap/structured-clone, originally created by Andrea Giammarchi under the ISC license.

License

ISC