@dbsp/nql 1.7.0 → 1.8.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CompiledNqlQuery } from '@dbsp/types';
+import { ColumnType, CompiledNqlQuery } from '@dbsp/types';
 export { CompiledNqlQuery, DeleteIntent, ExpressionIntent, IncludeIntent, InsertIntent, MutationIntent, OrderByIntent, QueryIntent, SelectAllIntent, SelectFieldsIntent, SelectIntent, SelectWithExpressionsIntent, UpdateIntent, UpsertIntent, WhereAndIntent, WhereComparisonIntent, WhereInIntent, WhereIntent, WhereLikeIntent, WhereNotIntent, WhereNullIntent, WhereOrIntent, WhereRangeIntent } from '@dbsp/types';
 import * as chevrotain from 'chevrotain';
 import { Lexer, CstParser, CstNode, IToken } from 'chevrotain';
@@ -454,11 +454,20 @@ interface ColumnValidatorPseudoColumn {
     readonly ascendantKeyword?: string;
     readonly descendantKeyword?: string;
 }
+/**
+ * Duck-type column shape carried by `ColumnValidatorSchema.getTable()`.
+ * `type`/`originalDbType` are optional so hand-authored test schemas that
+ * only supply `name` remain valid — absence makes a column's type
+ * unresolvable (untypeable), never silently mismatched.
+ */
+interface ColumnValidatorTableColumn {
+    readonly name: string;
+    readonly type?: ColumnType;
+    readonly originalDbType?: string;
+}
 interface ColumnValidatorSchema {
     getTable(name: string): {
-        readonly columns: readonly {
-            readonly name: string;
-        }[];
+        readonly columns: readonly ColumnValidatorTableColumn[];
         readonly pseudoColumns?: readonly ColumnValidatorPseudoColumn[];
     } | undefined;
     getRelationsFrom(sourceTable: string): readonly ColumnValidatorRelation[];
@@ -518,6 +527,15 @@ declare class NqlCompiler {
     private registerQueryBindingOutputSchema;
     private canonicalizeMutationBinding;
     private getMutationBindingOutputSchema;
+    /**
+     * Build `columnTypes`/`columnTypesUnavailable` for a mutation-RETURNING
+     * binding. #213 B2: detection consumes `ctx.lastMutationReturningItems`
+     * (alias-aware, positional) — NEVER the collapsed `columns` names — so an
+     * alias colliding with a real column (`returning email as name`) is
+     * flagged 'aliased-returning' rather than silently mistyped as the
+     * colliding column's type.
+     */
+    private buildMutationReturningColumnTypes;
     private compileSingleStatement;
 }
 /**

package/dist/index.js

@@ -43,6 +43,45 @@ var NqlSemanticException = class extends Error {
     this.relatedSymbol = relatedSymbol;
   }
 };
+
+// src/compiler/binding-column-types.ts
+function freezeColumnTypes(types) {
+  for (const info of Object.values(types)) {
+    Object.freeze(info);
+  }
+  return Object.freeze(types);
+}
+function buildBindingColumnTypes(columns, candidates) {
+  const attemptsByColumn = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    const bucket = attemptsByColumn.get(candidate.column);
+    if (bucket) {
+      bucket.push(candidate);
+    } else {
+      attemptsByColumn.set(candidate.column, [candidate]);
+    }
+  }
+  const types = /* @__PURE__ */ Object.create(
+    null
+  );
+  for (const column of columns) {
+    const attempts = attemptsByColumn.get(column) ?? [];
+    if (attempts.length > 1) {
+      return { untypeable: { column, reason: "duplicate-output-name" } };
+    }
+    const candidate = attempts[0];
+    if (candidate?.typed === void 0) {
+      return {
+        untypeable: {
+          column,
+          reason: candidate?.untypeable ?? "unresolvable-source"
+        }
+      };
+    }
+    types[column] = candidate.typed;
+  }
+  return { columnTypes: freezeColumnTypes(types) };
+}
 var DEFAULT_RELATION_TARGET_COLUMN = "id";
 function relationForeignKeys(relation) {
   if (!relation) return void 0;
@@ -117,6 +156,25 @@ var ColumnValidator = class _ColumnValidator {
   getPhysicalTableColumns(name) {
     return this.schema.getTable(name)?.columns.map((column) => column.name);
   }
+  /**
+   * Resolve a physical column's neutral type info for binding-snapshot
+   * type propagation (#213). Returns undefined when the table/column is
+   * unknown OR the schema did not supply a `type` for it — the caller
+   * treats undefined as untypeable, never falls back to a guess.
+   */
+  getTableColumnType(table, column) {
+    const resolvedName = this.resolvePhysicalColumnName(table, column);
+    if (resolvedName === void 0) return void 0;
+    const columnInfo = this.schema.getTable(table)?.columns.find((candidate) => candidate.name === resolvedName);
+    if (columnInfo?.type === void 0) return void 0;
+    return {
+      kind: "column",
+      type: columnInfo.type,
+      ...columnInfo.originalDbType !== void 0 && {
+        originalDbType: columnInfo.originalDbType
+      }
+    };
+  }
   getPseudoColumns(name) {
     return this.schema.getTable(name)?.pseudoColumns ?? [];
   }
@@ -1119,11 +1177,14 @@ function compileMutationPipeline(pipeline, ctx, fns, bindings) {
   ctx.currentFromTable = pipeline.mutation.table;
   const mutation = compileMutation(pipeline.mutation, ctx, fns, bindings);
   let returning;
+  let returningItems;
   for (const clause of pipeline.clauses) {
     if (clause.type === "select") {
-      returning = extractReturningColumns(clause, ctx);
+      returningItems = extractReturningItems(clause, ctx);
+      returning = returningItems === "star" ? ["*"] : returningItems.map((item) => item.output);
     }
   }
+  ctx.lastMutationReturningItems = returningItems;
   if (returning) {
     return {
       mutation: { ...mutation, returning }
@@ -1311,11 +1372,11 @@ function compileUpsertFrom(upsertFrom, ctx, fns, bindings) {
     }
   };
 }
-function extractReturningColumns(clause, ctx) {
-  const columns = [];
+function extractReturningItems(clause, ctx) {
+  const items = [];
   for (const item of clause.items) {
     if (item.type === "star") {
-      return ["*"];
+      return "star";
     }
     if (item.type === "expression") {
       const field = expressionToField(item.expression);
@@ -1323,11 +1384,14 @@ function extractReturningColumns(clause, ctx) {
         if (ctx.currentFromTable && !field.includes(".")) {
           ctx.validator?.validateColumn(ctx.currentFromTable, field);
         }
-        columns.push(item.alias ?? field);
+        items.push({
+          output: item.alias ?? field,
+          aliased: item.alias !== void 0
+        });
       }
     }
   }
-  return columns;
+  return items;
 }
 function resolveBindingsInWhere(where, bindings) {
   if (!bindings || bindings.size === 0) return where;
@@ -2470,39 +2534,74 @@ function resolveSourceOutputColumns(intent, ctx, bindingName) {
     `Cannot compute output schema for NQL binding '${bindingName}' from SELECT * on '${intent.from}' without a concrete table schema.`
   );
 }
-function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []) {
+function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = [], sourceBindingSchemas) {
   const columns = [];
   const seen = /* @__PURE__ */ new Set();
   const directProjectionLineage = [];
+  const typeCandidates = [];
+  const sourceIsPhysicalTable = ctx.validator?.hasPhysicalTable(intent.from) ?? false;
+  const sourceBindingSchema = sourceIsPhysicalTable ? void 0 : sourceBindingSchemas?.get(intent.from);
   const addColumn = (column) => addUnique(columns, seen, column);
   const resolveSourceColumn = (column) => ctx.validator?.resolveColumnName(intent.from, column) ?? column;
   const addDirectProjection = (outputColumn, sourceColumn) => {
+    const resolvedSourceColumn = resolveSourceColumn(sourceColumn);
+    let typeInfo;
+    let untypeableReason = "unresolvable-source";
+    if (sourceIsPhysicalTable) {
+      typeInfo = ctx.validator?.getTableColumnType(
+        intent.from,
+        resolvedSourceColumn
+      );
+    } else if (sourceBindingSchema?.columnTypes) {
+      typeInfo = sourceBindingSchema.columnTypes[resolvedSourceColumn];
+    } else if (sourceBindingSchema?.columnTypesUnavailable) {
+      untypeableReason = sourceBindingSchema.columnTypesUnavailable.reason;
+    }
+    typeCandidates.push(
+      typeInfo !== void 0 ? { column: outputColumn, typed: typeInfo } : { column: outputColumn, untypeable: untypeableReason }
+    );
     if (!addColumn(outputColumn)) return;
     directProjectionLineage.push({
       kind: "directProjection",
       sourceTable: intent.from,
-      sourceColumn: resolveSourceColumn(sourceColumn),
+      sourceColumn: resolvedSourceColumn,
       outputColumn
     });
   };
+  const addUntypedColumn = (outputColumn, reason) => {
+    typeCandidates.push({ column: outputColumn, untypeable: reason });
+    addColumn(outputColumn);
+  };
+  const addCountAggregateColumn = (outputColumn) => {
+    typeCandidates.push({
+      column: outputColumn,
+      typed: { kind: "aggregate", fn: "count" }
+    });
+    addColumn(outputColumn);
+  };
   const addSourceColumns = () => {
     for (const column of resolveSourceOutputColumns(intent, ctx, bindingName)) {
       addDirectProjection(column, column);
     }
   };
-  const { select } = intent;
-  if (!select || select.type === "all") {
-    addSourceColumns();
-    const outputSchema2 = { columns, directProjectionLineage };
+  const finalizeOutputSchema = () => {
+    const outputSchema = { columns, directProjectionLineage };
+    const typesResult = buildBindingColumnTypes(columns, typeCandidates);
     return {
-      columns: outputSchema2.columns,
+      columns: outputSchema.columns,
       relationFilters: getBindingRelationFilterMetadata(
         intent,
         ctx,
-        outputSchema2,
+        outputSchema,
         bindingDependencies
-      )
+      ),
+      ..."columnTypes" in typesResult ? { columnTypes: typesResult.columnTypes } : { columnTypesUnavailable: typesResult.untypeable }
     };
+  };
+  const { select } = intent;
+  if (!select || select.type === "all") {
+    addSourceColumns();
+    return finalizeOutputSchema();
   }
   if (select.type === "fields") {
     for (const field of select.fields) {
@@ -2512,16 +2611,7 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
         addDirectProjection(field, field);
       }
     }
-    const outputSchema2 = { columns, directProjectionLineage };
-    return {
-      columns: outputSchema2.columns,
-      relationFilters: getBindingRelationFilterMetadata(
-        intent,
-        ctx,
-        outputSchema2,
-        bindingDependencies
-      )
-    };
+    return finalizeOutputSchema();
   }
   if (select.type === "aggregate") {
     for (const field of select.fields ?? []) {
@@ -2534,18 +2624,13 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
           `Cannot compute output schema for NQL binding '${bindingName}': aggregate '${aggregate.function}' must use an alias.`
         );
       }
-      addColumn(aggregate.as);
+      if (aggregate.function === "count") {
+        addCountAggregateColumn(aggregate.as);
+      } else {
+        addUntypedColumn(aggregate.as, "unsupported-aggregate");
+      }
     }
-    const outputSchema2 = { columns, directProjectionLineage };
-    return {
-      columns: outputSchema2.columns,
-      relationFilters: getBindingRelationFilterMetadata(
-        intent,
-        ctx,
-        outputSchema2,
-        bindingDependencies
-      )
-    };
+    return finalizeOutputSchema();
   }
   for (const expr of select.columns) {
     if (expr.kind === "column" && expr.column === "*") {
@@ -2569,20 +2654,16 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
       addDirectProjection(outputColumn, expr.column);
     } else if (expr.kind === "columnAlias") {
       addDirectProjection(outputColumn, expr.column);
+    } else if (expr.kind === "aggregate" && expr.function === "count") {
+      addCountAggregateColumn(outputColumn);
     } else {
-      addColumn(outputColumn);
+      let reason = "computed-expression";
+      if (expr.kind === "relationColumn") reason = "relation-column";
+      else if (expr.kind === "aggregate") reason = "unsupported-aggregate";
+      addUntypedColumn(outputColumn, reason);
     }
   }
-  const outputSchema = { columns, directProjectionLineage };
-  return {
-    columns: outputSchema.columns,
-    relationFilters: getBindingRelationFilterMetadata(
-      intent,
-      ctx,
-      outputSchema,
-      bindingDependencies
-    )
-  };
+  return finalizeOutputSchema();
 }
 function validateNqlExpressionPaths(expr, ctx) {
   switch (expr.type) {
@@ -4165,78 +4246,33 @@ function stringArraysEqual(left, right) {
 function isNqlAstRecord(value) {
   return typeof value === "object" && value !== null;
 }
-function isExactPhysicalProjectionColumn(query, ctx, sourceColumn, outputColumn) {
-  const resolvedColumn = ctx.validator?.resolvePhysicalColumnName(
-    query.from,
-    sourceColumn
-  );
-  return resolvedColumn !== void 0 && sourceColumn === resolvedColumn && outputColumn === resolvedColumn;
-}
-function hasDirectPhysicalColumnProjection(query, ctx) {
-  const physicalColumns = ctx.validator?.getPhysicalTableColumns(query.from);
-  if (physicalColumns === void 0) return false;
-  const select = query.select;
-  if (!select || select.type === "all") return physicalColumns.length > 0;
-  let projectedColumnCount = 0;
-  const addStarProjection = () => {
-    projectedColumnCount += physicalColumns.length;
-    return physicalColumns.length > 0;
-  };
-  const addDirectProjection = (sourceColumn, outputColumn) => {
-    projectedColumnCount++;
-    return isExactPhysicalProjectionColumn(
-      query,
-      ctx,
-      sourceColumn,
-      outputColumn
-    );
-  };
-  if (select.type === "fields") {
-    for (const field of select.fields) {
-      if (field === "*") {
-        if (!addStarProjection()) return false;
-      } else if (!addDirectProjection(field, field)) {
-        return false;
-      }
-    }
-    return projectedColumnCount > 0;
-  }
-  if (select.type === "aggregate") return false;
-  for (const expr of select.columns) {
-    if (expr.kind === "column" && expr.column === "*") {
-      if (!addStarProjection()) return false;
-      continue;
-    }
-    if (expr.kind === "column") {
-      const outputColumn = expr.as ?? expr.column;
-      if (!addDirectProjection(expr.column, outputColumn)) return false;
-      continue;
-    }
-    if (expr.kind === "columnAlias") {
-      if (!addDirectProjection(expr.column, expr.alias)) return false;
-      continue;
-    }
-    return false;
+function classifyReadBindingSnapshotShape(query, ctx, sourceWasBinding, outputSchema) {
+  if (!sourceWasBinding && ctx.validator?.getPhysicalTableColumns(query.from) === void 0) {
+    return {
+      supported: false,
+      reason: `no physical model table source '${query.from}'`
+    };
   }
-  return projectedColumnCount > 0;
-}
-function classifyReadBindingSnapshotShape(query, ctx, sourceWasBinding) {
-  if (sourceWasBinding) {
-    return { supported: false, reason: "a binding source" };
+  if (outputSchema?.columnTypes) {
+    return { supported: true };
   }
-  if (ctx.validator?.getPhysicalTableColumns(query.from) === void 0) {
+  const untypeable = outputSchema?.columnTypesUnavailable;
+  if (untypeable?.reason === "unsupported-aggregate") {
     return {
       supported: false,
-      reason: `no physical model table source '${query.from}'`
+      reason: `aliased/computed/aggregate columns (unsupported aggregate column '${untypeable.column}')`
     };
   }
-  if (!hasDirectPhysicalColumnProjection(query, ctx)) {
+  if (untypeable) {
     return {
       supported: false,
-      reason: "aliased/computed/aggregate columns"
+      reason: `${untypeable.reason} column '${untypeable.column}'`
     };
   }
-  return { supported: true };
+  if (sourceWasBinding) {
+    return { supported: false, reason: "a binding source" };
+  }
+  return { supported: false, reason: "aliased/computed/aggregate columns" };
 }
 function addReadBindingReference(references, readBindingNames, name) {
   if (typeof name === "string" && readBindingNames.has(name)) {
@@ -4479,6 +4515,7 @@ var NqlCompiler = class {
     } finally {
       this.ctx.bindingOutputColumns.clear();
       this.ctx.bindingRelationFilters.clear();
+      this.ctx.lastMutationReturningItems = void 0;
       this.ctx.validator?.clearVirtualBindingTables();
     }
   }
@@ -4575,7 +4612,8 @@ var NqlCompiler = class {
             classifyReadBindingSnapshotShape(
               lastResult.query,
               this.ctx,
-              sourceWasBinding
+              sourceWasBinding,
+              outputSchema
             )
           );
           bindings.set(bindName, lastResult.query);
@@ -4665,7 +4703,12 @@ var NqlCompiler = class {
         query,
         this.ctx,
         bindName,
-        bindingDependencies
+        bindingDependencies,
+        // #213 B2: earlier bindings are already registered here (this
+        // map is populated in program-statement order), so a
+        // transitive `from` = binding chains through the SOURCE's
+        // typed schema instead of staying untypeable.
+        bindingOutputSchemas
       );
       bindingOutputSchemas.set(bindName, outputSchema);
       this.ctx.bindingOutputColumns.set(bindName, outputSchema.columns);
@@ -4705,20 +4748,50 @@ var NqlCompiler = class {
     const returning = mutation.returning;
     if (!returning || returning.length === 0) return void 0;
     if (returning.includes("*")) {
-      const columns = this.ctx.validator?.getTableColumns(mutation.table);
-      if (columns !== void 0) return { columns };
+      const columns2 = this.ctx.validator?.getTableColumns(mutation.table);
+      if (columns2 !== void 0) {
+        return {
+          columns: columns2,
+          ...this.buildMutationReturningColumnTypes(mutation.table, columns2)
+        };
+      }
       if (!this.ctx.validator) return void 0;
       throw new NqlSemanticException(
         NqlErrorCodes.SEM_INVALID_SYNTAX,
         `Cannot compute output schema for NQL binding '${bindName}' from mutation RETURNING * on '${mutation.table}' without a concrete table schema.`
       );
     }
+    const columns = returning.map(
+      (column) => this.ctx.validator?.resolveColumnName(mutation.table, column) ?? column
+    );
     return {
-      columns: returning.map(
-        (column) => this.ctx.validator?.resolveColumnName(mutation.table, column) ?? column
-      )
+      columns,
+      ...this.buildMutationReturningColumnTypes(mutation.table, columns)
     };
   }
+  /**
+   * Build `columnTypes`/`columnTypesUnavailable` for a mutation-RETURNING
+   * binding. #213 B2: detection consumes `ctx.lastMutationReturningItems`
+   * (alias-aware, positional) — NEVER the collapsed `columns` names — so an
+   * alias colliding with a real column (`returning email as name`) is
+   * flagged 'aliased-returning' rather than silently mistyped as the
+   * colliding column's type.
+   */
+  buildMutationReturningColumnTypes(table, columns) {
+    const items = this.ctx.lastMutationReturningItems;
+    const candidates = columns.map(
+      (column, index) => {
+        const item = items !== void 0 && items !== "star" ? items[index] : void 0;
+        if (item?.aliased) {
+          return { column, untypeable: "aliased-returning" };
+        }
+        const typeInfo = this.ctx.validator?.getTableColumnType(table, column);
+        return typeInfo !== void 0 ? { column, typed: typeInfo } : { column, untypeable: "unresolvable-source" };
+      }
+    );
+    const typesResult = buildBindingColumnTypes(columns, candidates);
+    return "columnTypes" in typesResult ? { columnTypes: typesResult.columnTypes } : { columnTypesUnavailable: typesResult.untypeable };
+  }
   compileSingleStatement(stmt, bindings) {
     if (stmt.type === "withQuery") {
       return compileWithQuery(stmt, this.ctx, this.fns);