@typicalday/firegraph 0.1.0 → 0.2.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 } from './index-CG3R68Hu.cjs';
-export { B as BulkBatchError, h as BulkOptions, i as BulkProgress, j as BulkResult, C as CascadeResult, k as CodegenOptions, l as DefineTypeOptions, m as DiscoveredEntity, E as EdgeTopology, n as EdgeTypeData, o as FiregraphConfig, p as GraphBatch, q as GraphTransaction, r as GraphWriter, H as HopDefinition, s as HopResult, N as NodeTypeData, t as QueryFilter, u as QueryMode, v as QueryOptions, S as StoredGraphRecord, w as TraversalOptions, x as TraversalResult, V as ViewContext, y as ViewDefaultsConfig, z as ViewResolverConfig, W as WhereClause, A as defineConfig, I as generateTypes, J as resolveView } from './index-CG3R68Hu.cjs';
+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';
 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';
 
@@ -99,6 +99,12 @@ declare class TraversalError extends FiregraphError {
 declare class DynamicRegistryError extends FiregraphError {
     constructor(message: string);
 }
+declare class QuerySafetyError extends FiregraphError {
+    constructor(message: string);
+}
+declare class RegistryScopeError extends FiregraphError {
+    constructor(aType: string, axbType: string, bType: string, scopePath: string, allowedIn: string[]);
+}
 
 /**
  * Entity Discovery — convention-based auto-discovery of entities from
@@ -150,6 +156,37 @@ interface DiscoverResult {
  */
 declare function discoverEntities(entitiesDir: string): DiscoverResult;
 
+/**
+ * Scope path matching for subgraph-level registry constraints.
+ *
+ * Scope paths are slash-separated names derived from the chain of
+ * `subgraph()` calls (e.g., `'agents'`, `'agents/memories'`).
+ * The root graph has an empty scope path (`''`).
+ *
+ * Patterns:
+ *   - `'root'`              — matches only the root graph (empty scope path)
+ *   - `'agents'`            — matches exactly `'agents'`
+ *   - `'agents/memories'`   — matches exactly `'agents/memories'`
+ *   - `'*​/agents'`          — `*` matches one segment: `'foo/agents'` but not `'a/b/agents'`
+ *   - `'**​/memories'`       — `**` matches zero or more segments
+ *   - `'**'`                — matches everything including root
+ */
+/**
+ * Test whether a scope path matches a single pattern.
+ *
+ * @param scopePath - The current scope path (empty string for root)
+ * @param pattern - The pattern to match against
+ */
+declare function matchScope(scopePath: string, pattern: string): boolean;
+/**
+ * Test whether a scope path matches any pattern in a list.
+ * Returns `true` if the list is empty or undefined (allowed everywhere).
+ *
+ * @param scopePath - The current scope path (empty string for root)
+ * @param patterns - Array of patterns to match against
+ */
+declare function matchScopeAny(scopePath: string, patterns: string[]): boolean;
+
 /**
  * JSON Schema validation and introspection utilities.
  *
@@ -183,4 +220,56 @@ declare function compileSchema(schema: object, label?: string): (data: unknown)
  */
 declare function jsonSchemaToFieldMeta(schema: any): FieldMeta[];
 
-export { BOOTSTRAP_ENTRIES, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryPlan, RegistryEntry, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, jsonSchemaToFieldMeta };
+interface FirestoreIndexField {
+    fieldPath: string;
+    order: 'ASCENDING' | 'DESCENDING';
+}
+interface FirestoreIndex {
+    collectionGroup: string;
+    queryScope: 'COLLECTION';
+    fields: FirestoreIndexField[];
+}
+interface FirestoreIndexConfig {
+    indexes: FirestoreIndex[];
+    fieldOverrides: unknown[];
+}
+/**
+ * Generates a Firestore index configuration for a firegraph collection.
+ *
+ * Always includes the 4 base composite indexes. If an entity discovery result
+ * is provided, generates additional data-field indexes for common query
+ * patterns on node data fields:
+ *   (aType, axbType, data.{field})
+ *
+ * @param collection - Firestore collection name (e.g. 'graph')
+ * @param entities - Optional discovery result for per-entity data field indexes
+ */
+declare function generateIndexConfig(collection: string, entities?: DiscoveryResult): FirestoreIndexConfig;
+
+/**
+ * Result of analyzing a query for collection scan risk.
+ */
+interface QuerySafetyResult {
+    /** Whether the query matches a known indexed pattern. */
+    safe: boolean;
+    /** Human-readable explanation when the query is unsafe. */
+    reason?: string;
+}
+/**
+ * Analyzes a set of query filters to determine whether the query would
+ * likely cause a full collection scan on Firestore Enterprise.
+ *
+ * A query is considered "safe" if the builtin fields present in the filters
+ * match at least one known composite index pattern. Queries that only use
+ * `data.*` fields without a safe base pattern are flagged as unsafe.
+ */
+declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
+
+/**
+ * Default result limit applied to findEdges/findNodes queries
+ * when no explicit limit is provided. Prevents unbounded result sets
+ * that could be expensive on Enterprise Firestore.
+ */
+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 };

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 } from './index-CG3R68Hu.js';
-export { B as BulkBatchError, h as BulkOptions, i as BulkProgress, j as BulkResult, C as CascadeResult, k as CodegenOptions, l as DefineTypeOptions, m as DiscoveredEntity, E as EdgeTopology, n as EdgeTypeData, o as FiregraphConfig, p as GraphBatch, q as GraphTransaction, r as GraphWriter, H as HopDefinition, s as HopResult, N as NodeTypeData, t as QueryFilter, u as QueryMode, v as QueryOptions, S as StoredGraphRecord, w as TraversalOptions, x as TraversalResult, V as ViewContext, y as ViewDefaultsConfig, z as ViewResolverConfig, W as WhereClause, A as defineConfig, I as generateTypes, J as resolveView } from './index-CG3R68Hu.js';
+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';
 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';
 
@@ -99,6 +99,12 @@ declare class TraversalError extends FiregraphError {
 declare class DynamicRegistryError extends FiregraphError {
     constructor(message: string);
 }
+declare class QuerySafetyError extends FiregraphError {
+    constructor(message: string);
+}
+declare class RegistryScopeError extends FiregraphError {
+    constructor(aType: string, axbType: string, bType: string, scopePath: string, allowedIn: string[]);
+}
 
 /**
  * Entity Discovery — convention-based auto-discovery of entities from
@@ -150,6 +156,37 @@ interface DiscoverResult {
  */
 declare function discoverEntities(entitiesDir: string): DiscoverResult;
 
+/**
+ * Scope path matching for subgraph-level registry constraints.
+ *
+ * Scope paths are slash-separated names derived from the chain of
+ * `subgraph()` calls (e.g., `'agents'`, `'agents/memories'`).
+ * The root graph has an empty scope path (`''`).
+ *
+ * Patterns:
+ *   - `'root'`              — matches only the root graph (empty scope path)
+ *   - `'agents'`            — matches exactly `'agents'`
+ *   - `'agents/memories'`   — matches exactly `'agents/memories'`
+ *   - `'*​/agents'`          — `*` matches one segment: `'foo/agents'` but not `'a/b/agents'`
+ *   - `'**​/memories'`       — `**` matches zero or more segments
+ *   - `'**'`                — matches everything including root
+ */
+/**
+ * Test whether a scope path matches a single pattern.
+ *
+ * @param scopePath - The current scope path (empty string for root)
+ * @param pattern - The pattern to match against
+ */
+declare function matchScope(scopePath: string, pattern: string): boolean;
+/**
+ * Test whether a scope path matches any pattern in a list.
+ * Returns `true` if the list is empty or undefined (allowed everywhere).
+ *
+ * @param scopePath - The current scope path (empty string for root)
+ * @param patterns - Array of patterns to match against
+ */
+declare function matchScopeAny(scopePath: string, patterns: string[]): boolean;
+
 /**
  * JSON Schema validation and introspection utilities.
  *
@@ -183,4 +220,56 @@ declare function compileSchema(schema: object, label?: string): (data: unknown)
  */
 declare function jsonSchemaToFieldMeta(schema: any): FieldMeta[];
 
-export { BOOTSTRAP_ENTRIES, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryPlan, RegistryEntry, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, jsonSchemaToFieldMeta };
+interface FirestoreIndexField {
+    fieldPath: string;
+    order: 'ASCENDING' | 'DESCENDING';
+}
+interface FirestoreIndex {
+    collectionGroup: string;
+    queryScope: 'COLLECTION';
+    fields: FirestoreIndexField[];
+}
+interface FirestoreIndexConfig {
+    indexes: FirestoreIndex[];
+    fieldOverrides: unknown[];
+}
+/**
+ * Generates a Firestore index configuration for a firegraph collection.
+ *
+ * Always includes the 4 base composite indexes. If an entity discovery result
+ * is provided, generates additional data-field indexes for common query
+ * patterns on node data fields:
+ *   (aType, axbType, data.{field})
+ *
+ * @param collection - Firestore collection name (e.g. 'graph')
+ * @param entities - Optional discovery result for per-entity data field indexes
+ */
+declare function generateIndexConfig(collection: string, entities?: DiscoveryResult): FirestoreIndexConfig;
+
+/**
+ * Result of analyzing a query for collection scan risk.
+ */
+interface QuerySafetyResult {
+    /** Whether the query matches a known indexed pattern. */
+    safe: boolean;
+    /** Human-readable explanation when the query is unsafe. */
+    reason?: string;
+}
+/**
+ * Analyzes a set of query filters to determine whether the query would
+ * likely cause a full collection scan on Firestore Enterprise.
+ *
+ * A query is considered "safe" if the builtin fields present in the filters
+ * match at least one known composite index pattern. Queries that only use
+ * `data.*` fields without a safe base pattern are flagged as unsafe.
+ */
+declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
+
+/**
+ * Default result limit applied to findEdges/findNodes queries
+ * when no explicit limit is provided. Prevents unbounded result sets
+ * that could be expensive on Enterprise Firestore.
+ */
+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 };