@dbsp/adapter-pgsql 1.2.0 → 1.3.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 { 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 { ParamIntent, DialectCapabilities, ModelIR, DbCasing, ColumnIR, HierarchyIR, WhereIntent, 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';
@@ -89,6 +89,16 @@ declare const camelCaseNaming: CamelCaseNamingPlugin;
  */
 declare function getNamingPluginForDbCasing(casing: 'snake_case' | 'camelCase' | 'preserve'): NamingPlugin;
 
+/**
+ * Internal registry of NQL `| bind name` CTE names visible to a compile pass.
+ *
+ * Binding names are query-local identifiers, not physical tables. When an active
+ * schema is present, real table FROM sources must be schema-qualified, while CTE
+ * binding names must remain unqualified.
+ */
+
+type BindingNameRegistry = ReadonlySet<string>;
+
 /**
  * Simplified PlanDecision for the spike
  * (In production, import from @dbsp/core)
@@ -257,6 +267,8 @@ interface CompilerOptions {
     readonly deriveFkColumnName?: FkColumnDerivation;
     /** ModelIR for type-aware parameter casting in WHERE clauses */
     readonly model?: _dbsp_types.ModelIR;
+    /** Query-local CTE/binding names that must not be schema-qualified. */
+    readonly bindingNames?: BindingNameRegistry;
 }
 declare class PlanCompiler {
     private readonly naming;
@@ -264,6 +276,7 @@ declare class PlanCompiler {
     private readonly defaultPk;
     private readonly deriveFk;
     private readonly model;
+    private readonly bindingNames;
     /** Mutable state shared with extracted condition/value compilation functions */
     private state;
     /** Track root table for EXISTS FK correlation */
@@ -282,6 +295,7 @@ declare class PlanCompiler {
     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;
@@ -289,6 +303,8 @@ declare class PlanCompiler {
     /** 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.
@@ -340,7 +356,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.
@@ -362,6 +380,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.
@@ -377,11 +396,21 @@ declare class PlanCompiler {
      * Returns undefined when neither expressionIntent nor column is present.
      */
     private compileOrderByDecision;
+    /**
+     * Compile a column reference that may use dotted 'relation.column' notation.
+     */
+    private compileRelationAwareColumnRef;
     /**
      * Compile a single groupBy decision into a ColumnRef AST node.
      * Supports dotted 'relation.column' notation for joined tables.
      */
     private compileGroupByDecision;
+    /**
+     * Compile a DISTINCT ON column into a ColumnRef AST node.
+     * Mirrors GROUP BY relation-alias resolution while preserving unqualified
+     * DISTINCT ON columns as unqualified references.
+     */
+    private compileDistinctOnColumn;
     /**
      * Assemble the final SelectStmt from all accumulated clause nodes.
      * Also handles the default SELECT *, CTEs, and row-level locking.
@@ -1042,6 +1071,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 */
@@ -1052,6 +1083,8 @@ interface CompilerContext {
     readonly deriveFkColumnName?: FkColumnDerivation;
     /** Alias of the outer (parent) query — used for FieldRef scope:'outer' resolution in EXISTS subqueries */
     readonly outerAlias?: string;
+    /** Query-local CTE/binding names that must not be schema-qualified. */
+    readonly bindingNames?: BindingNameRegistry;
     /**
      * Optional callback to compile a QueryIntent into an AST Node (SubLink subselect).
      * Set by PlanCompiler when compiling selectCustomExpression — enables SubqueryExpressionIntent
@@ -1405,6 +1438,12 @@ interface UpsertConfig {
     conflictAction: ConflictAction;
     /** Columns to update on conflict (for 'update' action) */
     updateColumns?: string[];
+    /** Optional WHERE clause for ON CONFLICT DO UPDATE */
+    actionWhere?: Decision[];
+    /** Optional direct WHERE intent for ON CONFLICT DO UPDATE */
+    actionWhereIntent?: WhereIntent;
+    /** Compile the direct action WHERE intent using the caller's WHERE compiler */
+    compileActionWhere?: (where: WhereIntent, state: CompilerState) => Node;
     /** Use EXCLUDED.column for update values (default: true) */
     useExcluded?: boolean;
     /** Columns to return (RETURNING clause) */
@@ -1608,6 +1647,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private cloneOptions;
     private buildCompileDeps;
     private requireNqlCompileModel;
+    private assertNqlBindingNamesDisjointFromTables;
     private compileNqlMutation;
     private compileNqlBundleLeaf;
     private compileNqlBundle;
@@ -1712,6 +1752,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;
+    private compileSetOperationWithBindings;
     /**
      * Create a dump for observability.
      */