@typicalday/firegraph 0.2.0 → 0.4.0

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

@@ -199,12 +199,38 @@ interface RegistryEntry {
      *   - `'**​/agents'`       — `**` matches zero or more segments
      */
     allowedIn?: string[];
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     *
+     * When set, forward traversal queries the named subgraph under each
+     * source node (e.g., `{collection}/{sourceUid}/{targetGraph}`) instead
+     * of the current collection. The subgraph contains both the edge
+     * documents and the target nodes they reference.
+     *
+     * Reverse traversal is unaffected — if you're already in the subgraph,
+     * the edges are local.
+     *
+     * Only applies to edge entries (not node self-loop entries).
+     * Must be a single segment (no `/`).
+     *
+     * @example
+     * ```ts
+     * { aType: 'task', axbType: 'assignedTo', bType: 'agent', targetGraph: 'workflow' }
+     * // Forward traversal from task1: queries {collection}/task1/workflow
+     * ```
+     */
+    targetGraph?: string;
 }
 /** Topology declaration for an edge (from edge.json). */
 interface EdgeTopology {
     from: string | string[];
     to: string | string[];
     inverseLabel?: string;
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     * See `RegistryEntry.targetGraph` for full documentation.
+     */
+    targetGraph?: string;
 }
 /** A discovered entity from the per-entity folder convention. */
 interface DiscoveredEntity {
@@ -227,6 +253,8 @@ interface DiscoveredEntity {
     sampleData?: Record<string, unknown>;
     /** Scope patterns constraining where this type can exist in subgraphs. */
     allowedIn?: string[];
+    /** Subgraph name where cross-graph edges of this type live. */
+    targetGraph?: string;
 }
 /** Result of scanning an entities directory. */
 interface DiscoveryResult {
@@ -284,10 +312,20 @@ interface EdgeTypeData {
     viewTemplate?: string;
     viewCss?: string;
     allowedIn?: string[];
+    targetGraph?: string;
 }
 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;
@@ -318,6 +356,8 @@ interface GraphClientOptions {
 interface GraphRegistry {
     validate(aType: string, axbType: string, bType: string, data: unknown, scopePath?: string): void;
     lookup(aType: string, axbType: string, bType: string): RegistryEntry | undefined;
+    /** Return all entries matching the given axbType (edge relation name). */
+    lookupByAxbType(axbType: string): ReadonlyArray<RegistryEntry>;
     entries(): ReadonlyArray<RegistryEntry>;
 }
 interface GraphReader {
@@ -356,6 +396,19 @@ interface GraphClient extends GraphReader, GraphWriter {
      * @returns A `GraphClient` scoped to `{collectionPath}/{parentNodeUid}/{name}`
      */
     subgraph(parentNodeUid: string, name?: string): GraphClient;
+    /**
+     * Find edges across all subgraphs using a Firestore collection group query.
+     *
+     * Queries all collections with the given name (defaults to `'graph'`) across
+     * the entire database. This is useful for cross-cutting reads that span
+     * multiple subgraphs.
+     *
+     * **Requires** a Firestore collection group index for the query pattern.
+     *
+     * @param params - Edge filter parameters (same as `findEdges`)
+     * @param collectionName - Collection name to query across (defaults to last segment of this client's collection path)
+     */
+    findEdgesGlobal(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
 }
 interface DynamicGraphClient extends GraphClient {
     /** Define or update a node type in the dynamic registry. */
@@ -381,6 +434,23 @@ interface HopDefinition {
         direction?: 'asc' | 'desc';
     };
     filter?: (edge: StoredGraphRecord) => boolean;
+    /**
+     * Subgraph name to cross into for this hop (forward traversal only).
+     *
+     * When set, the traversal queries the named subgraph under each source node
+     * instead of the current collection (`{collection}/{sourceUid}/{targetGraph}`).
+     *
+     * If omitted but the registry has a `targetGraph` for this `axbType`,
+     * the registry value is used automatically.
+     *
+     * **Context tracking:** Once a hop crosses into a subgraph, subsequent
+     * hops without `targetGraph` stay in that subgraph automatically. To
+     * cross into a different subgraph, set `targetGraph` explicitly on the
+     * next hop — explicit `targetGraph` always resolves relative to the
+     * root client, not the current subgraph. To return to the root graph,
+     * create a separate traversal from the root client.
+     */
+    targetGraph?: string;
 }
 interface TraversalOptions {
     maxReads?: number;
@@ -470,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-wSlVH5Nv.d.ts → index-DR3jF5_b.d.ts}

@@ -199,12 +199,38 @@ interface RegistryEntry {
      *   - `'**​/agents'`       — `**` matches zero or more segments
      */
     allowedIn?: string[];
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     *
+     * When set, forward traversal queries the named subgraph under each
+     * source node (e.g., `{collection}/{sourceUid}/{targetGraph}`) instead
+     * of the current collection. The subgraph contains both the edge
+     * documents and the target nodes they reference.
+     *
+     * Reverse traversal is unaffected — if you're already in the subgraph,
+     * the edges are local.
+     *
+     * Only applies to edge entries (not node self-loop entries).
+     * Must be a single segment (no `/`).
+     *
+     * @example
+     * ```ts
+     * { aType: 'task', axbType: 'assignedTo', bType: 'agent', targetGraph: 'workflow' }
+     * // Forward traversal from task1: queries {collection}/task1/workflow
+     * ```
+     */
+    targetGraph?: string;
 }
 /** Topology declaration for an edge (from edge.json). */
 interface EdgeTopology {
     from: string | string[];
     to: string | string[];
     inverseLabel?: string;
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     * See `RegistryEntry.targetGraph` for full documentation.
+     */
+    targetGraph?: string;
 }
 /** A discovered entity from the per-entity folder convention. */
 interface DiscoveredEntity {
@@ -227,6 +253,8 @@ interface DiscoveredEntity {
     sampleData?: Record<string, unknown>;
     /** Scope patterns constraining where this type can exist in subgraphs. */
     allowedIn?: string[];
+    /** Subgraph name where cross-graph edges of this type live. */
+    targetGraph?: string;
 }
 /** Result of scanning an entities directory. */
 interface DiscoveryResult {
@@ -284,10 +312,20 @@ interface EdgeTypeData {
     viewTemplate?: string;
     viewCss?: string;
     allowedIn?: string[];
+    targetGraph?: string;
 }
 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;
@@ -318,6 +356,8 @@ interface GraphClientOptions {
 interface GraphRegistry {
     validate(aType: string, axbType: string, bType: string, data: unknown, scopePath?: string): void;
     lookup(aType: string, axbType: string, bType: string): RegistryEntry | undefined;
+    /** Return all entries matching the given axbType (edge relation name). */
+    lookupByAxbType(axbType: string): ReadonlyArray<RegistryEntry>;
     entries(): ReadonlyArray<RegistryEntry>;
 }
 interface GraphReader {
@@ -356,6 +396,19 @@ interface GraphClient extends GraphReader, GraphWriter {
      * @returns A `GraphClient` scoped to `{collectionPath}/{parentNodeUid}/{name}`
      */
     subgraph(parentNodeUid: string, name?: string): GraphClient;
+    /**
+     * Find edges across all subgraphs using a Firestore collection group query.
+     *
+     * Queries all collections with the given name (defaults to `'graph'`) across
+     * the entire database. This is useful for cross-cutting reads that span
+     * multiple subgraphs.
+     *
+     * **Requires** a Firestore collection group index for the query pattern.
+     *
+     * @param params - Edge filter parameters (same as `findEdges`)
+     * @param collectionName - Collection name to query across (defaults to last segment of this client's collection path)
+     */
+    findEdgesGlobal(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
 }
 interface DynamicGraphClient extends GraphClient {
     /** Define or update a node type in the dynamic registry. */
@@ -381,6 +434,23 @@ interface HopDefinition {
         direction?: 'asc' | 'desc';
     };
     filter?: (edge: StoredGraphRecord) => boolean;
+    /**
+     * Subgraph name to cross into for this hop (forward traversal only).
+     *
+     * When set, the traversal queries the named subgraph under each source node
+     * instead of the current collection (`{collection}/{sourceUid}/{targetGraph}`).
+     *
+     * If omitted but the registry has a `targetGraph` for this `axbType`,
+     * the registry value is used automatically.
+     *
+     * **Context tracking:** Once a hop crosses into a subgraph, subsequent
+     * hops without `targetGraph` stay in that subgraph automatically. To
+     * cross into a different subgraph, set `targetGraph` explicitly on the
+     * next hop — explicit `targetGraph` always resolves relative to the
+     * root client, not the current subgraph. To return to the root graph,
+     * create a separate traversal from the root client.
+     */
+    targetGraph?: string;
 }
 interface TraversalOptions {
     maxReads?: number;
@@ -470,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 };