@nicia-ai/typegraph 0.1.0

package/dist/types-CjZ7g_7v.d.ts

@@ -0,0 +1,442 @@
+import { SQL } from 'drizzle-orm';
+import { S as SqlDialect } from './types-BRzHlhKC.js';
+
+/**
+ * Backend interface types for TypeGraph storage.
+ *
+ * The backend abstracts database operations, allowing different
+ * SQL implementations (SQLite, PostgreSQL) behind a common interface.
+ */
+
+/**
+ * Supported vector similarity metrics.
+ */
+type VectorMetric = "cosine" | "l2" | "inner_product";
+/**
+ * Supported vector index types.
+ */
+type VectorIndexType = "hnsw" | "ivfflat" | "none";
+/**
+ * Vector search capabilities.
+ */
+type VectorCapabilities = Readonly<{
+    /** Whether the backend supports vector operations */
+    supported: boolean;
+    /** Supported similarity metrics */
+    metrics: readonly VectorMetric[];
+    /** Supported index types */
+    indexTypes: readonly VectorIndexType[];
+    /** Maximum dimensions supported */
+    maxDimensions: number;
+}>;
+
+type Dialect = SqlDialect;
+/**
+ * Backend capabilities that vary by dialect.
+ */
+type BackendCapabilities = Readonly<{
+    /** Whether the backend supports JSONB type (vs TEXT for JSON) */
+    jsonb: boolean;
+    /** Whether the backend supports partial indexes */
+    partialIndexes: boolean;
+    /** Whether the backend supports GIN indexes for JSON */
+    ginIndexes: boolean;
+    /** Whether the backend supports CTE (WITH) queries */
+    cte: boolean;
+    /** Whether the backend supports RETURNING clause */
+    returning: boolean;
+    /** Whether the backend supports atomic transactions (D1 does not) */
+    transactions: boolean;
+    /** Vector search capabilities (undefined if not configured) */
+    vector?: VectorCapabilities | undefined;
+}>;
+/**
+ * A row from the typegraph_nodes table.
+ */
+type NodeRow = Readonly<{
+    graph_id: string;
+    kind: string;
+    id: string;
+    props: string;
+    version: number;
+    valid_from: string | undefined;
+    valid_to: string | undefined;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | undefined;
+}>;
+/**
+ * A row from the typegraph_edges table.
+ */
+type EdgeRow = Readonly<{
+    graph_id: string;
+    id: string;
+    kind: string;
+    from_kind: string;
+    from_id: string;
+    to_kind: string;
+    to_id: string;
+    props: string;
+    valid_from: string | undefined;
+    valid_to: string | undefined;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | undefined;
+}>;
+/**
+ * A row from the typegraph_node_uniques table.
+ */
+type UniqueRow = Readonly<{
+    graph_id: string;
+    node_kind: string;
+    constraint_name: string;
+    key: string;
+    node_id: string;
+    concrete_kind: string;
+    deleted_at: string | undefined;
+}>;
+/**
+ * A row from the typegraph_schema_versions table.
+ */
+type SchemaVersionRow = Readonly<{
+    graph_id: string;
+    version: number;
+    schema_hash: string;
+    schema_doc: string;
+    created_at: string;
+    is_active: boolean;
+}>;
+/**
+ * A row from the typegraph_node_embeddings table.
+ */
+type EmbeddingRow = Readonly<{
+    graph_id: string;
+    node_kind: string;
+    node_id: string;
+    field_path: string;
+    embedding: readonly number[];
+    dimensions: number;
+    created_at: string;
+    updated_at: string;
+}>;
+/**
+ * Parameters for inserting a node.
+ */
+type InsertNodeParams = Readonly<{
+    graphId: string;
+    kind: string;
+    id: string;
+    props: Record<string, unknown>;
+    validFrom?: string;
+    validTo?: string;
+}>;
+/**
+ * Parameters for updating a node.
+ */
+type UpdateNodeParams = Readonly<{
+    graphId: string;
+    kind: string;
+    id: string;
+    props: Record<string, unknown>;
+    validTo?: string;
+    incrementVersion?: boolean;
+    /** If true, clears deleted_at (un-deletes the node). Used by upsert. */
+    clearDeleted?: boolean;
+}>;
+/**
+ * Parameters for deleting a node (soft delete).
+ */
+type DeleteNodeParams = Readonly<{
+    graphId: string;
+    kind: string;
+    id: string;
+}>;
+/**
+ * Parameters for inserting an edge.
+ */
+type InsertEdgeParams = Readonly<{
+    graphId: string;
+    id: string;
+    kind: string;
+    fromKind: string;
+    fromId: string;
+    toKind: string;
+    toId: string;
+    props: Record<string, unknown>;
+    validFrom?: string;
+    validTo?: string;
+}>;
+/**
+ * Parameters for updating an edge.
+ */
+type UpdateEdgeParams = Readonly<{
+    graphId: string;
+    id: string;
+    props: Record<string, unknown>;
+    validTo?: string;
+}>;
+/**
+ * Parameters for deleting an edge (soft delete).
+ */
+type DeleteEdgeParams = Readonly<{
+    graphId: string;
+    id: string;
+}>;
+/**
+ * Parameters for hard deleting a node (permanent removal).
+ */
+type HardDeleteNodeParams = Readonly<{
+    graphId: string;
+    kind: string;
+    id: string;
+}>;
+/**
+ * Parameters for hard deleting an edge (permanent removal).
+ */
+type HardDeleteEdgeParams = Readonly<{
+    graphId: string;
+    id: string;
+}>;
+/**
+ * Parameters for inserting or updating an embedding.
+ */
+type UpsertEmbeddingParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    nodeId: string;
+    fieldPath: string;
+    embedding: readonly number[];
+    dimensions: number;
+}>;
+/**
+ * Parameters for deleting an embedding.
+ */
+type DeleteEmbeddingParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    nodeId: string;
+    fieldPath: string;
+}>;
+/**
+ * Parameters for vector similarity search.
+ */
+type VectorSearchParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    fieldPath: string;
+    queryEmbedding: readonly number[];
+    metric: VectorMetric;
+    limit: number;
+    minScore?: number;
+}>;
+/**
+ * Result from a vector similarity search.
+ */
+type VectorSearchResult = Readonly<{
+    nodeId: string;
+    score: number;
+}>;
+/**
+ * Parameters for creating a vector index.
+ */
+type CreateVectorIndexParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    fieldPath: string;
+    dimensions: number;
+    metric: VectorMetric;
+    indexType: VectorIndexType;
+    /** Index-specific parameters */
+    indexParams?: Readonly<{
+        /** HNSW: max connections per layer */
+        m?: number;
+        /** HNSW: construction search depth */
+        efConstruction?: number;
+        /** IVFFlat: number of lists */
+        lists?: number;
+    }>;
+}>;
+/**
+ * Parameters for dropping a vector index.
+ */
+type DropVectorIndexParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    fieldPath: string;
+}>;
+/**
+ * Transaction options.
+ */
+type TransactionOptions = Readonly<{
+    /** Transaction isolation level (if supported) */
+    isolationLevel?: "read_uncommitted" | "read_committed" | "repeatable_read" | "serializable";
+}>;
+/**
+ * Transaction backend - a backend scoped to a transaction.
+ */
+type TransactionBackend = Omit<GraphBackend, "transaction" | "close">;
+/**
+ * The GraphBackend interface abstracts database operations.
+ *
+ * Implementations should provide:
+ * - SQLite backend via better-sqlite3 or libsql
+ * - PostgreSQL backend via pg or postgres
+ */
+type GraphBackend = Readonly<{
+    /** The SQL dialect */
+    dialect: Dialect;
+    /** Backend capabilities */
+    capabilities: BackendCapabilities;
+    insertNode: (params: InsertNodeParams) => Promise<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>;
+    insertEdge: (params: InsertEdgeParams) => Promise<EdgeRow>;
+    updateEdge: (params: UpdateEdgeParams) => Promise<EdgeRow>;
+    deleteEdge: (params: DeleteEdgeParams) => Promise<void>;
+    hardDeleteEdge: (params: HardDeleteEdgeParams) => Promise<void>;
+    getEdge: (graphId: string, id: string) => Promise<EdgeRow | undefined>;
+    countEdgesFrom: (params: CountEdgesFromParams) => Promise<number>;
+    edgeExistsBetween: (params: EdgeExistsBetweenParams) => Promise<boolean>;
+    findEdgesConnectedTo: (params: FindEdgesConnectedToParams) => Promise<readonly EdgeRow[]>;
+    findNodesByKind: (params: FindNodesByKindParams) => Promise<readonly NodeRow[]>;
+    countNodesByKind: (params: CountNodesByKindParams) => Promise<number>;
+    findEdgesByKind: (params: FindEdgesByKindParams) => Promise<readonly EdgeRow[]>;
+    countEdgesByKind: (params: CountEdgesByKindParams) => Promise<number>;
+    insertUnique: (params: InsertUniqueParams) => Promise<void>;
+    deleteUnique: (params: DeleteUniqueParams) => Promise<void>;
+    checkUnique: (params: CheckUniqueParams) => Promise<UniqueRow | undefined>;
+    getActiveSchema: (graphId: string) => Promise<SchemaVersionRow | undefined>;
+    getSchemaVersion: (graphId: string, version: number) => Promise<SchemaVersionRow | undefined>;
+    insertSchema: (params: InsertSchemaParams) => Promise<SchemaVersionRow>;
+    setActiveSchema: (graphId: string, version: number) => Promise<void>;
+    upsertEmbedding?: (params: UpsertEmbeddingParams) => Promise<void>;
+    deleteEmbedding?: (params: DeleteEmbeddingParams) => Promise<void>;
+    getEmbedding?: (graphId: string, nodeKind: string, nodeId: string, fieldPath: string) => Promise<EmbeddingRow | undefined>;
+    vectorSearch?: (params: VectorSearchParams) => Promise<readonly VectorSearchResult[]>;
+    createVectorIndex?: (params: CreateVectorIndexParams) => Promise<void>;
+    dropVectorIndex?: (params: DropVectorIndexParams) => Promise<void>;
+    execute: <T>(query: SQL) => Promise<readonly T[]>;
+    transaction: <T>(fn: (tx: TransactionBackend) => Promise<T>, options?: TransactionOptions) => Promise<T>;
+    close: () => Promise<void>;
+}>;
+/**
+ * Parameters for inserting a unique constraint entry.
+ */
+type InsertUniqueParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    constraintName: string;
+    key: string;
+    nodeId: string;
+    concreteKind: string;
+}>;
+/**
+ * Parameters for deleting a unique constraint entry.
+ */
+type DeleteUniqueParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    constraintName: string;
+    key: string;
+}>;
+/**
+ * Parameters for checking a unique constraint.
+ */
+type CheckUniqueParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    constraintName: string;
+    key: string;
+}>;
+/**
+ * Parameters for inserting a schema version.
+ */
+type InsertSchemaParams = Readonly<{
+    graphId: string;
+    version: number;
+    schemaHash: string;
+    schemaDoc: Record<string, unknown>;
+    isActive: boolean;
+}>;
+/**
+ * Parameters for counting edges from a source node.
+ */
+type CountEdgesFromParams = Readonly<{
+    graphId: string;
+    edgeKind: string;
+    fromKind: string;
+    fromId: string;
+    /** If true, only count edges where valid_to IS NULL */
+    activeOnly?: boolean;
+}>;
+/**
+ * Parameters for checking if an edge exists between two nodes.
+ */
+type EdgeExistsBetweenParams = Readonly<{
+    graphId: string;
+    edgeKind: string;
+    fromKind: string;
+    fromId: string;
+    toKind: string;
+    toId: string;
+}>;
+/**
+ * Parameters for finding edges connected to a node.
+ */
+type FindEdgesConnectedToParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    nodeId: string;
+}>;
+/**
+ * Parameters for finding nodes by kind.
+ */
+type FindNodesByKindParams = Readonly<{
+    graphId: string;
+    kind: string;
+    limit?: number;
+    offset?: number;
+    /** If true, exclude deleted nodes. Default true. */
+    excludeDeleted?: boolean;
+}>;
+/**
+ * Parameters for counting nodes by kind.
+ */
+type CountNodesByKindParams = Readonly<{
+    graphId: string;
+    kind: string;
+    /** If true, exclude deleted nodes. Default true. */
+    excludeDeleted?: boolean;
+}>;
+/**
+ * Parameters for finding edges by kind.
+ */
+type FindEdgesByKindParams = Readonly<{
+    graphId: string;
+    kind: string;
+    fromKind?: string;
+    fromId?: string;
+    toKind?: string;
+    toId?: string;
+    limit?: number;
+    offset?: number;
+    /** If true, exclude deleted edges. Default true. */
+    excludeDeleted?: boolean;
+}>;
+/**
+ * Parameters for counting edges by kind.
+ */
+type CountEdgesByKindParams = Readonly<{
+    graphId: string;
+    kind: string;
+    fromKind?: string;
+    fromId?: string;
+    toKind?: string;
+    toId?: string;
+    /** If true, exclude deleted edges. Default true. */
+    excludeDeleted?: boolean;
+}>;
+
+export type { GraphBackend as G, SchemaVersionRow as S, TransactionBackend as T };