@dbsp/core 1.10.0 → 1.10.1

package/dist/index.js

@@ -3219,375 +3219,788 @@ function batchValues(data, columns, types, opts) {
   });
 }
 
-// src/dx/expressions.ts
-var OPERATOR_PATTERN = /^[a-zA-Z_<>=!@#%^&|~*+\-/.]+$/;
-var FUNCTION_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$/;
-var TYPE_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_ ]*(\[\])?$/;
-function toExpressionIntent(input) {
-  if (input instanceof ExpressionRef) return input.intent;
-  if (typeof input === "object" && input !== null && "__expr" in input && input.__expr === true && "intent" in input) {
-    return input.intent;
+// src/dx/column-utils.ts
+function getColumnName(field) {
+  if (typeof field === "string") {
+    return field;
   }
-  if (typeof input === "string") {
-    return { kind: "ref", column: input };
+  const colName = field[COLUMN_META];
+  if (colName === void 0) {
+    throw new Error("Invalid ColumnRef: missing COLUMN_META");
   }
-  return { kind: "param", value: input };
+  return colName;
 }
-var ExpressionRef = class _ExpressionRef {
-  __expr = true;
-  intent;
-  constructor(intent) {
-    this.intent = intent;
+
+// src/dx/window-functions.ts
+var WindowBuilder = class _WindowBuilder {
+  constructor(fnKind, partitions = [], orders = []) {
+    this.fnKind = fnKind;
+    this.partitions = partitions;
+    this.orders = orders;
   }
+  fnKind;
+  partitions;
+  orders;
   /**
-   * Set an alias for this expression in SELECT.
-   * Returns a new ExpressionRef — does not mutate.
+   * Create a ranking window builder (row_number, rank, dense_rank)
+   * @internal Use factory functions instead: rowNumber(), rank(), denseRank()
    */
-  as(alias) {
-    return new _ExpressionRef({
-      ...this.intent,
-      as: alias
-    });
-  }
-  /** WHERE: expr = value */
-  eq(value) {
-    return { kind: "expression", expr: this.intent, operator: "eq", value };
-  }
-  /** WHERE: expr != value */
-  neq(value) {
-    return { kind: "expression", expr: this.intent, operator: "neq", value };
+  static ranking(fn2) {
+    return new _WindowBuilder({ type: "ranking", fn: fn2 });
   }
-  /** WHERE: expr > value */
-  gt(value) {
-    return { kind: "expression", expr: this.intent, operator: "gt", value };
+  /**
+   * Create an aggregate window builder (sum, avg, count, min, max)
+   * @internal Use factory functions instead: sum(field), avg(field), etc.
+   */
+  static aggregate(fn2, field) {
+    return new _WindowBuilder({
+      type: "aggregate",
+      fn: fn2,
+      ...field !== void 0 ? { field } : {}
+    });
   }
-  /** WHERE: expr >= value */
-  gte(value) {
-    return { kind: "expression", expr: this.intent, operator: "gte", value };
+  /**
+   * Create an offset window builder (lag, lead)
+   * @internal Use factory functions instead: lag(field), lead(field)
+   */
+  static offset(fn2, field) {
+    return new _WindowBuilder({ type: "offset", fn: fn2, field });
   }
-  /** WHERE: expr < value */
-  lt(value) {
-    return { kind: "expression", expr: this.intent, operator: "lt", value };
+  /**
+   * Add partition field(s) to the OVER clause.
+   * Multiple calls APPEND fields (not replace).
+   * Supports both string field names and ColumnRef (DX-040).
+   *
+   * @example
+   * sum('amount').partitionBy('user_id').partitionBy('category')
+   * // → PARTITION BY "user_id", "category"
+   *
+   * @example DX-040 with ColumnRef
+   * rank().partitionBy(users.dept).orderBy(users.salary, 'desc')
+   */
+  partitionBy(...fields) {
+    const fieldNames = fields.map(
+      (f) => typeof f === "string" ? f : getColumnName(f)
+    );
+    return new _WindowBuilder(
+      this.fnKind,
+      [...this.partitions, ...fieldNames],
+      this.orders
+    );
   }
-  /** WHERE: expr <= value */
-  lte(value) {
-    return { kind: "expression", expr: this.intent, operator: "lte", value };
+  /**
+   * Add order field to the OVER clause.
+   * Multiple calls APPEND fields (not replace).
+   * Supports both string field names and ColumnRef (DX-040).
+   *
+   * @param field - Column name or ColumnRef to order by
+   * @param direction - Sort direction: 'asc' (default) or 'desc'
+   *
+   * @example
+   * rowNumber().orderBy('created_at').orderBy('id', 'desc')
+   * // → ORDER BY "created_at" ASC, "id" DESC
+   *
+   * @example DX-040 with ColumnRef
+   * rank().partitionBy(users.dept).orderBy(users.salary, 'desc')
+   */
+  orderBy(field, direction = "asc") {
+    const fieldName = typeof field === "string" ? field : getColumnName(field);
+    return new _WindowBuilder(this.fnKind, this.partitions, [
+      ...this.orders,
+      { field: fieldName, direction }
+    ]);
   }
   /**
-   * Add a FILTER (WHERE ...) clause to this function expression.
-   * Only valid on `fn()` expressions (customFn kind).
-   * Returns a new ExpressionRef — does not mutate.
+   * Finalize the window expression with an alias.
+   * Returns ExpressionSpec for use in columns().
    *
-   * @example fn('array_agg', ref('name')).filter(eq('active', true))
-   *          → array_agg("name") FILTER (WHERE "active" = $1)
-   * @throws Error if called on non-customFn expressions
+   * @param alias - Required alias for the result column
+   *
+   * @example
+   * columns(['id', rowNumber().orderBy('date').as('rn')])
    */
-  filter(condition) {
-    if (this.intent.kind !== "customFn") {
-      throw new Error(
-        `filter() can only be used on function expressions created with fn(). Got kind: '${this.intent.kind}'`
-      );
+  as(alias) {
+    return {
+      __expr: true,
+      intent: this.toWindowIntent(alias)
+    };
+  }
+  /**
+   * Convert builder state to WindowIntent — produces the correct discriminated branch.
+   * - ranking → RankingWindowIntent (no field)
+   * - aggregate → AggregateWindowIntent (field required; COUNT uses '*' when omitted)
+   * - offset → OffsetWindowIntent (field required)
+   */
+  toWindowIntent(alias) {
+    const over = {};
+    if (this.partitions.length > 0) {
+      over.partitionBy = this.partitions;
     }
-    return new _ExpressionRef({
-      ...this.intent,
-      filter: condition
-    });
+    if (this.orders.length > 0) {
+      over.orderBy = this.orders;
+    }
+    if (this.fnKind.type === "ranking") {
+      return {
+        kind: "window",
+        function: this.fnKind.fn,
+        alias,
+        over
+      };
+    }
+    if (this.fnKind.type === "offset") {
+      return {
+        kind: "window",
+        function: this.fnKind.fn,
+        field: this.fnKind.field,
+        alias,
+        over
+      };
+    }
+    const { field } = this.fnKind;
+    return {
+      kind: "window",
+      function: this.fnKind.fn,
+      ...field !== void 0 && { field },
+      alias,
+      over
+    };
   }
 };
-function ref2(column) {
-  return new ExpressionRef({
-    kind: "ref",
-    column
-  });
+function rowNumber() {
+  return WindowBuilder.ranking("row_number");
 }
-function param(value) {
-  return new ExpressionRef({
-    kind: "param",
-    value
-  });
+function rank() {
+  return WindowBuilder.ranking("rank");
 }
-function cast(expr, typeName) {
-  if (!TYPE_NAME_PATTERN.test(typeName)) {
-    throw new Error(`Invalid type name: ${typeName}`);
-  }
-  return new ExpressionRef({
-    kind: "cast",
-    expr: expr.intent,
-    typeName
-  });
+function denseRank() {
+  return WindowBuilder.ranking("dense_rank");
 }
-function op(operator, left, right) {
-  if (!operator || !OPERATOR_PATTERN.test(operator)) {
-    throw new Error(`Invalid operator: ${operator}`);
-  }
-  return new ExpressionRef({
-    kind: "customOp",
-    operator,
-    left: toExpressionIntent(left),
-    right: toExpressionIntent(right)
-  });
+function wSum(field) {
+  return WindowBuilder.aggregate("sum", field);
 }
-function fn(name, ...args) {
-  if (!name || !FUNCTION_NAME_PATTERN.test(name)) {
-    throw new Error(`Invalid function name: ${name}`);
-  }
-  const regularArgs = [];
-  const orderByArgs = [];
-  for (const arg of args) {
-    if (isAggOrderByArg(arg)) {
-      orderByArgs.push(arg);
-    } else {
-      regularArgs.push(toExpressionIntent(arg));
-    }
-  }
-  const intent = {
-    kind: "customFn",
-    name,
-    args: regularArgs,
-    ...orderByArgs.length > 0 ? { aggOrderBy: orderByArgs } : {}
-  };
-  return new ExpressionRef(intent);
+function wAvg(field) {
+  return WindowBuilder.aggregate("avg", field);
 }
-function literal(value) {
-  return new ExpressionRef({
-    kind: "literal",
-    value
-  });
+function wCount(field) {
+  return WindowBuilder.aggregate("count", field);
 }
-function unary(operator, expr) {
-  if (!operator || !OPERATOR_PATTERN.test(operator)) {
-    throw new Error(`Invalid operator: ${operator}`);
-  }
-  return new ExpressionRef({
-    kind: "unary",
-    operator,
-    operand: toExpressionIntent(expr)
+function wMin(field) {
+  return WindowBuilder.aggregate("min", field);
+}
+function wMax(field) {
+  return WindowBuilder.aggregate("max", field);
+}
+function lag(field) {
+  return WindowBuilder.offset("lag", field);
+}
+function lead(field) {
+  return WindowBuilder.offset("lead", field);
+}
+
+// src/dx/filters.ts
+function distinct(field) {
+  return { field, distinct: true };
+}
+function isDistinctField(value) {
+  return typeof value === "object" && value !== null && "field" in value && typeof value.field === "string" && "distinct" in value && value.distinct === true;
+}
+function createComparisonFilter(operator) {
+  return (field, value) => ({
+    kind: "comparison",
+    field: getColumnName(field),
+    operator,
+    value
   });
 }
-function namedArg(name, value) {
-  if (!name || !FUNCTION_NAME_PATTERN.test(name)) {
-    throw new Error(`namedArg: invalid argument name: ${name}`);
+var eq = createComparisonFilter("eq");
+var neq = createComparisonFilter("neq");
+var gt = createComparisonFilter("gt");
+var gte = createComparisonFilter("gte");
+var lt = createComparisonFilter("lt");
+var lte = createComparisonFilter("lte");
+var isDistinctFrom = createComparisonFilter("isDistinctFrom");
+function like(field, pattern, options) {
+  const caseInsensitive = typeof options === "boolean" ? options : options?.caseInsensitive;
+  const escapeChar = typeof options === "object" ? options.escape : void 0;
+  const intent = {
+    kind: "like",
+    field: getColumnName(field),
+    pattern
+  };
+  const withCi = caseInsensitive !== void 0 ? { ...intent, caseInsensitive } : intent;
+  if (escapeChar !== void 0) {
+    return { ...withCi, escape: escapeChar };
   }
-  return new ExpressionRef({
-    kind: "namedArg",
-    name,
-    value: toExpressionIntent(value)
-  });
+  return withCi;
 }
-function star() {
-  return new ExpressionRef({ kind: "star" });
+function inArray(field, values) {
+  return { kind: "in", field: getColumnName(field), values };
 }
-function array(...items) {
-  return new ExpressionRef({
-    kind: "array",
-    elements: items.map(toExpressionIntent)
-  });
+function inSubquery(field, query) {
+  const expr = "build" in query ? query.build() : query;
+  return {
+    kind: "in",
+    field: getColumnName(field),
+    subquery: expr.toIntent()
+  };
 }
-function isAggOrderByArg(input) {
-  return typeof input === "object" && input !== null && !Array.isArray(input) && !(input instanceof ExpressionRef) && "__aggOrderBy" in input && input.__aggOrderBy === true;
+function any(field, values) {
+  return { kind: "any", field: getColumnName(field), values };
 }
-function aggOrderBy(field, direction = "asc") {
-  return { __aggOrderBy: true, field, direction };
+function isNull(field) {
+  return { kind: "null", field: getColumnName(field), operator: "isNull" };
 }
-function arrayAgg(col2, ...rest) {
-  const colExpr = typeof col2 === "string" ? ref2(col2) : col2;
-  return fn("array_agg", colExpr, ...rest);
+function isNotNull(field) {
+  return { kind: "null", field: getColumnName(field), operator: "isNotNull" };
 }
-function stringAgg(col2, separator, ...rest) {
-  const colExpr = typeof col2 === "string" ? ref2(col2) : col2;
-  return fn("string_agg", colExpr, separator, ...rest);
+function and(...conditions) {
+  const flatConditions = conditions.length === 1 && Array.isArray(conditions[0]) ? conditions[0] : conditions;
+  return { kind: "and", conditions: flatConditions };
 }
-
-// src/dx/case-when-builder.ts
-function toResultIntent(value) {
-  if (value instanceof ExpressionRef) {
-    return value.intent;
+function or(...conditions) {
+  const flatConditions = conditions.length === 1 && Array.isArray(conditions[0]) ? conditions[0] : conditions;
+  return { kind: "or", conditions: flatConditions };
+}
+function not(condition) {
+  return { kind: "not", condition };
+}
+function exists(relation, options) {
+  const result = { kind: "exists", relation };
+  if (options?.where !== void 0) {
+    result.where = options.where;
   }
-  if (value === null || value === void 0) {
-    return { kind: "literal", value: null };
+  if (options?.recursive !== void 0) {
+    result.recursive = options.recursive;
   }
-  if (typeof value === "string") {
-    return { kind: "ref", column: value };
+  if (options?.include !== void 0) {
+    result.include = options.include;
   }
-  return { kind: "literal", value };
+  return result;
 }
-var CaseBuilder = class _CaseBuilder {
-  branches;
-  constructor(branches) {
-    this.branches = branches;
+function notExists(relation, options) {
+  const result = {
+    kind: "notExists",
+    relation
+  };
+  if (options?.where !== void 0) {
+    result.where = options.where;
   }
-  when(condition, thenValue) {
-    return new _CaseBuilder([
-      ...this.branches,
-      { condition, result: toResultIntent(thenValue) }
-    ]);
+  if (options?.recursive !== void 0) {
+    result.recursive = options.recursive;
   }
-  else(elseValue) {
-    const intent = {
-      kind: "case",
-      when: this.branches,
-      else: toResultIntent(elseValue)
-    };
-    return new ExpressionRef(intent);
+  if (options?.include !== void 0) {
+    result.include = options.include;
   }
-  as(alias) {
-    return this.toExpr().as(alias);
+  return result;
+}
+function rawExists(sq) {
+  const intent = "buildIntent" in sq ? sq.buildIntent() : sq.build().toIntent();
+  return { kind: "rawExists", subquery: intent };
+}
+function rawNotExists(sq) {
+  const intent = "buildIntent" in sq ? sq.buildIntent() : sq.build().toIntent();
+  return { kind: "rawNotExists", subquery: intent };
+}
+function getRelationName(rel) {
+  const meta = rel[RELATION_META];
+  if (!meta) {
+    throw new Error("Invalid RelationRef: missing RELATION_META");
   }
-  toExpr() {
-    const intent = {
-      kind: "case",
-      when: this.branches
-    };
-    return new ExpressionRef(intent);
+  return meta.target;
+}
+function every(relation, filter) {
+  const relationName = getRelationName(relation);
+  const where = filter(relation);
+  return {
+    kind: "relationFilter",
+    relation: relationName,
+    where,
+    mode: "every"
+  };
+}
+function none(relation, filter) {
+  const relationName = getRelationName(relation);
+  const where = filter(relation);
+  return {
+    kind: "relationFilter",
+    relation: relationName,
+    where,
+    mode: "none"
+  };
+}
+function some(relation, filter) {
+  const relationName = getRelationName(relation);
+  const where = filter(relation);
+  return {
+    kind: "relationFilter",
+    relation: relationName,
+    where,
+    mode: "some"
+  };
+}
+function coalesce(fields, as) {
+  if (fields.length === 0) {
+    throw new Error("coalesce() requires at least one field");
   }
-};
-function caseWhen(condition, thenValue) {
-  return new CaseBuilder([{ condition, result: toResultIntent(thenValue) }]);
+  if (!as || as.trim() === "") {
+    throw new Error("coalesce() requires a non-empty alias");
+  }
+  for (const f of fields) {
+    validateIdentifier(f, "column");
+  }
+  validateIdentifier(as, "column");
+  return {
+    __expr: true,
+    intent: { kind: "coalesce", fields, as }
+  };
 }
-
-// src/dx/builder-utils.ts
-function requireAdapter(adapter, operationName) {
-  if (!adapter) {
+function raw(sqlFragment, as) {
+  if (typeof as !== "string" || as.trim().length === 0) {
     throw new InvalidOperationError(
-      operationName,
-      "This operation requires an adapter \u2014 pass an adapter when creating the ORM"
+      "raw",
+      "raw() requires an alias as second argument, e.g. raw('COUNT(*)', 'count')"
     );
   }
-  return adapter;
+  validateIdentifier(as, "column");
+  return {
+    __expr: true,
+    intent: { kind: "raw", sql: sqlFragment, as }
+  };
 }
-
-// src/dx/cte-builder.ts
-var CteBuilder = class {
-  cteName;
-  adapter;
-  schemaName;
-  unnestColumns;
-  indexColumnName;
-  constructor(name, adapter, schemaName) {
-    this.cteName = name;
-    this.adapter = adapter;
-    this.schemaName = schemaName;
+function col(column, alias) {
+  validateIdentifier(column, "column");
+  validateIdentifier(alias, "column");
+  return {
+    __expr: true,
+    intent: { kind: "columnAlias", column, alias }
+  };
+}
+function relationColumn(relation, column, as) {
+  if (!relation) {
+    throw new Error("relationColumn() requires a non-empty relation path");
   }
-  /**
-   * Provide the column arrays for the unnest() CTE.
-   * All arrays must have the same length.
-   *
-   * @param columns - A record of column name → array of values.
-   */
-  fromUnnest(columns) {
-    const lengths = Object.values(columns).map((arr) => arr.length);
-    if (lengths.length > 1 && !lengths.every((l) => l === lengths[0])) {
-      throw new InvalidOperationError(
-        "withCte",
-        `Array length mismatch in CTE unnest columns: lengths are [${lengths.join(", ")}]`
-      );
-    }
-    this.unnestColumns = columns;
-    return this;
+  for (const segment of relation.split(".")) {
+    validateIdentifier(segment, "relation");
+  }
+  if (column !== "*") {
+    validateIdentifier(column, "column");
+  }
+  validateIdentifier(as, "column");
+  return {
+    __expr: true,
+    intent: { kind: "relationColumn", relation, column, as }
+  };
+}
+var SQL_RAW_MARKER = /* @__PURE__ */ Symbol.for("dbsp:raw-sql");
+function sql(sqlFragment) {
+  if (!sqlFragment || sqlFragment.trim() === "") {
+    throw new Error("sql() requires a non-empty SQL fragment");
+  }
+  return { [SQL_RAW_MARKER]: true, sql: sqlFragment };
+}
+function isSqlRaw(value) {
+  return typeof value === "object" && value !== null && SQL_RAW_MARKER in value && value[SQL_RAW_MARKER] === true;
+}
+
+// src/dx/expressions.ts
+var OPERATOR_PATTERN = /^[a-zA-Z_<>=!@#%^&|~*+\-/.]+$/;
+var FUNCTION_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$/;
+var TYPE_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_ ]*(\[\])?$/;
+function toExpressionIntent(input) {
+  if (input instanceof ExpressionRef) return input.intent;
+  if (typeof input === "object" && input !== null && "__expr" in input && input.__expr === true && "intent" in input) {
+    return input.intent;
+  }
+  if (typeof input === "string") {
+    return { kind: "ref", column: input };
+  }
+  return { kind: "param", value: input };
+}
+var ExpressionRef = class _ExpressionRef {
+  __expr = true;
+  intent;
+  constructor(intent) {
+    this.intent = intent;
   }
   /**
-   * Add a 0-based ordinality index column (uses WITH ORDINALITY).
-   *
-   * @param columnName - The name of the index column in the CTE.
+   * Set an alias for this expression in SELECT.
+   * Returns a new ExpressionRef — does not mutate.
    */
-  withIndex(columnName) {
-    this.indexColumnName = columnName;
-    return this;
+  as(alias) {
+    return new _ExpressionRef({
+      ...this.intent,
+      as: alias
+    });
+  }
+  /** WHERE: expr = value */
+  eq(value) {
+    return { kind: "expression", expr: this.intent, operator: "eq", value };
+  }
+  /** WHERE: expr != value */
+  neq(value) {
+    return { kind: "expression", expr: this.intent, operator: "neq", value };
+  }
+  /** WHERE: expr > value */
+  gt(value) {
+    return { kind: "expression", expr: this.intent, operator: "gt", value };
+  }
+  /** WHERE: expr >= value */
+  gte(value) {
+    return { kind: "expression", expr: this.intent, operator: "gte", value };
+  }
+  /** WHERE: expr < value */
+  lt(value) {
+    return { kind: "expression", expr: this.intent, operator: "lt", value };
+  }
+  /** WHERE: expr <= value */
+  lte(value) {
+    return { kind: "expression", expr: this.intent, operator: "lte", value };
   }
   /**
-   * Attach an outer query and produce a CteQueryBuilder for execution.
+   * Add a FILTER (WHERE ...) clause to this function expression.
+   * Valid on `fn()` expressions (customFn kind), including DISTINCT calls
+   * produced by `fn(aggName, distinct(field))` (still customFn kind).
+   * Returns a new ExpressionRef — does not mutate.
    *
-   * @param selectBuilder - A QueryBuilder (from orm.select(...))
+   * NOTE: the FILTER clause is only emitted when the expression is used in
+   * column position (`.columns([...])`) — the adapter patches it in at that
+   * one SELECT-list branch (compiler.ts). Using `.filter()` inside
+   * `.orderBy()`, `.having()`, `cast()`, or any other nested context compiles
+   * successfully but silently drops the FILTER clause (tracked separately,
+   * not specific to DISTINCT).
+   *
+   * @example fn('array_agg', ref('name')).filter(eq('active', true))
+   *          → array_agg("name") FILTER (WHERE "active" = $1)   // in .columns()
+   * @example fn('count', distinct('id')).filter(eq('active', true))
+   *          → count(DISTINCT id) FILTER (WHERE "active" = $1)  // in .columns()
+   * @throws Error if called on any other expression kind
    */
-  query(selectBuilder) {
-    if (!this.unnestColumns) {
-      throw new InvalidOperationError(
-        "withCte",
-        "CTE requires a data source \u2014 call .fromUnnest() first"
+  filter(condition) {
+    if (this.intent.kind !== "customFn") {
+      throw new Error(
+        `filter() can only be used on function expressions created with fn(). Got kind: '${this.intent.kind}'`
       );
     }
-    const cteIntent = {
-      kind: "unnestCte",
-      name: this.cteName,
-      columns: this.unnestColumns,
-      ...this.indexColumnName !== void 0 && {
-        indexColumn: this.indexColumnName
-      }
-    };
-    return new CteQueryBuilder(
-      cteIntent,
-      selectBuilder,
-      this.adapter,
-      this.schemaName
-    );
+    return new _ExpressionRef({
+      ...this.intent,
+      filter: condition
+    });
   }
 };
-var CteQueryBuilder = class {
-  cteIntent;
-  outerBuilder;
-  adapter;
-  schemaName;
-  constructor(cteIntent, outerBuilder, adapter, schemaName) {
-    this.cteIntent = cteIntent;
-    this.outerBuilder = outerBuilder;
-    this.adapter = adapter;
-    this.schemaName = schemaName;
+function ref2(column) {
+  return new ExpressionRef({
+    kind: "ref",
+    column
+  });
+}
+function param(value) {
+  return new ExpressionRef({
+    kind: "param",
+    value
+  });
+}
+function cast(expr, typeName) {
+  if (!TYPE_NAME_PATTERN.test(typeName)) {
+    throw new Error(`Invalid type name: ${typeName}`);
   }
-  /**
-   * Build the CteQueryIntent AST.
-   */
-  buildIntent() {
-    const queryIntent = this.outerBuilder.buildIntent();
-    return {
-      kind: "cteQuery",
-      ctes: [this.cteIntent],
-      query: queryIntent
-    };
+  return new ExpressionRef({
+    kind: "cast",
+    expr: expr.intent,
+    typeName
+  });
+}
+function op(operator, left, right) {
+  if (!operator || !OPERATOR_PATTERN.test(operator)) {
+    throw new Error(`Invalid operator: ${operator}`);
   }
-  requireAdapter() {
-    return requireAdapter(this.adapter, "withCte");
+  return new ExpressionRef({
+    kind: "customOp",
+    operator,
+    left: toExpressionIntent(left),
+    right: toExpressionIntent(right)
+  });
+}
+function fn(name, ...args) {
+  if (!name || !FUNCTION_NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid function name: ${name}`);
   }
-  /**
-   * Compile to SQL and return an observability dump.
-   */
-  dump() {
-    const adapter = this.requireAdapter();
-    const intent = this.buildIntent();
-    const compileOptions = this.schemaName ? { schemaName: this.schemaName } : void 0;
-    const compiled = adapter.compileCteQuery(
-      intent,
-      compileOptions
-    );
-    return {
-      sql: compiled.sql,
-      params: compiled.parameters,
-      intent
-    };
+  const regularArgs = [];
+  const orderByArgs = [];
+  let distinct2 = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (isDistinctField2(arg)) {
+      if (i !== 0) {
+        throw new Error(
+          `fn('${name}', ...): distinct() is only supported as the first argument \u2014 SQL DISTINCT applies to the whole argument list, not a single position.`
+        );
+      }
+      const field = arg.field;
+      if (field === "*") {
+        throw new Error(
+          `fn('${name}', distinct('*')): DISTINCT on '*' is not valid SQL \u2014 '*' has no columns to deduplicate on. Provide a specific column, or omit distinct() (e.g. fn('${name}', star())) for a plain star call.`
+        );
+      }
+      distinct2 = true;
+      regularArgs.push(toExpressionIntent(field));
+    } else if (isAggOrderByArg(arg)) {
+      orderByArgs.push(arg);
+    } else {
+      regularArgs.push(toExpressionIntent(arg));
+    }
   }
-  /**
-   * Execute the CTE query and return all results.
-   */
-  async all() {
-    const adapter = this.requireAdapter();
-    const intent = this.buildIntent();
-    const compileOptions = this.schemaName ? { schemaName: this.schemaName } : void 0;
-    const compiled = adapter.compileCteQuery(
-      intent,
-      compileOptions
-    );
-    return adapter.execute(compiled);
+  const intent = {
+    kind: "customFn",
+    name,
+    args: regularArgs,
+    ...distinct2 ? { distinct: true } : {},
+    ...orderByArgs.length > 0 ? { aggOrderBy: orderByArgs } : {}
+  };
+  return new ExpressionRef(intent);
+}
+function literal(value) {
+  return new ExpressionRef({
+    kind: "literal",
+    value
+  });
+}
+function unary(operator, expr) {
+  if (!operator || !OPERATOR_PATTERN.test(operator)) {
+    throw new Error(`Invalid operator: ${operator}`);
   }
-  /**
-   * Alias for all().
-   */
-  execute() {
-    return this.all();
+  return new ExpressionRef({
+    kind: "unary",
+    operator,
+    operand: toExpressionIntent(expr)
+  });
+}
+function namedArg(name, value) {
+  if (!name || !FUNCTION_NAME_PATTERN.test(name)) {
+    throw new Error(`namedArg: invalid argument name: ${name}`);
   }
-};
-
-// src/dx/feature-checkers.ts
-var DEFAULT_FEATURE_CHECKERS = Object.freeze([
-  // -----------------------------------------------------------------------
+  return new ExpressionRef({
+    kind: "namedArg",
+    name,
+    value: toExpressionIntent(value)
+  });
+}
+function star() {
+  return new ExpressionRef({ kind: "star" });
+}
+function array(...items) {
+  return new ExpressionRef({
+    kind: "array",
+    elements: items.map(toExpressionIntent)
+  });
+}
+function isDistinctField2(input) {
+  return !Array.isArray(input) && !(input instanceof ExpressionRef) && isDistinctField(input);
+}
+function isAggOrderByArg(input) {
+  return typeof input === "object" && input !== null && !Array.isArray(input) && !(input instanceof ExpressionRef) && "__aggOrderBy" in input && input.__aggOrderBy === true;
+}
+function aggOrderBy(field, direction = "asc") {
+  return { __aggOrderBy: true, field, direction };
+}
+function arrayAgg(col2, ...rest) {
+  const colExpr = typeof col2 === "string" ? ref2(col2) : col2;
+  return fn("array_agg", colExpr, ...rest);
+}
+function stringAgg(col2, separator, ...rest) {
+  const colExpr = typeof col2 === "string" ? ref2(col2) : col2;
+  return fn("string_agg", colExpr, separator, ...rest);
+}
+
+// src/dx/case-when-builder.ts
+function toResultIntent(value) {
+  if (value instanceof ExpressionRef) {
+    return value.intent;
+  }
+  if (value === null || value === void 0) {
+    return { kind: "literal", value: null };
+  }
+  if (typeof value === "string") {
+    return { kind: "ref", column: value };
+  }
+  return { kind: "literal", value };
+}
+var CaseBuilder = class _CaseBuilder {
+  branches;
+  constructor(branches) {
+    this.branches = branches;
+  }
+  when(condition, thenValue) {
+    return new _CaseBuilder([
+      ...this.branches,
+      { condition, result: toResultIntent(thenValue) }
+    ]);
+  }
+  else(elseValue) {
+    const intent = {
+      kind: "case",
+      when: this.branches,
+      else: toResultIntent(elseValue)
+    };
+    return new ExpressionRef(intent);
+  }
+  as(alias) {
+    return this.toExpr().as(alias);
+  }
+  toExpr() {
+    const intent = {
+      kind: "case",
+      when: this.branches
+    };
+    return new ExpressionRef(intent);
+  }
+};
+function caseWhen(condition, thenValue) {
+  return new CaseBuilder([{ condition, result: toResultIntent(thenValue) }]);
+}
+
+// src/dx/builder-utils.ts
+function requireAdapter(adapter, operationName) {
+  if (!adapter) {
+    throw new InvalidOperationError(
+      operationName,
+      "This operation requires an adapter \u2014 pass an adapter when creating the ORM"
+    );
+  }
+  return adapter;
+}
+
+// src/dx/cte-builder.ts
+var CteBuilder = class {
+  cteName;
+  adapter;
+  schemaName;
+  unnestColumns;
+  indexColumnName;
+  constructor(name, adapter, schemaName) {
+    this.cteName = name;
+    this.adapter = adapter;
+    this.schemaName = schemaName;
+  }
+  /**
+   * Provide the column arrays for the unnest() CTE.
+   * All arrays must have the same length.
+   *
+   * @param columns - A record of column name → array of values.
+   */
+  fromUnnest(columns) {
+    const lengths = Object.values(columns).map((arr) => arr.length);
+    if (lengths.length > 1 && !lengths.every((l) => l === lengths[0])) {
+      throw new InvalidOperationError(
+        "withCte",
+        `Array length mismatch in CTE unnest columns: lengths are [${lengths.join(", ")}]`
+      );
+    }
+    this.unnestColumns = columns;
+    return this;
+  }
+  /**
+   * Add a 0-based ordinality index column (uses WITH ORDINALITY).
+   *
+   * @param columnName - The name of the index column in the CTE.
+   */
+  withIndex(columnName) {
+    this.indexColumnName = columnName;
+    return this;
+  }
+  /**
+   * Attach an outer query and produce a CteQueryBuilder for execution.
+   *
+   * @param selectBuilder - A QueryBuilder (from orm.select(...))
+   */
+  query(selectBuilder) {
+    if (!this.unnestColumns) {
+      throw new InvalidOperationError(
+        "withCte",
+        "CTE requires a data source \u2014 call .fromUnnest() first"
+      );
+    }
+    const cteIntent = {
+      kind: "unnestCte",
+      name: this.cteName,
+      columns: this.unnestColumns,
+      ...this.indexColumnName !== void 0 && {
+        indexColumn: this.indexColumnName
+      }
+    };
+    return new CteQueryBuilder(
+      cteIntent,
+      selectBuilder,
+      this.adapter,
+      this.schemaName
+    );
+  }
+};
+var CteQueryBuilder = class {
+  cteIntent;
+  outerBuilder;
+  adapter;
+  schemaName;
+  constructor(cteIntent, outerBuilder, adapter, schemaName) {
+    this.cteIntent = cteIntent;
+    this.outerBuilder = outerBuilder;
+    this.adapter = adapter;
+    this.schemaName = schemaName;
+  }
+  /**
+   * Build the CteQueryIntent AST.
+   */
+  buildIntent() {
+    const queryIntent = this.outerBuilder.buildIntent();
+    return {
+      kind: "cteQuery",
+      ctes: [this.cteIntent],
+      query: queryIntent
+    };
+  }
+  requireAdapter() {
+    return requireAdapter(this.adapter, "withCte");
+  }
+  /**
+   * Compile to SQL and return an observability dump.
+   */
+  dump() {
+    const adapter = this.requireAdapter();
+    const intent = this.buildIntent();
+    const compileOptions = this.schemaName ? { schemaName: this.schemaName } : void 0;
+    const compiled = adapter.compileCteQuery(
+      intent,
+      compileOptions
+    );
+    return {
+      sql: compiled.sql,
+      params: compiled.parameters,
+      intent
+    };
+  }
+  /**
+   * Execute the CTE query and return all results.
+   */
+  async all() {
+    const adapter = this.requireAdapter();
+    const intent = this.buildIntent();
+    const compileOptions = this.schemaName ? { schemaName: this.schemaName } : void 0;
+    const compiled = adapter.compileCteQuery(
+      intent,
+      compileOptions
+    );
+    return adapter.execute(compiled);
+  }
+  /**
+   * Alias for all().
+   */
+  execute() {
+    return this.all();
+  }
+};
+
+// src/dx/feature-checkers.ts
+var DEFAULT_FEATURE_CHECKERS = Object.freeze([
+  // -----------------------------------------------------------------------
   // Schema-level features
   // -----------------------------------------------------------------------
   {
@@ -3861,389 +4274,6 @@ var DEFAULT_FEATURE_CHECKERS = Object.freeze([
   }
 ]);
 
-// src/dx/column-utils.ts
-function getColumnName(field) {
-  if (typeof field === "string") {
-    return field;
-  }
-  const colName = field[COLUMN_META];
-  if (colName === void 0) {
-    throw new Error("Invalid ColumnRef: missing COLUMN_META");
-  }
-  return colName;
-}
-
-// src/dx/window-functions.ts
-var WindowBuilder = class _WindowBuilder {
-  constructor(fnKind, partitions = [], orders = []) {
-    this.fnKind = fnKind;
-    this.partitions = partitions;
-    this.orders = orders;
-  }
-  fnKind;
-  partitions;
-  orders;
-  /**
-   * Create a ranking window builder (row_number, rank, dense_rank)
-   * @internal Use factory functions instead: rowNumber(), rank(), denseRank()
-   */
-  static ranking(fn2) {
-    return new _WindowBuilder({ type: "ranking", fn: fn2 });
-  }
-  /**
-   * Create an aggregate window builder (sum, avg, count, min, max)
-   * @internal Use factory functions instead: sum(field), avg(field), etc.
-   */
-  static aggregate(fn2, field) {
-    return new _WindowBuilder({
-      type: "aggregate",
-      fn: fn2,
-      ...field !== void 0 ? { field } : {}
-    });
-  }
-  /**
-   * Create an offset window builder (lag, lead)
-   * @internal Use factory functions instead: lag(field), lead(field)
-   */
-  static offset(fn2, field) {
-    return new _WindowBuilder({ type: "offset", fn: fn2, field });
-  }
-  /**
-   * Add partition field(s) to the OVER clause.
-   * Multiple calls APPEND fields (not replace).
-   * Supports both string field names and ColumnRef (DX-040).
-   *
-   * @example
-   * sum('amount').partitionBy('user_id').partitionBy('category')
-   * // → PARTITION BY "user_id", "category"
-   *
-   * @example DX-040 with ColumnRef
-   * rank().partitionBy(users.dept).orderBy(users.salary, 'desc')
-   */
-  partitionBy(...fields) {
-    const fieldNames = fields.map(
-      (f) => typeof f === "string" ? f : getColumnName(f)
-    );
-    return new _WindowBuilder(
-      this.fnKind,
-      [...this.partitions, ...fieldNames],
-      this.orders
-    );
-  }
-  /**
-   * Add order field to the OVER clause.
-   * Multiple calls APPEND fields (not replace).
-   * Supports both string field names and ColumnRef (DX-040).
-   *
-   * @param field - Column name or ColumnRef to order by
-   * @param direction - Sort direction: 'asc' (default) or 'desc'
-   *
-   * @example
-   * rowNumber().orderBy('created_at').orderBy('id', 'desc')
-   * // → ORDER BY "created_at" ASC, "id" DESC
-   *
-   * @example DX-040 with ColumnRef
-   * rank().partitionBy(users.dept).orderBy(users.salary, 'desc')
-   */
-  orderBy(field, direction = "asc") {
-    const fieldName = typeof field === "string" ? field : getColumnName(field);
-    return new _WindowBuilder(this.fnKind, this.partitions, [
-      ...this.orders,
-      { field: fieldName, direction }
-    ]);
-  }
-  /**
-   * Finalize the window expression with an alias.
-   * Returns ExpressionSpec for use in columns().
-   *
-   * @param alias - Required alias for the result column
-   *
-   * @example
-   * columns(['id', rowNumber().orderBy('date').as('rn')])
-   */
-  as(alias) {
-    return {
-      __expr: true,
-      intent: this.toWindowIntent(alias)
-    };
-  }
-  /**
-   * Convert builder state to WindowIntent — produces the correct discriminated branch.
-   * - ranking → RankingWindowIntent (no field)
-   * - aggregate → AggregateWindowIntent (field required; COUNT uses '*' when omitted)
-   * - offset → OffsetWindowIntent (field required)
-   */
-  toWindowIntent(alias) {
-    const over = {};
-    if (this.partitions.length > 0) {
-      over.partitionBy = this.partitions;
-    }
-    if (this.orders.length > 0) {
-      over.orderBy = this.orders;
-    }
-    if (this.fnKind.type === "ranking") {
-      return {
-        kind: "window",
-        function: this.fnKind.fn,
-        alias,
-        over
-      };
-    }
-    if (this.fnKind.type === "offset") {
-      return {
-        kind: "window",
-        function: this.fnKind.fn,
-        field: this.fnKind.field,
-        alias,
-        over
-      };
-    }
-    const { field } = this.fnKind;
-    return {
-      kind: "window",
-      function: this.fnKind.fn,
-      ...field !== void 0 && { field },
-      alias,
-      over
-    };
-  }
-};
-function rowNumber() {
-  return WindowBuilder.ranking("row_number");
-}
-function rank() {
-  return WindowBuilder.ranking("rank");
-}
-function denseRank() {
-  return WindowBuilder.ranking("dense_rank");
-}
-function wSum(field) {
-  return WindowBuilder.aggregate("sum", field);
-}
-function wAvg(field) {
-  return WindowBuilder.aggregate("avg", field);
-}
-function wCount(field) {
-  return WindowBuilder.aggregate("count", field);
-}
-function wMin(field) {
-  return WindowBuilder.aggregate("min", field);
-}
-function wMax(field) {
-  return WindowBuilder.aggregate("max", field);
-}
-function lag(field) {
-  return WindowBuilder.offset("lag", field);
-}
-function lead(field) {
-  return WindowBuilder.offset("lead", field);
-}
-
-// src/dx/filters.ts
-function distinct(field) {
-  return { field, distinct: true };
-}
-function isDistinctField(value) {
-  return typeof value === "object" && value !== null && "field" in value && "distinct" in value && value.distinct === true;
-}
-function createComparisonFilter(operator) {
-  return (field, value) => ({
-    kind: "comparison",
-    field: getColumnName(field),
-    operator,
-    value
-  });
-}
-var eq = createComparisonFilter("eq");
-var neq = createComparisonFilter("neq");
-var gt = createComparisonFilter("gt");
-var gte = createComparisonFilter("gte");
-var lt = createComparisonFilter("lt");
-var lte = createComparisonFilter("lte");
-var isDistinctFrom = createComparisonFilter("isDistinctFrom");
-function like(field, pattern, options) {
-  const caseInsensitive = typeof options === "boolean" ? options : options?.caseInsensitive;
-  const escapeChar = typeof options === "object" ? options.escape : void 0;
-  const intent = {
-    kind: "like",
-    field: getColumnName(field),
-    pattern
-  };
-  const withCi = caseInsensitive !== void 0 ? { ...intent, caseInsensitive } : intent;
-  if (escapeChar !== void 0) {
-    return { ...withCi, escape: escapeChar };
-  }
-  return withCi;
-}
-function inArray(field, values) {
-  return { kind: "in", field: getColumnName(field), values };
-}
-function inSubquery(field, query) {
-  const expr = "build" in query ? query.build() : query;
-  return {
-    kind: "in",
-    field: getColumnName(field),
-    subquery: expr.toIntent()
-  };
-}
-function any(field, values) {
-  return { kind: "any", field: getColumnName(field), values };
-}
-function isNull(field) {
-  return { kind: "null", field: getColumnName(field), operator: "isNull" };
-}
-function isNotNull(field) {
-  return { kind: "null", field: getColumnName(field), operator: "isNotNull" };
-}
-function and(...conditions) {
-  const flatConditions = conditions.length === 1 && Array.isArray(conditions[0]) ? conditions[0] : conditions;
-  return { kind: "and", conditions: flatConditions };
-}
-function or(...conditions) {
-  const flatConditions = conditions.length === 1 && Array.isArray(conditions[0]) ? conditions[0] : conditions;
-  return { kind: "or", conditions: flatConditions };
-}
-function not(condition) {
-  return { kind: "not", condition };
-}
-function exists(relation, options) {
-  const result = { kind: "exists", relation };
-  if (options?.where !== void 0) {
-    result.where = options.where;
-  }
-  if (options?.recursive !== void 0) {
-    result.recursive = options.recursive;
-  }
-  if (options?.include !== void 0) {
-    result.include = options.include;
-  }
-  return result;
-}
-function notExists(relation, options) {
-  const result = {
-    kind: "notExists",
-    relation
-  };
-  if (options?.where !== void 0) {
-    result.where = options.where;
-  }
-  if (options?.recursive !== void 0) {
-    result.recursive = options.recursive;
-  }
-  if (options?.include !== void 0) {
-    result.include = options.include;
-  }
-  return result;
-}
-function rawExists(sq) {
-  const intent = "buildIntent" in sq ? sq.buildIntent() : sq.build().toIntent();
-  return { kind: "rawExists", subquery: intent };
-}
-function rawNotExists(sq) {
-  const intent = "buildIntent" in sq ? sq.buildIntent() : sq.build().toIntent();
-  return { kind: "rawNotExists", subquery: intent };
-}
-function getRelationName(rel) {
-  const meta = rel[RELATION_META];
-  if (!meta) {
-    throw new Error("Invalid RelationRef: missing RELATION_META");
-  }
-  return meta.target;
-}
-function every(relation, filter) {
-  const relationName = getRelationName(relation);
-  const where = filter(relation);
-  return {
-    kind: "relationFilter",
-    relation: relationName,
-    where,
-    mode: "every"
-  };
-}
-function none(relation, filter) {
-  const relationName = getRelationName(relation);
-  const where = filter(relation);
-  return {
-    kind: "relationFilter",
-    relation: relationName,
-    where,
-    mode: "none"
-  };
-}
-function some(relation, filter) {
-  const relationName = getRelationName(relation);
-  const where = filter(relation);
-  return {
-    kind: "relationFilter",
-    relation: relationName,
-    where,
-    mode: "some"
-  };
-}
-function coalesce(fields, as) {
-  if (fields.length === 0) {
-    throw new Error("coalesce() requires at least one field");
-  }
-  if (!as || as.trim() === "") {
-    throw new Error("coalesce() requires a non-empty alias");
-  }
-  for (const f of fields) {
-    validateIdentifier(f, "column");
-  }
-  validateIdentifier(as, "column");
-  return {
-    __expr: true,
-    intent: { kind: "coalesce", fields, as }
-  };
-}
-function raw(sqlFragment, as) {
-  if (typeof as !== "string" || as.trim().length === 0) {
-    throw new InvalidOperationError(
-      "raw",
-      "raw() requires an alias as second argument, e.g. raw('COUNT(*)', 'count')"
-    );
-  }
-  validateIdentifier(as, "column");
-  return {
-    __expr: true,
-    intent: { kind: "raw", sql: sqlFragment, as }
-  };
-}
-function col(column, alias) {
-  validateIdentifier(column, "column");
-  validateIdentifier(alias, "column");
-  return {
-    __expr: true,
-    intent: { kind: "columnAlias", column, alias }
-  };
-}
-function relationColumn(relation, column, as) {
-  if (!relation) {
-    throw new Error("relationColumn() requires a non-empty relation path");
-  }
-  for (const segment of relation.split(".")) {
-    validateIdentifier(segment, "relation");
-  }
-  if (column !== "*") {
-    validateIdentifier(column, "column");
-  }
-  validateIdentifier(as, "column");
-  return {
-    __expr: true,
-    intent: { kind: "relationColumn", relation, column, as }
-  };
-}
-var SQL_RAW_MARKER = /* @__PURE__ */ Symbol.for("dbsp:raw-sql");
-function sql(sqlFragment) {
-  if (!sqlFragment || sqlFragment.trim() === "") {
-    throw new Error("sql() requires a non-empty SQL fragment");
-  }
-  return { [SQL_RAW_MARKER]: true, sql: sqlFragment };
-}
-function isSqlRaw(value) {
-  return typeof value === "object" && value !== null && SQL_RAW_MARKER in value && value[SQL_RAW_MARKER] === true;
-}
-
 // src/dx/full-text-search.ts
 function fullTextSearch({
   query,