@nicia-ai/typegraph 0.13.0 → 0.15.0

package/dist/{store-Bmdt_dS6.d.cts → store-BNercm8P.d.cts}

@@ -1,5 +1,5 @@
-import { S as SqlSchema, G as GraphBackend, T as TransactionBackend } from './types-GLkwvQvS.cjs';
-import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, f as SchemaValidationResult } from './manager-DGSnJa1v.cjs';
+import { S as SqlSchema, G as GraphBackend, T as TransactionBackend, E as EdgeRow, N as NodeRow } from './types-B3mmOMJV.cjs';
+import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, d as SchemaValidationResult } from './manager-Bj1UEnhE.cjs';
 import { S as SqlDialect, N as NodeType, A as AnyEdgeType, T as TemporalMode, E as EdgeType, d as EdgeRegistration, b as EdgeId, g as NodeId, i as NodeRegistration } from './types-DMzKq0d5.cjs';
 import { z } from 'zod';
 import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, o as RecursiveCyclePolicy, q as TraversalDirection, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-Bh2NDeaK.cjs';
@@ -610,16 +610,40 @@ type CreateQueryBuilderOptions = Readonly<{
  * Store types for TypeGraph operations.
  */
 
+/**
+ * Canonical mapping from snake_case row fields to camelCase meta fields.
+ *
+ * This is the single source of truth for which row columns become metadata.
+ * Both the Meta types and the row-to-meta functions in row-mappers.ts must
+ * stay in sync with this mapping. If you add a temporal/audit column to a
+ * row type, add the mapping here — the compiler will then force you to
+ * update the row mapper functions as well (since their return type is
+ * NodeMeta/EdgeMeta, which is derived from this mapping).
+ */
+type TemporalMetaFieldMap = Readonly<{
+    valid_from: "validFrom";
+    valid_to: "validTo";
+    created_at: "createdAt";
+    updated_at: "updatedAt";
+    deleted_at: "deletedAt";
+}>;
+/**
+ * Maps row fields to their camelCase meta counterparts, preserving types.
+ */
+type MapRowToMeta<R extends Readonly<Record<string, unknown>>, M extends Readonly<Record<string, string>>> = Readonly<{
+    [SnakeKey in keyof M as M[SnakeKey] & string]: SnakeKey extends keyof R ? R[SnakeKey] : never;
+}>;
 /**
  * Metadata for a node instance.
+ * Derived from NodeRow via TemporalMetaFieldMap + version.
+ *
+ * Adding a new metadata column requires:
+ * 1. Add the column to NodeRow in backend/types.ts
+ * 2. Add the mapping to TemporalMetaFieldMap above
+ * 3. The compiler will error in rowToNodeMeta() until you add the field there
  */
-type NodeMeta = Readonly<{
-    version: number;
-    validFrom: string | undefined;
-    validTo: string | undefined;
-    createdAt: string;
-    updatedAt: string;
-    deletedAt: string | undefined;
+type NodeMeta = MapRowToMeta<NodeRow, TemporalMetaFieldMap> & Readonly<{
+    version: NodeRow["version"];
 }>;
 /**
  * A node instance in the graph.
@@ -654,14 +678,9 @@ type UpdateNodeInput<N extends NodeType = NodeType> = Readonly<{
 }>;
 /**
  * Metadata for an edge instance.
+ * Derived from EdgeRow via TemporalMetaFieldMap (edges have no version).
  */
-type EdgeMeta = Readonly<{
-    validFrom: string | undefined;
-    validTo: string | undefined;
-    createdAt: string;
-    updatedAt: string;
-    deletedAt: string | undefined;
-}>;
+type EdgeMeta = MapRowToMeta<EdgeRow, TemporalMetaFieldMap>;
 /**
  * An edge instance in the graph.
  *
@@ -1247,6 +1266,14 @@ type EdgeToTypes<R extends EdgeRegistration> = R["to"] extends readonly (infer N
  * Extracts the edge type and from/to node types automatically.
  */
 type TypedEdgeCollection<R extends EdgeRegistration> = EdgeCollection<R["type"], EdgeFromTypes<R> extends NodeType ? EdgeFromTypes<R> : NodeType, EdgeToTypes<R> extends NodeType ? EdgeToTypes<R> : NodeType>;
+/** Mapped type of all node collections for a graph. */
+type GraphNodeCollections<G extends GraphDef> = {
+    [K in keyof G["nodes"] & string]-?: NodeCollection<G["nodes"][K]["type"], ConstraintNames<G["nodes"][K]>>;
+};
+/** Mapped type of all edge collections for a graph. */
+type GraphEdgeCollections<G extends GraphDef> = {
+    [K in keyof G["edges"] & string]-?: TypedEdgeCollection<G["edges"][K]>;
+};
 /**
  * A typed transaction context with collection API.
  *
@@ -1258,20 +1285,50 @@ type TypedEdgeCollection<R extends EdgeRegistration> = EdgeCollection<R["type"],
  * await store.transaction(async (tx) => {
  *   const person = await tx.nodes.Person.create({ name: "Alice" });
  *   const company = await tx.nodes.Company.create({ name: "Acme" });
- *   // Pass nodes directly - their kind and id properties are used
  *   await tx.edges.worksAt.create(person, company, { role: "Engineer" });
  * });
  * ```
  */
 type TransactionContext<G extends GraphDef> = Readonly<{
-    /** Node collections for the transaction */
+    nodes: GraphNodeCollections<G>;
+    edges: GraphEdgeCollections<G>;
+}>;
+/**
+ * A type-level projection of a store's surface onto a subset of its
+ * node and edge collections.
+ *
+ * Node collections are projected with constraint names erased (`never`),
+ * so constraint-based methods like `findByConstraint` become uncallable.
+ * This is intentional: unique constraints are graph-registration-level
+ * details that differ between graphs sharing the same node types.
+ *
+ * @example
+ * ```typescript
+ * type CoreStore = StoreProjection<
+ *   typeof myGraph,
+ *   "Document" | "Chunk",
+ *   "hasChunk"
+ * >;
+ *
+ * async function ingestChunk(
+ *   store: CoreStore,
+ *   document: Node<typeof Document>,
+ *   text: string,
+ * ) {
+ *   const chunk = await store.nodes.Chunk.create({ text });
+ *   await store.edges.hasChunk.create(document, chunk);
+ *   return chunk;
+ * }
+ * ```
+ *
+ * Both `Store<G>` and `TransactionContext<G>` are structurally assignable
+ * to a `StoreProjection` whose keys are a subset of `G`.
+ */
+type StoreProjection<G extends GraphDef, N extends keyof G["nodes"] & string = never, E extends keyof G["edges"] & string = never> = Readonly<{
     nodes: {
-        [K in keyof G["nodes"] & string]-?: NodeCollection<G["nodes"][K]["type"], ConstraintNames<G["nodes"][K]>>;
-    };
-    /** Edge collections for the transaction */
-    edges: {
-        [K in keyof G["edges"] & string]-?: TypedEdgeCollection<G["edges"][K]>;
+        [K in N]-?: NodeCollection<G["nodes"][K]["type"], never>;
     };
+    edges: Pick<GraphEdgeCollections<G>, E>;
 }>;
 
 /**
@@ -1756,7 +1813,8 @@ declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, Edg
     constructor(config: QueryBuilderConfig, state: QueryBuilderState, edgeKinds: readonly string[], edgeAlias: EA, direction: Dir, fromAlias: string, inverseEdgeKinds?: readonly string[], optional?: Optional, variableLength?: VariableLengthState, pendingEdgePredicates?: readonly NodePredicate[]);
     /**
      * Enables variable-length (recursive) traversal.
-     * By default, traverses unlimited depth with cycle prevention.
+     * Defaults to MAX_RECURSIVE_DEPTH (10) hops with cycle prevention.
+     * Use `maxHops` to override (up to MAX_EXPLICIT_RECURSIVE_DEPTH).
      */
     recursive<const O extends RecursiveTraversalOptions = Record<string, never>>(options?: O): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional, O extends {
         depth: infer D extends boolean | string;
@@ -2027,9 +2085,7 @@ declare class Store<G extends GraphDef> {
      * const people = await store.nodes.Person.find({ limit: 10 });
      * ```
      */
-    get nodes(): {
-        [K in keyof G["nodes"] & string]-?: NodeCollection<G["nodes"][K]["type"], ConstraintNames<G["nodes"][K]>>;
-    };
+    get nodes(): GraphNodeCollections<G>;
     /**
      * Edge collections for ergonomic CRUD operations.
      *
@@ -2046,9 +2102,7 @@ declare class Store<G extends GraphDef> {
      * const edges = await store.edges.worksAt.findFrom({ kind: "Person", id: person.id });
      * ```
      */
-    get edges(): {
-        [K in keyof G["edges"] & string]-?: TypedEdgeCollection<G["edges"][K]>;
-    };
+    get edges(): GraphEdgeCollections<G>;
     /**
      * Creates a query builder for this store.
      *
@@ -2196,6 +2250,7 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  *
  * This is the recommended way to create a store in production.
  * It automatically:
+ * - Creates base tables on a fresh database (if the backend supports bootstrapTables)
  * - Initializes the schema on first run (version 1)
  * - Auto-migrates safe changes (additive changes)
  * - Throws MigrationError for breaking changes
@@ -2220,4 +2275,4 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  */
 declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions & SchemaManagerOptions): Promise<[Store<G>, SchemaValidationResult]>;
 
-export { type SubsetNode as $, type AliasMap as A, type BatchResults as B, type CreateQueryBuilderOptions as C, type PropsAccessor as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type QueryHookContext as J, type QueryOptions as K, type SelectableEdge as L, type SelectableNode as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, type SelectContext as S, TraversalBuilder as T, Store as U, type StoreHooks as V, type StoreOptions as W, type StreamOptions as X, type SubgraphOptions as Y, type SubgraphResult as Z, type SubsetEdge as _, type AggregateResult as a, type TransactionContext as a0, type TypedEdgeCollection as a1, UnionableQuery as a2, type UpdateEdgeInput as a3, type UpdateNodeInput as a4, createStore as a5, createStoreWithSchema as a6, defineSubgraphProject as a7, embedding as a8, exists as a9, fieldRef as aa, getEmbeddingDimensions as ab, inSubquery as ac, isEmbeddingSchema as ad, isParameterRef as ae, notExists as af, notInSubquery as ag, param as ah, type AnyEdge as b, type AnyNode as c, type BatchableQuery as d, type ConstraintNames as e, type CreateEdgeInput as f, type CreateNodeInput as g, type Edge as h, type EdgeAccessor as i, type EdgeCollection as j, type EdgeFindByEndpointsOptions as k, type EdgeGetOrCreateByEndpointsOptions as l, type EdgeGetOrCreateByEndpointsResult as m, type EmbeddingSchema as n, type EmbeddingValue as o, ExecutableAggregateQuery as p, ExecutableQuery as q, type NodeAccessor as r, type NodeAlias as s, type NodeCollection as t, type NodeGetOrCreateByConstraintOptions as u, type NodeGetOrCreateByConstraintResult as v, type NodeRef as w, type PaginatedResult as x, type Predicate as y, PreparedQuery as z };
+export { type SubgraphOptions as $, type AliasMap as A, type BatchResults as B, type CreateQueryBuilderOptions as C, type Predicate as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, PreparedQuery as J, type PropsAccessor as K, type QueryHookContext as L, type QueryOptions as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, type SelectContext as S, TraversalBuilder as T, type SelectableEdge as U, type SelectableNode as V, Store as W, type StoreHooks as X, type StoreOptions as Y, type StoreProjection as Z, type StreamOptions as _, type AggregateResult as a, type SubgraphResult as a0, type SubsetEdge as a1, type SubsetNode as a2, type TransactionContext as a3, type TypedEdgeCollection as a4, UnionableQuery as a5, type UpdateEdgeInput as a6, type UpdateNodeInput as a7, createStore as a8, createStoreWithSchema as a9, defineSubgraphProject as aa, embedding as ab, exists as ac, fieldRef as ad, getEmbeddingDimensions as ae, inSubquery as af, isEmbeddingSchema as ag, isParameterRef as ah, notExists as ai, notInSubquery as aj, param as ak, type AnyEdge as b, type AnyNode as c, type BatchableQuery as d, type ConstraintNames as e, type CreateEdgeInput as f, type CreateNodeInput as g, type Edge as h, type EdgeAccessor as i, type EdgeCollection as j, type EdgeFindByEndpointsOptions as k, type EdgeGetOrCreateByEndpointsOptions as l, type EdgeGetOrCreateByEndpointsResult as m, type EmbeddingSchema as n, type EmbeddingValue as o, ExecutableAggregateQuery as p, ExecutableQuery as q, type GraphEdgeCollections as r, type GraphNodeCollections as s, type NodeAccessor as t, type NodeAlias as u, type NodeCollection as v, type NodeGetOrCreateByConstraintOptions as w, type NodeGetOrCreateByConstraintResult as x, type NodeRef as y, type PaginatedResult as z };

package/dist/{store-6-vH0ZIj.d.ts → store-CD_0yf2s.d.ts}

@@ -1,5 +1,5 @@
-import { S as SqlSchema, G as GraphBackend, T as TransactionBackend } from './types-1YJKodRv.js';
-import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, f as SchemaValidationResult } from './manager-BCLhWysp.js';
+import { S as SqlSchema, G as GraphBackend, T as TransactionBackend, E as EdgeRow, N as NodeRow } from './types-ThB4cFLp.js';
+import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, d as SchemaValidationResult } from './manager-Chhrq1vl.js';
 import { S as SqlDialect, N as NodeType, A as AnyEdgeType, T as TemporalMode, E as EdgeType, d as EdgeRegistration, b as EdgeId, g as NodeId, i as NodeRegistration } from './types-DMzKq0d5.js';
 import { z } from 'zod';
 import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, o as RecursiveCyclePolicy, q as TraversalDirection, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-COMyNeMn.js';
@@ -610,16 +610,40 @@ type CreateQueryBuilderOptions = Readonly<{
  * Store types for TypeGraph operations.
  */
 
+/**
+ * Canonical mapping from snake_case row fields to camelCase meta fields.
+ *
+ * This is the single source of truth for which row columns become metadata.
+ * Both the Meta types and the row-to-meta functions in row-mappers.ts must
+ * stay in sync with this mapping. If you add a temporal/audit column to a
+ * row type, add the mapping here — the compiler will then force you to
+ * update the row mapper functions as well (since their return type is
+ * NodeMeta/EdgeMeta, which is derived from this mapping).
+ */
+type TemporalMetaFieldMap = Readonly<{
+    valid_from: "validFrom";
+    valid_to: "validTo";
+    created_at: "createdAt";
+    updated_at: "updatedAt";
+    deleted_at: "deletedAt";
+}>;
+/**
+ * Maps row fields to their camelCase meta counterparts, preserving types.
+ */
+type MapRowToMeta<R extends Readonly<Record<string, unknown>>, M extends Readonly<Record<string, string>>> = Readonly<{
+    [SnakeKey in keyof M as M[SnakeKey] & string]: SnakeKey extends keyof R ? R[SnakeKey] : never;
+}>;
 /**
  * Metadata for a node instance.
+ * Derived from NodeRow via TemporalMetaFieldMap + version.
+ *
+ * Adding a new metadata column requires:
+ * 1. Add the column to NodeRow in backend/types.ts
+ * 2. Add the mapping to TemporalMetaFieldMap above
+ * 3. The compiler will error in rowToNodeMeta() until you add the field there
  */
-type NodeMeta = Readonly<{
-    version: number;
-    validFrom: string | undefined;
-    validTo: string | undefined;
-    createdAt: string;
-    updatedAt: string;
-    deletedAt: string | undefined;
+type NodeMeta = MapRowToMeta<NodeRow, TemporalMetaFieldMap> & Readonly<{
+    version: NodeRow["version"];
 }>;
 /**
  * A node instance in the graph.
@@ -654,14 +678,9 @@ type UpdateNodeInput<N extends NodeType = NodeType> = Readonly<{
 }>;
 /**
  * Metadata for an edge instance.
+ * Derived from EdgeRow via TemporalMetaFieldMap (edges have no version).
  */
-type EdgeMeta = Readonly<{
-    validFrom: string | undefined;
-    validTo: string | undefined;
-    createdAt: string;
-    updatedAt: string;
-    deletedAt: string | undefined;
-}>;
+type EdgeMeta = MapRowToMeta<EdgeRow, TemporalMetaFieldMap>;
 /**
  * An edge instance in the graph.
  *
@@ -1247,6 +1266,14 @@ type EdgeToTypes<R extends EdgeRegistration> = R["to"] extends readonly (infer N
  * Extracts the edge type and from/to node types automatically.
  */
 type TypedEdgeCollection<R extends EdgeRegistration> = EdgeCollection<R["type"], EdgeFromTypes<R> extends NodeType ? EdgeFromTypes<R> : NodeType, EdgeToTypes<R> extends NodeType ? EdgeToTypes<R> : NodeType>;
+/** Mapped type of all node collections for a graph. */
+type GraphNodeCollections<G extends GraphDef> = {
+    [K in keyof G["nodes"] & string]-?: NodeCollection<G["nodes"][K]["type"], ConstraintNames<G["nodes"][K]>>;
+};
+/** Mapped type of all edge collections for a graph. */
+type GraphEdgeCollections<G extends GraphDef> = {
+    [K in keyof G["edges"] & string]-?: TypedEdgeCollection<G["edges"][K]>;
+};
 /**
  * A typed transaction context with collection API.
  *
@@ -1258,20 +1285,50 @@ type TypedEdgeCollection<R extends EdgeRegistration> = EdgeCollection<R["type"],
  * await store.transaction(async (tx) => {
  *   const person = await tx.nodes.Person.create({ name: "Alice" });
  *   const company = await tx.nodes.Company.create({ name: "Acme" });
- *   // Pass nodes directly - their kind and id properties are used
  *   await tx.edges.worksAt.create(person, company, { role: "Engineer" });
  * });
  * ```
  */
 type TransactionContext<G extends GraphDef> = Readonly<{
-    /** Node collections for the transaction */
+    nodes: GraphNodeCollections<G>;
+    edges: GraphEdgeCollections<G>;
+}>;
+/**
+ * A type-level projection of a store's surface onto a subset of its
+ * node and edge collections.
+ *
+ * Node collections are projected with constraint names erased (`never`),
+ * so constraint-based methods like `findByConstraint` become uncallable.
+ * This is intentional: unique constraints are graph-registration-level
+ * details that differ between graphs sharing the same node types.
+ *
+ * @example
+ * ```typescript
+ * type CoreStore = StoreProjection<
+ *   typeof myGraph,
+ *   "Document" | "Chunk",
+ *   "hasChunk"
+ * >;
+ *
+ * async function ingestChunk(
+ *   store: CoreStore,
+ *   document: Node<typeof Document>,
+ *   text: string,
+ * ) {
+ *   const chunk = await store.nodes.Chunk.create({ text });
+ *   await store.edges.hasChunk.create(document, chunk);
+ *   return chunk;
+ * }
+ * ```
+ *
+ * Both `Store<G>` and `TransactionContext<G>` are structurally assignable
+ * to a `StoreProjection` whose keys are a subset of `G`.
+ */
+type StoreProjection<G extends GraphDef, N extends keyof G["nodes"] & string = never, E extends keyof G["edges"] & string = never> = Readonly<{
     nodes: {
-        [K in keyof G["nodes"] & string]-?: NodeCollection<G["nodes"][K]["type"], ConstraintNames<G["nodes"][K]>>;
-    };
-    /** Edge collections for the transaction */
-    edges: {
-        [K in keyof G["edges"] & string]-?: TypedEdgeCollection<G["edges"][K]>;
+        [K in N]-?: NodeCollection<G["nodes"][K]["type"], never>;
     };
+    edges: Pick<GraphEdgeCollections<G>, E>;
 }>;
 
 /**
@@ -1756,7 +1813,8 @@ declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, Edg
     constructor(config: QueryBuilderConfig, state: QueryBuilderState, edgeKinds: readonly string[], edgeAlias: EA, direction: Dir, fromAlias: string, inverseEdgeKinds?: readonly string[], optional?: Optional, variableLength?: VariableLengthState, pendingEdgePredicates?: readonly NodePredicate[]);
     /**
      * Enables variable-length (recursive) traversal.
-     * By default, traverses unlimited depth with cycle prevention.
+     * Defaults to MAX_RECURSIVE_DEPTH (10) hops with cycle prevention.
+     * Use `maxHops` to override (up to MAX_EXPLICIT_RECURSIVE_DEPTH).
      */
     recursive<const O extends RecursiveTraversalOptions = Record<string, never>>(options?: O): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional, O extends {
         depth: infer D extends boolean | string;
@@ -2027,9 +2085,7 @@ declare class Store<G extends GraphDef> {
      * const people = await store.nodes.Person.find({ limit: 10 });
      * ```
      */
-    get nodes(): {
-        [K in keyof G["nodes"] & string]-?: NodeCollection<G["nodes"][K]["type"], ConstraintNames<G["nodes"][K]>>;
-    };
+    get nodes(): GraphNodeCollections<G>;
     /**
      * Edge collections for ergonomic CRUD operations.
      *
@@ -2046,9 +2102,7 @@ declare class Store<G extends GraphDef> {
      * const edges = await store.edges.worksAt.findFrom({ kind: "Person", id: person.id });
      * ```
      */
-    get edges(): {
-        [K in keyof G["edges"] & string]-?: TypedEdgeCollection<G["edges"][K]>;
-    };
+    get edges(): GraphEdgeCollections<G>;
     /**
      * Creates a query builder for this store.
      *
@@ -2196,6 +2250,7 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  *
  * This is the recommended way to create a store in production.
  * It automatically:
+ * - Creates base tables on a fresh database (if the backend supports bootstrapTables)
  * - Initializes the schema on first run (version 1)
  * - Auto-migrates safe changes (additive changes)
  * - Throws MigrationError for breaking changes
@@ -2220,4 +2275,4 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  */
 declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions & SchemaManagerOptions): Promise<[Store<G>, SchemaValidationResult]>;
 
-export { type SubsetNode as $, type AliasMap as A, type BatchResults as B, type CreateQueryBuilderOptions as C, type PropsAccessor as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type QueryHookContext as J, type QueryOptions as K, type SelectableEdge as L, type SelectableNode as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, type SelectContext as S, TraversalBuilder as T, Store as U, type StoreHooks as V, type StoreOptions as W, type StreamOptions as X, type SubgraphOptions as Y, type SubgraphResult as Z, type SubsetEdge as _, type AggregateResult as a, type TransactionContext as a0, type TypedEdgeCollection as a1, UnionableQuery as a2, type UpdateEdgeInput as a3, type UpdateNodeInput as a4, createStore as a5, createStoreWithSchema as a6, defineSubgraphProject as a7, embedding as a8, exists as a9, fieldRef as aa, getEmbeddingDimensions as ab, inSubquery as ac, isEmbeddingSchema as ad, isParameterRef as ae, notExists as af, notInSubquery as ag, param as ah, type AnyEdge as b, type AnyNode as c, type BatchableQuery as d, type ConstraintNames as e, type CreateEdgeInput as f, type CreateNodeInput as g, type Edge as h, type EdgeAccessor as i, type EdgeCollection as j, type EdgeFindByEndpointsOptions as k, type EdgeGetOrCreateByEndpointsOptions as l, type EdgeGetOrCreateByEndpointsResult as m, type EmbeddingSchema as n, type EmbeddingValue as o, ExecutableAggregateQuery as p, ExecutableQuery as q, type NodeAccessor as r, type NodeAlias as s, type NodeCollection as t, type NodeGetOrCreateByConstraintOptions as u, type NodeGetOrCreateByConstraintResult as v, type NodeRef as w, type PaginatedResult as x, type Predicate as y, PreparedQuery as z };
+export { type SubgraphOptions as $, type AliasMap as A, type BatchResults as B, type CreateQueryBuilderOptions as C, type Predicate as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, PreparedQuery as J, type PropsAccessor as K, type QueryHookContext as L, type QueryOptions as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, type SelectContext as S, TraversalBuilder as T, type SelectableEdge as U, type SelectableNode as V, Store as W, type StoreHooks as X, type StoreOptions as Y, type StoreProjection as Z, type StreamOptions as _, type AggregateResult as a, type SubgraphResult as a0, type SubsetEdge as a1, type SubsetNode as a2, type TransactionContext as a3, type TypedEdgeCollection as a4, UnionableQuery as a5, type UpdateEdgeInput as a6, type UpdateNodeInput as a7, createStore as a8, createStoreWithSchema as a9, defineSubgraphProject as aa, embedding as ab, exists as ac, fieldRef as ad, getEmbeddingDimensions as ae, inSubquery as af, isEmbeddingSchema as ag, isParameterRef as ah, notExists as ai, notInSubquery as aj, param as ak, type AnyEdge as b, type AnyNode as c, type BatchableQuery as d, type ConstraintNames as e, type CreateEdgeInput as f, type CreateNodeInput as g, type Edge as h, type EdgeAccessor as i, type EdgeCollection as j, type EdgeFindByEndpointsOptions as k, type EdgeGetOrCreateByEndpointsOptions as l, type EdgeGetOrCreateByEndpointsResult as m, type EmbeddingSchema as n, type EmbeddingValue as o, ExecutableAggregateQuery as p, ExecutableQuery as q, type GraphEdgeCollections as r, type GraphNodeCollections as s, type NodeAccessor as t, type NodeAlias as u, type NodeCollection as v, type NodeGetOrCreateByConstraintOptions as w, type NodeGetOrCreateByConstraintResult as x, type NodeRef as y, type PaginatedResult as z };

package/dist/{types-GLkwvQvS.d.cts → types-B3mmOMJV.d.cts}

@@ -118,6 +118,9 @@ declare const DEFAULT_SQL_SCHEMA: SqlSchema;
  *
  * These types represent the JSON-serializable format used for
  * homoiconic schema storage in the database.
+ *
+ * The Zod schema (serializedSchemaZod) is the single source of truth.
+ * The TypeScript type (SerializedSchema) is inferred from it.
  */
 
 /**
@@ -229,7 +232,10 @@ type SerializedEdgeDef = Readonly<{
  * Complete serialized schema document.
  *
  * This is the format stored in the schema_doc column of
- * typegraph_schema_versions.
+ * typegraph_schema_versions. The type is kept explicit rather than
+ * inferred from the Zod schema so that downstream code sees the
+ * precise literal union types (DeleteBehavior, TemporalMode, etc.)
+ * instead of the broader `string` type that Zod's passthrough schema uses.
  */
 type SerializedSchema = Readonly<{
     graphId: string;
@@ -375,7 +381,7 @@ type InsertNodeParams = Readonly<{
     graphId: string;
     kind: string;
     id: string;
-    props: Record<string, unknown>;
+    props: Readonly<Record<string, unknown>>;
     validFrom?: string;
     validTo?: string;
 }>;
@@ -386,7 +392,7 @@ type UpdateNodeParams = Readonly<{
     graphId: string;
     kind: string;
     id: string;
-    props: Record<string, unknown>;
+    props: Readonly<Record<string, unknown>>;
     validTo?: string;
     incrementVersion?: boolean;
     /** If true, clears deleted_at (un-deletes the node). Used by upsert. */
@@ -411,7 +417,7 @@ type InsertEdgeParams = Readonly<{
     fromId: string;
     toKind: string;
     toId: string;
-    props: Record<string, unknown>;
+    props: Readonly<Record<string, unknown>>;
     validFrom?: string;
     validTo?: string;
 }>;
@@ -421,7 +427,7 @@ type InsertEdgeParams = Readonly<{
 type UpdateEdgeParams = Readonly<{
     graphId: string;
     id: string;
-    props: Record<string, unknown>;
+    props: Readonly<Record<string, unknown>>;
     validTo?: string;
     clearDeleted?: boolean;
 }>;
@@ -587,6 +593,14 @@ type GraphBackend = Readonly<{
      * Intended for import-replacement workflows. No hooks, no per-row logic.
      */
     clearGraph: (graphId: string) => Promise<void>;
+    /**
+     * Creates the base TypeGraph tables if they don't already exist.
+     *
+     * Called automatically by `createStoreWithSchema()` when a fresh database
+     * is detected. Users who manage DDL themselves via `createStore()` never
+     * hit this path.
+     */
+    bootstrapTables?: () => Promise<void>;
     execute: <T>(query: SQL) => Promise<readonly T[]>;
     /** Execute pre-compiled SQL text with bound parameters. Available on sync SQLite and pg backends. */
     executeRaw?: <T>(sqlText: string, params: readonly unknown[]) => Promise<readonly T[]>;
@@ -745,4 +759,4 @@ type CountEdgesByKindParams = Readonly<{
     asOf?: string;
 }>;
 
-export { DEFAULT_SQL_SCHEMA as D, type GraphBackend as G, type InferenceType as I, type JsonSchema as J, type MetaEdge as M, type OntologyRelation as O, type SqlSchema as S, type TransactionBackend as T, type MetaEdgeProperties as a, type SqlTableNames as b, createSqlSchema as c, type SerializedNodeDef as d, type SerializedEdgeDef as e, type SerializedMetaEdge as f, type SerializedOntologyRelation as g, type SerializedClosures as h, isMetaEdge as i, type SerializedSchema as j, type SchemaHash as k, type SerializedOntology as l, type SerializedUniqueConstraint as m, type SchemaVersionRow as n };
+export { DEFAULT_SQL_SCHEMA as D, type EdgeRow as E, type GraphBackend as G, type InferenceType as I, type JsonSchema as J, type MetaEdge as M, type NodeRow as N, type OntologyRelation as O, type SqlSchema as S, type TransactionBackend as T, type MetaEdgeProperties as a, type SqlTableNames as b, createSqlSchema as c, type SerializedNodeDef as d, type SerializedEdgeDef as e, type SerializedMetaEdge as f, type SerializedOntologyRelation as g, type SerializedClosures as h, isMetaEdge as i, type SerializedSchema as j, type SchemaHash as k, type SerializedOntology as l, type SerializedUniqueConstraint as m, type SchemaVersionRow as n };

package/dist/{types-C8Ra3ROE.d.cts → types-CZd2PEOc.d.cts}

@@ -99,7 +99,10 @@ type NonEmptyJsonPointerFor<T> = Exclude<JsonPointerFor<T>, "">;
 type NonEmptyJsonPointerSegmentsFor<T> = Exclude<JsonPointerSegmentsFor<T>, readonly []>;
 type IndexFieldInput<T> = (keyof T & string) | NonEmptyJsonPointerFor<T> | NonEmptyJsonPointerSegmentsFor<T> | JsonPointer;
 type NodeIndexConfig<N extends NodeType> = Readonly<{
-    fields: readonly IndexFieldInput<z.infer<N["schema"]>>[];
+    fields: readonly [
+        IndexFieldInput<z.infer<N["schema"]>>,
+        ...IndexFieldInput<z.infer<N["schema"]>>[]
+    ];
     coveringFields?: readonly IndexFieldInput<z.infer<N["schema"]>>[] | undefined;
     unique?: boolean | undefined;
     name?: string | undefined;
@@ -108,7 +111,10 @@ type NodeIndexConfig<N extends NodeType> = Readonly<{
 }>;
 type EdgeIndexDirection = "out" | "in" | "none";
 type EdgeIndexConfig<E extends AnyEdgeType> = Readonly<{
-    fields: readonly IndexFieldInput<z.infer<E["schema"]>>[];
+    fields: readonly [
+        IndexFieldInput<z.infer<E["schema"]>>,
+        ...IndexFieldInput<z.infer<E["schema"]>>[]
+    ];
     coveringFields?: readonly IndexFieldInput<z.infer<E["schema"]>>[] | undefined;
     unique?: boolean | undefined;
     name?: string | undefined;

package/dist/{types-CC8eB0PB.d.ts → types-Ceb01czq.d.ts}

@@ -99,7 +99,10 @@ type NonEmptyJsonPointerFor<T> = Exclude<JsonPointerFor<T>, "">;
 type NonEmptyJsonPointerSegmentsFor<T> = Exclude<JsonPointerSegmentsFor<T>, readonly []>;
 type IndexFieldInput<T> = (keyof T & string) | NonEmptyJsonPointerFor<T> | NonEmptyJsonPointerSegmentsFor<T> | JsonPointer;
 type NodeIndexConfig<N extends NodeType> = Readonly<{
-    fields: readonly IndexFieldInput<z.infer<N["schema"]>>[];
+    fields: readonly [
+        IndexFieldInput<z.infer<N["schema"]>>,
+        ...IndexFieldInput<z.infer<N["schema"]>>[]
+    ];
     coveringFields?: readonly IndexFieldInput<z.infer<N["schema"]>>[] | undefined;
     unique?: boolean | undefined;
     name?: string | undefined;
@@ -108,7 +111,10 @@ type NodeIndexConfig<N extends NodeType> = Readonly<{
 }>;
 type EdgeIndexDirection = "out" | "in" | "none";
 type EdgeIndexConfig<E extends AnyEdgeType> = Readonly<{
-    fields: readonly IndexFieldInput<z.infer<E["schema"]>>[];
+    fields: readonly [
+        IndexFieldInput<z.infer<E["schema"]>>,
+        ...IndexFieldInput<z.infer<E["schema"]>>[]
+    ];
     coveringFields?: readonly IndexFieldInput<z.infer<E["schema"]>>[] | undefined;
     unique?: boolean | undefined;
     name?: string | undefined;

package/dist/{types-1YJKodRv.d.ts → types-ThB4cFLp.d.ts}

@@ -118,6 +118,9 @@ declare const DEFAULT_SQL_SCHEMA: SqlSchema;
  *
  * These types represent the JSON-serializable format used for
  * homoiconic schema storage in the database.
+ *
+ * The Zod schema (serializedSchemaZod) is the single source of truth.
+ * The TypeScript type (SerializedSchema) is inferred from it.
  */
 
 /**
@@ -229,7 +232,10 @@ type SerializedEdgeDef = Readonly<{
  * Complete serialized schema document.
  *
  * This is the format stored in the schema_doc column of
- * typegraph_schema_versions.
+ * typegraph_schema_versions. The type is kept explicit rather than
+ * inferred from the Zod schema so that downstream code sees the
+ * precise literal union types (DeleteBehavior, TemporalMode, etc.)
+ * instead of the broader `string` type that Zod's passthrough schema uses.
  */
 type SerializedSchema = Readonly<{
     graphId: string;
@@ -375,7 +381,7 @@ type InsertNodeParams = Readonly<{
     graphId: string;
     kind: string;
     id: string;
-    props: Record<string, unknown>;
+    props: Readonly<Record<string, unknown>>;
     validFrom?: string;
     validTo?: string;
 }>;
@@ -386,7 +392,7 @@ type UpdateNodeParams = Readonly<{
     graphId: string;
     kind: string;
     id: string;
-    props: Record<string, unknown>;
+    props: Readonly<Record<string, unknown>>;
     validTo?: string;
     incrementVersion?: boolean;
     /** If true, clears deleted_at (un-deletes the node). Used by upsert. */
@@ -411,7 +417,7 @@ type InsertEdgeParams = Readonly<{
     fromId: string;
     toKind: string;
     toId: string;
-    props: Record<string, unknown>;
+    props: Readonly<Record<string, unknown>>;
     validFrom?: string;
     validTo?: string;
 }>;
@@ -421,7 +427,7 @@ type InsertEdgeParams = Readonly<{
 type UpdateEdgeParams = Readonly<{
     graphId: string;
     id: string;
-    props: Record<string, unknown>;
+    props: Readonly<Record<string, unknown>>;
     validTo?: string;
     clearDeleted?: boolean;
 }>;
@@ -587,6 +593,14 @@ type GraphBackend = Readonly<{
      * Intended for import-replacement workflows. No hooks, no per-row logic.
      */
     clearGraph: (graphId: string) => Promise<void>;
+    /**
+     * Creates the base TypeGraph tables if they don't already exist.
+     *
+     * Called automatically by `createStoreWithSchema()` when a fresh database
+     * is detected. Users who manage DDL themselves via `createStore()` never
+     * hit this path.
+     */
+    bootstrapTables?: () => Promise<void>;
     execute: <T>(query: SQL) => Promise<readonly T[]>;
     /** Execute pre-compiled SQL text with bound parameters. Available on sync SQLite and pg backends. */
     executeRaw?: <T>(sqlText: string, params: readonly unknown[]) => Promise<readonly T[]>;
@@ -745,4 +759,4 @@ type CountEdgesByKindParams = Readonly<{
     asOf?: string;
 }>;
 
-export { DEFAULT_SQL_SCHEMA as D, type GraphBackend as G, type InferenceType as I, type JsonSchema as J, type MetaEdge as M, type OntologyRelation as O, type SqlSchema as S, type TransactionBackend as T, type MetaEdgeProperties as a, type SqlTableNames as b, createSqlSchema as c, type SerializedNodeDef as d, type SerializedEdgeDef as e, type SerializedMetaEdge as f, type SerializedOntologyRelation as g, type SerializedClosures as h, isMetaEdge as i, type SerializedSchema as j, type SchemaHash as k, type SerializedOntology as l, type SerializedUniqueConstraint as m, type SchemaVersionRow as n };
+export { DEFAULT_SQL_SCHEMA as D, type EdgeRow as E, type GraphBackend as G, type InferenceType as I, type JsonSchema as J, type MetaEdge as M, type NodeRow as N, type OntologyRelation as O, type SqlSchema as S, type TransactionBackend as T, type MetaEdgeProperties as a, type SqlTableNames as b, createSqlSchema as c, type SerializedNodeDef as d, type SerializedEdgeDef as e, type SerializedMetaEdge as f, type SerializedOntologyRelation as g, type SerializedClosures as h, isMetaEdge as i, type SerializedSchema as j, type SchemaHash as k, type SerializedOntology as l, type SerializedUniqueConstraint as m, type SchemaVersionRow as n };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicia-ai/typegraph",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "TypeScript-first embedded knowledge graph library with ontological reasoning",
   "type": "module",
   "main": "./dist/index.cjs",