typed-clone

Type-safe, performant, and extensible clone implementation.

---

Motivation

This library was initially developed to provide a type-safe alternative to the naive structuredClone-based implementation in grugway.

• Type-safe: Clearly encodes types that can and cannot be meaningfully cloned through the type system. Not-cloneable types get returned as Ref<T> explicitly.
• Performant: Fast enough for the 20% of data types that make up 80% of real-world usage. structuredClone fallback for the rest (e.g. typed arrays).
• Extensible: Simple, symbol-based clone protocol for custom types.

Use Cases

This library particularly shines when referential transparency and infallibility are desired, or when dealing with heterogeneous and complex data that usually requires hand-rolled copy/clone implementations. typed-clone offers a good baseline implementation in those cases.

The custom clone protocol also allows for a seamless interaction of standard data types with your custom types or domain model.

---

Quick Start

Runtime Requirements

• Bun: ≥1.0.0
• Deno: ≥1.14
• Node.js: ≥17.0.0
• Browsers: Support structuredClone

Installation

Node.js / Bun:

(bun | (p)npm) add @aedge-io/typed-clone

Deno:

deno add jsr:@aedge-io/typed-clone

---

Usage

Simple

import { clone } from "@aedge-io/typed-clone";

const clonedRec = clone({ msg: "hello there!" }); // { msg: string }
const clonedFn = clone(() => "hello there again!"); // Ref<() => string>

Complex

import { Clone, clone, Cloneable, CloneOptions } from "@aedge-io/typed-clone";

class NotCloneable {
  constructor(readonly name: string, private age: number) {}
  greet() {
    return `Hi, I am ${this.name} and ${this.age} years old.`;
  }
}

class Point { // implements Cloneable<Point>
  constructor(private x: number, private y: number) {}
  [Clone](opts?: CloneOptions) {
    return new Point(this.x, this.y);
  }
}

const randInt = () => Math.floor(Math.random() * 100);

const uintArray = new Uint8Array(new ArrayBuffer(4));
uintArray.set([0, 1, 2, 3]);

const meta = {
  createdAt: new Date(),
};

const original = {
  metadata: meta,
  handlers: new Map([["rand", randInt]]),
  primitives: ["string", 42, true, BigInt(9001), Symbol("foo")] as const,
  ref: new NotCloneable("Bob", 71),
  points: {
    unique: new Set([new Point(0, 1), new Point(1, 2)]),
    metadata: meta,
  },
  buf: uintArray,
  circularRef: {},
};
original.circularRef = original;

const cloned = clone(original, { transfer: [original.buf.buffer] });

// cloned = {
//   metadata: {
//     createdAt: Date;
//   };
//   handlers: Map<string, Ref<() => number>>;
//   primitives: readonly [string, number, boolean, bigInt, Ref<unique symbol>];
//   ref: Ref<NotCloneable>;
//   points: {
//     unique: Set<Point>; /* `Point` supports clone protocol */
//     metadata: {
//         createdAt: Date;
//     };
//   };
//   buf: Uint8Array<ArrayBuffer>;
//   circularRef: { ... };
// };

console.log("deep clone:", cloned !== original);
console.log("metadata cloned:", cloned.metadata !== original.metadata);
console.log("date cloned:", +cloned.metadata.createdAt === +meta.createdAt);
console.log("map cloned:", cloned.handlers !== original.handlers);
console.log("fn is ref:", cloned.handlers.get("rand") === randInt);
console.log("array cloned:", cloned.primitives !== original.primitives);
console.log("symbol is ref:", cloned.primitives[4] === original.primitives[4]);
console.log("class is ref:", cloned.ref === original.ref);
console.log("set cloned:", cloned.points.unique !== original.points.unique);
console.log("buf transferred:", original.buf.buffer.byteLength === 0);
console.log("circular ref preserved:", cloned.circularRef === cloned);
console.log(
  "shared refs preserved:",
  cloned.metadata === cloned.points.metadata,
);

---

Performance

clone = clone(value) (default, shared-ref cache)

clone (nc) = clone(value, { preserveRefs: false })

Benchmark	clone	ops/s	clone (nc)	ops/s
Plain record (8 keys)	257.1 ns	3,890,000	203.8 ns	4,908,000
Plain record (64 keys)	2.3 µs	440,400	2.2 µs	463,400
Plain record (256 keys)	23.0 µs	43,520	21.7 µs	46,020
Nested records (d=4, 16 leaves)	4.3 µs	232,000	2.8 µs	351,900
Nested records (d=8, 256 leaves)	77.3 µs	12,940	47.6 µs	21,030
Nested records (d=12, 4096 leaves)	1.3 ms	745	790.3 µs	1,265
Array<primitive> (n=256)	317.2 ns	3,152,000	333.8 ns	2,996,000
Array<primitive> (n=8192)	9.0 µs	111,300	8.9 µs	112,900
Array<record> (n=256)	39.4 µs	25,370	24.5 µs	40,830
Array<record> (n=8192)	1.4 ms	720	757.0 µs	1,321
Map<string,record> (n=256)	47.4 µs	21,100	35.4 µs	28,290
Set<record> (n=256)	47.1 µs	21,230	35.2 µs	28,380
Real: Frontend state slice	1.3 µs	758,900	941.4 ns	1,062,000
Real: JSON Schema (32 props)	19.5 µs	51,230	12.7 µs	78,500
Real: API collection (32 items)	96.4 µs	10,370	75.4 µs	13,260
Real: Agent session (32 turns)	50.2 µs	19,930	33.7 µs	29,690
Real: Normalized store (256 entities)	111.2 µs	8,992	103.0 µs	9,708
Real: Dashboard data (8K rows)	349.9 µs	2,858	322.3 µs	3,103

By default, typed-clone keeps track of object references to support shared and circular references. The overhead is most pronounced for small data structures. By disabling it, clone operations can be up to ~50% faster.

For a comprehensive write-up including memory overhead and comparison to rfdc and structuredClone, see docs.

Your mileage may vary though! Run the full benchmark suite with deno bench.

Security

Unlike similar packages, typed-clone guards against primitive prototype poisoning. However, this protection does not extend to prototype pollution in general, since the mitigations are quite runtime-dependent.

• Secure JSON.parse
• MDN prototype pollution

Caveats

Given the structural nature of TypeScript's type system, certain edge-case subclasses currently don't get inferred correctly. Check out the docs for a comprehensive overview.

---

License

MIT License — see LICENSE.md

Resources

• MDN structuredClone
• V8 Memory Model