@typicalday/firegraph 0.11.1 → 0.12.0

package/README.md

@@ -101,16 +101,19 @@ const g = createGraphClient(db, 'graph', { registry });
 ```typescript
 const tourId = generateId();
 
-// Create or overwrite a node
+// Create or deep-merge a node (sibling keys at any depth survive)
 await g.putNode('tour', tourId, { name: 'Dolomites Classic' });
 
 // Read a node
 const node = await g.getNode(tourId);
 // → StoredGraphRecord | null
 
-// Update fields (partial merge into data)
+// Partial update (deep merge into data)
 await g.updateNode(tourId, { difficulty: 'extreme' });
 
+// Full replace — discards every prior key not in the new payload
+await g.replaceNode('tour', tourId, { name: 'Dolomites — 2026 Edition' });
+
 // Delete a node
 await g.removeNode(tourId);
 
@@ -118,12 +121,19 @@ await g.removeNode(tourId);
 const tours = await g.findNodes({ aType: 'tour' });
 ```
 
+**Write semantics (0.12+):** `putNode`/`putEdge` and `updateNode`/`updateEdge`
+**deep-merge** by default — sibling keys at every nesting depth survive. Use
+`replaceNode`/`replaceEdge` when you want the old "wipe and rewrite" behaviour.
+Arrays are terminal (replaced wholesale, not element-merged); `undefined`
+values are skipped; `null` is preserved verbatim; and the
+[`deleteField()`](#field-deletion) sentinel removes a field at any depth.
+
 ### Edges
 
 ```typescript
 const depId = generateId();
 
-// Create or overwrite an edge
+// Create or deep-merge an edge
 await g.putEdge('tour', tourId, 'hasDeparture', 'departure', depId, { order: 0 });
 
 // Read a specific edge
@@ -133,10 +143,33 @@ const edge = await g.getEdge(tourId, 'hasDeparture', depId);
 // Check existence
 const exists = await g.edgeExists(tourId, 'hasDeparture', depId);
 
+// Partial update (deep merge)
+await g.updateEdge(tourId, 'hasDeparture', depId, { order: 5 });
+
+// Full replace — discards every prior key not in the new payload
+await g.replaceEdge('tour', tourId, 'hasDeparture', 'departure', depId, { order: 5 });
+
 // Delete an edge
 await g.removeEdge(tourId, 'hasDeparture', depId);
 ```
 
+### Field Deletion
+
+The `deleteField()` sentinel removes a field from a stored document. It works
+across every backend (Firestore, SQLite, Cloudflare Durable Objects), so
+calling code stays portable:
+
+```typescript
+import { deleteField } from 'firegraph';
+
+await g.updateNode(tourId, {
+  meta: { deprecatedTag: deleteField() }, // removes meta.deprecatedTag
+});
+```
+
+Equivalent to Firestore's `FieldValue.delete()`, but Workers-safe and
+SQLite-aware.
+
 ### Querying Edges
 
 `findEdges` accepts any combination of filters. When all three identifiers (`aUid`, `axbType`, `bUid`) are provided, it uses a direct document lookup instead of a query scan.
@@ -377,8 +410,8 @@ const tour = await g.getNode(tourId);
 
 - **Version storage**: The `v` field lives on the record envelope (top-level, alongside `aType`, `data`, etc.), not inside `data`. Records without `v` are treated as version 0 (legacy data).
 - **Read path**: When a record is read and its `v` is behind the derived version (`max(toVersion)` from migrations), migrations run sequentially to bring data up to the current version.
-- **Write path**: When writing via `putNode`/`putEdge`, the record is stamped with `v` equal to the derived version automatically.
-- **`updateNode`**: Does not stamp `v` — it is a raw partial update without schema context. The next read re-triggers migration (which is idempotent).
+- **Write path**: When writing via `putNode`/`putEdge` (deep-merge) or `replaceNode`/`replaceEdge` (full overwrite), the record is stamped with `v` equal to the derived version automatically.
+- **`updateNode` / `updateEdge`**: Do not stamp `v` — they are raw partial patches without schema context. The next read re-triggers migration (which is idempotent).
 
 #### Write-Back
 
@@ -694,7 +727,7 @@ All errors extend `FiregraphError` with a `code` property:
 | `FiregraphError`         | varies                   | Base class                                                      |
 | `NodeNotFoundError`      | `NODE_NOT_FOUND`         | Node lookup fails (not thrown by `getNode` — it returns `null`) |
 | `EdgeNotFoundError`      | `EDGE_NOT_FOUND`         | Edge lookup fails                                               |
-| `ValidationError`        | `VALIDATION_ERROR`       | Schema validation fails (registry + Zod)                        |
+| `ValidationError`        | `VALIDATION_ERROR`       | Schema validation fails (registry JSON Schema validation)       |
 | `RegistryViolationError` | `REGISTRY_VIOLATION`     | Triple not registered                                           |
 | `RegistryScopeError`     | `REGISTRY_SCOPE`         | Type not allowed at this subgraph scope                         |
 | `MigrationError`         | `MIGRATION_ERROR`        | Migration function fails or chain is incomplete                 |
@@ -711,7 +744,7 @@ try {
 } catch (err) {
   if (err instanceof ValidationError) {
     console.error(err.code); // 'VALIDATION_ERROR'
-    console.error(err.details); // Zod error details
+    console.error(err.details); // OutputUnit[] from @cfworker/json-schema
   }
 }
 ```
@@ -877,14 +910,6 @@ pnpm test:emulator  # Full test suite against Firestore emulator
 
 Requires Node.js 18+.
 
-## Releasing
-
-Versions and npm publishes are automated via [release-please](https://github.com/googleapis/release-please).
-Land PRs to `main` with conventional-commit messages; release-please opens a
-Release PR that, when merged, tags + publishes to npm. See
-[docs/releasing.md](docs/releasing.md) for maintainer setup (NPM token,
-workflow permissions) and the full flow.
-
 ## License
 
 MIT

package/dist/backend-BsR0lnFL.d.ts

@@ -0,0 +1,200 @@
+import { S as StoredGraphRecord, g as QueryFilter, z as QueryOptions, l as GraphReader, m as BulkOptions, C as CascadeResult, F as FindEdgesParams, o as BulkResult } from './types-DxYLy8Ol.js';
+
+/**
+ * Write-plan helper — flattens partial-update payloads into a list of
+ * deep-path operations every backend can execute identically.
+ *
+ * Background: firegraph used to ship two write semantics that quietly
+ * disagreed about depth.
+ *   - `putNode`/`putEdge` did a full document replace.
+ *   - `updateNode`/`updateEdge` did a one-level shallow merge: top-level
+ *     keys were preserved, but nested objects were replaced wholesale.
+ *
+ * Both behaviours dropped sibling keys silently. The 0.12 contract is that
+ * `put*` and `update*` deep-merge by default (sibling keys at any depth
+ * survive); `replace*` is the explicit escape hatch.
+ *
+ * `flattenPatch` walks a partial-update payload and emits one
+ * {@link DataPathOp} per terminal value. Plain objects recurse; arrays,
+ * primitives, Firestore special types, and tagged firegraph-serialization
+ * objects are terminal (replaced as a unit). `undefined` values are
+ * skipped; `null` is preserved as a real `null` write; the
+ * {@link DELETE_FIELD} sentinel marks a field for removal.
+ *
+ * The output is deliberately backend-agnostic. Each backend translates ops
+ * into its native dialect:
+ *   - Firestore: dotted field path → `data.a.b.c` for `update()`.
+ *   - SQLite / DO SQLite: `json_set(data, '$.a.b.c', ?)` /
+ *     `json_remove(data, '$.a.b.c')`.
+ */
+/**
+ * Sentinel returned by {@link deleteField}. Treated by all backends as
+ * "remove this field from the stored document".
+ *
+ * Equivalent to Firestore's `FieldValue.delete()`, but works for SQLite
+ * backends too. Use inside `updateNode`/`updateEdge` payloads.
+ */
+declare const DELETE_FIELD: unique symbol;
+type DeleteSentinel = typeof DELETE_FIELD;
+/**
+ * Returns the firegraph delete sentinel. Place this anywhere in an
+ * `updateNode`/`updateEdge` payload to remove the corresponding field.
+ *
+ * ```ts
+ * await client.updateNode('tour', uid, {
+ *   attrs: { obsoleteFlag: deleteField() },
+ * });
+ * ```
+ */
+declare function deleteField(): DeleteSentinel;
+/** Type guard for the delete sentinel. */
+declare function isDeleteSentinel(value: unknown): value is DeleteSentinel;
+/**
+ * Single terminal write operation produced by {@link flattenPatch}.
+ *
+ * `path` is a non-empty array of plain object keys. `value` is the value to
+ * write; ignored when `delete` is `true`. Arrays / primitives / Firestore
+ * special types appear here as whole terminal values.
+ */
+interface DataPathOp {
+    path: readonly string[];
+    value: unknown;
+    delete: boolean;
+}
+/**
+ * Flatten a partial-update payload into a list of terminal {@link DataPathOp}s.
+ *
+ * Rules:
+ *   - Plain objects (no prototype or `Object.prototype`) recurse — each
+ *     key becomes another path segment.
+ *   - Arrays are terminal: writing `{tags: ['a']}` overwrites the whole
+ *     `tags` array. Element-wise array merging is intentionally NOT
+ *     supported — it's almost never what callers actually want, and
+ *     Firestore `arrayUnion`/`arrayRemove` give precise semantics when
+ *     they are.
+ *   - `undefined` values are skipped (no op generated). Use
+ *     {@link deleteField} if you actually want to remove a field.
+ *   - `null` is preserved verbatim — emits a terminal op with `value: null`.
+ *   - {@link DELETE_FIELD} produces an op with `delete: true`.
+ *   - Firestore special types and tagged serialization payloads are terminal.
+ *   - Class instances are terminal.
+ *
+ * Throws if any object key on the recursion path is unsafe (see
+ * {@link assertSafePath}).
+ */
+declare function flattenPatch(data: Record<string, unknown>): DataPathOp[];
+
+/**
+ * Backend abstraction for firegraph.
+ *
+ * `StorageBackend` is the single interface every storage driver implements.
+ * The Firestore backend wraps `@google-cloud/firestore`; the SQLite backend
+ * (shared by D1 and Durable Object SQLite) uses a parameterized SQL executor.
+ *
+ * `GraphClientImpl` and friends depend only on this interface — they have
+ * no direct knowledge of Firestore or SQLite.
+ */
+
+/**
+ * Per-record write payload — backend-agnostic. Timestamps are not present;
+ * the backend supplies them via `serverTimestamp()` placeholders that it
+ * itself resolves at commit time.
+ */
+interface WritableRecord {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    /** Schema version (set by the writer when registry has migrations). */
+    v?: number;
+}
+/**
+ * Write semantics for `setDoc`.
+ *
+ *   - `'merge'` — the new contract (0.12+). Existing fields not mentioned
+ *     in the new data survive; nested objects are recursively merged;
+ *     arrays are replaced as a unit. This is the default for
+ *     `putNode` / `putEdge`.
+ *   - `'replace'` — the document is replaced wholesale, dropping any
+ *     fields not present in the payload. This is the explicit escape
+ *     hatch surfaced as `replaceNode` / `replaceEdge` and used by
+ *     migration write-back.
+ */
+type WriteMode = 'merge' | 'replace';
+/**
+ * Patch shape for `updateDoc`.
+ *
+ *   - `dataOps`: list of deep-path terminal ops produced by
+ *     `flattenPatch()` (one op per leaf — arrays / primitives / Firestore
+ *     special types are terminal). Used by `updateNode` / `updateEdge`.
+ *     Sibling keys at every depth are preserved.
+ *   - `replaceData`: full `data` replacement. Used only by the migration
+ *     write-back path, which has already produced a complete migrated
+ *     document.
+ *   - `v`: optional schema-version stamp.
+ *
+ * `updatedAt` is always set by the backend.
+ */
+interface UpdatePayload {
+    dataOps?: DataPathOp[];
+    replaceData?: Record<string, unknown>;
+    v?: number;
+}
+/**
+ * Read/write transaction adapter. Mirrors Firestore's transaction semantics:
+ * reads are snapshot-consistent; writes are issued inside the transaction
+ * and a rejection from any write aborts the surrounding `runTransaction`.
+ *
+ * Writes return `Promise<void>` so SQL drivers can surface row-level errors
+ * (constraint violations, malformed JSON paths) rather than swallowing them.
+ * Firestore implementations can resolve synchronously since the underlying
+ * `Transaction.set/update/delete` calls are themselves synchronous buffers.
+ */
+interface TransactionBackend {
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+}
+/**
+ * Atomic multi-write batch.
+ */
+interface BatchBackend {
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): void;
+    updateDoc(docId: string, update: UpdatePayload): void;
+    deleteDoc(docId: string): void;
+    commit(): Promise<void>;
+}
+/**
+ * The single storage abstraction.
+ *
+ * Each backend instance is scoped to a "graph location" — for Firestore
+ * that's a collection path; for SQLite it's a (table, scopePath) pair.
+ * `subgraph()` returns a child backend bound to a nested location.
+ */
+interface StorageBackend {
+    /** Backend-internal location identifier (collection path or table name). */
+    readonly collectionPath: string;
+    /** Subgraph scope (empty string for root). */
+    readonly scopePath: string;
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+    runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;
+    createBatch(): BatchBackend;
+    subgraph(parentNodeUid: string, name: string): StorageBackend;
+    removeNodeCascade(uid: string, reader: GraphReader, options?: BulkOptions): Promise<CascadeResult>;
+    bulkRemoveEdges(params: FindEdgesParams, reader: GraphReader, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Find edges across all subgraphs sharing a given collection name.
+     * Optional — backends that can't support this should throw a clear error.
+     */
+    findEdgesGlobal?(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
+}
+
+export { type BatchBackend as B, DELETE_FIELD as D, type StorageBackend as S, type TransactionBackend as T, type UpdatePayload as U, type WritableRecord as W, type DataPathOp as a, type WriteMode as b, deleteField as d, flattenPatch as f, isDeleteSentinel as i };

package/dist/backend-Ct-fLlkG.d.cts

@@ -0,0 +1,200 @@
+import { S as StoredGraphRecord, g as QueryFilter, z as QueryOptions, l as GraphReader, m as BulkOptions, C as CascadeResult, F as FindEdgesParams, o as BulkResult } from './types-DxYLy8Ol.cjs';
+
+/**
+ * Write-plan helper — flattens partial-update payloads into a list of
+ * deep-path operations every backend can execute identically.
+ *
+ * Background: firegraph used to ship two write semantics that quietly
+ * disagreed about depth.
+ *   - `putNode`/`putEdge` did a full document replace.
+ *   - `updateNode`/`updateEdge` did a one-level shallow merge: top-level
+ *     keys were preserved, but nested objects were replaced wholesale.
+ *
+ * Both behaviours dropped sibling keys silently. The 0.12 contract is that
+ * `put*` and `update*` deep-merge by default (sibling keys at any depth
+ * survive); `replace*` is the explicit escape hatch.
+ *
+ * `flattenPatch` walks a partial-update payload and emits one
+ * {@link DataPathOp} per terminal value. Plain objects recurse; arrays,
+ * primitives, Firestore special types, and tagged firegraph-serialization
+ * objects are terminal (replaced as a unit). `undefined` values are
+ * skipped; `null` is preserved as a real `null` write; the
+ * {@link DELETE_FIELD} sentinel marks a field for removal.
+ *
+ * The output is deliberately backend-agnostic. Each backend translates ops
+ * into its native dialect:
+ *   - Firestore: dotted field path → `data.a.b.c` for `update()`.
+ *   - SQLite / DO SQLite: `json_set(data, '$.a.b.c', ?)` /
+ *     `json_remove(data, '$.a.b.c')`.
+ */
+/**
+ * Sentinel returned by {@link deleteField}. Treated by all backends as
+ * "remove this field from the stored document".
+ *
+ * Equivalent to Firestore's `FieldValue.delete()`, but works for SQLite
+ * backends too. Use inside `updateNode`/`updateEdge` payloads.
+ */
+declare const DELETE_FIELD: unique symbol;
+type DeleteSentinel = typeof DELETE_FIELD;
+/**
+ * Returns the firegraph delete sentinel. Place this anywhere in an
+ * `updateNode`/`updateEdge` payload to remove the corresponding field.
+ *
+ * ```ts
+ * await client.updateNode('tour', uid, {
+ *   attrs: { obsoleteFlag: deleteField() },
+ * });
+ * ```
+ */
+declare function deleteField(): DeleteSentinel;
+/** Type guard for the delete sentinel. */
+declare function isDeleteSentinel(value: unknown): value is DeleteSentinel;
+/**
+ * Single terminal write operation produced by {@link flattenPatch}.
+ *
+ * `path` is a non-empty array of plain object keys. `value` is the value to
+ * write; ignored when `delete` is `true`. Arrays / primitives / Firestore
+ * special types appear here as whole terminal values.
+ */
+interface DataPathOp {
+    path: readonly string[];
+    value: unknown;
+    delete: boolean;
+}
+/**
+ * Flatten a partial-update payload into a list of terminal {@link DataPathOp}s.
+ *
+ * Rules:
+ *   - Plain objects (no prototype or `Object.prototype`) recurse — each
+ *     key becomes another path segment.
+ *   - Arrays are terminal: writing `{tags: ['a']}` overwrites the whole
+ *     `tags` array. Element-wise array merging is intentionally NOT
+ *     supported — it's almost never what callers actually want, and
+ *     Firestore `arrayUnion`/`arrayRemove` give precise semantics when
+ *     they are.
+ *   - `undefined` values are skipped (no op generated). Use
+ *     {@link deleteField} if you actually want to remove a field.
+ *   - `null` is preserved verbatim — emits a terminal op with `value: null`.
+ *   - {@link DELETE_FIELD} produces an op with `delete: true`.
+ *   - Firestore special types and tagged serialization payloads are terminal.
+ *   - Class instances are terminal.
+ *
+ * Throws if any object key on the recursion path is unsafe (see
+ * {@link assertSafePath}).
+ */
+declare function flattenPatch(data: Record<string, unknown>): DataPathOp[];
+
+/**
+ * Backend abstraction for firegraph.
+ *
+ * `StorageBackend` is the single interface every storage driver implements.
+ * The Firestore backend wraps `@google-cloud/firestore`; the SQLite backend
+ * (shared by D1 and Durable Object SQLite) uses a parameterized SQL executor.
+ *
+ * `GraphClientImpl` and friends depend only on this interface — they have
+ * no direct knowledge of Firestore or SQLite.
+ */
+
+/**
+ * Per-record write payload — backend-agnostic. Timestamps are not present;
+ * the backend supplies them via `serverTimestamp()` placeholders that it
+ * itself resolves at commit time.
+ */
+interface WritableRecord {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    /** Schema version (set by the writer when registry has migrations). */
+    v?: number;
+}
+/**
+ * Write semantics for `setDoc`.
+ *
+ *   - `'merge'` — the new contract (0.12+). Existing fields not mentioned
+ *     in the new data survive; nested objects are recursively merged;
+ *     arrays are replaced as a unit. This is the default for
+ *     `putNode` / `putEdge`.
+ *   - `'replace'` — the document is replaced wholesale, dropping any
+ *     fields not present in the payload. This is the explicit escape
+ *     hatch surfaced as `replaceNode` / `replaceEdge` and used by
+ *     migration write-back.
+ */
+type WriteMode = 'merge' | 'replace';
+/**
+ * Patch shape for `updateDoc`.
+ *
+ *   - `dataOps`: list of deep-path terminal ops produced by
+ *     `flattenPatch()` (one op per leaf — arrays / primitives / Firestore
+ *     special types are terminal). Used by `updateNode` / `updateEdge`.
+ *     Sibling keys at every depth are preserved.
+ *   - `replaceData`: full `data` replacement. Used only by the migration
+ *     write-back path, which has already produced a complete migrated
+ *     document.
+ *   - `v`: optional schema-version stamp.
+ *
+ * `updatedAt` is always set by the backend.
+ */
+interface UpdatePayload {
+    dataOps?: DataPathOp[];
+    replaceData?: Record<string, unknown>;
+    v?: number;
+}
+/**
+ * Read/write transaction adapter. Mirrors Firestore's transaction semantics:
+ * reads are snapshot-consistent; writes are issued inside the transaction
+ * and a rejection from any write aborts the surrounding `runTransaction`.
+ *
+ * Writes return `Promise<void>` so SQL drivers can surface row-level errors
+ * (constraint violations, malformed JSON paths) rather than swallowing them.
+ * Firestore implementations can resolve synchronously since the underlying
+ * `Transaction.set/update/delete` calls are themselves synchronous buffers.
+ */
+interface TransactionBackend {
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+}
+/**
+ * Atomic multi-write batch.
+ */
+interface BatchBackend {
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): void;
+    updateDoc(docId: string, update: UpdatePayload): void;
+    deleteDoc(docId: string): void;
+    commit(): Promise<void>;
+}
+/**
+ * The single storage abstraction.
+ *
+ * Each backend instance is scoped to a "graph location" — for Firestore
+ * that's a collection path; for SQLite it's a (table, scopePath) pair.
+ * `subgraph()` returns a child backend bound to a nested location.
+ */
+interface StorageBackend {
+    /** Backend-internal location identifier (collection path or table name). */
+    readonly collectionPath: string;
+    /** Subgraph scope (empty string for root). */
+    readonly scopePath: string;
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+    runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;
+    createBatch(): BatchBackend;
+    subgraph(parentNodeUid: string, name: string): StorageBackend;
+    removeNodeCascade(uid: string, reader: GraphReader, options?: BulkOptions): Promise<CascadeResult>;
+    bulkRemoveEdges(params: FindEdgesParams, reader: GraphReader, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Find edges across all subgraphs sharing a given collection name.
+     * Optional — backends that can't support this should throw a clear error.
+     */
+    findEdgesGlobal?(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
+}
+
+export { type BatchBackend as B, DELETE_FIELD as D, type StorageBackend as S, type TransactionBackend as T, type UpdatePayload as U, type WritableRecord as W, type DataPathOp as a, type WriteMode as b, deleteField as d, flattenPatch as f, isDeleteSentinel as i };