@dbsp/nql 1.1.0 → 1.2.0

package/README.md

@@ -15,16 +15,22 @@ pnpm add @dbsp/nql
 
 ```typescript
 // doctest: skip — exec-only operation; compile from @dbsp/nql is not in doctest preamble and orm.from(intent).all() requires a real PostgreSQL connection
+import { createPgsqlCompileOnlyAdapter } from '@dbsp/adapter-pgsql';
 import { compile } from '@dbsp/nql';
 
-// Compile an NQL query to IntentAST
-const intent = compile(
+// Compile an NQL query to a public intent bundle
+const compiled = compile(
   "users | where active = true | select name, email | order name asc | limit 20",
-  schema
+  db.model
 );
 
-// Pass the intent to the ORM
-const users = await orm.from(intent).all();
+if (!compiled.success || !compiled.ast?.query) {
+  throw new Error(compiled.errors.map((e) => e.message).join(', '));
+}
+
+// Pass the whole bundle to the adapter; bound params are explicit public IR nodes
+const adapter = createPgsqlCompileOnlyAdapter();
+const query = adapter.compile(compiled.ast, { model: db.model });
 ```
 
 ## Syntax overview
@@ -51,12 +57,39 @@ orders | group customerId | select customerId, sum(total) as revenue
 
 - **Pipe syntax** — Readable left-to-right data flow (`table | filter | select | order`)
 - **SQL-style literals** — Single-quoted strings (`'value'`), not double-quoted
+- **Named parameters** — Bind runtime values with `:name` in expression positions
 - **CTE support** — `WITH name AS (subquery)` for named subqueries
 - **Schema-aware** — Validates column names and relation paths against `ModelIR` at parse time
 - **LLM-friendly** — Concise syntax designed for AI-generated queries
 - **Chevrotain-based** — Robust lexer + parser with structured error recovery
 - **Composable** — Output `IntentAST` is the same type used by the TypeScript fluent builders
 
+## Named parameters
+
+Use `:name` placeholders for runtime values and pass a `params` map to the compiler:
+
+```typescript
+// doctest: skip — illustrative direct compiler params example
+import { createPgsqlCompileOnlyAdapter } from '@dbsp/adapter-pgsql';
+import { compile } from '@dbsp/nql';
+
+const compiled = compile(
+  'users | where id = :id and active = :active | limit :limit',
+  db.model,
+  undefined,
+  { params: { id: 42, active: true, limit: 10 } },
+);
+
+if (!compiled.success || !compiled.ast?.query) {
+  throw new Error(compiled.errors.map((e) => e.message).join(', '));
+}
+
+const adapter = createPgsqlCompileOnlyAdapter();
+const query = adapter.compile(compiled.ast, { model: db.model });
+```
+
+Missing params fail compilation. `null` binds SQL `NULL`; `undefined`, `NaN`, and `Infinity` are rejected. The `@dbsp/core` `orm.nql` template tag builds on the same mechanism for `${value}` interpolation. See [Named Parameters and Template Binding](https://oorabona.github.io/db-semantic-planner/nql/#named-parameters-and-template-binding) for the full contract.
+
 ## Documentation
 
 - [Guides](https://oorabona.github.io/db-semantic-planner/guide/)

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { QueryIntent, CteQueryIntent, MutationIntent, SetOperationIntent } from '@dbsp/types';
-export { 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 { 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';
 
@@ -71,13 +71,14 @@ interface NqlOrderByClause {
 }
 interface NqlLimitClause {
     type: 'limit';
-    count: number;
+    count: NqlLimitCount;
     relation?: string;
 }
 interface NqlOffsetClause {
     type: 'offset';
-    count: number;
+    count: NqlLimitCount;
 }
+type NqlLimitCount = number | NqlNamedParamExpr;
 /**
  * Capture mutation result into a variable (for chained mutations)
  * Used with `bind` keyword: `insert ... | bind result | ...`
@@ -135,7 +136,7 @@ interface NqlOrderItem {
     expression: NqlExpression;
     direction: 'asc' | 'desc';
 }
-type NqlExpression = NqlBinaryExpression | NqlUnaryExpression | NqlComparisonExpression | NqlRangeOpExpression | NqlInExpression | NqlAnyExpression | NqlBetweenExpression | NqlIsNullExpression | NqlExistsExpression | NqlRelationFilterExpression | NqlFunctionCall | NqlWindowExpression | NqlCaseExpression | NqlPathExpression | NqlJsonAccessExpression | NqlJsonComparisonExpression | NqlLiteral | NqlSubquery | NqlVariableRef;
+type NqlExpression = NqlBinaryExpression | NqlUnaryExpression | NqlComparisonExpression | NqlRangeOpExpression | NqlInExpression | NqlAnyExpression | NqlBetweenExpression | NqlIsNullExpression | NqlExistsExpression | NqlRelationFilterExpression | NqlFunctionCall | NqlWindowExpression | NqlCaseExpression | NqlPathExpression | NqlJsonAccessExpression | NqlJsonComparisonExpression | NqlLiteral | NqlSubquery | NqlVariableRef | NqlNamedParamExpr;
 interface NqlBinaryExpression {
     type: 'binary';
     operator: 'and' | 'or' | '+' | '-' | '*' | '/' | '%';
@@ -162,7 +163,7 @@ interface NqlRangeOpExpression {
     operator: 'overlaps' | 'contains' | 'containedBy';
     left: NqlExpression;
     range?: NqlRangeLiteral;
-    scalar?: NqlLiteral;
+    scalar?: NqlLiteral | NqlNamedParamExpr;
 }
 interface NqlInExpression {
     type: 'in';
@@ -297,6 +298,15 @@ interface NqlVariableRef {
     type: 'variable';
     name: string;
 }
+/**
+ * Bound parameter reference (e.g. `:tenantId`).
+ * The leading colon is not part of `name`; compiler resolution uses
+ * `CompilerContext.params`.
+ */
+interface NqlNamedParamExpr {
+    type: 'namedParam';
+    name: string;
+}
 type NqlLiteral = NqlStringLiteral | NqlNumberLiteral | NqlBooleanLiteral | NqlNullLiteral | NqlDateRangeLiteral | NqlRangeLiteral;
 interface NqlStringLiteral {
     type: 'string';
@@ -354,7 +364,7 @@ interface NqlInsertFrom {
     /** WHERE clause to filter source rows */
     where?: NqlExpression | undefined;
     /** LIMIT clause to restrict rows */
-    limit?: number | undefined;
+    limit?: NqlLimitCount | undefined;
 }
 interface NqlUpdate {
     type: 'update';
@@ -385,31 +395,15 @@ interface NqlUpsertFrom {
     source: string;
     columns?: string[] | undefined;
     where?: NqlExpression | undefined;
-    limit?: number | undefined;
+    limit?: NqlLimitCount | undefined;
 }
 interface NqlAssignment {
     column: string;
     value: NqlExpression;
 }
 
-interface CompileResult {
-    readonly query?: QueryIntent;
-    /** CTE query (WITH clause): wraps outer QueryIntent in CteQueryIntent */
-    readonly cteQuery?: CteQueryIntent;
-    readonly mutation?: MutationIntent;
-    readonly returning?: readonly string[];
-    /** Named bindings from `| bind X` clauses (CTE source queries) */
-    readonly bindings?: ReadonlyMap<string, QueryIntent>;
-    /**
-     * Named mutation bindings from `mutation | select cols | bind X` clauses.
-     * When a mutation has RETURNING and is bound, the original MutationIntent is stored here
-     * so the adapter can compile it as a CTE: `WITH X AS (INSERT ... RETURNING cols) ...`
-     * The corresponding synthetic QueryIntent is also stored in `bindings` for reference resolution.
-     */
-    readonly mutationBindings?: ReadonlyMap<string, MutationIntent>;
-    /** Set operation (UNION/INTERSECT/EXCEPT) wrapping two queries */
-    readonly setOperation?: SetOperationIntent;
-}
+type CompileResult = CompiledNqlQuery;
+
 /**
  * Duck-type interface for schema-based column validation.
  * Loose coupling: ModelIR from @dbsp/core satisfies this shape without direct import.
@@ -512,6 +506,11 @@ interface NqlWarning {
 declare const allTokens: chevrotain.TokenType[];
 declare const NqlLexer: Lexer;
 
+/**
+ * Tokenize NQL source with the public lexer.
+ */
+declare function tokenize(input: string): ReturnType<typeof NqlLexer.tokenize>;
+
 /**
  * NQL Parser using Chevrotain CstParser
  */
@@ -580,13 +579,23 @@ declare class NqlParser extends CstParser {
      */
     private orderClause;
     /**
-     * limit_clause = "limit" [ident_segment ("." ident_segment)*] NUMBER ;
+     * limit_clause = "limit" [ident_segment ("." ident_segment)*] (NUMBER | NAMED_PARAM) ;
      */
     private limitClause;
     /**
-     * offset_clause = "offset" NUMBER ;
+     * offset_clause = "offset" (NUMBER | NAMED_PARAM) ;
      */
     private offsetClause;
+    /**
+     * numeric_value_atom = NUMBER | NAMED_PARAM ;
+     *
+     * Structural-position durability rule: value positions that consume scalar
+     * values may add `NamedParam` here and validate the resolved value in the
+     * compiler. Structural positions such as identifiers, directions, lock modes,
+     * and traversal depth hints must not consume this helper; use nqlRaw()/builder
+     * APIs for trusted dynamic structure.
+     */
+    private numericValueAtom;
     /**
      * lock_clause = lock_strength [ lock_wait_policy ] ;
      * lock_strength = "for update" | "for share" | "for no key update" | "for key share" ;
@@ -664,7 +673,7 @@ declare class NqlParser extends CstParser {
      */
     private rangeOp;
     /**
-     * range_op_suffix = range_op (range_literal | literal) ;
+     * range_op_suffix = range_op (range_literal | literal | named_param_expr) ;
      * Example: overlaps [1,10) or contains (0,100) or contains 25
      * Note: contains can take a scalar value (e.g., contains 25 checks if range contains the value)
      */
@@ -747,9 +756,13 @@ declare class NqlParser extends CstParser {
      */
     private jsonAccessExpr;
     /**
-     * primary_expr = literal | case_expr | path_expr | func_call | "(" expr ")" | "(" scalar_subquery ")" ;
+     * primary_expr = named_param_expr | literal | case_expr | path_expr | func_call | "(" expr ")" | "(" scalar_subquery ")" ;
      */
     private primaryExpr;
+    /**
+     * named_param_expr = NAMED_PARAM ;
+     */
+    private namedParamExpr;
     /**
      * Check if at start of scalar subquery (ident | ...)
      */
@@ -866,7 +879,7 @@ declare class NqlParser extends CstParser {
      */
     private insertStmt;
     /**
-     * insert_from_stmt = "insert" "into" ident_segment "from" ident_segment [ "where" boolean_expr ] [ "limit" number ] ;
+     * insert_from_stmt = "insert" "into" ident_segment "from" ident_segment [ "where" boolean_expr ] [ "limit" numeric_value_atom ] ;
      * @example insert into archived_users from users where active = false limit 100
      */
     private insertFromStmt;
@@ -885,7 +898,7 @@ declare class NqlParser extends CstParser {
      */
     private upsertStmt;
     /**
-     * upsert_from_stmt = "upsert" "into" ident_segment "on" ( "(" ident_list ")" | ident_segment ) "from" ident_segment [ "where" boolean_expr ] [ "limit" number ] ;
+     * upsert_from_stmt = "upsert" "into" ident_segment "on" ( "(" ident_list ")" | ident_segment ) "from" ident_segment [ "where" boolean_expr ] [ "limit" numeric_value_atom ] ;
      * @example upsert into authors on id from counts
      * @example upsert into authors on (id, email) from counts where active = true
      */
@@ -956,6 +969,7 @@ declare class NqlCstVisitor extends BaseCstVisitor {
     orderClause(ctx: CstContext): NqlClause;
     limitClause(ctx: CstContext): NqlClause;
     offsetClause(ctx: CstContext): NqlClause;
+    numericValueAtom(ctx: CstContext): NqlLimitCount;
     selectList(ctx: CstContext): NqlSelectItem[];
     selectItem(ctx: CstContext): NqlSelectItem;
     relationStarExpr(ctx: CstContext): NqlSelectItem;
@@ -982,6 +996,7 @@ declare class NqlCstVisitor extends BaseCstVisitor {
     unaryExpr(ctx: CstContext): NqlExpression;
     jsonAccessExpr(ctx: CstContext): NqlExpression;
     primaryExpr(ctx: CstContext): NqlExpression;
+    namedParamExpr(ctx: CstContext): NqlNamedParamExpr;
     caseExpr(ctx: CstContext): NqlCaseExpression;
     searchedCaseBody(_ctx: CstContext): void;
     simpleCaseBody(_ctx: CstContext): void;
@@ -1056,4 +1071,4 @@ declare function parse(input: string, _options?: ParseOptions): ParseResult<NqlP
 declare function compile(input: string, schema: unknown, // ModelIR from @dbsp/core — satisfies ColumnValidatorSchema
 options?: ParseOptions, compilerOptions?: NqlCompilerOptions): ParseResult<CompileResult>;
 
-export { type ColumnValidatorSchema, type CompileResult, type NqlAnyExpression, type NqlAssignment, type NqlBetweenExpression, type NqlBinaryExpression, type NqlBindClause, type NqlBooleanLiteral, type NqlCaseExpression, type NqlClause, type NqlComparisonExpression, NqlCompiler, type NqlCompilerOptions, NqlCstVisitor, type NqlCteItem, type NqlDateRangeLiteral, type NqlDelete, type NqlError, type NqlExistsExpression, type NqlExpression, type NqlFlatClause, type NqlFunctionCall, type NqlGroupByClause, type NqlInExpression, type NqlInsert, type NqlInsertFrom, type NqlIsNullExpression, type NqlJoinParam, type NqlJoinSpec, type NqlJsonAccessExpression, type NqlJsonComparisonExpression, NqlLexer, type NqlLimitClause, type NqlLiteral, type NqlLockClause, type NqlMutation, type NqlMutationClause, type NqlMutationPipeline, type NqlNullLiteral, type NqlNumberLiteral, type NqlOffsetClause, type NqlOrderByClause, type NqlOrderItem, type NqlParseError, NqlParser, type NqlPathExpression, type NqlProgram, type NqlQuery, type NqlRangeLiteral, type NqlRangeOpExpression, type NqlRelationFilterExpression, type NqlSelectClause, type NqlSelectExpression, type NqlSelectItem, type NqlSelectRelationStar, type NqlSelectStar, type NqlSemanticError, type NqlSetClause, type NqlStatement, type NqlStringLiteral, type NqlSubquery, type NqlUnaryExpression, type NqlUpdate, type NqlUpsert, type NqlUpsertFrom, type NqlVariableRef, type NqlWarning, type NqlWhereClause, type NqlWindowExpression, type NqlWithQuery, type ParseOptions, type ParseResult, allTokens, compile, createCompiler, cstToAst, nqlVisitor, parse, parseCst };
+export { type ColumnValidatorSchema, type CompileResult, type NqlAnyExpression, type NqlAssignment, type NqlBetweenExpression, type NqlBinaryExpression, type NqlBindClause, type NqlBooleanLiteral, type NqlCaseExpression, type NqlClause, type NqlComparisonExpression, NqlCompiler, type NqlCompilerOptions, NqlCstVisitor, type NqlCteItem, type NqlDateRangeLiteral, type NqlDelete, type NqlError, type NqlExistsExpression, type NqlExpression, type NqlFlatClause, type NqlFunctionCall, type NqlGroupByClause, type NqlInExpression, type NqlInsert, type NqlInsertFrom, type NqlIsNullExpression, type NqlJoinParam, type NqlJoinSpec, type NqlJsonAccessExpression, type NqlJsonComparisonExpression, NqlLexer, type NqlLimitClause, type NqlLimitCount, type NqlLiteral, type NqlLockClause, type NqlMutation, type NqlMutationClause, type NqlMutationPipeline, type NqlNamedParamExpr, type NqlNullLiteral, type NqlNumberLiteral, type NqlOffsetClause, type NqlOrderByClause, type NqlOrderItem, type NqlParseError, NqlParser, type NqlPathExpression, type NqlProgram, type NqlQuery, type NqlRangeLiteral, type NqlRangeOpExpression, type NqlRelationFilterExpression, type NqlSelectClause, type NqlSelectExpression, type NqlSelectItem, type NqlSelectRelationStar, type NqlSelectStar, type NqlSemanticError, type NqlSetClause, type NqlStatement, type NqlStringLiteral, type NqlSubquery, type NqlUnaryExpression, type NqlUpdate, type NqlUpsert, type NqlUpsertFrom, type NqlVariableRef, type NqlWarning, type NqlWhereClause, type NqlWindowExpression, type NqlWithQuery, type ParseOptions, type ParseResult, allTokens, compile, createCompiler, cstToAst, nqlVisitor, parse, parseCst, tokenize };