patch-db/CLAUDE.md

CLAUDE.md

patch-db is a JSON Patch–based database with a Rust backend and TypeScript client.

Where to look

Need	File
What this project is, quick start examples	README.md
Project structure, crate details, data flow, storage format, concurrency	ARCHITECTURE.md
Build commands, testing, code style, making changes	CONTRIBUTING.md

Key files

Area	Path
Core API	core/src/store.rs — PatchDb, TypedPatchDb, Store, MutateResult
Types	core/src/patch.rs — Revision, Dump, DiffPatch, diff()
Subscriptions	core/src/subscriber.rs — DbWatch, TypedDbWatch, Subscriber, Broadcast
Model system	core/src/model.rs — HasModel, Model, ModelExt, Pointer
Derive macro	macro-internals/src/lib.rs — HasModel derive implementation
Error types	core/src/lib.rs — Error enum, re-exports
JSON Pointer	json-ptr/src/lib.rs — JsonPointer, ROOT, path navigation
JSON Patch	json-patch/src/lib.rs — Patch, PatchOperation, diff(), patch()
TS client	client/lib/patch-db.ts — PatchDB<T> class
TS patch lib	client/lib/json-patch-lib.ts — client-side patch application
TS types	client/lib/types.ts — Revision, Dump, Update, PatchOp

Operating rules

• Wire format — Rust and TS define Revision, Dump, and patch operations independently. Changes to one side must be mirrored in the other. See the cross-layer section in CONTRIBUTING.md.
• Patch operations — Only add, remove, and replace are used. The TS client does not implement test, move, or copy.
• Immutable patch application — The TS client applies patches by shallow-copying objects/arrays, not mutating in place. This is intentional for UI framework change detection.
• HasModel derive — Respects serde attributes (rename_all, rename, flatten, tag, content). Generated accessors follow the pattern as_<field>(), as_<field>_mut(), into_<field>().
• Error handling — Rust uses thiserror with the Error enum in core/src/lib.rs. TS does not have formal error types.