`@arcanejs/diff`

Typed JSON diff/patch utilities used by ArcaneJS to synchronize state efficiently.

@arcanejs/diff provides:

diffJson(a, b) to compute structural differences
patchJson(old, diff) to apply a diff and reconstruct the new value
Type-level diff contracts (Diff<T>, NestedDiff<T>, JSONValue, etc.)

Install

npm install @arcanejs/diff

API

`diffJson(a, b)`

Compares two JSON-compatible values and returns a typed diff.

Possible diff forms:

{ type: 'match' }
{ type: 'value', after } for primitive/type changes
{ type: 'splice', start, count, items } for array length changes
{ type: 'modified-a', changes } for same-length array item updates
{ type: 'modified-o', additions?, deletions?, changes? } for object updates

`patchJson(old, diff)`

Applies a diff to a previous value and returns the patched result.

Patch behavior is immutable (returns new arrays/objects where needed).

Usage

import { diffJson, patchJson, type Diff } from '@arcanejs/diff';

type Model = {
  name: string;
  values: number[];
};

const previous: Model = { name: 'A', values: [1, 2, 3] };
const next: Model = { name: 'B', values: [1, 4, 3, 5] };

const diff: Diff<Model> = diffJson(previous, next);
const reconstructed = patchJson(previous, diff);

console.log(reconstructed); // { name: 'B', values: [1, 4, 3, 5] }

Type Safety

Diff<T> is parameterized on the JSON value type, so diffs and patch operations remain tied to the expected shape.

Error Cases

patchJson throws when diff/value kinds are incompatible, for example:

applying splice to non-arrays
applying modified-o to non-objects

ArcaneJS Usage

ArcaneJS server tracks the last tree sent to each client and sends tree-diff updates computed with diffJson; browser stage reconstructs latest tree with patchJson.

Relevant references: