durcno 1.0.0-alpha.16 → 1.0.0-alpha.18

package/dist/bin.cjs

@@ -9631,7 +9631,9 @@ function orderTables(tables, order) {
     Object.entries(tables).map(([tableName, table]) => {
       const references = Object.values(table.columns).map(
         (column) => column.references ? `${column.references.schema}.${column.references.table}` : void 0
-      ).filter((table2) => table2 !== void 0);
+      ).filter(
+        (table2) => table2 !== void 0 && table2 !== tableName
+      );
       return [tableName, references];
     })
   );
@@ -10455,7 +10457,7 @@ async function status(options) {
 }
 
 // src/cli/index.ts
-program.version("1.0.0-alpha.15");
+program.version("1.0.0-alpha.17");
 var Options = {
   config: ["--config <path>", "Path to the config file"]
 };

package/dist/src/columns/common.d.mts

@@ -1,7 +1,7 @@
+import { AnyFilter } from "../filters/index.mjs";
 import { CheckExpression } from "../constraints/check.mjs";
 import { entityType } from "../symbols.mjs";
 import { AnyColumn, StdTable, StdTableColumn } from "../table.mjs";
-import { AnyFilter } from "../filters/index.mjs";
 import { Arg } from "../query-builders/pre.mjs";
 import { Query, QueryContext } from "../query-builders/query.mjs";
 import { Sql } from "../sql.mjs";

package/dist/src/constraints/check.d.mts

@@ -1,5 +1,5 @@
-import { AnyColumn, TableAnyColumn } from "../table.mjs";
 import { AnyFilter, Filter } from "../filters/index.mjs";
+import { AnyColumn, TableAnyColumn } from "../table.mjs";
 import { QueryContext } from "../query-builders/query.mjs";
 import { Sql } from "../sql.mjs";
 

package/dist/src/cte.d.mts

@@ -0,0 +1,16 @@
+import { VirtualTable } from "./virtual-table.mjs";
+import { AnyColumn } from "./table.mjs";
+
+//#region src/cte.d.ts
+declare class Cte<TName extends string, TColumns extends Record<string, AnyColumn>> extends VirtualTable<TName, TColumns> {
+  /** Phantom type — extracts `TName` safely through `CteWithColumns` intersections. */
+  readonly $cteName: TName;
+}
+type CteWithColumns<TName extends string, TColumns extends Record<string, AnyColumn>> = Cte<TName, TColumns> & TColumns;
+type AnyCteWithColumns = CteWithColumns<any, Record<any, any>>;
+/** Maps a tuple of `CteWithColumns` to an object keyed by CTE name. */
+type CtesByName<TCtes extends AnyCteWithColumns[]> = { [K in TCtes[number] as K extends {
+  $cteName: infer TName extends string;
+} ? TName : never]: K };
+//#endregion
+export { AnyCteWithColumns, Cte, CteWithColumns, CtesByName };

package/dist/src/cte.mjs

@@ -0,0 +1,5 @@
+import { VirtualTable } from "./virtual-table.mjs";
+//#region src/cte.ts
+var Cte = class extends VirtualTable {};
+//#endregion
+export { Cte };

package/dist/src/db.d.mts

@@ -1,7 +1,9 @@
 import { CamelToSnake, Valueof } from "./types.mjs";
-import { AnyColumn, AnyRelations, IsTableWC, Relations, TableWCorNever, TableWithColumns } from "./table.mjs";
+import { AnySubquery, InferQueryColumns } from "./virtual-table.mjs";
 import { SelectBuilder } from "./query-builders/select.mjs";
 import { FilterExpression } from "./filters/index.mjs";
+import { AnyColumn, AnyRelations, IsTableWC, Relations, TableWCorNever, TableWithColumns } from "./table.mjs";
+import { AnyCteWithColumns, CteWithColumns } from "./cte.mjs";
 import { Config } from "./index.mjs";
 import { AggregateQuery } from "./query-builders/aggregates.mjs";
 import { CountQuery } from "./query-builders/count.mjs";
@@ -13,6 +15,7 @@ import { InsertBuilder } from "./query-builders/insert.mjs";
 import { RawQuery } from "./query-builders/raw.mjs";
 import { RelationQueryBuilder } from "./query-builders/rq.mjs";
 import { UpdateBuilder } from "./query-builders/update.mjs";
+import { WithStatement } from "./query-builders/with.mjs";
 import { $Pool, QueryExecutor } from "./connectors/common.mjs";
 
 //#region src/db.d.ts
@@ -149,6 +152,26 @@ declare class Base<TTName extends string, TTables extends Record<TTName, TableWi
    * @returns A RawQuery instance that resolves to the query result (or transformed result if handler provided)
    */
   raw<TReturn = unknown>(query: string, args: (string | number | null)[] | undefined, rowsHandler: ((rows: any[]) => TReturn) | undefined): RawQuery<TReturn>;
+  /**
+   * Create a CTE definition by name.
+   * @param name The CTE name to be used in the WITH clause
+   * @returns An object with `.as()` to bind a subquery
+   *
+   * @example
+   * const activeCte = db.with("activeUsers").as(db.from(Users).select(...));
+   */
+  with<TCteName extends string>(name: TCteName): {
+    as: <TQuery extends AnySubquery>(query: TQuery) => CteWithColumns<TCteName, InferQueryColumns<TCteName, TQuery>>;
+  };
+  /**
+   * Attach one or more CTEs to a statement.
+   * @param ctes One or more CTE instances created via `db.with("name").as(...)`
+   * @returns A `WithStatement` to build the SELECT/INSERT/UPDATE/DELETE against
+   *
+   * @example
+   * const rows = await db.with(activeCte).from(ctes => ctes.activeUsers).select();
+   */
+  with<TCtes extends [AnyCteWithColumns, ...AnyCteWithColumns[]]>(...ctes: TCtes): WithStatement<TCtes, TPrepare>;
 }
 declare class DB<TTName extends string, TTables extends Record<TTName, TableWithColumns<string, string, Record<string, AnyColumn>>>, TAllRelations extends Record<StdTableFullName, AnyRelations>> extends Base<TTName, TTables, TAllRelations, false> {
   #private;

package/dist/src/db.mjs

@@ -1,5 +1,8 @@
 import { Query } from "./query-builders/query.mjs";
 import { is } from "./entity.mjs";
+import { Relations, Table } from "./table.mjs";
+import { bindVirtualTableColumns } from "./virtual-table.mjs";
+import { Cte } from "./cte.mjs";
 import { AggregateQuery } from "./query-builders/aggregates.mjs";
 import { CountQuery } from "./query-builders/count.mjs";
 import { DeleteQuery } from "./query-builders/delete.mjs";
@@ -11,7 +14,7 @@ import { RawQuery } from "./query-builders/raw.mjs";
 import { RelationQueryBuilder } from "./query-builders/rq.mjs";
 import { SelectBuilder } from "./query-builders/select.mjs";
 import { UpdateBuilder } from "./query-builders/update.mjs";
-import { Relations, Table } from "./table.mjs";
+import { WithStatement } from "./query-builders/with.mjs";
 //#region src/db.ts
 var Base = class {
 	#allRelations;
@@ -119,6 +122,12 @@ var Base = class {
 	raw(query, args = [], rowsHandler) {
 		return new RawQuery(query, args, rowsHandler, this.#getExecutor());
 	}
+	with(nameOrFirstCte, ...restCtes) {
+		if (typeof nameOrFirstCte === "string") return { as: (query) => {
+			return bindVirtualTableColumns(new Cte(nameOrFirstCte, query.getResolvedColumns(), query));
+		} };
+		return new WithStatement([nameOrFirstCte, ...restCtes], this.#getExecutor(), this.$.pre);
+	}
 };
 var DB = class extends Base {
 	#pool;

package/dist/src/filters/array.d.mts

@@ -1,5 +1,5 @@
-import { AnyColumn } from "../table.mjs";
 import { Filter } from "./index.mjs";
+import { AnyColumn } from "../table.mjs";
 import { Arg, IsArg } from "../query-builders/pre.mjs";
 import { Query, QueryContext } from "../query-builders/query.mjs";
 

package/dist/src/filters/index.d.mts

@@ -1,7 +1,7 @@
 import { BasicTypes, Or } from "../types.mjs";
-import { AnyColumn } from "../table.mjs";
-import { AnyScalarSqlFn } from "../functions/index.mjs";
+import { AnyAggregateSqlFn, AnyScalarSqlFn, AnySqlFn } from "../functions/index.mjs";
 import { SelectQuery } from "../query-builders/select.mjs";
+import { AnyColumn } from "../table.mjs";
 import { Arg, IsArg } from "../query-builders/pre.mjs";
 import { Query, QueryContext } from "../query-builders/query.mjs";
 import { Sql } from "../sql.mjs";
@@ -25,6 +25,16 @@ type AnyFilter = Filter<any, any>;
  */
 type FilterExpression<TScopeColumns extends AnyColumn, TPrepare extends boolean = false> = Filter<TScopeColumns, TPrepare extends true ? boolean : false> | Sql;
 type StdCondition = FilterExpression<AnyColumn>;
+/**
+ * A HAVING clause expression. Structurally identical to `FilterExpression` but
+ * signals intent — it is used in `.having()` rather than `.where()`.
+ *
+ * Note: TypeScript does not prevent aggregate `SqlFn` expressions from being
+ * passed to `.where()` at the type level (the `$Columns` phantom traces back to
+ * `AnyColumn` regardless of aggregate/scalar kind). PostgreSQL will reject such
+ * queries at runtime. This is a known limitation.
+ */
+type HavingExpression<TScopeColumns extends AnyColumn, TPrepare extends boolean = false> = FilterExpression<TScopeColumns, TPrepare>;
 type HasArg<T> = T extends {
   $HasArg: true;
 } ? true : false;
@@ -35,7 +45,7 @@ declare class ComparisonLeftIsColumn<TLeft extends AnyColumn, TOp extends string
   constructor(field: TLeft, op: TOp, right: TRight);
   toQuery(query: Query, ctx?: QueryContext): void;
 }
-declare class ComparisonLeftIsSqlFn<TLeft extends AnyScalarSqlFn, TOp extends string, TRight extends BasicTypes | AnyScalarSqlFn> extends Filter<TLeft["$Columns"] | (TRight extends AnyScalarSqlFn ? TRight["$Columns"] : never), HasArg<TLeft> extends true ? true : HasArg<TRight>> {
+declare class ComparisonLeftIsSqlFn<TLeft extends AnySqlFn, TOp extends string, TRight extends BasicTypes | AnySqlFn> extends Filter<TLeft["$Columns"] | (TRight extends AnyScalarSqlFn ? TRight["$Columns"] : never), HasArg<TLeft> extends true ? true : HasArg<TRight>> {
   readonly left: TLeft;
   readonly op: TOp;
   readonly right: TRight;
@@ -46,26 +56,38 @@ declare function eq<TLeft extends AnyColumn, TRight extends TLeft["ValType"]>(le
 declare function eq<TLeft extends AnyColumn, TRight extends Arg<TLeft["ValType"]> | AnyColumn | AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, "=", TRight>;
 declare function eq<TLeft extends AnyScalarSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "=", TRight>;
 declare function eq<TLeft extends AnyScalarSqlFn, TRight extends AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "=", TRight>;
+declare function eq<TLeft extends AnyAggregateSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "=", TRight>;
+declare function eq<TLeft extends AnyAggregateSqlFn, TRight extends AnyAggregateSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "=", TRight>;
 declare function ne<TLeft extends AnyColumn, TRight extends TLeft["ValType"]>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, "!=", TRight>;
 declare function ne<TLeft extends AnyColumn, TRight extends Arg<TLeft["ValType"]> | AnyColumn | AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, "!=", TRight>;
 declare function ne<TLeft extends AnyScalarSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "!=", TRight>;
 declare function ne<TLeft extends AnyScalarSqlFn, TRight extends AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "!=", TRight>;
+declare function ne<TLeft extends AnyAggregateSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "!=", TRight>;
+declare function ne<TLeft extends AnyAggregateSqlFn, TRight extends AnyAggregateSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "!=", TRight>;
 declare function gt<TLeft extends AnyColumn, TRight extends TLeft["ValType"]>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, ">", TRight>;
 declare function gt<TLeft extends AnyColumn, TRight extends Arg<TLeft["ValType"]> | AnyColumn | AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, ">", TRight>;
 declare function gt<TLeft extends AnyScalarSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, ">", TRight>;
 declare function gt<TLeft extends AnyScalarSqlFn, TRight extends AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, ">", TRight>;
+declare function gt<TLeft extends AnyAggregateSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, ">", TRight>;
+declare function gt<TLeft extends AnyAggregateSqlFn, TRight extends AnyAggregateSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, ">", TRight>;
 declare function gte<TLeft extends AnyColumn, TRight extends TLeft["ValType"]>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, ">=", TRight>;
 declare function gte<TLeft extends AnyColumn, TRight extends Arg<TLeft["ValType"]> | AnyColumn | AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, ">=", TRight>;
 declare function gte<TLeft extends AnyScalarSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, ">=", TRight>;
 declare function gte<TLeft extends AnyScalarSqlFn, TRight extends AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, ">=", TRight>;
+declare function gte<TLeft extends AnyAggregateSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, ">=", TRight>;
+declare function gte<TLeft extends AnyAggregateSqlFn, TRight extends AnyAggregateSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, ">=", TRight>;
 declare function lt<TLeft extends AnyColumn, TRight extends TLeft["ValType"]>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, "<", TRight>;
 declare function lt<TLeft extends AnyColumn, TRight extends Arg<TLeft["ValType"]> | AnyColumn | AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, "<", TRight>;
 declare function lt<TLeft extends AnyScalarSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "<", TRight>;
 declare function lt<TLeft extends AnyScalarSqlFn, TRight extends AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "<", TRight>;
+declare function lt<TLeft extends AnyAggregateSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "<", TRight>;
+declare function lt<TLeft extends AnyAggregateSqlFn, TRight extends AnyAggregateSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "<", TRight>;
 declare function lte<TLeft extends AnyColumn, TRight extends TLeft["ValType"]>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, "<=", TRight>;
 declare function lte<TLeft extends AnyColumn, TRight extends Arg<TLeft["ValType"]> | AnyColumn | AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsColumn<TLeft, "<=", TRight>;
 declare function lte<TLeft extends AnyScalarSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "<=", TRight>;
 declare function lte<TLeft extends AnyScalarSqlFn, TRight extends AnyScalarSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "<=", TRight>;
+declare function lte<TLeft extends AnyAggregateSqlFn, TRight extends BasicTypes>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "<=", TRight>;
+declare function lte<TLeft extends AnyAggregateSqlFn, TRight extends AnyAggregateSqlFn>(left: TLeft, right: TRight): ComparisonLeftIsSqlFn<TLeft, "<=", TRight>;
 declare class IsNullCondition<TCol extends AnyColumn> extends Filter<TCol, false> {
   readonly field: TCol;
   constructor(field: TCol);
@@ -78,7 +100,7 @@ declare class IsNotNullCondition<TCol extends AnyColumn> extends Filter<TCol, fa
   toQuery(query: Query, ctx?: QueryContext): void;
 }
 declare function isNotNull<TCol extends AnyColumn>(field: TCol): IsNotNullCondition<TCol>;
-type InSelectQuery<TArg extends boolean, TReturn> = SelectQuery<any, any, any, any, any, TArg, any, any, Record<string, TReturn>[]>;
+type InSelectQuery<TArg extends boolean, TReturn> = SelectQuery<any, any, any, any, any, TArg, any, any, any, any, Record<string, TReturn>[]>;
 declare class InCondition<TCol extends AnyColumn, TArg extends boolean> extends Filter<TCol, TArg> {
   readonly field: TCol;
   readonly values: TCol["ValType"][] | InSelectQuery<TArg, TCol["ValType"]>;
@@ -106,4 +128,4 @@ declare class OrCondition<TConditions extends (AnyFilter | Sql)[]> extends Filte
 }
 declare function or<TConditions extends (AnyFilter | Sql)[]>(...conditions: TConditions): OrCondition<TConditions>;
 //#endregion
-export { AnyFilter, Filter, FilterExpression, StdCondition, and, eq, gt, gte, isIn, isNotNull, isNull, lt, lte, ne, notIn, or };
+export { AnyFilter, Filter, FilterExpression, HavingExpression, StdCondition, and, eq, gt, gte, isIn, isNotNull, isNull, lt, lte, ne, notIn, or };

package/dist/src/filters/index.mjs

@@ -119,7 +119,7 @@ var InCondition = class extends Filter {
 		} else {
 			this.field.toQuery(query, ctx);
 			query.sql += " IN (";
-			query.sql += this.values.toQuery();
+			this.values.toQuery(query);
 			query.sql += ")";
 		}
 	}

package/dist/src/filters/string.d.mts

@@ -1,5 +1,5 @@
-import { Column } from "../columns/common.mjs";
 import { Filter } from "./index.mjs";
+import { Column } from "../columns/common.mjs";
 import { Arg, IsArg } from "../query-builders/pre.mjs";
 import { Query, QueryContext } from "../query-builders/query.mjs";
 

package/dist/src/functions/aggregate.d.mts

@@ -1,5 +1,5 @@
-import { AnyColumn } from "../table.mjs";
 import { AnyScalarSqlFn, ExprColumns, HasArg, SqlFn } from "./index.mjs";
+import { AnyColumn } from "../table.mjs";
 import { Query, QueryContext } from "../query-builders/query.mjs";
 
 //#region src/functions/aggregate.d.ts
@@ -36,6 +36,9 @@ declare class CountFn<TExpr extends AnyColumn> extends SqlFn<TExpr, false, "aggr
   private readonly expr;
   readonly isAggregate = true;
   constructor(expr: TExpr);
+  toDriverValue(value: number | null): unknown;
+  toSQLValue(value: number | null): string;
+  fromDriverValue(value: unknown): number | null;
   /** Appends `count(expr)` to the query SQL. */
   toQuery(query: Query, ctx?: QueryContext): void;
 }
@@ -50,6 +53,9 @@ declare class CountFn<TExpr extends AnyColumn> extends SqlFn<TExpr, false, "aggr
  */
 declare class CountStarFn extends SqlFn<never, false, "aggregate", "numeric", number> {
   readonly isAggregate = true;
+  toDriverValue(value: number | null): unknown;
+  toSQLValue(value: number | null): string;
+  fromDriverValue(value: unknown): number | null;
   /** Appends `count(*)` to the query SQL. */
   toQuery(query: Query, _ctx?: QueryContext): void;
 }
@@ -66,6 +72,9 @@ declare class CountDistinctFn<TExpr extends AnyColumn> extends SqlFn<TExpr, fals
   private readonly expr;
   readonly isAggregate = true;
   constructor(expr: TExpr);
+  toDriverValue(value: number | null): unknown;
+  toSQLValue(value: number | null): string;
+  fromDriverValue(value: unknown): number | null;
   /** Appends `count(DISTINCT expr)` to the query SQL. */
   toQuery(query: Query, ctx?: QueryContext): void;
 }
@@ -111,6 +120,9 @@ declare class SumFn<TExpr extends NumericAggregateInput> extends SqlFn<ExprColum
   private readonly expr;
   readonly isAggregate = true;
   constructor(expr: TExpr);
+  toDriverValue(value: TExpr["$"]["TsType"] | null): unknown;
+  toSQLValue(value: TExpr["$"]["TsType"] | null): string;
+  fromDriverValue(value: unknown): TExpr["$"]["TsType"] | null;
   /** Appends `sum(expr)` to the query SQL. */
   toQuery(query: Query, ctx?: QueryContext): void;
 }
@@ -140,12 +152,12 @@ declare class AvgFn<TExpr extends NumericAggregateInput> extends SqlFn<ExprColum
   private readonly expr;
   readonly isAggregate = true;
   constructor(expr: TExpr);
+  toDriverValue(value: TExpr["$"]["TsType"] | null): unknown;
+  toSQLValue(value: TExpr["$"]["TsType"] | null): string;
   /**
    * Preserves the raw PostgreSQL `numeric` string (e.g. `"2.5000000000"`).
-   * The default `SqlFn.fromDriver` would coerce numeric strings to `number`,
-   * which contradicts the declared `string | null` return type.
    */
-  fromDriver(value: unknown): string | null;
+  fromDriverValue(value: unknown): TExpr["$"]["TsType"] | null;
   /** Appends `avg(expr)` to the query SQL. */
   toQuery(query: Query, ctx?: QueryContext): void;
 }
@@ -176,11 +188,13 @@ declare class MinFn<TExpr extends AggregateInput> extends SqlFn<ExprColumns<TExp
   private readonly expr;
   readonly isAggregate = true;
   constructor(expr: TExpr);
+  toDriverValue(value: TExpr["$"]["TsType"] | null): unknown;
+  toSQLValue(value: TExpr["$"]["TsType"] | null): string;
   /**
-   * Delegates to the inner expression's own `fromDriver` so that the result
+   * Delegates to the inner expression's own conversion so that the result
    * is deserialized to the same TypeScript type as the wrapped column/function.
    */
-  fromDriver(value: unknown): TExpr["$"]["TsType"] | null;
+  fromDriverValue(value: unknown): TExpr["$"]["TsType"] | null;
   /** Appends `min(expr)` to the query SQL. */
   toQuery(query: Query, ctx?: QueryContext): void;
 }
@@ -211,11 +225,13 @@ declare class MaxFn<TExpr extends AggregateInput> extends SqlFn<ExprColumns<TExp
   private readonly expr;
   readonly isAggregate = true;
   constructor(expr: TExpr);
+  toDriverValue(value: TExpr["$"]["TsType"] | null): unknown;
+  toSQLValue(value: TExpr["$"]["TsType"] | null): string;
   /**
-   * Delegates to the inner expression's own `fromDriver` so that the result
+   * Delegates to the inner expression's own conversion so that the result
    * is deserialized to the same TypeScript type as the wrapped column/function.
    */
-  fromDriver(value: unknown): TExpr["$"]["TsType"] | null;
+  fromDriverValue(value: unknown): TExpr["$"]["TsType"] | null;
   /** Appends `max(expr)` to the query SQL. */
   toQuery(query: Query, ctx?: QueryContext): void;
 }

package/dist/src/functions/aggregate.mjs

@@ -1,4 +1,5 @@
 import { SqlFn } from "./index.mjs";
+import { isCol } from "../entity.mjs";
 //#region src/functions/aggregate.ts
 /**
 * SQL aggregate expression: `count(col)`
@@ -17,6 +18,15 @@ var CountFn = class extends SqlFn {
 		super();
 		this.expr = expr;
 	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		return SqlFn._numericToSQL(value);
+	}
+	fromDriverValue(value) {
+		return SqlFn._numericFromDriver(value);
+	}
 	/** Appends `count(expr)` to the query SQL. */
 	toQuery(query, ctx) {
 		query.sql += "count(";
@@ -35,6 +45,15 @@ var CountFn = class extends SqlFn {
 */
 var CountStarFn = class extends SqlFn {
 	isAggregate = true;
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		return SqlFn._numericToSQL(value);
+	}
+	fromDriverValue(value) {
+		return SqlFn._numericFromDriver(value);
+	}
 	/** Appends `count(*)` to the query SQL. */
 	toQuery(query, _ctx) {
 		query.sql += "count(*)";
@@ -55,6 +74,15 @@ var CountDistinctFn = class extends SqlFn {
 		super();
 		this.expr = expr;
 	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		return SqlFn._numericToSQL(value);
+	}
+	fromDriverValue(value) {
+		return SqlFn._numericFromDriver(value);
+	}
 	/** Appends `count(DISTINCT expr)` to the query SQL. */
 	toQuery(query, ctx) {
 		query.sql += "count(DISTINCT ";
@@ -96,6 +124,17 @@ var SumFn = class extends SqlFn {
 		super();
 		this.expr = expr;
 	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		return SqlFn._numericToSQL(value);
+	}
+	fromDriverValue(value) {
+		if (value === null) return null;
+		if (typeof value === "bigint") return value;
+		return Number(value);
+	}
 	/** Appends `sum(expr)` to the query SQL. */
 	toQuery(query, ctx) {
 		query.sql += "sum(";
@@ -133,12 +172,16 @@ var AvgFn = class extends SqlFn {
 		super();
 		this.expr = expr;
 	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		return SqlFn._stringToSQL(value);
+	}
 	/**
 	* Preserves the raw PostgreSQL `numeric` string (e.g. `"2.5000000000"`).
-	* The default `SqlFn.fromDriver` would coerce numeric strings to `number`,
-	* which contradicts the declared `string | null` return type.
 	*/
-	fromDriver(value) {
+	fromDriverValue(value) {
 		if (value === null) return null;
 		return value;
 	}
@@ -180,13 +223,21 @@ var MinFn = class extends SqlFn {
 		super();
 		this.expr = expr;
 	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		if (isCol(this.expr)) return this.expr.toSQLScalar(value);
+		return this.expr.toSQLValue(value);
+	}
 	/**
-	* Delegates to the inner expression's own `fromDriver` so that the result
+	* Delegates to the inner expression's own conversion so that the result
 	* is deserialized to the same TypeScript type as the wrapped column/function.
 	*/
-	fromDriver(value) {
+	fromDriverValue(value) {
 		if (value === null) return null;
-		return this.expr.fromDriver(value);
+		if (isCol(this.expr)) return this.expr.fromDriverScalar(value);
+		return this.expr.fromDriverValue(value);
 	}
 	/** Appends `min(expr)` to the query SQL. */
 	toQuery(query, ctx) {
@@ -226,13 +277,21 @@ var MaxFn = class extends SqlFn {
 		super();
 		this.expr = expr;
 	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		if (isCol(this.expr)) return this.expr.toSQLScalar(value);
+		return this.expr.toSQLValue(value);
+	}
 	/**
-	* Delegates to the inner expression's own `fromDriver` so that the result
+	* Delegates to the inner expression's own conversion so that the result
 	* is deserialized to the same TypeScript type as the wrapped column/function.
 	*/
-	fromDriver(value) {
+	fromDriverValue(value) {
 		if (value === null) return null;
-		return this.expr.fromDriver(value);
+		if (isCol(this.expr)) return this.expr.fromDriverScalar(value);
+		return this.expr.fromDriverValue(value);
 	}
 	/** Appends `max(expr)` to the query SQL. */
 	toQuery(query, ctx) {

package/dist/src/functions/arithmetic.d.mts

@@ -0,0 +1,67 @@
+import { Or } from "../types.mjs";
+import { AnySqlFn, ExprColumns, HasArg, SqlFn } from "./index.mjs";
+import { AnyScalarColumn } from "../table.mjs";
+import { Arg, IsArg } from "../query-builders/pre.mjs";
+import { Query, QueryContext } from "../query-builders/query.mjs";
+
+//#region src/functions/arithmetic.d.ts
+/**
+ * Union of every valid operand for arithmetic operators:
+ * a numeric column or SqlFn, a plain number literal, or an `Arg<number>`.
+ */
+type NumericOperand = ((AnyScalarColumn | AnySqlFn) & {
+  $: {
+    PgType: "numeric";
+  };
+}) | number | Arg<number>;
+/**
+ * Computes the `THasArg` slot for a two-operand arithmetic expression.
+ * Resolves to `true` if either operand embeds an `Arg` or is itself an `Arg`.
+ */
+type BinaryOpHasArg<TLeft extends NumericOperand, TRight extends NumericOperand> = Or<Or<HasArg<TLeft>, IsArg<TLeft>>, Or<HasArg<TRight>, IsArg<TRight>>>;
+declare class AddFn<TLeft extends NumericOperand, TRight extends NumericOperand> extends SqlFn<ExprColumns<TLeft> | ExprColumns<TRight>, BinaryOpHasArg<TLeft, TRight>, "scalar", "numeric", number> {
+  private readonly left;
+  private readonly right;
+  constructor(left: TLeft, right: TRight);
+  toDriverValue(value: number | null): unknown;
+  toSQLValue(value: number | null): string;
+  fromDriverValue(value: unknown): number | null;
+  toQuery(query: Query, ctx?: QueryContext): void;
+}
+/** Returns the sum of two numeric expressions. */
+declare function add<TLeft extends NumericOperand, TRight extends NumericOperand>(left: TLeft, right: TRight): AddFn<TLeft, TRight>;
+declare class SubFn<TLeft extends NumericOperand, TRight extends NumericOperand> extends SqlFn<ExprColumns<TLeft> | ExprColumns<TRight>, BinaryOpHasArg<TLeft, TRight>, "scalar", "numeric", number> {
+  private readonly left;
+  private readonly right;
+  constructor(left: TLeft, right: TRight);
+  toDriverValue(value: number | null): unknown;
+  toSQLValue(value: number | null): string;
+  fromDriverValue(value: unknown): number | null;
+  toQuery(query: Query, ctx?: QueryContext): void;
+}
+/** Returns the difference of two numeric expressions. */
+declare function sub<TLeft extends NumericOperand, TRight extends NumericOperand>(left: TLeft, right: TRight): SubFn<TLeft, TRight>;
+declare class MulFn<TLeft extends NumericOperand, TRight extends NumericOperand> extends SqlFn<ExprColumns<TLeft> | ExprColumns<TRight>, BinaryOpHasArg<TLeft, TRight>, "scalar", "numeric", number> {
+  private readonly left;
+  private readonly right;
+  constructor(left: TLeft, right: TRight);
+  toDriverValue(value: number | null): unknown;
+  toSQLValue(value: number | null): string;
+  fromDriverValue(value: unknown): number | null;
+  toQuery(query: Query, ctx?: QueryContext): void;
+}
+/** Returns the product of two numeric expressions. */
+declare function mul<TLeft extends NumericOperand, TRight extends NumericOperand>(left: TLeft, right: TRight): MulFn<TLeft, TRight>;
+declare class DivFn<TLeft extends NumericOperand, TRight extends NumericOperand> extends SqlFn<ExprColumns<TLeft> | ExprColumns<TRight>, BinaryOpHasArg<TLeft, TRight>, "scalar", "numeric", number> {
+  private readonly left;
+  private readonly right;
+  constructor(left: TLeft, right: TRight);
+  toDriverValue(value: number | null): unknown;
+  toSQLValue(value: number | null): string;
+  fromDriverValue(value: unknown): number | null;
+  toQuery(query: Query, ctx?: QueryContext): void;
+}
+/** Returns the quotient of two numeric expressions. */
+declare function div<TLeft extends NumericOperand, TRight extends NumericOperand>(left: TLeft, right: TRight): DivFn<TLeft, TRight>;
+//#endregion
+export { add, div, mul, sub };