@nicia-ai/typegraph 0.2.0 → 0.3.0

package/dist/{test-helpers-BjyRYJZX.d.ts → test-helpers-CIq1Hhj1.d.ts}

@@ -10,6 +10,10 @@ declare function generateSqliteDDL(tables?: SqliteTables): string[];
  * Convenience function that joins all DDL statements.
  */
 declare function getSqliteMigrationSQL(tables?: SqliteTables): string;
+/**
+ * Generates all DDL statements for the given PostgreSQL tables.
+ */
+declare function generatePostgresDDL(tables?: PostgresTables): string[];
 /**
  * Generates a single SQL string for PostgreSQL migrations.
  * Convenience function that joins all DDL statements.
@@ -19,4 +23,4 @@ declare function getSqliteMigrationSQL(tables?: SqliteTables): string;
  */
 declare function getPostgresMigrationSQL(tables?: PostgresTables): string;
 
-export { generateSqliteDDL as a, getSqliteMigrationSQL as b, getPostgresMigrationSQL as g };
+export { getPostgresMigrationSQL as a, generateSqliteDDL as b, getSqliteMigrationSQL as c, generatePostgresDDL as g };

package/dist/{test-helpers-NoQXhleQ.d.cts → test-helpers-DPRFVky4.d.cts}

@@ -10,6 +10,10 @@ declare function generateSqliteDDL(tables?: SqliteTables): string[];
  * Convenience function that joins all DDL statements.
  */
 declare function getSqliteMigrationSQL(tables?: SqliteTables): string;
+/**
+ * Generates all DDL statements for the given PostgreSQL tables.
+ */
+declare function generatePostgresDDL(tables?: PostgresTables): string[];
 /**
  * Generates a single SQL string for PostgreSQL migrations.
  * Convenience function that joins all DDL statements.
@@ -19,4 +23,4 @@ declare function getSqliteMigrationSQL(tables?: SqliteTables): string;
  */
 declare function getPostgresMigrationSQL(tables?: PostgresTables): string;
 
-export { generateSqliteDDL as a, getSqliteMigrationSQL as b, getPostgresMigrationSQL as g };
+export { getPostgresMigrationSQL as a, generateSqliteDDL as b, getSqliteMigrationSQL as c, generatePostgresDDL as g };

package/dist/{types-D_3mEv2y.d.ts → types-BL1GyVku.d.cts}

@@ -1,4 +1,4 @@
-import { J as JsonPointer } from './ast-BVyihVbP.js';
+import { J as JsonPointer } from './ast-D-3bOanX.cjs';
 
 /**
  * QueryProfiler types.
@@ -155,4 +155,4 @@ type ProfilerOptions = Readonly<{
     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 };
+export type { DeclaredIndex as D, IndexRecommendation as I, ProfilerOptions as P, RecommendationPriority as R, UsageContext as U, ProfileReport as a, ProfileSummary as b, PropertyAccessStats as c, PropertyPath as d };

package/dist/{types-DsRfx0yk.d.ts → types-Cdbi4hcx.d.ts}

@@ -1,6 +1,57 @@
 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.js';
 import { S as SqlDialect } from './types-BRzHlhKC.js';
 
+/** 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
  *
@@ -63,6 +114,144 @@ declare function createSqlSchema(names?: Partial<SqlTableNames>): SqlSchema;
  */
 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.
  *
@@ -92,7 +281,6 @@ type VectorCapabilities = Readonly<{
     maxDimensions: number;
 }>;
 
-type Dialect = SqlDialect;
 /**
  * Backend capabilities that vary by dialect.
  */
@@ -236,6 +424,7 @@ type UpdateEdgeParams = Readonly<{
     id: string;
     props: Record<string, unknown>;
     validTo?: string;
+    clearDeleted?: boolean;
 }>;
 /**
  * Parameters for deleting an edge (soft delete).
@@ -296,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;
 }>;
 /**
@@ -346,21 +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[]>;
@@ -382,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>;
 }>;
@@ -421,7 +629,7 @@ type InsertSchemaParams = Readonly<{
     graphId: string;
     version: number;
     schemaHash: string;
-    schemaDoc: Record<string, unknown>;
+    schemaDoc: SerializedSchema;
     isActive: boolean;
 }>;
 /**
@@ -464,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.
@@ -473,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.
@@ -488,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.
@@ -501,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 { DEFAULT_SQL_SCHEMA as D, type GraphBackend as G, type SqlSchema as S, type TransactionBackend as T, type SqlTableNames as a, type SchemaVersionRow as b, createSqlSchema as c };
+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-BrSfFSpW.d.cts → types-DCGa53O2.d.ts}

@@ -1,4 +1,4 @@
-import { J as JsonPointer } from './ast-BVyihVbP.cjs';
+import { J as JsonPointer } from './ast-CXFx6bF6.js';
 
 /**
  * QueryProfiler types.
@@ -155,4 +155,4 @@ type ProfilerOptions = Readonly<{
     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 };
+export type { DeclaredIndex as D, IndexRecommendation as I, ProfilerOptions as P, RecommendationPriority as R, UsageContext as U, ProfileReport as a, ProfileSummary as b, PropertyAccessStats as c, PropertyPath as d };