@nicia-ai/typegraph 0.3.0 → 0.4.0

package/dist/interchange/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkZJHQZZT2_cjs = require('../chunk-ZJHQZZT2.cjs');
-require('../chunk-OYL2SGBD.cjs');
+var chunkK2ROKOK3_cjs = require('../chunk-K2ROKOK3.cjs');
+require('../chunk-44SXEVF4.cjs');
 var zod = require('zod');
 
 var FORMAT_VERSION = "1.0";
@@ -121,8 +121,8 @@ async function exportGraph(store, options) {
   const graph = store.graph;
   const graphId = store.graphId;
   const backend = store.backend;
-  const nodeKindsToExport = options_.nodeKinds ?? chunkZJHQZZT2_cjs.getNodeKinds(graph);
-  const edgeKindsToExport = options_.edgeKinds ?? chunkZJHQZZT2_cjs.getEdgeKinds(graph);
+  const nodeKindsToExport = options_.nodeKinds ?? chunkK2ROKOK3_cjs.getNodeKinds(graph);
+  const edgeKindsToExport = options_.edgeKinds ?? chunkK2ROKOK3_cjs.getEdgeKinds(graph);
   const nodes = [];
   for (const kind of nodeKindsToExport) {
     const kindNodes = await exportNodesOfKind(backend, graphId, kind, options_);
@@ -136,7 +136,7 @@ async function exportGraph(store, options) {
   const schemaVersion = await backend.getActiveSchema(graphId);
   return {
     formatVersion: FORMAT_VERSION,
-    exportedAt: chunkZJHQZZT2_cjs.nowIso(),
+    exportedAt: chunkK2ROKOK3_cjs.nowIso(),
     source: {
       type: "typegraph-export",
       graphId,
@@ -284,7 +284,7 @@ async function importGraph(store, data, options) {
 }
 function buildNodeSchemaMap(graph) {
   const map = /* @__PURE__ */ new Map();
-  for (const kindName of chunkZJHQZZT2_cjs.getNodeKinds(graph)) {
+  for (const kindName of chunkK2ROKOK3_cjs.getNodeKinds(graph)) {
     const registration = graph.nodes[kindName];
     map.set(kindName, {
       registration,
@@ -295,7 +295,7 @@ function buildNodeSchemaMap(graph) {
 }
 function buildEdgeSchemaMap(graph) {
   const map = /* @__PURE__ */ new Map();
-  for (const kindName of chunkZJHQZZT2_cjs.getEdgeKinds(graph)) {
+  for (const kindName of chunkK2ROKOK3_cjs.getEdgeKinds(graph)) {
     const registration = graph.edges[kindName];
     map.set(kindName, {
       registration,

package/dist/interchange/index.d.cts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { G as GraphDef } from '../manager-Jc5Btay9.cjs';
-import { S as Store } from '../store-nbBybLWP.cjs';
+import { G as GraphDef } from '../manager-0NysX4s6.cjs';
+import { S as Store } from '../store-DhoA5uRc.cjs';
 import '../types-DTJEu_-h.cjs';
-import '../types-DDP0MGBF.cjs';
+import '../types-BUy-pHKH.cjs';
 import 'drizzle-orm';
 import '../types-BRzHlhKC.cjs';
 import '../ast-D-3bOanX.cjs';

package/dist/interchange/index.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { G as GraphDef } from '../manager-e9LXthrx.js';
-import { S as Store } from '../store-DM3Tk3Pw.js';
+import { G as GraphDef } from '../manager-DFKe7ql3.js';
+import { S as Store } from '../store-SiovWEYA.js';
 import '../types-DTJEu_-h.js';
-import '../types-Cdbi4hcx.js';
+import '../types-6EKrWTs9.js';
 import 'drizzle-orm';
 import '../types-BRzHlhKC.js';
 import '../ast-CXFx6bF6.js';

package/dist/interchange/index.js

@@ -1,5 +1,5 @@
-import { getNodeKinds, getEdgeKinds, nowIso } from '../chunk-XDTYTNYL.js';
-import '../chunk-O5XPCJLF.js';
+import { getNodeKinds, getEdgeKinds, nowIso } from '../chunk-TGDFBLGS.js';
+import '../chunk-SJ2QMDXY.js';
 import { z } from 'zod';
 
 var FORMAT_VERSION = "1.0";

package/dist/{manager-Jc5Btay9.d.cts → manager-0NysX4s6.d.cts}

@@ -1,5 +1,5 @@
 import { a as NodeRegistration, b as EdgeRegistration, D as DeleteBehavior, T as TemporalMode, N as NodeType, c as EdgeTypeWithEndpoints, G as GraphDefaults, A as AnyEdgeType } from './types-DTJEu_-h.cjs';
-import { O as OntologyRelation, S as SerializedNodeDef, a as SerializedEdgeDef, e as SerializedSchema, G as GraphBackend, i as SchemaVersionRow } from './types-DDP0MGBF.cjs';
+import { O as OntologyRelation, S as SerializedNodeDef, a as SerializedEdgeDef, e as SerializedSchema, G as GraphBackend, i as SchemaVersionRow } from './types-BUy-pHKH.cjs';
 
 /** Brand key for GraphDef */
 declare const GRAPH_DEF_BRAND: "__graphDef";

package/dist/{manager-e9LXthrx.d.ts → manager-DFKe7ql3.d.ts}

@@ -1,5 +1,5 @@
 import { a as NodeRegistration, b as EdgeRegistration, D as DeleteBehavior, T as TemporalMode, N as NodeType, c as EdgeTypeWithEndpoints, G as GraphDefaults, A as AnyEdgeType } from './types-DTJEu_-h.js';
-import { O as OntologyRelation, S as SerializedNodeDef, a as SerializedEdgeDef, e as SerializedSchema, G as GraphBackend, i as SchemaVersionRow } from './types-Cdbi4hcx.js';
+import { O as OntologyRelation, S as SerializedNodeDef, a as SerializedEdgeDef, e as SerializedSchema, G as GraphBackend, i as SchemaVersionRow } from './types-6EKrWTs9.js';
 
 /** Brand key for GraphDef */
 declare const GRAPH_DEF_BRAND: "__graphDef";

package/dist/profiler/index.d.cts

@@ -1,11 +1,11 @@
-import { G as GraphDef } from '../manager-Jc5Btay9.cjs';
+import { G as GraphDef } from '../manager-0NysX4s6.cjs';
 import { Q as QueryAst } from '../ast-D-3bOanX.cjs';
-import { S as Store } from '../store-nbBybLWP.cjs';
+import { S as Store } from '../store-DhoA5uRc.cjs';
 import { P as ProfilerOptions, a as ProfileReport } from '../types-BL1GyVku.cjs';
 export { D as DeclaredIndex, I as IndexRecommendation, b as ProfileSummary, c as PropertyAccessStats, d as PropertyPath, R as RecommendationPriority, U as UsageContext } from '../types-BL1GyVku.cjs';
 import '../types-DTJEu_-h.cjs';
 import 'zod';
-import '../types-DDP0MGBF.cjs';
+import '../types-BUy-pHKH.cjs';
 import 'drizzle-orm';
 import '../types-BRzHlhKC.cjs';
 

package/dist/profiler/index.d.ts

@@ -1,11 +1,11 @@
-import { G as GraphDef } from '../manager-e9LXthrx.js';
+import { G as GraphDef } from '../manager-DFKe7ql3.js';
 import { Q as QueryAst } from '../ast-CXFx6bF6.js';
-import { S as Store } from '../store-DM3Tk3Pw.js';
+import { S as Store } from '../store-SiovWEYA.js';
 import { P as ProfilerOptions, a as ProfileReport } from '../types-DCGa53O2.js';
 export { D as DeclaredIndex, I as IndexRecommendation, b as ProfileSummary, c as PropertyAccessStats, d as PropertyPath, R as RecommendationPriority, U as UsageContext } from '../types-DCGa53O2.js';
 import '../types-DTJEu_-h.js';
 import 'zod';
-import '../types-Cdbi4hcx.js';
+import '../types-6EKrWTs9.js';
 import 'drizzle-orm';
 import '../types-BRzHlhKC.js';
 

package/dist/schema/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunkDD6ONEBN_cjs = require('../chunk-DD6ONEBN.cjs');
-require('../chunk-ZJHQZZT2.cjs');
-require('../chunk-OYL2SGBD.cjs');
+var chunkLDM2AFKZ_cjs = require('../chunk-LDM2AFKZ.cjs');
+require('../chunk-K2ROKOK3.cjs');
+require('../chunk-44SXEVF4.cjs');
 
 // src/schema/deserializer.ts
 function deserializeSchema(schema) {
@@ -42,7 +42,7 @@ function buildRegistryFromClosures(schema) {
   const edgeImplyingClosure = recordToMap(closures.edgeImplyingClosure);
   const nodeKinds = /* @__PURE__ */ new Map();
   const edgeKinds = /* @__PURE__ */ new Map();
-  return new chunkDD6ONEBN_cjs.KindRegistry(nodeKinds, edgeKinds, {
+  return new chunkLDM2AFKZ_cjs.KindRegistry(nodeKinds, edgeKinds, {
     subClassAncestors,
     subClassDescendants,
     broaderClosure,
@@ -70,75 +70,75 @@ function simpleRecordToMap(record) {
 
 Object.defineProperty(exports, "computeSchemaDiff", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.computeSchemaDiff; }
+  get: function () { return chunkLDM2AFKZ_cjs.computeSchemaDiff; }
 });
 Object.defineProperty(exports, "computeSchemaHash", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.computeSchemaHash; }
+  get: function () { return chunkLDM2AFKZ_cjs.computeSchemaHash; }
 });
 Object.defineProperty(exports, "createValidationError", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.createValidationError; }
+  get: function () { return chunkLDM2AFKZ_cjs.createValidationError; }
 });
 Object.defineProperty(exports, "deserializeWherePredicate", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.deserializeWherePredicate; }
+  get: function () { return chunkLDM2AFKZ_cjs.deserializeWherePredicate; }
 });
 Object.defineProperty(exports, "ensureSchema", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.ensureSchema; }
+  get: function () { return chunkLDM2AFKZ_cjs.ensureSchema; }
 });
 Object.defineProperty(exports, "getActiveSchema", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.getActiveSchema; }
+  get: function () { return chunkLDM2AFKZ_cjs.getActiveSchema; }
 });
 Object.defineProperty(exports, "getMigrationActions", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.getMigrationActions; }
+  get: function () { return chunkLDM2AFKZ_cjs.getMigrationActions; }
 });
 Object.defineProperty(exports, "getSchemaChanges", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.getSchemaChanges; }
+  get: function () { return chunkLDM2AFKZ_cjs.getSchemaChanges; }
 });
 Object.defineProperty(exports, "initializeSchema", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.initializeSchema; }
+  get: function () { return chunkLDM2AFKZ_cjs.initializeSchema; }
 });
 Object.defineProperty(exports, "isBackwardsCompatible", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.isBackwardsCompatible; }
+  get: function () { return chunkLDM2AFKZ_cjs.isBackwardsCompatible; }
 });
 Object.defineProperty(exports, "isSchemaInitialized", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.isSchemaInitialized; }
+  get: function () { return chunkLDM2AFKZ_cjs.isSchemaInitialized; }
 });
 Object.defineProperty(exports, "migrateSchema", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.migrateSchema; }
+  get: function () { return chunkLDM2AFKZ_cjs.migrateSchema; }
 });
 Object.defineProperty(exports, "rollbackSchema", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.rollbackSchema; }
+  get: function () { return chunkLDM2AFKZ_cjs.rollbackSchema; }
 });
 Object.defineProperty(exports, "serializeSchema", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.serializeSchema; }
+  get: function () { return chunkLDM2AFKZ_cjs.serializeSchema; }
 });
 Object.defineProperty(exports, "validateEdgeProps", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.validateEdgeProps; }
+  get: function () { return chunkLDM2AFKZ_cjs.validateEdgeProps; }
 });
 Object.defineProperty(exports, "validateNodeProps", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.validateNodeProps; }
+  get: function () { return chunkLDM2AFKZ_cjs.validateNodeProps; }
 });
 Object.defineProperty(exports, "validateProps", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.validateProps; }
+  get: function () { return chunkLDM2AFKZ_cjs.validateProps; }
 });
 Object.defineProperty(exports, "wrapZodError", {
   enumerable: true,
-  get: function () { return chunkDD6ONEBN_cjs.wrapZodError; }
+  get: function () { return chunkLDM2AFKZ_cjs.wrapZodError; }
 });
 exports.deserializeSchema = deserializeSchema;
 //# sourceMappingURL=index.cjs.map

package/dist/schema/index.d.cts

@@ -1,9 +1,9 @@
-import { K as KindRegistry, G as GraphDef } from '../manager-Jc5Btay9.cjs';
-export { C as ChangeSeverity, a as ChangeType, E as EdgeChange, M as MigrationHookContext, N as NodeChange, O as OntologyChange, S as SchemaDiff, b as SchemaManagerOptions, c as SchemaValidationResult, d as computeSchemaDiff, e as ensureSchema, g as getActiveSchema, f as getMigrationActions, h as getSchemaChanges, i as initializeSchema, j as isBackwardsCompatible, k as isSchemaInitialized, m as migrateSchema, r as rollbackSchema } from '../manager-Jc5Btay9.cjs';
-import { S as SerializedNodeDef, a as SerializedEdgeDef, b as SerializedMetaEdge, c as SerializedOntologyRelation, d as SerializedClosures, e as SerializedSchema, f as SchemaHash } from '../types-DDP0MGBF.cjs';
-export { J as JsonSchema, g as SerializedOntology, h as SerializedUniqueConstraint } from '../types-DDP0MGBF.cjs';
+import { K as KindRegistry, G as GraphDef } from '../manager-0NysX4s6.cjs';
+export { C as ChangeSeverity, a as ChangeType, E as EdgeChange, M as MigrationHookContext, N as NodeChange, O as OntologyChange, S as SchemaDiff, b as SchemaManagerOptions, c as SchemaValidationResult, d as computeSchemaDiff, e as ensureSchema, g as getActiveSchema, f as getMigrationActions, h as getSchemaChanges, i as initializeSchema, j as isBackwardsCompatible, k as isSchemaInitialized, m as migrateSchema, r as rollbackSchema } from '../manager-0NysX4s6.cjs';
+import { S as SerializedNodeDef, a as SerializedEdgeDef, b as SerializedMetaEdge, c as SerializedOntologyRelation, d as SerializedClosures, e as SerializedSchema, f as SchemaHash } from '../types-BUy-pHKH.cjs';
+export { J as JsonSchema, g as SerializedOntology, h as SerializedUniqueConstraint } from '../types-BUy-pHKH.cjs';
 import { ZodType, ZodError } from 'zod';
-import { V as ValidationIssue, a as ValidationError } from '../index-Dkicw49A.cjs';
+import { V as ValidationIssue, a as ValidationError } from '../index-DyrR_d-H.cjs';
 import '../types-DTJEu_-h.cjs';
 import 'drizzle-orm';
 import '../types-BRzHlhKC.cjs';

package/dist/schema/index.d.ts

@@ -1,9 +1,9 @@
-import { K as KindRegistry, G as GraphDef } from '../manager-e9LXthrx.js';
-export { C as ChangeSeverity, a as ChangeType, E as EdgeChange, M as MigrationHookContext, N as NodeChange, O as OntologyChange, S as SchemaDiff, b as SchemaManagerOptions, c as SchemaValidationResult, d as computeSchemaDiff, e as ensureSchema, g as getActiveSchema, f as getMigrationActions, h as getSchemaChanges, i as initializeSchema, j as isBackwardsCompatible, k as isSchemaInitialized, m as migrateSchema, r as rollbackSchema } from '../manager-e9LXthrx.js';
-import { S as SerializedNodeDef, a as SerializedEdgeDef, b as SerializedMetaEdge, c as SerializedOntologyRelation, d as SerializedClosures, e as SerializedSchema, f as SchemaHash } from '../types-Cdbi4hcx.js';
-export { J as JsonSchema, g as SerializedOntology, h as SerializedUniqueConstraint } from '../types-Cdbi4hcx.js';
+import { K as KindRegistry, G as GraphDef } from '../manager-DFKe7ql3.js';
+export { C as ChangeSeverity, a as ChangeType, E as EdgeChange, M as MigrationHookContext, N as NodeChange, O as OntologyChange, S as SchemaDiff, b as SchemaManagerOptions, c as SchemaValidationResult, d as computeSchemaDiff, e as ensureSchema, g as getActiveSchema, f as getMigrationActions, h as getSchemaChanges, i as initializeSchema, j as isBackwardsCompatible, k as isSchemaInitialized, m as migrateSchema, r as rollbackSchema } from '../manager-DFKe7ql3.js';
+import { S as SerializedNodeDef, a as SerializedEdgeDef, b as SerializedMetaEdge, c as SerializedOntologyRelation, d as SerializedClosures, e as SerializedSchema, f as SchemaHash } from '../types-6EKrWTs9.js';
+export { J as JsonSchema, g as SerializedOntology, h as SerializedUniqueConstraint } from '../types-6EKrWTs9.js';
 import { ZodType, ZodError } from 'zod';
-import { V as ValidationIssue, a as ValidationError } from '../index-Dkicw49A.js';
+import { V as ValidationIssue, a as ValidationError } from '../index-DyrR_d-H.js';
 import '../types-DTJEu_-h.js';
 import 'drizzle-orm';
 import '../types-BRzHlhKC.js';

package/dist/schema/index.js

@@ -1,7 +1,7 @@
-import { KindRegistry } from '../chunk-NP4G4ZKM.js';
-export { computeSchemaDiff, computeSchemaHash, createValidationError, deserializeWherePredicate, ensureSchema, getActiveSchema, getMigrationActions, getSchemaChanges, initializeSchema, isBackwardsCompatible, isSchemaInitialized, migrateSchema, rollbackSchema, serializeSchema, validateEdgeProps, validateNodeProps, validateProps, wrapZodError } from '../chunk-NP4G4ZKM.js';
-import '../chunk-XDTYTNYL.js';
-import '../chunk-O5XPCJLF.js';
+import { KindRegistry } from '../chunk-M5SOQ7UV.js';
+export { computeSchemaDiff, computeSchemaHash, createValidationError, deserializeWherePredicate, ensureSchema, getActiveSchema, getMigrationActions, getSchemaChanges, initializeSchema, isBackwardsCompatible, isSchemaInitialized, migrateSchema, rollbackSchema, serializeSchema, validateEdgeProps, validateNodeProps, validateProps, wrapZodError } from '../chunk-M5SOQ7UV.js';
+import '../chunk-TGDFBLGS.js';
+import '../chunk-SJ2QMDXY.js';
 
 // src/schema/deserializer.ts
 function deserializeSchema(schema) {

package/dist/{store-nbBybLWP.d.cts → store-DhoA5uRc.d.cts}

@@ -1,5 +1,5 @@
-import { k as SqlSchema, G as GraphBackend } from './types-DDP0MGBF.cjs';
-import { K as KindRegistry, G as GraphDef, b as SchemaManagerOptions, c as SchemaValidationResult } from './manager-Jc5Btay9.cjs';
+import { k as SqlSchema, G as GraphBackend } from './types-BUy-pHKH.cjs';
+import { K as KindRegistry, G as GraphDef, b as SchemaManagerOptions, c as SchemaValidationResult } from './manager-0NysX4s6.cjs';
 import { N as NodeType, A as AnyEdgeType, T as TemporalMode, E as EdgeType, b as EdgeRegistration, g as NodeId } from './types-DTJEu_-h.cjs';
 import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, d as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, o as RecursiveCyclePolicy, q as TraversalDirection, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-D-3bOanX.cjs';
 import { SQL } from 'drizzle-orm';
@@ -724,7 +724,7 @@ type OperationHookContext = HookContext & Readonly<{
 /**
  * Observability hooks for monitoring store operations.
  *
- * Note: Batch operations (`bulkCreate`, `bulkInsert`, `bulkUpsert`) skip
+ * Note: Batch operations (`bulkCreate`, `bulkInsert`, `bulkUpsertById`) skip
  * per-item operation hooks for throughput. Query hooks still fire normally.
  *
  * @example
@@ -776,6 +776,47 @@ type StoreOptions = Readonly<{
         traversalExpansion?: TraversalExpansion;
     }>;
 }>;
+/**
+ * Behavior when a get-or-create operation matches an existing record.
+ */
+type IfExistsMode = "return" | "update";
+/**
+ * Action taken by a get-or-create operation.
+ */
+type GetOrCreateAction = "created" | "found" | "updated" | "resurrected";
+/**
+ * Result of a node getOrCreateByConstraint operation.
+ */
+type NodeGetOrCreateByConstraintResult<N extends NodeType> = Readonly<{
+    node: Node<N>;
+    action: GetOrCreateAction;
+}>;
+/**
+ * Options for node getOrCreateByConstraint operations.
+ */
+type NodeGetOrCreateByConstraintOptions = Readonly<{
+    /** Existing record behavior. Default: "return" */
+    ifExists?: IfExistsMode;
+}>;
+/**
+ * Result of an edge getOrCreateByEndpoints operation.
+ */
+type EdgeGetOrCreateByEndpointsResult<E extends AnyEdgeType> = Readonly<{
+    edge: Edge<E>;
+    action: GetOrCreateAction;
+}>;
+/**
+ * Options for edge getOrCreateByEndpoints operations.
+ */
+type EdgeGetOrCreateByEndpointsOptions<E extends AnyEdgeType> = Readonly<{
+    /**
+     * Edge property fields to include in the match key alongside the (from, to) endpoints.
+     * Default: `[]` — match on endpoints only.
+     */
+    matchOn?: readonly (keyof z.input<E["schema"]>)[];
+    /** Existing record behavior. Default: "return" */
+    ifExists?: IfExistsMode;
+}>;
 /**
  * A collection of nodes of a specific type.
  *
@@ -831,7 +872,7 @@ type NodeCollection<N extends NodeType> = Readonly<{
      * If a node with the given ID exists, updates it with the provided props.
      * Otherwise, creates a new node with that ID.
      */
-    upsert: (id: string, props: z.input<N["schema"]>, options?: Readonly<{
+    upsertById: (id: string, props: z.input<N["schema"]>, options?: Readonly<{
         validFrom?: string;
         validTo?: string;
     }>) => Promise<Node<N>>;
@@ -853,7 +894,7 @@ type NodeCollection<N extends NodeType> = Readonly<{
      * For each item, if a node with the given ID exists, updates it.
      * Otherwise, creates a new node with that ID.
      */
-    bulkUpsert: (items: readonly Readonly<{
+    bulkUpsertById: (items: readonly Readonly<{
         id: string;
         props: z.input<N["schema"]>;
         validFrom?: string;
@@ -879,6 +920,27 @@ type NodeCollection<N extends NodeType> = Readonly<{
      * that don't exist.
      */
     bulkDelete: (ids: readonly NodeId<N>[]) => Promise<void>;
+    /**
+     * Get an existing node by uniqueness constraint, or create a new one.
+     *
+     * Looks up a node by the named constraint key computed from `props`.
+     * If found, returns it (optionally updating with `ifExists: "update"`).
+     * If not found, creates a new node. Soft-deleted matches are always resurrected.
+     *
+     * @param constraintName - Name of the uniqueness constraint to match on
+     * @param props - Full properties for create, or merge source for update
+     * @param options - Existing record behavior (default: "return")
+     */
+    getOrCreateByConstraint: (constraintName: string, props: z.input<N["schema"]>, options?: NodeGetOrCreateByConstraintOptions) => Promise<NodeGetOrCreateByConstraintResult<N>>;
+    /**
+     * Batch version of getOrCreateByConstraint.
+     *
+     * Results are returned in the same order as the input items.
+     * Atomic when the backend supports transactions.
+     */
+    bulkGetOrCreateByConstraint: (constraintName: string, items: readonly Readonly<{
+        props: z.input<N["schema"]>;
+    }>[], options?: NodeGetOrCreateByConstraintOptions) => Promise<NodeGetOrCreateByConstraintResult<N>[]>;
 }>;
 /**
  * Reference to a node endpoint (kind and id).
@@ -1011,7 +1073,7 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
      * For each item, if an edge with the given ID exists, updates it.
      * Otherwise, creates a new edge with that ID.
      */
-    bulkUpsert: (items: readonly Readonly<{
+    bulkUpsertById: (items: readonly Readonly<{
         id: string;
         from: TypedNodeRef<From>;
         to: TypedNodeRef<To>;
@@ -1041,6 +1103,30 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
      * that don't exist.
      */
     bulkDelete: (ids: readonly string[]) => Promise<void>;
+    /**
+     * Get an existing edge by endpoints and optional property fields, or create a new one.
+     *
+     * Matches edges of this kind between `(from, to)`. When `matchOn` specifies
+     * property fields, only edges whose properties match on those fields are considered.
+     * Soft-deleted matches are resurrected when cardinality allows.
+     *
+     * @param from - Source node
+     * @param to - Target node
+     * @param props - Full properties for create, or merge source for update
+     * @param options - Match criteria and conflict resolution
+     */
+    getOrCreateByEndpoints: (from: TypedNodeRef<From>, to: TypedNodeRef<To>, props: z.input<E["schema"]>, options?: EdgeGetOrCreateByEndpointsOptions<E>) => Promise<EdgeGetOrCreateByEndpointsResult<E>>;
+    /**
+     * Batch version of getOrCreateByEndpoints.
+     *
+     * Results are returned in the same order as the input items.
+     * Atomic when the backend supports transactions.
+     */
+    bulkGetOrCreateByEndpoints: (items: readonly Readonly<{
+        from: TypedNodeRef<From>;
+        to: TypedNodeRef<To>;
+        props: z.input<E["schema"]>;
+    }>[], options?: EdgeGetOrCreateByEndpointsOptions<E>) => Promise<EdgeGetOrCreateByEndpointsResult<E>[]>;
 }>;
 /**
  * Extract the union of 'from' node types from an EdgeRegistration.
@@ -1817,4 +1903,4 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  */
 declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions & SchemaManagerOptions): Promise<[Store<G>, SchemaValidationResult]>;
 
-export { notExists as $, type AliasMap as A, type TransactionContext as B, type CreateQueryBuilderOptions as C, type TypedEdgeCollection as D, type EdgeAliasMap as E, type FieldAccessor as F, type TypedNodeRef as G, type HookContext as H, type UpdateEdgeInput as I, type UpdateNodeInput as J, createStore as K, createStoreWithSchema as L, embedding as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, Store as S, TraversalBuilder as T, UnionableQuery as U, exists as V, fieldRef as W, getEmbeddingDimensions as X, inSubquery as Y, isEmbeddingSchema as Z, isParameterRef as _, type AggregateResult as a, notInSubquery as a0, param as a1, type CreateEdgeInput as b, type CreateNodeInput as c, type Edge as d, type EdgeAccessor as e, type EdgeCollection as f, type EmbeddingSchema as g, type EmbeddingValue as h, ExecutableAggregateQuery as i, ExecutableQuery as j, type NodeAccessor as k, type NodeAlias as l, type NodeCollection as m, type NodeRef as n, type PaginatedResult as o, type Predicate as p, PreparedQuery as q, type PropsAccessor as r, type QueryHookContext as s, type QueryOptions as t, type SelectContext as u, type SelectableEdge as v, type SelectableNode as w, type StoreHooks as x, type StoreOptions as y, type StreamOptions as z };
+export { exists as $, type AliasMap as A, type SelectableNode as B, type CreateQueryBuilderOptions as C, type StoreHooks as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type StoreOptions as J, type StreamOptions as K, type TransactionContext as L, type TypedEdgeCollection as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, Store as S, TraversalBuilder as T, type TypedNodeRef as U, UnionableQuery as V, type UpdateEdgeInput as W, type UpdateNodeInput as X, createStore as Y, createStoreWithSchema as Z, embedding as _, type AggregateResult as a, fieldRef as a0, getEmbeddingDimensions as a1, inSubquery as a2, isEmbeddingSchema as a3, isParameterRef as a4, notExists as a5, notInSubquery as a6, param as a7, type CreateEdgeInput as b, type CreateNodeInput as c, type Edge as d, type EdgeAccessor as e, type EdgeCollection as f, type EdgeGetOrCreateByEndpointsOptions as g, type EdgeGetOrCreateByEndpointsResult as h, type EmbeddingSchema as i, type EmbeddingValue as j, ExecutableAggregateQuery as k, ExecutableQuery as l, type NodeAccessor as m, type NodeAlias as n, type NodeCollection as o, type NodeGetOrCreateByConstraintOptions as p, type NodeGetOrCreateByConstraintResult as q, type NodeRef as r, type PaginatedResult as s, type Predicate as t, PreparedQuery as u, type PropsAccessor as v, type QueryHookContext as w, type QueryOptions as x, type SelectContext as y, type SelectableEdge as z };

package/dist/{store-DM3Tk3Pw.d.ts → store-SiovWEYA.d.ts}

@@ -1,5 +1,5 @@
-import { k as SqlSchema, G as GraphBackend } from './types-Cdbi4hcx.js';
-import { K as KindRegistry, G as GraphDef, b as SchemaManagerOptions, c as SchemaValidationResult } from './manager-e9LXthrx.js';
+import { k as SqlSchema, G as GraphBackend } from './types-6EKrWTs9.js';
+import { K as KindRegistry, G as GraphDef, b as SchemaManagerOptions, c as SchemaValidationResult } from './manager-DFKe7ql3.js';
 import { N as NodeType, A as AnyEdgeType, T as TemporalMode, E as EdgeType, b as EdgeRegistration, g as NodeId } from './types-DTJEu_-h.js';
 import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, d as JsonPointerInput, T as TraversalExpansion, l as Traversal, N as NodePredicate, m as ProjectedField, O as OrderSpec, G as GroupBySpec, o as RecursiveCyclePolicy, q as TraversalDirection, A as AggregateExpr, r as SelectiveField, s as ComposableQuery, t as SetOperationType, u as SetOperation, S as SortDirection } from './ast-CXFx6bF6.js';
 import { SQL } from 'drizzle-orm';
@@ -724,7 +724,7 @@ type OperationHookContext = HookContext & Readonly<{
 /**
  * Observability hooks for monitoring store operations.
  *
- * Note: Batch operations (`bulkCreate`, `bulkInsert`, `bulkUpsert`) skip
+ * Note: Batch operations (`bulkCreate`, `bulkInsert`, `bulkUpsertById`) skip
  * per-item operation hooks for throughput. Query hooks still fire normally.
  *
  * @example
@@ -776,6 +776,47 @@ type StoreOptions = Readonly<{
         traversalExpansion?: TraversalExpansion;
     }>;
 }>;
+/**
+ * Behavior when a get-or-create operation matches an existing record.
+ */
+type IfExistsMode = "return" | "update";
+/**
+ * Action taken by a get-or-create operation.
+ */
+type GetOrCreateAction = "created" | "found" | "updated" | "resurrected";
+/**
+ * Result of a node getOrCreateByConstraint operation.
+ */
+type NodeGetOrCreateByConstraintResult<N extends NodeType> = Readonly<{
+    node: Node<N>;
+    action: GetOrCreateAction;
+}>;
+/**
+ * Options for node getOrCreateByConstraint operations.
+ */
+type NodeGetOrCreateByConstraintOptions = Readonly<{
+    /** Existing record behavior. Default: "return" */
+    ifExists?: IfExistsMode;
+}>;
+/**
+ * Result of an edge getOrCreateByEndpoints operation.
+ */
+type EdgeGetOrCreateByEndpointsResult<E extends AnyEdgeType> = Readonly<{
+    edge: Edge<E>;
+    action: GetOrCreateAction;
+}>;
+/**
+ * Options for edge getOrCreateByEndpoints operations.
+ */
+type EdgeGetOrCreateByEndpointsOptions<E extends AnyEdgeType> = Readonly<{
+    /**
+     * Edge property fields to include in the match key alongside the (from, to) endpoints.
+     * Default: `[]` — match on endpoints only.
+     */
+    matchOn?: readonly (keyof z.input<E["schema"]>)[];
+    /** Existing record behavior. Default: "return" */
+    ifExists?: IfExistsMode;
+}>;
 /**
  * A collection of nodes of a specific type.
  *
@@ -831,7 +872,7 @@ type NodeCollection<N extends NodeType> = Readonly<{
      * If a node with the given ID exists, updates it with the provided props.
      * Otherwise, creates a new node with that ID.
      */
-    upsert: (id: string, props: z.input<N["schema"]>, options?: Readonly<{
+    upsertById: (id: string, props: z.input<N["schema"]>, options?: Readonly<{
         validFrom?: string;
         validTo?: string;
     }>) => Promise<Node<N>>;
@@ -853,7 +894,7 @@ type NodeCollection<N extends NodeType> = Readonly<{
      * For each item, if a node with the given ID exists, updates it.
      * Otherwise, creates a new node with that ID.
      */
-    bulkUpsert: (items: readonly Readonly<{
+    bulkUpsertById: (items: readonly Readonly<{
         id: string;
         props: z.input<N["schema"]>;
         validFrom?: string;
@@ -879,6 +920,27 @@ type NodeCollection<N extends NodeType> = Readonly<{
      * that don't exist.
      */
     bulkDelete: (ids: readonly NodeId<N>[]) => Promise<void>;
+    /**
+     * Get an existing node by uniqueness constraint, or create a new one.
+     *
+     * Looks up a node by the named constraint key computed from `props`.
+     * If found, returns it (optionally updating with `ifExists: "update"`).
+     * If not found, creates a new node. Soft-deleted matches are always resurrected.
+     *
+     * @param constraintName - Name of the uniqueness constraint to match on
+     * @param props - Full properties for create, or merge source for update
+     * @param options - Existing record behavior (default: "return")
+     */
+    getOrCreateByConstraint: (constraintName: string, props: z.input<N["schema"]>, options?: NodeGetOrCreateByConstraintOptions) => Promise<NodeGetOrCreateByConstraintResult<N>>;
+    /**
+     * Batch version of getOrCreateByConstraint.
+     *
+     * Results are returned in the same order as the input items.
+     * Atomic when the backend supports transactions.
+     */
+    bulkGetOrCreateByConstraint: (constraintName: string, items: readonly Readonly<{
+        props: z.input<N["schema"]>;
+    }>[], options?: NodeGetOrCreateByConstraintOptions) => Promise<NodeGetOrCreateByConstraintResult<N>[]>;
 }>;
 /**
  * Reference to a node endpoint (kind and id).
@@ -1011,7 +1073,7 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
      * For each item, if an edge with the given ID exists, updates it.
      * Otherwise, creates a new edge with that ID.
      */
-    bulkUpsert: (items: readonly Readonly<{
+    bulkUpsertById: (items: readonly Readonly<{
         id: string;
         from: TypedNodeRef<From>;
         to: TypedNodeRef<To>;
@@ -1041,6 +1103,30 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
      * that don't exist.
      */
     bulkDelete: (ids: readonly string[]) => Promise<void>;
+    /**
+     * Get an existing edge by endpoints and optional property fields, or create a new one.
+     *
+     * Matches edges of this kind between `(from, to)`. When `matchOn` specifies
+     * property fields, only edges whose properties match on those fields are considered.
+     * Soft-deleted matches are resurrected when cardinality allows.
+     *
+     * @param from - Source node
+     * @param to - Target node
+     * @param props - Full properties for create, or merge source for update
+     * @param options - Match criteria and conflict resolution
+     */
+    getOrCreateByEndpoints: (from: TypedNodeRef<From>, to: TypedNodeRef<To>, props: z.input<E["schema"]>, options?: EdgeGetOrCreateByEndpointsOptions<E>) => Promise<EdgeGetOrCreateByEndpointsResult<E>>;
+    /**
+     * Batch version of getOrCreateByEndpoints.
+     *
+     * Results are returned in the same order as the input items.
+     * Atomic when the backend supports transactions.
+     */
+    bulkGetOrCreateByEndpoints: (items: readonly Readonly<{
+        from: TypedNodeRef<From>;
+        to: TypedNodeRef<To>;
+        props: z.input<E["schema"]>;
+    }>[], options?: EdgeGetOrCreateByEndpointsOptions<E>) => Promise<EdgeGetOrCreateByEndpointsResult<E>[]>;
 }>;
 /**
  * Extract the union of 'from' node types from an EdgeRegistration.
@@ -1817,4 +1903,4 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  */
 declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions & SchemaManagerOptions): Promise<[Store<G>, SchemaValidationResult]>;
 
-export { notExists as $, type AliasMap as A, type TransactionContext as B, type CreateQueryBuilderOptions as C, type TypedEdgeCollection as D, type EdgeAliasMap as E, type FieldAccessor as F, type TypedNodeRef as G, type HookContext as H, type UpdateEdgeInput as I, type UpdateNodeInput as J, createStore as K, createStoreWithSchema as L, embedding as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, Store as S, TraversalBuilder as T, UnionableQuery as U, exists as V, fieldRef as W, getEmbeddingDimensions as X, inSubquery as Y, isEmbeddingSchema as Z, isParameterRef as _, type AggregateResult as a, notInSubquery as a0, param as a1, type CreateEdgeInput as b, type CreateNodeInput as c, type Edge as d, type EdgeAccessor as e, type EdgeCollection as f, type EmbeddingSchema as g, type EmbeddingValue as h, ExecutableAggregateQuery as i, ExecutableQuery as j, type NodeAccessor as k, type NodeAlias as l, type NodeCollection as m, type NodeRef as n, type PaginatedResult as o, type Predicate as p, PreparedQuery as q, type PropsAccessor as r, type QueryHookContext as s, type QueryOptions as t, type SelectContext as u, type SelectableEdge as v, type SelectableNode as w, type StoreHooks as x, type StoreOptions as y, type StreamOptions as z };
+export { exists as $, type AliasMap as A, type SelectableNode as B, type CreateQueryBuilderOptions as C, type StoreHooks as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type StoreOptions as J, type StreamOptions as K, type TransactionContext as L, type TypedEdgeCollection as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, Store as S, TraversalBuilder as T, type TypedNodeRef as U, UnionableQuery as V, type UpdateEdgeInput as W, type UpdateNodeInput as X, createStore as Y, createStoreWithSchema as Z, embedding as _, type AggregateResult as a, fieldRef as a0, getEmbeddingDimensions as a1, inSubquery as a2, isEmbeddingSchema as a3, isParameterRef as a4, notExists as a5, notInSubquery as a6, param as a7, type CreateEdgeInput as b, type CreateNodeInput as c, type Edge as d, type EdgeAccessor as e, type EdgeCollection as f, type EdgeGetOrCreateByEndpointsOptions as g, type EdgeGetOrCreateByEndpointsResult as h, type EmbeddingSchema as i, type EmbeddingValue as j, ExecutableAggregateQuery as k, ExecutableQuery as l, type NodeAccessor as m, type NodeAlias as n, type NodeCollection as o, type NodeGetOrCreateByConstraintOptions as p, type NodeGetOrCreateByConstraintResult as q, type NodeRef as r, type PaginatedResult as s, type Predicate as t, PreparedQuery as u, type PropsAccessor as v, type QueryHookContext as w, type QueryOptions as x, type SelectContext as y, type SelectableEdge as z };

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

@@ -572,6 +572,7 @@ type GraphBackend = Readonly<{
     insertUnique: (params: InsertUniqueParams) => Promise<void>;
     deleteUnique: (params: DeleteUniqueParams) => Promise<void>;
     checkUnique: (params: CheckUniqueParams) => Promise<UniqueRow | undefined>;
+    checkUniqueBatch?: (params: CheckUniqueBatchParams) => Promise<readonly UniqueRow[]>;
     getActiveSchema: (graphId: string) => Promise<SchemaVersionRow | undefined>;
     getSchemaVersion: (graphId: string, version: number) => Promise<SchemaVersionRow | undefined>;
     insertSchema: (params: InsertSchemaParams) => Promise<SchemaVersionRow>;
@@ -621,6 +622,19 @@ type CheckUniqueParams = Readonly<{
     nodeKind: string;
     constraintName: string;
     key: string;
+    /** If true, also returns soft-deleted entries. Used by get-or-create operations. */
+    includeDeleted?: boolean;
+}>;
+/**
+ * Parameters for batch-checking unique constraints.
+ */
+type CheckUniqueBatchParams = Readonly<{
+    graphId: string;
+    nodeKind: string;
+    constraintName: string;
+    keys: readonly string[];
+    /** If true, also returns soft-deleted entries. Used by get-or-create operations. */
+    includeDeleted?: boolean;
 }>;
 /**
  * Parameters for inserting a schema version.