Serialization

const encode = createJsonEncoder<Session>();
const decode = createJsonDecoder<Session>();

const wire = encode(session); // a JSON string — Date and Map survive
const back = decode(wire); // Date is a Date again, Map is a Map again

back.startedAt instanceof Date; // true
back.flags instanceof Map; // true

// Plain JSON.stringify can't do this — your Date turns into a string and
// your Map turns into {} on the way out, and never comes back.
JSON.stringify(session); // {"id":"s-1","startedAt":"2026-01-01T...","flags":{}}

// 'clone' (default) — builds a fresh value from the declared shape, so
// undeclared keys are dropped for free. Never touches your input.
const encodeClean = createJsonEncoder<Profile>({strategy: 'clone'});

// 'mutate' — transforms leaves in place (no clone), and KEEPS undeclared keys
// on the wire. Fastest, but it mutates the object you pass in.
const encodeFast = createJsonEncoder<Profile>({strategy: 'mutate'});

// 'direct' — single pass, no clone, always strips undeclared keys.
const encodeDirect = createJsonEncoder<Profile>({strategy: 'direct'});

const encode = createBinaryEncoder<Telemetry>();
const decode = createBinaryDecoder<Telemetry>();

const bytes = encode(sample); // an ArrayBuffer — compact, no field names on the wire
const back = decode(bytes); // typed as DataOnly<Telemetry>

back.recordedAt instanceof Date; // true — Date round-trips, like JSON

// In a hot loop, build the serializer once and hand it to the encoder so it
// reuses the same backing buffer instead of allocating a fresh one each call.
const ser = createDataViewSerializer('ticks');
const ticks: Tick[] = [
  {symbol: 'TS', price: 7},
  {symbol: 'GO', price: 9},
];

const buffers = ticks.map((tick) => encode(tick, ser)); // writes into the shared serializer

// Same idea on the way back — reuse a deserializer for a known buffer.
const des = createDataViewDeserializer('ticks', buffers[0]);
const firstTick = decode(des);

import {registerClassSerializer, createJsonEncoder, createJsonDecoder} from 'ts-runtypes';

// Your own class. ts-runtypes can't guess how to put it on the wire, so
// you teach it once: a serialize/deserialize pair keyed by the class name.
class Money {
  constructor(
    public amount: number,
    public currency: string
  ) {}
}

registerClassSerializer<Money>('Money', {
  // instance -> JSON-ready data (the pipeline stringifies this for you)
  serialize: (m) => `${m.amount} ${m.currency}`,
  // parsed data -> rebuilt instance
  deserialize: (data) => {
    const [amount, currency] = String(data).split(' ');
    return new Money(Number(amount), currency);
  },
});

type Invoice = {id: string; total: Money};

const encode = createJsonEncoder<Invoice>();
const decode = createJsonDecoder<Invoice>();

const json = encode({id: 'inv_1', total: new Money(4999, 'USD')});
const back = decode(json); // back.total is a real Money instance again

export {Money, encode, decode, back};
export type {Invoice};

// Arm the guard for THIS encoder only. The encoder throws a
// `CircularReferenceError` instead of recursing forever.
const encode = createJsonEncoder<Node>(undefined, {rejectCircularRefs: true});

try {
  encode(cyclic as Node);
} catch (err) {
  err instanceof CircularReferenceError; // true
  (err as CircularReferenceError).path; // ['next'] — where the back-edge was found
}

// Or arm it once globally — every guarded factory (validate, getValidationErrors,
// JSON encoder, binary encoder) checks unless given `{rejectCircularRefs: false}`.
setRejectCircularRefs(true);

const encodeBin = createBinaryEncoder<Node>(); // armed via the global flag
try {
  encodeBin(cyclic as Node);
} catch (err) {
  err instanceof CircularReferenceError; // true
}

setRejectCircularRefs(false); // disarm — back to the default

// Shared-but-acyclic values pass — `shared` is reached twice, but never
// through itself, so the guard stays quiet.
const shared: Node = {name: 'shared'};
const dag: Node[] = [
  {name: 'root', next: shared},
  {name: 'alt', next: shared},
];

const encodeList = createJsonEncoder<Node[]>(undefined, {rejectCircularRefs: true});
encodeList(dag); // encodes normally — no cycle

const decode = createJsonDecoder<Cart>();

// The decoder returns DataOnly<Cart>, not Cart — the method is gone from the
// type because it was never on the wire. TS now stops you from calling it.
const cart = decode('{"items":["TS-7"],"total":42}');

cart.items; // string[]  ✅
cart.total; // number    ✅
// cart.checkout();      ❌ TS error — checkout isn't part of DataOnly<Cart>