@dbsp/adapter-pgsql 1.1.1 → 1.2.0

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,9 +275,9 @@ 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;
     /**
@@ -286,6 +288,7 @@ declare class PlanCompiler {
     constructor(options?: CompilerOptions);
     /** Build immutable context for handler-based WHERE compilation */
     private handlerCtx;
+    private findAliasForLegacySourceTable;
     /**
      * Dispatch a PlanDecision through the unified WHERE handler system.
      * Bridges PlanCompiler's state to handler types, calls dispatcher, syncs back.
@@ -324,6 +327,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.
@@ -1058,6 +1065,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 +1120,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 +1159,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 +1205,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 +1607,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 +1630,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 +1711,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 +1990,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 +1999,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 +2184,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.
  */