@typicalday/firegraph 0.1.0 → 0.2.0

package/dist/{index-CG3R68Hu.d.cts → index-wSlVH5Nv.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,6 +187,18 @@ 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[];
 }
 /** Topology declaration for an edge (from edge.json). */
 interface EdgeTopology {
@@ -203,6 +225,8 @@ 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[];
 }
 /** Result of scanning an entities directory. */
 interface DiscoveryResult {
@@ -233,6 +257,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 +269,7 @@ interface NodeTypeData {
     subtitleField?: string;
     viewTemplate?: string;
     viewCss?: string;
+    allowedIn?: string[];
 }
 /** Data shape stored in an `edgeType` meta-node. */
 interface EdgeTypeData {
@@ -256,7 +283,9 @@ interface EdgeTypeData {
     subtitleField?: string;
     viewTemplate?: string;
     viewCss?: string;
+    allowedIn?: string[];
 }
+type ScanProtection = 'error' | 'warn' | 'off';
 interface GraphClientOptions {
     /** Static registry built from code/discovery. Ignored if registryMode is set. */
     registry?: GraphRegistry;
@@ -275,9 +304,19 @@ 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;
     entries(): ReadonlyArray<RegistryEntry>;
 }
@@ -302,6 +341,21 @@ 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;
 }
 interface DynamicGraphClient extends GraphClient {
     /** Define or update a node type in the dynamic registry. */
@@ -357,6 +411,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 +470,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-wSlVH5Nv.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,6 +187,18 @@ 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[];
 }
 /** Topology declaration for an edge (from edge.json). */
 interface EdgeTopology {
@@ -203,6 +225,8 @@ 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[];
 }
 /** Result of scanning an entities directory. */
 interface DiscoveryResult {
@@ -233,6 +257,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 +269,7 @@ interface NodeTypeData {
     subtitleField?: string;
     viewTemplate?: string;
     viewCss?: string;
+    allowedIn?: string[];
 }
 /** Data shape stored in an `edgeType` meta-node. */
 interface EdgeTypeData {
@@ -256,7 +283,9 @@ interface EdgeTypeData {
     subtitleField?: string;
     viewTemplate?: string;
     viewCss?: string;
+    allowedIn?: string[];
 }
+type ScanProtection = 'error' | 'warn' | 'off';
 interface GraphClientOptions {
     /** Static registry built from code/discovery. Ignored if registryMode is set. */
     registry?: GraphRegistry;
@@ -275,9 +304,19 @@ 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;
     entries(): ReadonlyArray<RegistryEntry>;
 }
@@ -302,6 +341,21 @@ 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;
 }
 interface DynamicGraphClient extends GraphClient {
     /** Define or update a node type in the dynamic registry. */
@@ -357,6 +411,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 +470,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 };