@nicia-ai/typegraph 0.1.0

package/dist/test-helpers-BjyRYJZX.d.ts

@@ -0,0 +1,22 @@
+import { PostgresTables } from './backend/drizzle/schema/postgres.js';
+import { SqliteTables } from './backend/drizzle/schema/sqlite.js';
+
+/**
+ * Generates all DDL statements for the given SQLite tables.
+ */
+declare function generateSqliteDDL(tables?: SqliteTables): string[];
+/**
+ * Generates a single SQL string for SQLite migrations.
+ * Convenience function that joins all DDL statements.
+ */
+declare function getSqliteMigrationSQL(tables?: SqliteTables): string;
+/**
+ * Generates a single SQL string for PostgreSQL migrations.
+ * Convenience function that joins all DDL statements.
+ *
+ * Includes CREATE EXTENSION for pgvector since the embeddings table
+ * uses the native VECTOR type.
+ */
+declare function getPostgresMigrationSQL(tables?: PostgresTables): string;
+
+export { generateSqliteDDL as a, getSqliteMigrationSQL as b, getPostgresMigrationSQL as g };

package/dist/test-helpers-NoQXhleQ.d.cts

@@ -0,0 +1,22 @@
+import { PostgresTables } from './backend/drizzle/schema/postgres.cjs';
+import { SqliteTables } from './backend/drizzle/schema/sqlite.cjs';
+
+/**
+ * Generates all DDL statements for the given SQLite tables.
+ */
+declare function generateSqliteDDL(tables?: SqliteTables): string[];
+/**
+ * Generates a single SQL string for SQLite migrations.
+ * Convenience function that joins all DDL statements.
+ */
+declare function getSqliteMigrationSQL(tables?: SqliteTables): string;
+/**
+ * Generates a single SQL string for PostgreSQL migrations.
+ * Convenience function that joins all DDL statements.
+ *
+ * Includes CREATE EXTENSION for pgvector since the embeddings table
+ * uses the native VECTOR type.
+ */
+declare function getPostgresMigrationSQL(tables?: PostgresTables): string;
+
+export { generateSqliteDDL as a, getSqliteMigrationSQL as b, getPostgresMigrationSQL as g };

package/dist/types-BRzHlhKC.d.cts

@@ -0,0 +1,14 @@
+/**
+ * SQL Dialect Abstraction Layer
+ *
+ * Provides a unified interface for dialect-specific SQL generation.
+ * Implementing a new dialect (MySQL, SQL Server, etc.) requires
+ * implementing this interface.
+ */
+
+/**
+ * Supported SQL dialects.
+ */
+type SqlDialect = "sqlite" | "postgres";
+
+export type { SqlDialect as S };

package/dist/types-BRzHlhKC.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SQL Dialect Abstraction Layer
+ *
+ * Provides a unified interface for dialect-specific SQL generation.
+ * Implementing a new dialect (MySQL, SQL Server, etc.) requires
+ * implementing this interface.
+ */
+
+/**
+ * Supported SQL dialects.
+ */
+type SqlDialect = "sqlite" | "postgres";
+
+export type { SqlDialect as S };

package/dist/types-BrSfFSpW.d.cts

@@ -0,0 +1,158 @@
+import { J as JsonPointer } from './ast-BVyihVbP.cjs';
+
+/**
+ * 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 };

package/dist/types-CX4cLd7M.d.ts

@@ -0,0 +1,152 @@
+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.js';
+
+type IndexScope = 
+/**
+ * Prefix index keys with `(graph_id, kind)` (nodes) or `(graph_id, kind)` (edges).
+ *
+ * This matches TypeGraph queries which always filter on `graph_id` and `kind`
+ * (often as `IN (...)` due to ontology expansion).
+ */
+"graphAndKind"
+/**
+ * Prefix index keys with `graph_id` only.
+ */
+ | "graph"
+/**
+ * Do not prefix index keys with TypeGraph system columns.
+ */
+ | "none";
+type IndexWhereOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn";
+type IndexWhereExpression = Readonly<{
+    __type: "index_where_and";
+    predicates: readonly IndexWhereExpression[];
+}> | Readonly<{
+    __type: "index_where_or";
+    predicates: readonly IndexWhereExpression[];
+}> | Readonly<{
+    __type: "index_where_not";
+    predicate: IndexWhereExpression;
+}> | Readonly<{
+    __type: "index_where_comparison";
+    left: IndexWhereOperand;
+    op: IndexWhereOp;
+    right: IndexWhereLiteral | readonly IndexWhereLiteral[];
+}> | Readonly<{
+    __type: "index_where_null_check";
+    operand: IndexWhereOperand;
+    op: "isNull" | "isNotNull";
+}>;
+type IndexWhereOperand = Readonly<{
+    __type: "index_operand_system";
+    column: SystemColumnName;
+    valueType: ValueType | undefined;
+}> | Readonly<{
+    __type: "index_operand_prop";
+    field: string;
+    valueType: ValueType | undefined;
+}>;
+type IndexWhereLiteral = Readonly<{
+    __type: "index_where_literal";
+    value: string | number | boolean;
+    valueType: ValueType;
+}>;
+type IndexWhereComparableValue<T> = NonNullable<T> extends string ? string : NonNullable<T> extends number ? number : NonNullable<T> extends boolean ? boolean : NonNullable<T> extends Date ? Date | string : never;
+type IndexWhereFieldBuilder<T> = Readonly<{
+    eq: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    neq: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    gt: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    gte: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    lt: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    lte: (value: IndexWhereComparableValue<T>) => IndexWhereExpression;
+    in: (values: readonly IndexWhereComparableValue<T>[]) => IndexWhereExpression;
+    notIn: (values: readonly IndexWhereComparableValue<T>[]) => IndexWhereExpression;
+    isNull: () => IndexWhereExpression;
+    isNotNull: () => IndexWhereExpression;
+}>;
+type NodeIndexWhereBuilder<N extends NodeType> = Readonly<{
+    graphId: IndexWhereFieldBuilder<string>;
+    kind: IndexWhereFieldBuilder<string>;
+    id: IndexWhereFieldBuilder<string>;
+    deletedAt: IndexWhereFieldBuilder<string | undefined>;
+    validFrom: IndexWhereFieldBuilder<string | undefined>;
+    validTo: IndexWhereFieldBuilder<string | undefined>;
+    createdAt: IndexWhereFieldBuilder<string>;
+    updatedAt: IndexWhereFieldBuilder<string>;
+    version: IndexWhereFieldBuilder<number>;
+} & {
+    [K in keyof z.infer<N["schema"]>]-?: IndexWhereFieldBuilder<z.infer<N["schema"]>[K]>;
+}>;
+type EdgeIndexWhereBuilder<E extends AnyEdgeType> = Readonly<{
+    graphId: IndexWhereFieldBuilder<string>;
+    kind: IndexWhereFieldBuilder<string>;
+    id: IndexWhereFieldBuilder<string>;
+    fromKind: IndexWhereFieldBuilder<string>;
+    fromId: IndexWhereFieldBuilder<string>;
+    toKind: IndexWhereFieldBuilder<string>;
+    toId: IndexWhereFieldBuilder<string>;
+    deletedAt: IndexWhereFieldBuilder<string | undefined>;
+    validFrom: IndexWhereFieldBuilder<string | undefined>;
+    validTo: IndexWhereFieldBuilder<string | undefined>;
+    createdAt: IndexWhereFieldBuilder<string>;
+    updatedAt: IndexWhereFieldBuilder<string>;
+} & {
+    [K in keyof z.infer<E["schema"]>]-?: IndexWhereFieldBuilder<z.infer<E["schema"]>[K]>;
+}>;
+type IndexWhereInput<Builder> = IndexWhereExpression | ((where: Builder) => IndexWhereExpression);
+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"]>>[];
+    coveringFields?: readonly IndexFieldInput<z.infer<N["schema"]>>[] | undefined;
+    unique?: boolean | undefined;
+    name?: string | undefined;
+    scope?: IndexScope | undefined;
+    where?: IndexWhereInput<NodeIndexWhereBuilder<N>> | undefined;
+}>;
+type EdgeIndexDirection = "out" | "in" | "none";
+type EdgeIndexConfig<E extends AnyEdgeType> = Readonly<{
+    fields: readonly IndexFieldInput<z.infer<E["schema"]>>[];
+    coveringFields?: readonly IndexFieldInput<z.infer<E["schema"]>>[] | undefined;
+    unique?: boolean | undefined;
+    name?: string | undefined;
+    scope?: IndexScope | undefined;
+    /**
+     * Optional direction hint to prefix edge indexes with the join key that
+     * TypeGraph traversal queries use (`from_id` for out, `to_id` for in).
+     */
+    direction?: EdgeIndexDirection | undefined;
+    where?: IndexWhereInput<EdgeIndexWhereBuilder<E>> | undefined;
+}>;
+type NodeIndex<N extends NodeType = NodeType> = Readonly<{
+    __type: "typegraph_node_index";
+    node: N;
+    nodeKind: N["name"];
+    fields: readonly JsonPointer[];
+    fieldValueTypes: readonly (ValueType | undefined)[];
+    coveringFields: readonly JsonPointer[];
+    coveringFieldValueTypes: readonly (ValueType | undefined)[];
+    unique: boolean;
+    scope: IndexScope;
+    where: IndexWhereExpression | undefined;
+    name: string;
+}>;
+type EdgeIndex<E extends AnyEdgeType = EdgeType> = Readonly<{
+    __type: "typegraph_edge_index";
+    edge: E;
+    edgeKind: E["name"];
+    fields: readonly JsonPointer[];
+    fieldValueTypes: readonly (ValueType | undefined)[];
+    coveringFields: readonly JsonPointer[];
+    coveringFieldValueTypes: readonly (ValueType | undefined)[];
+    unique: boolean;
+    scope: IndexScope;
+    direction: EdgeIndexDirection;
+    where: IndexWhereExpression | undefined;
+    name: string;
+}>;
+type TypeGraphIndex = NodeIndex | EdgeIndex;
+type SystemColumnName = "graph_id" | "kind" | "id" | "from_kind" | "from_id" | "to_kind" | "to_id" | "deleted_at" | "valid_from" | "valid_to" | "created_at" | "updated_at" | "version";
+
+export type { EdgeIndex as E, IndexWhereExpression as I, NodeIndex as N, SystemColumnName as S, TypeGraphIndex as T, EdgeIndexConfig as a, NodeIndexConfig as b, EdgeIndexDirection as c, EdgeIndexWhereBuilder as d, IndexScope as e, IndexWhereFieldBuilder as f, IndexWhereInput as g, NodeIndexWhereBuilder as h };