buffered-clone

Social Media Photo by marc belver colomer on Unsplash

A structuredClone like utility that converts all supported JS types, plus ImageData, into a binary format.

Highlights

• recursive out of the box for almost anything that can be serialized
• once hot, it's nearly as fast as native structuredClone
• it allows filling pre-allocated buffers and SharedArrayBuffer
• it allows growing buffers if resizable
• supports toJSON (already) and MessagePack extensions like mechanism (coming soon)

API

import BufferedClone from 'buffered-clone';

const { encode, decode } = new BufferedClone({
  // it's feature detected at runtime, don't change it
  // unless you know what you are doing.
  littleEndian: true,
  // by default makes references and strings encoded once
  circular: true,
  // if a view has already reserved buffer size,
  // this can be used to offset the encoding
  byteOffset: 0,
  // either the initial buffer length, when not provided,
  // or the amount of RAM to ask per each resize on top
  // of the new required size (incremental grow): the smaller
  // this value is, the least RAM is used but the slowest
  // serialization happens while encoding (due multiple resizes)
  byteLength: 0x1000000,
  // forces usage of Float 32 numbers instead of
  // the JS default which is Float 64
  useFloat32: false,
  // encodes strings directly as UTF16 without
  // needing any UTF16 to UTF8 conversion.
  // it is usually faster than UTF8 encode + view.set(...)
  // and it can deal with SharedArrayBuffer or resizable
  // ArrayBuffer without throwing, ideal for encodeInto case
  useUTF16: false,
  // mirrors common known strings or values
  // across worlds: it must be a precise list
  mirrored: [],
  // it can be a growable SharedArrayBuffer
  // or a resizable ArrayBuffer
  // or just nothing, defaulting to:
  buffer: new ArrayBuffer(0x1000000)
});

// returns a Uint8Array of the serialized data
encode(anyCompatibleValue);


// encodes *into* the currently available buffer
encode(anyCompatibleValue, true);
// encodes *into* a different buffer (discards the previous)
encode(anyCompatibleValue, specificBuffer);

// returns any compatible value that was serialized
decode(ui8a);