@nicia-ai/typegraph 0.1.1 → 0.3.0

package/dist/{types-DDOSfrih.d.cts → types-DDP0MGBF.d.cts}

@@ -1,6 +1,257 @@
 import { SQL } from 'drizzle-orm';
+import { N as NodeType, E as EdgeType, U as UniquenessScope, C as Collation, D as DeleteBehavior, d as Cardinality, e as EndpointExistence, T as TemporalMode } from './types-DTJEu_-h.cjs';
 import { S as SqlDialect } from './types-BRzHlhKC.cjs';
 
+/** Brand key for MetaEdge */
+declare const META_EDGE_BRAND: "__metaEdge";
+/**
+ * How a meta-edge affects queries and validation.
+ */
+type InferenceType = "subsumption" | "hierarchy" | "substitution" | "constraint" | "composition" | "association" | "none";
+/**
+ * Properties of a meta-edge.
+ */
+type MetaEdgeProperties = Readonly<{
+    transitive: boolean;
+    symmetric: boolean;
+    reflexive: boolean;
+    inverse: string | undefined;
+    inference: InferenceType;
+    description: string | undefined;
+}>;
+/**
+ * A meta-edge definition.
+ *
+ * Meta-edges represent type-level relationships (between kinds),
+ * not instance-level relationships (between nodes).
+ */
+type MetaEdge<K extends string = string> = Readonly<{
+    [META_EDGE_BRAND]: true;
+    name: K;
+    properties: MetaEdgeProperties;
+}>;
+/**
+ * A relation in the ontology (instance of meta-edge between types).
+ *
+ * @example
+ * ```typescript
+ * // Podcast subClassOf Media
+ * subClassOf(Podcast, Media)
+ *
+ * // Person equivalentTo schema:Person
+ * equivalentTo(Person, "https://schema.org/Person")
+ * ```
+ */
+type OntologyRelation = Readonly<{
+    metaEdge: MetaEdge;
+    from: NodeType | EdgeType | string;
+    to: NodeType | EdgeType | string;
+}>;
+/**
+ * Checks if a value is a MetaEdge.
+ */
+declare function isMetaEdge(value: unknown): value is MetaEdge;
+
+/**
+ * SQL Schema Configuration for Query Compilation
+ *
+ * Provides table and column identifiers that the query compiler uses.
+ * This allows the compiler to work with custom table names instead of
+ * hard-coded defaults.
+ */
+
+/**
+ * Table names for TypeGraph SQL schema.
+ */
+type SqlTableNames = Readonly<{
+    /** Nodes table name (default: "typegraph_nodes") */
+    nodes: string;
+    /** Edges table name (default: "typegraph_edges") */
+    edges: string;
+    /** Node embeddings table name (default: "typegraph_node_embeddings") */
+    embeddings: string;
+}>;
+/**
+ * SQL schema configuration for query compilation.
+ * Contains table identifiers and utility methods for generating SQL references.
+ */
+type SqlSchema = Readonly<{
+    /** Table names */
+    tables: SqlTableNames;
+    /** Get a SQL reference to the nodes table */
+    nodesTable: SQL;
+    /** Get a SQL reference to the edges table */
+    edgesTable: SQL;
+    /** Get a SQL reference to the embeddings table */
+    embeddingsTable: SQL;
+}>;
+/**
+ * Creates a SqlSchema configuration from table names.
+ *
+ * Table names are validated to ensure they are valid SQL identifiers.
+ * This prevents SQL injection and ensures compatibility across databases.
+ *
+ * @param names - Optional custom table names (defaults to standard names)
+ * @returns SqlSchema configuration for query compilation
+ * @throws Error if any table name is invalid
+ *
+ * @example
+ * ```typescript
+ * // Use default table names
+ * const schema = createSqlSchema();
+ *
+ * // Use custom table names
+ * const schema = createSqlSchema({
+ *   nodes: "myapp_nodes",
+ *   edges: "myapp_edges",
+ *   embeddings: "myapp_embeddings",
+ * });
+ * ```
+ */
+declare function createSqlSchema(names?: Partial<SqlTableNames>): SqlSchema;
+/**
+ * Default SqlSchema using standard TypeGraph table names.
+ */
+declare const DEFAULT_SQL_SCHEMA: SqlSchema;
+
+/**
+ * Types for serialized schema storage.
+ *
+ * These types represent the JSON-serializable format used for
+ * homoiconic schema storage in the database.
+ */
+
+/**
+ * JSON Schema type (subset used by Zod toJSONSchema).
+ *
+ * This is a simplified version - the actual JSON Schema has many more properties.
+ */
+type JsonSchema = Readonly<{
+    $schema?: string;
+    type?: string | readonly string[];
+    properties?: Record<string, JsonSchema>;
+    required?: readonly string[];
+    items?: JsonSchema;
+    additionalProperties?: boolean | JsonSchema;
+    enum?: readonly unknown[];
+    const?: unknown;
+    anyOf?: readonly JsonSchema[];
+    oneOf?: readonly JsonSchema[];
+    allOf?: readonly JsonSchema[];
+    not?: JsonSchema;
+    description?: string;
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    [key: string]: unknown;
+}>;
+/**
+ * Serialized representation of a meta-edge.
+ */
+type SerializedMetaEdge = Readonly<{
+    name: string;
+    transitive: boolean;
+    symmetric: boolean;
+    reflexive: boolean;
+    inverse: string | undefined;
+    inference: InferenceType;
+    description: string | undefined;
+}>;
+/**
+ * Serialized representation of an ontology relation.
+ */
+type SerializedOntologyRelation = Readonly<{
+    metaEdge: string;
+    from: string;
+    to: string;
+}>;
+/**
+ * Precomputed closures stored in the schema for fast runtime lookup.
+ */
+type SerializedClosures = Readonly<{
+    subClassAncestors: Record<string, readonly string[]>;
+    subClassDescendants: Record<string, readonly string[]>;
+    broaderClosure: Record<string, readonly string[]>;
+    narrowerClosure: Record<string, readonly string[]>;
+    equivalenceSets: Record<string, readonly string[]>;
+    disjointPairs: readonly string[];
+    partOfClosure: Record<string, readonly string[]>;
+    hasPartClosure: Record<string, readonly string[]>;
+    iriToKind: Record<string, string>;
+    edgeInverses: Record<string, string>;
+    edgeImplicationsClosure: Record<string, readonly string[]>;
+    edgeImplyingClosure: Record<string, readonly string[]>;
+}>;
+/**
+ * Complete serialized ontology section.
+ */
+type SerializedOntology = Readonly<{
+    metaEdges: Record<string, SerializedMetaEdge>;
+    relations: readonly SerializedOntologyRelation[];
+    closures: SerializedClosures;
+}>;
+/**
+ * Serialized representation of a uniqueness constraint.
+ */
+type SerializedUniqueConstraint = Readonly<{
+    name: string;
+    fields: readonly string[];
+    where: string | undefined;
+    scope: UniquenessScope;
+    collation: Collation;
+}>;
+/**
+ * Serialized representation of a node kind.
+ */
+type SerializedNodeDef = Readonly<{
+    kind: string;
+    properties: JsonSchema;
+    uniqueConstraints: readonly SerializedUniqueConstraint[];
+    onDelete: DeleteBehavior;
+    description: string | undefined;
+}>;
+/**
+ * Serialized representation of an edge kind.
+ */
+type SerializedEdgeDef = Readonly<{
+    kind: string;
+    fromKinds: readonly string[];
+    toKinds: readonly string[];
+    properties: JsonSchema;
+    cardinality: Cardinality;
+    endpointExistence: EndpointExistence;
+    description: string | undefined;
+}>;
+/**
+ * Complete serialized schema document.
+ *
+ * This is the format stored in the schema_doc column of
+ * typegraph_schema_versions.
+ */
+type SerializedSchema = Readonly<{
+    graphId: string;
+    version: number;
+    generatedAt: string;
+    nodes: Record<string, SerializedNodeDef>;
+    edges: Record<string, SerializedEdgeDef>;
+    ontology: SerializedOntology;
+    defaults: Readonly<{
+        onNodeDelete: DeleteBehavior;
+        temporalMode: TemporalMode;
+    }>;
+}>;
+/**
+ * A schema hash for detecting changes.
+ *
+ * We hash the schema content (excluding version and generatedAt)
+ * to detect if the schema has actually changed.
+ */
+type SchemaHash = string;
+
 /**
  * Backend interface types for TypeGraph storage.
  *
@@ -30,7 +281,6 @@ type VectorCapabilities = Readonly<{
     maxDimensions: number;
 }>;
 
-type Dialect = SqlDialect;
 /**
  * Backend capabilities that vary by dialect.
  */
@@ -174,6 +424,7 @@ type UpdateEdgeParams = Readonly<{
     id: string;
     props: Record<string, unknown>;
     validTo?: string;
+    clearDeleted?: boolean;
 }>;
 /**
  * Parameters for deleting an edge (soft delete).
@@ -234,6 +485,10 @@ type VectorSearchParams = Readonly<{
  */
 type VectorSearchResult = Readonly<{
     nodeId: string;
+    /**
+     * Cosine metric returns similarity score (higher is better).
+     * L2 and inner_product return raw distance (lower is better).
+     */
     score: number;
 }>;
 /**
@@ -284,19 +539,29 @@ type TransactionBackend = Omit<GraphBackend, "transaction" | "close">;
  */
 type GraphBackend = Readonly<{
     /** The SQL dialect */
-    dialect: Dialect;
+    dialect: SqlDialect;
     /** Backend capabilities */
     capabilities: BackendCapabilities;
+    /** Table names used by this backend (for query schema auto-derivation) */
+    tableNames?: SqlTableNames | undefined;
     insertNode: (params: InsertNodeParams) => Promise<NodeRow>;
+    insertNodeNoReturn?: (params: InsertNodeParams) => Promise<void>;
+    insertNodesBatch?: (params: readonly InsertNodeParams[]) => Promise<void>;
+    insertNodesBatchReturning?: (params: readonly InsertNodeParams[]) => Promise<readonly NodeRow[]>;
     updateNode: (params: UpdateNodeParams) => Promise<NodeRow>;
     deleteNode: (params: DeleteNodeParams) => Promise<void>;
     hardDeleteNode: (params: HardDeleteNodeParams) => Promise<void>;
     getNode: (graphId: string, kind: string, id: string) => Promise<NodeRow | undefined>;
+    getNodes?: (graphId: string, kind: string, ids: readonly string[]) => Promise<readonly NodeRow[]>;
     insertEdge: (params: InsertEdgeParams) => Promise<EdgeRow>;
+    insertEdgeNoReturn?: (params: InsertEdgeParams) => Promise<void>;
+    insertEdgesBatch?: (params: readonly InsertEdgeParams[]) => Promise<void>;
+    insertEdgesBatchReturning?: (params: readonly InsertEdgeParams[]) => Promise<readonly EdgeRow[]>;
     updateEdge: (params: UpdateEdgeParams) => Promise<EdgeRow>;
     deleteEdge: (params: DeleteEdgeParams) => Promise<void>;
     hardDeleteEdge: (params: HardDeleteEdgeParams) => Promise<void>;
     getEdge: (graphId: string, id: string) => Promise<EdgeRow | undefined>;
+    getEdges?: (graphId: string, ids: readonly string[]) => Promise<readonly EdgeRow[]>;
     countEdgesFrom: (params: CountEdgesFromParams) => Promise<number>;
     edgeExistsBetween: (params: EdgeExistsBetweenParams) => Promise<boolean>;
     findEdgesConnectedTo: (params: FindEdgesConnectedToParams) => Promise<readonly EdgeRow[]>;
@@ -318,6 +583,13 @@ type GraphBackend = Readonly<{
     createVectorIndex?: (params: CreateVectorIndexParams) => Promise<void>;
     dropVectorIndex?: (params: DropVectorIndexParams) => 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[]>;
+    /** Compile a Drizzle SQL object to { sql, params } without executing. */
+    compileSql?: (query: SQL) => Readonly<{
+        sql: string;
+        params: readonly unknown[];
+    }>;
     transaction: <T>(fn: (tx: TransactionBackend) => Promise<T>, options?: TransactionOptions) => Promise<T>;
     close: () => Promise<void>;
 }>;
@@ -357,7 +629,7 @@ type InsertSchemaParams = Readonly<{
     graphId: string;
     version: number;
     schemaHash: string;
-    schemaDoc: Record<string, unknown>;
+    schemaDoc: SerializedSchema;
     isActive: boolean;
 }>;
 /**
@@ -400,6 +672,10 @@ type FindNodesByKindParams = Readonly<{
     offset?: number;
     /** If true, exclude deleted nodes. Default true. */
     excludeDeleted?: boolean;
+    /** Temporal mode for filtering by validity period. */
+    temporalMode?: TemporalMode;
+    /** Timestamp for "current" and "asOf" temporal modes. */
+    asOf?: string;
 }>;
 /**
  * Parameters for counting nodes by kind.
@@ -409,6 +685,10 @@ type CountNodesByKindParams = Readonly<{
     kind: string;
     /** If true, exclude deleted nodes. Default true. */
     excludeDeleted?: boolean;
+    /** Temporal mode for filtering by validity period. */
+    temporalMode?: TemporalMode;
+    /** Timestamp for "current" and "asOf" temporal modes. */
+    asOf?: string;
 }>;
 /**
  * Parameters for finding edges by kind.
@@ -424,6 +704,10 @@ type FindEdgesByKindParams = Readonly<{
     offset?: number;
     /** If true, exclude deleted edges. Default true. */
     excludeDeleted?: boolean;
+    /** Temporal mode for filtering by validity period. */
+    temporalMode?: TemporalMode;
+    /** Timestamp for "current" and "asOf" temporal modes. */
+    asOf?: string;
 }>;
 /**
  * Parameters for counting edges by kind.
@@ -437,6 +721,10 @@ type CountEdgesByKindParams = Readonly<{
     toId?: string;
     /** If true, exclude deleted edges. Default true. */
     excludeDeleted?: boolean;
+    /** Temporal mode for filtering by validity period. */
+    temporalMode?: TemporalMode;
+    /** Timestamp for "current" and "asOf" temporal modes. */
+    asOf?: string;
 }>;
 
-export type { GraphBackend as G, SchemaVersionRow as S, TransactionBackend as T };
+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 SerializedNodeDef as S, type TransactionBackend as T, type SerializedEdgeDef as a, type SerializedMetaEdge as b, type SerializedOntologyRelation as c, type SerializedClosures as d, type SerializedSchema as e, type SchemaHash as f, type SerializedOntology as g, type SerializedUniqueConstraint as h, type SchemaVersionRow as i, type MetaEdgeProperties as j, type SqlSchema as k, type SqlTableNames as l, createSqlSchema as m, isMetaEdge as n };

package/dist/{types-a5rAxC92.d.cts → types-DHRsi6j9.d.cts}

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { A as AnyEdgeType, E as EdgeType, J as JsonPointer, V as ValueType, a as JsonPointerFor, b as JsonPointerSegmentsFor, N as NodeType } from './ast-BVyihVbP.cjs';
+import { A as AnyEdgeType, E as EdgeType, N as NodeType } from './types-DTJEu_-h.cjs';
+import { J as JsonPointer, V as ValueType, a as JsonPointerFor, b as JsonPointerSegmentsFor } from './ast-D-3bOanX.cjs';
 
 type IndexScope = 
 /**
@@ -122,7 +123,7 @@ type EdgeIndexConfig<E extends AnyEdgeType> = Readonly<{
 type NodeIndex<N extends NodeType = NodeType> = Readonly<{
     __type: "typegraph_node_index";
     node: N;
-    nodeKind: N["name"];
+    nodeKind: N["kind"];
     fields: readonly JsonPointer[];
     fieldValueTypes: readonly (ValueType | undefined)[];
     coveringFields: readonly JsonPointer[];
@@ -135,7 +136,7 @@ type NodeIndex<N extends NodeType = NodeType> = Readonly<{
 type EdgeIndex<E extends AnyEdgeType = EdgeType> = Readonly<{
     __type: "typegraph_edge_index";
     edge: E;
-    edgeKind: E["name"];
+    edgeKind: E["kind"];
     fields: readonly JsonPointer[];
     fieldValueTypes: readonly (ValueType | undefined)[];
     coveringFields: readonly JsonPointer[];

package/dist/types-DTJEu_-h.d.cts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+
+/** Brand key for NodeType */
+declare const NODE_TYPE_BRAND: "__nodeType";
+/** Brand key for EdgeType */
+declare const EDGE_TYPE_BRAND: "__edgeType";
+/** Brand symbol for NodeId */
+declare const __nodeId: unique symbol;
+/**
+ * A node type definition.
+ *
+ * Created via `defineNode()`. Represents a type of node in the graph
+ * with an associated Zod schema for properties.
+ */
+type NodeType<K extends string = string, S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> = Readonly<{
+    [NODE_TYPE_BRAND]: true;
+    kind: K;
+    schema: S;
+    description: string | undefined;
+}>;
+/**
+ * Branded node ID type.
+ *
+ * Prevents mixing IDs from different node types at compile time.
+ */
+type NodeId<N extends NodeType> = string & Readonly<{
+    [__nodeId]: N;
+}>;
+/**
+ * Infer the props type from a NodeType.
+ */
+type NodeProps<N extends NodeType> = z.infer<N["schema"]>;
+/**
+ * An edge type definition.
+ *
+ * Created via `defineEdge()`. Represents a type of edge in the graph
+ * with an optional Zod schema for properties.
+ *
+ * Optionally includes `from` and `to` arrays that define the allowed
+ * source and target node types (domain and range constraints).
+ */
+type EdgeType<K extends string = string, S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, From extends readonly NodeType[] | undefined = undefined, To extends readonly NodeType[] | undefined = undefined> = Readonly<{
+    [EDGE_TYPE_BRAND]: true;
+    kind: K;
+    schema: S;
+    description: string | undefined;
+    from: From;
+    to: To;
+}>;
+/**
+ * Base edge type for use in constraints - accepts any from/to configuration.
+ */
+type AnyEdgeType = EdgeType<string, z.ZodObject<z.ZodRawShape>, readonly NodeType[] | undefined, readonly NodeType[] | undefined>;
+/**
+ * An edge type that has both from and to constraints defined.
+ * Can be used directly in defineGraph without an EdgeRegistration wrapper.
+ */
+type EdgeTypeWithEndpoints = EdgeType<string, z.ZodObject<z.ZodRawShape>, readonly NodeType[], readonly NodeType[]>;
+/**
+ * Infer the props type from an EdgeType.
+ */
+type EdgeProps<E extends AnyEdgeType> = z.infer<E["schema"]>;
+/**
+ * Delete behaviors for nodes.
+ */
+type DeleteBehavior = "restrict" | "cascade" | "disconnect";
+/**
+ * Edge cardinality constraints.
+ */
+type Cardinality = "many" | "one" | "unique" | "oneActive";
+/**
+ * Endpoint existence modes for edge validation.
+ */
+type EndpointExistence = "notDeleted" | "currentlyValid" | "ever";
+/**
+ * Temporal query modes.
+ */
+type TemporalMode = "current" | "asOf" | "includeEnded" | "includeTombstones";
+/**
+ * Uniqueness constraint scope.
+ */
+type UniquenessScope = "kind" | "kindWithSubClasses";
+/**
+ * Collation for uniqueness constraints.
+ */
+type Collation = "binary" | "caseInsensitive";
+/**
+ * Uniqueness constraint definition.
+ */
+type UniqueConstraint<S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> = Readonly<{
+    name: string;
+    fields: readonly (keyof z.infer<S> & string)[];
+    where?: (props: UniqueConstraintPredicateBuilder<S>) => UniqueConstraintPredicate;
+    scope: UniquenessScope;
+    collation: Collation;
+}>;
+/**
+ * Predicate builder for uniqueness constraint where clause.
+ * Uses -? to make all fields required in the builder, even if optional in the schema.
+ */
+type UniqueConstraintPredicateBuilder<S extends z.ZodObject<z.ZodRawShape>> = Readonly<{
+    [K in keyof z.infer<S>]-?: UniqueConstraintField;
+}>;
+/**
+ * Field operations for uniqueness constraint predicates.
+ */
+type UniqueConstraintField = Readonly<{
+    isNull: () => UniqueConstraintPredicate;
+    isNotNull: () => UniqueConstraintPredicate;
+}>;
+/**
+ * A uniqueness constraint predicate (internal representation).
+ */
+type UniqueConstraintPredicate = Readonly<{
+    __type: "unique_predicate";
+    field: string;
+    op: "isNull" | "isNotNull";
+}>;
+/**
+ * Node registration in a graph definition.
+ */
+type NodeRegistration<N extends NodeType = NodeType> = Readonly<{
+    type: N;
+    unique?: readonly UniqueConstraint<N["schema"]>[];
+    onDelete?: DeleteBehavior;
+}>;
+/**
+ * Edge registration in a graph definition.
+ */
+type EdgeRegistration<E extends AnyEdgeType = AnyEdgeType, FromTypes extends NodeType = NodeType, ToTypes extends NodeType = NodeType> = Readonly<{
+    type: E;
+    from: readonly FromTypes[];
+    to: readonly ToTypes[];
+    cardinality?: Cardinality;
+    endpointExistence?: EndpointExistence;
+}>;
+/**
+ * Default settings for a graph.
+ */
+type GraphDefaults = Readonly<{
+    onNodeDelete?: DeleteBehavior;
+    temporalMode?: TemporalMode;
+}>;
+/**
+ * Checks if a value is a NodeType.
+ */
+declare function isNodeType(value: unknown): value is NodeType;
+/**
+ * Checks if a value is an EdgeType.
+ */
+declare function isEdgeType(value: unknown): value is AnyEdgeType;
+/**
+ * Checks if a value is an EdgeType with both from and to constraints defined.
+ * Such edges can be used directly in defineGraph without an EdgeRegistration wrapper.
+ */
+declare function isEdgeTypeWithEndpoints(value: unknown): value is EdgeTypeWithEndpoints;
+
+export { type AnyEdgeType as A, type Collation as C, type DeleteBehavior as D, type EdgeType as E, type GraphDefaults as G, type NodeType as N, type TemporalMode as T, type UniquenessScope as U, type NodeRegistration as a, type EdgeRegistration as b, type EdgeTypeWithEndpoints as c, type Cardinality as d, type EndpointExistence as e, type EdgeProps as f, type NodeId as g, type NodeProps as h, type UniqueConstraint as i, isEdgeType as j, isEdgeTypeWithEndpoints as k, isNodeType as l };