@typicalday/firegraph 0.3.0 → 0.4.0

package/README.md

@@ -340,7 +340,7 @@ Key behaviors:
 - **After `reloadRegistry()`**: Domain writes are validated against the compiled registry. Unknown types are always rejected.
 - **Upsert semantics**: Calling `defineNodeType('tour', ...)` twice overwrites the previous definition. After reloading, the latest schema is used.
 - **Separate collection**: Meta-nodes can be stored in a different collection via `registryMode: { mode: 'dynamic', collection: 'meta' }`.
-- **Mutual exclusivity**: `registry` (static) and `registryMode` (dynamic) cannot be used together.
+- **Merged mode**: Provide both `registry` (static) and `registryMode` (dynamic) to get a merged registry where static entries take priority and dynamic definitions can only add new types — not override existing ones.
 
 Dynamic registry returns a `DynamicGraphClient` which extends `GraphClient` with `defineNodeType()`, `defineEdgeType()`, and `reloadRegistry()`. Transactions and batches also validate against the compiled dynamic registry.
 

package/dist/codegen/index.d.cts

@@ -1,2 +1,2 @@
-export { l as CodegenOptions, J as generateTypes } from '../index-CQkofEC_.cjs';
+export { l as CodegenOptions, J as generateTypes } from '../index-DR3jF5_b.cjs';
 import '@google-cloud/firestore';

package/dist/codegen/index.d.ts

@@ -1,2 +1,2 @@
-export { l as CodegenOptions, J as generateTypes } from '../index-CQkofEC_.js';
+export { l as CodegenOptions, J as generateTypes } from '../index-DR3jF5_b.js';
 import '@google-cloud/firestore';

package/dist/editor/server/index.mjs

@@ -30072,6 +30072,9 @@ function matchSegments(path4, pi, pattern, qi) {
 function tripleKey(aType, axbType, bType) {
   return `${aType}:${axbType}:${bType}`;
 }
+function tripleKeyFor(e) {
+  return tripleKey(e.aType, e.axbType, e.bType);
+}
 function createRegistry(input) {
   const map2 = /* @__PURE__ */ new Map();
   let entries;
@@ -30138,6 +30141,45 @@ function createRegistry(input) {
     }
   };
 }
+function createMergedRegistry(base, extension) {
+  const baseKeys = new Set(base.entries().map(tripleKeyFor));
+  return {
+    lookup(aType, axbType, bType) {
+      return base.lookup(aType, axbType, bType) ?? extension.lookup(aType, axbType, bType);
+    },
+    lookupByAxbType(axbType) {
+      const baseResults = base.lookupByAxbType(axbType);
+      const extResults = extension.lookupByAxbType(axbType);
+      if (extResults.length === 0) return baseResults;
+      if (baseResults.length === 0) return extResults;
+      const seen = new Set(baseResults.map(tripleKeyFor));
+      const merged = [...baseResults];
+      for (const entry of extResults) {
+        if (!seen.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    },
+    validate(aType, axbType, bType, data, scopePath) {
+      if (baseKeys.has(tripleKey(aType, axbType, bType))) {
+        return base.validate(aType, axbType, bType, data, scopePath);
+      }
+      return extension.validate(aType, axbType, bType, data, scopePath);
+    },
+    entries() {
+      const extEntries = extension.entries();
+      if (extEntries.length === 0) return base.entries();
+      const merged = [...base.entries()];
+      for (const entry of extEntries) {
+        if (!baseKeys.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    }
+  };
+}
 function discoveryToEntries(discovery) {
   const entries = [];
   for (const [name, entity] of discovery.nodes) {
@@ -30304,14 +30346,12 @@ var GraphClientImpl = class _GraphClientImpl {
     this.db = db2;
     this.scopePath = scopePath;
     this.adapter = createFirestoreAdapter(db2, collectionPath);
-    if (options?.registry && options?.registryMode) {
-      throw new DynamicRegistryError(
-        'Cannot provide both "registry" and "registryMode". Use "registry" for static mode or "registryMode" for dynamic mode.'
-      );
-    }
     if (options?.registryMode) {
       this.dynamicConfig = options.registryMode;
       this.bootstrapRegistry = createBootstrapRegistry();
+      if (options.registry) {
+        this.staticRegistry = options.registry;
+      }
       const metaCollectionPath = options.registryMode.collection;
       if (metaCollectionPath && metaCollectionPath !== collectionPath) {
         this.metaAdapter = createFirestoreAdapter(db2, metaCollectionPath);
@@ -30363,18 +30403,20 @@ var GraphClientImpl = class _GraphClientImpl {
   /**
    * Get the appropriate registry for validating a write to the given type.
    *
-   * - Static mode: returns staticRegistry (or undefined if none set)
-   * - Dynamic mode:
+   * - Static-only mode: returns staticRegistry (or undefined if none set)
+   * - Dynamic mode (pure or merged):
    *   - Meta-types (nodeType, edgeType): validated against bootstrapRegistry
    *   - Domain types: validated against dynamicRegistry (falls back to
    *     bootstrapRegistry which rejects unknown types)
+   *   - Merged mode: dynamicRegistry is a merged wrapper (static + dynamic
+   *     extension), so static entries take priority automatically.
    */
   getRegistryForType(aType) {
     if (!this.dynamicConfig) return this.staticRegistry;
     if (aType === META_NODE_TYPE || aType === META_EDGE_TYPE) {
       return this.bootstrapRegistry;
     }
-    return this.dynamicRegistry ?? this.bootstrapRegistry;
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
   }
   /**
    * Get the Firestore adapter for writing the given type.
@@ -30388,13 +30430,13 @@ var GraphClientImpl = class _GraphClientImpl {
   }
   /**
    * Get the combined registry for transaction/batch context.
-   * In static mode, returns staticRegistry.
+   * In static-only mode, returns staticRegistry.
    * In dynamic mode, returns dynamicRegistry (which includes bootstrap entries)
-   * or bootstrapRegistry if not yet reloaded.
+   * or falls back to staticRegistry (merged mode) or bootstrapRegistry.
    */
   getCombinedRegistry() {
     if (!this.dynamicConfig) return this.staticRegistry;
-    return this.dynamicRegistry ?? this.bootstrapRegistry;
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
   }
   // ---------------------------------------------------------------------------
   // Query dispatch
@@ -30591,6 +30633,11 @@ var GraphClientImpl = class _GraphClientImpl {
         `Cannot define type "${name}": this name is reserved for the meta-registry.`
       );
     }
+    if (this.staticRegistry?.lookup(name, NODE_RELATION, name)) {
+      throw new DynamicRegistryError(
+        `Cannot define node type "${name}": already defined in the static registry.`
+      );
+    }
     const uid = generateDeterministicUid(META_NODE_TYPE, name);
     const data = { name, jsonSchema };
     if (description !== void 0) data.description = description;
@@ -30612,6 +30659,19 @@ var GraphClientImpl = class _GraphClientImpl {
         `Cannot define type "${name}": this name is reserved for the meta-registry.`
       );
     }
+    if (this.staticRegistry) {
+      const fromTypes = Array.isArray(topology.from) ? topology.from : [topology.from];
+      const toTypes = Array.isArray(topology.to) ? topology.to : [topology.to];
+      for (const aType of fromTypes) {
+        for (const bType of toTypes) {
+          if (this.staticRegistry.lookup(aType, name, bType)) {
+            throw new DynamicRegistryError(
+              `Cannot define edge type "${name}" for (${aType}) -> (${bType}): already defined in the static registry.`
+            );
+          }
+        }
+      }
+    }
     const uid = generateDeterministicUid(META_EDGE_TYPE, name);
     const data = {
       name,
@@ -30636,7 +30696,12 @@ var GraphClientImpl = class _GraphClientImpl {
       );
     }
     const reader = this.createMetaReader();
-    this.dynamicRegistry = await createRegistryFromGraph(reader);
+    const dynamicOnly = await createRegistryFromGraph(reader);
+    if (this.staticRegistry) {
+      this.dynamicRegistry = createMergedRegistry(this.staticRegistry, dynamicOnly);
+    } else {
+      this.dynamicRegistry = dynamicOnly;
+    }
   }
   /**
    * Create a GraphReader for the meta-collection.

package/dist/{index-CQkofEC_.d.cts → index-DR3jF5_b.d.cts}

@@ -316,7 +316,16 @@ interface EdgeTypeData {
 }
 type ScanProtection = 'error' | 'warn' | 'off';
 interface GraphClientOptions {
-    /** Static registry built from code/discovery. Ignored if registryMode is set. */
+    /**
+     * Static registry built from code/discovery.
+     *
+     * When provided alone, all writes are validated against this registry.
+     *
+     * When provided together with `registryMode`, operates in **merged mode**:
+     * static entries take priority and cannot be overridden by dynamic
+     * definitions. Dynamic definitions can only add new types. The merged
+     * client is returned as a `DynamicGraphClient`.
+     */
     registry?: GraphRegistry;
     /** Dynamic registry mode — type definitions stored as graph data. */
     registryMode?: DynamicRegistryConfig;
@@ -531,4 +540,4 @@ interface CodegenOptions {
  */
 declare function generateTypes(discovery: DiscoveryResult, options?: CodegenOptions): Promise<string>;
 
-export { type ViewResolverConfig as A, type BulkBatchError as B, type CascadeResult as C, type DynamicRegistryConfig as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, defineConfig as I, generateTypes as J, resolveView as K, type NodeTypeData as N, type QueryPlan as Q, type RegistryEntry as R, type ScanProtection as S, type TraversalBuilder as T, type ViewContext as V, type WhereClause as W, type DynamicGraphClient as a, type GraphClient as b, type DiscoveryResult as c, type GraphRegistry as d, type GraphReader as e, type GraphRecord as f, type FindNodesParams as g, type QueryFilter as h, type BulkOptions as i, type BulkProgress as j, type BulkResult as k, type CodegenOptions as l, type DefineTypeOptions as m, type DiscoveredEntity as n, type EdgeTypeData as o, type FiregraphConfig as p, type GraphBatch as q, type GraphTransaction as r, type GraphWriter as s, type HopResult as t, type QueryMode as u, type QueryOptions as v, type StoredGraphRecord as w, type TraversalOptions as x, type TraversalResult as y, type ViewDefaultsConfig as z };
+export { type ViewResolverConfig as A, type BulkBatchError as B, type CascadeResult as C, type DynamicRegistryConfig as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, defineConfig as I, generateTypes as J, resolveView as K, type NodeTypeData as N, type QueryPlan as Q, type RegistryEntry as R, type ScanProtection as S, type TraversalBuilder as T, type ViewContext as V, type WhereClause as W, type DynamicGraphClient as a, type GraphClient as b, type GraphRegistry as c, type DiscoveryResult as d, type GraphReader as e, type GraphRecord as f, type FindNodesParams as g, type QueryFilter as h, type BulkOptions as i, type BulkProgress as j, type BulkResult as k, type CodegenOptions as l, type DefineTypeOptions as m, type DiscoveredEntity as n, type EdgeTypeData as o, type FiregraphConfig as p, type GraphBatch as q, type GraphTransaction as r, type GraphWriter as s, type HopResult as t, type QueryMode as u, type QueryOptions as v, type StoredGraphRecord as w, type TraversalOptions as x, type TraversalResult as y, type ViewDefaultsConfig as z };

package/dist/{index-CQkofEC_.d.ts → index-DR3jF5_b.d.ts}

@@ -316,7 +316,16 @@ interface EdgeTypeData {
 }
 type ScanProtection = 'error' | 'warn' | 'off';
 interface GraphClientOptions {
-    /** Static registry built from code/discovery. Ignored if registryMode is set. */
+    /**
+     * Static registry built from code/discovery.
+     *
+     * When provided alone, all writes are validated against this registry.
+     *
+     * When provided together with `registryMode`, operates in **merged mode**:
+     * static entries take priority and cannot be overridden by dynamic
+     * definitions. Dynamic definitions can only add new types. The merged
+     * client is returned as a `DynamicGraphClient`.
+     */
     registry?: GraphRegistry;
     /** Dynamic registry mode — type definitions stored as graph data. */
     registryMode?: DynamicRegistryConfig;
@@ -531,4 +540,4 @@ interface CodegenOptions {
  */
 declare function generateTypes(discovery: DiscoveryResult, options?: CodegenOptions): Promise<string>;
 
-export { type ViewResolverConfig as A, type BulkBatchError as B, type CascadeResult as C, type DynamicRegistryConfig as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, defineConfig as I, generateTypes as J, resolveView as K, type NodeTypeData as N, type QueryPlan as Q, type RegistryEntry as R, type ScanProtection as S, type TraversalBuilder as T, type ViewContext as V, type WhereClause as W, type DynamicGraphClient as a, type GraphClient as b, type DiscoveryResult as c, type GraphRegistry as d, type GraphReader as e, type GraphRecord as f, type FindNodesParams as g, type QueryFilter as h, type BulkOptions as i, type BulkProgress as j, type BulkResult as k, type CodegenOptions as l, type DefineTypeOptions as m, type DiscoveredEntity as n, type EdgeTypeData as o, type FiregraphConfig as p, type GraphBatch as q, type GraphTransaction as r, type GraphWriter as s, type HopResult as t, type QueryMode as u, type QueryOptions as v, type StoredGraphRecord as w, type TraversalOptions as x, type TraversalResult as y, type ViewDefaultsConfig as z };
+export { type ViewResolverConfig as A, type BulkBatchError as B, type CascadeResult as C, type DynamicRegistryConfig as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, defineConfig as I, generateTypes as J, resolveView as K, type NodeTypeData as N, type QueryPlan as Q, type RegistryEntry as R, type ScanProtection as S, type TraversalBuilder as T, type ViewContext as V, type WhereClause as W, type DynamicGraphClient as a, type GraphClient as b, type GraphRegistry as c, type DiscoveryResult as d, type GraphReader as e, type GraphRecord as f, type FindNodesParams as g, type QueryFilter as h, type BulkOptions as i, type BulkProgress as j, type BulkResult as k, type CodegenOptions as l, type DefineTypeOptions as m, type DiscoveredEntity as n, type EdgeTypeData as o, type FiregraphConfig as p, type GraphBatch as q, type GraphTransaction as r, type GraphWriter as s, type HopResult as t, type QueryMode as u, type QueryOptions as v, type StoredGraphRecord as w, type TraversalOptions as x, type TraversalResult as y, type ViewDefaultsConfig as z };

package/dist/index.cjs

@@ -59,6 +59,7 @@ __export(index_exports, {
   computeNodeDocId: () => computeNodeDocId,
   createBootstrapRegistry: () => createBootstrapRegistry,
   createGraphClient: () => createGraphClient,
+  createMergedRegistry: () => createMergedRegistry,
   createRegistry: () => createRegistry,
   createRegistryFromGraph: () => createRegistryFromGraph,
   createTraversal: () => createTraversal,
@@ -845,6 +846,9 @@ function matchSegments(path, pi, pattern, qi) {
 function tripleKey(aType, axbType, bType) {
   return `${aType}:${axbType}:${bType}`;
 }
+function tripleKeyFor(e) {
+  return tripleKey(e.aType, e.axbType, e.bType);
+}
 function createRegistry(input) {
   const map = /* @__PURE__ */ new Map();
   let entries;
@@ -911,6 +915,45 @@ function createRegistry(input) {
     }
   };
 }
+function createMergedRegistry(base, extension) {
+  const baseKeys = new Set(base.entries().map(tripleKeyFor));
+  return {
+    lookup(aType, axbType, bType) {
+      return base.lookup(aType, axbType, bType) ?? extension.lookup(aType, axbType, bType);
+    },
+    lookupByAxbType(axbType) {
+      const baseResults = base.lookupByAxbType(axbType);
+      const extResults = extension.lookupByAxbType(axbType);
+      if (extResults.length === 0) return baseResults;
+      if (baseResults.length === 0) return extResults;
+      const seen = new Set(baseResults.map(tripleKeyFor));
+      const merged = [...baseResults];
+      for (const entry of extResults) {
+        if (!seen.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    },
+    validate(aType, axbType, bType, data, scopePath) {
+      if (baseKeys.has(tripleKey(aType, axbType, bType))) {
+        return base.validate(aType, axbType, bType, data, scopePath);
+      }
+      return extension.validate(aType, axbType, bType, data, scopePath);
+    },
+    entries() {
+      const extEntries = extension.entries();
+      if (extEntries.length === 0) return base.entries();
+      const merged = [...base.entries()];
+      for (const entry of extEntries) {
+        if (!baseKeys.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    }
+  };
+}
 function discoveryToEntries(discovery) {
   const entries = [];
   for (const [name, entity] of discovery.nodes) {
@@ -1077,14 +1120,12 @@ var GraphClientImpl = class _GraphClientImpl {
     this.db = db;
     this.scopePath = scopePath;
     this.adapter = createFirestoreAdapter(db, collectionPath);
-    if (options?.registry && options?.registryMode) {
-      throw new DynamicRegistryError(
-        'Cannot provide both "registry" and "registryMode". Use "registry" for static mode or "registryMode" for dynamic mode.'
-      );
-    }
     if (options?.registryMode) {
       this.dynamicConfig = options.registryMode;
       this.bootstrapRegistry = createBootstrapRegistry();
+      if (options.registry) {
+        this.staticRegistry = options.registry;
+      }
       const metaCollectionPath = options.registryMode.collection;
       if (metaCollectionPath && metaCollectionPath !== collectionPath) {
         this.metaAdapter = createFirestoreAdapter(db, metaCollectionPath);
@@ -1136,18 +1177,20 @@ var GraphClientImpl = class _GraphClientImpl {
   /**
    * Get the appropriate registry for validating a write to the given type.
    *
-   * - Static mode: returns staticRegistry (or undefined if none set)
-   * - Dynamic mode:
+   * - Static-only mode: returns staticRegistry (or undefined if none set)
+   * - Dynamic mode (pure or merged):
    *   - Meta-types (nodeType, edgeType): validated against bootstrapRegistry
    *   - Domain types: validated against dynamicRegistry (falls back to
    *     bootstrapRegistry which rejects unknown types)
+   *   - Merged mode: dynamicRegistry is a merged wrapper (static + dynamic
+   *     extension), so static entries take priority automatically.
    */
   getRegistryForType(aType) {
     if (!this.dynamicConfig) return this.staticRegistry;
     if (aType === META_NODE_TYPE || aType === META_EDGE_TYPE) {
       return this.bootstrapRegistry;
     }
-    return this.dynamicRegistry ?? this.bootstrapRegistry;
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
   }
   /**
    * Get the Firestore adapter for writing the given type.
@@ -1161,13 +1204,13 @@ var GraphClientImpl = class _GraphClientImpl {
   }
   /**
    * Get the combined registry for transaction/batch context.
-   * In static mode, returns staticRegistry.
+   * In static-only mode, returns staticRegistry.
    * In dynamic mode, returns dynamicRegistry (which includes bootstrap entries)
-   * or bootstrapRegistry if not yet reloaded.
+   * or falls back to staticRegistry (merged mode) or bootstrapRegistry.
    */
   getCombinedRegistry() {
     if (!this.dynamicConfig) return this.staticRegistry;
-    return this.dynamicRegistry ?? this.bootstrapRegistry;
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
   }
   // ---------------------------------------------------------------------------
   // Query dispatch
@@ -1364,6 +1407,11 @@ var GraphClientImpl = class _GraphClientImpl {
         `Cannot define type "${name}": this name is reserved for the meta-registry.`
       );
     }
+    if (this.staticRegistry?.lookup(name, NODE_RELATION, name)) {
+      throw new DynamicRegistryError(
+        `Cannot define node type "${name}": already defined in the static registry.`
+      );
+    }
     const uid = generateDeterministicUid(META_NODE_TYPE, name);
     const data = { name, jsonSchema };
     if (description !== void 0) data.description = description;
@@ -1385,6 +1433,19 @@ var GraphClientImpl = class _GraphClientImpl {
         `Cannot define type "${name}": this name is reserved for the meta-registry.`
       );
     }
+    if (this.staticRegistry) {
+      const fromTypes = Array.isArray(topology.from) ? topology.from : [topology.from];
+      const toTypes = Array.isArray(topology.to) ? topology.to : [topology.to];
+      for (const aType of fromTypes) {
+        for (const bType of toTypes) {
+          if (this.staticRegistry.lookup(aType, name, bType)) {
+            throw new DynamicRegistryError(
+              `Cannot define edge type "${name}" for (${aType}) -> (${bType}): already defined in the static registry.`
+            );
+          }
+        }
+      }
+    }
     const uid = generateDeterministicUid(META_EDGE_TYPE, name);
     const data = {
       name,
@@ -1409,7 +1470,12 @@ var GraphClientImpl = class _GraphClientImpl {
       );
     }
     const reader = this.createMetaReader();
-    this.dynamicRegistry = await createRegistryFromGraph(reader);
+    const dynamicOnly = await createRegistryFromGraph(reader);
+    if (this.staticRegistry) {
+      this.dynamicRegistry = createMergedRegistry(this.staticRegistry, dynamicOnly);
+    } else {
+      this.dynamicRegistry = dynamicOnly;
+    }
   }
   /**
    * Create a GraphReader for the meta-collection.
@@ -2431,6 +2497,7 @@ var QueryClient = class {
   computeNodeDocId,
   createBootstrapRegistry,
   createGraphClient,
+  createMergedRegistry,
   createRegistry,
   createRegistryFromGraph,
   createTraversal,