@nicia-ai/typegraph 0.11.1 → 0.13.0

package/dist/interchange/index.d.cts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { G as GraphDef } from '../manager-DGSnJa1v.cjs';
-import { L as Store } from '../store-C01_WsOg.cjs';
+import { U as Store } from '../store-Bmdt_dS6.cjs';
 import '../types-DMzKq0d5.cjs';
 import '../types-GLkwvQvS.cjs';
 import 'drizzle-orm';

package/dist/interchange/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { G as GraphDef } from '../manager-BCLhWysp.js';
-import { L as Store } from '../store-Cy6gSNqg.js';
+import { U as Store } from '../store-6-vH0ZIj.js';
 import '../types-DMzKq0d5.js';
 import '../types-1YJKodRv.js';
 import 'drizzle-orm';

package/dist/profiler/index.d.cts

@@ -1,6 +1,6 @@
 import { G as GraphDef } from '../manager-DGSnJa1v.cjs';
 import { Q as QueryAst } from '../ast-Bh2NDeaK.cjs';
-import { L as Store } from '../store-C01_WsOg.cjs';
+import { U as Store } from '../store-Bmdt_dS6.cjs';
 import { P as ProfilerOptions, a as ProfileReport } from '../types-CVtGFpB9.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-CVtGFpB9.cjs';
 import '../types-DMzKq0d5.cjs';

package/dist/profiler/index.d.ts

@@ -1,6 +1,6 @@
 import { G as GraphDef } from '../manager-BCLhWysp.js';
 import { Q as QueryAst } from '../ast-COMyNeMn.js';
-import { L as Store } from '../store-Cy6gSNqg.js';
+import { U as Store } from '../store-6-vH0ZIj.js';
 import { P as ProfilerOptions, a as ProfileReport } from '../types-COPePE8_.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-COPePE8_.js';
 import '../types-DMzKq0d5.js';

package/dist/{store-Cy6gSNqg.d.ts → store-6-vH0ZIj.d.ts}

@@ -1,9 +1,9 @@
-import { S as SqlSchema, G as GraphBackend } from './types-1YJKodRv.js';
+import { S as SqlSchema, G as GraphBackend, T as TransactionBackend } from './types-1YJKodRv.js';
 import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, f as SchemaValidationResult } from './manager-BCLhWysp.js';
 import { S as SqlDialect, N as NodeType, A as AnyEdgeType, T as TemporalMode, E as EdgeType, d as EdgeRegistration, b as EdgeId, g as NodeId, i as NodeRegistration } from './types-DMzKq0d5.js';
+import { z } from 'zod';
 import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c 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-COMyNeMn.js';
 import { SQL } from 'drizzle-orm';
-import { z } from 'zod';
 
 /**
  * Embedding type for vector search.
@@ -244,6 +244,24 @@ declare function notInSubquery(field: FieldRef, subquery: QueryAst): Predicate;
  * and ExecutableQuery classes.
  */
 
+/**
+ * A query that can be executed within a `store.batch()` call.
+ *
+ * Both `ExecutableQuery` and `UnionableQuery` satisfy this interface.
+ * The result type `R` is preserved per-query in the batch return tuple.
+ */
+type BatchableQuery<R = unknown> = Readonly<{
+    executeOn: (backend: GraphBackend | TransactionBackend) => Promise<readonly R[]>;
+}>;
+/**
+ * Maps a tuple of BatchableQuery types to their result types.
+ *
+ * Given `[BatchableQuery<A>, BatchableQuery<B>]`, produces
+ * `[readonly A[], readonly B[]]`.
+ */
+type BatchResults<Queries extends readonly BatchableQuery<unknown>[]> = {
+    -readonly [K in keyof Queries]: Queries[K] extends BatchableQuery<infer R> ? readonly R[] : never;
+};
 /**
  * Extracts the names of valid target node kinds for an edge traversal.
  *
@@ -1073,6 +1091,25 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
     findFrom: (from: NodeRef<From>) => Promise<Edge<E, From, To>[]>;
     /** Find edges to a specific node */
     findTo: (to: NodeRef<To>) => Promise<Edge<E, From, To>[]>;
+    /**
+     * Deferred variant of `findFrom` for use with `store.batch()`.
+     *
+     * Returns a `BatchableQuery` instead of executing immediately.
+     */
+    batchFindFrom: (from: NodeRef<From>) => BatchableQuery<Edge<E, From, To>>;
+    /**
+     * Deferred variant of `findTo` for use with `store.batch()`.
+     *
+     * Returns a `BatchableQuery` instead of executing immediately.
+     */
+    batchFindTo: (to: NodeRef<To>) => BatchableQuery<Edge<E, From, To>>;
+    /**
+     * Deferred variant of `findByEndpoints` for use with `store.batch()`.
+     *
+     * Returns a `BatchableQuery` that yields a 0-or-1 element array
+     * (matching `findByEndpoints`' at-most-one semantics).
+     */
+    batchFindByEndpoints: (from: NodeRef<From>, to: NodeRef<To>, options?: EdgeFindByEndpointsOptions<E>) => BatchableQuery<Edge<E, From, To>>;
     /** Delete an edge (soft delete - sets deletedAt timestamp) */
     delete: (id: EdgeId<E>) => Promise<void>;
     /**
@@ -1264,7 +1301,68 @@ type SubsetNode<G extends GraphDef, K extends NodeKinds<G>> = {
 type SubsetEdge<G extends GraphDef, K extends EdgeKinds<G>> = {
     [Kind in K]: Edge<G["edges"][Kind]["type"]>;
 }[K];
-type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends NodeKinds<G>> = Readonly<{
+type EmptyShape = Readonly<Record<never, never>>;
+type NodeProjectionPropertyKey<N extends NodeType> = Exclude<keyof Node<N>, "id" | "kind" | "meta"> & string;
+type EdgeProjectionPropertyKey<E extends AnyEdgeType> = Exclude<keyof Edge<E>, "id" | "kind" | "fromKind" | "fromId" | "toKind" | "toId" | "meta"> & string;
+type SubgraphNodeProjectionField<N extends NodeType = NodeType> = NodeProjectionPropertyKey<N> | "meta";
+type SubgraphEdgeProjectionField<E extends AnyEdgeType = AnyEdgeType> = EdgeProjectionPropertyKey<E> | "meta";
+type SubgraphNodeProjectionMap<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>> = Readonly<{
+    [K in NodeKinds<G>]?: K extends NK ? readonly SubgraphNodeProjectionField<G["nodes"][K]["type"]>[] : never;
+}>;
+type SubgraphEdgeProjectionMap<G extends GraphDef, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
+    [K in EdgeKinds<G>]?: K extends EK ? readonly SubgraphEdgeProjectionField<G["edges"][K]["type"]>[] : never;
+}>;
+type SubgraphProject<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
+    /**
+     * Node fields to keep per kind.
+     *
+     * Projected nodes always retain `kind` and `id`.
+     * Use `"meta"` to include the full metadata object; omit it to exclude metadata entirely.
+     * Only kinds present in `includeKinds` (or all node kinds when omitted) are valid keys.
+     */
+    nodes?: SubgraphNodeProjectionMap<G, NK>;
+    /**
+     * Edge fields to keep per kind.
+     *
+     * Projected edges always retain `id`, `kind`, `fromKind`, `fromId`,
+     * `toKind`, and `toId`.
+     * Use `"meta"` to include the full metadata object; omit it to exclude metadata entirely.
+     * Only edge kinds listed in `edges` are valid keys.
+     */
+    edges?: SubgraphEdgeProjectionMap<G, EK>;
+}>;
+/**
+ * Identity function that preserves literal types for reusable projection configs.
+ *
+ * Without this helper, storing a projection in a typed variable widens the
+ * field arrays to `string[]`, defeating compile-time narrowing on results.
+ *
+ * @example
+ * ```ts
+ * const project = defineSubgraphProject(graph)({
+ *   nodes: { Task: ["title", "meta"] },
+ *   edges: { uses_skill: [] },
+ * });
+ * const result = await store.subgraph(rootId, { edges: ["uses_skill"], project });
+ * // result.nodes narrowed correctly — task.status is a type error
+ * ```
+ */
+declare function defineSubgraphProject<G extends GraphDef>(_graph: G): <const P extends SubgraphProject<G>>(project: P) => P;
+type HasMeta<Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? "meta" extends Selection[number] ? true : false : false;
+type SelectedNodeProps<N extends NodeType, Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? Pick<Node<N>, Extract<Selection[number], NodeProjectionPropertyKey<N>>> : EmptyShape;
+type SelectedEdgeProps<E extends AnyEdgeType, Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? Pick<Edge<E>, Extract<Selection[number], EdgeProjectionPropertyKey<E>>> : EmptyShape;
+type ProjectedNodeResult<N extends NodeType, Selection extends readonly string[] | undefined> = Readonly<Pick<Node<N>, "id" | "kind">> & Readonly<SelectedNodeProps<N, Selection>> & (HasMeta<Selection> extends true ? Readonly<{
+    meta: NodeMeta;
+}> : EmptyShape);
+type ProjectedEdgeResult<E extends AnyEdgeType, Selection extends readonly string[] | undefined> = Readonly<Pick<Edge<E>, "id" | "kind" | "fromKind" | "fromId" | "toKind" | "toId">> & Readonly<SelectedEdgeProps<E, Selection>> & (HasMeta<Selection> extends true ? Readonly<{
+    meta: EdgeMeta;
+}> : EmptyShape);
+type ProjectionSelection<P, Key extends "nodes" | "edges", Kind extends string> = P extends Readonly<{
+    [K in Key]?: infer Map;
+}> ? Map extends Readonly<Record<string, readonly string[] | undefined>> ? Kind extends keyof Map ? Map[Kind] : undefined : undefined : undefined;
+type SubgraphNodeResultForKind<G extends GraphDef, Kind extends NodeKinds<G>, P> = ProjectionSelection<P, "nodes", Kind> extends readonly string[] ? ProjectedNodeResult<G["nodes"][Kind]["type"], ProjectionSelection<P, "nodes", Kind>> : Node<G["nodes"][Kind]["type"]>;
+type SubgraphEdgeResultForKind<G extends GraphDef, Kind extends EdgeKinds<G>, P> = ProjectionSelection<P, "edges", Kind> extends readonly string[] ? ProjectedEdgeResult<G["edges"][Kind]["type"], ProjectionSelection<P, "edges", Kind>> : Edge<G["edges"][Kind]["type"]>;
+type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends NodeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Readonly<{
     /** Edge kinds to follow during traversal. Edges not listed are not traversed. */
     edges: readonly EK[];
     /** Maximum traversal depth from root (default: 10). */
@@ -1285,10 +1383,25 @@ type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends Nod
     direction?: "out" | "both";
     /** Cycle policy — reuse RecursiveCyclePolicy (default: "prevent"). */
     cyclePolicy?: RecursiveCyclePolicy;
+    /**
+     * Optional field-level projection per node/edge kind.
+     *
+     * Projected nodes keep `kind` and `id`; projected edges keep their structural
+     * endpoint fields. Kinds omitted from `project` remain fully hydrated.
+     * Projection applies to every returned entity, including the root node.
+     *
+     * Only kinds present in `includeKinds` (nodes) or `edges` (edges) are valid
+     * projection keys. Specifying a kind outside those sets is a compile-time error.
+     */
+    project?: P;
 }>;
-type SubgraphResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
-    nodes: readonly SubsetNode<G, NK>[];
-    edges: readonly SubsetEdge<G, EK>[];
+type SubgraphResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Readonly<{
+    nodes: readonly {
+        [Kind in NK]: SubgraphNodeResultForKind<G, Kind, P>;
+    }[NK][];
+    edges: readonly {
+        [Kind in EK]: SubgraphEdgeResultForKind<G, Kind, P>;
+    }[EK][];
 }>;
 
 /**
@@ -1461,6 +1574,12 @@ declare class UnionableQuery<G extends GraphDef, R> {
      * Executes the combined query.
      */
     execute(): Promise<readonly R[]>;
+    /**
+     * Executes the combined query against a provided backend.
+     *
+     * Used by `store.batch()` to run multiple queries over a single connection.
+     */
+    executeOn(backend: GraphBackend | TransactionBackend): Promise<readonly R[]>;
 }
 
 /**
@@ -1578,6 +1697,14 @@ declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, Edge
      * @throws Error if no backend is configured
      */
     execute(): Promise<readonly R[]>;
+    /**
+     * Executes the query against a provided backend.
+     *
+     * Used by `store.batch()` to run multiple queries over a single connection
+     * (e.g., within a transaction). The full compile → execute → transform
+     * pipeline runs identically to `execute()`, but against the given backend.
+     */
+    executeOn(backend: GraphBackend | TransactionBackend): Promise<readonly R[]>;
     /**
      * Executes a paginated query using cursor-based keyset pagination.
      *
@@ -1935,6 +2062,40 @@ declare class Store<G extends GraphDef> {
      * ```
      */
     query(): QueryBuilder<G>;
+    /**
+     * Executes multiple queries over a single connection with snapshot consistency.
+     *
+     * Acquires one connection via an implicit transaction, executes each query
+     * sequentially on that connection, and returns a typed tuple of results.
+     * Each query preserves its own result type, projection, filtering,
+     * sorting, and pagination.
+     *
+     * Read-only — use `bulkCreate`, `bulkInsert`, etc. for write batching.
+     *
+     * @example
+     * ```typescript
+     * const [people, companies] = await store.batch(
+     *   store.query()
+     *     .from("Person", "p")
+     *     .select((ctx) => ({ id: ctx.p.id, name: ctx.p.name })),
+     *   store.query()
+     *     .from("Company", "c")
+     *     .select((ctx) => ({ id: ctx.c.id, name: ctx.c.name }))
+     *     .orderBy("c", "name", "asc")
+     *     .limit(5),
+     * );
+     * // people:    readonly { id: string; name: string }[]
+     * // companies: readonly { id: string; name: string }[]
+     * ```
+     *
+     * @param queries - Two or more executable queries (from `.select()` or set operations)
+     * @returns A tuple with per-query typed results, preserving input order
+     */
+    batch<const Queries extends readonly [
+        BatchableQuery<unknown>,
+        BatchableQuery<unknown>,
+        ...BatchableQuery<unknown>[]
+    ]>(...queries: Queries): Promise<BatchResults<Queries>>;
     /**
      * Extracts a typed subgraph by traversing from a root node.
      *
@@ -1957,7 +2118,7 @@ declare class Store<G extends GraphDef> {
      * }
      * ```
      */
-    subgraph<const EK extends EdgeKinds<G>, const NK extends NodeKinds<G> = NodeKinds<G>>(rootId: NodeId<AllNodeTypes<G>>, options: SubgraphOptions<G, EK, NK>): Promise<SubgraphResult<G, NK, EK>>;
+    subgraph<const EK extends EdgeKinds<G>, const NK extends NodeKinds<G> = NodeKinds<G>, const P extends SubgraphProject<G, NK, EK> | undefined = undefined>(rootId: NodeId<AllNodeTypes<G>>, options: SubgraphOptions<G, EK, NK, P>): Promise<SubgraphResult<G, NK, EK, P>>;
     /**
      * Executes a function within a transaction.
      *
@@ -2059,4 +2220,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 { type TypedEdgeCollection as $, type AliasMap as A, type QueryHookContext as B, type CreateQueryBuilderOptions as C, type QueryOptions as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type SelectableEdge as J, type SelectableNode as K, Store as L, type StoreHooks as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, type SelectContext as S, TraversalBuilder as T, type StoreOptions as U, type StreamOptions as V, type SubgraphOptions as W, type SubgraphResult as X, type SubsetEdge as Y, type SubsetNode as Z, type TransactionContext as _, type AggregateResult as a, UnionableQuery as a0, type UpdateEdgeInput as a1, type UpdateNodeInput as a2, createStore as a3, createStoreWithSchema as a4, embedding as a5, exists as a6, fieldRef as a7, getEmbeddingDimensions as a8, inSubquery as a9, isEmbeddingSchema as aa, isParameterRef as ab, notExists as ac, notInSubquery as ad, param as ae, type AnyEdge as b, type AnyNode as c, type ConstraintNames as d, type CreateEdgeInput as e, type CreateNodeInput as f, type Edge as g, type EdgeAccessor as h, type EdgeCollection as i, type EdgeFindByEndpointsOptions as j, type EdgeGetOrCreateByEndpointsOptions as k, type EdgeGetOrCreateByEndpointsResult as l, type EmbeddingSchema as m, type EmbeddingValue as n, ExecutableAggregateQuery as o, ExecutableQuery as p, type NodeAccessor as q, type NodeAlias as r, type NodeCollection as s, type NodeGetOrCreateByConstraintOptions as t, type NodeGetOrCreateByConstraintResult as u, type NodeRef as v, type PaginatedResult as w, type Predicate as x, PreparedQuery as y, type PropsAccessor as z };
+export { type SubsetNode as $, type AliasMap as A, type BatchResults as B, type CreateQueryBuilderOptions as C, type PropsAccessor as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type QueryHookContext as J, type QueryOptions as K, type SelectableEdge as L, type SelectableNode as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, type SelectContext as S, TraversalBuilder as T, Store as U, type StoreHooks as V, type StoreOptions as W, type StreamOptions as X, type SubgraphOptions as Y, type SubgraphResult as Z, type SubsetEdge as _, type AggregateResult as a, type TransactionContext as a0, type TypedEdgeCollection as a1, UnionableQuery as a2, type UpdateEdgeInput as a3, type UpdateNodeInput as a4, createStore as a5, createStoreWithSchema as a6, defineSubgraphProject as a7, embedding as a8, exists as a9, fieldRef as aa, getEmbeddingDimensions as ab, inSubquery as ac, isEmbeddingSchema as ad, isParameterRef as ae, notExists as af, notInSubquery as ag, param as ah, type AnyEdge as b, type AnyNode as c, type BatchableQuery as d, type ConstraintNames as e, type CreateEdgeInput as f, type CreateNodeInput as g, type Edge as h, type EdgeAccessor as i, type EdgeCollection as j, type EdgeFindByEndpointsOptions as k, type EdgeGetOrCreateByEndpointsOptions as l, type EdgeGetOrCreateByEndpointsResult as m, type EmbeddingSchema as n, type EmbeddingValue as o, ExecutableAggregateQuery as p, ExecutableQuery as q, type NodeAccessor as r, type NodeAlias as s, type NodeCollection as t, type NodeGetOrCreateByConstraintOptions as u, type NodeGetOrCreateByConstraintResult as v, type NodeRef as w, type PaginatedResult as x, type Predicate as y, PreparedQuery as z };

package/dist/{store-C01_WsOg.d.cts → store-Bmdt_dS6.d.cts}

@@ -1,9 +1,9 @@
-import { S as SqlSchema, G as GraphBackend } from './types-GLkwvQvS.cjs';
+import { S as SqlSchema, G as GraphBackend, T as TransactionBackend } from './types-GLkwvQvS.cjs';
 import { K as KindRegistry, G as GraphDef, E as EdgeKinds, N as NodeKinds, a as AllNodeTypes, S as SchemaManagerOptions, f as SchemaValidationResult } from './manager-DGSnJa1v.cjs';
 import { S as SqlDialect, N as NodeType, A as AnyEdgeType, T as TemporalMode, E as EdgeType, d as EdgeRegistration, b as EdgeId, g as NodeId, i as NodeRegistration } from './types-DMzKq0d5.cjs';
+import { z } from 'zod';
 import { V as ValueType, i as PredicateExpression, k as VectorMetricType, Q as QueryAst, J as JsonPointer, F as FieldRef, P as ParameterRef, c 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-Bh2NDeaK.cjs';
 import { SQL } from 'drizzle-orm';
-import { z } from 'zod';
 
 /**
  * Embedding type for vector search.
@@ -244,6 +244,24 @@ declare function notInSubquery(field: FieldRef, subquery: QueryAst): Predicate;
  * and ExecutableQuery classes.
  */
 
+/**
+ * A query that can be executed within a `store.batch()` call.
+ *
+ * Both `ExecutableQuery` and `UnionableQuery` satisfy this interface.
+ * The result type `R` is preserved per-query in the batch return tuple.
+ */
+type BatchableQuery<R = unknown> = Readonly<{
+    executeOn: (backend: GraphBackend | TransactionBackend) => Promise<readonly R[]>;
+}>;
+/**
+ * Maps a tuple of BatchableQuery types to their result types.
+ *
+ * Given `[BatchableQuery<A>, BatchableQuery<B>]`, produces
+ * `[readonly A[], readonly B[]]`.
+ */
+type BatchResults<Queries extends readonly BatchableQuery<unknown>[]> = {
+    -readonly [K in keyof Queries]: Queries[K] extends BatchableQuery<infer R> ? readonly R[] : never;
+};
 /**
  * Extracts the names of valid target node kinds for an edge traversal.
  *
@@ -1073,6 +1091,25 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
     findFrom: (from: NodeRef<From>) => Promise<Edge<E, From, To>[]>;
     /** Find edges to a specific node */
     findTo: (to: NodeRef<To>) => Promise<Edge<E, From, To>[]>;
+    /**
+     * Deferred variant of `findFrom` for use with `store.batch()`.
+     *
+     * Returns a `BatchableQuery` instead of executing immediately.
+     */
+    batchFindFrom: (from: NodeRef<From>) => BatchableQuery<Edge<E, From, To>>;
+    /**
+     * Deferred variant of `findTo` for use with `store.batch()`.
+     *
+     * Returns a `BatchableQuery` instead of executing immediately.
+     */
+    batchFindTo: (to: NodeRef<To>) => BatchableQuery<Edge<E, From, To>>;
+    /**
+     * Deferred variant of `findByEndpoints` for use with `store.batch()`.
+     *
+     * Returns a `BatchableQuery` that yields a 0-or-1 element array
+     * (matching `findByEndpoints`' at-most-one semantics).
+     */
+    batchFindByEndpoints: (from: NodeRef<From>, to: NodeRef<To>, options?: EdgeFindByEndpointsOptions<E>) => BatchableQuery<Edge<E, From, To>>;
     /** Delete an edge (soft delete - sets deletedAt timestamp) */
     delete: (id: EdgeId<E>) => Promise<void>;
     /**
@@ -1264,7 +1301,68 @@ type SubsetNode<G extends GraphDef, K extends NodeKinds<G>> = {
 type SubsetEdge<G extends GraphDef, K extends EdgeKinds<G>> = {
     [Kind in K]: Edge<G["edges"][Kind]["type"]>;
 }[K];
-type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends NodeKinds<G>> = Readonly<{
+type EmptyShape = Readonly<Record<never, never>>;
+type NodeProjectionPropertyKey<N extends NodeType> = Exclude<keyof Node<N>, "id" | "kind" | "meta"> & string;
+type EdgeProjectionPropertyKey<E extends AnyEdgeType> = Exclude<keyof Edge<E>, "id" | "kind" | "fromKind" | "fromId" | "toKind" | "toId" | "meta"> & string;
+type SubgraphNodeProjectionField<N extends NodeType = NodeType> = NodeProjectionPropertyKey<N> | "meta";
+type SubgraphEdgeProjectionField<E extends AnyEdgeType = AnyEdgeType> = EdgeProjectionPropertyKey<E> | "meta";
+type SubgraphNodeProjectionMap<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>> = Readonly<{
+    [K in NodeKinds<G>]?: K extends NK ? readonly SubgraphNodeProjectionField<G["nodes"][K]["type"]>[] : never;
+}>;
+type SubgraphEdgeProjectionMap<G extends GraphDef, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
+    [K in EdgeKinds<G>]?: K extends EK ? readonly SubgraphEdgeProjectionField<G["edges"][K]["type"]>[] : never;
+}>;
+type SubgraphProject<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
+    /**
+     * Node fields to keep per kind.
+     *
+     * Projected nodes always retain `kind` and `id`.
+     * Use `"meta"` to include the full metadata object; omit it to exclude metadata entirely.
+     * Only kinds present in `includeKinds` (or all node kinds when omitted) are valid keys.
+     */
+    nodes?: SubgraphNodeProjectionMap<G, NK>;
+    /**
+     * Edge fields to keep per kind.
+     *
+     * Projected edges always retain `id`, `kind`, `fromKind`, `fromId`,
+     * `toKind`, and `toId`.
+     * Use `"meta"` to include the full metadata object; omit it to exclude metadata entirely.
+     * Only edge kinds listed in `edges` are valid keys.
+     */
+    edges?: SubgraphEdgeProjectionMap<G, EK>;
+}>;
+/**
+ * Identity function that preserves literal types for reusable projection configs.
+ *
+ * Without this helper, storing a projection in a typed variable widens the
+ * field arrays to `string[]`, defeating compile-time narrowing on results.
+ *
+ * @example
+ * ```ts
+ * const project = defineSubgraphProject(graph)({
+ *   nodes: { Task: ["title", "meta"] },
+ *   edges: { uses_skill: [] },
+ * });
+ * const result = await store.subgraph(rootId, { edges: ["uses_skill"], project });
+ * // result.nodes narrowed correctly — task.status is a type error
+ * ```
+ */
+declare function defineSubgraphProject<G extends GraphDef>(_graph: G): <const P extends SubgraphProject<G>>(project: P) => P;
+type HasMeta<Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? "meta" extends Selection[number] ? true : false : false;
+type SelectedNodeProps<N extends NodeType, Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? Pick<Node<N>, Extract<Selection[number], NodeProjectionPropertyKey<N>>> : EmptyShape;
+type SelectedEdgeProps<E extends AnyEdgeType, Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? Pick<Edge<E>, Extract<Selection[number], EdgeProjectionPropertyKey<E>>> : EmptyShape;
+type ProjectedNodeResult<N extends NodeType, Selection extends readonly string[] | undefined> = Readonly<Pick<Node<N>, "id" | "kind">> & Readonly<SelectedNodeProps<N, Selection>> & (HasMeta<Selection> extends true ? Readonly<{
+    meta: NodeMeta;
+}> : EmptyShape);
+type ProjectedEdgeResult<E extends AnyEdgeType, Selection extends readonly string[] | undefined> = Readonly<Pick<Edge<E>, "id" | "kind" | "fromKind" | "fromId" | "toKind" | "toId">> & Readonly<SelectedEdgeProps<E, Selection>> & (HasMeta<Selection> extends true ? Readonly<{
+    meta: EdgeMeta;
+}> : EmptyShape);
+type ProjectionSelection<P, Key extends "nodes" | "edges", Kind extends string> = P extends Readonly<{
+    [K in Key]?: infer Map;
+}> ? Map extends Readonly<Record<string, readonly string[] | undefined>> ? Kind extends keyof Map ? Map[Kind] : undefined : undefined : undefined;
+type SubgraphNodeResultForKind<G extends GraphDef, Kind extends NodeKinds<G>, P> = ProjectionSelection<P, "nodes", Kind> extends readonly string[] ? ProjectedNodeResult<G["nodes"][Kind]["type"], ProjectionSelection<P, "nodes", Kind>> : Node<G["nodes"][Kind]["type"]>;
+type SubgraphEdgeResultForKind<G extends GraphDef, Kind extends EdgeKinds<G>, P> = ProjectionSelection<P, "edges", Kind> extends readonly string[] ? ProjectedEdgeResult<G["edges"][Kind]["type"], ProjectionSelection<P, "edges", Kind>> : Edge<G["edges"][Kind]["type"]>;
+type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends NodeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Readonly<{
     /** Edge kinds to follow during traversal. Edges not listed are not traversed. */
     edges: readonly EK[];
     /** Maximum traversal depth from root (default: 10). */
@@ -1285,10 +1383,25 @@ type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends Nod
     direction?: "out" | "both";
     /** Cycle policy — reuse RecursiveCyclePolicy (default: "prevent"). */
     cyclePolicy?: RecursiveCyclePolicy;
+    /**
+     * Optional field-level projection per node/edge kind.
+     *
+     * Projected nodes keep `kind` and `id`; projected edges keep their structural
+     * endpoint fields. Kinds omitted from `project` remain fully hydrated.
+     * Projection applies to every returned entity, including the root node.
+     *
+     * Only kinds present in `includeKinds` (nodes) or `edges` (edges) are valid
+     * projection keys. Specifying a kind outside those sets is a compile-time error.
+     */
+    project?: P;
 }>;
-type SubgraphResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
-    nodes: readonly SubsetNode<G, NK>[];
-    edges: readonly SubsetEdge<G, EK>[];
+type SubgraphResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Readonly<{
+    nodes: readonly {
+        [Kind in NK]: SubgraphNodeResultForKind<G, Kind, P>;
+    }[NK][];
+    edges: readonly {
+        [Kind in EK]: SubgraphEdgeResultForKind<G, Kind, P>;
+    }[EK][];
 }>;
 
 /**
@@ -1461,6 +1574,12 @@ declare class UnionableQuery<G extends GraphDef, R> {
      * Executes the combined query.
      */
     execute(): Promise<readonly R[]>;
+    /**
+     * Executes the combined query against a provided backend.
+     *
+     * Used by `store.batch()` to run multiple queries over a single connection.
+     */
+    executeOn(backend: GraphBackend | TransactionBackend): Promise<readonly R[]>;
 }
 
 /**
@@ -1578,6 +1697,14 @@ declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, Edge
      * @throws Error if no backend is configured
      */
     execute(): Promise<readonly R[]>;
+    /**
+     * Executes the query against a provided backend.
+     *
+     * Used by `store.batch()` to run multiple queries over a single connection
+     * (e.g., within a transaction). The full compile → execute → transform
+     * pipeline runs identically to `execute()`, but against the given backend.
+     */
+    executeOn(backend: GraphBackend | TransactionBackend): Promise<readonly R[]>;
     /**
      * Executes a paginated query using cursor-based keyset pagination.
      *
@@ -1935,6 +2062,40 @@ declare class Store<G extends GraphDef> {
      * ```
      */
     query(): QueryBuilder<G>;
+    /**
+     * Executes multiple queries over a single connection with snapshot consistency.
+     *
+     * Acquires one connection via an implicit transaction, executes each query
+     * sequentially on that connection, and returns a typed tuple of results.
+     * Each query preserves its own result type, projection, filtering,
+     * sorting, and pagination.
+     *
+     * Read-only — use `bulkCreate`, `bulkInsert`, etc. for write batching.
+     *
+     * @example
+     * ```typescript
+     * const [people, companies] = await store.batch(
+     *   store.query()
+     *     .from("Person", "p")
+     *     .select((ctx) => ({ id: ctx.p.id, name: ctx.p.name })),
+     *   store.query()
+     *     .from("Company", "c")
+     *     .select((ctx) => ({ id: ctx.c.id, name: ctx.c.name }))
+     *     .orderBy("c", "name", "asc")
+     *     .limit(5),
+     * );
+     * // people:    readonly { id: string; name: string }[]
+     * // companies: readonly { id: string; name: string }[]
+     * ```
+     *
+     * @param queries - Two or more executable queries (from `.select()` or set operations)
+     * @returns A tuple with per-query typed results, preserving input order
+     */
+    batch<const Queries extends readonly [
+        BatchableQuery<unknown>,
+        BatchableQuery<unknown>,
+        ...BatchableQuery<unknown>[]
+    ]>(...queries: Queries): Promise<BatchResults<Queries>>;
     /**
      * Extracts a typed subgraph by traversing from a root node.
      *
@@ -1957,7 +2118,7 @@ declare class Store<G extends GraphDef> {
      * }
      * ```
      */
-    subgraph<const EK extends EdgeKinds<G>, const NK extends NodeKinds<G> = NodeKinds<G>>(rootId: NodeId<AllNodeTypes<G>>, options: SubgraphOptions<G, EK, NK>): Promise<SubgraphResult<G, NK, EK>>;
+    subgraph<const EK extends EdgeKinds<G>, const NK extends NodeKinds<G> = NodeKinds<G>, const P extends SubgraphProject<G, NK, EK> | undefined = undefined>(rootId: NodeId<AllNodeTypes<G>>, options: SubgraphOptions<G, EK, NK, P>): Promise<SubgraphResult<G, NK, EK, P>>;
     /**
      * Executes a function within a transaction.
      *
@@ -2059,4 +2220,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 { type TypedEdgeCollection as $, type AliasMap as A, type QueryHookContext as B, type CreateQueryBuilderOptions as C, type QueryOptions as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type SelectableEdge as J, type SelectableNode as K, Store as L, type StoreHooks as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, type SelectContext as S, TraversalBuilder as T, type StoreOptions as U, type StreamOptions as V, type SubgraphOptions as W, type SubgraphResult as X, type SubsetEdge as Y, type SubsetNode as Z, type TransactionContext as _, type AggregateResult as a, UnionableQuery as a0, type UpdateEdgeInput as a1, type UpdateNodeInput as a2, createStore as a3, createStoreWithSchema as a4, embedding as a5, exists as a6, fieldRef as a7, getEmbeddingDimensions as a8, inSubquery as a9, isEmbeddingSchema as aa, isParameterRef as ab, notExists as ac, notInSubquery as ad, param as ae, type AnyEdge as b, type AnyNode as c, type ConstraintNames as d, type CreateEdgeInput as e, type CreateNodeInput as f, type Edge as g, type EdgeAccessor as h, type EdgeCollection as i, type EdgeFindByEndpointsOptions as j, type EdgeGetOrCreateByEndpointsOptions as k, type EdgeGetOrCreateByEndpointsResult as l, type EmbeddingSchema as m, type EmbeddingValue as n, ExecutableAggregateQuery as o, ExecutableQuery as p, type NodeAccessor as q, type NodeAlias as r, type NodeCollection as s, type NodeGetOrCreateByConstraintOptions as t, type NodeGetOrCreateByConstraintResult as u, type NodeRef as v, type PaginatedResult as w, type Predicate as x, PreparedQuery as y, type PropsAccessor as z };
+export { type SubsetNode as $, type AliasMap as A, type BatchResults as B, type CreateQueryBuilderOptions as C, type PropsAccessor as D, type EdgeAliasMap as E, type FieldAccessor as F, type GetOrCreateAction as G, type HookContext as H, type IfExistsMode as I, type QueryHookContext as J, type QueryOptions as K, type SelectableEdge as L, type SelectableNode as M, type Node as N, type OperationHookContext as O, type PaginateOptions as P, QueryBuilder as Q, type RecursiveTraversalOptions as R, type SelectContext as S, TraversalBuilder as T, Store as U, type StoreHooks as V, type StoreOptions as W, type StreamOptions as X, type SubgraphOptions as Y, type SubgraphResult as Z, type SubsetEdge as _, type AggregateResult as a, type TransactionContext as a0, type TypedEdgeCollection as a1, UnionableQuery as a2, type UpdateEdgeInput as a3, type UpdateNodeInput as a4, createStore as a5, createStoreWithSchema as a6, defineSubgraphProject as a7, embedding as a8, exists as a9, fieldRef as aa, getEmbeddingDimensions as ab, inSubquery as ac, isEmbeddingSchema as ad, isParameterRef as ae, notExists as af, notInSubquery as ag, param as ah, type AnyEdge as b, type AnyNode as c, type BatchableQuery as d, type ConstraintNames as e, type CreateEdgeInput as f, type CreateNodeInput as g, type Edge as h, type EdgeAccessor as i, type EdgeCollection as j, type EdgeFindByEndpointsOptions as k, type EdgeGetOrCreateByEndpointsOptions as l, type EdgeGetOrCreateByEndpointsResult as m, type EmbeddingSchema as n, type EmbeddingValue as o, ExecutableAggregateQuery as p, ExecutableQuery as q, type NodeAccessor as r, type NodeAlias as s, type NodeCollection as t, type NodeGetOrCreateByConstraintOptions as u, type NodeGetOrCreateByConstraintResult as v, type NodeRef as w, type PaginatedResult as x, type Predicate as y, PreparedQuery as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicia-ai/typegraph",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "TypeScript-first embedded knowledge graph library with ontological reasoning",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -122,8 +122,8 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "better-sqlite3": ">=9.0.0",
-    "drizzle-orm": ">=0.35.0",
+    "better-sqlite3": ">=9.0.0 <13.0.0",
+    "drizzle-orm": ">=0.35.0 <1.0.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -132,25 +132,25 @@
     }
   },
   "dependencies": {
-    "nanoid": "^5.1.6"
+    "nanoid": "^5.1.7"
   },
   "devDependencies": {
     "@stryker-mutator/core": "^9.6.0",
     "@stryker-mutator/vitest-runner": "^9.6.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^24.12.0",
-    "@types/pg": "^8.18.0",
-    "@vitest/coverage-v8": "^4.0.18",
-    "better-sqlite3": "^12.6.2",
+    "@types/pg": "^8.20.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "better-sqlite3": "^12.8.0",
     "drizzle-orm": "^0.45.1",
-    "eslint": "^9.39.4",
+    "eslint": "^10.1.0",
     "fast-check": "^4.6.0",
     "pg": "^8.20.0",
-    "sqlite-vec": "0.1.7-alpha.2",
+    "sqlite-vec": "^0.1.7",
     "tsd": "^0.33.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.2",
     "zod": "^4.3.6",
     "@typegraph/eslint-config": "0.1.0"
   },