@jsondelta/patch

Zig-powered JSON patch application and delta inversion. Apply diffs, undo changes, roundtrip losslessly.

Install

npm install @jsondelta/patch

Usage

import{patch,invert}from'@jsondelta/patch'constdoc={name: 'alice',role: 'viewer',tags: ['staff']}constdelta=[{op: 'replace',path: ['role'],old: 'viewer',new: 'admin'},{op: 'add',path: ['tags',1],value: 'elevated'}]constupdated=patch(doc,delta)// { name: 'alice', role: 'admin', tags: ['staff', 'elevated'] }constundone=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'constundoStack=[]functionapplyEdit(doc,newDoc){constdelta=diff(doc,newDoc)undoStack.push(delta)returnnewDoc}functionundo(doc){constdelta=undoStack.pop()returnpatch(doc,invert(delta))}letdoc={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'constbaseConfig=JSON.parse(fs.readFileSync('config.json','utf8'))constenvPatch=awaitfetch('/api/config-patches/production').then(r=>r.json())constconfig=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