bare-structured-clone

Reference for bare-structured-clone: the HTML structured-clone algorithm for Bare—structuredClone plus low-level serialize/deserialize with transfer.

stable

bare-structured-clone implements the HTML structured-clone algorithm for Bare: the structuredClone function plus the low-level serialize/deserialize primitives that inter-thread messaging (bare-channel) is built on. It's a native addon and requires Bare >=1.2.0.

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] })

Require bare-structured-clone/global to install structuredClone as a global.

API

`const copy = structuredClone(value[, options])`

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

options = {
  transfer: [],
  interfaces: []
}

transfer is an array of ArrayBuffer and Transferable objects whose ownership is transferred to the clone. After transfer, the original objects are detached. interfaces is an array of Serializable and Transferable constructors that may appear in value; each constructor must be present at both serialize and deserialize time.

Low-level serialization

`serialize(value[, forStorage[, interfaces]])` · `serializeWithTransfer(value[, transferList[, interfaces]])`

Produce a serialized representation, optionally with a transfer list.

`deserialize(serialized[, interfaces])` · `deserializeWithTransfer(serialized[, interfaces])`

Reconstruct a value from its serialized form.

`preencode(state, serialized)` · `encode(state, serialized)` · `const serialized = decode(state)`

The wire codec used to move serialized values across a boundary, plus constants, symbols, and the Serializable / Transferable base classes for custom types.

`class Serializable`

Base class for custom serializable interfaces. Subclasses must implement two methods keyed by the symbols above:

const { Serializable, symbols } = require('bare-structured-clone')

class MySerializable extends Serializable {
  [symbols.serialize](forStorage) {
    // Return a `SerializableValue` describing this instance
  }

  static [symbols.deserialize](serialized) {
    // Return a new instance reconstructed from `serialized`
  }
}

The constructor must be registered via the interfaces option on both ends of the clone.

`class Transferable`

Base class for custom transferable interfaces. Instances carry a detached boolean that flips to true once ownership has been transferred. Subclasses must implement two methods keyed by the symbols above:

const { Transferable, symbols } = require('bare-structured-clone')

class MyTransferable extends Transferable {
  [symbols.detach]() {
    // Release ownership and return a `SerializableValue` describing
    // the detached state
  }

  static [symbols.attach](serialized) {
    // Return a new instance that takes ownership of `serialized`
  }
}

The constructor must be registered via the interfaces option on both ends of the clone. The base detach implementation sets detached to true; subclasses should call super[symbols.detach]() after releasing their state.

Builds on bare-buffer, bare-type, and bare-url (see Bare modules).