@typicalday/firegraph 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Firestore } from '@google-cloud/firestore';
-import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, R as RegistryEntry, c as DiscoveryResult, d as GraphRegistry, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-CQkofEC_.cjs';
-export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-CQkofEC_.cjs';
+import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, c as GraphRegistry, R as RegistryEntry, d as DiscoveryResult, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-DR3jF5_b.cjs';
+export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-DR3jF5_b.cjs';
 export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b as ViewMeta, c as ViewRegistry, d as ViewRegistryInput, e as defineViews } from './views-DL60k0cf.cjs';
 export { Q as QueryClient, a as QueryClientError, b as QueryClientErrorCode, c as QueryClientOptions } from './client-Bk2Cm6xv.cjs';
 
@@ -26,6 +26,17 @@ declare function createGraphClient(db: Firestore, collectionPath: string, option
  * ```
  */
 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;
 
 /** The aType used for node type definition meta-nodes. */
 declare const META_NODE_TYPE = "nodeType";
@@ -336,4 +347,4 @@ declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
  */
 declare const DEFAULT_QUERY_LIMIT = 500;
 
-export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, jsonSchemaToFieldMeta, matchScope, matchScopeAny, resolveAncestorCollection };
+export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createMergedRegistry, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, jsonSchemaToFieldMeta, matchScope, matchScopeAny, resolveAncestorCollection };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Firestore } from '@google-cloud/firestore';
-import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, R as RegistryEntry, c as DiscoveryResult, d as GraphRegistry, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-CQkofEC_.js';
-export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-CQkofEC_.js';
+import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, c as GraphRegistry, R as RegistryEntry, d as DiscoveryResult, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-DR3jF5_b.js';
+export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-DR3jF5_b.js';
 export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b as ViewMeta, c as ViewRegistry, d as ViewRegistryInput, e as defineViews } from './views-DL60k0cf.js';
 export { Q as QueryClient, a as QueryClientError, b as QueryClientErrorCode, c as QueryClientOptions } from './client-Bk2Cm6xv.js';
 
@@ -26,6 +26,17 @@ declare function createGraphClient(db: Firestore, collectionPath: string, option
  * ```
  */
 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;
 
 /** The aType used for node type definition meta-nodes. */
 declare const META_NODE_TYPE = "nodeType";
@@ -336,4 +347,4 @@ declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
  */
 declare const DEFAULT_QUERY_LIMIT = 500;
 
-export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, jsonSchemaToFieldMeta, matchScope, matchScopeAny, resolveAncestorCollection };
+export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createMergedRegistry, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, jsonSchemaToFieldMeta, matchScope, matchScopeAny, resolveAncestorCollection };

package/dist/index.js

@@ -773,6 +773,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;
@@ -839,6 +842,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) {
@@ -1005,14 +1047,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);
@@ -1064,18 +1104,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.
@@ -1089,13 +1131,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
@@ -1292,6 +1334,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;
@@ -1313,6 +1360,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,
@@ -1337,7 +1397,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.
@@ -2038,6 +2103,7 @@ export {
   computeNodeDocId,
   createBootstrapRegistry,
   createGraphClient,
+  createMergedRegistry,
   createRegistry,
   createRegistryFromGraph,
   createTraversal,