bare-structured-clone

stable

bare-structured-clone — Structured cloning algorithm for JavaScript. It is a native addon and requires Bare >=1.2.0.

Implements the HTML spec's structured clone serialization, deserialization, and transfer steps, and exposes a compact-encoding codec for encoding serialized values to a buffer.

npm i bare-structured-clone

Usage

const structuredClone = require('bare-structured-clone')

const copy = structuredClone({ hello: 'world' })

const buffer = new ArrayBuffer(4)
const transferred = structuredClone(buffer, { transfer: [buffer] })

To install structuredClone as a global, require the global submodule:

require('bare-structured-clone/global')

const copy = structuredClone({ hello: 'world' })

API

DataCloneError

`DataCloneError.ALREADY_TRANSFERRED(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code ALREADY_TRANSFERRED.

`DataCloneError.INVALID_ARRAY_LAYOUT(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_ARRAY_LAYOUT.

`DataCloneError.INVALID_INTERFACE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_INTERFACE.

`DataCloneError.INVALID_PROPERTY_KEY(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_PROPERTY_KEY.

`DataCloneError.INVALID_REFERENCE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_REFERENCE.

`DataCloneError.INVALID_TYPE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	—

`DataCloneError.INVALID_VERSION(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_VERSION.

`DataCloneError.INVALID_VIEW(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	—

`DataCloneError.UNSERIALIZABLE_TYPE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code UNSERIALIZABLE_TYPE.

`DataCloneError.UNTRANSFERABLE_TYPE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code UNTRANSFERABLE_TYPE.

Functions

`structuredClone`

structuredClone<T extends SerializableValue | TransferableValue>(value: T, opts?: StructuredCloneOptions): T

Clone value by serializing and then deserializing it. opts may include a transfer list and an interfaces list.

Parameters

Parameter	Type	Default	Description
`value`	`T`	—	The value to clone.
`opts?`	`StructuredCloneOptions`	—	Options carrying the optional `transfer` and `interfaces` lists.

Returns T — A deep copy of value, with any transferred objects detached from the original.

Throws

UNSERIALIZABLE_TYPE — value, or a value it references, is of a type that cannot be serialized (for example a function, a symbol, or a detached ArrayBuffer).
UNTRANSFERABLE_TYPE — a value in the transfer list cannot be transferred.
ALREADY_TRANSFERRED — a value in the transfer list has already been transferred.
INVALID_INTERFACE — a serializable or transferable value has an interface that is not present in the interfaces list.

`structuredClone.deserialize`

structuredClone.deserialize<T extends SerializableValue>(serialized: SerializedValue, interfaces?: (SerializableConstructor | TransferableConstructor)[]): T

Parameters

Parameter	Type	Default	Description
`serialized`	`SerializedValue`	—	A value previously produced by `serialize`.
`interfaces?`	`(SerializableConstructor \| TransferableConstructor)[]`	—	Serializable and transferable constructors to recognize when deserializing custom platform objects.

Returns T — The value reconstructed from serialized.

`structuredClone.deserializeWithTransfer`

structuredClone.deserializeWithTransfer<T extends SerializableValue | TransferableValue>(serialized: SerializedTransfer, interfaces?: (SerializableConstructor | TransferableConstructor)[]): T

Parameters

Parameter	Type	Default	Description
`serialized`	`SerializedTransfer`	—	A value previously produced by `serializeWithTransfer`.
`interfaces?`	`(SerializableConstructor \| TransferableConstructor)[]`	—	Serializable and transferable constructors to recognize when deserializing custom platform objects.

Returns T — The value reconstructed from serialized, with its transferred objects re-attached.

`structuredClone.serialize`

structuredClone.serialize(value: SerializableValue, forStorage?: boolean, interfaces?: (SerializableConstructor | TransferableConstructor)[]): SerializedValue

Parameters

Parameter	Type	Default	Description
`value`	`SerializableValue`	—	The value to serialize.
`forStorage?`	`boolean`	—	Whether the serialized form will be persisted rather than sent across a boundary immediately.
`interfaces?`	`(SerializableConstructor \| TransferableConstructor)[]`	—	Serializable and transferable constructors to recognize when serializing custom platform objects.

Returns SerializedValue — A serialized representation of value.

`structuredClone.serializeWithTransfer`

structuredClone.serializeWithTransfer(value: SerializableValue | TransferableValue, transferList?: TransferableValue[], interfaces?: (SerializableConstructor | TransferableConstructor)[]): SerializedTransfer

Parameters

Parameter	Type	Default	Description
`value`	`SerializableValue` \| `TransferableValue`	—	The value to serialize.
`transferList?`	`TransferableValue[]`	—	Transferable objects to include in the transfer list; each is detached from the original after serializing.
`interfaces?`	`(SerializableConstructor \| TransferableConstructor)[]`	—	Serializable and transferable constructors to recognize when serializing custom platform objects.

Returns SerializedTransfer — A serialized representation of value, plus its transfer list.

`structuredClone.preencode(state: object, serialized: SerializedValue | SerializedTransfer): void`

A compact-encoding preencode step for a value already produced by serialize() or serializeWithTransfer(): a dry run that only advances state.end, to size the buffer before encoding.

Parameters

Parameter	Type	Default	Description
`state`	`object`	—	A `compact-encoding` state (`{ start, end, buffer }`), typically created with `require('compact-encoding').state()`.
`serialized`	`SerializedValue` \| `SerializedTransfer`	—	A value previously produced by `serialize()` or `serializeWithTransfer()`.

`structuredClone.encode(state: object, serialized: SerializedValue | SerializedTransfer): void`

The compact-encoding encode step: writes serialized into state.buffer at state.start, advancing state.start past the encoded value.

Parameters

Parameter	Type	Default	Description
`state`	`object`	—	A `compact-encoding` state, with `buffer` sized to `state.end` from a prior `preencode` call.
`serialized`	`SerializedValue` \| `SerializedTransfer`	—	A value previously produced by `serialize()` or `serializeWithTransfer()`.

`structuredClone.decode(state: object): SerializedValue | SerializedTransfer`

The compact-encoding decode step: reads a serialized value back out of state.buffer at state.start, advancing state.start past it. Pass the result to deserialize() or deserializeWithTransfer() to reconstruct the original value.

Parameters

Parameter	Type	Default	Description
`state`	`object`	—	A `compact-encoding` state positioned at a previously encoded value.

Returns SerializedValue \| SerializedTransfer — The decoded serialized value.

Constants and variables

`structuredClone.constants`

structuredClone.constants: {
  VERSION: number

  type: {
    // Primitive types
    UNDEFINED: 0
    NULL: 1
    TRUE: 2
    FALSE: 3
    NUMBER: 4
    INTEGER: 5
    BIGINT: 6
    STRING: 7

    // Builtin objects
    DATE: 8
    REGEXP: 9
    ERROR: 10

    // Builtin binary data objects
    ARRAYBUFFER: 11
    RESIZABLEARRAYBUFFER: 12
    SHAREDARRAYBUFFER: 13
    GROWABLESHAREDARRAYBUFFER: 14
    TYPEDARRAY: 15
    DATAVIEW: 16

    // Builtin composite objects
    MAP: 17
    SET: 18
    ARRAY: 19
    OBJECT: 20

    // Object references
    REFERENCE: 21

    // Object transfers
    TRANSFER: 22

    // Platform objects
    URL: 23
    BUFFER: 24
    EXTERNAL: 25
    SERIALIZABLE: 26
    TRANSFERABLE: 27

    typedarray: {
      UINT8ARRAY: 1
      UINT8CLAMPEDARRAY: 2
      INT8ARRAY: 3
      UINT16ARRAY: 4
      INT16ARRAY: 5
      UINT32ARRAY: 6
      INT32ARRAY: 7
      BIGUINT64ARRAY: 8
      BIGINT64ARRAY: 9
      FLOAT16ARRAY: 12
      FLOAT32ARRAY: 10
      FLOAT64ARRAY: 11
    }

    error: {
      AGGREGATE: 1
      EVAL: 2
      RANGE: 3
      REFERENCE: 4
      SYNTAX: 5
      TYPE: 6
      URI: 7
    }

    // Property key kinds
    key: {
      INDEX: 1
      NAME: 2
      NAME_REFERENCE: 3
    }

    // Array layouts
    array: {
      DENSE: 1
      SPARSE: 2
    }
  }
}

Numeric tags used in serialized values. Also available as require('bare-structured-clone/constants').

`structuredClone.symbols`

structuredClone.symbols: {
  readonly serialize: unique symbol
  readonly deserialize: unique symbol
  readonly detach: unique symbol
  readonly attach: unique symbol
  readonly interface: unique symbol
}

Types

`structuredClone.SerializableValue`

type SerializableValue = | undefined
  | null
  | boolean
  | number
  | bigint
  | string
  | Date
  | RegExp
  | Error
  | ArrayBuffer
  | SharedArrayBuffer
  | Uint8Array
  | Uint8ClampedArray
  | Int8Array
  | Uint16Array
  | Int16Array
  | Uint32Array
  | Int32Array
  | BigUint64Array
  | BigInt64Array
  | Float16Array
  | Float32Array
  | Float64Array
  | DataView
  | Map<SerializableValue, SerializableValue>
  | Set<SerializableValue>
  | SerializableValue[]
  | { [key: string | number]: SerializableValue }
  | URL
  | Buffer
  | Serializable

`structuredClone.TransferableValue`

type TransferableValue = ArrayBuffer | Transferable

`StructuredCloneOptions`

interface StructuredCloneOptions {
  transfer: TransferableValue[]
  interfaces: (SerializableConstructor | TransferableConstructor)[]
}

`SerializableConstructor`

interface SerializableConstructor<T = unknown> {
}

`TransferableConstructor`

interface TransferableConstructor<T = unknown> {
}

`SerializedTransfer`

interface SerializedTransfer {
  type: typeof constants.type.TRANSFER
  transfers: (
    | SerializedArrayBufferTransfer
    | SerializedResizableArrayBufferTransfer
    | SerializedTransferableTransfer
  )[]
  value: SerializedValue
}

`SerializedArrayBufferTransfer`

interface SerializedArrayBufferTransfer {
  type: typeof constants.type.ARRAYBUFFER
  id: number
  backingStore: ArrayBuffer
}

`SerializedResizableArrayBufferTransfer`

interface SerializedResizableArrayBufferTransfer {
  type: typeof constants.type.RESIZABLEARRAYBUFFER
  id: number
  backingStore: ArrayBuffer
  maxByteLength: number
}

`SerializedTransferableTransfer`

interface SerializedTransferableTransfer {
  type: typeof constants.type.TRANSFERABLE
  id: number
  interface: number
  value: SerializedValue
}

Classes

`Serializable`

class Serializable {
}

Base class for a custom serializable type. A subclass implements [symbols.serialize](forStorage), returning the SerializableValue to serialize, and a static [symbols.deserialize](serialized), returning a new instance reconstructed from it. The subclass's constructor must be registered via the interfaces option on both ends of the clone.

`Transferable`

class Transferable {
  detached: boolean
}

Base class for a custom transferable type. A subclass implements [symbols.detach](), releasing ownership and returning the SerializableValue to serialize, and a static [symbols.attach](serialized), returning a new instance that takes ownership of serialized. The base [symbols.detach]() implementation sets detached to true; a subclass should call super[symbols.detach]() after releasing its own state. The subclass's constructor must be registered via the interfaces option on both ends of the clone.

constants: {
  VERSION: number

  type: {
    // Primitive types
    UNDEFINED: 0
    NULL: 1
    TRUE: 2
    FALSE: 3
    NUMBER: 4
    INTEGER: 5
    BIGINT: 6
    STRING: 7

    // Builtin objects
    DATE: 8
    REGEXP: 9
    ERROR: 10

    // Builtin binary data objects
    ARRAYBUFFER: 11
    RESIZABLEARRAYBUFFER: 12
    SHAREDARRAYBUFFER: 13
    GROWABLESHAREDARRAYBUFFER: 14
    TYPEDARRAY: 15
    DATAVIEW: 16

    // Builtin composite objects
    MAP: 17
    SET: 18
    ARRAY: 19
    OBJECT: 20

    // Object references
    REFERENCE: 21

    // Object transfers
    TRANSFER: 22

    // Platform objects
    URL: 23
    BUFFER: 24
    EXTERNAL: 25
    SERIALIZABLE: 26
    TRANSFERABLE: 27

    typedarray: {
      UINT8ARRAY: 1
      UINT8CLAMPEDARRAY: 2
      INT8ARRAY: 3
      UINT16ARRAY: 4
      INT16ARRAY: 5
      UINT32ARRAY: 6
      INT32ARRAY: 7
      BIGUINT64ARRAY: 8
      BIGINT64ARRAY: 9
      FLOAT16ARRAY: 12
      FLOAT32ARRAY: 10
      FLOAT64ARRAY: 11
    }

    error: {
      AGGREGATE: 1
      EVAL: 2
      RANGE: 3
      REFERENCE: 4
      SYNTAX: 5
      TYPE: 6
      URI: 7
    }

    // Property key kinds
    key: {
      INDEX: 1
      NAME: 2
      NAME_REFERENCE: 3
    }

    // Array layouts
    array: {
      DENSE: 1
      SPARSE: 2
    }
  }
}

Numeric tags used in serialized values. Also available as require('bare-structured-clone/constants').

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code ALREADY_TRANSFERRED.

`errors.DataCloneError.INVALID_ARRAY_LAYOUT(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_ARRAY_LAYOUT.

`errors.DataCloneError.INVALID_INTERFACE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_INTERFACE.

`errors.DataCloneError.INVALID_PROPERTY_KEY(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_PROPERTY_KEY.

`errors.DataCloneError.INVALID_REFERENCE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_REFERENCE.

`errors.DataCloneError.INVALID_TYPE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	—

`errors.DataCloneError.INVALID_VERSION(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code INVALID_VERSION.

`errors.DataCloneError.INVALID_VIEW(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	—

`errors.DataCloneError.UNSERIALIZABLE_TYPE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code UNSERIALIZABLE_TYPE.

`errors.DataCloneError.UNTRANSFERABLE_TYPE(msg: string): DataCloneError`

Parameters

Parameter	Type	Default	Description
`msg`	`string`	—	The error message.

Returns DataCloneError — A new DataCloneError with code UNTRANSFERABLE_TYPE.

bare-structured-clone

On this page