durcno 1.0.0-alpha.16 → 1.0.0-alpha.17

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.16");
 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 { 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";

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 };

package/dist/src/functions/arithmetic.mjs

@@ -0,0 +1,123 @@
+import { SqlFn } from "./index.mjs";
+import { Arg } from "../query-builders/pre.mjs";
+import { is } from "../entity.mjs";
+//#region src/functions/arithmetic.ts
+/**
+* Appends a single numeric operand fragment to the query.
+* Handles `Arg<number>`, literal `number`, and column/SqlFn operands.
+*/
+function numericExprToQuery(query, ctx, operand) {
+	if (is(operand, Arg)) query.addArg(operand);
+	else if (typeof operand === "number") query.sql += operand.toString();
+	else operand.toQuery(query, ctx);
+}
+var AddFn = class extends SqlFn {
+	constructor(left, right) {
+		super();
+		this.left = left;
+		this.right = right;
+	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		return SqlFn._numericToSQL(value);
+	}
+	fromDriverValue(value) {
+		return SqlFn._numericFromDriver(value);
+	}
+	toQuery(query, ctx) {
+		query.sql += "(";
+		numericExprToQuery(query, ctx, this.left);
+		query.sql += " + ";
+		numericExprToQuery(query, ctx, this.right);
+		query.sql += ")";
+	}
+};
+/** Returns the sum of two numeric expressions. */
+function add(left, right) {
+	return new AddFn(left, right);
+}
+var SubFn = class extends SqlFn {
+	constructor(left, right) {
+		super();
+		this.left = left;
+		this.right = right;
+	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		return SqlFn._numericToSQL(value);
+	}
+	fromDriverValue(value) {
+		return SqlFn._numericFromDriver(value);
+	}
+	toQuery(query, ctx) {
+		query.sql += "(";
+		numericExprToQuery(query, ctx, this.left);
+		query.sql += " - ";
+		numericExprToQuery(query, ctx, this.right);
+		query.sql += ")";
+	}
+};
+/** Returns the difference of two numeric expressions. */
+function sub(left, right) {
+	return new SubFn(left, right);
+}
+var MulFn = class extends SqlFn {
+	constructor(left, right) {
+		super();
+		this.left = left;
+		this.right = right;
+	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		return SqlFn._numericToSQL(value);
+	}
+	fromDriverValue(value) {
+		return SqlFn._numericFromDriver(value);
+	}
+	toQuery(query, ctx) {
+		query.sql += "(";
+		numericExprToQuery(query, ctx, this.left);
+		query.sql += " * ";
+		numericExprToQuery(query, ctx, this.right);
+		query.sql += ")";
+	}
+};
+/** Returns the product of two numeric expressions. */
+function mul(left, right) {
+	return new MulFn(left, right);
+}
+var DivFn = class extends SqlFn {
+	constructor(left, right) {
+		super();
+		this.left = left;
+		this.right = right;
+	}
+	toDriverValue(value) {
+		return value;
+	}
+	toSQLValue(value) {
+		return SqlFn._numericToSQL(value);
+	}
+	fromDriverValue(value) {
+		return SqlFn._numericFromDriver(value);
+	}
+	toQuery(query, ctx) {
+		query.sql += "(";
+		numericExprToQuery(query, ctx, this.left);
+		query.sql += " / ";
+		numericExprToQuery(query, ctx, this.right);
+		query.sql += ")";
+	}
+};
+/** Returns the quotient of two numeric expressions. */
+function div(left, right) {
+	return new DivFn(left, right);
+}
+//#endregion
+export { add, div, mul, sub };

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

@@ -7,14 +7,10 @@ import { Sql } from "../sql.mjs";
  * Abstract base class for typed SQL functions.
  *
  * Analogous to `Filter` but for expressions that produce a **value** rather
- * than a boolean predicate. A `SqlFn` can be used in:
- * - `.select({ alias: sqlFn })` — adds a computed column to the result
- * - `.orderBy(asc(sqlFn))` — orders by a computed expression
- * - `.where(lt(sqlFn, value))` — compares the expression in a WHERE clause
+ * than a boolean predicate.
  *
  * @template TColumn - The scoped table column(s) this expression references.
  * @template THasArg - `true` when this expression embeds at least one `Arg` placeholder.
- *   Set to `true` in concrete subclasses that accept `Arg` values; defaults to `false`.
  *   Arg-bearing expressions are only accepted in prepared queries (`db.prepare()`).
  * @template TFnType - `"aggregate"` for aggregate functions (e.g. `count`, `sum`),
  *   `"scalar"` for scalar functions (e.g. `lower`, `abs`). Defaults to the union.
@@ -46,19 +42,20 @@ declare abstract class SqlFn<TColumn extends AnyColumn, THasArg extends boolean
   /** Appends the SQL fragment for this expression to the query (no trailing semicolon). */
   abstract toQuery(query: Query, ctx?: QueryContext): void;
   toSQL(): string;
-  /**
-   * Converts a raw driver value returned from PostgreSQL into the TypeScript
-   * value declared by `TTsType`.
-   *
-   * The default implementation covers the common cases:
-   * - `null` → `null`
-   * - `bigint` → `bigint` (passed through as-is to preserve precision)
-   * - numeric string (e.g. `"42"`, `"3"`) → `Number(value)`
-   * - anything else → `value` as-is
-   *
-   * Subclasses can override this method to provide custom conversions.
-   */
-  fromDriver(value: unknown): TTsType;
+  /** Converts a TypeScript value to a raw driver value (write path). */
+  abstract toDriverValue(value: TTsType | null): unknown;
+  /** Converts a TypeScript value to a SQL literal string. */
+  abstract toSQLValue(value: TTsType | null): string;
+  /** Converts a raw PostgreSQL driver value to the TypeScript type `TTsType`. */
+  abstract fromDriverValue(value: unknown): TTsType | null;
+  /** Default implementation for numeric-returning functions. */
+  protected static _numericFromDriver(value: unknown): number | null;
+  /** Default implementation for string-returning functions. */
+  protected static _stringFromDriver(value: unknown): string | null;
+  /** Default SQL literal for a numeric value. */
+  protected static _numericToSQL(value: number | bigint | null): string;
+  /** Default SQL literal for a string value. */
+  protected static _stringToSQL(value: string | null): string;
 }
 type AnySqlFn = SqlFn<any, any, any, any, any>;
 type AnyScalarSqlFn = SqlFn<any, any, "scalar", any, any>;