@typicalday/firegraph 0.1.0

package/dist/index-CG3R68Hu.d.cts

@@ -0,0 +1,414 @@
+import { Timestamp, FieldValue, WhereFilterOp } from '@google-cloud/firestore';
+
+/**
+ * Firegraph Configuration — project-level config file support.
+ *
+ * Projects create a `firegraph.config.ts` (or `.js`/`.mjs`) in their root:
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'firegraph';
+ *
+ * export default defineConfig({
+ *   entities: './entities',
+ *   project: 'my-project',
+ *   collection: 'graph',
+ * });
+ * ```
+ */
+/** Display contexts where views can appear. */
+type ViewContext = 'listing' | 'detail' | 'inline';
+/** View resolution configuration for a single entity type. */
+interface ViewResolverConfig {
+    /** Default view name (e.g. 'card'). Falls back to 'json' if unset. */
+    default?: string;
+    /** View to use in NodeBrowser listing rows. */
+    listing?: string;
+    /** View to use on the NodeDetail page. */
+    detail?: string;
+    /** View to use for inline/embedded previews (edge rows, traversal). */
+    inline?: string;
+}
+/** Declarative view defaults, keyed by entity type. */
+interface ViewDefaultsConfig {
+    /** Node view defaults keyed by aType (e.g. 'user', 'task'). */
+    nodes?: Record<string, ViewResolverConfig>;
+    /** Edge view defaults keyed by axbType (e.g. 'hasDeparture'). */
+    edges?: Record<string, ViewResolverConfig>;
+}
+/** Project-level firegraph configuration. */
+interface FiregraphConfig {
+    /** Path to entities directory (per-entity folder convention). */
+    entities?: string;
+    /** GCP project ID. */
+    project?: string;
+    /** Firestore collection path (default: 'graph'). */
+    collection?: string;
+    /** Firestore emulator address (e.g. '127.0.0.1:8080'). */
+    emulator?: string;
+    /**
+     * Query execution backend.
+     *
+     * - `'pipeline'` (default) — Uses Firestore Pipeline API. Requires Enterprise
+     *   Firestore. Enables indexless queries on `data.*` fields.
+     * - `'standard'` — Uses standard Firestore `.where().get()` queries. Not
+     *   recommended for production. See README for risk details.
+     *
+     * When the emulator is active, always falls back to `'standard'`.
+     */
+    queryMode?: QueryMode;
+    /**
+     * AI chat configuration. Auto-detects `claude` CLI on PATH by default.
+     * Set to `false` to disable chat even if claude is available.
+     */
+    chat?: false | {
+        /** Claude model to use (default: 'sonnet'). */
+        model?: string;
+        /** Maximum concurrent claude processes (default: 2). */
+        maxConcurrency?: number;
+    };
+    /** Editor-specific settings. */
+    editor?: {
+        /** Server port (default: 3883). */
+        port?: number;
+        /** Force read-only mode. */
+        readonly?: boolean;
+    };
+    /** Declarative view defaults per entity type (overrides per-entity meta.json). */
+    viewDefaults?: ViewDefaultsConfig;
+    /**
+     * Dynamic registry mode. When set, the editor loads type definitions
+     * from Firestore meta-nodes in addition to filesystem entities.
+     * Filesystem types take precedence on name conflicts.
+     */
+    registryMode?: DynamicRegistryConfig;
+}
+/**
+ * Identity function providing type-checking and autocomplete for config files.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'firegraph';
+ * export default defineConfig({ entities: './entities' });
+ * ```
+ */
+declare function defineConfig(config: FiregraphConfig): FiregraphConfig;
+/**
+ * Resolve which view to show for a given entity.
+ *
+ * 1. If `context` is provided and a context-specific default exists, use it.
+ * 2. Falls back to `resolverConfig.default`.
+ * 3. Ultimate fallback: `'json'`.
+ *
+ * Only returns view names that exist in `availableViewNames`.
+ */
+declare function resolveView(resolverConfig: ViewResolverConfig | undefined, availableViewNames: string[], context?: ViewContext): string;
+
+interface GraphRecord {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    createdAt: Timestamp | FieldValue;
+    updatedAt: Timestamp | FieldValue;
+}
+interface StoredGraphRecord {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+}
+interface WhereClause {
+    field: string;
+    op: '==' | '!=' | '<' | '<=' | '>' | '>=';
+    value: unknown;
+}
+interface FindEdgesParams {
+    aType?: string;
+    aUid?: string;
+    axbType?: string;
+    bType?: string;
+    bUid?: string;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    where?: WhereClause[];
+}
+interface FindNodesParams {
+    aType: string;
+}
+interface QueryOptions {
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+}
+type QueryPlan = {
+    strategy: 'get';
+    docId: string;
+} | {
+    strategy: 'query';
+    filters: QueryFilter[];
+    options?: QueryOptions;
+};
+interface QueryFilter {
+    field: string;
+    op: WhereFilterOp;
+    value: unknown;
+}
+interface RegistryEntry {
+    aType: string;
+    axbType: string;
+    bType: string;
+    /** JSON Schema object for the data payload. */
+    jsonSchema?: object;
+    description?: string;
+    inverseLabel?: string;
+    /** Data field to use as the display title (e.g. 'name', 'date'). */
+    titleField?: string;
+    /** Data field to use as the display subtitle (e.g. 'status', 'difficulty'). */
+    subtitleField?: string;
+}
+/** Topology declaration for an edge (from edge.json). */
+interface EdgeTopology {
+    from: string | string[];
+    to: string | string[];
+    inverseLabel?: string;
+}
+/** A discovered entity from the per-entity folder convention. */
+interface DiscoveredEntity {
+    kind: 'node' | 'edge';
+    name: string;
+    /** Parsed JSON Schema for the data payload. */
+    schema: object;
+    /** Edge topology (only for edges). */
+    topology?: EdgeTopology;
+    description?: string;
+    /** Data field to use as the display title (e.g. 'name', 'date'). */
+    titleField?: string;
+    /** Data field to use as the display subtitle (e.g. 'status', 'difficulty'). */
+    subtitleField?: string;
+    /** View defaults from meta.json. */
+    viewDefaults?: ViewResolverConfig;
+    /** Absolute path to views.ts if present. */
+    viewsPath?: string;
+    /** Sample data from sample.json. */
+    sampleData?: Record<string, unknown>;
+}
+/** Result of scanning an entities directory. */
+interface DiscoveryResult {
+    nodes: Map<string, DiscoveredEntity>;
+    edges: Map<string, DiscoveredEntity>;
+}
+/** Controls which Firestore query backend is used. */
+type QueryMode = 'pipeline' | 'standard';
+/**
+ * Configuration for dynamic registry mode where type definitions
+ * are stored as graph data (meta-nodes) rather than in code.
+ */
+interface DynamicRegistryConfig {
+    mode: 'dynamic';
+    /**
+     * Collection path for meta-type nodes (`nodeType`, `edgeType`).
+     * Defaults to the main `collectionPath` if omitted.
+     */
+    collection?: string;
+}
+/** Options for defineNodeType / defineEdgeType beyond the core fields. */
+interface DefineTypeOptions {
+    /** Data field to use as the display title (e.g. 'name', 'date'). */
+    titleField?: string;
+    /** Data field to use as the display subtitle (e.g. 'status', 'difficulty'). */
+    subtitleField?: string;
+    /** Mustache HTML template for rendering this type in the editor. */
+    viewTemplate?: string;
+    /** Scoped CSS for the view template (injected via Shadow DOM). */
+    viewCss?: string;
+}
+/** Data shape stored in a `nodeType` meta-node. */
+interface NodeTypeData {
+    name: string;
+    jsonSchema: object;
+    description?: string;
+    titleField?: string;
+    subtitleField?: string;
+    viewTemplate?: string;
+    viewCss?: string;
+}
+/** Data shape stored in an `edgeType` meta-node. */
+interface EdgeTypeData {
+    name: string;
+    from: string | string[];
+    to: string | string[];
+    jsonSchema?: object;
+    inverseLabel?: string;
+    description?: string;
+    titleField?: string;
+    subtitleField?: string;
+    viewTemplate?: string;
+    viewCss?: string;
+}
+interface GraphClientOptions {
+    /** Static registry built from code/discovery. Ignored if registryMode is set. */
+    registry?: GraphRegistry;
+    /** Dynamic registry mode — type definitions stored as graph data. */
+    registryMode?: DynamicRegistryConfig;
+    /**
+     * Query execution backend.
+     *
+     * - `'pipeline'` (default) — Uses Firestore Pipeline API. Requires Enterprise
+     *   Firestore. Enables indexless queries on `data.*` fields.
+     * - `'standard'` — Uses standard Firestore `.where().get()` queries. Requires
+     *   composite indexes for `data.*` filters or risks full collection scans
+     *   (Enterprise) / query failures (Standard Firestore).
+     *
+     * When `FIRESTORE_EMULATOR_HOST` is set, the client auto-falls back to
+     * `'standard'` regardless of this setting (emulator doesn't support pipelines).
+     */
+    queryMode?: QueryMode;
+}
+interface GraphRegistry {
+    validate(aType: string, axbType: string, bType: string, data: unknown): void;
+    lookup(aType: string, axbType: string, bType: string): RegistryEntry | undefined;
+    entries(): ReadonlyArray<RegistryEntry>;
+}
+interface GraphReader {
+    getNode(uid: string): Promise<StoredGraphRecord | null>;
+    getEdge(aUid: string, axbType: string, bUid: string): Promise<StoredGraphRecord | null>;
+    edgeExists(aUid: string, axbType: string, bUid: string): Promise<boolean>;
+    findEdges(params: FindEdgesParams): Promise<StoredGraphRecord[]>;
+    findNodes(params: FindNodesParams): Promise<StoredGraphRecord[]>;
+}
+interface GraphWriter {
+    putNode(aType: string, uid: string, data: Record<string, unknown>): Promise<void>;
+    putEdge(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
+    updateNode(uid: string, data: Record<string, unknown>): Promise<void>;
+    removeNode(uid: string): Promise<void>;
+    removeEdge(aUid: string, axbType: string, bUid: string): Promise<void>;
+}
+interface GraphClient extends GraphReader, GraphWriter {
+    runTransaction<T>(fn: (tx: GraphTransaction) => Promise<T>): Promise<T>;
+    batch(): GraphBatch;
+    /** Delete a node and all its outgoing/incoming edges in chunked batches. */
+    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>;
+}
+interface DynamicGraphClient extends GraphClient {
+    /** Define or update a node type in the dynamic registry. */
+    defineNodeType(name: string, jsonSchema: object, description?: string, options?: DefineTypeOptions): Promise<void>;
+    /** Define or update an edge type in the dynamic registry. */
+    defineEdgeType(name: string, topology: EdgeTopology, jsonSchema?: object, description?: string, options?: DefineTypeOptions): Promise<void>;
+    /** Reload the registry from meta-type nodes in the graph. */
+    reloadRegistry(): Promise<void>;
+}
+interface GraphTransaction extends GraphReader, GraphWriter {
+}
+interface GraphBatch extends GraphWriter {
+    commit(): Promise<void>;
+}
+interface HopDefinition {
+    axbType: string;
+    direction?: 'forward' | 'reverse';
+    aType?: string;
+    bType?: string;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    filter?: (edge: StoredGraphRecord) => boolean;
+}
+interface TraversalOptions {
+    maxReads?: number;
+    concurrency?: number;
+    returnIntermediates?: boolean;
+}
+interface HopResult {
+    axbType: string;
+    depth: number;
+    edges: StoredGraphRecord[];
+    sourceCount: number;
+    truncated: boolean;
+}
+interface TraversalResult {
+    nodes: StoredGraphRecord[];
+    hops: HopResult[];
+    totalReads: number;
+    truncated: boolean;
+}
+interface TraversalBuilder {
+    follow(axbType: string, options?: Omit<HopDefinition, 'axbType'>): TraversalBuilder;
+    run(options?: TraversalOptions): Promise<TraversalResult>;
+}
+interface BulkOptions {
+    /** Max operations per Firestore batch (default 500, Firestore hard limit). */
+    batchSize?: number;
+    /** Number of retry attempts per failed batch (default 3). */
+    maxRetries?: number;
+    /** Called after each batch commits. */
+    onProgress?: (progress: BulkProgress) => void;
+}
+interface BulkProgress {
+    /** Batches committed so far. */
+    completedBatches: number;
+    /** Total batches planned. */
+    totalBatches: number;
+    /** Total documents deleted so far. */
+    deletedSoFar: number;
+}
+interface BulkResult {
+    /** Total documents successfully deleted. */
+    deleted: number;
+    /** Number of batches committed. */
+    batches: number;
+    /** Errors from batches that failed after all retries. */
+    errors: BulkBatchError[];
+}
+interface BulkBatchError {
+    /** Zero-based index of the failed batch. */
+    batchIndex: number;
+    /** The underlying error. */
+    error: Error;
+    /** Number of operations in this batch that were not applied. */
+    operationCount: number;
+}
+interface CascadeResult extends BulkResult {
+    /** Number of edges deleted. */
+    edgesDeleted: number;
+    /** Whether the node itself was deleted. */
+    nodeDeleted: boolean;
+}
+
+/**
+ * Code generation — produces TypeScript type definitions from JSON Schema
+ * files discovered via the entity folder convention.
+ *
+ * Uses `json-schema-to-typescript` to compile each entity's `schema.json`
+ * into a TypeScript interface.
+ *
+ * Naming convention:
+ * - Nodes:  `{PascalName}Data`       (e.g. `TaskData`)
+ * - Edges:  `{PascalName}EdgeData`   (e.g. `HasStepEdgeData`)
+ */
+
+interface CodegenOptions {
+    /** Add banner comment at top of output. Defaults to true. */
+    banner?: boolean;
+}
+/**
+ * Generate TypeScript type definitions from a DiscoveryResult.
+ * Returns the full file content as a string.
+ */
+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 };