@typicalday/firegraph 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+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';
+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';
+
+declare function createGraphClient(db: Firestore, collectionPath: string, options: GraphClientOptions & {
+    registryMode: DynamicRegistryConfig;
+}): DynamicGraphClient;
+declare function createGraphClient(db: Firestore, collectionPath: string, options?: GraphClientOptions): GraphClient;
+
+/**
+ * Build a registry from either explicit entries or a DiscoveryResult.
+ *
+ * @example
+ * ```ts
+ * // From explicit entries (programmatic)
+ * const registry = createRegistry([
+ *   { aType: 'user', axbType: 'is', bType: 'user', jsonSchema: userSchema },
+ *   { aType: 'user', axbType: 'follows', bType: 'user', jsonSchema: followsSchema },
+ * ]);
+ *
+ * // From discovery result (folder convention)
+ * const discovered = await discoverEntities('./entities');
+ * const registry = createRegistry(discovered);
+ * ```
+ */
+declare function createRegistry(input: RegistryEntry[] | DiscoveryResult): GraphRegistry;
+
+/** The aType used for node type definition meta-nodes. */
+declare const META_NODE_TYPE = "nodeType";
+/** The aType used for edge type definition meta-nodes. */
+declare const META_EDGE_TYPE = "edgeType";
+/** JSON Schema for the `data` payload of a `nodeType` meta-node. */
+declare const NODE_TYPE_SCHEMA: object;
+/** JSON Schema for the `data` payload of an `edgeType` meta-node. */
+declare const EDGE_TYPE_SCHEMA: object;
+/** Registry entries for the two meta-types (always present). */
+declare const BOOTSTRAP_ENTRIES: readonly RegistryEntry[];
+/**
+ * Build the bootstrap registry that validates meta-type writes.
+ * This is always available, even before any dynamic types are loaded.
+ */
+declare function createBootstrapRegistry(): GraphRegistry;
+/**
+ * Generate a deterministic UID for a meta-type definition.
+ * This ensures that defining the same type name always targets the same
+ * Firestore document, enabling upsert semantics.
+ *
+ * Format: 21-char base64url substring of SHA-256(`metaType:name`).
+ */
+declare function generateDeterministicUid(metaType: string, name: string): string;
+/**
+ * Read meta-type nodes from the graph and compile them into a GraphRegistry.
+ *
+ * The returned registry includes both the dynamic entries AND the bootstrap
+ * meta-type entries, so meta-type writes remain validateable after a reload.
+ *
+ * @param reader - A GraphReader pointed at the collection containing meta-nodes.
+ */
+declare function createRegistryFromGraph(reader: GraphReader): Promise<GraphRegistry>;
+
+declare function generateId(): string;
+
+declare function computeNodeDocId(uid: string): string;
+declare function computeEdgeDocId(aUid: string, axbType: string, bUid: string): string;
+
+declare function buildNodeRecord(aType: string, uid: string, data: Record<string, unknown>): GraphRecord;
+declare function buildEdgeRecord(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): GraphRecord;
+
+declare function buildEdgeQueryPlan(params: FindEdgesParams): QueryPlan;
+declare function buildNodeQueryPlan(params: FindNodesParams): QueryPlan;
+
+declare function createTraversal(reader: GraphReader, startUid: string): TraversalBuilder;
+
+declare class FiregraphError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare class NodeNotFoundError extends FiregraphError {
+    constructor(uid: string);
+}
+declare class EdgeNotFoundError extends FiregraphError {
+    constructor(aUid: string, axbType: string, bUid: string);
+}
+declare class ValidationError extends FiregraphError {
+    readonly details?: unknown | undefined;
+    constructor(message: string, details?: unknown | undefined);
+}
+declare class RegistryViolationError extends FiregraphError {
+    constructor(aType: string, axbType: string, bType: string);
+}
+declare class InvalidQueryError extends FiregraphError {
+    constructor(message: string);
+}
+declare class TraversalError extends FiregraphError {
+    constructor(message: string);
+}
+declare class DynamicRegistryError extends FiregraphError {
+    constructor(message: string);
+}
+
+/**
+ * Entity Discovery — convention-based auto-discovery of entities from
+ * a per-entity folder structure.
+ *
+ * Scans `entitiesDir/nodes/` and `entitiesDir/edges/` subdirectories.
+ * Each subfolder is treated as an entity type.
+ *
+ * Schema files can be either `schema.json` (plain JSON Schema) or
+ * `schema.ts` / `schema.js` (a module whose default export is a JSON Schema
+ * object). When both exist, the TS/JS file takes precedence so that authors
+ * can compose schemas programmatically while keeping a JSON fallback.
+ *
+ * @example
+ * ```
+ * entities/
+ *   nodes/
+ *     task/
+ *       schema.json | schema.ts   (required — one or both)
+ *       views.ts                  (optional)
+ *       sample.json               (optional)
+ *       meta.json                 (optional)
+ *   edges/
+ *     hasStep/
+ *       schema.json | schema.ts   (required — one or both)
+ *       edge.json                 (required — topology)
+ *       views.ts                  (optional)
+ *       sample.json               (optional)
+ *       meta.json                 (optional)
+ * ```
+ */
+
+declare class DiscoveryError extends FiregraphError {
+    constructor(message: string);
+}
+interface DiscoveryWarning {
+    code: 'DANGLING_TOPOLOGY_REF';
+    message: string;
+}
+interface DiscoverResult {
+    result: DiscoveryResult;
+    warnings: DiscoveryWarning[];
+}
+/**
+ * Scan an entities directory and return all discovered nodes and edges.
+ *
+ * @param entitiesDir - Path to the entities directory (absolute or relative to cwd)
+ * @returns Discovery result with nodes and edges maps, plus any warnings
+ */
+declare function discoverEntities(entitiesDir: string): DiscoverResult;
+
+/**
+ * JSON Schema validation and introspection utilities.
+ *
+ * Standard JSON Schema validation and introspection
+ * processing. Uses ajv for validation and a recursive walker for converting
+ * JSON Schema properties into FieldMeta objects for editor form generation.
+ */
+interface FieldMeta {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'unknown';
+    required: boolean;
+    description?: string;
+    enumValues?: string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    min?: number;
+    max?: number;
+    isInt?: boolean;
+    itemMeta?: FieldMeta;
+    fields?: FieldMeta[];
+}
+/**
+ * Compile a JSON Schema into a validation function.
+ * The returned function throws `ValidationError` if data is invalid.
+ */
+declare function compileSchema(schema: object, label?: string): (data: unknown) => void;
+/**
+ * Convert a JSON Schema (expected to be `type: "object"`) into `FieldMeta[]`
+ * suitable for the editor's SchemaForm component.
+ */
+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 };