@typicalday/firegraph 0.1.0 → 0.3.0

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

@@ -141,9 +141,19 @@ interface FindEdgesParams {
         direction?: 'asc' | 'desc';
     };
     where?: WhereClause[];
+    /** Set to true to allow queries that may cause full collection scans. */
+    allowCollectionScan?: boolean;
 }
 interface FindNodesParams {
     aType: string;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    where?: WhereClause[];
+    /** Set to true to allow queries that may cause full collection scans. */
+    allowCollectionScan?: boolean;
 }
 interface QueryOptions {
     limit?: number;
@@ -177,12 +187,50 @@ interface RegistryEntry {
     titleField?: string;
     /** Data field to use as the display subtitle (e.g. 'status', 'difficulty'). */
     subtitleField?: string;
+    /**
+     * Scope patterns constraining where this type can exist.
+     * Omit or leave empty to allow everywhere (backwards compatible).
+     *
+     * Patterns:
+     *   - `'root'`            — top-level collection only
+     *   - `'agents'`          — exact subgraph name match
+     *   - `'workflow/agents'`  — exact path match
+     *   - `'*​/agents'`        — `*` matches one segment
+     *   - `'**​/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 {
@@ -203,6 +251,10 @@ interface DiscoveredEntity {
     viewsPath?: string;
     /** Sample data from sample.json. */
     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 {
@@ -233,6 +285,8 @@ interface DefineTypeOptions {
     viewTemplate?: string;
     /** Scoped CSS for the view template (injected via Shadow DOM). */
     viewCss?: string;
+    /** Scope patterns constraining where this type can exist in subgraphs. */
+    allowedIn?: string[];
 }
 /** Data shape stored in a `nodeType` meta-node. */
 interface NodeTypeData {
@@ -243,6 +297,7 @@ interface NodeTypeData {
     subtitleField?: string;
     viewTemplate?: string;
     viewCss?: string;
+    allowedIn?: string[];
 }
 /** Data shape stored in an `edgeType` meta-node. */
 interface EdgeTypeData {
@@ -256,7 +311,10 @@ interface EdgeTypeData {
     subtitleField?: string;
     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. */
     registry?: GraphRegistry;
@@ -275,10 +333,22 @@ interface GraphClientOptions {
      * `'standard'` regardless of this setting (emulator doesn't support pipelines).
      */
     queryMode?: QueryMode;
+    /**
+     * Controls query safety behavior for full collection scan prevention.
+     *
+     * - `'error'` (default) — Throws `QuerySafetyError` for queries that would
+     *   likely cause a full collection scan. Override per-query with
+     *   `allowCollectionScan: true`.
+     * - `'warn'` — Logs a warning but executes the query.
+     * - `'off'` — No scan protection.
+     */
+    scanProtection?: ScanProtection;
 }
 interface GraphRegistry {
-    validate(aType: string, axbType: string, bType: string, data: unknown): void;
+    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 {
@@ -302,6 +372,34 @@ interface GraphClient extends GraphReader, GraphWriter {
     removeNodeCascade(uid: string, options?: BulkOptions): Promise<CascadeResult>;
     /** Find all edges matching `params` and delete them in chunked batches. */
     bulkRemoveEdges(params: FindEdgesParams, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Create a scoped client for a Firestore subcollection under the given
+     * parent node's document.
+     *
+     * The returned client shares a snapshot of the parent's registry at
+     * the time of this call. If the parent is a `DynamicGraphClient` and
+     * `reloadRegistry()` is called later, existing subgraph clients will
+     * NOT see the updated types — create a new subgraph client after
+     * reloading to pick up changes.
+     *
+     * @param parentNodeUid - UID of the parent node whose document owns the subcollection
+     * @param name - Subcollection name (defaults to `'graph'`). Must not contain `/`.
+     * @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. */
@@ -327,6 +425,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;
@@ -357,6 +472,11 @@ interface BulkOptions {
     maxRetries?: number;
     /** Called after each batch commits. */
     onProgress?: (progress: BulkProgress) => void;
+    /**
+     * Recursively delete subcollections (subgraphs) under the node's document.
+     * Defaults to `true` for `removeNodeCascade`.
+     */
+    deleteSubcollections?: boolean;
 }
 interface BulkProgress {
     /** Batches committed so far. */
@@ -411,4 +531,4 @@ interface CodegenOptions {
  */
 declare function generateTypes(discovery: DiscoveryResult, options?: CodegenOptions): Promise<string>;
 
-export { defineConfig 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, generateTypes as I, resolveView as J, type NodeTypeData as N, type QueryPlan as Q, type RegistryEntry as R, type StoredGraphRecord 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 BulkOptions as h, type BulkProgress as i, type BulkResult as j, type CodegenOptions as k, type DefineTypeOptions as l, type DiscoveredEntity as m, type EdgeTypeData as n, type FiregraphConfig as o, type GraphBatch as p, type GraphTransaction as q, type GraphWriter as r, type HopResult as s, type QueryFilter as t, type QueryMode as u, type QueryOptions as v, type TraversalOptions as w, type TraversalResult as x, type ViewDefaultsConfig as y, type ViewResolverConfig 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 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 };

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

@@ -141,9 +141,19 @@ interface FindEdgesParams {
         direction?: 'asc' | 'desc';
     };
     where?: WhereClause[];
+    /** Set to true to allow queries that may cause full collection scans. */
+    allowCollectionScan?: boolean;
 }
 interface FindNodesParams {
     aType: string;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    where?: WhereClause[];
+    /** Set to true to allow queries that may cause full collection scans. */
+    allowCollectionScan?: boolean;
 }
 interface QueryOptions {
     limit?: number;
@@ -177,12 +187,50 @@ interface RegistryEntry {
     titleField?: string;
     /** Data field to use as the display subtitle (e.g. 'status', 'difficulty'). */
     subtitleField?: string;
+    /**
+     * Scope patterns constraining where this type can exist.
+     * Omit or leave empty to allow everywhere (backwards compatible).
+     *
+     * Patterns:
+     *   - `'root'`            — top-level collection only
+     *   - `'agents'`          — exact subgraph name match
+     *   - `'workflow/agents'`  — exact path match
+     *   - `'*​/agents'`        — `*` matches one segment
+     *   - `'**​/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 {
@@ -203,6 +251,10 @@ interface DiscoveredEntity {
     viewsPath?: string;
     /** Sample data from sample.json. */
     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 {
@@ -233,6 +285,8 @@ interface DefineTypeOptions {
     viewTemplate?: string;
     /** Scoped CSS for the view template (injected via Shadow DOM). */
     viewCss?: string;
+    /** Scope patterns constraining where this type can exist in subgraphs. */
+    allowedIn?: string[];
 }
 /** Data shape stored in a `nodeType` meta-node. */
 interface NodeTypeData {
@@ -243,6 +297,7 @@ interface NodeTypeData {
     subtitleField?: string;
     viewTemplate?: string;
     viewCss?: string;
+    allowedIn?: string[];
 }
 /** Data shape stored in an `edgeType` meta-node. */
 interface EdgeTypeData {
@@ -256,7 +311,10 @@ interface EdgeTypeData {
     subtitleField?: string;
     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. */
     registry?: GraphRegistry;
@@ -275,10 +333,22 @@ interface GraphClientOptions {
      * `'standard'` regardless of this setting (emulator doesn't support pipelines).
      */
     queryMode?: QueryMode;
+    /**
+     * Controls query safety behavior for full collection scan prevention.
+     *
+     * - `'error'` (default) — Throws `QuerySafetyError` for queries that would
+     *   likely cause a full collection scan. Override per-query with
+     *   `allowCollectionScan: true`.
+     * - `'warn'` — Logs a warning but executes the query.
+     * - `'off'` — No scan protection.
+     */
+    scanProtection?: ScanProtection;
 }
 interface GraphRegistry {
-    validate(aType: string, axbType: string, bType: string, data: unknown): void;
+    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 {
@@ -302,6 +372,34 @@ interface GraphClient extends GraphReader, GraphWriter {
     removeNodeCascade(uid: string, options?: BulkOptions): Promise<CascadeResult>;
     /** Find all edges matching `params` and delete them in chunked batches. */
     bulkRemoveEdges(params: FindEdgesParams, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Create a scoped client for a Firestore subcollection under the given
+     * parent node's document.
+     *
+     * The returned client shares a snapshot of the parent's registry at
+     * the time of this call. If the parent is a `DynamicGraphClient` and
+     * `reloadRegistry()` is called later, existing subgraph clients will
+     * NOT see the updated types — create a new subgraph client after
+     * reloading to pick up changes.
+     *
+     * @param parentNodeUid - UID of the parent node whose document owns the subcollection
+     * @param name - Subcollection name (defaults to `'graph'`). Must not contain `/`.
+     * @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. */
@@ -327,6 +425,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;
@@ -357,6 +472,11 @@ interface BulkOptions {
     maxRetries?: number;
     /** Called after each batch commits. */
     onProgress?: (progress: BulkProgress) => void;
+    /**
+     * Recursively delete subcollections (subgraphs) under the node's document.
+     * Defaults to `true` for `removeNodeCascade`.
+     */
+    deleteSubcollections?: boolean;
 }
 interface BulkProgress {
     /** Batches committed so far. */
@@ -411,4 +531,4 @@ interface CodegenOptions {
  */
 declare function generateTypes(discovery: DiscoveryResult, options?: CodegenOptions): Promise<string>;
 
-export { defineConfig 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, generateTypes as I, resolveView as J, type NodeTypeData as N, type QueryPlan as Q, type RegistryEntry as R, type StoredGraphRecord 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 BulkOptions as h, type BulkProgress as i, type BulkResult as j, type CodegenOptions as k, type DefineTypeOptions as l, type DiscoveredEntity as m, type EdgeTypeData as n, type FiregraphConfig as o, type GraphBatch as p, type GraphTransaction as q, type GraphWriter as r, type HopResult as s, type QueryFilter as t, type QueryMode as u, type QueryOptions as v, type TraversalOptions as w, type TraversalResult as x, type ViewDefaultsConfig as y, type ViewResolverConfig 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 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 };