@console-one/wire

Two closely-related serialization tools in one package, zero dependencies:

1. StructCodec — a dictionary-based compression codec for repetitive object graphs. First occurrence of a value is a literal; subsequent near-duplicates encode as ref or delta against the dict.
2. WireRegistry — an adapter-driven bundler for serializing heterogeneous object graphs with stable keys and dependency edges. Bundle a root; get a { roots, table } graph where each node has a content-addressable key and explicit deps.
3. HoistCompilerBuilder — a code generator that walks an object graph, decides which nodes are "simple enough to inline" and which should be hoisted into named bindings, and emits them grouped by bucket (e.g. types, helpers, handlers).

All three share a philosophy: separate transport/codegen from validation. Where libraries like Zod or JSON Schema use one schema to both describe data and validate it, wire treats "how to serialize" and "how to codegen" as distinct adapter contracts. You write a NodeAdapter or a HoistHandler that says "here's how to match this kind of node, here's how to turn it into JSON / inline it / hoist it, here's how to undo that" — and the same graph can be bundled for transport, compressed via delta, or code-generated into emitted source.

Install

npm install @console-one/wire

StructCodec — dictionary compression with delta encoding

import { StructCodec } from '@console-one/wire'

const codec = new StructCodec()

// First time: literal
codec.encode({ x: 1, y: 2 })
// → { v: { x: 1, y: 2 } }

// Identical repeat: numeric ref
codec.encode({ x: 1, y: 2 })
// → 0  (dict index)

// Near-duplicate: delta against the closest dict entry
codec.encode({ x: 1, y: 2, z: 3 })
// → { b: 0, d: { s: [[ 'z', { v: 3 } ]] } }

// Decode reconstructs exact values
const back = codec.decode(0)  // → { x: 1, y: 2 }

Four encoded forms, unambiguously distinguishable by shape:

• REF (number) — exact match at dict[n]
• DELTA ({ b, d }) — like dict[b], except for the Diff
• LITERAL ({ v }) — raw value, no compression
• NESTED ({ nd }) — recursive diff applied to a corresponding base field

Snapshots are serializable via codec.snapshot() / StructCodec.restore(snapshot).

Standalone tree compaction

For one-shot compression (no codec instance needed):

import { compactTree, expandTree } from '@console-one/wire'

const data = { users: [
  { role: 'admin', perms: ['read', 'write'] },
  { role: 'admin', perms: ['read', 'write'] },
  { role: 'user', perms: ['read'] }
] }

const compacted = compactTree(data)
// → { v: 1, dict: [...], root: ... }   // duplicate objects interned in dict

const back = expandTree(compacted)
// deep-equal to `data`

WireRegistry — bundle an object graph

import { WireRegistry, NodeAdapter } from '@console-one/wire'

type Name = { kind: 'name'; id: string; value: string }
type Var  = { kind: 'var';  id: string; name: Name }

const nameAdapter: NodeAdapter<Name> = {
  type: 'name',
  matches: (x): x is Name => x?.kind === 'name',
  key: n => n.id,
  toJSON:   (n) => ({ value: n.value }),
  fromJSON: (d) => ({ kind: 'name', id: '', value: d.value })
}

const varAdapter: NodeAdapter<Var> = {
  type: 'var',
  matches: (x): x is Var => x?.kind === 'var',
  key: v => v.id,
  deps: v => [v.name],
  toJSON:   (v, ref) => ({ name: ref(v.name) }),
  fromJSON: (d, get)  => ({ kind: 'var', id: '', name: get(d.name.$ref) })
}

const registry = new WireRegistry([nameAdapter, varAdapter])

const v: Var = { kind: 'var', id: 'v1', name: { kind: 'name', id: 'n1', value: 'alpha' } }
const bundle = registry.bundle([v])
// → { version: 1, roots: ['v1'], table: { v1: {...}, n1: {...} } }

const [restored] = registry.unbundle(bundle)
// restored === { kind: 'var', id: '', name: { kind: 'name', id: '', value: 'alpha' } }

Key properties:

• Content-addressable keys — if NodeAdapter.key is omitted, the key is ${type}:${djb2(JSON.stringify(node))}, giving structural dedup for free.
• Explicit dep edges — toJSON(node, ref) uses the ref(child) callback to register a child; deps are recorded so unbundle can respect topological order.
• Cycle-safe — unbundle makes forward progress as long as a node's deps are resolved, and force-decodes one node at a time if a cycle is detected.

HoistCompilerBuilder — code generation with hoisting

Turn an expression-tree-ish object graph into generated source where trivial nodes inline and heavy ones are lifted to named bindings, grouped into buckets:

import { HoistCompilerBuilder } from '@console-one/wire'

const compiler = new HoistCompilerBuilder()
  .add({
    type: 'lit',
    matches: (x): x is { kind: 'lit'; v: number } => x?.kind === 'lit',
    key: e => `lit:${e.v}`,
    deps: () => [],
    isSimple: () => true,
    renderInline: e => String(e.v),
    renderHoisted: () => ({ body: '' })
  })
  .add({
    type: 'add',
    matches: (x): x is { kind: 'add'; l: any; r: any } => x?.kind === 'add',
    key: e => `add:${JSON.stringify(e)}`,
    classify: () => 'expr',
    deps: e => [e.l, e.r],
    isSimple: () => false,
    renderInline: () => '',
    renderHoisted: (e, tryCompile) => ({
      body: `${tryCompile(e.l)} + ${tryCompile(e.r)}`,
      bucket: 'expr'
    })
  })
  .build()

const expr = { kind: 'add', l: { kind: 'lit', v: 2 }, r: { kind: 'lit', v: 3 } }
const result = compiler.compileAll([expr])
// → { sections: { expr: [{ key: 'add:...', name: 'E_xxxxx', body: '2 + 3', ... }] }, body: '...' }

const source = compiler.emit(result)
// rendered source with sections concatenated

A HoistHandler decides:

• Structural dedup via key / id
• Inline vs hoist via isSimple
• How to refer to a hoisted binding via refName
• Which bucket a hoisted node belongs to via classify

Public surface

From @console-one/wire:

Codec

• StructCodec — encode / decode / snapshot / restore
• compactTree(value) / expandTree(compacted)
• Types: Diff, Encoded, EncodedRef, EncodedDelta, EncodedLit, EncodedNested, CodecSnapshot, CompactedTree

Bundler

• WireRegistry — bundle(roots) / unbundle(bundle)
• djb2(s) — stable string hash used for default content addressing
• Types: WireRecord, WireBundle, NodeAdapter<T>

Compiler

• HoistCompilerBuilder — .add(handler).build(opts) → { tryCompile, compileAll, emit }
• Types: TryCompile, HoistedNode, CompileSections, CompileResult, HoistHandler<T>, NodeHandler<T>, CompilerOptions

Layout

src/
├── index.ts        # Public surface
├── smoke.ts        # End-to-end smoke test
├── codec.ts        # StructCodec, compactTree/expandTree
├── registry.ts     # WireRegistry, djb2
├── nodeadaptor.ts  # NodeAdapter<T> type
└── compiler.ts     # HoistCompilerBuilder

Zero runtime dependencies. TypeScript-first with full .d.ts emit.

Smoke test

npm install
npm run build
npm run smoke

Asserts six end-to-end paths:

1. Ref compression — repeated structure compresses to a numeric ref; decode reconstructs exactly.
2. Delta encoding — similar-but-different structure compresses as a delta or nested form (not a full literal re-emit).
3. Tree compaction — compactTree → expandTree round-trips deep-equal.
4. Bundler — typed object graph serializes and deserializes through NodeAdapters with deps preserved.
5. Hash determinism — djb2 is stable and discriminates.
6. Compiler — HoistCompilerBuilder hoists non-simple nodes into buckets and inlines the simple ones.

License

MIT