Install

npm install @jsondelta/patch

Usage

import { patch, invert } from '@jsondelta/patch'

const doc = { name: 'alice', role: 'viewer', tags: ['staff'] }
const delta = [
  { op: 'replace', path: ['role'], old: 'viewer', new: 'admin' },
  { op: 'add', path: ['tags', 1], value: 'elevated' }
]

const updated = patch(doc, delta)
// { name: 'alice', role: 'admin', tags: ['staff', 'elevated'] }

const undone = patch(updated, invert(delta))
// { name: 'alice', role: 'viewer', tags: ['staff'] }

The default import selects the fastest available backend: WebAssembly or pure JS fallback. You can also import a specific backend directly:

import { patch, invert } from '@jsondelta/patch/fallback'
import { patch, invert } from '@jsondelta/patch/wasm'

Real-world examples

Undo/redo in a collaborative editor

import { diff } from '@jsondelta/diff'
import { patch, invert } from '@jsondelta/patch'

const undoStack = []

function applyEdit(doc, newDoc) {
  const delta = diff(doc, newDoc)
  undoStack.push(delta)
  return newDoc
}

function undo(doc) {
  const delta = undoStack.pop()
  return patch(doc, invert(delta))
}

let doc = { title: 'Draft', body: 'Hello' }
doc = applyEdit(doc, { title: 'Draft', body: 'Hello world' })
doc = applyEdit(doc, { title: 'Final', body: 'Hello world' })
doc = undo(doc)
// { title: 'Draft', body: 'Hello world' }

Applying configuration patches from a remote source

import { patch } from '@jsondelta/patch'

const baseConfig = JSON.parse(fs.readFileSync('config.json', 'utf8'))
const envPatch = await fetch('/api/config-patches/production').then(r => r.json())

const config = patch(baseConfig, envPatch)

API

patch(doc, delta)

Apply a delta to a document, returning the patched result. The original document is not mutated.

• doc - any JSON-compatible value
• delta - array of operations from @jsondelta/diff
• Returns the patched document

invert(delta)

Reverse a delta so that applying the inverted delta undoes the original patch. Operations are flipped (add becomes remove, remove becomes add, replace swaps old and new) and the order is reversed.

• delta - array of operations from @jsondelta/diff
• Returns the inverted delta

How it works

The patch engine is written in Zig and compiled to WebAssembly (73KB). It parses the document and delta, groups operations by path segment, and recursively rebuilds the document with changes applied. This grouping approach correctly handles all delta shapes from @jsondelta/diff, including multiple array removals.

The pure JS fallback implements the same algorithm for environments where WebAssembly is not available.

Architecture:

1. WebAssembly - Zig compiled to wasm32-freestanding. Near-native speed, runs in Node.js and browsers
2. Pure JS fallback - Zero-dependency, always works. Same algorithm, same output

License

MIT