@dbsp/core 1.5.0 → 1.6.0

package/dist/index.js

@@ -1665,7 +1665,7 @@ function isManyToMany(rel) {
 }
 
 // src/planner.ts
-import { toColumnList } from "@dbsp/types";
+import { resolveJsonAggOrderKey, toColumnList } from "@dbsp/types";
 
 // src/dx/errors.ts
 var ExecutionError = class _ExecutionError extends Error {
@@ -2410,12 +2410,6 @@ function isSubquerySelectedColumnNonNullable(existsIntent, sourceTable, model) {
   if (!column) return false;
   return !column.nullable;
 }
-function resolveTargetJsonAggOrderKey(model, targetTable) {
-  const table = model.getTable(targetTable);
-  if (!table) return { columns: [], fallback: false };
-  const pkColumns = toColumnList(table.primaryKey);
-  return pkColumns.length > 0 ? { columns: pkColumns, fallback: false } : { columns: table.columns.map((col2) => col2.name), fallback: true };
-}
 function optimizeInToExists(where, sourceTable, model, negated = false) {
   switch (where.kind) {
     case "in": {
@@ -2744,7 +2738,8 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
   const explicitJoinType = includeStrategy === "join" ? include.join ?? cascadedJoinType : void 0;
   const includeDecisionId = generateDecisionId(state, "include-strategy");
   const parentKey = relation.type === "belongsTo" ? relation.targetKey : relation.sourceKey;
-  const targetOrder = resolveTargetJsonAggOrderKey(model, relation.target);
+  const targetTable = model.getTable(relation.target);
+  const targetOrder = targetTable ? resolveJsonAggOrderKey(targetTable) : void 0;
   state.decisions.push({
     id: includeDecisionId,
     type: "include-strategy",
@@ -2760,10 +2755,10 @@ function processInclude(include, sourceTable, model, state, opts, intentPath, de
         foreignKey: relation.foreignKey
       },
       ...parentKey !== void 0 && { parentKey },
-      ...targetOrder.columns.length > 0 && {
-        targetPrimaryKey: targetOrder.columns
+      ...targetOrder && targetOrder.columns.length > 0 && {
+        targetOrderKey: targetOrder.columns
       },
-      ...targetOrder.fallback && { orderByFallback: true }
+      ...targetOrder?.fallback && { orderByFallback: true }
     },
     choice: includeStrategy,
     // Embed joinType so the adapter's join handler can use it directly
@@ -6257,7 +6252,7 @@ import {
   NqlLexer,
   compile as nqlCompile
 } from "@dbsp/nql";
-import { toColumnList as toColumnList2 } from "@dbsp/types";
+import { resolveJsonAggOrderKey as resolveJsonAggOrderKey2 } from "@dbsp/types";
 import {
   explainUnsupportedNqlBindingIncludeHop,
   getTrustedNqlRelationFilterFields,
@@ -6411,7 +6406,11 @@ function virtualRelationIncludeShape(relation) {
     type: relationType,
     foreignKey,
     source: relation.sourceTable,
-    target: relation.targetTable
+    target: relation.targetTable,
+    ...relation.through !== void 0 && { through: relation.through },
+    ...relation.throughTargetColumn !== void 0 && {
+      otherKey: relation.throughTargetColumn
+    }
   };
 }
 var BINDING_INCLUDE_NODE_ONLY_RELATION = {
@@ -6457,7 +6456,8 @@ function trustedBindingRelationColumnIsAdmitted(column) {
   if (trusted.cardinality === "one") {
     return !isDotted || trusted.hops.length > 0;
   }
-  return trusted.cardinality === "many" && trusted.relationType === "hasMany" && !isDotted && trusted.hops.length === 0;
+  const hasCompleteManyToManyProof = (trusted.relationType === "manyToMany" || trusted.relationType === "belongsToMany") && trusted.through !== void 0 && trusted.throughSourceColumn !== void 0 && trusted.throughTargetColumn !== void 0;
+  return trusted.cardinality === "many" && (trusted.relationType === "hasMany" || hasCompleteManyToManyProof) && !isDotted && trusted.hops.length === 0;
 }
 function assertProvenBindingInclude(bindingName, include, provenRelations) {
   const proven = provenRelations.get(include.relation);
@@ -6519,7 +6519,8 @@ function createBindingIncludeDecision(intent, include, relation, index, model) {
   const relationType = relation.relationType;
   const foreignKey = relationType === "belongsTo" ? relation.sourceColumn : relation.targetColumn;
   const parentKey = relationType === "belongsTo" ? relation.targetColumn : relation.sourceColumn;
-  const targetOrder = resolveTargetJsonAggOrderKey2(model, relation.targetTable);
+  const targetTable = model.getTable(relation.targetTable);
+  const targetOrder = targetTable ? resolveJsonAggOrderKey2(targetTable) : void 0;
   return {
     id: `binding-include-${index}`,
     type: "include-strategy",
@@ -6530,10 +6531,10 @@ function createBindingIncludeDecision(intent, include, relation, index, model) {
       relationType,
       foreignKey,
       parentKey,
-      ...targetOrder.columns.length > 0 && {
-        targetPrimaryKey: targetOrder.columns
+      ...targetOrder && targetOrder.columns.length > 0 && {
+        targetOrderKey: targetOrder.columns
       },
-      ...targetOrder.fallback && { orderByFallback: true },
+      ...targetOrder?.fallback && { orderByFallback: true },
       includeAlias: include.relation,
       intentPath: `include[${index}]`
     },
@@ -6549,12 +6550,6 @@ function parentKeyForRelation(relation) {
   if (relation.type === "belongsTo") return relation.targetKey;
   return relation.sourceKey;
 }
-function resolveTargetJsonAggOrderKey2(model, targetTable) {
-  const table = model.getTable(targetTable);
-  if (!table) return { columns: [], fallback: false };
-  const pkColumns = toColumnList2(table.primaryKey);
-  return pkColumns.length > 0 ? { columns: pkColumns, fallback: false } : { columns: table.columns.map((col2) => col2.name), fallback: true };
-}
 function assertSupportedBindingIncludeHop(bindingName, rootIncludeRelation, relationName, relation, include, reasonPrefix = "") {
   const unsupportedReason = explainUnsupportedNqlBindingIncludeHop(
     relationName,
@@ -6653,10 +6648,11 @@ function createBindingTailIncludeDecisions(bindingName, include, firstHopRelatio
     const baseContext = { ...decision.context };
     delete baseContext.foreignKey;
     delete baseContext.parentKey;
-    delete baseContext.targetPrimaryKey;
+    delete baseContext.targetOrderKey;
     delete baseContext.orderByFallback;
     const parentKey = parentKeyForRelation(relation);
-    const targetOrder = resolveTargetJsonAggOrderKey2(model, relation.target);
+    const targetTable = model.getTable(relation.target);
+    const targetOrder = targetTable ? resolveJsonAggOrderKey2(targetTable) : void 0;
     return {
       ...decision,
       id: `binding-include-${includeIndex}-tail-${tailIndex}`,
@@ -6674,10 +6670,10 @@ function createBindingTailIncludeDecisions(bindingName, include, firstHopRelatio
         // Leave parentKey absent when RelationIR does not specify it so the
         // adapter applies the same defaultPkColumnName fallback as real-table includes.
         ...parentKey !== void 0 && { parentKey },
-        ...targetOrder.columns.length > 0 && {
-          targetPrimaryKey: targetOrder.columns
+        ...targetOrder && targetOrder.columns.length > 0 && {
+          targetOrderKey: targetOrder.columns
         },
-        ...targetOrder.fallback && { orderByFallback: true },
+        ...targetOrder?.fallback && { orderByFallback: true },
         intentPath: rebaseBindingTailIntentPath(
           decision.context.intentPath,
           includeIndex
@@ -6698,6 +6694,13 @@ function createBindingFinalPlan(intent, bundle, model, dialectCapabilities) {
       );
     }
     const proven = provenIncludes.get(include.relation);
+    if (!proven) {
+      throw bindingFinalIncludeError(
+        intent.from,
+        include.relation,
+        "include relation proof was not emitted by the binding compiler"
+      );
+    }
     const firstHopDecision = createBindingIncludeDecision(
       intent,
       include,
@@ -6848,6 +6851,14 @@ function assembleNqlTemplate(strings, values) {
 function hasMutationBindingBodies(bundle) {
   return (bundle.mutationBindings?.size ?? 0) > 0;
 }
+function hasSnapshotReadBindingSteps(bundle) {
+  return bundle.nqlProgramSequence?.some(
+    (step) => step.kind === "query" && step.snapshot === true
+  ) ?? false;
+}
+function hasExecutableNqlProgramSequence(bundle) {
+  return hasMutationBindingBodies(bundle) || hasSnapshotReadBindingSteps(bundle);
+}
 function requireMutationBindingColumns(bundle, bindName) {
   const columns = bundle.bindingOutputSchemas?.get(bindName)?.columns;
   if (columns === void 0 || columns.length === 0) {
@@ -6911,6 +6922,7 @@ function orderedSequenceStepToProgramStep(step) {
       intent: step.query,
       ...step.bindName !== void 0 && { bindName: step.bindName },
       final: step.final,
+      ...step.snapshot === true && { snapshot: true },
       ...dependencyStep.bindingDependencies !== void 0 && {
         bindingDependencies: dependencyStep.bindingDependencies
       }
@@ -6926,15 +6938,32 @@ function orderedSequenceStepToProgramStep(step) {
     }
   };
 }
+var structuredCloneFn = globalThis.structuredClone;
+function hasCustomSnapshotPrototype(value) {
+  if (value === null || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype !== Object.prototype && prototype !== null && prototype !== Array.prototype && prototype !== Date.prototype && prototype !== Map.prototype && prototype !== Set.prototype;
+}
+function cloneMutationSnapshotColumnValue(value) {
+  if (hasCustomSnapshotPrototype(value) || structuredCloneFn === void 0) {
+    return value;
+  }
+  try {
+    return structuredCloneFn(value);
+  } catch {
+    return value;
+  }
+}
 function snapshotMutationRows(rows) {
   return rows.map((row) => {
-    if (Array.isArray(row)) {
-      return [...row];
+    if (row === null || typeof row !== "object") {
+      return cloneMutationSnapshotColumnValue(row);
     }
-    if (row !== null && typeof row === "object") {
-      return { ...row };
+    const snapshot = { ...row };
+    for (const key of Reflect.ownKeys(snapshot)) {
+      snapshot[key] = cloneMutationSnapshotColumnValue(snapshot[key]);
     }
-    return row;
+    return snapshot;
   });
 }
 function assertNqlProgramSteps(compiledIntent, steps) {
@@ -6958,6 +6987,13 @@ function assertNqlProgramSteps(compiledIntent, steps) {
   }
   const seenBindNames = /* @__PURE__ */ new Set();
   for (const step of steps) {
+    if (step.kind === "query" && step.snapshot === true) {
+      if (step.bindName === void 0 || step.final) {
+        throw new Error(
+          "NQL program sequence query snapshots must be named non-final statements."
+        );
+      }
+    }
     if (step.bindName === void 0) continue;
     if (seenBindNames.has(step.bindName)) {
       throw new Error(
@@ -7063,6 +7099,18 @@ function filterOptionalMapByBindingDependencies(source, bindingDependencies) {
   const filtered = filterMapByBindingDependencies(source, bindingDependencies);
   return filtered.size > 0 ? filtered : void 0;
 }
+function runtimeSourceBindingNames(sourceBundle) {
+  const names = /* @__PURE__ */ new Set();
+  for (const name of sourceBundle.mutationBindings?.keys() ?? []) {
+    names.add(name);
+  }
+  for (const step of sourceBundle.nqlProgramSequence ?? []) {
+    if (step.kind === "query" && step.snapshot === true && step.bindName !== void 0) {
+      names.add(step.bindName);
+    }
+  }
+  return names.size > 0 ? names : void 0;
+}
 function filterMapByRuntimeBindingDependencies(source, runtimeSourceBindings, bindingDependencies) {
   if (source === void 0) return /* @__PURE__ */ new Map();
   if (bindingDependencies === void 0 || runtimeSourceBindings === void 0 || runtimeSourceBindings.size === 0) {
@@ -7202,7 +7250,7 @@ var NqlBuilderImpl = class {
   }
   dump(meta) {
     const compiledIntent = this.compile();
-    if (hasMutationBindingBodies(compiledIntent.bundle)) {
+    if (hasExecutableNqlProgramSequence(compiledIntent.bundle)) {
       return this.dumpNqlProgramSequence(compiledIntent, meta);
     }
     if (compiledIntent.kind === "mutation") {
@@ -7285,7 +7333,7 @@ var NqlBuilderImpl = class {
   createNqlStatementBundle(statement, bindings, runtimeBindings, sourceBundle, bindingDependencies, planReport) {
     const statementBindings = filterMapByRuntimeBindingDependencies(
       bindings,
-      sourceBundle.mutationBindings,
+      runtimeSourceBindingNames(sourceBundle),
       bindingDependencies
     );
     const statementRuntimeBindings = filterMapByBindingDependencies(
@@ -7425,6 +7473,28 @@ var NqlBuilderImpl = class {
           if (step.final) {
             finalRows = rows.transformedRows;
           }
+        } else if (step.snapshot === true && step.bindName !== void 0) {
+          const statementBundle = this.createNqlStatementBundle(
+            { query: step.intent },
+            priorBindings,
+            runtimeBindings,
+            sourceBundle,
+            step.bindingDependencies
+          );
+          const compiled = txAdapter.compile(
+            statementBundle,
+            this.nqlBundleCompileOptions()
+          );
+          const rows = await txAdapter.execute(compiled);
+          runtimeBindings.set(
+            step.bindName,
+            createRuntimeBinding(
+              sourceBundle,
+              step.bindName,
+              snapshotMutationRows(rows),
+              txAdapter.dbCasing
+            )
+          );
         } else if (step.final) {
           const planReport = isBindingFinalQuery(compiledIntent.bundle) && compiledIntent.kind === "query" ? createBindingFinalPlan(
             step.intent,
@@ -7516,6 +7586,12 @@ var NqlBuilderImpl = class {
           sql: compiled.sql,
           params: compiled.parameters
         });
+        if (step.snapshot === true && step.bindName !== void 0) {
+          runtimeBindings.set(step.bindName, {
+            columns: requireMutationBindingColumns(sourceBundle, step.bindName),
+            rows: []
+          });
+        }
       }
       if (step.bindName !== void 0) {
         const boundQuery = sourceBundle.bindings?.get(step.bindName);
@@ -7595,7 +7671,7 @@ var NqlBuilderImpl = class {
       );
     }
     const compiledIntent = this.compile();
-    if (hasMutationBindingBodies(compiledIntent.bundle)) {
+    if (hasExecutableNqlProgramSequence(compiledIntent.bundle)) {
       return this.executeNqlProgramSequence(compiledIntent, adapter);
     }
     if (compiledIntent.kind === "mutation") {
@@ -7940,7 +8016,7 @@ async function cursorPaginate(builder, options) {
 }
 
 // src/dx/result-hydrator.ts
-import { toColumnList as toColumnList3 } from "@dbsp/types";
+import { toColumnList as toColumnList2 } from "@dbsp/types";
 
 // src/dx/relation-paths.ts
 function nonEmptyString(value) {
@@ -8317,7 +8393,7 @@ var ResultHydrator = class {
    * Get the foreign key column name from relation metadata.
    */
   getForeignKeyColumn(foreignKey) {
-    const columns = toColumnList3(foreignKey);
+    const columns = toColumnList2(foreignKey);
     if (columns.length === 0) {
       return "parent_id";
     }
@@ -8418,7 +8494,7 @@ var ResultHydrator = class {
    * case (slower but collision-safe for any value content).
    */
   extractKeyValue(obj, key) {
-    const columns = toColumnList3(key);
+    const columns = toColumnList2(key);
     if (columns.length === 0) {
       return void 0;
     }
@@ -8436,7 +8512,7 @@ var ResultHydrator = class {
     return parts.join(COMPOSITE_KEY_SEP);
   }
   extractQueryKeyValue(obj, key) {
-    const columns = toColumnList3(key);
+    const columns = toColumnList2(key);
     if (columns.length === 0) {
       return void 0;
     }
@@ -10867,6 +10943,7 @@ function rangeContainedBy(fieldOrColumn, valueOrRange, rangeType = "daterange")
 }
 
 // src/dx/schema-bridge.ts
+import { buildRelationKeyFields, toColumnList as toColumnList3 } from "@dbsp/types";
 import * as v from "valibot";
 function generatedTypeToColumnType(genType) {
   switch (genType) {
@@ -10919,6 +10996,37 @@ function mapRelationType2(kind) {
       return "belongsToMany";
   }
 }
+function sourceTableFromQualifiedName(qualifiedName) {
+  const dotIndex = qualifiedName.indexOf(".");
+  return dotIndex > 0 ? qualifiedName.slice(0, dotIndex) : qualifiedName;
+}
+function relationNameFromQualifiedName(qualifiedName) {
+  const dotIndex = qualifiedName.indexOf(".");
+  return dotIndex > 0 ? qualifiedName.slice(dotIndex + 1) : qualifiedName;
+}
+function columnListsEqual(left, right) {
+  const leftColumns = toColumnList3(left);
+  const rightColumns = toColumnList3(right);
+  return leftColumns.length === rightColumns.length && leftColumns.every((column, index) => column === rightColumns[index]);
+}
+function generatedReferencedColumns(key) {
+  const columns = toColumnList3(key);
+  return columns.length > 0 ? columns : ["id"];
+}
+function findRelationForeignKey(sourceTable, genRelation, tables) {
+  switch (genRelation.kind) {
+    case "belongsTo":
+      return tables.get(sourceTable)?.foreignKeys.find(
+        (fk) => fk.references.table === genRelation.target && columnListsEqual(fk.columns, genRelation.foreignKey)
+      );
+    case "hasMany":
+      return tables.get(genRelation.target)?.foreignKeys.find(
+        (fk) => fk.references.table === sourceTable && columnListsEqual(fk.columns, genRelation.foreignKey)
+      );
+    case "manyToMany":
+      return void 0;
+  }
+}
 function isGeneratedTableWithConfig(table) {
   const columns = table.columns;
   return typeof columns === "object" && columns !== null && typeof columns.type !== "string";
@@ -11046,10 +11154,9 @@ function buildTableIRFromDefinition(tableName, genTable, fkAutoIndex) {
     }
   });
 }
-function buildRelationIR(qualifiedName, genRelation, hints) {
-  const dotIndex = qualifiedName.indexOf(".");
-  const sourceTable = dotIndex > 0 ? qualifiedName.slice(0, dotIndex) : qualifiedName;
-  const relationName = dotIndex > 0 ? qualifiedName.slice(dotIndex + 1) : qualifiedName;
+function buildRelationIR(qualifiedName, genRelation, hints, relationFk) {
+  const sourceTable = sourceTableFromQualifiedName(qualifiedName);
+  const relationName = relationNameFromQualifiedName(qualifiedName);
   const hint = hints[qualifiedName];
   const relCardinality = genRelation.kind === "hasMany" ? genRelation.cardinality : void 0;
   const cardinality = hint?.cardinality === "one" ? "one" : relCardinality === "one" ? "one" : genRelation.kind === "belongsTo" ? "one" : "many";
@@ -11073,14 +11180,38 @@ function buildRelationIR(qualifiedName, genRelation, hints) {
     case "belongsTo":
       return {
         ...baseRelation,
-        foreignKey: genRelation.foreignKey,
-        ...genRelation.targetKey ? { targetKey: genRelation.targetKey } : {}
+        ...buildRelationKeyFields(
+          relationFk ?? {
+            columns: genRelation.foreignKey,
+            references: {
+              table: genRelation.target,
+              columns: generatedReferencedColumns(genRelation.targetKey)
+            }
+          },
+          "belongsTo",
+          {
+            foreignKeyShape: genRelation.foreignKey,
+            ...genRelation.targetKey !== void 0 ? { referencedKeyShape: genRelation.targetKey } : {}
+          }
+        )
       };
     case "hasMany":
       return {
         ...baseRelation,
-        foreignKey: genRelation.foreignKey,
-        ...genRelation.sourceKey ? { sourceKey: genRelation.sourceKey } : {}
+        ...buildRelationKeyFields(
+          relationFk ?? {
+            columns: genRelation.foreignKey,
+            references: {
+              table: sourceTable,
+              columns: generatedReferencedColumns(genRelation.sourceKey)
+            }
+          },
+          "inverse",
+          {
+            foreignKeyShape: genRelation.foreignKey,
+            ...genRelation.sourceKey !== void 0 ? { referencedKeyShape: genRelation.sourceKey } : {}
+          }
+        )
       };
     case "manyToMany":
       return {
@@ -11102,9 +11233,15 @@ function buildModelFromSchema(schema2) {
     );
   }
   for (const [qualifiedName, genRelation] of Object.entries(schema2.relations)) {
+    const sourceTable = sourceTableFromQualifiedName(qualifiedName);
     relations.set(
       qualifiedName,
-      buildRelationIR(qualifiedName, genRelation, schema2.hints)
+      buildRelationIR(
+        qualifiedName,
+        genRelation,
+        schema2.hints,
+        findRelationForeignKey(sourceTable, genRelation, tables)
+      )
     );
   }
   return new ModelIRImpl(tables, relations);