@typicalday/firegraph 0.2.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-wSlVH5Nv.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-wSlVH5Nv.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";
@@ -71,7 +82,18 @@ declare function buildEdgeRecord(aType: string, aUid: string, axbType: string, b
 declare function buildEdgeQueryPlan(params: FindEdgesParams): QueryPlan;
 declare function buildNodeQueryPlan(params: FindNodesParams): QueryPlan;
 
-declare function createTraversal(reader: GraphReader, startUid: string): TraversalBuilder;
+/**
+ * Create a traversal builder for multi-hop graph traversal.
+ *
+ * Accepts either a `GraphReader` (backwards compatible) or a `GraphClient`.
+ * When a `GraphClient` is provided, cross-graph traversal via `targetGraph`
+ * is supported — the traversal can follow edges into subgraphs.
+ *
+ * @param reader - A `GraphClient` or `GraphReader` to execute queries against
+ * @param startUid - UID of the starting node
+ * @param registry - Optional registry for automatic `targetGraph` resolution
+ */
+declare function createTraversal(reader: GraphClient | GraphReader, startUid: string, registry?: GraphRegistry): TraversalBuilder;
 
 declare class FiregraphError extends Error {
     readonly code: string;
@@ -187,6 +209,52 @@ declare function matchScope(scopePath: string, pattern: string): boolean;
  */
 declare function matchScopeAny(scopePath: string, patterns: string[]): boolean;
 
+/**
+ * Cross-graph edge resolution utilities.
+ *
+ * Provides path-scanning resolution for determining whether an edge's source
+ * (aUid) is an ancestor node by checking if the UID appears in the Firestore
+ * collection path.
+ *
+ * Firestore paths have a rigid alternating structure:
+ *   collection / docId / collection / docId / collection
+ *
+ * Given a path like `graph/A/workspace/B/context`, segments at even indices
+ * are collection names and odd indices are document IDs. When we find a UID
+ * at an odd index, the collection containing that document is the path up to
+ * (and including) the preceding even-index segment.
+ */
+/**
+ * Parse a Firestore collection path and determine the collection path
+ * where a given UID's document lives, if that UID is an ancestor in the path.
+ *
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to search for in the path
+ * @returns The collection path containing the UID, or `null` if not found in the path
+ *
+ * @example
+ * ```ts
+ * // Path: graph/A/workspace/B/context
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'A')
+ * // → 'graph'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'B')
+ * // → 'graph/A/workspace'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'unknown')
+ * // → null
+ * ```
+ */
+declare function resolveAncestorCollection(collectionPath: string, uid: string): string | null;
+/**
+ * Check whether a UID belongs to an ancestor node by scanning the collection path.
+ *
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to check
+ * @returns `true` if the UID appears as a document segment in the path
+ */
+declare function isAncestorUid(collectionPath: string, uid: string): boolean;
+
 /**
  * JSON Schema validation and introspection utilities.
  *
@@ -226,7 +294,7 @@ interface FirestoreIndexField {
 }
 interface FirestoreIndex {
     collectionGroup: string;
-    queryScope: 'COLLECTION';
+    queryScope: 'COLLECTION' | 'COLLECTION_GROUP';
     fields: FirestoreIndexField[];
 }
 interface FirestoreIndexConfig {
@@ -241,10 +309,17 @@ interface FirestoreIndexConfig {
  * patterns on node data fields:
  *   (aType, axbType, data.{field})
  *
+ * When registry entries with `targetGraph` are provided, also generates
+ * collection group indexes for `findEdgesGlobal()` queries. The collection
+ * group name defaults to `'graph'` (the standard subgraph name) but can be
+ * overridden per `targetGraph` value.
+ *
  * @param collection - Firestore collection name (e.g. 'graph')
  * @param entities - Optional discovery result for per-entity data field indexes
+ * @param registryEntries - Optional registry entries; when any have `targetGraph`,
+ *   collection group indexes are generated for the distinct subgraph names
  */
-declare function generateIndexConfig(collection: string, entities?: DiscoveryResult): FirestoreIndexConfig;
+declare function generateIndexConfig(collection: string, entities?: DiscoveryResult, registryEntries?: ReadonlyArray<RegistryEntry>): FirestoreIndexConfig;
 
 /**
  * Result of analyzing a query for collection scan risk.
@@ -272,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, jsonSchemaToFieldMeta, matchScope, matchScopeAny };
+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-wSlVH5Nv.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-wSlVH5Nv.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";
@@ -71,7 +82,18 @@ declare function buildEdgeRecord(aType: string, aUid: string, axbType: string, b
 declare function buildEdgeQueryPlan(params: FindEdgesParams): QueryPlan;
 declare function buildNodeQueryPlan(params: FindNodesParams): QueryPlan;
 
-declare function createTraversal(reader: GraphReader, startUid: string): TraversalBuilder;
+/**
+ * Create a traversal builder for multi-hop graph traversal.
+ *
+ * Accepts either a `GraphReader` (backwards compatible) or a `GraphClient`.
+ * When a `GraphClient` is provided, cross-graph traversal via `targetGraph`
+ * is supported — the traversal can follow edges into subgraphs.
+ *
+ * @param reader - A `GraphClient` or `GraphReader` to execute queries against
+ * @param startUid - UID of the starting node
+ * @param registry - Optional registry for automatic `targetGraph` resolution
+ */
+declare function createTraversal(reader: GraphClient | GraphReader, startUid: string, registry?: GraphRegistry): TraversalBuilder;
 
 declare class FiregraphError extends Error {
     readonly code: string;
@@ -187,6 +209,52 @@ declare function matchScope(scopePath: string, pattern: string): boolean;
  */
 declare function matchScopeAny(scopePath: string, patterns: string[]): boolean;
 
+/**
+ * Cross-graph edge resolution utilities.
+ *
+ * Provides path-scanning resolution for determining whether an edge's source
+ * (aUid) is an ancestor node by checking if the UID appears in the Firestore
+ * collection path.
+ *
+ * Firestore paths have a rigid alternating structure:
+ *   collection / docId / collection / docId / collection
+ *
+ * Given a path like `graph/A/workspace/B/context`, segments at even indices
+ * are collection names and odd indices are document IDs. When we find a UID
+ * at an odd index, the collection containing that document is the path up to
+ * (and including) the preceding even-index segment.
+ */
+/**
+ * Parse a Firestore collection path and determine the collection path
+ * where a given UID's document lives, if that UID is an ancestor in the path.
+ *
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to search for in the path
+ * @returns The collection path containing the UID, or `null` if not found in the path
+ *
+ * @example
+ * ```ts
+ * // Path: graph/A/workspace/B/context
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'A')
+ * // → 'graph'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'B')
+ * // → 'graph/A/workspace'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'unknown')
+ * // → null
+ * ```
+ */
+declare function resolveAncestorCollection(collectionPath: string, uid: string): string | null;
+/**
+ * Check whether a UID belongs to an ancestor node by scanning the collection path.
+ *
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to check
+ * @returns `true` if the UID appears as a document segment in the path
+ */
+declare function isAncestorUid(collectionPath: string, uid: string): boolean;
+
 /**
  * JSON Schema validation and introspection utilities.
  *
@@ -226,7 +294,7 @@ interface FirestoreIndexField {
 }
 interface FirestoreIndex {
     collectionGroup: string;
-    queryScope: 'COLLECTION';
+    queryScope: 'COLLECTION' | 'COLLECTION_GROUP';
     fields: FirestoreIndexField[];
 }
 interface FirestoreIndexConfig {
@@ -241,10 +309,17 @@ interface FirestoreIndexConfig {
  * patterns on node data fields:
  *   (aType, axbType, data.{field})
  *
+ * When registry entries with `targetGraph` are provided, also generates
+ * collection group indexes for `findEdgesGlobal()` queries. The collection
+ * group name defaults to `'graph'` (the standard subgraph name) but can be
+ * overridden per `targetGraph` value.
+ *
  * @param collection - Firestore collection name (e.g. 'graph')
  * @param entities - Optional discovery result for per-entity data field indexes
+ * @param registryEntries - Optional registry entries; when any have `targetGraph`,
+ *   collection group indexes are generated for the distinct subgraph names
  */
-declare function generateIndexConfig(collection: string, entities?: DiscoveryResult): FirestoreIndexConfig;
+declare function generateIndexConfig(collection: string, entities?: DiscoveryResult, registryEntries?: ReadonlyArray<RegistryEntry>): FirestoreIndexConfig;
 
 /**
  * Result of analyzing a query for collection scan risk.
@@ -272,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, jsonSchemaToFieldMeta, matchScope, matchScopeAny };
+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 };