@nicia-ai/typegraph 0.3.1 → 0.5.0

package/dist/{store-nbBybLWP.d.cts → store-nDW3GOFb.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-WX8V9dqn.cjs';
+import { K as KindRegistry, G as GraphDef, b as SchemaManagerOptions, c as SchemaValidationResult } from './manager-DiPf-0GG.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,59 @@ 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 findByEndpoints operations.
+ */
+type EdgeFindByEndpointsOptions<E extends AnyEdgeType> = Readonly<{
+    /**
+     * Edge property fields to include in the match alongside the (from, to) endpoints.
+     * When omitted, matches on endpoints only (returns first live edge).
+     */
+    matchOn?: readonly (keyof z.input<E["schema"]>)[];
+    /** Property values to match against when matchOn is specified. */
+    props?: Partial<z.input<E["schema"]>>;
+}>;
+/**
+ * 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 +884,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 +906,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 +932,46 @@ type NodeCollection<N extends NodeType> = Readonly<{
      * that don't exist.
      */
     bulkDelete: (ids: readonly NodeId<N>[]) => Promise<void>;
+    /**
+     * Find a node by uniqueness constraint.
+     *
+     * Looks up a live node by the named constraint key computed from `props`.
+     * Returns the node if found, or undefined. Soft-deleted nodes are excluded.
+     *
+     * @param constraintName - Name of the uniqueness constraint to match on
+     * @param props - Properties to compute the constraint key from
+     */
+    findByConstraint: (constraintName: string, props: z.input<N["schema"]>) => Promise<Node<N> | undefined>;
+    /**
+     * Batch version of findByConstraint.
+     *
+     * Results are returned in the same order as the input items.
+     * Returns undefined for entries that don't match.
+     */
+    bulkFindByConstraint: (constraintName: string, items: readonly Readonly<{
+        props: z.input<N["schema"]>;
+    }>[]) => Promise<(Node<N> | undefined)[]>;
+    /**
+     * 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 +1104,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 +1134,41 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
      * that don't exist.
      */
     bulkDelete: (ids: readonly string[]) => Promise<void>;
+    /**
+     * Find a live edge by endpoints and optional property fields.
+     *
+     * Returns the first matching live edge, or undefined.
+     * Soft-deleted edges are excluded.
+     *
+     * @param from - Source node
+     * @param to - Target node
+     * @param options - Match criteria (matchOn fields and property values)
+     */
+    findByEndpoints: (from: TypedNodeRef<From>, to: TypedNodeRef<To>, options?: EdgeFindByEndpointsOptions<E>) => Promise<Edge<E> | undefined>;
+    /**
+     * 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.
@@ -1747,6 +1875,16 @@ declare class Store<G extends GraphDef> {
      * ```
      */
     transaction<T>(fn: (tx: TransactionContext<G>) => Promise<T>): Promise<T>;
+    /**
+     * Hard-deletes all data for this graph from the database.
+     *
+     * Removes all nodes, edges, uniqueness entries, embeddings, and schema versions
+     * for this graph's ID. No hooks, no per-row logic. Wrapped in a transaction
+     * when the backend supports it.
+     *
+     * The store is usable after clearing — new data can be created immediately.
+     */
+    clear(): Promise<void>;
     /**
      * Closes the store and releases underlying resources.
      *
@@ -1817,4 +1955,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 { embedding as $, type AliasMap as A, type SelectableEdge as B, type CreateQueryBuilderOptions as C, type SelectableNode as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type StoreHooks as J, type StoreOptions as K, type StreamOptions as L, type TransactionContext 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 TypedEdgeCollection as U, type TypedNodeRef as V, UnionableQuery as W, type UpdateEdgeInput as X, type UpdateNodeInput as Y, createStore as Z, createStoreWithSchema as _, type AggregateResult as a, exists as a0, fieldRef as a1, getEmbeddingDimensions as a2, inSubquery as a3, isEmbeddingSchema as a4, isParameterRef as a5, notExists as a6, notInSubquery as a7, param as a8, type CreateEdgeInput as b, type CreateNodeInput as c, type Edge as d, type EdgeAccessor as e, type EdgeCollection as f, type EdgeFindByEndpointsOptions as g, type EdgeGetOrCreateByEndpointsOptions as h, type EdgeGetOrCreateByEndpointsResult as i, type EmbeddingSchema as j, type EmbeddingValue as k, ExecutableAggregateQuery as l, ExecutableQuery as m, type NodeAccessor as n, type NodeAlias as o, type NodeCollection as p, type NodeGetOrCreateByConstraintOptions as q, type NodeGetOrCreateByConstraintResult as r, type NodeRef as s, type PaginatedResult as t, type Predicate as u, PreparedQuery as v, type PropsAccessor as w, type QueryHookContext as x, type QueryOptions as y, type SelectContext as z };

package/dist/{types-Cdbi4hcx.d.ts → types-DpIoePMI.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>;
@@ -582,6 +583,11 @@ type GraphBackend = Readonly<{
     vectorSearch?: (params: VectorSearchParams) => Promise<readonly VectorSearchResult[]>;
     createVectorIndex?: (params: CreateVectorIndexParams) => Promise<void>;
     dropVectorIndex?: (params: DropVectorIndexParams) => Promise<void>;
+    /**
+     * Hard-deletes all data for a graph (nodes, edges, uniques, embeddings, schema versions).
+     * Intended for import-replacement workflows. No hooks, no per-row logic.
+     */
+    clearGraph: (graphId: string) => 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[]>;
@@ -621,6 +627,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.

package/dist/{types-DDP0MGBF.d.cts → types-WX8V9dqn.d.cts}

@@ -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>;
@@ -582,6 +583,11 @@ type GraphBackend = Readonly<{
     vectorSearch?: (params: VectorSearchParams) => Promise<readonly VectorSearchResult[]>;
     createVectorIndex?: (params: CreateVectorIndexParams) => Promise<void>;
     dropVectorIndex?: (params: DropVectorIndexParams) => Promise<void>;
+    /**
+     * Hard-deletes all data for a graph (nodes, edges, uniques, embeddings, schema versions).
+     * Intended for import-replacement workflows. No hooks, no per-row logic.
+     */
+    clearGraph: (graphId: string) => 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[]>;
@@ -621,6 +627,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicia-ai/typegraph",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "TypeScript-first embedded knowledge graph library with ontological reasoning",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -183,7 +183,7 @@
     "@vitest/coverage-v8": "^4.0.18",
     "better-sqlite3": "^12.6.2",
     "drizzle-orm": "^0.45.1",
-    "eslint": "^9.39.2",
+    "eslint": "^9.39.3",
     "fast-check": "^4.5.3",
     "pg": "^8.18.0",
     "sqlite-vec": "0.1.7-alpha.2",