@typicalday/firegraph 0.11.2 → 0.12.0

package/dist/registry-Fi074zVa.d.ts

@@ -0,0 +1,64 @@
+import { R as RegistryEntry, e as GraphRegistry, l as GraphReader, i as MigrationExecutor, b as DiscoveryResult } from './types-DxYLy8Ol.js';
+
+/** The aType used for node type definition meta-nodes. */
+declare const META_NODE_TYPE = "nodeType";
+/** The aType used for edge type definition meta-nodes. */
+declare const META_EDGE_TYPE = "edgeType";
+/** JSON Schema for the `data` payload of a `nodeType` meta-node. */
+declare const NODE_TYPE_SCHEMA: object;
+/** JSON Schema for the `data` payload of an `edgeType` meta-node. */
+declare const EDGE_TYPE_SCHEMA: object;
+/** Registry entries for the two meta-types (always present). */
+declare const BOOTSTRAP_ENTRIES: readonly RegistryEntry[];
+declare function createBootstrapRegistry(): GraphRegistry;
+/**
+ * Generate a deterministic UID for a meta-type definition.
+ * This ensures that defining the same type name always targets the same
+ * Firestore document, enabling upsert semantics.
+ *
+ * Format: 21-char base64url substring of SHA-256(`metaType:name`).
+ */
+declare function generateDeterministicUid(metaType: string, name: string): string;
+/**
+ * Read meta-type nodes from the graph and compile them into a GraphRegistry.
+ *
+ * The returned registry includes both the dynamic entries AND the bootstrap
+ * meta-type entries, so meta-type writes remain validateable after a reload.
+ *
+ * @param reader - A GraphReader pointed at the collection containing meta-nodes.
+ * @param executor - Optional custom executor for compiling stored migration source strings.
+ */
+declare function createRegistryFromGraph(reader: GraphReader, executor?: MigrationExecutor): Promise<GraphRegistry>;
+
+declare function generateId(): string;
+
+/**
+ * Build a registry from either explicit entries or a DiscoveryResult.
+ *
+ * @example
+ * ```ts
+ * // From explicit entries (programmatic)
+ * const registry = createRegistry([
+ *   { aType: 'user', axbType: 'is', bType: 'user', jsonSchema: userSchema },
+ *   { aType: 'user', axbType: 'follows', bType: 'user', jsonSchema: followsSchema },
+ * ]);
+ *
+ * // From discovery result (folder convention)
+ * const discovered = await discoverEntities('./entities');
+ * const registry = createRegistry(discovered);
+ * ```
+ */
+declare function createRegistry(input: RegistryEntry[] | DiscoveryResult): GraphRegistry;
+/**
+ * Create a merged registry where `base` entries take priority and `extension`
+ * entries fill in gaps. Lookups and validation check `base` first; only if the
+ * triple is not found there does the merged registry fall through to
+ * `extension`.
+ *
+ * The `entries()` method returns a deduplicated list (base wins on collision).
+ * The `lookupByAxbType()` method merges results from both registries,
+ * deduplicating by triple key with base entries winning.
+ */
+declare function createMergedRegistry(base: GraphRegistry, extension: GraphRegistry): GraphRegistry;
+
+export { BOOTSTRAP_ENTRIES as B, EDGE_TYPE_SCHEMA as E, META_EDGE_TYPE as M, NODE_TYPE_SCHEMA as N, META_NODE_TYPE as a, createMergedRegistry as b, createBootstrapRegistry as c, createRegistry as d, createRegistryFromGraph as e, generateId as f, generateDeterministicUid as g };

package/dist/{serialization-ZZ7RSDRX.js → serialization-OE2PFZMY.js}

@@ -1,13 +1,15 @@
 import {
-  SERIALIZATION_TAG,
   deserializeFirestoreTypes,
-  isTaggedValue,
   serializeFirestoreTypes
-} from "./chunk-5753Y42M.js";
+} from "./chunk-C2QMD7RY.js";
+import {
+  SERIALIZATION_TAG,
+  isTaggedValue
+} from "./chunk-EQJUUVFG.js";
 export {
   SERIALIZATION_TAG,
   deserializeFirestoreTypes,
   isTaggedValue,
   serializeFirestoreTypes
 };
-//# sourceMappingURL=serialization-ZZ7RSDRX.js.map
+//# sourceMappingURL=serialization-OE2PFZMY.js.map

package/dist/{types-BGWxcpI_.d.cts → types-DxYLy8Ol.d.cts}

@@ -260,7 +260,8 @@ interface IndexFieldSpec {
      * because SQLite expression indexes must match the query compiler's
      * output verbatim, and inlining quoted path components into DDL would
      * desynchronize the two compilers. If you need to filter by an exotic
-     * key, use `replaceData` writes rather than an indexed field.
+     * key, use `replaceNode` / `replaceEdge` writes rather than an indexed
+     * field.
      */
     path: string;
     /** Descending order; defaults to ascending. */
@@ -583,9 +584,42 @@ interface GraphReader {
     findNodes(params: FindNodesParams): Promise<StoredGraphRecord[]>;
 }
 interface GraphWriter {
+    /**
+     * Write a node, deep-merging into any existing record.
+     *
+     * Nested objects are merged recursively — sibling keys at any depth
+     * survive. Arrays are terminal (replaced as a unit, not element-merged).
+     * `undefined` values are omitted; `null` is preserved. To delete a field,
+     * pass the `deleteField()` sentinel as its value.
+     *
+     * Use {@link replaceNode} when you want full-document replacement.
+     */
     putNode(aType: string, uid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Write an edge, deep-merging into any existing record. See
+     * {@link putNode} for the merge contract.
+     */
     putEdge(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Replace a node's `data` payload entirely. Any field absent from
+     * `data` is dropped. Use sparingly — prefer {@link putNode} unless you
+     * specifically need to drop unknown fields.
+     */
+    replaceNode(aType: string, uid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Replace an edge's `data` payload entirely. See {@link replaceNode}.
+     */
+    replaceEdge(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Patch a node's `data` payload. Like {@link putNode} this is a deep
+     * merge — nested objects are walked, only leaves are written. Use the
+     * `deleteField()` sentinel to remove a field.
+     */
     updateNode(uid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Patch an edge's `data` payload. See {@link updateNode}.
+     */
+    updateEdge(aUid: string, axbType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
     removeNode(uid: string): Promise<void>;
     removeEdge(aUid: string, axbType: string, bUid: string): Promise<void>;
 }
@@ -733,4 +767,4 @@ interface CascadeResult extends BulkResult {
     nodeDeleted: boolean;
 }
 
-export { type ScanProtection as A, type BulkBatchError as B, type CascadeResult as C, type DynamicGraphClient as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, type IndexSpec as I, type TraversalOptions as J, type TraversalResult as K, type ViewDefaultsConfig as L, type MigrationExecutor as M, type NodeTypeData as N, type ViewResolverConfig as O, defineConfig as P, type QueryPlan as Q, type RegistryEntry as R, type StoredGraphRecord as S, type TraversalBuilder as T, resolveView as U, type ViewContext as V, type WhereClause as W, type GraphClient as a, type DiscoveryResult as b, type GraphRegistry as c, type GraphReader as d, type DynamicRegistryConfig as e, type MigrationWriteBack as f, type MigrationStep as g, type FindNodesParams as h, type QueryFilter as i, type GraphRecord as j, type MigrationFn as k, type StoredMigrationStep as l, type BulkOptions as m, type BulkProgress as n, type BulkResult as o, type DefineTypeOptions as p, type DiscoveredEntity as q, type EdgeTypeData as r, type FiregraphConfig as s, type GraphBatch as t, type GraphTransaction as u, type GraphWriter as v, type HopResult as w, type IndexFieldSpec as x, type QueryMode as y, type QueryOptions as z };
+export { type ScanProtection as A, type BulkBatchError as B, type CascadeResult as C, type DynamicGraphClient as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, type IndexSpec as I, type TraversalOptions as J, type TraversalResult as K, type ViewDefaultsConfig as L, type MigrationWriteBack as M, type NodeTypeData as N, type ViewResolverConfig as O, defineConfig as P, type QueryPlan as Q, type RegistryEntry as R, type StoredGraphRecord as S, type TraversalBuilder as T, resolveView as U, type ViewContext as V, type WhereClause as W, type GraphClient as a, type DiscoveryResult as b, type DynamicRegistryConfig as c, type MigrationStep as d, type GraphRegistry as e, type FindNodesParams as f, type QueryFilter as g, type GraphRecord as h, type MigrationExecutor as i, type MigrationFn as j, type StoredMigrationStep as k, type GraphReader as l, type BulkOptions as m, type BulkProgress as n, type BulkResult as o, type DefineTypeOptions as p, type DiscoveredEntity as q, type EdgeTypeData as r, type FiregraphConfig as s, type GraphBatch as t, type GraphTransaction as u, type GraphWriter as v, type HopResult as w, type IndexFieldSpec as x, type QueryMode as y, type QueryOptions as z };

package/dist/{types-BGWxcpI_.d.ts → types-DxYLy8Ol.d.ts}

@@ -260,7 +260,8 @@ interface IndexFieldSpec {
      * because SQLite expression indexes must match the query compiler's
      * output verbatim, and inlining quoted path components into DDL would
      * desynchronize the two compilers. If you need to filter by an exotic
-     * key, use `replaceData` writes rather than an indexed field.
+     * key, use `replaceNode` / `replaceEdge` writes rather than an indexed
+     * field.
      */
     path: string;
     /** Descending order; defaults to ascending. */
@@ -583,9 +584,42 @@ interface GraphReader {
     findNodes(params: FindNodesParams): Promise<StoredGraphRecord[]>;
 }
 interface GraphWriter {
+    /**
+     * Write a node, deep-merging into any existing record.
+     *
+     * Nested objects are merged recursively — sibling keys at any depth
+     * survive. Arrays are terminal (replaced as a unit, not element-merged).
+     * `undefined` values are omitted; `null` is preserved. To delete a field,
+     * pass the `deleteField()` sentinel as its value.
+     *
+     * Use {@link replaceNode} when you want full-document replacement.
+     */
     putNode(aType: string, uid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Write an edge, deep-merging into any existing record. See
+     * {@link putNode} for the merge contract.
+     */
     putEdge(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Replace a node's `data` payload entirely. Any field absent from
+     * `data` is dropped. Use sparingly — prefer {@link putNode} unless you
+     * specifically need to drop unknown fields.
+     */
+    replaceNode(aType: string, uid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Replace an edge's `data` payload entirely. See {@link replaceNode}.
+     */
+    replaceEdge(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Patch a node's `data` payload. Like {@link putNode} this is a deep
+     * merge — nested objects are walked, only leaves are written. Use the
+     * `deleteField()` sentinel to remove a field.
+     */
     updateNode(uid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Patch an edge's `data` payload. See {@link updateNode}.
+     */
+    updateEdge(aUid: string, axbType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
     removeNode(uid: string): Promise<void>;
     removeEdge(aUid: string, axbType: string, bUid: string): Promise<void>;
 }
@@ -733,4 +767,4 @@ interface CascadeResult extends BulkResult {
     nodeDeleted: boolean;
 }
 
-export { type ScanProtection as A, type BulkBatchError as B, type CascadeResult as C, type DynamicGraphClient as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, type IndexSpec as I, type TraversalOptions as J, type TraversalResult as K, type ViewDefaultsConfig as L, type MigrationExecutor as M, type NodeTypeData as N, type ViewResolverConfig as O, defineConfig as P, type QueryPlan as Q, type RegistryEntry as R, type StoredGraphRecord as S, type TraversalBuilder as T, resolveView as U, type ViewContext as V, type WhereClause as W, type GraphClient as a, type DiscoveryResult as b, type GraphRegistry as c, type GraphReader as d, type DynamicRegistryConfig as e, type MigrationWriteBack as f, type MigrationStep as g, type FindNodesParams as h, type QueryFilter as i, type GraphRecord as j, type MigrationFn as k, type StoredMigrationStep as l, type BulkOptions as m, type BulkProgress as n, type BulkResult as o, type DefineTypeOptions as p, type DiscoveredEntity as q, type EdgeTypeData as r, type FiregraphConfig as s, type GraphBatch as t, type GraphTransaction as u, type GraphWriter as v, type HopResult as w, type IndexFieldSpec as x, type QueryMode as y, type QueryOptions as z };
+export { type ScanProtection as A, type BulkBatchError as B, type CascadeResult as C, type DynamicGraphClient as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, type IndexSpec as I, type TraversalOptions as J, type TraversalResult as K, type ViewDefaultsConfig as L, type MigrationWriteBack as M, type NodeTypeData as N, type ViewResolverConfig as O, defineConfig as P, type QueryPlan as Q, type RegistryEntry as R, type StoredGraphRecord as S, type TraversalBuilder as T, resolveView as U, type ViewContext as V, type WhereClause as W, type GraphClient as a, type DiscoveryResult as b, type DynamicRegistryConfig as c, type MigrationStep as d, type GraphRegistry as e, type FindNodesParams as f, type QueryFilter as g, type GraphRecord as h, type MigrationExecutor as i, type MigrationFn as j, type StoredMigrationStep as k, type GraphReader as l, type BulkOptions as m, type BulkProgress as n, type BulkResult as o, type DefineTypeOptions as p, type DiscoveredEntity as q, type EdgeTypeData as r, type FiregraphConfig as s, type GraphBatch as t, type GraphTransaction as u, type GraphWriter as v, type HopResult as w, type IndexFieldSpec as x, type QueryMode as y, type QueryOptions as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typicalday/firegraph",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Generic Firestore adjacency graph client with smart query planning",
   "type": "module",
   "main": "./dist/index.cjs",

package/dist/backend-U-MLShlg.d.ts

@@ -1,97 +0,0 @@
-import { S as StoredGraphRecord, i as QueryFilter, z as QueryOptions, d as GraphReader, m as BulkOptions, C as CascadeResult, F as FindEdgesParams, o as BulkResult } from './types-BGWxcpI_.js';
-
-/**
- * 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;
-}
-/**
- * Patch shape for `updateDoc`. Captures the two patterns that exist today:
- *   - `dataFields`: shallow merge under `data` (used by `updateNode`)
- *   - `replaceData`: full data replacement (used by migration write-back)
- *   - `v`: optional schema-version stamp
- *
- * `updatedAt` is always set by the backend.
- */
-interface UpdatePayload {
-    dataFields?: Record<string, unknown>;
-    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): 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): 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): 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, StorageBackend as S, TransactionBackend as T, UpdatePayload as U, WritableRecord as W };

package/dist/backend-np4gEVhB.d.cts

@@ -1,97 +0,0 @@
-import { S as StoredGraphRecord, i as QueryFilter, z as QueryOptions, d as GraphReader, m as BulkOptions, C as CascadeResult, F as FindEdgesParams, o as BulkResult } from './types-BGWxcpI_.cjs';
-
-/**
- * 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;
-}
-/**
- * Patch shape for `updateDoc`. Captures the two patterns that exist today:
- *   - `dataFields`: shallow merge under `data` (used by `updateNode`)
- *   - `replaceData`: full data replacement (used by migration write-back)
- *   - `v`: optional schema-version stamp
- *
- * `updatedAt` is always set by the backend.
- */
-interface UpdatePayload {
-    dataFields?: Record<string, unknown>;
-    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): 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): 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): 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, StorageBackend as S, TransactionBackend as T, UpdatePayload as U, WritableRecord as W };

package/dist/chunk-5753Y42M.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/serialization.ts"],"sourcesContent":["/**\n * Firestore-aware serialization for the sandbox migration pipeline.\n *\n * Firestore documents can contain special types (Timestamp, GeoPoint,\n * VectorValue, DocumentReference) that don't survive plain JSON\n * round-tripping. This module provides tagged serialization: Firestore\n * types are wrapped in tagged plain objects before JSON marshaling and\n * reconstructed after.\n *\n * Only used by the `defaultExecutor` sandbox path. Static migrations\n * (in-memory functions) receive raw Firestore objects directly.\n */\n\nimport type { DocumentReference, Firestore } from '@google-cloud/firestore';\nimport { FieldValue, GeoPoint, Timestamp } from '@google-cloud/firestore';\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/** Sentinel key used to tag serialized Firestore types. */\nexport const SERIALIZATION_TAG = '__firegraph_ser__' as const;\n\n/** Known discriminator values for tagged types. */\nconst KNOWN_TYPES = new Set(['Timestamp', 'GeoPoint', 'VectorValue', 'DocumentReference']);\n\n// One-time warning for DocumentReference deserialization without db\nlet _docRefWarned = false;\n\n// ---------------------------------------------------------------------------\n// Type guard\n// ---------------------------------------------------------------------------\n\n/** Check if a value is a tagged serialized Firestore type. */\nexport function isTaggedValue(value: unknown): boolean {\n  if (value === null || typeof value !== 'object') return false;\n  const tag = (value as Record<string, unknown>)[SERIALIZATION_TAG];\n  return typeof tag === 'string' && KNOWN_TYPES.has(tag);\n}\n\n// ---------------------------------------------------------------------------\n// Detection helpers\n// ---------------------------------------------------------------------------\n\nfunction isTimestamp(value: unknown): value is Timestamp {\n  return value instanceof Timestamp;\n}\n\nfunction isGeoPoint(value: unknown): value is GeoPoint {\n  return value instanceof GeoPoint;\n}\n\nfunction isDocumentReference(value: unknown): value is DocumentReference {\n  // Duck-type check: DocumentReference has path (string) and firestore properties\n  if (value === null || typeof value !== 'object') return false;\n  const v = value as Record<string, unknown>;\n  return (\n    typeof v.path === 'string' &&\n    v.firestore !== undefined &&\n    typeof v.id === 'string' &&\n    v.constructor?.name === 'DocumentReference'\n  );\n}\n\nfunction isVectorValue(value: unknown): boolean {\n  if (value === null || typeof value !== 'object') return false;\n  const v = value as Record<string, unknown>;\n  return (\n    v.constructor?.name === 'VectorValue' && Array.isArray((v as Record<string, unknown>)._values)\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Serialize\n// ---------------------------------------------------------------------------\n\n/**\n * Recursively walk a data object and replace Firestore types with tagged\n * plain objects suitable for JSON serialization.\n *\n * Returns a new object tree — the input is never mutated.\n */\nexport function serializeFirestoreTypes(data: Record<string, unknown>): Record<string, unknown> {\n  return serializeValue(data) as Record<string, unknown>;\n}\n\nfunction serializeValue(value: unknown): unknown {\n  // Primitives\n  if (value === null || value === undefined) return value;\n  if (typeof value !== 'object') return value;\n\n  // Firestore types (check before generic object/array)\n  if (isTimestamp(value)) {\n    return {\n      [SERIALIZATION_TAG]: 'Timestamp',\n      seconds: value.seconds,\n      nanoseconds: value.nanoseconds,\n    };\n  }\n  if (isGeoPoint(value)) {\n    return {\n      [SERIALIZATION_TAG]: 'GeoPoint',\n      latitude: value.latitude,\n      longitude: value.longitude,\n    };\n  }\n  if (isDocumentReference(value)) {\n    return { [SERIALIZATION_TAG]: 'DocumentReference', path: (value as DocumentReference).path };\n  }\n  if (isVectorValue(value)) {\n    // Prefer toArray() (public API) over _values (private internal property)\n    const v = value as Record<string, unknown>;\n    const values =\n      typeof v.toArray === 'function' ? (v.toArray as () => number[])() : (v._values as number[]);\n    return { [SERIALIZATION_TAG]: 'VectorValue', values: [...values] };\n  }\n\n  // Arrays\n  if (Array.isArray(value)) {\n    return value.map(serializeValue);\n  }\n\n  // Plain objects — recurse\n  const result: Record<string, unknown> = {};\n  for (const key of Object.keys(value as Record<string, unknown>)) {\n    result[key] = serializeValue((value as Record<string, unknown>)[key]);\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Deserialize\n// ---------------------------------------------------------------------------\n\n/**\n * Recursively walk a data object and reconstruct Firestore types from\n * tagged plain objects.\n *\n * @param data - The data to deserialize (typically from JSON.parse)\n * @param db - Optional Firestore instance for DocumentReference reconstruction.\n *   If not provided, tagged DocumentReferences are left as-is with a one-time warning.\n *\n * Returns a new object tree — the input is never mutated.\n */\nexport function deserializeFirestoreTypes(\n  data: Record<string, unknown>,\n  db?: Firestore,\n): Record<string, unknown> {\n  return deserializeValue(data, db) as Record<string, unknown>;\n}\n\nfunction deserializeValue(value: unknown, db?: Firestore): unknown {\n  if (value === null || value === undefined) return value;\n  if (typeof value !== 'object') return value;\n\n  // Short-circuit for values that are already real Firestore types.\n  // This makes deserializeFirestoreTypes idempotent — safe to call on data\n  // that has already been deserialized (e.g., write-back after defaultExecutor\n  // already reconstructed types, or static migrations that return raw types).\n  if (\n    isTimestamp(value) ||\n    isGeoPoint(value) ||\n    isDocumentReference(value) ||\n    isVectorValue(value)\n  ) {\n    return value;\n  }\n\n  // Arrays\n  if (Array.isArray(value)) {\n    return value.map((v) => deserializeValue(v, db));\n  }\n\n  const obj = value as Record<string, unknown>;\n\n  // Check for tagged Firestore type\n  if (isTaggedValue(obj)) {\n    const tag = obj[SERIALIZATION_TAG] as string;\n\n    switch (tag) {\n      case 'Timestamp':\n        // Validate expected fields before reconstruction\n        if (typeof obj.seconds !== 'number' || typeof obj.nanoseconds !== 'number') return obj;\n        return new Timestamp(obj.seconds, obj.nanoseconds);\n\n      case 'GeoPoint':\n        if (typeof obj.latitude !== 'number' || typeof obj.longitude !== 'number') return obj;\n        return new GeoPoint(obj.latitude, obj.longitude);\n\n      case 'VectorValue':\n        if (!Array.isArray(obj.values)) return obj;\n        return FieldValue.vector(obj.values as number[]);\n\n      case 'DocumentReference':\n        if (typeof obj.path !== 'string') return obj;\n        if (db) {\n          return db.doc(obj.path);\n        }\n        // No db available — leave as tagged object with one-time warning\n        if (!_docRefWarned) {\n          _docRefWarned = true;\n          console.warn(\n            '[firegraph] DocumentReference encountered during migration deserialization ' +\n              'but no Firestore instance available. The reference will remain as a tagged ' +\n              'object with its path. Enable write-back for full reconstruction.',\n          );\n        }\n        return obj;\n\n      default:\n        // Unknown tag — leave as-is (forward compatibility)\n        return obj;\n    }\n  }\n\n  // Plain object — recurse\n  const result: Record<string, unknown> = {};\n  for (const key of Object.keys(obj)) {\n    result[key] = deserializeValue(obj[key], db);\n  }\n  return result;\n}\n"],"mappings":"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","names":[]}