Node V8 Serialization: Preserve Shared TypedArray Backing with an Explicit Contract

A binary cache can return exactly the bytes you saved and still break your program. If two views originally shared an ArrayBuffer, writing through one view may stop updating the other after a V8 serialize/deserialize round trip. Test the sharing relationship separately from the initial data. For a local deep clone, structuredClone can preserve this relationship in the fixture below. For a stored representation, encode one backing store plus view descriptors and reconstruct the views explicitly.

This guide addresses a specific reader report from May 2023 in Node issue 48153. The report is evidence of a real developer problem, not a measurement of current search demand. Its closure does not establish that the two APIs became interchangeable. The examples here were executed on Node v26.5.0 on macOS arm64; run them on your deployment version before adopting their assertions. No worker transfer, throughput benchmark, hostile-input decoder, or cross-version persistence compatibility was tested.

Reproduce bytes that match but updates that diverge

Start with an eight-byte store and two overlapping views. Both views begin at byte two and cover four bytes. The nonzero offset makes it harder for an accidental whole-buffer copy to appear correct. Save the following as a CommonJS file and run it with node. Each assertion describes a distinct requirement, and a failed assertion should stop the check.

'use strict';
const assert = require('node:assert/strict');
const {serialize, deserialize} = require('node:v8');

const backing = new ArrayBuffer(8);
const bytes = new Uint8Array(backing, 2, 4);
const view = new DataView(backing, 2, 4);
bytes.set([11, 22, 33, 44]);
const original = {backing, bytes, view};

const cloned = structuredClone(original);
assert.notEqual(cloned.backing, backing);
assert.equal(cloned.bytes.buffer, cloned.backing);
assert.equal(cloned.view.buffer, cloned.backing);
assert.equal(cloned.bytes.byteOffset, 2);
cloned.bytes[0] = 99;
assert.equal(cloned.view.getUint8(0), 99);
assert.equal(bytes[0], 11);

const restored = deserialize(serialize(original));
assert.deepEqual([...restored.bytes], [11, 22, 33, 44]);
assert.equal(restored.view.getUint8(0), 11);
restored.bytes[0] = 88;
assert.equal(restored.view.getUint8(0), 11);
assert.equal(new Uint8Array(restored.backing)[2], 11);
assert.equal(bytes[0], 11);
console.log(process.version, 'bytes match; alias contract differs');

The expected final line ends with “bytes match; alias contract differs.” The important failure is semantic: changing restored.bytes does not update restored.view or the separately restored backing object at the corresponding location. A byte-for-byte comparison immediately after loading would miss it. Do not use buffer identity alone as the test: backing allocations and offsets may be implementation details. Mutation at an overlapping byte is the behavior your application actually relies on.

The clone also remains independent of the original. Sharing within the cloned graph and sharing with the input are different requirements. This fixture demands the first and rejects the second. A shallow object spread would leave the original views in place; that is the separate problem covered by object spread and nested updates.

Why the default serializer is relevant

Node documents that v8.serialize uses DefaultSerializer. That class handles typed views as host objects and records their referenced byte regions. Consequently, preserving a view's data is not the same application contract as retaining every relationship between its original backing store and other views. The observed round trip above is consistent with that distinction. The exact allocation strategy is not a suitable cache schema.

Use structuredClone when your actual goal is an in-process clone and its supported value types fit your data. This example deliberately uses Uint8Array and DataView. It does not establish that a Node Buffer keeps its Buffer-specific prototype or methods after cloning. It also does not exercise the transfer option, detachment, SharedArrayBuffer, functions, custom classes, or external resources. Test those requirements separately if they are part of your object graph.

When you need bytes to persist or send elsewhere, the clone operation alone does not define a stored format. First decide what a consumer must reconstruct: independent byte snapshots, a shared backing store, or only higher-level decoded values. Keeping independent snapshots can be correct for immutable data. Reconstructing aliasing matters when consumers depend on mutations being visible through multiple views.

Store one byte array and rebuild two overlapping views

The following self-contained example uses a small versioned envelope. Byte offsets are relative to the one stored backing array. Length is expressed in bytes for both supported view types. These units are deliberate: other typed-array constructors take element counts and can impose alignment requirements. Do not add them by substituting a constructor name without extending and testing the schema.

'use strict';
const assert = require('node:assert/strict');
const {serialize, deserialize} = require('node:v8');

function restore(wire) {
  if (!wire || wire.version !== 1 || !Array.isArray(wire.data) ||
      wire.data.length > 1024 ||
      !wire.data.every(n => Number.isInteger(n) && n >= 0 && n <= 255) ||
      !Array.isArray(wire.views) || wire.views.length !== 2) {
    throw new TypeError('Invalid bounded local envelope');
  }
  const store = Uint8Array.from(wire.data).buffer;
  const output = {backing: store};
  for (const [index, d] of wire.views.entries()) {
    const expected = index === 0 ? 'Uint8Array' : 'DataView';
    if (!d || d.kind !== expected ||
        !Number.isSafeInteger(d.offset) || d.offset < 0 ||
        !Number.isSafeInteger(d.length) || d.length < 0 ||
        d.offset > store.byteLength ||
        d.length > store.byteLength - d.offset) {
      throw new RangeError('Invalid view descriptor');
    }
    if (index === 0) {
      output.bytes = new Uint8Array(store, d.offset, d.length);
    } else {
      output.view = new DataView(store, d.offset, d.length);
    }
  }
  return output;
}

const envelope = {
  version: 1,
  data: [0, 0, 11, 22, 33, 44, 0, 0],
  views: [
    {kind: 'Uint8Array', offset: 2, length: 4},
    {kind: 'DataView', offset: 3, length: 3},
  ],
};
const decoded = deserialize(serialize(envelope));
const result = restore(decoded);
assert.equal(result.bytes.buffer, result.backing);
assert.equal(result.view.buffer, result.backing);
assert.equal(result.bytes.byteOffset, 2);
assert.equal(result.view.byteOffset, 3);
assert.deepEqual([...result.bytes], [11, 22, 33, 44]);
assert.equal(result.view.getUint8(0), 22);
result.bytes[1] = 77;
assert.equal(result.view.getUint8(0), 77);
assert.equal(envelope.data[3], 22);

for (const [field, value] of [
  ['offset', -1], ['offset', 9], ['offset', 2.5],
  ['length', -1], ['length', 99], ['kind', 'Uint16Array'],
]) {
  const bad = structuredClone(envelope);
  bad.views[0][field] = value;
  assert.throws(() => restore(bad), RangeError);
}
const badByte = structuredClone(envelope);
badByte.data[0] = 256;
assert.throws(() => restore(badByte), TypeError);
const badVersion = structuredClone(envelope);
badVersion.version = 2;
assert.throws(() => restore(badVersion), TypeError);
console.log(process.version, 'shared mutation and 8 invalid cases checked');

Here the second view starts one byte after the first. The update uses bytes[1] and view.getUint8(0), which refer to the same backing position. This catches a decoder that restores both views at the same offset merely because the first example did so. The input envelope remains unchanged because the reconstruction allocates a new store.

This is a bounded local fixture, not a general secure binary interchange parser. In particular, validation happens after V8 deserialization; the size check cannot prevent the deserializer from allocating memory first. Accepting arbitrary external payloads needs transport-size limits, format selection, resource limits and separate security review. The helper assumes a dense array of ordinary local values. It is not designed for sparse arrays, proxy objects, arbitrary properties or user-selected constructors.

Define the production boundary before changing the cache

The example preserves all eight backing bytes. In a real Buffer slice, the underlying store may contain unrelated bytes outside the intended range. Do not export a whole backing allocation merely to preserve aliasing. Identify the allowed data region first, copy only that region into a deliberate store, and translate every offset to the new origin. The Buffer range and length guide addresses those units separately; it does not replace the sharing checks here.

For multiple stores, add explicit store identifiers and a fixed allowlist of view kinds. Decide how to represent lengths, empty views, overlapping regions and out-of-range descriptors. Preserve the schema version and specify rejection of unknown versions. Keep tests that check initial values, unequal offsets, shared mutation and source independence. For multibyte views, add alignment and byte-order checks appropriate to the actual operations.

Before migrating existing cache entries, test your installed runtime, real view types, expected maximum size and stored-format compatibility policy. This guide does not claim that disk round trips, upgrades or worker messages were validated. If you only need immutable snapshots, independent views may already meet your contract; avoid reconstructing sharing without a reader requirement. If you need mutable shared views, make that requirement explicit and verify it after loading rather than treating successful serialization as proof.