@dbsp/nql 1.9.5 → 1.10.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ColumnType, CompiledNqlQuery } from '@dbsp/types';
+import { ColumnType, ColumnJsReadType, 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';
@@ -463,6 +463,7 @@ interface ColumnValidatorPseudoColumn {
 interface ColumnValidatorTableColumn {
     readonly name: string;
     readonly type?: ColumnType;
+    readonly js?: ColumnJsReadType;
     readonly originalDbType?: string;
     readonly originalDbTypeSchema?: string;
     readonly originalDbTypeSchemaScope?: 'target' | 'absolute';
@@ -529,6 +530,7 @@ declare class NqlCompiler {
     private registerQueryBindingOutputSchema;
     private canonicalizeMutationBinding;
     private getMutationBindingOutputSchema;
+    private buildMutationReturningDeclaredOutputs;
     /**
      * Build `columnTypes`/`columnTypesUnavailable` for a mutation-RETURNING
      * binding. #213 B2: detection consumes `ctx.lastMutationReturningItems`

package/dist/index.js

@@ -1,4 +1,4 @@
-import { NQL_INTERNAL_COMPILER_OPTIONS, explainUnsupportedNqlBindingIncludeHop, markNqlTrustedRelationFilter, createNqlBindingRef, isNqlBindingRef, getNqlBindingRefName } from '@dbsp/types/internal';
+import { NQL_INTERNAL_COMPILER_OPTIONS, explainUnsupportedNqlBindingIncludeHop, markNqlTrustedRelationFilter, getTrustedNqlRelationFilterFields, createNqlBindingRef, isNqlBindingRef, getNqlBindingRefName } from '@dbsp/types/internal';
 import { NQL_SELECT_AGGREGATE_FUNCTIONS, NQL_SELECT_VALUE_FUNCTIONS, NQL_SELECT_JSON_FUNCTIONS, NQL_SELECT_SCALAR_FUNCTIONS, toColumnList, isNqlSelectWindowFunctionAllowed, isRankingWindowFunction, isParamIntent } from '@dbsp/types';
 import { createToken, Lexer, CstParser } from 'chevrotain';
 
@@ -181,6 +181,12 @@ var ColumnValidator = class _ColumnValidator {
       }
     };
   }
+  getTableColumnJsReadType(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);
+    return columnInfo?.type === "bigint" ? columnInfo.js : void 0;
+  }
   getPseudoColumns(name) {
     return this.schema.getTable(name)?.pseudoColumns ?? [];
   }
@@ -1610,6 +1616,13 @@ function toSnakeCase(name) {
 function columnsMatch(left, right) {
   return left === right || toSnakeCase(left) === toSnakeCase(right);
 }
+var scalarOneShape = {
+  kind: "scalar",
+  cardinality: "one"
+};
+function unknownShape(reason) {
+  return { kind: "unknown", reason };
+}
 function expressionIntentContainsAggregate(value) {
   if (!value || typeof value !== "object") return false;
   const record = value;
@@ -2578,13 +2591,84 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
   const columns = [];
   const seen = /* @__PURE__ */ new Set();
   const directProjectionLineage = [];
+  const declaredOutputCandidates = /* @__PURE__ */ new Map();
   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 addDeclaredOutputCandidate = (outputKey, descriptor) => {
+    const candidates = declaredOutputCandidates.get(outputKey) ?? [];
+    candidates.push(descriptor);
+    declaredOutputCandidates.set(outputKey, candidates);
+  };
+  const unresolvedOutput = (outputKey, reason) => ({
+    outputKey,
+    source: { kind: "unresolved", reason },
+    shape: unknownShape(reason)
+  });
+  const modelColumnOutput = (outputKey, table, column, shape = scalarOneShape) => {
+    const js = ctx.validator?.getTableColumnJsReadType(table, column);
+    return {
+      outputKey,
+      source: {
+        kind: "modelColumn",
+        table,
+        column,
+        ...js !== void 0 ? { js } : {}
+      },
+      shape
+    };
+  };
+  const withOutputKey = (descriptor, outputKey) => ({
+    outputKey,
+    source: descriptor.source,
+    shape: descriptor.shape
+  });
+  const resolveDirectProjectionOutput = (outputKey, resolvedSourceColumn) => {
+    if (sourceIsPhysicalTable) {
+      return modelColumnOutput(outputKey, intent.from, resolvedSourceColumn);
+    }
+    const sourceDescriptors = sourceBindingSchema?.declaredOutputs?.filter(
+      (descriptor) => columnsMatch(descriptor.outputKey, resolvedSourceColumn)
+    );
+    if (sourceDescriptors?.length === 1) {
+      const [descriptor] = sourceDescriptors;
+      if (descriptor !== void 0) return withOutputKey(descriptor, outputKey);
+    }
+    return unresolvedOutput(
+      outputKey,
+      `binding output '${outputKey}' did not resolve to a declared source column`
+    );
+  };
+  const resolvePhysicalRelationColumnOutput = (outputKey, expr) => {
+    if (!sourceIsPhysicalTable || !ctx.validator) return void 0;
+    const relationPath = expr.relation.split(".");
+    if (relationPath.length === 0 || relationPath.some((part) => part === "")) {
+      return void 0;
+    }
+    let targetTable = intent.from;
+    for (const relationName of relationPath) {
+      const relation = ctx.validator.getRelation(targetTable, relationName);
+      if (relation === void 0) return void 0;
+      if (relation.type !== "belongsTo" && relation.type !== "hasOne" || relation.recursive !== void 0) {
+        return void 0;
+      }
+      targetTable = relation.target;
+    }
+    const resolvedColumn = ctx.validator.resolvePhysicalColumnName(
+      targetTable,
+      expr.column
+    );
+    if (resolvedColumn === void 0) return void 0;
+    return modelColumnOutput(outputKey, targetTable, resolvedColumn);
+  };
   const addDirectProjection = (outputColumn, sourceColumn) => {
     const resolvedSourceColumn = resolveSourceColumn(sourceColumn);
+    addDeclaredOutputCandidate(
+      outputColumn,
+      resolveDirectProjectionOutput(outputColumn, resolvedSourceColumn)
+    );
     let typeInfo;
     let untypeableReason = "unresolvable-source";
     if (sourceIsPhysicalTable) {
@@ -2609,10 +2693,51 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
     });
   };
   const addUntypedColumn = (outputColumn, reason) => {
+    addDeclaredOutputCandidate(
+      outputColumn,
+      unresolvedOutput(
+        outputColumn,
+        `binding output '${outputColumn}' has no proven scalar model column source (${reason})`
+      )
+    );
     typeCandidates.push({ column: outputColumn, untypeable: reason });
     addColumn(outputColumn);
   };
+  const addRelationColumn = (outputColumn, expr) => {
+    const trusted = getTrustedNqlRelationFilterFields(expr);
+    const targetTable = trusted?.hops.at(-1)?.target ?? trusted?.targetTable;
+    const isScalarRelationColumn = trusted?.selectedColumn !== void 0 && trusted.cardinality === "one" && trusted.recursive === void 0 && (trusted.relationType === "belongsTo" || trusted.relationType === "hasOne");
+    const descriptor = targetTable !== void 0 && isScalarRelationColumn ? modelColumnOutput(outputColumn, targetTable, trusted.selectedColumn) : trusted !== void 0 ? targetTable !== void 0 && trusted.selectedColumn !== void 0 ? modelColumnOutput(
+      outputColumn,
+      targetTable,
+      trusted.selectedColumn,
+      {
+        kind: "array",
+        cardinality: "many"
+      }
+    ) : void 0 : expr.kind === "relationColumn" ? resolvePhysicalRelationColumnOutput(outputColumn, expr) : void 0;
+    addDeclaredOutputCandidate(
+      outputColumn,
+      descriptor ?? unresolvedOutput(
+        outputColumn,
+        `relation output '${outputColumn}' has no proven scalar model column source`
+      )
+    );
+    typeCandidates.push({
+      column: outputColumn,
+      untypeable: "relation-column"
+    });
+    addColumn(outputColumn);
+  };
   const addCountAggregateColumn = (outputColumn) => {
+    addDeclaredOutputCandidate(outputColumn, {
+      outputKey: outputColumn,
+      source: {
+        kind: "expression",
+        reason: `aggregate output '${outputColumn}' has no scalar model column source`
+      },
+      shape: { kind: "aggregate-scalar", aggregate: "count" }
+    });
     typeCandidates.push({
       column: outputColumn,
       typed: { kind: "aggregate", fn: "count" }
@@ -2627,8 +2752,22 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
   const finalizeOutputSchema = () => {
     const outputSchema = { columns, directProjectionLineage };
     const typesResult = buildBindingColumnTypes(columns, typeCandidates);
+    const declaredOutputs = columns.map((column) => {
+      const candidates = declaredOutputCandidates.get(column) ?? [];
+      if (candidates.length !== 1) {
+        return unresolvedOutput(
+          column,
+          `binding output '${column}' has ambiguous declared output sources`
+        );
+      }
+      return candidates[0] ?? unresolvedOutput(
+        column,
+        `binding output '${column}' has no declared output source`
+      );
+    });
     return {
       columns: outputSchema.columns,
+      declaredOutputs,
       relationFilters: getBindingRelationFilterMetadata(
         intent,
         ctx,
@@ -2696,10 +2835,11 @@ function getQueryOutputSchema(intent, ctx, bindingName, bindingDependencies = []
       addDirectProjection(outputColumn, expr.column);
     } else if (expr.kind === "aggregate" && expr.function === "count") {
       addCountAggregateColumn(outputColumn);
+    } else if (expr.kind === "relationColumn") {
+      addRelationColumn(outputColumn, expr);
     } else {
       let reason = "computed-expression";
-      if (expr.kind === "relationColumn") reason = "relation-column";
-      else if (expr.kind === "aggregate") reason = "unsupported-aggregate";
+      if (expr.kind === "aggregate") reason = "unsupported-aggregate";
       addUntypedColumn(outputColumn, reason);
     }
   }
@@ -4838,6 +4978,10 @@ var NqlCompiler = class {
       if (columns2 !== void 0) {
         return {
           columns: columns2,
+          declaredOutputs: this.buildMutationReturningDeclaredOutputs(
+            mutation.table,
+            columns2
+          ),
           ...this.buildMutationReturningColumnTypes(mutation.table, columns2)
         };
       }
@@ -4859,14 +5003,43 @@ var NqlCompiler = class {
       });
       return {
         columns: columns2,
+        declaredOutputs: this.buildMutationReturningDeclaredOutputs(
+          mutation.table,
+          columns2
+        ),
         ...this.buildMutationReturningColumnTypes(mutation.table, columns2)
       };
     }
     return {
       columns,
+      declaredOutputs: this.buildMutationReturningDeclaredOutputs(
+        mutation.table,
+        columns
+      ),
       ...this.buildMutationReturningColumnTypes(mutation.table, columns)
     };
   }
+  buildMutationReturningDeclaredOutputs(table, columns) {
+    const items = this.ctx.lastMutationReturningItems;
+    return columns.map((column, index) => {
+      const item = items !== void 0 && items !== "star" ? items[index] : void 0;
+      const sourceColumn = item !== void 0 ? this.ctx.validator?.resolveColumnName(table, item.source) ?? item.source : column;
+      const js = this.ctx.validator?.getTableColumnJsReadType(
+        table,
+        sourceColumn
+      );
+      return {
+        outputKey: column,
+        source: {
+          kind: "modelColumn",
+          table,
+          column: sourceColumn,
+          ...js !== void 0 && { js }
+        },
+        shape: { kind: "scalar", cardinality: "one" }
+      };
+    });
+  }
   /**
    * Build `columnTypes`/`columnTypesUnavailable` for a mutation-RETURNING
    * binding. #213 B2: detection consumes `ctx.lastMutationReturningItems`