@nicia-ai/typegraph 0.21.0 → 0.23.0

package/dist/index.js

@@ -1,11 +1,13 @@
+import { quoteIdentifier, EMPTY_REQUIRED_COLUMNS, addRequiredColumn, markSelectiveFieldAsRequired, markFieldRefAsRequired, NODE_COLUMNS, shouldProjectColumn, mapSelectiveSystemFieldToColumn, isIdFieldRef, isAggregateExpr, EDGE_COLUMNS } from './chunk-3EUKJEQ3.js';
 import { META_EDGE_BRAND, META_EDGE_SUB_CLASS_OF, META_EDGE_NARROWER, META_EDGE_BROADER, META_EDGE_RELATED_TO, META_EDGE_EQUIVALENT_TO, META_EDGE_SAME_AS, META_EDGE_DIFFERENT_FROM, META_EDGE_DISJOINT_WITH, META_EDGE_HAS_PART, META_EDGE_PART_OF, META_EDGE_INVERSE_OF, META_EDGE_IMPLIES, ensureSchema, computeClosuresFromOntology, createEmptyClosures, KindRegistry, validateNodeProps, validateEdgeProps } from './chunk-JYUQA77I.js';
 export { isMetaEdge } from './chunk-JYUQA77I.js';
 import { NODE_TYPE_BRAND, EDGE_TYPE_BRAND, nowIso, validateOptionalIsoDate, getNodeKinds, getEdgeKinds } from './chunk-RS5OLGEW.js';
 export { defineGraph, getEdgeKinds, getNodeKinds, isEdgeType, isEdgeTypeWithEndpoints, isGraphDef, isNodeType } from './chunk-RS5OLGEW.js';
+import { runOptionallyInTransaction } from './chunk-7TU5EWQ7.js';
 import { ConfigurationError, UnsupportedPredicateError, ValidationError, CompilerInvariantError, KindNotFoundError, DatabaseOperationError, EdgeNotFoundError, NodeConstraintNotFoundError, RestrictedDeleteError, NodeNotFoundError, EndpointNotFoundError, UniquenessError, CardinalityError, EndpointError, DisjointError } from './chunk-WFMTAEEN.js';
 export { BackendDisposedError, CardinalityError, CompilerInvariantError, ConfigurationError, DatabaseOperationError, DisjointError, EdgeNotFoundError, EndpointError, EndpointNotFoundError, KindNotFoundError, MigrationError, NodeConstraintNotFoundError, NodeNotFoundError, RestrictedDeleteError, SchemaMismatchError, TypeGraphError, UniquenessError, UnsupportedPredicateError, ValidationError, VersionConflictError, getErrorSuggestion, isConstraintError, isSystemError, isTypeGraphError, isUserRecoverable } from './chunk-WFMTAEEN.js';
-import { MAX_PG_IDENTIFIER_LENGTH, DEFAULT_PAGINATION_LIMIT, getDialect, DEFAULT_STREAM_BATCH_SIZE, NODE_META_KEYS, EDGE_META_KEYS, SQLITE_PATH_DELIMITER, PG_ARRAY_START, PG_ARRAY_END, PG_PATH_ELEMENT_SEPARATOR, fnv1aBase36 } from './chunk-4XNE2JG3.js';
-export { fts5Strategy, tsvectorStrategy } from './chunk-4XNE2JG3.js';
+import { MAX_PG_IDENTIFIER_LENGTH, DEFAULT_PAGINATION_LIMIT, getDialect, DEFAULT_STREAM_BATCH_SIZE, NODE_META_KEYS, EDGE_META_KEYS, SQLITE_PATH_DELIMITER, PG_ARRAY_START, PG_ARRAY_END, PG_PATH_ELEMENT_SEPARATOR, fnv1aBase36 } from './chunk-753F33CV.js';
+export { fts5Strategy, tsvectorStrategy } from './chunk-753F33CV.js';
 import { jsonPointer, parseJsonPointer, createSchemaIntrospector, normalizeJsonPointer, joinJsonPointers, resolveFieldTypeInfoAtJsonPointer, getSearchableMetadata, DEFAULT_SEARCHABLE_LANGUAGE, getEmbeddingDimensions, isEmbeddingSchema } from './chunk-EYELZHKY.js';
 export { DEFAULT_SEARCHABLE_LANGUAGE, MAX_JSON_POINTER_DEPTH, embedding, getEmbeddingDimensions, getSearchableMetadata, isEmbeddingSchema, isSearchableSchema, joinJsonPointers, jsonPointer, normalizeJsonPointer, parseJsonPointer, searchable } from './chunk-EYELZHKY.js';
 import { z } from 'zod';
@@ -1944,7 +1946,7 @@ function validateTableName(name, label) {
     );
   }
 }
-function quoteIdentifier(name) {
+function quoteIdentifier2(name) {
   return `"${name.replaceAll('"', '""')}"`;
 }
 function createSqlSchema(names = {}) {
@@ -1955,10 +1957,10 @@ function createSqlSchema(names = {}) {
   validateTableName(tables.fulltext, "fulltext");
   return {
     tables,
-    nodesTable: sql.raw(quoteIdentifier(tables.nodes)),
-    edgesTable: sql.raw(quoteIdentifier(tables.edges)),
-    embeddingsTable: sql.raw(quoteIdentifier(tables.embeddings)),
-    fulltextTable: sql.raw(quoteIdentifier(tables.fulltext))
+    nodesTable: sql.raw(quoteIdentifier2(tables.nodes)),
+    edgesTable: sql.raw(quoteIdentifier2(tables.edges)),
+    embeddingsTable: sql.raw(quoteIdentifier2(tables.embeddings)),
+    fulltextTable: sql.raw(quoteIdentifier2(tables.fulltext))
   };
 }
 var DEFAULT_SQL_SCHEMA = createSqlSchema();
@@ -1996,76 +1998,6 @@ function compileTypedJsonExtract(input) {
     }
   }
 }
-var NODE_COLUMNS = [
-  "id",
-  "kind",
-  "props",
-  "version",
-  "valid_from",
-  "valid_to",
-  "created_at",
-  "updated_at",
-  "deleted_at"
-];
-var EDGE_COLUMNS = [
-  "id",
-  "kind",
-  "from_id",
-  "to_id",
-  "props",
-  "valid_from",
-  "valid_to",
-  "created_at",
-  "updated_at",
-  "deleted_at"
-];
-var EMPTY_REQUIRED_COLUMNS = /* @__PURE__ */ new Set();
-function quoteIdentifier2(identifier) {
-  return sql.raw(`"${identifier.replaceAll('"', '""')}"`);
-}
-function shouldProjectColumn(requiredColumns, column, alwaysRequiredColumns) {
-  if (alwaysRequiredColumns?.has(column)) return true;
-  if (requiredColumns === void 0) return true;
-  return requiredColumns.has(column);
-}
-function addRequiredColumn(requiredColumnsByAlias, alias, column) {
-  const existing = requiredColumnsByAlias.get(alias);
-  if (existing) {
-    existing.add(column);
-    return;
-  }
-  requiredColumnsByAlias.set(alias, /* @__PURE__ */ new Set([column]));
-}
-function markFieldRefAsRequired(requiredColumnsByAlias, field2) {
-  const column = field2.path[0];
-  if (column === void 0) return;
-  addRequiredColumn(requiredColumnsByAlias, field2.alias, column);
-}
-function mapSelectiveSystemFieldToColumn(field2) {
-  if (field2 === "fromId") return "from_id";
-  if (field2 === "toId") return "to_id";
-  if (field2.startsWith("meta.")) {
-    return field2.slice(5).replaceAll(/([A-Z])/g, "_$1").toLowerCase();
-  }
-  return field2;
-}
-function markSelectiveFieldAsRequired(requiredColumnsByAlias, field2) {
-  if (field2.isSystemField) {
-    addRequiredColumn(
-      requiredColumnsByAlias,
-      field2.alias,
-      mapSelectiveSystemFieldToColumn(field2.field)
-    );
-    return;
-  }
-  addRequiredColumn(requiredColumnsByAlias, field2.alias, "props");
-}
-function isIdFieldRef(field2) {
-  return field2.path.length === 1 && field2.path[0] === "id" && field2.jsonPointer === void 0;
-}
-function isAggregateExpr(source) {
-  return "__type" in source && source.__type === "aggregate";
-}
 
 // src/query/compiler/emitter/standard-builders.ts
 function compileColumnReference(tableAlias, column) {
@@ -2075,7 +2007,7 @@ function compileColumnReference(tableAlias, column) {
   return sql`${sql.raw(tableAlias)}.${sql.raw(column)}`;
 }
 function qualifyColumn(owner, name) {
-  return sql`${quoteIdentifier2(owner)}.${quoteIdentifier2(name)}`;
+  return sql`${quoteIdentifier(owner)}.${quoteIdentifier(name)}`;
 }
 var SCOPED_RELEVANCE_NODES_ALIAS = "scoped_relevance_nodes";
 function buildScopedNodeIdsSubquery(nodeAlias) {
@@ -2085,7 +2017,7 @@ function buildScopedNodeIdsSubquery(nodeAlias) {
         SELECT DISTINCT
           ${qualifyColumn(cteAlias, `${nodeAlias}_id`)} AS node_id,
           ${qualifyColumn(cteAlias, `${nodeAlias}_kind`)} AS node_kind
-        FROM ${quoteIdentifier2(cteAlias)}
+        FROM ${quoteIdentifier(cteAlias)}
       ) AS ${sql.raw(SCOPED_RELEVANCE_NODES_ALIAS)}
   `;
 }
@@ -2107,6 +2039,7 @@ function buildStandardStartCte(input) {
   const { ast, ctx, graphId, predicateIndex, requiredColumnsByAlias } = input;
   const alias = ast.start.alias;
   const kinds = ast.start.kinds;
+  const cteMaterialization = ctx.dialect.capabilities.emitNotMaterializedHint ? sql`NOT MATERIALIZED ` : sql``;
   const kindFilter = compileKindFilter(sql.raw("kind"), kinds);
   const temporalFilter = input.temporalFilterPass.forAlias();
   const cteContext = { ...ctx, cteColumnPrefix: "" };
@@ -2121,14 +2054,19 @@ function buildStandardStartCte(input) {
     ...predicateClauses
   ];
   const effectiveRequiredColumns = requiredColumnsByAlias ? requiredColumnsByAlias.get(alias) ?? EMPTY_REQUIRED_COLUMNS : void 0;
+  const limitClause = input.limitOffset === void 0 ? sql`` : input.limitOffset.offset === void 0 ? sql`
+        LIMIT ${input.limitOffset.limit}
+      ` : sql`
+      LIMIT ${input.limitOffset.limit} OFFSET ${input.limitOffset.offset}
+    `;
   return sql`
-    cte_${sql.raw(alias)} AS (
+    cte_${sql.raw(alias)} AS ${cteMaterialization}(
       SELECT ${sql.join(
     compileNodeSelectColumns(void 0, alias, effectiveRequiredColumns),
     sql`, `
   )}
       FROM ${ctx.schema.nodesTable}
-      WHERE ${sql.join(whereClauses, sql` AND `)}
+      WHERE ${sql.join(whereClauses, sql` AND `)}${limitClause}
     )
   `;
 }
@@ -2192,7 +2130,7 @@ function buildStandardTraversalCte(input) {
     ...compileEdgeSelectColumns("e", edgeAlias, requiredEdgeColumns),
     ...compileNodeSelectColumns("n", nodeAlias, requiredNodeColumns)
   ];
-  const cteMaterialization = materializeCte ? sql`MATERIALIZED ` : sql``;
+  const cteMaterialization = materializeCte ? sql`MATERIALIZED ` : ctx.dialect.capabilities.emitNotMaterializedHint ? sql`NOT MATERIALIZED ` : sql``;
   function compileTraversalBranch(branch) {
     const whereClauses = [
       ...baseWhereClauses,
@@ -2341,7 +2279,7 @@ function buildStandardProjection(input) {
   }
   const projectedFields = fields.map((field2) => {
     const source = compileProjectedSource(field2, dialect);
-    return sql`${source} AS ${quoteIdentifier2(field2.outputName)}`;
+    return sql`${source} AS ${quoteIdentifier(field2.outputName)}`;
   });
   return sql.join(projectedFields, sql`, `);
 }
@@ -2361,7 +2299,7 @@ function compileSelectiveProjection(fields, dialect, ast, collapsedTraversalCteA
     const cteAlias = collapsedTraversalCteAlias ?? aliasToCte.get(field2.alias) ?? `cte_${field2.alias}`;
     if (field2.isSystemField) {
       const dbColumn = mapSelectiveSystemFieldToColumn(field2.field);
-      return sql`${sql.raw(cteAlias)}.${sql.raw(`${field2.alias}_${dbColumn}`)} AS ${quoteIdentifier2(field2.outputName)}`;
+      return sql`${sql.raw(cteAlias)}.${sql.raw(`${field2.alias}_${dbColumn}`)} AS ${quoteIdentifier(field2.outputName)}`;
     }
     const propsColumn = `${field2.alias}_props`;
     const column = sql`${sql.raw(cteAlias)}.${sql.raw(propsColumn)}`;
@@ -2372,7 +2310,7 @@ function compileSelectiveProjection(fields, dialect, ast, collapsedTraversalCteA
       pointer,
       valueType: field2.valueType
     });
-    return sql`${extracted} AS ${quoteIdentifier2(field2.outputName)}`;
+    return sql`${extracted} AS ${quoteIdentifier(field2.outputName)}`;
   });
   return sql.join(columns, sql`, `);
 }
@@ -3703,10 +3641,10 @@ function compileRecursiveProjection(ast, traversal, dialect) {
     sql`${sql.raw(nodeAlias)}_deleted_at`
   ];
   if (vl.depthAlias !== void 0) {
-    fields.push(sql`depth AS ${quoteIdentifier2(vl.depthAlias)}`);
+    fields.push(sql`depth AS ${quoteIdentifier(vl.depthAlias)}`);
   }
   if (vl.pathAlias !== void 0) {
-    fields.push(sql`path AS ${quoteIdentifier2(vl.pathAlias)}`);
+    fields.push(sql`path AS ${quoteIdentifier(vl.pathAlias)}`);
   }
   return sql.join(fields, sql`, `);
 }
@@ -3720,7 +3658,7 @@ function compileRecursiveSelectiveProjection(fields, ast, traversal, dialect) {
     }
     if (field2.isSystemField) {
       const dbColumn = mapSelectiveSystemFieldToColumn(field2.field);
-      return sql`${sql.raw(`${field2.alias}_${dbColumn}`)} AS ${quoteIdentifier2(field2.outputName)}`;
+      return sql`${sql.raw(`${field2.alias}_${dbColumn}`)} AS ${quoteIdentifier(field2.outputName)}`;
     }
     const column = sql.raw(`${field2.alias}_props`);
     const extracted = compileTypedJsonExtract({
@@ -3729,14 +3667,14 @@ function compileRecursiveSelectiveProjection(fields, ast, traversal, dialect) {
       pointer: jsonPointer([field2.field]),
       valueType: field2.valueType
     });
-    return sql`${extracted} AS ${quoteIdentifier2(field2.outputName)}`;
+    return sql`${extracted} AS ${quoteIdentifier(field2.outputName)}`;
   });
   const vl = traversal.variableLength;
   if (vl.depthAlias !== void 0) {
-    columns.push(sql`depth AS ${quoteIdentifier2(vl.depthAlias)}`);
+    columns.push(sql`depth AS ${quoteIdentifier(vl.depthAlias)}`);
   }
   if (vl.pathAlias !== void 0) {
-    columns.push(sql`path AS ${quoteIdentifier2(vl.pathAlias)}`);
+    columns.push(sql`path AS ${quoteIdentifier(vl.pathAlias)}`);
   }
   return sql.join(columns, sql`, `);
 }
@@ -4251,7 +4189,7 @@ function buildProjectedPropertyColumns(alias, plan, dialect) {
         valueType: fieldPlan.typeInfo?.valueType
       });
       columns.push(
-        sql`CASE WHEN ${sql.raw(alias)}.kind = ${kind} THEN ${extracted} ELSE NULL END AS ${quoteIdentifier2(fieldPlan.outputName)}`
+        sql`CASE WHEN ${sql.raw(alias)}.kind = ${kind} THEN ${extracted} ELSE NULL END AS ${quoteIdentifier(fieldPlan.outputName)}`
       );
     }
   }
@@ -5282,8 +5220,10 @@ function resolveCountAggregateFastPath(ast) {
   if (groupField.alias !== ast.start.alias || !isIdFieldRef(groupField)) {
     return void 0;
   }
-  let requiresCount = false;
-  let requiresCountDistinct = false;
+  let requiresNodeCount = false;
+  let requiresNodeCountDistinct = false;
+  let requiresEdgeCount = false;
+  let requiresEdgeCountDistinct = false;
   for (const projectedField of ast.projection.fields) {
     const source = projectedField.source;
     if (!isAggregateExpr(source)) {
@@ -5292,26 +5232,35 @@ function resolveCountAggregateFastPath(ast) {
       }
       continue;
     }
-    if (source.field.alias !== traversal.nodeAlias || !isIdFieldRef(source.field)) {
+    if (!isIdFieldRef(source.field)) {
+      return void 0;
+    }
+    const isNodeTarget = source.field.alias === traversal.nodeAlias;
+    const isEdgeTarget = source.field.alias === traversal.edgeAlias;
+    if (!isNodeTarget && !isEdgeTarget) {
       return void 0;
     }
     if (source.function === "count") {
-      requiresCount = true;
+      if (isNodeTarget) requiresNodeCount = true;
+      else requiresEdgeCount = true;
       continue;
     }
     if (source.function === "countDistinct") {
-      requiresCountDistinct = true;
+      if (isNodeTarget) requiresNodeCountDistinct = true;
+      else requiresEdgeCountDistinct = true;
       continue;
     }
     return void 0;
   }
-  if (!requiresCount && !requiresCountDistinct) {
+  if (!requiresNodeCount && !requiresNodeCountDistinct && !requiresEdgeCount && !requiresEdgeCountDistinct) {
     return void 0;
   }
   return {
     traversal,
-    requiresCount,
-    requiresCountDistinct
+    requiresNodeCount,
+    requiresNodeCountDistinct,
+    requiresEdgeCount,
+    requiresEdgeCountDistinct
   };
 }
 function compileCountAggregateFastPath(ast, graphId, ctx, logicalPlan, requiredColumnsByAlias, predicateIndex, temporalFilterPass) {
@@ -5319,15 +5268,23 @@ function compileCountAggregateFastPath(ast, graphId, ctx, logicalPlan, requiredC
   if (!plan) {
     return void 0;
   }
-  const { traversal, requiresCount, requiresCountDistinct } = plan;
+  const {
+    traversal,
+    requiresNodeCount,
+    requiresNodeCountDistinct,
+    requiresEdgeCount,
+    requiresEdgeCountDistinct
+  } = plan;
   const { dialect } = ctx;
   const startAlias = ast.start.alias;
   const previousAlias = traversal.joinFromAlias;
   const previousAliasIdColumn = `${previousAlias}_id`;
   const previousAliasKindColumn = `${previousAlias}_kind`;
   const countCteAlias = `cte_${traversal.nodeAlias}_counts`;
-  const countColumn = `${traversal.nodeAlias}_count`;
-  const countDistinctColumn = `${traversal.nodeAlias}_count_distinct`;
+  const nodeCountColumn = `${traversal.nodeAlias}_count`;
+  const nodeCountDistinctColumn = `${traversal.nodeAlias}_count_distinct`;
+  const edgeCountColumn = `${traversal.edgeAlias}_count`;
+  const edgeCountDistinctColumn = `${traversal.edgeAlias}_count_distinct`;
   const previousNodeKinds = getNodeKindsForAlias(ast, traversal.joinFromAlias);
   const edgeKinds = [...new Set(traversal.edgeKinds)];
   const nodeKinds = traversal.nodeKinds;
@@ -5353,34 +5310,68 @@ function compileCountAggregateFastPath(ast, graphId, ctx, logicalPlan, requiredC
   const targetField = traversal.direction === "out" ? "to_id" : "from_id";
   const joinKindField = traversal.direction === "out" ? "from_kind" : "to_kind";
   const targetKindField = traversal.direction === "out" ? "to_kind" : "from_kind";
+  const hasNodePredicates = nodePredicateClauses.length > 0;
+  const requiresNodeJoin = requiresNodeCount || requiresNodeCountDistinct || hasNodePredicates;
+  const useInnerJoin = hasNodePredicates;
   const whereClauses = [
     sql`e.graph_id = ${graphId}`,
     compileKindFilter(sql.raw("e.kind"), edgeKinds),
     compileKindFilter(sql.raw(`e.${joinKindField}`), previousNodeKinds),
     compileKindFilter(sql.raw(`e.${targetKindField}`), nodeKinds),
-    compileKindFilter(sql.raw("n.kind"), nodeKinds),
     edgeTemporalFilter,
-    nodeTemporalFilter,
-    ...nodePredicateClauses,
-    ...edgePredicateClauses
+    ...edgePredicateClauses,
+    // INNER JOIN mode: node-side filters in WHERE constrain every aggregate.
+    ...requiresNodeJoin && useInnerJoin ? [
+      compileKindFilter(sql.raw("n.kind"), nodeKinds),
+      nodeTemporalFilter,
+      ...nodePredicateClauses
+    ] : []
   ];
+  const nodeJoinOnClauses = requiresNodeJoin ? useInnerJoin ? (
+    // INNER JOIN: only the key conditions; filters live in WHERE.
+    [
+      sql`n.graph_id = e.graph_id`,
+      sql`n.id = e.${sql.raw(targetField)}`,
+      sql`n.kind = e.${sql.raw(targetKindField)}`
+    ]
+  ) : [
+    sql`n.graph_id = e.graph_id`,
+    sql`n.id = e.${sql.raw(targetField)}`,
+    sql`n.kind = e.${sql.raw(targetKindField)}`,
+    compileKindFilter(sql.raw("n.kind"), nodeKinds),
+    nodeTemporalFilter
+  ] : [];
   const aggregateColumns = [];
-  if (requiresCount) {
-    aggregateColumns.push(sql`COUNT(n.id) AS ${sql.raw(countColumn)}`);
+  if (requiresNodeCount) {
+    aggregateColumns.push(sql`COUNT(n.id) AS ${sql.raw(nodeCountColumn)}`);
+  }
+  if (requiresNodeCountDistinct) {
+    aggregateColumns.push(
+      sql`COUNT(DISTINCT n.id) AS ${sql.raw(nodeCountDistinctColumn)}`
+    );
   }
-  if (requiresCountDistinct) {
+  if (requiresEdgeCount) {
+    aggregateColumns.push(sql`COUNT(e.id) AS ${sql.raw(edgeCountColumn)}`);
+  }
+  if (requiresEdgeCountDistinct) {
     aggregateColumns.push(
-      sql`COUNT(DISTINCT n.id) AS ${sql.raw(countDistinctColumn)}`
+      sql`COUNT(DISTINCT e.id) AS ${sql.raw(edgeCountDistinctColumn)}`
     );
   }
+  const startCteLimit = traversal.optional && ast.orderBy === void 0 && ast.limit !== void 0 ? { limit: ast.limit, offset: ast.offset } : void 0;
   const startCte = buildStandardStartCte({
     ast,
     ctx,
     graphId,
     predicateIndex,
     requiredColumnsByAlias,
-    temporalFilterPass
+    temporalFilterPass,
+    ...startCteLimit === void 0 ? {} : { limitOffset: startCteLimit }
   });
+  const targetNodeJoinKeyword = useInnerJoin ? "JOIN" : "LEFT JOIN";
+  const targetNodeJoin = requiresNodeJoin ? sql`
+        ${sql.raw(targetNodeJoinKeyword)} ${ctx.schema.nodesTable} n ON ${sql.join(nodeJoinOnClauses, sql` AND `)}
+      ` : sql``;
   const countCte = sql`
     ${sql.raw(countCteAlias)} AS (
       SELECT
@@ -5389,16 +5380,20 @@ function compileCountAggregateFastPath(ast, graphId, ctx, logicalPlan, requiredC
         ${sql.join(aggregateColumns, sql`, `)}
       FROM cte_${sql.raw(previousAlias)}
       JOIN ${ctx.schema.edgesTable} e ON cte_${sql.raw(previousAlias)}.${sql.raw(previousAliasIdColumn)} = e.${sql.raw(joinField)}
-        AND cte_${sql.raw(previousAlias)}.${sql.raw(previousAliasKindColumn)} = e.${sql.raw(joinKindField)}
-      JOIN ${ctx.schema.nodesTable} n ON n.graph_id = e.graph_id
-        AND n.id = e.${sql.raw(targetField)}
-        AND n.kind = e.${sql.raw(targetKindField)}
+        AND cte_${sql.raw(previousAlias)}.${sql.raw(previousAliasKindColumn)} = e.${sql.raw(joinKindField)}${targetNodeJoin}
       WHERE ${sql.join(whereClauses, sql` AND `)}
       GROUP BY
         cte_${sql.raw(previousAlias)}.${sql.raw(previousAliasIdColumn)},
         cte_${sql.raw(previousAlias)}.${sql.raw(previousAliasKindColumn)}
     )
   `;
+  function resolveCountColumn(source) {
+    const isEdge = source.field.alias === traversal.edgeAlias;
+    if (source.function === "countDistinct") {
+      return isEdge ? edgeCountDistinctColumn : nodeCountDistinctColumn;
+    }
+    return isEdge ? edgeCountColumn : nodeCountColumn;
+  }
   const projection = sql.join(
     ast.projection.fields.map((projectedField) => {
       const source = projectedField.source;
@@ -5409,12 +5404,12 @@ function compileCountAggregateFastPath(ast, graphId, ctx, logicalPlan, requiredC
           source.valueType,
           `cte_${source.alias}`
         );
-        return sql`${value} AS ${quoteIdentifier2(projectedField.outputName)}`;
+        return sql`${value} AS ${quoteIdentifier(projectedField.outputName)}`;
       }
-      const projectedCountColumn = source.function === "countDistinct" ? countDistinctColumn : countColumn;
+      const projectedCountColumn = resolveCountColumn(source);
       const countValue = sql`${sql.raw(countCteAlias)}.${sql.raw(projectedCountColumn)}`;
       const aggregateValue = traversal.optional ? sql`COALESCE(${countValue}, 0)` : countValue;
-      return sql`${aggregateValue} AS ${quoteIdentifier2(projectedField.outputName)}`;
+      return sql`${aggregateValue} AS ${quoteIdentifier(projectedField.outputName)}`;
     }),
     sql`, `
   );
@@ -5426,19 +5421,29 @@ function compileCountAggregateFastPath(ast, graphId, ctx, logicalPlan, requiredC
       AND ${sql.raw(countCteAlias)}.${sql.raw(previousAliasKindColumn)} = cte_${sql.raw(previousAlias)}.${sql.raw(previousAliasKindColumn)}
   `;
   const orderBy = buildStandardOrderBy({ ast, dialect });
-  const limitOffset = buildLimitOffsetClause({
-    limit: ast.limit,
-    offset: ast.offset
-  });
+  const emittedLogicalPlan = startCteLimit === void 0 ? logicalPlan : stripLimitOffsetFromPlan(logicalPlan);
+  const limitOffset = startCteLimit === void 0 ? buildLimitOffsetClause({ limit: ast.limit, offset: ast.offset }) : void 0;
   return emitStandardQuerySql({
     ctes: [startCte, countCte],
     fromClause,
     ...orderBy === void 0 ? {} : { orderBy },
     ...limitOffset === void 0 ? {} : { limitOffset },
-    logicalPlan,
+    logicalPlan: emittedLogicalPlan,
     projection
   });
 }
+function stripLimitOffsetFromPlan(plan) {
+  return { ...plan, root: stripLimitOffsetFromPlanNode(plan.root) };
+}
+function stripLimitOffsetFromPlanNode(node) {
+  if (node.op === "limit_offset") {
+    return stripLimitOffsetFromPlanNode(node.input);
+  }
+  if ("input" in node) {
+    return { ...node, input: stripLimitOffsetFromPlanNode(node.input) };
+  }
+  return node;
+}
 var STANDARD_QUERY_STRATEGY_HANDLERS = {
   cte_project: compileStandardQueryWithCteStrategy
 };
@@ -9363,6 +9368,12 @@ function countDistinct(alias, field2) {
     }
   };
 }
+function countEdges(edgeAlias) {
+  return count(edgeAlias);
+}
+function countDistinctEdges(edgeAlias) {
+  return countDistinct(edgeAlias);
+}
 function sum(alias, field2) {
   return {
     __type: "aggregate",
@@ -12708,17 +12719,17 @@ async function rebuildFulltextIndex(ctx, nodeKind, options) {
       if (remaining > 0 && pageResult.skippedIds.length > 0) {
         skippedIds.push(...pageResult.skippedIds.slice(0, remaining));
       }
-      await backend.transaction(async (tx) => {
+      const writePage = async (target) => {
         if (pageResult.toUpsert.length > 0) {
-          if (tx.upsertFulltextBatch) {
-            await tx.upsertFulltextBatch({
+          if (target.upsertFulltextBatch) {
+            await target.upsertFulltextBatch({
               graphId: ctx.graphId,
               nodeKind: kind,
               rows: pageResult.toUpsert
             });
-          } else if (tx.upsertFulltext) {
+          } else if (target.upsertFulltext) {
             for (const item of pageResult.toUpsert) {
-              await tx.upsertFulltext({
+              await target.upsertFulltext({
                 graphId: ctx.graphId,
                 nodeKind: kind,
                 nodeId: item.nodeId,
@@ -12729,15 +12740,15 @@ async function rebuildFulltextIndex(ctx, nodeKind, options) {
           }
         }
         if (pageResult.toDelete.length > 0) {
-          if (tx.deleteFulltextBatch) {
-            await tx.deleteFulltextBatch({
+          if (target.deleteFulltextBatch) {
+            await target.deleteFulltextBatch({
               graphId: ctx.graphId,
               nodeKind: kind,
               nodeIds: pageResult.toDelete
             });
-          } else if (tx.deleteFulltext) {
+          } else if (target.deleteFulltext) {
             for (const nodeId of pageResult.toDelete) {
-              await tx.deleteFulltext({
+              await target.deleteFulltext({
                 graphId: ctx.graphId,
                 nodeKind: kind,
                 nodeId
@@ -12745,7 +12756,8 @@ async function rebuildFulltextIndex(ctx, nodeKind, options) {
             }
           }
         }
-      });
+      };
+      await runOptionallyInTransaction(backend, writePage);
       processed += rows.length;
       upserted += pageResult.toUpsert.length;
       cleared += pageResult.toDelete.length;
@@ -13427,12 +13439,19 @@ var Store = class {
   }
   // === Batch Query Execution ===
   /**
-   * Executes multiple queries over a single connection with snapshot consistency.
+   * Executes multiple queries and returns a typed tuple of results.
    *
-   * 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.
+   * Each query preserves its own result type, projection, filtering, sorting,
+   * and pagination.
+   *
+   * **Snapshot consistency is conditional.** When
+   * `backend.capabilities.transactions` is `true`, queries run sequentially
+   * on a single connection inside an implicit transaction and observe the
+   * same database snapshot. When transactions are unavailable
+   * (Cloudflare D1, `drizzle-orm/neon-http`), queries run sequentially over
+   * independent connections and may observe writes that landed between them.
+   * Branch on `backend.capabilities.transactions` if you need a guaranteed
+   * snapshot.
    *
    * Read-only — use `bulkCreate`, `bulkInsert`, etc. for write batching.
    *
@@ -13456,10 +13475,10 @@ var Store = class {
    * @returns A tuple with per-query typed results, preserving input order
    */
   async batch(...queries) {
-    return this.#backend.transaction(async (txBackend) => {
+    return runOptionallyInTransaction(this.#backend, async (target) => {
       const results = [];
       for (const query of queries) {
-        const result = await query.executeOn(txBackend);
+        const result = await query.executeOn(target);
         results.push(result);
       }
       return results;
@@ -13523,8 +13542,26 @@ var Store = class {
    *   );
    * });
    * ```
+   *
+   * **Backends without transactions.** When `backend.capabilities.transactions`
+   * is `false` (Cloudflare D1, `drizzle-orm/neon-http`), this method runs the
+   * callback against the same backend used outside `transaction()` — writes
+   * are applied as they happen and a thrown error does **not** roll back
+   * earlier writes inside the callback. Branch on
+   * `backend.capabilities.transactions` if you require atomicity:
+   *
+   * ```typescript
+   * if (backend.capabilities.transactions) {
+   *   await store.transaction(async (tx) => { ... });
+   * } else {
+   *   // sequential, non-atomic — handle partial-failure recovery yourself
+   * }
+   * ```
    */
   async transaction(fn) {
+    if (!this.#backend.capabilities.transactions) {
+      return fn({ nodes: this.nodes, edges: this.edges });
+    }
     return this.#backend.transaction(async (txBackend) => {
       const txNodeOperations = {
         ...this.#nodeOperations,
@@ -13572,6 +13609,36 @@ var Store = class {
     this.#search = void 0;
   }
   // === Lifecycle ===
+  /**
+   * Refreshes the backend's query-planner statistics.
+   *
+   * Call this once after a large initial import or bulk backfill. The
+   * planner uses table statistics to choose between TypeGraph's
+   * multi-column indexes; without fresh stats a forward traversal can
+   * pick a reverse index and run an order of magnitude slower than
+   * needed. Autovacuum / background statistics will catch up
+   * eventually, but calling this explicitly after a bulk load gives
+   * you correct latencies immediately.
+   *
+   * Implementations:
+   * - SQLite runs `ANALYZE`, populating `sqlite_stat1`
+   * - PostgreSQL runs `ANALYZE` on the TypeGraph-managed tables
+   *
+   * Costs a few tens of milliseconds at the sizes this library is
+   * designed for. Safe to call at any time.
+   *
+   * @example
+   * ```typescript
+   * // After a bulk import
+   * for (const batch of batches) {
+   *   await store.nodes.Document.bulkCreate(batch);
+   * }
+   * await store.refreshStatistics();
+   * ```
+   */
+  async refreshStatistics() {
+    await this.#backend.refreshStatistics();
+  }
   /**
    * Closes the store and releases underlying resources.
    *
@@ -13676,6 +13743,6 @@ async function createStoreWithSchema(graph, backend, options) {
   return [store, result];
 }
 
-export { DEFAULT_SQL_SCHEMA, ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, StoreSearch, UnionableQuery, avg, broader, composeFragments, core, count, countDistinct, createExternalRef, createFragment, createQueryBuilder, createSqlSchema, createStore, createStoreWithSchema, defineEdge, defineNode, defineSubgraphProject, differentFrom, disjointWith, equivalentTo, exists, externalRef, field, fieldRef, generateId, getExternalRefTable, hasPart, having, havingEq, havingGt, havingGte, havingLt, havingLte, implies, inSubquery, inverseOf, isExternalRefSchema, isParameterRef, limitFragment, max, metaEdge, min, narrower, notExists, notInSubquery, offsetFragment, orderByFragment, param, partOf, relatedTo, sameAs, subClassOf, sum };
+export { DEFAULT_SQL_SCHEMA, ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, StoreSearch, UnionableQuery, avg, broader, composeFragments, core, count, countDistinct, countDistinctEdges, countEdges, createExternalRef, createFragment, createQueryBuilder, createSqlSchema, createStore, createStoreWithSchema, defineEdge, defineNode, defineSubgraphProject, differentFrom, disjointWith, equivalentTo, exists, externalRef, field, fieldRef, generateId, getExternalRefTable, hasPart, having, havingEq, havingGt, havingGte, havingLt, havingLte, implies, inSubquery, inverseOf, isExternalRefSchema, isParameterRef, limitFragment, max, metaEdge, min, narrower, notExists, notInSubquery, offsetFragment, orderByFragment, param, partOf, relatedTo, sameAs, subClassOf, sum };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map