@nicia-ai/typegraph 0.2.0 → 0.3.0

package/dist/manager-Jc5Btay9.d.cts

@@ -0,0 +1,493 @@
+import { a as NodeRegistration, b as EdgeRegistration, D as DeleteBehavior, T as TemporalMode, N as NodeType, c as EdgeTypeWithEndpoints, G as GraphDefaults, A as AnyEdgeType } from './types-DTJEu_-h.cjs';
+import { O as OntologyRelation, S as SerializedNodeDef, a as SerializedEdgeDef, e as SerializedSchema, G as GraphBackend, i as SchemaVersionRow } from './types-DDP0MGBF.cjs';
+
+/** Brand key for GraphDef */
+declare const GRAPH_DEF_BRAND: "__graphDef";
+/**
+ * An edge entry in the graph definition.
+ * Can be:
+ * - EdgeType directly (if it has from/to defined)
+ * - EdgeRegistration object (always works, can override/narrow defaults)
+ */
+type EdgeEntry = EdgeRegistration | EdgeTypeWithEndpoints;
+/**
+ * Normalized edge map type - all entries become EdgeRegistration.
+ */
+type NormalizedEdges<TEdges extends Record<string, EdgeEntry>> = {
+    [K in keyof TEdges]: TEdges[K] extends EdgeRegistration ? TEdges[K] : TEdges[K] extends EdgeTypeWithEndpoints ? EdgeRegistration<TEdges[K], TEdges[K]["from"][number], TEdges[K]["to"][number]> : never;
+};
+/**
+ * Configuration for defineGraph.
+ */
+type GraphDefConfig<TNodes extends Record<string, NodeRegistration>, TEdges extends Record<string, EdgeEntry>, TOntology extends readonly OntologyRelation[]> = Readonly<{
+    /** Unique identifier for this graph */
+    id: string;
+    /** Node registrations */
+    nodes: TNodes;
+    /** Edge registrations or EdgeTypes with built-in domain/range */
+    edges: TEdges;
+    /** Ontology relations */
+    ontology?: TOntology;
+    /** Graph-wide defaults */
+    defaults?: GraphDefaults;
+}>;
+/**
+ * A graph definition.
+ *
+ * This is a compile-time artifact that describes the structure of a graph.
+ * Use `createStore()` to create a runtime store from this definition.
+ */
+type GraphDef<TNodes extends Record<string, NodeRegistration> = Record<string, NodeRegistration>, TEdges extends Record<string, EdgeRegistration> = Record<string, EdgeRegistration>, TOntology extends readonly OntologyRelation[] = readonly OntologyRelation[]> = Readonly<{
+    [GRAPH_DEF_BRAND]: true;
+    id: string;
+    nodes: TNodes;
+    edges: TEdges;
+    ontology: TOntology;
+    defaults: Readonly<{
+        onNodeDelete: DeleteBehavior;
+        temporalMode: TemporalMode;
+    }>;
+}>;
+/**
+ * Extract node kind names from a GraphDef.
+ */
+type NodeKinds<G extends GraphDef> = keyof G["nodes"] & string;
+/**
+ * Extract edge kind names from a GraphDef.
+ */
+type EdgeKinds<G extends GraphDef> = keyof G["edges"] & string;
+/**
+ * Get a NodeType from a GraphDef by kind name.
+ */
+type GetNodeType<G extends GraphDef, K extends NodeKinds<G>> = G["nodes"][K]["type"];
+/**
+ * Get an EdgeType from a GraphDef by kind name.
+ */
+type GetEdgeType<G extends GraphDef, K extends EdgeKinds<G>> = G["edges"][K]["type"];
+/**
+ * Get all NodeTypes from a GraphDef.
+ */
+type AllNodeTypes<G extends GraphDef> = {
+    [K in NodeKinds<G>]: G["nodes"][K]["type"];
+}[NodeKinds<G>];
+/**
+ * Get all EdgeTypes from a GraphDef.
+ */
+type AllEdgeTypes<G extends GraphDef> = {
+    [K in EdgeKinds<G>]: G["edges"][K]["type"];
+}[EdgeKinds<G>];
+/**
+ * Creates a graph definition.
+ *
+ * @example
+ * ```typescript
+ * const graph = defineGraph({
+ *   id: "my_graph",
+ *   nodes: {
+ *     Person: { type: Person },
+ *     Company: { type: Company },
+ *   },
+ *   edges: {
+ *     // Traditional EdgeRegistration syntax
+ *     worksAt: {
+ *       type: worksAt,
+ *       from: [Person],
+ *       to: [Company],
+ *       cardinality: "many",
+ *     },
+ *     // Or use EdgeType directly if it has from/to defined
+ *     knows,  // EdgeType with built-in domain/range
+ *   },
+ *   ontology: [
+ *     subClassOf(Company, Organization),
+ *     disjointWith(Person, Organization),
+ *   ],
+ *   defaults: {
+ *     onNodeDelete: "restrict",
+ *     temporalMode: "current",
+ *   },
+ * });
+ * ```
+ */
+declare function defineGraph<TNodes extends Record<string, NodeRegistration<NodeType>>, TEdges extends Record<string, EdgeEntry>, TOntology extends readonly OntologyRelation[]>(config: GraphDefConfig<TNodes, TEdges, TOntology>): GraphDef<TNodes, NormalizedEdges<TEdges>, TOntology>;
+/**
+ * Checks if a value is a GraphDef.
+ */
+declare function isGraphDef(value: unknown): value is GraphDef;
+/**
+ * Gets all node kind names from a GraphDef.
+ */
+declare function getNodeKinds<G extends GraphDef>(graph: G): readonly string[];
+/**
+ * Gets all edge kind names from a GraphDef.
+ */
+declare function getEdgeKinds<G extends GraphDef>(graph: G): readonly string[];
+
+/**
+ * KindRegistry holds precomputed closures for ontological reasoning.
+ *
+ * Computed at store initialization and cached for fast query-time lookups.
+ */
+declare class KindRegistry {
+    readonly nodeKinds: ReadonlyMap<string, NodeType>;
+    readonly edgeKinds: ReadonlyMap<string, AnyEdgeType>;
+    readonly subClassAncestors: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly subClassDescendants: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly broaderClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly narrowerClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly equivalenceSets: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly iriToKind: ReadonlyMap<string, string>;
+    readonly disjointPairs: ReadonlySet<string>;
+    readonly partOfClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly hasPartClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly edgeInverses: ReadonlyMap<string, string>;
+    readonly edgeImplicationsClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly edgeImplyingClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    constructor(nodeKinds: ReadonlyMap<string, NodeType>, edgeKinds: ReadonlyMap<string, AnyEdgeType>, closures: {
+        subClassAncestors: ReadonlyMap<string, ReadonlySet<string>>;
+        subClassDescendants: ReadonlyMap<string, ReadonlySet<string>>;
+        broaderClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        narrowerClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        equivalenceSets: ReadonlyMap<string, ReadonlySet<string>>;
+        iriToKind: ReadonlyMap<string, string>;
+        disjointPairs: ReadonlySet<string>;
+        partOfClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        hasPartClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        edgeInverses: ReadonlyMap<string, string>;
+        edgeImplicationsClosure: ReadonlyMap<string, ReadonlySet<string>>;
+        edgeImplyingClosure: ReadonlyMap<string, ReadonlySet<string>>;
+    });
+    /**
+     * Checks if child is a subclass of parent (directly or transitively).
+     */
+    isSubClassOf(child: string, parent: string): boolean;
+    /**
+     * Expands a kind to include all its subclasses.
+     * Returns [kind, ...subclasses].
+     */
+    expandSubClasses(kind: string): readonly string[];
+    /**
+     * Gets all ancestors of a kind (via subClassOf).
+     */
+    getAncestors(kind: string): ReadonlySet<string>;
+    /**
+     * Gets all descendants of a kind (via subClassOf).
+     */
+    getDescendants(kind: string): ReadonlySet<string>;
+    /**
+     * Checks if narrowerConcept is narrower than broaderConcept.
+     */
+    isNarrowerThan(narrowerConcept: string, broaderConcept: string): boolean;
+    /**
+     * Checks if broaderConcept is broader than narrowerConcept.
+     */
+    isBroaderThan(broaderConcept: string, narrowerConcept: string): boolean;
+    /**
+     * Expands to include all narrower concepts.
+     */
+    expandNarrower(kind: string): readonly string[];
+    /**
+     * Expands to include all broader concepts.
+     */
+    expandBroader(kind: string): readonly string[];
+    /**
+     * Checks if two kinds are equivalent.
+     */
+    areEquivalent(a: string, b: string): boolean;
+    /**
+     * Gets all equivalents of a kind (including external IRIs).
+     */
+    getEquivalents(kind: string): readonly string[];
+    /**
+     * Resolves an external IRI to an internal kind name.
+     */
+    resolveIri(iri: string): string | undefined;
+    /**
+     * Checks if two kinds are disjoint.
+     */
+    areDisjoint(a: string, b: string): boolean;
+    /**
+     * Gets all kinds that are disjoint with the given kind.
+     */
+    getDisjointKinds(kind: string): readonly string[];
+    /**
+     * Checks if part is part of whole (directly or transitively).
+     */
+    isPartOf(part: string, whole: string): boolean;
+    /**
+     * Gets all wholes that contain this part.
+     */
+    getWholes(part: string): readonly string[];
+    /**
+     * Gets all parts of this whole.
+     */
+    getParts(whole: string): readonly string[];
+    /**
+     * Gets the inverse edge kind for a given edge kind.
+     * If edgeA inverseOf edgeB, then getInverseEdge("edgeA") returns "edgeB".
+     */
+    getInverseEdge(edgeKind: string): string | undefined;
+    /**
+     * Gets all edges implied by a given edge (transitively).
+     * If A implies B and B implies C, then getImpliedEdges("A") returns ["B", "C"].
+     */
+    getImpliedEdges(edgeKind: string): readonly string[];
+    /**
+     * Gets all edges that imply a given edge (transitively).
+     * If A implies B and B implies C, then getImplyingEdges("C") returns ["A", "B"].
+     * Used for query-time expansion: when querying for C, also include A and B edges.
+     */
+    getImplyingEdges(edgeKind: string): readonly string[];
+    /**
+     * Expands an edge kind to include all edges that imply it.
+     * Returns [edgeKind, ...implyingEdges].
+     */
+    expandImplyingEdges(edgeKind: string): readonly string[];
+    /**
+     * Checks if a concrete kind is assignable to a target kind.
+     * Uses subsumption: Company is assignable to Organization if Company subClassOf Organization.
+     */
+    isAssignableTo(concreteKind: string, targetKind: string): boolean;
+    /**
+     * Validates that a kind exists in the registry.
+     */
+    hasNodeType(name: string): boolean;
+    /**
+     * Validates that an edge kind exists in the registry.
+     */
+    hasEdgeType(name: string): boolean;
+    /**
+     * Gets a node kind by name.
+     */
+    getNodeType(name: string): NodeType | undefined;
+    /**
+     * Gets an edge kind by name.
+     */
+    getEdgeType(name: string): AnyEdgeType | undefined;
+}
+
+/**
+ * Schema migration utilities.
+ *
+ * Provides diff detection between schema versions to identify
+ * what has changed and what migrations might be needed.
+ */
+
+/**
+ * Types of changes that can occur in a schema.
+ */
+type ChangeType = "added" | "removed" | "modified" | "renamed";
+/**
+ * Severity of a change for migration purposes.
+ */
+type ChangeSeverity = "safe" | "warning" | "breaking";
+/**
+ * A change to a node definition.
+ */
+type NodeChange = Readonly<{
+    type: ChangeType;
+    kind: string;
+    severity: ChangeSeverity;
+    details: string;
+    before?: SerializedNodeDef | undefined;
+    after?: SerializedNodeDef | undefined;
+}>;
+/**
+ * A change to an edge definition.
+ */
+type EdgeChange = Readonly<{
+    type: ChangeType;
+    kind: string;
+    severity: ChangeSeverity;
+    details: string;
+    before?: SerializedEdgeDef | undefined;
+    after?: SerializedEdgeDef | undefined;
+}>;
+/**
+ * A change to the ontology.
+ */
+type OntologyChange = Readonly<{
+    type: ChangeType;
+    entity: "metaEdge" | "relation";
+    name: string;
+    severity: ChangeSeverity;
+    details: string;
+}>;
+/**
+ * A complete diff between two schema versions.
+ */
+type SchemaDiff = Readonly<{
+    fromVersion: number;
+    toVersion: number;
+    /** Changes to node definitions */
+    nodes: readonly NodeChange[];
+    /** Changes to edge definitions */
+    edges: readonly EdgeChange[];
+    /** Changes to ontology */
+    ontology: readonly OntologyChange[];
+    /** Whether any breaking changes exist */
+    hasBreakingChanges: boolean;
+    /** Whether the change is backwards compatible (no breaking changes) */
+    isBackwardsCompatible: boolean;
+    /** Whether any changes exist at all */
+    hasChanges: boolean;
+    /** Summary of changes */
+    summary: string;
+}>;
+/**
+ * Computes the diff between two schema versions.
+ *
+ * @param before - The previous schema version
+ * @param after - The new schema version
+ * @returns A diff describing all changes
+ */
+declare function computeSchemaDiff(before: SerializedSchema, after: SerializedSchema): SchemaDiff;
+/**
+ * Checks if a schema change is backwards compatible.
+ *
+ * A change is backwards compatible if:
+ * - No nodes or edges were removed
+ * - No required properties were added
+ * - No existing properties were removed
+ */
+declare function isBackwardsCompatible(diff: SchemaDiff): boolean;
+/**
+ * Gets a list of actions needed for migration.
+ */
+declare function getMigrationActions(diff: SchemaDiff): readonly string[];
+
+/**
+ * Schema manager for TypeGraph.
+ *
+ * Provides schema lifecycle management:
+ * - Initialization on first store creation
+ * - Validation on store open
+ * - Auto-migration for safe changes
+ * - Error reporting for breaking changes
+ */
+
+/**
+ * Result of schema validation.
+ */
+type SchemaValidationResult = {
+    status: "initialized";
+    version: number;
+} | {
+    status: "unchanged";
+    version: number;
+} | {
+    status: "migrated";
+    fromVersion: number;
+    toVersion: number;
+    diff: SchemaDiff;
+} | {
+    status: "pending";
+    version: number;
+    diff: SchemaDiff;
+} | {
+    status: "breaking";
+    diff: SchemaDiff;
+    actions: readonly string[];
+};
+/**
+ * Context passed to migration lifecycle hooks.
+ *
+ * Hooks are intended for observability (logging, metrics, alerts),
+ * not for data transformations. Use an explicit migration runner
+ * for backfill scripts — see the schema evolution guide.
+ */
+type MigrationHookContext = Readonly<{
+    graphId: string;
+    fromVersion: number;
+    toVersion: number;
+    diff: SchemaDiff;
+}>;
+/**
+ * Options for schema management.
+ */
+type SchemaManagerOptions = Readonly<{
+    /** If true, auto-migrate safe changes. Default: true */
+    autoMigrate?: boolean;
+    /** If true, throw on breaking changes. Default: true */
+    throwOnBreaking?: boolean;
+    /** Called before a safe auto-migration is applied. For observability only. */
+    onBeforeMigrate?: (context: MigrationHookContext) => void | Promise<void>;
+    /** Called after a safe auto-migration is applied. For observability only. */
+    onAfterMigrate?: (context: MigrationHookContext) => void | Promise<void>;
+}>;
+/**
+ * Ensures the schema is initialized and up-to-date.
+ *
+ * This is the main entry point for schema management. It:
+ * 1. Initializes the schema if this is the first run (version 1)
+ * 2. Returns "unchanged" if the schema matches the current graph
+ * 3. Auto-migrates safe changes if autoMigrate is true
+ * 4. Throws MigrationError for breaking changes if throwOnBreaking is true
+ *
+ * @param backend - The database backend
+ * @param graph - The current graph definition
+ * @param options - Schema management options
+ * @returns The result of schema validation
+ * @throws MigrationError if breaking changes detected and throwOnBreaking is true
+ */
+declare function ensureSchema<G extends GraphDef>(backend: GraphBackend, graph: G, options?: SchemaManagerOptions): Promise<SchemaValidationResult>;
+/**
+ * Initializes the schema for a new graph.
+ *
+ * Creates version 1 of the schema and marks it as active.
+ *
+ * @param backend - The database backend
+ * @param graph - The graph definition
+ * @returns The created schema version row
+ */
+declare function initializeSchema<G extends GraphDef>(backend: GraphBackend, graph: G): Promise<SchemaVersionRow>;
+/**
+ * Migrates the schema to match the current graph definition.
+ *
+ * This creates a new schema version and marks it as active.
+ * The old version is preserved for history/rollback.
+ *
+ * @param backend - The database backend
+ * @param graph - The current graph definition
+ * @param currentVersion - The current active schema version
+ * @returns The new version number
+ */
+declare function migrateSchema<G extends GraphDef>(backend: GraphBackend, graph: G, currentVersion: number): Promise<number>;
+/**
+ * Rolls back the active schema to a previous version.
+ *
+ * The target version must already exist in the version history.
+ * This does not delete newer versions — it simply switches the active pointer.
+ *
+ * @param backend - The database backend
+ * @param graphId - The graph ID
+ * @param targetVersion - The version to roll back to
+ * @throws MigrationError if the target version does not exist
+ */
+declare function rollbackSchema(backend: GraphBackend, graphId: string, targetVersion: number): Promise<void>;
+/**
+ * Gets the current active schema for a graph.
+ *
+ * @param backend - The database backend
+ * @param graphId - The graph ID
+ * @returns The active schema or undefined if not initialized
+ */
+declare function getActiveSchema(backend: GraphBackend, graphId: string): Promise<SerializedSchema | undefined>;
+/**
+ * Checks if a graph's schema has been initialized.
+ *
+ * @param backend - The database backend
+ * @param graphId - The graph ID
+ * @returns True if the schema has been initialized
+ */
+declare function isSchemaInitialized(backend: GraphBackend, graphId: string): Promise<boolean>;
+/**
+ * Gets the schema diff between the stored schema and current graph.
+ *
+ * @param backend - The database backend
+ * @param graph - The current graph definition
+ * @returns The diff, or undefined if schema not initialized
+ */
+declare function getSchemaChanges<G extends GraphDef>(backend: GraphBackend, graph: G): Promise<SchemaDiff | undefined>;
+
+export { type AllEdgeTypes as A, type ChangeSeverity as C, type EdgeChange as E, type GraphDef as G, KindRegistry as K, type MigrationHookContext as M, type NodeChange as N, type OntologyChange as O, type SchemaDiff as S, type ChangeType as a, type SchemaManagerOptions as b, type SchemaValidationResult as c, computeSchemaDiff as d, ensureSchema as e, getMigrationActions as f, getActiveSchema as g, getSchemaChanges as h, initializeSchema as i, isBackwardsCompatible as j, isSchemaInitialized as k, type AllNodeTypes as l, migrateSchema as m, type EdgeKinds as n, type GetEdgeType as o, type GetNodeType as p, type NodeKinds as q, rollbackSchema as r, defineGraph as s, getEdgeKinds as t, getNodeKinds as u, isGraphDef as v };