@dbsp/adapter-pgsql 1.1.1 → 1.2.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ExpressionRef, IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ModelIR as ModelIR$1 } from '@dbsp/core';
 export { normalizeSQL } from '@dbsp/core';
 import * as _dbsp_types from '@dbsp/types';
-import { DialectCapabilities, ModelIR, DbCasing, ColumnIR, HierarchyIR, Adapter, AdapterLogger, AdapterCapabilities, PlanReport, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, CompileOnlyAdapter, QueryIntent } from '@dbsp/types';
+import { ParamIntent, DialectCapabilities, ModelIR, DbCasing, ColumnIR, HierarchyIR, Adapter, AdapterLogger, AdapterCapabilities, PlanReport, CompiledNqlQuery, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, CompileOnlyAdapter, QueryIntent } from '@dbsp/types';
 import * as _pgsql_types from '@pgsql/types';
 import { Node, OnConflictClause, ParamRef } from '@pgsql/types';
 import { Pool, PoolClient } from 'pg';
@@ -117,10 +117,10 @@ interface PlanDecision {
         column: string;
         value: unknown;
     }[];
-    readonly limit?: number | {
+    readonly limit?: number | ParamIntent | {
         paramIndex: number;
     };
-    readonly offset?: number | {
+    readonly offset?: number | ParamIntent | {
         paramIndex: number;
     };
     readonly partitionBy?: readonly string[];
@@ -131,6 +131,8 @@ interface PlanDecision {
     readonly dataType?: string;
     readonly sourceTable?: string;
     readonly relationName?: string;
+    readonly relationPath?: string;
+    readonly hydrationPrefix?: string;
     readonly relationType?: 'belongsTo' | 'hasMany' | 'hasOne';
     readonly foreignKey?: string;
     readonly parentKey?: string;
@@ -141,7 +143,7 @@ interface PlanDecision {
         readonly from: string;
         readonly select: string;
         readonly where?: PlanDecision;
-        readonly limit?: number;
+        readonly limit?: number | ParamIntent;
         readonly orderBy?: readonly {
             field: string;
             direction?: string;
@@ -273,19 +275,23 @@ declare class PlanCompiler {
     /** CTE nodes from include handlers (e.g., CTE strategy) */
     private pendingCtes;
     /**
-     * Maps joined targetTable → alias for multi-hop FK resolution.
-     * Populated as join decisions are compiled so later hops can find
-     * the correct source alias (e.g., 'symbols' → 'callee').
+     * Maps relation-dotted include path → JOIN alias for multi-hop FK resolution.
+     * Populated as join decisions are compiled so later hops can find the
+     * correct source alias (e.g., 'callee.file' reads parent path 'callee').
      */
     private joinAliasMap;
     /**
      * Tracks all join aliases in use for the current query.
+     * Entries are stored in emitted database-alias space, after naming.toDatabase().
      * Ensures no two JOINs share the same alias (DOUBLE-ALIAS prevention).
      */
     private usedJoinAliases;
     constructor(options?: CompilerOptions);
     /** Build immutable context for handler-based WHERE compilation */
     private handlerCtx;
+    private findAliasForLegacySourceTable;
+    private emittedJoinAlias;
+    private resolvedJoinAliases;
     /**
      * Dispatch a PlanDecision through the unified WHERE handler system.
      * Bridges PlanCompiler's state to handler types, calls dispatcher, syncs back.
@@ -324,6 +330,10 @@ declare class PlanCompiler {
     private createHandlerContext;
     /** Build a fresh HandlerCompilerState sharing the current parameter array. */
     private createHandlerState;
+    private compileExpressionSubquery;
+    private compileGenericNqlFunction;
+    private compileNqlFunctionArg;
+    private compileNqlCaseExpressionArg;
     /**
      * Compile a SELECT-list target via expression handler.
      * Wraps the node in a ResTarget and pushes it onto targetList.
@@ -333,7 +343,9 @@ declare class PlanCompiler {
      * Compile an includeStrategy decision and register its results.
      * Pushes targets onto targetList, raw joins / CTEs onto instance collections.
      */
+    private registerIncludeCompilationResult;
     private compileIncludeDecision;
+    private compileJoinIncludeAllocationPass;
     /**
      * Fold a WHERE-family decision into an existing where expression.
      * Returns the updated (or new) where node.
@@ -355,6 +367,7 @@ declare class PlanCompiler {
      * column refs like `project_id` resolve against the joined table, not root.
      */
     private compileIncludeWhereConditions;
+    private reserveManualJoinAliases;
     /**
      * Apply a single join decision to the FROM clause in-place.
      * Chains multiple joins by wrapping from[0] as the left-arg each time.
@@ -1035,6 +1048,8 @@ interface CompilerContext {
     readonly rootTable: string;
     /** Current table alias (for JOINs) */
     readonly currentAlias?: string;
+    /** Final relation path/name → SQL join alias map for relation-aware expression contexts */
+    readonly aliases?: ReadonlyMap<string, string>;
     /** Maximum recursive depth (default: 100) */
     readonly maxRecursiveDepth: number;
     /** Optional callback for raw SQL audit trail */
@@ -1058,6 +1073,12 @@ interface CompilerContext {
         ast: Node;
         parameters: readonly unknown[];
     };
+    /**
+     * Optional recursive compiler for NQL-origin SELECT expression values nested
+     * inside handler arguments, such as coalesce(upper(name), :fallback) or
+     * (price + :a) * :b.
+     */
+    readonly compileNqlSelectExpression?: (value: unknown, ctx: CompilerContext, state: CompilerState) => Node;
     /**
      * Optional ModelIR for type-aware parameter casting.
      * When provided, WHERE comparisons emit `$N::type` to eliminate
@@ -1107,15 +1128,17 @@ interface Decision {
         column: string;
         value: unknown;
     }[];
-    readonly limit?: number | {
+    readonly limit?: number | ParamIntent | {
         paramIndex: number;
     };
-    readonly offset?: number | {
+    readonly offset?: number | ParamIntent | {
         paramIndex: number;
     };
     readonly strategy?: 'join' | 'lateral' | 'json_agg' | 'cte';
     readonly relation?: string;
     readonly relationName?: string;
+    readonly relationPath?: string;
+    readonly hydrationPrefix?: string;
     readonly include?: readonly Decision[];
     readonly relationType?: 'belongsTo' | 'hasMany' | 'hasOne';
     readonly foreignKey?: string;
@@ -1144,7 +1167,7 @@ interface Decision {
     readonly expandRelation?: string;
     readonly relationColumns?: readonly string[];
     readonly columnAliases?: Readonly<Record<string, string>>;
-    readonly jsonPath?: readonly string[];
+    readonly jsonPath?: readonly unknown[];
     readonly jsonMode?: 'json' | 'text';
     readonly _compiledFilterWhere?: _pgsql_types.Node;
     readonly filterWhere?: _pgsql_types.Node;
@@ -1190,6 +1213,13 @@ type WhereDispatcher = (decision: Decision, ctx: CompilerContext, state: Compile
 interface ExpressionHandler {
     /** Expression type(s) this handler supports */
     readonly types: readonly string[];
+    /**
+     * Safe to use when a function name comes from NQL text.
+     *
+     * Raw/escape-hatch handlers must not set this. NQL-origin function names use
+     * this opt-in surface only, then fall back to generic FuncCall emission.
+     */
+    readonly nqlSafe?: boolean;
     /**
      * Compile an expression to AST.
      * @param decision The expression decision
@@ -1585,6 +1615,10 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      */
     private cloneOptions;
     private buildCompileDeps;
+    private requireNqlCompileModel;
+    private compileNqlMutation;
+    private compileNqlBundleLeaf;
+    private compileNqlBundle;
     /**
      * Returns the pool/client executor, or throws if in compile-only mode.
      */
@@ -1604,7 +1638,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     /**
      * Compile a plan to executable SQL.
      */
-    compile<T = unknown>(plan: PlanReport, options?: CompileOptions): CompiledQuery<T>;
+    compile<T = unknown>(plan: PlanReport | CompiledNqlQuery, options?: CompileOptions): CompiledQuery<T>;
     /**
      * Compile a plan with includes, returning subquery include metadata (DX-033).
      */
@@ -1685,7 +1719,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     /**
      * Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL.
      */
-    compileSetOperation(intent: SetOperationIntent, model: ModelIR, _options?: CompileOptions): CompiledQuery;
+    compileSetOperation(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery;
     /**
      * Create a dump for observability.
      */
@@ -1964,7 +1998,7 @@ declare function compileSetOperation(intent: SetOperationIntent, compileFn: Leaf
  * @param planFn - The plan() function from @dbsp/core
  */
 declare function createLeafCompileFn(adapter: {
-    compile(plan: PlanReport, options: {
+    compile(plan: PlanReport, options: CompileOptions & {
         model: ModelIR$1;
     }): {
         sql: string;
@@ -1973,7 +2007,7 @@ declare function createLeafCompileFn(adapter: {
     dialectCapabilities: DialectCapabilities;
 }, model: ModelIR$1, planFn: (intent: QueryIntent, model: ModelIR$1, options: {
     dialectCapabilities: DialectCapabilities;
-}) => PlanReport): LeafCompileFn;
+}) => PlanReport, options?: CompileOptions): LeafCompileFn;
 
 /**
  * Cursor-Based Streaming Support
@@ -2158,10 +2192,10 @@ declare class InvalidIdentifierError extends Error {
  * 6. Reserved keywords are allowed (will be quoted)
  *
  * @param value The identifier to validate
- * @param type Type of identifier (for error messages): 'table', 'column', 'schema', 'alias'
+ * @param type Type of identifier (for error messages): 'table', 'column', 'schema', 'alias', 'function'
  * @throws InvalidIdentifierError if validation fails
  */
-declare function validateIdentifier(value: string, type: 'table' | 'column' | 'schema' | 'alias'): void;
+declare function validateIdentifier(value: string, type: 'table' | 'column' | 'schema' | 'alias' | 'function'): void;
 /**
  * Check if an identifier is a SQL reserved keyword.
  */