@dbsp/nql 1.6.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';
@@ -402,21 +402,73 @@ interface NqlAssignment {
     value: NqlExpression;
 }
 
+/**
+ * NQL Error Types
+ *
+ * Structured error types for lexer, parser, and semantic errors.
+ */
+/** Source location for error reporting */
+interface SourceLocation {
+    line: number;
+    column: number;
+    offset: number;
+}
+/** Base error interface for all NQL errors */
+interface NqlError {
+    code: string;
+    message: string;
+    location?: SourceLocation | undefined;
+    suggestion?: string | undefined;
+}
+/** Parser errors (syntax errors) */
+interface NqlParseError extends NqlError {
+    code: `ERR-PARSE-${string}`;
+    expected?: string[] | undefined;
+    found?: string | undefined;
+}
+/** Semantic errors (validation failures) */
+interface NqlSemanticError extends NqlError {
+    code: `ERR-SEM-${string}`;
+    relatedSymbol?: string | undefined;
+}
+/** Warning (non-fatal issues) */
+interface NqlWarning {
+    code: string;
+    message: string;
+    location?: SourceLocation | undefined;
+    suggestion?: string | undefined;
+}
+
 type CompileResult = CompiledNqlQuery;
 
 /**
  * Duck-type interface for schema-based column validation.
  * Loose coupling: ModelIR from @dbsp/core satisfies this shape without direct import.
  */
+interface ColumnValidatorPseudoColumn {
+    readonly table?: string;
+    readonly foreignKeyColumn?: string;
+    readonly targetColumn?: string;
+    readonly parentRole: string;
+    readonly childRole: string;
+    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 pseudoColumns?: readonly {
-            readonly parentRole: string;
-            readonly childRole: string;
-        }[];
+        readonly columns: readonly ColumnValidatorTableColumn[];
+        readonly pseudoColumns?: readonly ColumnValidatorPseudoColumn[];
     } | undefined;
     getRelationsFrom(sourceTable: string): readonly ColumnValidatorRelation[];
     getRelation?(qualifiedName: string): ColumnValidatorRelation | undefined;
@@ -428,7 +480,7 @@ interface ColumnValidatorRelation {
     readonly type?: 'hasOne' | 'hasMany' | 'belongsTo' | 'belongsToMany';
     readonly foreignKey?: string | readonly string[] | undefined;
     readonly through?: string | undefined;
-    readonly otherKey?: string | undefined;
+    readonly otherKey?: string | readonly string[] | undefined;
     readonly throughSourceKey?: string | undefined;
     readonly throughTargetKey?: string | undefined;
     readonly recursive?: unknown;
@@ -475,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;
 }
 /**
@@ -482,43 +543,6 @@ declare class NqlCompiler {
  */
 declare function createCompiler(options?: NqlCompilerOptions, schema?: ColumnValidatorSchema): NqlCompiler;
 
-/**
- * NQL Error Types
- *
- * Structured error types for lexer, parser, and semantic errors.
- */
-/** Source location for error reporting */
-interface SourceLocation {
-    line: number;
-    column: number;
-    offset: number;
-}
-/** Base error interface for all NQL errors */
-interface NqlError {
-    code: string;
-    message: string;
-    location?: SourceLocation | undefined;
-    suggestion?: string | undefined;
-}
-/** Parser errors (syntax errors) */
-interface NqlParseError extends NqlError {
-    code: `ERR-PARSE-${string}`;
-    expected?: string[] | undefined;
-    found?: string | undefined;
-}
-/** Semantic errors (validation failures) */
-interface NqlSemanticError extends NqlError {
-    code: `ERR-SEM-${string}`;
-    relatedSymbol?: string | undefined;
-}
-/** Warning (non-fatal issues) */
-interface NqlWarning {
-    code: string;
-    message: string;
-    location?: SourceLocation | undefined;
-    suggestion?: string | undefined;
-}
-
 declare const allTokens: chevrotain.TokenType[];
 declare const NqlLexer: Lexer;