@maxjay/patchwork/angular wraps an Engine in a reactive store built on Angular Signals (Angular 16+). All reads are exposed as Signals; all mutations fire those signals, so templates, computeds, and effects update automatically — no ChangeDetectorRef, no NgZone.
@angular/core is a peer dependency. The adapter ships with patchwork.
npm install @maxjay/patchwork @angular/coreThe peer dep is optional — install patchwork without Angular if you only use the core engine. The adapter only loads if you import from @maxjay/patchwork/angular.
import{createPatchworkStore}from'@maxjay/patchwork/angular';
@Component({template: ` <input [value]="port()" (input)="setPort($event)"> <button (click)="store.accept()" [disabled]="!diff().length">Save</button> <button (click)="store.decline()" [disabled]="!diff().length">Discard</button> `,})classServerSettings{store=createPatchworkStore({server: {port: 8080}});port=this.store.getValue<number>('$.server.port');diff=this.store.diff();setPort(e: Event){this.store.replace('$.server.port',+(e.targetasHTMLInputElement).value);}}Wraps a new Engine in a reactive store.
conststore=createPatchworkStore<MyConfig>(initialDoc,{ schema });Wraps an existing Engine. Useful when the engine is created elsewhere — e.g., shared with non-Angular code, hydrated from a snapshot.
constengine=newEngine(initial);conststore=fromEngine(engine);| Method | Returns | Source |
|---|---|---|
store.draft | Signal<T> | whole draft |
store.base | Signal<T> | whole base |
store.get<U>(path) | Signal<Array<{path, value: U}>> | draft, JSONPath query |
store.getBase<U>(path) | Signal<Array<{path, value: U}>> | base, JSONPath query |
store.getValue<U>(path) | Signal<U> | draft, strict single-match |
store.getValueBase<U>(path) | Signal<U> | base, strict single-match |
store.diff(path?, options?) | Signal<DiffOp[]> | structural diff — options: key, includeUnchanged, cascade |
The <U> type parameter is optional and defaults to JsonValue. Declare it to get a typed signal without a cast:
// Without generic — requires a cast at the call siteitems=this.store.getValue('$.items')asSignal<Item[]>;// With generic — typed directlyitems=this.store.getValue<Item[]>('$.items');groups=this.store.getValue<Group[]>('$.groups');members=this.store.getValue<Member[]>('$.members');This works the same way for get<U>, getBase<U>, and getValueBase<U>.
Methods that take args (everything except draft/base) return a newSignal on each call. Assign once to a class field — don't call them in a template hot path. This is the same pattern as Angular's own computed().
// ✅ Right — created onceport=this.store.getValue<number>('$.server.port');// ❌ Wrong — new Signal per change-detection cycle
template: `{{ store.getValue('$.server.port')() }}`add, replace, delete, move, copy, revert — same signatures as Engine. Each fires the draft signal.
restore(op) — inverts a DiffOp from diff() and pushes it onto the undo stack. Fires the draft signal.
undo, redo — fire both draft and base signals.
accept — promotes draft to base, fires the base signal. decline — resets draft from base, fires the draft signal.
store.beginEphemeral(), store.commitEphemeral(), store.discardEphemeral() — same semantics as Engine. Only available on root stores — scope() returns a store that throws on these. Use the root store for ephemeral.
Sub-store rooted at a subtree. Shares the parent's signal ticks — mutations through either side update both. Use to scope a component or feature module to a slice of the document without losing reactivity.
constnetwork=store.scope<NetworkConfig>('$.network');network.replace('$.timeout',5000);// store.draft().network.timeout === 5000 toonetwork.accept() commits the network subtree only — the rest of base stays put. network.diff() is automatically scoped to that subtree.
Escape hatch. Returns the underlying Engine or NodeEngine. Use for anything not surfaced through the store — but going around the store skips signal updates.
diff doubles as both a "has unsaved changes" indicator and a per-row state source. With identity-keyed diffing, the identity field on add/remove ops tells you exactly which item was affected — no path parsing required:
@Component({template: ` @for (item of items(); track item.id) { <div [class]="stateOf(item.id)">{{ item.name }}</div> } <button (click)="store.accept()" [disabled]="!diff().length">Save</button> <button (click)="store.decline()" [disabled]="!diff().length">Discard</button> `,})classItemList{store=createPatchworkStore<any>({items: [...]},{schema: {type: 'object',properties: {items: {type: 'array','x-key': 'id',items: {type: 'object'}},},},},);items=this.store.getValue<Item[]>('$.items');diff=this.store.diff('$.items');stateOf(id: string): string{constops=this.diff();if(ops.some(o=>o.op==='add'&&o.identity===id))return'added';if(ops.some(o=>o.op==='remove'&&o.identity===id))return'removed';if(ops.some(o=>o.op==='replace'&&o.identity===id))return'modified';if(ops.some(o=>o.op==='move'&&o.identity===id))return'displaced';return'unchanged';}}Bind input changes live but collapse to one undo entry on blur:
@Component({template: `<input [value]="port()" (focus)="store.beginEphemeral()" (input)="onInput($event)" (blur)="store.commitEphemeral()" >`,})classPortField{store=createPatchworkStore({port: 8080});port=this.store.getValue<number>('$.port');onInput(e: Event){this.store.replace('$.port',+(e.targetasHTMLInputElement).value);}}One undo() snaps the field back to the value it had on focus. discardEphemeral() cancels instead — unwinds all session mutations with no history trace.
diff doubles as a "has unsaved changes" indicator:
hasChanges=computed(()=>this.store.diff()().length>0);Or directly in the template:
<button(click)="store.accept()" [disabled]="!diff().length">Save</button>Put the store on a service:
@Injectable({providedIn: 'root'})classConfigStore{privateinner=createPatchworkStore<Config>(getInitial());readonlydraft=this.inner.draft;readonlydiff=this.inner.diff();add(...args: Parameters<typeofthis.inner.add>){this.inner.add(...args);}replace(...args: Parameters<typeofthis.inner.replace>){this.inner.replace(...args);}accept(){this.inner.accept();}decline(){this.inner.decline();}}Any component that injects ConfigStore and reads its signals participates in the same reactive document.
Use scope() to give a feature module its own store view without wiring the full document:
@Injectable()classNetworkSettingsStore{privateroot=inject(ConfigStore).inner;readonlystore=this.root.scope<NetworkConfig>('$.network');readonlytimeout=this.store.getValue<number>('$.timeout');readonlydiff=this.store.diff();}Mutations through NetworkSettingsStore are visible on the root store's signals, and vice versa. store.accept() commits only the network subtree.
The store updates engine state in-place (no structuredClone per mutation) and uses equal: () => false on its internal tick signals to force propagation regardless of reference equality. This keeps the hot path cheap — mutating 100 fields doesn't allocate 100 cloned documents — while keeping signal semantics correct.
If you read engine.draft directly (without going through the store), you get the same reference the store holds. Don't mutate it through the engine after that — the store's signal won't fire and the UI will desync. Always go through the store for writes.