+ Six demonstrations from src/main.ts. The Vite AOT plugin in
+ vite.config.ts inlines every type(…) call at
+ build time, so no runtime new Function is involved.
+
if we're in a browser ──────────
+
+const out =
+ typeof document !== 'undefined' ? document.getElementById('out') : null;
+
+function log(...args: unknown[]): void {
+ console.log(...args);
+ if (out) {
+ const text = args
+ .map((a) => {
+ if (typeof a === 'string') return a;
+ if (a instanceof Uint8Array) return `Uint8Array(${a.length})`;
+ try {
+ return JSON.stringify(a);
+ } catch {
+ return String(a);
+ }
+ })
+ .join(' ');
+ out.textContent += text + '\n';
+ }
+}
+
+// ─── Example 1: flat schema ────────────────────────────────────────────────
+//
+// Define a Ticker, infer its TypeScript type from the schema, encode and
+// decode it. This is the 90% use case.
+
+const Ticker = type('Ticker', {
+ symbol: str,
+ last: f64,
+ bid: f64,
+ ask: f64,
+ volume: f64,
+});
+
+type Ticker = typeof Ticker.$infer;
+// → { symbol: string; last: number; bid: number; ask: number; volume: number }
+
+const ticker: Ticker = {
+ symbol: 'BTC-USD',
+ last: 67891.23,
+ bid: 67890.5,
+ ask: 67892.0,
+ volume: 1234567.89,
+};
+
+const tickerBytes = Ticker.encode(ticker);
+const tickerBack = Ticker.decode(tickerBytes);
+
+log('Example 1: Ticker');
+log(` encoded ${tickerBytes.length} bytes (JSON would be ${JSON.stringify(ticker).length})`);
+log(' decoded:', tickerBack);
+
+// ─── Example 2: nested object + list ───────────────────────────────────────
+//
+// `Level` is itself a codec; it can be passed as a field in another `type()`.
+// The transformer inlines its encode/decode into the parent — no per-element
+// function dispatch.
+
+const Level = type('Level', { p: f64, q: f64 });
+
+const Book = type('Book', {
+ symbol: str,
+ ts: u53,
+ bids: list(Level),
+ asks: list(Level),
+});
+
+const book = {
+ symbol: 'BTC-USD',
+ ts: Date.now(),
+ bids: [
+ { p: 67890.5, q: 0.1 },
+ { p: 67890.0, q: 0.3 },
+ { p: 67889.5, q: 0.5 },
+ ],
+ asks: [
+ { p: 67891.0, q: 0.2 },
+ { p: 67891.5, q: 0.4 },
+ ],
+};
+
+const bookBytes = Book.encode(book);
+log('\nExample 2: OrderBook');
+log(` encoded ${bookBytes.length} bytes (JSON: ${JSON.stringify(book).length})`);
+log(' decoded.bids[0]:', Book.decode(bookBytes).bids[0]);
+
+// ─── Example 3: enum + bitset + optional ───────────────────────────────────
+//
+// Enums encode as one byte. Bitsets pack up to 32 flags into a u32. Optional
+// fields add one presence byte.
+
+const Order = type('Order', {
+ id: u53,
+ side: enumOf(['buy', 'sell'] as const),
+ qty: f64,
+ price: opt(f64), // market orders have no price
+ flags: flags(['ioc', 'post_only', 'reduce_only'] as const),
+});
+
+const marketOrder = {
+ id: 1,
+ side: 'buy' as const,
+ qty: 0.5,
+ price: undefined,
+ flags: { ioc: true, post_only: false, reduce_only: false },
+};
+
+const limitOrder = {
+ id: 2,
+ side: 'sell' as const,
+ qty: 0.5,
+ price: 67900,
+ flags: { ioc: false, post_only: true, reduce_only: false },
+};
+
+log('\nExample 3: Orders (enum + opt + flags)');
+log(` market: ${Order.encode(marketOrder).length}b`);
+log(` limit: ${Order.encode(limitOrder).length}b`);
+
+// ─── Example 4: discriminated union ────────────────────────────────────────
+//
+// Each variant has its own field map. The discriminator (`kind`) is written as
+// a one-byte tag, then the variant's fields follow.
+
+const Event = oneOf('Event', 'kind', {
+ fill: { price: f64, qty: f64 },
+ cancel: { reason: str },
+ expire: { at: u53 },
+});
+
+const events = [
+ { kind: 'fill', price: 67891.0, qty: 0.5 },
+ { kind: 'cancel', reason: 'user-requested' },
+ { kind: 'expire', at: Date.now() + 60_000 },
+];
+
+log('\nExample 4: Events (union)');
+for (const e of events) {
+ const bytes = Event.encode(e as never);
+ log(` ${e.kind.padEnd(7)}: ${bytes.length}b`);
+}
+
+// ─── Example 5: pooled writer (hot path) ───────────────────────────────────
+//
+// Reuse one Writer across many encodes. `encodeInto` writes directly into the
+// pooled buffer; `bytes()` returns a zero-copy view. This is the lowest-overhead
+// path — what to use inside a tight WebSocket frame loop.
+
+const w = new Writer(1024);
+
+function sendTicker(t: Ticker, socket: { send(bytes: Uint8Array): void }): void {
+ w.reset();
+ Ticker.encodeInto(t, w);
+ socket.send(w.bytes());
+}
+
+const fakeSocket = {
+ send(bytes: Uint8Array): void {
+ log(` socket received ${bytes.length} bytes`);
+ },
+};
+
+log('\nExample 5: pooled writer hot path');
+sendTicker(ticker, fakeSocket);
+sendTicker({ ...ticker, last: 67900 }, fakeSocket);
+
+// ─── Example 6: router (framed multi-message protocol) ─────────────────────
+//
+// `router` prepends a 2-byte schema-ID frame on encode and dispatches on it on
+// decode. Use this when one socket carries many message types.
+
+const proto = router(Ticker, Book, Order, Event);
+
+const framedTicker = proto.encode(ticker, Ticker);
+const framedBook = proto.encode(book, Book);
+
+log('\nExample 6: router (framed)');
+log(` framed ticker: ${framedTicker.length}b (first 2 bytes = schema id)`);
+log(` framed book: ${framedBook.length}b`);
+
+const dispatched1 = proto.decode(framedTicker);
+const dispatched2 = proto.decode(framedBook);
+log(' dispatched ticker symbol:', (dispatched1 as Ticker).symbol);
+log(' dispatched book bids[0]:', (dispatched2 as typeof book).bids[0]);
diff --git a/serializer/test/api.test.ts b/serializer/test/api.test.ts
new file mode 100644
index 0000000..b5970fc
--- /dev/null
+++ b/serializer/test/api.test.ts
@@ -0,0 +1,161 @@
+import { test, expect } from 'vitest';
+import {
+ type,
+ oneOf,
+ router,
+ u53,
+ f64,
+ str,
+ bool,
+ list,
+ opt,
+ enumOf,
+ flags,
+ tuple,
+ f64Array,
+ clearRegistry,
+ Writer,
+ Reader,
+} from '../plugin/index.ts';
+
+test('type() — flat schema round-trip', () => {
+ clearRegistry();
+ const Ticker = type('Ticker', {
+ symbol: str,
+ last: f64,
+ volume: f64,
+ });
+
+ type Ticker = typeof Ticker.$infer;
+
+ const v: Ticker = { symbol: 'BTC-USD', last: 100.5, volume: 1234 };
+ const bytes = Ticker.encode(v);
+ expect(Ticker.decode(bytes)).toEqual(v);
+});
+
+test('type() — nested object via inline reference', () => {
+ clearRegistry();
+ const Price = type('Price', { value: f64, scale: u53 });
+ const Order = type('Order', {
+ id: u53,
+ price: Price,
+ qty: f64,
+ });
+
+ const v = { id: 42, price: { value: 100.5, scale: 2 }, qty: 0.5 };
+ expect(Order.decode(Order.encode(v))).toEqual(v);
+});
+
+test('type() — anonymous (no name) still works', () => {
+ clearRegistry();
+ const Anon = type({ x: u53, y: f64 });
+ const v = { x: 1, y: 2.5 };
+ expect(Anon.decode(Anon.encode(v))).toEqual(v);
+});
+
+test('list, opt, enumOf, flags, tuple — combinators', () => {
+ clearRegistry();
+ const T = type('Combo', {
+ tags: list(str),
+ maybe: opt(f64),
+ side: enumOf(['buy', 'sell'] as const),
+ f: flags(['ioc', 'post_only'] as const),
+ point: tuple(f64, f64),
+ });
+
+ const v = {
+ tags: ['a', 'b'],
+ maybe: 3.14,
+ side: 'buy' as const,
+ f: { ioc: true, post_only: false },
+ point: [1, 2] as [number, number],
+ };
+
+ expect(T.decode(T.encode(v))).toEqual(v);
+
+ const v2 = { ...v, maybe: undefined };
+ expect(T.decode(T.encode(v2))).toEqual(v2);
+});
+
+test('type() — typed array field', () => {
+ clearRegistry();
+ const Signal = type('Signal', { name: str, samples: f64Array });
+ const v = { name: 'x', samples: new Float64Array([1, 2, 3, 4]) };
+ const back = Signal.decode(Signal.encode(v));
+ expect(back.name).toBe('x');
+ expect(back.samples).toBeInstanceOf(Float64Array);
+ expect(Array.from(back.samples)).toEqual([1, 2, 3, 4]);
+});
+
+test('oneOf() — discriminated union', () => {
+ clearRegistry();
+ const Event = oneOf('Event', 'kind', {
+ fill: { price: f64, qty: f64 },
+ cancel: { reason: str },
+ });
+
+ const a = { kind: 'fill', price: 100, qty: 0.5 };
+ const b = { kind: 'cancel', reason: 'user' };
+ expect(Event.decode(Event.encode(a as never))).toEqual(a);
+ expect(Event.decode(Event.encode(b as never))).toEqual(b);
+});
+
+test('encodeInto / decodeFrom — pooled writer hot path', () => {
+ clearRegistry();
+ const T = type('Pooled', { x: u53, y: f64 });
+ const w = new Writer(256);
+
+ const v = { x: 42, y: 3.14 };
+
+ w.reset();
+ T.encodeInto(v, w);
+ const bytes = w.bytes();
+ expect(bytes.length).toBeGreaterThan(0);
+
+ const r = new Reader(bytes);
+ expect(T.decodeFrom(r)).toEqual(v);
+});
+
+test('router() — framed multi-type dispatch', () => {
+ clearRegistry();
+ const A = type('A', { x: u53 });
+ const B = type('B', { y: str });
+
+ const proto = router(A, B);
+
+ const bytesA = proto.encode({ x: 7 }, A);
+ const bytesB = proto.encode({ y: 'hi' }, B);
+
+ expect(proto.decode(bytesA)).toEqual({ x: 7 });
+ expect(proto.decode(bytesB)).toEqual({ y: 'hi' });
+});
+
+test('typeof T.$infer — TS inference works at compile time', () => {
+ clearRegistry();
+ const Order = type('OrderInf', {
+ id: u53,
+ price: f64,
+ side: enumOf(['buy', 'sell'] as const),
+ active: bool,
+ tags: list(str),
+ });
+
+ type Order = typeof Order.$infer;
+
+ const v: Order = {
+ id: 1,
+ price: 100,
+ side: 'buy',
+ active: true,
+ tags: ['a'],
+ };
+ expect(Order.decode(Order.encode(v))).toEqual(v);
+});
+
+test('codec id is deterministic by name', () => {
+ clearRegistry();
+ const A = type('Same', { x: u53 });
+ clearRegistry();
+ const B = type('Same', { y: f64 });
+ expect(A.id).toBe(B.id);
+});
diff --git a/serializer/test/bench/aot.bench.ts b/serializer/test/bench/aot.bench.ts
new file mode 100644
index 0000000..179a123
--- /dev/null
+++ b/serializer/test/bench/aot.bench.ts
@@ -0,0 +1,197 @@
+/**
+ * Compile-time (AOT) vs runtime codegen benchmark.
+ *
+ * The AOT codecs are produced by running our transformer on a sample TS file
+ * at bench startup, writing the result to a temp file, and importing it. The
+ * runtime codecs come from the regular `type(...)` runtime path.
+ */
+
+import { bench, beforeAll, afterAll, describe } from 'vitest';
+import { writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { transform } from '../../plugin/compile/transformer.ts';
+import {
+ type as runtimeType,
+ type TypeCodec,
+ u53,
+ f64,
+ str,
+ list,
+ enumOf,
+ flags,
+ clearRegistry,
+ Reader,
+ Writer,
+} from '../../plugin/index.ts';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const GEN_FILE = join(HERE, '__aot_codecs.ts');
+
+const AOT_SOURCE = `
+import { type, u53, f64, str, list, enumOf, flags } from '../../plugin/index.ts';
+
+export const Ticker = type('AotTicker', {
+ symbol: str,
+ last: f64,
+ bid: f64,
+ ask: f64,
+ volume: f64,
+});
+
+export const Order = type('AotOrder', {
+ id: u53,
+ account: u53,
+ symbol: str,
+ side: enumOf(['buy', 'sell'] as const),
+ price: f64,
+ qty: f64,
+ filledQty: f64,
+ ts: u53,
+ flags: flags(['ioc', 'post_only', 'reduce_only'] as const),
+});
+
+export const Level = type('AotLevel', { p: f64, q: f64 });
+
+export const Book = type('AotBook', {
+ symbol: str,
+ ts: u53,
+ bids: list(Level),
+ asks: list(Level),
+});
+`;
+
+interface AotCodec {
+ encode: (v: unknown, w?: Writer) => Uint8Array;
+ decode: (b: Uint8Array) => unknown;
+ encodeInto: (v: unknown, w: Writer) => void;
+ decodeFrom: (r: Reader) => unknown;
+ id: number;
+}
+
+let aot: Record;
+let rtTicker: TypeCodec;
+let rtOrder: TypeCodec;
+let rtLevel: TypeCodec;
+let rtBook: TypeCodec;
+
+const ticker = {
+ symbol: 'BTC-USD', last: 67891.23, bid: 67890.5, ask: 67892.0, volume: 1234567.89,
+};
+const order = {
+ id: 9876543210, account: 12345678, symbol: 'BTC-USD',
+ side: 'buy' as const, price: 67500.5, qty: 0.125, filledQty: 0,
+ ts: 1716100000123,
+ flags: { ioc: false, post_only: true, reduce_only: false },
+};
+const book = {
+ symbol: 'BTC-USD',
+ ts: 1716100000123,
+ bids: Array.from({ length: 1000 }, (_, i) => ({ p: 67890 - i * 0.5, q: 0.1 + (i % 100) * 0.01 })),
+ asks: Array.from({ length: 1000 }, (_, i) => ({ p: 67891 + i * 0.5, q: 0.1 + (i % 100) * 0.01 })),
+};
+
+const wT = new Writer(256);
+const wO = new Writer(256);
+const wB = new Writer(64 * 1024);
+
+let tickerAot: Uint8Array;
+let tickerRt: Uint8Array;
+let orderAot: Uint8Array;
+let orderRt: Uint8Array;
+let bookAot: Uint8Array;
+let bookRt: Uint8Array;
+
+beforeAll(async () => {
+ // Build the AOT module on the fly.
+ const transformed = transform(AOT_SOURCE, GEN_FILE, {
+ importPath: '../../plugin/index.ts',
+ packageAliases: ['../../plugin/index.ts'],
+ });
+ writeFileSync(GEN_FILE, transformed.code, 'utf8');
+ const url = `${pathToFileURL(GEN_FILE).href}?t=${Date.now()}`;
+ aot = (await import(/* @vite-ignore */ url)) as Record;
+
+ // Runtime equivalents with non-colliding names.
+ clearRegistry();
+ rtTicker = runtimeType('RtTicker', {
+ symbol: str, last: f64, bid: f64, ask: f64, volume: f64,
+ });
+ rtOrder = runtimeType('RtOrder', {
+ id: u53, account: u53, symbol: str,
+ side: enumOf(['buy', 'sell'] as const),
+ price: f64, qty: f64, filledQty: f64, ts: u53,
+ flags: flags(['ioc', 'post_only', 'reduce_only'] as const),
+ });
+ rtLevel = runtimeType('RtLevel', { p: f64, q: f64 });
+ rtBook = runtimeType('RtBook', {
+ symbol: str, ts: u53, bids: list(rtLevel), asks: list(rtLevel),
+ });
+
+ // Pre-encode for decode benches
+ tickerAot = aot.Ticker!.encode(ticker);
+ wT.reset(); rtTicker.encodeInto(ticker, wT); tickerRt = wT.bytes().slice();
+ orderAot = aot.Order!.encode(order);
+ wO.reset(); rtOrder.encodeInto(order, wO); orderRt = wO.bytes().slice();
+ bookAot = aot.Book!.encode(book);
+ wB.reset(); rtBook.encodeInto(book, wB); bookRt = wB.bytes().slice();
+});
+
+afterAll(() => {
+ if (existsSync(GEN_FILE)) rmSync(GEN_FILE, { force: true });
+});
+
+describe('encode ticker (AOT vs runtime)', () => {
+ bench('AOT (compiled)', () => {
+ wT.reset();
+ aot.Ticker!.encodeInto(ticker, wT);
+ });
+ bench('runtime (new Function)', () => {
+ wT.reset();
+ rtTicker.encodeInto(ticker, wT);
+ });
+});
+
+describe('encode order (AOT vs runtime)', () => {
+ bench('AOT (compiled)', () => {
+ wO.reset();
+ aot.Order!.encodeInto(order, wO);
+ });
+ bench('runtime', () => {
+ wO.reset();
+ rtOrder.encodeInto(order, wO);
+ });
+});
+
+describe('encode book 1000 levels (AOT vs runtime)', () => {
+ bench('AOT (compiled)', () => {
+ wB.reset();
+ aot.Book!.encodeInto(book, wB);
+ });
+ bench('runtime', () => {
+ wB.reset();
+ rtBook.encodeInto(book, wB);
+ });
+});
+
+describe('decode ticker (AOT vs runtime)', () => {
+ bench('AOT (compiled)', () => {
+ const r = new Reader(tickerAot);
+ aot.Ticker!.decodeFrom(r);
+ });
+ bench('runtime', () => {
+ const r = new Reader(tickerRt);
+ rtTicker.decodeFrom(r);
+ });
+});
+
+describe('decode book 1000 levels (AOT vs runtime)', () => {
+ bench('AOT (compiled)', () => {
+ const r = new Reader(bookAot);
+ aot.Book!.decodeFrom(r);
+ });
+ bench('runtime', () => {
+ const r = new Reader(bookRt);
+ rtBook.decodeFrom(r);
+ });
+});
diff --git a/serializer/test/bench/codec.bench.ts b/serializer/test/bench/codec.bench.ts
new file mode 100644
index 0000000..9a201c4
--- /dev/null
+++ b/serializer/test/bench/codec.bench.ts
@@ -0,0 +1,121 @@
+import { bench, describe } from 'vitest';
+import { Reader, Writer, deserialize, serialize } from '../../plugin/index.ts';
+import {
+ buildBook,
+ buildOrder,
+ buildTicker,
+ registerAll,
+} from './payloads.ts';
+
+const codecs = registerAll();
+
+const ticker = buildTicker();
+const order = buildOrder();
+const book = buildBook(1000);
+
+// Pre-allocated pooled Writers (sized generously so we don't measure grow()).
+const wTicker = new Writer(256);
+const wOrder = new Writer(256);
+const wBook = new Writer(64 * 1024);
+
+// Pre-encoded buffers for decode benches.
+const tickerJSON = JSON.stringify(ticker);
+const orderJSON = JSON.stringify(order);
+const bookJSON = JSON.stringify(book);
+
+const tickerBin = serialize(ticker, codecs.ticker);
+const orderBin = serialize(order, codecs.order);
+const bookBin = serialize(book, codecs.book);
+
+// One-time payload-size print on module load so it appears once in bench output.
+// eslint-disable-next-line no-console
+console.log(
+ '\n--- payload sizes ---\n' +
+ `ticker | json: ${tickerJSON.length}b bin: ${tickerBin.length}b (${((tickerBin.length / tickerJSON.length) * 100).toFixed(0)}%)\n` +
+ `order | json: ${orderJSON.length}b bin: ${orderBin.length}b (${((orderBin.length / orderJSON.length) * 100).toFixed(0)}%)\n` +
+ `book | json: ${bookJSON.length}b bin: ${bookBin.length}b (${((bookBin.length / bookJSON.length) * 100).toFixed(0)}%)\n`,
+);
+
+describe('encode ticker (5 fields)', () => {
+ bench('JSON.stringify', () => {
+ JSON.stringify(ticker);
+ });
+ bench('codec.encode (pooled)', () => {
+ wTicker.reset();
+ codecs.ticker.encode(wTicker, ticker);
+ });
+});
+
+describe('encode order (10 fields + bitset)', () => {
+ bench('JSON.stringify', () => {
+ JSON.stringify(order);
+ });
+ bench('codec.encode (pooled)', () => {
+ wOrder.reset();
+ codecs.order.encode(wOrder, order);
+ });
+});
+
+describe('encode book (1000 levels)', () => {
+ bench('JSON.stringify', () => {
+ JSON.stringify(book);
+ });
+ bench('codec.encode (pooled)', () => {
+ wBook.reset();
+ codecs.book.encode(wBook, book);
+ });
+});
+
+describe('decode ticker', () => {
+ bench('JSON.parse', () => {
+ JSON.parse(tickerJSON);
+ });
+ bench('codec.decode', () => {
+ const r = new Reader(tickerBin);
+ r.pos = 2;
+ codecs.ticker.decode(r);
+ });
+});
+
+describe('decode order', () => {
+ bench('JSON.parse', () => {
+ JSON.parse(orderJSON);
+ });
+ bench('codec.decode', () => {
+ const r = new Reader(orderBin);
+ r.pos = 2;
+ codecs.order.decode(r);
+ });
+});
+
+describe('decode book (1000 levels)', () => {
+ bench('JSON.parse', () => {
+ JSON.parse(bookJSON);
+ });
+ bench('codec.decode', () => {
+ const r = new Reader(bookBin);
+ r.pos = 2;
+ codecs.book.decode(r);
+ });
+});
+
+describe('roundtrip ticker', () => {
+ bench('JSON', () => {
+ JSON.parse(JSON.stringify(ticker));
+ });
+ bench('codec (pooled)', () => {
+ wTicker.reset();
+ codecs.ticker.encode(wTicker, ticker);
+ const r = new Reader(wTicker.bytes());
+ codecs.ticker.decode(r);
+ });
+});
+
+describe('serialize+deserialize ticker (with frame)', () => {
+ bench('JSON', () => {
+ JSON.parse(JSON.stringify(ticker));
+ });
+ bench('serialize/deserialize (framed)', () => {
+ deserialize(serialize(ticker, codecs.ticker));
+ });
+});
diff --git a/serializer/test/bench/payloads.ts b/serializer/test/bench/payloads.ts
new file mode 100644
index 0000000..7eab1f8
--- /dev/null
+++ b/serializer/test/bench/payloads.ts
@@ -0,0 +1,118 @@
+import { defineSchema, register, s } from '../../plugin/index.ts';
+import type { Codec } from '../../plugin/index.ts';
+
+export const TickerSchema = defineSchema('BenchTicker', (s) => ({
+ symbol: s.str,
+ last: s.f64,
+ bid: s.f64,
+ ask: s.f64,
+ volume: s.f64,
+}));
+
+export const OrderSchema = defineSchema('BenchOrder', (s) => ({
+ id: s.u53,
+ account: s.u53,
+ symbol: s.str,
+ side: s.enum(['buy', 'sell'] as const),
+ type: s.enum(['limit', 'market', 'stop', 'stop_limit'] as const),
+ price: s.f64,
+ qty: s.f64,
+ filledQty: s.f64,
+ ts: s.u53,
+ flags: s.bitset(['ioc', 'post_only', 'reduce_only'] as const),
+}));
+
+export const LevelSchema = defineSchema('BenchLevel', (s) => ({
+ p: s.f64,
+ q: s.f64,
+}));
+
+export const BookSchema = defineSchema('BenchBook', (s) => ({
+ symbol: s.str,
+ ts: s.u53,
+ bids: s.array(LevelSchema),
+ asks: s.array(LevelSchema),
+}));
+
+export interface Ticker {
+ symbol: string;
+ last: number;
+ bid: number;
+ ask: number;
+ volume: number;
+}
+
+export interface Order {
+ id: number;
+ account: number;
+ symbol: string;
+ side: 'buy' | 'sell';
+ type: 'limit' | 'market' | 'stop' | 'stop_limit';
+ price: number;
+ qty: number;
+ filledQty: number;
+ ts: number;
+ flags: { ioc: boolean; post_only: boolean; reduce_only: boolean };
+}
+
+export interface Level {
+ p: number;
+ q: number;
+}
+
+export interface Book {
+ symbol: string;
+ ts: number;
+ bids: Level[];
+ asks: Level[];
+}
+
+export function buildTicker(): Ticker {
+ return {
+ symbol: 'BTC-USD',
+ last: 67891.23,
+ bid: 67890.5,
+ ask: 67892.0,
+ volume: 1234567.89,
+ };
+}
+
+export function buildOrder(): Order {
+ return {
+ id: 9876543210,
+ account: 12345678,
+ symbol: 'BTC-USD',
+ side: 'buy',
+ type: 'limit',
+ price: 67500.5,
+ qty: 0.125,
+ filledQty: 0,
+ ts: 1716100000123,
+ flags: { ioc: false, post_only: true, reduce_only: false },
+ };
+}
+
+export function buildBook(depth: number): Book {
+ const bids: Level[] = new Array(depth);
+ const asks: Level[] = new Array(depth);
+ for (let i = 0; i < depth; i++) {
+ bids[i] = { p: 67890 - i * 0.5, q: 0.1 + (i % 100) * 0.01 };
+ asks[i] = { p: 67891 + i * 0.5, q: 0.1 + (i % 100) * 0.01 };
+ }
+ return { symbol: 'BTC-USD', ts: 1716100000123, bids, asks };
+}
+
+export interface Codecs {
+ ticker: Codec;
+ order: Codec;
+ level: Codec;
+ book: Codec;
+}
+
+export function registerAll(): Codecs {
+ const ticker = register(TickerSchema);
+ const order = register(OrderSchema);
+ const level = register(LevelSchema);
+ const book = register(BookSchema);
+ return { ticker, order, level, book };
+}
diff --git a/serializer/test/bench/results.md b/serializer/test/bench/results.md
new file mode 100644
index 0000000..c18d6b0
--- /dev/null
+++ b/serializer/test/bench/results.md
@@ -0,0 +1,117 @@
+# Benchmark results
+
+Hardware: Intel Xeon (Icelake) @ 2.46 GHz, Windows Server 2019
+Runtime: Node.js 24.14.0 (x64)
+Tool: mitata
+Date: 2026-05-21
+
+Reproduce: `npm run bench` from the `serializer/` directory. Numbers below use the avg (the p75 column where they diverge).
+
+## Payload sizes
+
+| Workload | JSON bytes | Binary bytes | Binary/JSON ratio |
+|---|---:|---:|---:|
+| Ticker (5 fields) | 82 | 42 | **0.51** |
+| Order (10 fields + bitset) | 203 | 52 | **0.26** |
+| Book snapshot (1000 levels) | 48,577 | 32,020 | **0.66** |
+
+## Encode (lower is better)
+
+| Workload | JSON.stringify | codec.encode (pooled) | Speedup vs JSON |
+|---|---:|---:|---:|
+| Ticker | 598.4 ns | **52.2 ns** | **11.5×** |
+| Order | 1,170 ns | **123.4 ns** | **9.5×** |
+| Book (1000 levels) | 437 µs | **10.2 µs** | **42.9×** |
+
+## Decode (lower is better)
+
+| Workload | JSON.parse | codec.decode | Speedup vs JSON |
+|---|---:|---:|---:|
+| Ticker | 696.3 ns | **311.0 ns** | **2.2×** |
+| Order | 1,440 ns | **360.6 ns** | **4.0×** |
+| Book (1000 levels) | 497 µs | **24–28 µs** (high GC variance) | **17–20×** |
+
+## Roundtrip
+
+| | ns/iter | Note |
+|---|---:|---|
+| `JSON.parse(JSON.stringify(...))` | 1,400 ns | baseline |
+| Pooled codec encode + Reader decode | **418 ns** | **3.35× faster** |
+| Un-pooled `serialize` + `deserialize` (framed) | 2,180 ns | 1.55× slower |
+
+The un-pooled `serialize()` allocates a fresh Writer + DataView + Uint8Array on every call. Hot paths must pool a Writer.
+
+## What changed vs v1 baseline
+
+The v1 codec used method-call style for every operation: every `w.f64(v)` was a method dispatch with internal property reads on `this.buf`, `this.view`, `this.pos`. The optimized codec restructures the generated functions around four V8-friendly patterns:
+
+| # | Optimization | Effect |
+|---|---|---|
+| 1 | Lift `pos`, `buf`, `view` to function-local `let/const` at start; sync `w.pos = pos` at end | Replaces N×3 property loads with N register reads |
+| 2 | Inline all bounded-size ops (`u8`–`f64`, `bool`, varints, `enum`, `bitset`) using the lifted locals | Eliminates the method-call cost per primitive |
+| 3 | Pre-`ensure` for the bounded prefix of each schema in a single bounds check | One growth check per ~10 fields instead of one per field |
+| 4 | Inline nested objects/arrays/unions/tuples — no per-element function dispatch | Tight inner loops for array