@nicia-ai/typegraph 0.1.0

package/dist/types-DDOSfrih.d.cts

@@ -0,0 +1,442 @@
+import { SQL } from 'drizzle-orm';
+import { S as SqlDialect } from './types-BRzHlhKC.cjs';
+
+/**
+ * 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 };

package/dist/types-D_3mEv2y.d.ts

@@ -0,0 +1,158 @@
+import { J as JsonPointer } from './ast-BVyihVbP.js';
+
+/**
+ * QueryProfiler types.
+ *
+ * Type definitions for the query profiling system that captures
+ * property access patterns and generates index recommendations.
+ */
+
+type ProfileEntityType = "node" | "edge";
+type PropertyTarget = Readonly<{
+    __type: "prop";
+    pointer: JsonPointer;
+}> | Readonly<{
+    __type: "system";
+    field: string;
+}>;
+/**
+ * Represents a property access path.
+ *
+ * @example
+ * ```typescript
+ * // Simple property access
+ * { entityType: "node", kind: "Person", target: { __type: "prop", pointer: "/email" } }
+ *
+ * // Nested property access
+ * { entityType: "node", kind: "Order", target: { __type: "prop", pointer: "/metadata/priority" } }
+ * ```
+ */
+type PropertyPath = Readonly<{
+    entityType: ProfileEntityType;
+    kind: string;
+    target: PropertyTarget;
+}>;
+/**
+ * Usage context for a property access.
+ */
+type UsageContext = "filter" | "sort" | "select" | "groupBy";
+/**
+ * Statistics for a property access pattern.
+ */
+type PropertyAccessStats = Readonly<{
+    /** Number of times this property was accessed */
+    count: number;
+    /** Contexts in which this property was used */
+    contexts: ReadonlySet<UsageContext>;
+    /** Predicate types used with this property (eq, contains, gt, etc.) */
+    predicateTypes: ReadonlySet<string>;
+    /** When this pattern was first observed */
+    firstSeen: Date;
+    /** When this pattern was last observed */
+    lastSeen: Date;
+}>;
+/**
+ * A declared index for comparison against usage patterns.
+ *
+ * Pass these to QueryProfiler to exclude already-indexed
+ * properties from recommendations.
+ */
+type DeclaredIndex = Readonly<{
+    /** Whether this index applies to nodes or edges */
+    entityType: ProfileEntityType;
+    /** The kind name this index applies to */
+    kind: string;
+    /** Props JSON pointers covered by this index (in key order for composite indexes) */
+    fields: readonly JsonPointer[];
+    /** Whether this is a unique index */
+    unique: boolean;
+    /** Index name (for reference in reports) */
+    name: string;
+}>;
+/**
+ * Priority level for index recommendations.
+ */
+type RecommendationPriority = "high" | "medium" | "low";
+/**
+ * An index recommendation based on observed query patterns.
+ */
+type IndexRecommendation = Readonly<{
+    /** Whether this recommendation is for nodes or edges */
+    entityType: ProfileEntityType;
+    /** The kind name that would benefit from this index */
+    kind: string;
+    /** Props JSON pointers to index (in key order for composite indexes) */
+    fields: readonly JsonPointer[];
+    /** Human-readable reason for the recommendation */
+    reason: string;
+    /** How often this property was accessed */
+    frequency: number;
+    /** Priority based on frequency and usage context */
+    priority: RecommendationPriority;
+}>;
+/**
+ * Summary statistics for a profiling session.
+ */
+type ProfileSummary = Readonly<{
+    /** Total number of queries executed */
+    totalQueries: number;
+    /** Number of unique property access patterns */
+    uniquePatterns: number;
+    /** When profiling started */
+    startedAt: Date;
+    /** Duration of profiling session in milliseconds */
+    durationMs: number;
+}>;
+/**
+ * Complete profiler report with patterns, recommendations, and summary.
+ *
+ * @example
+ * ```typescript
+ * const report = profiler.getReport();
+ *
+ * console.log(`Total queries: ${report.summary.totalQueries}`);
+ * console.log(`Unique patterns: ${report.summary.uniquePatterns}`);
+ *
+ * for (const rec of report.recommendations) {
+ *   console.log(`[${rec.priority}] ${rec.entityType}:${rec.kind} ${rec.fields.join(", ")}: ${rec.reason}`);
+ * }
+ * ```
+ */
+type ProfileReport = Readonly<{
+    /** All property access patterns aggregated by path */
+    patterns: ReadonlyMap<string, PropertyAccessStats>;
+    /** Index recommendations sorted by priority */
+    recommendations: readonly IndexRecommendation[];
+    /** Summary statistics */
+    summary: ProfileSummary;
+    /** Properties used in filters that lack indexes */
+    unindexedFilters: readonly PropertyPath[];
+}>;
+/**
+ * Options for configuring the QueryProfiler.
+ */
+type ProfilerOptions = Readonly<{
+    /**
+     * Declared indexes to compare against usage patterns.
+     * Properties covered by these indexes will be excluded from recommendations.
+     */
+    declaredIndexes?: readonly DeclaredIndex[];
+    /**
+     * Minimum frequency for a property to be included in recommendations.
+     * Properties accessed fewer times than this will not generate recommendations.
+     * @default 3
+     */
+    minFrequencyForRecommendation?: number;
+    /**
+     * Minimum frequency for a `medium` priority recommendation.
+     * @default 5
+     */
+    mediumFrequencyThreshold?: number;
+    /**
+     * Minimum frequency for a `high` priority recommendation.
+     * @default 10
+     */
+    highFrequencyThreshold?: number;
+}>;
+
+export type { DeclaredIndex as D, IndexRecommendation as I, ProfilerOptions as P, RecommendationPriority as R, UsageContext as U, ProfileReport as a, ProfileEntityType as b, PropertyTarget as c, PropertyPath as d, PropertyAccessStats as e, ProfileSummary as f };