Frontier Codec

Patch serialization, binary frames, and patch-history codecs for Frontier.

This package sits above @shapeshift-labs/frontier, the small JSON diff/apply core package. It keeps transport, persistence, and canonicalization helpers in a separate package so core imports stay small and predictable.

• npm: @shapeshift-labs/frontier-codec
• source: siliconjungle/-shapeshift-labs-frontier-codec
• license: MIT

Related Packages

• @shapeshift-labs/frontier: core JSON diff/apply primitives used by this package.
• @shapeshift-labs/frontier-engine: planned diff engine and history helpers that use this package for encoded histories.
• @shapeshift-labs/frontier-query: shared query-key, selector path, condition, identity, and table-schema primitives.
• @shapeshift-labs/frontier-mutation: explicit mutation and selector plans compiled to Frontier patches or CRDT operations.

Package source repositories:

• siliconjungle/-shapeshift-labs-frontier
• siliconjungle/-shapeshift-labs-frontier-engine
• siliconjungle/-shapeshift-labs-frontier-query
• siliconjungle/-shapeshift-labs-frontier-mutation

Install

npm install @shapeshift-labs/frontier @shapeshift-labs/frontier-codec

Usage

import { diff, applyPatchImmutable } from '@shapeshift-labs/frontier';
import { encodePatch, decodePatch } from '@shapeshift-labs/frontier-codec';

const before = { count: 1 };
const after = { count: 2 };

const patch = diff(before, after);
const bytes = encodePatch(patch);
const decoded = decodePatch(bytes);

console.log(applyPatchImmutable(before, decoded));

API

import {
  serializePatch,
  deserializePatch,
  encodePatch,
  decodePatch,
  encodePatchBase64url,
  decodePatchBase64url,
  encodePatchHistory,
  decodePatchHistory,
  applyPatchHistory,
  applyEncodedPatchHistory,
  createPatchHistoryBuilder,
  createCodecSchemaId,
  encodePatchFrame,
  decodePatchFrame,
  encodePatchHistoryFrame,
  decodePatchHistoryFrame,
  inspectCodecFrame,
  readCodecFramePayload,
  stringifyCanonicalJson,
  encodeCanonicalJson
} from '@shapeshift-labs/frontier-codec';

What It Provides

Frontier Codec is for moving Frontier patches across process, network, and storage boundaries:

• serializePatch() / deserializePatch() for compact JSON-safe patch payloads.
• encodePatch() / decodePatch() for binary patch payloads.
• encodePatchBase64url() / decodePatchBase64url() for URL/header-safe transport strings.
• encodePatchHistory() / decodePatchHistory() for compact patch-history persistence.
• applyPatchHistory() / applyEncodedPatchHistory() for replaying stored histories.
• createPatchHistoryBuilder() for incremental history assembly.
• encodePatchFrame() / decodePatchFrame() for versioned typed wire frames.
• inspectCodecFrame() / readCodecFramePayload() for metadata-first frame handling.
• stringifyCanonicalJson() / encodeCanonicalJson() for deterministic signing, hashing, and cache keys.

Binary Patch Transport

import { diff, applyPatchImmutable } from '@shapeshift-labs/frontier';
import { encodePatchBase64url, decodePatchBase64url } from '@shapeshift-labs/frontier-codec';

const patch = diff({ title: 'Draft' }, { title: 'Published' });
const token = encodePatchBase64url(patch);

const received = decodePatchBase64url(token);
const next = applyPatchImmutable({ title: 'Draft' }, received);

Patch History

import { applyEncodedPatchHistory, encodePatchHistory } from '@shapeshift-labs/frontier-codec';

const encoded = encodePatchHistory([
  [{ op: 'add', path: ['items'], value: [] }],
  [{ op: 'add', path: ['items', 0], value: { id: 'a', done: false } }]
]);

const current = applyEncodedPatchHistory({}, encoded);

Versioned Frames

import { encodePatchFrame, inspectCodecFrame, readCodecFramePayload } from '@shapeshift-labs/frontier-codec';

const frame = encodePatchFrame([{ op: 'replace', path: ['count'], value: 2 }], {
  schemaId: 'counter-v1'
});

const info = inspectCodecFrame(frame);
const bytes = readCodecFramePayload(frame);

Canonical JSON

import { stringifyCanonicalJson } from '@shapeshift-labs/frontier-codec/canonical';

const stable = stringifyCanonicalJson({ b: 2, a: 1 });
// {"a":1,"b":2}

Subpath Imports

import { encodePatch } from '@shapeshift-labs/frontier-codec/codec';
import { encodePatchHistory } from '@shapeshift-labs/frontier-codec/history';
import { encodePatchFrame } from '@shapeshift-labs/frontier-codec/frame';
import { stringifyCanonicalJson } from '@shapeshift-labs/frontier-codec/canonical';
import type { PatchHistoryCodecOptions } from '@shapeshift-labs/frontier-codec/types';

Package Scope

This package is intentionally limited to:

• Frontier patch string and binary codecs.
• Base64url patch transport helpers.
• Patch-history encoding and replay.
• Versioned codec frames.
• Canonical JSON helpers for transport, hashing, and signing workflows.

CRDT update codecs live in the CRDT package layer. State routing, sync providers, awareness, rich text, and document handles are separate layers.

TypeScript

The package ships ESM JavaScript plus .d.ts declarations for every public subpath. The package-local TypeScript source lives in src/ and compiles directly to dist/; it is not copied from the monorepo root build output.

Validation

The package test suite covers:

• smoke imports for every public subpath;
• type-checking examples against the published declarations;
• deterministic patch/history/frame/canonical conformance cases;
• index-list binary codec fuzzing;
• patch/history/frame round-trip fuzzing against @shapeshift-labs/frontier diff/apply.

Run it with:

npm test

Run the package-local fuzzer directly:

npm run fuzz

For a publish dry run:

npm run pack:dry

Benchmarks

Run the package-local benchmark:

npm run bench

Latest local package benchmark on Node v26.1.0, darwin arm64, 3 rounds:

| Fixture | Median | p95 | | --- | ---: | ---: | | Patch encode, 1k keyed-row edit, 30 B | 0.61 us | 0.66 us | | Patch decode, 1k keyed-row edit, 30 B | 0.36 us | 0.43 us | | Frame inspect + payload slice, 70 B | 0.40 us | 0.42 us | | Frame decode, 1k keyed-row edit, 70 B | 0.59 us | 0.62 us | | History decode+apply, 128 patches, 2.8 KiB | 56.11 us | 56.47 us | | Canonical JSON stringify, 523 B | 6.34 us | 6.49 us |

These are Frontier-only package measurements, not competitor comparisons.

License

MIT. See LICENSE.