@atscript/db-sql-tools 0.1.147 → 0.1.149

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let _uniqu_core = require("@uniqu/core");
 let _atscript_db = require("@atscript/db");
+let _uniqu_core = require("@uniqu/core");
 let _atscript_db_agg = require("@atscript/db/agg");
 //#region src/dialect.ts
 /**
@@ -24,6 +24,32 @@ function havingGroupRef(dialect, expr, alias) {
 	return dialect.bucketAliasInHaving ? dialect.quoteIdentifier(alias) : expr;
 }
 /**
+* Runs `fn`, rethrowing a driver error as the `DbError`
+* {@link SqlDialect.mapQueryError} maps it to (any other error unchanged).
+* `controls` of the query tell whether it has arithmetic expressions.
+* @since 0.1.148
+*/
+async function mapQueryErrors(dialect, fn, controls) {
+	try {
+		return await fn();
+	} catch (error) {
+		const select = controls?.$select;
+		const arithmetic = !!(select?.exprAggregates?.length || select?.exprs?.length);
+		throw dialect.mapQueryError?.(error, arithmetic) ?? error;
+	}
+}
+/**
+* One `ORDER BY` key with the uniform "NULL is the smallest value" ordering:
+* `<expr> ASC` / `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a
+* dialect where NULL sorts largest ({@link SqlDialect.nullsSortLargest}).
+* Shared by first-row joins and `first` / `last` aggregates.
+* @since 0.1.148
+*/
+function orderKeySql(dialect, expr, desc) {
+	const nulls = dialect.nullsSortLargest ? desc ? " NULLS LAST" : " NULLS FIRST" : "";
+	return `${expr} ${desc ? "DESC" : "ASC"}${nulls}`;
+}
+/**
 * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
 * {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
 *
@@ -55,6 +81,67 @@ const EMPTY_OR = {
 	params: []
 };
 //#endregion
+//#region src/arith.ts
+/**
+* Renders a computed expression tree (`@db.compute` on a view, or a query-time
+* arithmetic `$select` entry) as SQL, in IEEE double on every dialect: each
+* literal is cast with {@link SqlDialect.castDouble}; `+ - *` render as
+* `(l op r)`, `/` as `(l / NULLIF(r, 0))` (division by zero is NULL), unary
+* minus as `(-x)` and `coalesce` as `COALESCE(…)`. `leaf` renders a field
+* reference as raw SQL, which is cast to double here — or, as `{ double }`,
+* SQL that already is a double (a nested computed column) and stays as is.
+*
+* The one renderer of both paths, so declared and query-time arithmetic
+* cannot diverge.
+*
+* @param fail - the error to throw for a failure (default `DbError`:
+*   `AGG_EXPR_NOT_SUPPORTED` without `castDouble`, `INVALID_QUERY` for a
+*   non-finite literal).
+* @since 0.1.148
+*/
+function renderArith(dialect, node, leaf, fail = defaultFailure) {
+	const cast = dialect.castDouble?.bind(dialect);
+	if (!cast) throw fail("no-cast");
+	const render = (e) => {
+		if (typeof e === "number") {
+			if (!Number.isFinite(e)) throw fail("non-finite");
+			return cast(String(e));
+		}
+		if ("field" in e) {
+			const sql = leaf(e.field);
+			return typeof sql === "string" ? cast(sql) : sql.double;
+		}
+		const args = e.args.map(render);
+		switch (e.op) {
+			case "neg": return `(-${args[0]})`;
+			case "coalesce": return `COALESCE(${args.join(", ")})`;
+			case "/": return `(${args[0]} / NULLIF(${args[1]}, 0))`;
+			default: return `(${args[0]} ${e.op} ${args[1]})`;
+		}
+	};
+	return render(node);
+}
+function defaultFailure(reason) {
+	return reason === "no-cast" ? (0, _atscript_db.aggregateExpressionsNotSupported)() : new _atscript_db.DbError("INVALID_QUERY", [{
+		path: "$select",
+		message: "Expression literal is not finite"
+	}]);
+}
+/** The error of a numeric overflow that is no arithmetic expression's (`INVALID_QUERY`, `path` `""`). */
+function numericOutOfRangeError() {
+	return new _atscript_db.DbError("INVALID_QUERY", [{
+		path: "",
+		message: "Numeric value out of range"
+	}]);
+}
+/** The error of a double overflow in aggregate arithmetic (`INVALID_QUERY`, `path` `$select`). */
+function arithOverflowError() {
+	return new _atscript_db.DbError("INVALID_QUERY", [{
+		path: "$select",
+		message: "Arithmetic overflow"
+	}]);
+}
+//#endregion
 //#region src/filter-builder.ts
 /**
 * Creates a dialect-specific filter visitor for `walkFilter`.
@@ -428,15 +515,23 @@ const AGG_FN_SQL = {
 */
 function renderAggCall(fn, arg, path) {
 	(0, _atscript_db_agg.assertAggregateFn)(fn, path);
-	return fn === "countDistinct" ? `COUNT(DISTINCT ${arg})` : `${AGG_FN_SQL[fn]}(${arg})`;
+	if (fn === "countDistinct") return `COUNT(DISTINCT ${arg})`;
+	return `${AGG_FN_SQL[fn]}(${arg})`;
 }
-/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)` / `COUNT(DISTINCT "region")`. */
-function aggFnSql(dialect, expr) {
-	const field = expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field);
-	return renderAggCall(expr.$fn, field);
+/**
+* `MIN` / `MAX` of a column the engine may not aggregate directly: a boolean
+* on a dialect with {@link SqlDialect.booleanAggregates} (PostgreSQL has no
+* `MIN(boolean)`) renders its stand-in.
+*/
+function pickSql(dialect, select, fn, column, sql) {
+	const bool = select?.sources.get(column)?.designType === "boolean" ? dialect.booleanAggregates?.[fn] : void 0;
+	return bool ? `${bool}(${sql})` : renderAggCall(fn, sql);
 }
-function buildAggExpr(dialect, expr) {
-	return `${aggFnSql(dialect, expr)} AS ${dialect.quoteIdentifier((0, _atscript_db_agg.resolveAlias)(expr))}`;
+/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)` / `COUNT(DISTINCT "region")`. */
+function aggFnSql(dialect, select, expr) {
+	if (expr.$field === "*") return renderAggCall(expr.$fn, "*");
+	const field = dialect.quoteIdentifier(expr.$field);
+	return expr.$fn === "min" || expr.$fn === "max" ? pickSql(dialect, select, expr.$fn, expr.$field, field) : renderAggCall(expr.$fn, field);
 }
 const BUCKET_UNIT_SET = new Set(_uniqu_core.BUCKET_UNITS);
 const WEEK_START_SET = new Set(_uniqu_core.WEEK_STARTS);
@@ -484,25 +579,52 @@ function groupKeySql(dialect, controls, key) {
 	const bucket = controls.$select?.bucketByAlias(key);
 	return bucket ? bucketSql(dialect, bucket) : dialect.quoteIdentifier(key);
 }
+/** Alias of the derived table `first` / `last` aggregates read from. */
+const ROWS_ALIAS = "__as_rows";
+/** The derived-table column of the `i`-th `first` / `last` entry. */
+const firstLastColumn = (i) => `__as_fl${i}`;
+/**
+* The SQL each computed alias stands for where an alias is not usable
+* (HAVING; other expressions): an aggregate's call, a `first` / `last`
+* derived column (aggregated: constant within its group), a row-level
+* expression aggregate's call, and every group-level expression rendered over
+* those (in dependency order, operands cast to double). A grouped column
+* renders as its quoted name.
+*/
+function aliasSqlMap(dialect, controls) {
+	const map = /* @__PURE__ */ new Map();
+	const select = controls.$select;
+	const quote = (name) => dialect.quoteIdentifier(name);
+	for (const expr of select?.aggregates ?? []) map.set((0, _atscript_db_agg.resolveAlias)(expr), aggFnSql(dialect, select, expr));
+	for (const e of select?.exprAggregates ?? []) map.set(e.alias, renderAggCall(e.fn, renderArith(dialect, e.expr, quote)));
+	(select?.firstLast ?? []).forEach((fl, i) => {
+		const col = quote(firstLastColumn(i));
+		map.set(fl.alias, dialect.anyValue ? dialect.anyValue(col, select?.sources.get(fl.column)) : renderAggCall("min", col));
+	});
+	for (const e of select?.exprs ?? []) map.set(e.alias, renderArith(dialect, e.expr, (name) => map.get(name) ?? quote(name)));
+	return map;
+}
 /**
 * ` HAVING <predicate>` (leading space) + params for `controls.$having`, or
 * `undefined` when there is nothing to render. Shared by the row and the
 * count builders so both filter the same group set.
 *
-* A key that names an aggregate alias (`$as`, else `fn_field`) renders the
-* aggregate expression itself — `SUM("amount") > ?` — because PostgreSQL does
-* not allow a SELECT alias in HAVING (MySQL and SQLite tolerate it, so the
-* expression form keeps all three identical). A calendar-bucket alias renders
-* its bucket expression ({@link groupKeySql}), or its quoted alias when the
-* dialect sets `SqlDialect.bucketAliasInHaving` (`havingGroupRef`). Other keys
-* (grouped columns) render as plain columns.
+* A key that names a computed alias (`$as`, else `fn_field`) renders what the
+* alias stands for — `SUM("amount") > ?`, an expression's arithmetic — because
+* PostgreSQL does not allow a SELECT alias in HAVING (MySQL and SQLite
+* tolerate it, so the expression form keeps all three identical). A
+* calendar-bucket alias renders its bucket expression ({@link groupKeySql}),
+* or its quoted alias when the dialect sets `SqlDialect.bucketAliasInHaving`
+* (`havingGroupRef`). Other keys (grouped columns) render as plain columns.
+* `aliasSql` is the query's {@link aliasSqlMap} when the caller has built it.
 */
-function havingClause(dialect, controls) {
+function havingClause(dialect, controls, aliasSql) {
 	const having = controls.$having;
 	if (!having) return void 0;
-	const exprByAlias = /* @__PURE__ */ new Map();
-	for (const expr of controls.$select?.aggregates ?? []) exprByAlias.set((0, _atscript_db_agg.resolveAlias)(expr), aggFnSql(dialect, expr));
+	const exprByAlias = aliasSql ?? aliasSqlMap(dialect, controls);
+	const refs = /* @__PURE__ */ new Set();
 	const fragment = (0, _uniqu_core.walkFilter)(having, createFilterVisitor(dialect, { columnRef: (field) => {
+		refs.add(field);
 		const aggExpr = exprByAlias.get(field);
 		if (aggExpr) return aggExpr;
 		const bucket = controls.$select?.bucketByAlias(field);
@@ -511,43 +633,103 @@ function havingClause(dialect, controls) {
 	if (!fragment || fragment.sql === EMPTY_AND.sql) return void 0;
 	return {
 		sql: ` HAVING ${fragment.sql}`,
-		params: fragment.params
+		params: fragment.params,
+		refs
 	};
 }
 /** `<bucket expr> AS "alias"` for every calendar bucket in `$select`. */
 function bucketSelectParts(dialect, controls) {
 	return (controls.$select?.buckets ?? []).map((bucket) => `${bucketSql(dialect, bucket)} AS ${dialect.quoteIdentifier(bucket.alias)}`);
 }
+/** ` GROUP BY <keys>` (leading space), or `""` for the whole table as one group. */
+function groupByClause(dialect, controls) {
+	const keys = controls.$groupBy ?? [];
+	return keys.length ? ` GROUP BY ${keys.map((key) => groupKeySql(dialect, controls, key)).join(", ")}` : "";
+}
+/** Whether any of the HAVING keys is a `first` / `last` alias, or an expression over one. */
+function readsFirstLast(select, refs) {
+	if (!select?.firstLast) return false;
+	const firstLast = new Set(select.firstLast.map((fl) => fl.alias));
+	const names = new Map((select.exprs ?? []).map((e) => [e.alias, e.names]));
+	const visit = (name, seen) => {
+		if (firstLast.has(name)) return true;
+		const deps = names.get(name);
+		if (!deps || seen.has(name)) return false;
+		seen.add(name);
+		return deps.some((dep) => visit(dep, seen));
+	};
+	return [...refs].some((key) => visit(key, /* @__PURE__ */ new Set()));
+}
+/**
+* The columns the outer query reads from the derived table of a `first` /
+* `last` aggregate: group keys (a bucket's source for its alias), plain
+* `$select` fields, aggregate fields and the leaves of row-level expressions.
+* The `$rowOrder` columns and the `first` / `last` sources stay inside the
+* window; a group-level expression, `$having` and `$sort` read aliases or
+* group keys only.
+*/
+function rowColumns(controls) {
+	const select = controls.$select;
+	const columns = /* @__PURE__ */ new Set();
+	for (const key of controls.$groupBy ?? []) if (!select?.bucketByAlias(key)) columns.add(key);
+	for (const bucket of select?.buckets ?? []) columns.add(bucket.field);
+	for (const field of select?.asArray ?? []) columns.add(field);
+	for (const expr of select?.aggregates ?? []) if (expr.$field !== "*") columns.add(expr.$field);
+	for (const e of select?.exprAggregates ?? []) for (const name of e.names) columns.add(name);
+	return [...columns];
+}
+/**
+* The row source of an aggregate: `FROM <table> WHERE <where>`; with `first` /
+* `last` (and `withRows`) a derived table instead — the table's rows that
+* pass the WHERE, only the columns {@link rowColumns} lists, plus one
+* `FIRST_VALUE(col) OVER (PARTITION BY <group keys> ORDER BY <rowOrder>)`
+* column per entry (`last` over the reversed order). Each group then reads its
+* representative row's value as an aggregate (constant within the group). The
+* WHERE moves inside unchanged, so the bind parameters keep their order.
+*/
+function aggSource(dialect, table, where, controls, withRows) {
+	const quotedTable = dialect.quoteTable(table);
+	const firstLast = controls.$select?.firstLast;
+	const rowOrder = controls.$select?.rowOrder;
+	if (!withRows || !firstLast?.length || !rowOrder?.length) return `FROM ${quotedTable} WHERE ${where.sql}`;
+	const groupBy = controls.$groupBy;
+	const partition = groupBy?.length ? `PARTITION BY ${groupBy.map((key) => groupKeySql(dialect, controls, key)).join(", ")} ` : "";
+	const order = (reverse) => rowOrder.map((k) => orderKeySql(dialect, dialect.quoteIdentifier(k.column), k.desc !== reverse)).join(", ");
+	return `FROM (SELECT ${[...rowColumns(controls).map((column) => dialect.quoteIdentifier(column)), ...firstLast.map((fl, i) => {
+		const col = dialect.quoteIdentifier(firstLastColumn(i));
+		return `FIRST_VALUE(${dialect.quoteIdentifier(fl.column)}) OVER (${partition}ORDER BY ${order(fl.fn === "last")}) AS ${col}`;
+	})].join(", ")} FROM ${quotedTable} WHERE ${where.sql}) AS ${dialect.quoteIdentifier(ROWS_ALIAS)}`;
+}
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
 *
 * SELECT lists the plain grouped columns, then `<bucket expr> AS "alias"`
-* per calendar bucket, then the aggregates. Bucket expressions are
+* per calendar bucket, then every computed alias (aggregates, row-level
+* expression aggregates, `first` / `last`, group-level expressions — the
+* order of `UniquSelect.computedAliases`). Bucket expressions are
 * parameter-free, so the bind parameters are exactly those of the same query
 * without buckets (WHERE, HAVING, LIMIT, OFFSET).
 */
 function buildAggregateSelect(dialect, table, where, controls) {
+	const select = controls.$select;
 	const selectParts = [];
-	const plainFields = controls.$select?.asArray;
-	if (plainFields) for (const f of plainFields) selectParts.push(dialect.quoteIdentifier(f));
+	for (const f of select?.asArray ?? []) selectParts.push(dialect.quoteIdentifier(f));
 	selectParts.push(...bucketSelectParts(dialect, controls));
-	const aggregates = controls.$select?.aggregates;
-	if (aggregates) for (const expr of aggregates) selectParts.push(buildAggExpr(dialect, expr));
-	let sql = `SELECT ${selectParts.length > 0 ? selectParts.join(", ") : "*"} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	let aliasSql;
+	if (select?.exprAggregates || select?.firstLast || select?.exprs) {
+		aliasSql = aliasSqlMap(dialect, controls);
+		for (const alias of select.computedAliases) selectParts.push(`${aliasSql.get(alias)} AS ${dialect.quoteIdentifier(alias)}`);
+	} else for (const expr of select?.aggregates ?? []) selectParts.push(`${aggFnSql(dialect, select, expr)} AS ${dialect.quoteIdentifier((0, _atscript_db_agg.resolveAlias)(expr))}`);
+	let sql = `SELECT ${selectParts.length > 0 ? selectParts.join(", ") : "*"} ${aggSource(dialect, table, where, controls, true)}${groupByClause(dialect, controls)}`;
 	const params = [...where.params];
-	const groupBy = controls.$groupBy;
-	if (groupBy?.length) {
-		const groupCols = groupBy.map((key) => groupKeySql(dialect, controls, key)).join(", ");
-		sql += ` GROUP BY ${groupCols}`;
-	}
-	const having = havingClause(dialect, controls);
+	const having = havingClause(dialect, controls, aliasSql);
 	if (having) {
 		sql += having.sql;
 		params.push(...having.params);
 	}
 	if (controls.$sort) {
 		const orderParts = [];
-		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(orderKeySql(dialect, dialect.quoteIdentifier(col), dir === -1));
 		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
 	}
 	if (controls.$limit !== void 0) {
@@ -568,21 +750,30 @@ function buildAggregateSelect(dialect, table, where, controls) {
 * Builds a COUNT query for the number of distinct groups — the groups that
 * survive `$having` when one is given (the same predicate the row query
 * renders, so `$count` agrees with the row set). Returns `{ count: N }` when
-* executed.
+* executed. The rows come straight from the table, unless `$having` reads a
+* `first` / `last` value (or an expression over one): only then the window
+* derived table is built.
 */
 function buildAggregateCount(dialect, table, where, controls) {
 	const groupFields = controls.$groupBy;
 	const having = havingClause(dialect, controls);
 	const countCol = `COUNT(*) AS ${dialect.quoteIdentifier("count")}`;
-	if (!groupFields?.length && !having) return finalizeParams(dialect, {
-		sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
-		params: where.params
-	});
-	const groupBy = groupFields?.length ? ` GROUP BY ${groupFields.map((key) => groupKeySql(dialect, controls, key)).join(", ")}` : "";
+	if (!groupFields?.length && !having) {
+		if ((controls.$select?.computedAliases.length ?? 0) > 0) return finalizeParams(dialect, {
+			sql: `SELECT 1 AS ${dialect.quoteIdentifier("count")}`,
+			params: []
+		});
+		return finalizeParams(dialect, {
+			sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
+			params: where.params
+		});
+	}
+	const from = aggSource(dialect, table, where, controls, !!having && readsFirstLast(controls.$select, having.refs));
+	const groupBy = groupByClause(dialect, controls);
 	let inner = "COUNT(*)";
 	if (groupBy) inner = bucketSelectParts(dialect, controls).join(", ") || "1";
 	return finalizeParams(dialect, {
-		sql: `SELECT ${countCol} FROM (SELECT ${inner} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
+		sql: `SELECT ${countCol} FROM (SELECT ${inner} ${from}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
 		params: [...where.params, ...having?.params ?? []]
 	});
 }
@@ -648,30 +839,16 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 function viewComputeExpr(dialect, c, byPath, resolveFieldRef, grouped = false, cache = /* @__PURE__ */ new Map()) {
 	const cached = cache.get(c.viewPath);
 	if (cached !== void 0) return cached;
-	const cast = dialect.castDouble?.bind(dialect);
-	if (!cast) throw new Error(`View column "${c.viewColumn}": computed view columns are not supported by this adapter`);
-	const render = (e) => {
-		if (typeof e === "number") {
-			if (!Number.isFinite(e)) throw new Error(`View column "${c.viewColumn}": non-finite literal in @db.compute`);
-			return cast(String(e));
-		}
-		if ("field" in e) {
-			const leaf = byPath.get(e.field);
-			if (!leaf) throw new Error(`View column "${c.viewColumn}": "${e.field}" is not a column of the view`);
-			if (leaf.expr !== void 0) return viewComputeExpr(dialect, leaf, byPath, resolveFieldRef, grouped, cache);
-			if (leaf.aggFn) return cast(viewAggExpr(dialect, leaf, resolveFieldRef));
-			const source = viewSourceExpr(dialect, leaf);
-			return cast(grouped && leaf.json ? `MIN(${source})` : source);
-		}
-		const args = e.args.map(render);
-		switch (e.op) {
-			case "neg": return `(-${args[0]})`;
-			case "coalesce": return `COALESCE(${args.join(", ")})`;
-			case "/": return `(${args[0]} / NULLIF(${args[1]}, 0))`;
-			default: return `(${args[0]} ${e.op} ${args[1]})`;
-		}
+	const fail = (reason) => /* @__PURE__ */ new Error(reason === "no-cast" ? `View column "${c.viewColumn}": computed view columns are not supported by this adapter` : `View column "${c.viewColumn}": non-finite literal in @db.compute`);
+	const leaf = (field) => {
+		const mapping = byPath.get(field);
+		if (!mapping) throw new Error(`View column "${c.viewColumn}": "${field}" is not a column of the view`);
+		if (mapping.expr !== void 0) return { double: viewComputeExpr(dialect, mapping, byPath, resolveFieldRef, grouped, cache) };
+		if (mapping.aggFn) return viewAggExpr(dialect, mapping, resolveFieldRef);
+		const source = viewSourceExpr(dialect, mapping);
+		return grouped && mapping.json ? `MIN(${source})` : source;
 	};
-	const sql = render(c.expr);
+	const sql = renderArith(dialect, c.expr, leaf, fail);
 	cache.set(c.viewPath, sql);
 	return sql;
 }
@@ -695,10 +872,7 @@ function firstRowOn(dialect, join, target, condition, resolveFieldRef) {
 		type: join.targetType,
 		field: first.key
 	});
-	return `${key} = (SELECT ${key} FROM ${target} WHERE ${condition} ORDER BY ${first.order.map(({ ref, desc }) => {
-		const nulls = dialect.nullsSortLargest ? desc ? " NULLS LAST" : " NULLS FIRST" : "";
-		return `${resolveFieldRef(ref)} ${desc ? "DESC" : "ASC"}${nulls}`;
-	}).join(", ")} LIMIT 1)`;
+	return `${key} = (SELECT ${key} FROM ${target} WHERE ${condition} ORDER BY ${first.order.map(({ ref, desc }) => orderKeySql(dialect, resolveFieldRef(ref), desc)).join(", ")} LIMIT 1)`;
 }
 /**
 * Builds a CREATE VIEW statement from a view plan and column mappings.
@@ -779,6 +953,21 @@ function insertManyColumns(rows) {
 	return [...columns];
 }
 /**
+* Splits `rows` into batches that stay under the driver's bind-parameter limit
+* (PostgreSQL ~65535, MySQL packet size): `maxParams` (default 60000) divided
+* by the column count. Returns the shared column union and the batches.
+*/
+function chunkInsertRows(rows, maxParams = 6e4) {
+	const columns = insertManyColumns(rows);
+	const size = columns.length > 0 ? Math.max(1, Math.floor(maxParams / columns.length)) : rows.length;
+	const batches = [];
+	for (let offset = 0; offset < rows.length; offset += size) batches.push(rows.slice(offset, offset + size));
+	return {
+		columns,
+		batches
+	};
+}
+/**
 * Builds a multi-row `INSERT … VALUES (…), (…)` statement over `columns`
 * (default: {@link insertManyColumns} of `rows`). A row lacking a column gets
 * `DEFAULT` — exactly what a single-row INSERT omitting it stores. Callers
@@ -1262,6 +1451,7 @@ exports.PARTITION_ROW_NUMBER_ALIAS = PARTITION_ROW_NUMBER_ALIAS;
 exports.SEARCH_SOURCE_ALIAS = SEARCH_SOURCE_ALIAS;
 exports.SQL_DEFAULT = SQL_DEFAULT;
 exports.VECTOR_DISTANCE_ALIAS = VECTOR_DISTANCE_ALIAS;
+exports.arithOverflowError = arithOverflowError;
 exports.buildAggregateCount = buildAggregateCount;
 exports.buildAggregateSelect = buildAggregateSelect;
 exports.buildCreateView = buildCreateView;
@@ -1277,6 +1467,7 @@ exports.buildUpdate = buildUpdate;
 exports.buildVectorSearchCount = buildVectorSearchCount;
 exports.buildVectorSearchSelect = buildVectorSearchSelect;
 exports.buildWhere = buildWhere;
+exports.chunkInsertRows = chunkInsertRows;
 exports.createFilterVisitor = createFilterVisitor;
 exports.defaultValueForType = defaultValueForType;
 exports.defaultValueToSqlLiteral = defaultValueToSqlLiteral;
@@ -1288,13 +1479,17 @@ exports.geoWindowFromControls = geoWindowFromControls;
 exports.groupKeySql = groupKeySql;
 exports.insertManyColumns = insertManyColumns;
 exports.jsonDollarPath = jsonDollarPath;
+exports.mapQueryErrors = mapQueryErrors;
 exports.normalizeGeoPointValue = normalizeGeoPointValue;
+exports.numericOutOfRangeError = numericOutOfRangeError;
+exports.orderKeySql = orderKeySql;
 exports.parseRegexString = parseRegexString;
 exports.queryNodeToSql = queryNodeToSql;
 exports.queryOpToSql = queryOpToSql;
 exports.quotedJsonPathSegments = quotedJsonPathSegments;
 exports.refActionToSql = refActionToSql;
 exports.renameGeoDistance = renameGeoDistance;
+exports.renderArith = renderArith;
 exports.replaceColumnsFor = replaceColumnsFor;
 exports.sqlStringLiteral = sqlStringLiteral;
 exports.sqlTimeZoneLiteral = sqlTimeZoneLiteral;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
+import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
@@ -95,6 +95,38 @@ interface SqlDialect {
    * @since 0.1.147
    */
   castDouble?(expr: string): string;
+  /**
+   * The aggregate functions that stand in for `MIN` / `MAX` over a BOOLEAN
+   * column on an engine that has no `MIN(boolean)` (PostgreSQL: `BOOL_AND` /
+   * `BOOL_OR`). Absent: `MIN` / `MAX` apply to booleans as to any column.
+   * @since 0.1.148
+   */
+  booleanAggregates?: {
+    min: string;
+    max: string;
+  };
+  /**
+   * Renders the "any value of the group" pick over an already rendered column
+   * — what a `first` / `last` derived column (constant within its group)
+   * aggregates through — for the column's source `field` (`undefined` when
+   * unknown). The dialect picks the cheapest aggregate its engine has for the
+   * column's type: a streaming `MIN` where one exists, a type-agnostic form
+   * only where it does not (PostgreSQL: `MIN` for ordered types, `BOOL_AND`
+   * for a boolean, `(ARRAY_AGG(x))[1]` for uuid, bytea, point, json, …).
+   * Absent: `MIN(x)`.
+   * @since 0.1.148
+   */
+  anyValue?(expr: string, field: TDbFieldMeta | undefined): string;
+  /**
+   * Maps a driver error of a grouped query to the `DbError` it means — a
+   * numeric overflow (`arithOverflowError` when the query has arithmetic
+   * expressions, else `numericOutOfRangeError`), an unknown calendar-bucket
+   * zone — or `undefined` to let it propagate unchanged. `arithmetic` is
+   * whether the query selects any arithmetic expression. Run by
+   * {@link mapQueryErrors}.
+   * @since 0.1.148
+   */
+  mapQueryError?(error: unknown, arithmetic: boolean): Error | undefined;
   /**
    * `true` when the database sorts NULL as the LARGEST value (PostgreSQL):
    * first-row join order keys then render `ASC NULLS FIRST` /
@@ -113,6 +145,21 @@ interface SqlDialect {
  * (e.g. `$1, $2, ...` for PostgreSQL). No-op when `dialect.paramPlaceholder` is not set.
  */
 declare function finalizeParams(dialect: SqlDialect, fragment: TSqlFragment): TSqlFragment;
+/**
+ * Runs `fn`, rethrowing a driver error as the `DbError`
+ * {@link SqlDialect.mapQueryError} maps it to (any other error unchanged).
+ * `controls` of the query tell whether it has arithmetic expressions.
+ * @since 0.1.148
+ */
+declare function mapQueryErrors<R>(dialect: SqlDialect, fn: () => Promise<R>, controls?: DbControls): Promise<R>;
+/**
+ * One `ORDER BY` key with the uniform "NULL is the smallest value" ordering:
+ * `<expr> ASC` / `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a
+ * dialect where NULL sorts largest ({@link SqlDialect.nullsSortLargest}).
+ * Shared by first-row joins and `first` / `last` aggregates.
+ * @since 0.1.148
+ */
+declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean): string;
 /**
  * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
  * {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
@@ -128,6 +175,34 @@ declare function quotedJsonPathSegments(path: readonly string[]): string[];
 declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
 //#endregion
+//#region src/arith.d.ts
+/** Why {@link renderArith} cannot render an expression. */
+type TArithFailure = "no-cast" | "non-finite";
+/**
+ * Renders a computed expression tree (`@db.compute` on a view, or a query-time
+ * arithmetic `$select` entry) as SQL, in IEEE double on every dialect: each
+ * literal is cast with {@link SqlDialect.castDouble}; `+ - *` render as
+ * `(l op r)`, `/` as `(l / NULLIF(r, 0))` (division by zero is NULL), unary
+ * minus as `(-x)` and `coalesce` as `COALESCE(…)`. `leaf` renders a field
+ * reference as raw SQL, which is cast to double here — or, as `{ double }`,
+ * SQL that already is a double (a nested computed column) and stays as is.
+ *
+ * The one renderer of both paths, so declared and query-time arithmetic
+ * cannot diverge.
+ *
+ * @param fail - the error to throw for a failure (default `DbError`:
+ *   `AGG_EXPR_NOT_SUPPORTED` without `castDouble`, `INVALID_QUERY` for a
+ *   non-finite literal).
+ * @since 0.1.148
+ */
+declare function renderArith(dialect: SqlDialect, node: AtscriptExprNode, leaf: (field: string) => string | {
+  double: string;
+}, fail?: (reason: TArithFailure) => Error): string;
+/** The error of a numeric overflow that is no arithmetic expression's (`INVALID_QUERY`, `path` `""`). */
+declare function numericOutOfRangeError(): DbError;
+/** The error of a double overflow in aggregate arithmetic (`INVALID_QUERY`, `path` `$select`). */
+declare function arithOverflowError(): DbError;
+//#endregion
 //#region src/filter-builder.d.ts
 interface TFilterVisitorOptions {
   /**
@@ -326,6 +401,15 @@ declare function buildInsert(dialect: SqlDialect, table: string, data: Record<st
  * some).
  */
 declare function insertManyColumns(rows: readonly Record<string, unknown>[]): string[];
+/**
+ * Splits `rows` into batches that stay under the driver's bind-parameter limit
+ * (PostgreSQL ~65535, MySQL packet size): `maxParams` (default 60000) divided
+ * by the column count. Returns the shared column union and the batches.
+ */
+declare function chunkInsertRows(rows: readonly Record<string, unknown>[], maxParams?: number): {
+  columns: string[];
+  batches: Record<string, unknown>[][];
+};
 /**
  * Builds a multi-row `INSERT … VALUES (…), (…)` statement over `columns`
  * (default: {@link insertManyColumns} of `rows`). A row lacking a column gets
@@ -495,7 +579,7 @@ declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref:
  * SQL function name of each single-name aggregate. `countDistinct` is not a
  * name but a form (`COUNT(DISTINCT x)`) — see {@link renderAggCall}.
  */
-declare const AGG_FN_SQL: Readonly<Record<Exclude<TDbAggregateFn, "countDistinct">, string>>;
+declare const AGG_FN_SQL: Readonly<Record<Exclude<TDbAggregateFn, "countDistinct" | "first" | "last">, string>>;
 /**
  * The SQL a `$groupBy` key renders as: a calendar-bucket alias renders the
  * bucket EXPRESSION (`dialect.calendarBucket`), anything else the quoted
@@ -512,7 +596,9 @@ declare function groupKeySql(dialect: SqlDialect, controls: DbControls, key: str
  * Builds a SELECT ... GROUP BY statement with aggregate functions.
  *
  * SELECT lists the plain grouped columns, then `<bucket expr> AS "alias"`
- * per calendar bucket, then the aggregates. Bucket expressions are
+ * per calendar bucket, then every computed alias (aggregates, row-level
+ * expression aggregates, `first` / `last`, group-level expressions — the
+ * order of `UniquSelect.computedAliases`). Bucket expressions are
  * parameter-free, so the bind parameters are exactly those of the same query
  * without buckets (WHERE, HAVING, LIMIT, OFFSET).
  */
@@ -521,7 +607,9 @@ declare function buildAggregateSelect(dialect: SqlDialect, table: string, where:
  * Builds a COUNT query for the number of distinct groups — the groups that
  * survive `$having` when one is given (the same predicate the row query
  * renders, so `$count` agrees with the row set). Returns `{ count: N }` when
- * executed.
+ * executed. The rows come straight from the table, unless `$having` reads a
+ * `first` / `last` value (or an expression over one): only then the window
+ * derived table is built.
  */
 declare function buildAggregateCount(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
 //#endregion
@@ -538,4 +626,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
+import { AtscriptExprNode, AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, DbError, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { FilterExpr, FilterVisitor } from "@uniqu/core";
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, TDbForeignKey, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
 //#region src/dialect.d.ts
@@ -95,6 +95,38 @@ interface SqlDialect {
    * @since 0.1.147
    */
   castDouble?(expr: string): string;
+  /**
+   * The aggregate functions that stand in for `MIN` / `MAX` over a BOOLEAN
+   * column on an engine that has no `MIN(boolean)` (PostgreSQL: `BOOL_AND` /
+   * `BOOL_OR`). Absent: `MIN` / `MAX` apply to booleans as to any column.
+   * @since 0.1.148
+   */
+  booleanAggregates?: {
+    min: string;
+    max: string;
+  };
+  /**
+   * Renders the "any value of the group" pick over an already rendered column
+   * — what a `first` / `last` derived column (constant within its group)
+   * aggregates through — for the column's source `field` (`undefined` when
+   * unknown). The dialect picks the cheapest aggregate its engine has for the
+   * column's type: a streaming `MIN` where one exists, a type-agnostic form
+   * only where it does not (PostgreSQL: `MIN` for ordered types, `BOOL_AND`
+   * for a boolean, `(ARRAY_AGG(x))[1]` for uuid, bytea, point, json, …).
+   * Absent: `MIN(x)`.
+   * @since 0.1.148
+   */
+  anyValue?(expr: string, field: TDbFieldMeta | undefined): string;
+  /**
+   * Maps a driver error of a grouped query to the `DbError` it means — a
+   * numeric overflow (`arithOverflowError` when the query has arithmetic
+   * expressions, else `numericOutOfRangeError`), an unknown calendar-bucket
+   * zone — or `undefined` to let it propagate unchanged. `arithmetic` is
+   * whether the query selects any arithmetic expression. Run by
+   * {@link mapQueryErrors}.
+   * @since 0.1.148
+   */
+  mapQueryError?(error: unknown, arithmetic: boolean): Error | undefined;
   /**
    * `true` when the database sorts NULL as the LARGEST value (PostgreSQL):
    * first-row join order keys then render `ASC NULLS FIRST` /
@@ -113,6 +145,21 @@ interface SqlDialect {
  * (e.g. `$1, $2, ...` for PostgreSQL). No-op when `dialect.paramPlaceholder` is not set.
  */
 declare function finalizeParams(dialect: SqlDialect, fragment: TSqlFragment): TSqlFragment;
+/**
+ * Runs `fn`, rethrowing a driver error as the `DbError`
+ * {@link SqlDialect.mapQueryError} maps it to (any other error unchanged).
+ * `controls` of the query tell whether it has arithmetic expressions.
+ * @since 0.1.148
+ */
+declare function mapQueryErrors<R>(dialect: SqlDialect, fn: () => Promise<R>, controls?: DbControls): Promise<R>;
+/**
+ * One `ORDER BY` key with the uniform "NULL is the smallest value" ordering:
+ * `<expr> ASC` / `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a
+ * dialect where NULL sorts largest ({@link SqlDialect.nullsSortLargest}).
+ * Shared by first-row joins and `first` / `last` aggregates.
+ * @since 0.1.148
+ */
+declare function orderKeySql(dialect: SqlDialect, expr: string, desc: boolean): string;
 /**
  * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
  * {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
@@ -128,6 +175,34 @@ declare function quotedJsonPathSegments(path: readonly string[]): string[];
 declare const EMPTY_AND: TSqlFragment;
 declare const EMPTY_OR: TSqlFragment;
 //#endregion
+//#region src/arith.d.ts
+/** Why {@link renderArith} cannot render an expression. */
+type TArithFailure = "no-cast" | "non-finite";
+/**
+ * Renders a computed expression tree (`@db.compute` on a view, or a query-time
+ * arithmetic `$select` entry) as SQL, in IEEE double on every dialect: each
+ * literal is cast with {@link SqlDialect.castDouble}; `+ - *` render as
+ * `(l op r)`, `/` as `(l / NULLIF(r, 0))` (division by zero is NULL), unary
+ * minus as `(-x)` and `coalesce` as `COALESCE(…)`. `leaf` renders a field
+ * reference as raw SQL, which is cast to double here — or, as `{ double }`,
+ * SQL that already is a double (a nested computed column) and stays as is.
+ *
+ * The one renderer of both paths, so declared and query-time arithmetic
+ * cannot diverge.
+ *
+ * @param fail - the error to throw for a failure (default `DbError`:
+ *   `AGG_EXPR_NOT_SUPPORTED` without `castDouble`, `INVALID_QUERY` for a
+ *   non-finite literal).
+ * @since 0.1.148
+ */
+declare function renderArith(dialect: SqlDialect, node: AtscriptExprNode, leaf: (field: string) => string | {
+  double: string;
+}, fail?: (reason: TArithFailure) => Error): string;
+/** The error of a numeric overflow that is no arithmetic expression's (`INVALID_QUERY`, `path` `""`). */
+declare function numericOutOfRangeError(): DbError;
+/** The error of a double overflow in aggregate arithmetic (`INVALID_QUERY`, `path` `$select`). */
+declare function arithOverflowError(): DbError;
+//#endregion
 //#region src/filter-builder.d.ts
 interface TFilterVisitorOptions {
   /**
@@ -326,6 +401,15 @@ declare function buildInsert(dialect: SqlDialect, table: string, data: Record<st
  * some).
  */
 declare function insertManyColumns(rows: readonly Record<string, unknown>[]): string[];
+/**
+ * Splits `rows` into batches that stay under the driver's bind-parameter limit
+ * (PostgreSQL ~65535, MySQL packet size): `maxParams` (default 60000) divided
+ * by the column count. Returns the shared column union and the batches.
+ */
+declare function chunkInsertRows(rows: readonly Record<string, unknown>[], maxParams?: number): {
+  columns: string[];
+  batches: Record<string, unknown>[][];
+};
 /**
  * Builds a multi-row `INSERT … VALUES (…), (…)` statement over `columns`
  * (default: {@link insertManyColumns} of `rows`). A row lacking a column gets
@@ -495,7 +579,7 @@ declare function queryNodeToSql(node: AtscriptQueryNode, resolveFieldRef: (ref:
  * SQL function name of each single-name aggregate. `countDistinct` is not a
  * name but a form (`COUNT(DISTINCT x)`) — see {@link renderAggCall}.
  */
-declare const AGG_FN_SQL: Readonly<Record<Exclude<TDbAggregateFn, "countDistinct">, string>>;
+declare const AGG_FN_SQL: Readonly<Record<Exclude<TDbAggregateFn, "countDistinct" | "first" | "last">, string>>;
 /**
  * The SQL a `$groupBy` key renders as: a calendar-bucket alias renders the
  * bucket EXPRESSION (`dialect.calendarBucket`), anything else the quoted
@@ -512,7 +596,9 @@ declare function groupKeySql(dialect: SqlDialect, controls: DbControls, key: str
  * Builds a SELECT ... GROUP BY statement with aggregate functions.
  *
  * SELECT lists the plain grouped columns, then `<bucket expr> AS "alias"`
- * per calendar bucket, then the aggregates. Bucket expressions are
+ * per calendar bucket, then every computed alias (aggregates, row-level
+ * expression aggregates, `first` / `last`, group-level expressions — the
+ * order of `UniquSelect.computedAliases`). Bucket expressions are
  * parameter-free, so the bind parameters are exactly those of the same query
  * without buckets (WHERE, HAVING, LIMIT, OFFSET).
  */
@@ -521,7 +607,9 @@ declare function buildAggregateSelect(dialect: SqlDialect, table: string, where:
  * Builds a COUNT query for the number of distinct groups — the groups that
  * survive `$having` when one is given (the same predicate the row query
  * renders, so `$count` agrees with the row set). Returns `{ count: N }` when
- * executed.
+ * executed. The rows come straight from the table, unless `$having` reads a
+ * `first` / `last` value (or an expression over one): only then the window
+ * derived table is built.
  */
 declare function buildAggregateCount(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls): TSqlFragment;
 //#endregion
@@ -538,4 +626,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TArithFailure, type TFilterVisitorOptions, type TGeoCircle, type TGeoSearchControls, type TGeoWindow, type TReplaceColumn, type TSqlFragment, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };

package/dist/index.mjs

@@ -1,5 +1,5 @@
+import { DbError, aggregateExpressionsNotSupported, containsRelationFilter, fkColumns, isFieldRef, isResolvedRelationFilter } from "@atscript/db";
 import { BUCKET_UNITS, TIME_ZONE_NAME_RE, WEEK_STARTS, walkFilter } from "@uniqu/core";
-import { DbError, containsRelationFilter, fkColumns, isFieldRef, isResolvedRelationFilter } from "@atscript/db";
 import { assertAggregateFn, resolveAlias } from "@atscript/db/agg";
 //#region src/dialect.ts
 /**
@@ -23,6 +23,32 @@ function havingGroupRef(dialect, expr, alias) {
 	return dialect.bucketAliasInHaving ? dialect.quoteIdentifier(alias) : expr;
 }
 /**
+* Runs `fn`, rethrowing a driver error as the `DbError`
+* {@link SqlDialect.mapQueryError} maps it to (any other error unchanged).
+* `controls` of the query tell whether it has arithmetic expressions.
+* @since 0.1.148
+*/
+async function mapQueryErrors(dialect, fn, controls) {
+	try {
+		return await fn();
+	} catch (error) {
+		const select = controls?.$select;
+		const arithmetic = !!(select?.exprAggregates?.length || select?.exprs?.length);
+		throw dialect.mapQueryError?.(error, arithmetic) ?? error;
+	}
+}
+/**
+* One `ORDER BY` key with the uniform "NULL is the smallest value" ordering:
+* `<expr> ASC` / `<expr> DESC`, plus `NULLS FIRST` / `NULLS LAST` on a
+* dialect where NULL sorts largest ({@link SqlDialect.nullsSortLargest}).
+* Shared by first-row joins and `first` / `last` aggregates.
+* @since 0.1.148
+*/
+function orderKeySql(dialect, expr, desc) {
+	const nulls = dialect.nullsSortLargest ? desc ? " NULLS LAST" : " NULLS FIRST" : "";
+	return `${expr} ${desc ? "DESC" : "ASC"}${nulls}`;
+}
+/**
 * Each JSON path segment wrapped in double quotes (`"a"`), for the dialects'
 * {@link SqlDialect.jsonExtract} path literals (`'$."a"."b"'`, `'{"a","b"}'`).
 *
@@ -54,6 +80,67 @@ const EMPTY_OR = {
 	params: []
 };
 //#endregion
+//#region src/arith.ts
+/**
+* Renders a computed expression tree (`@db.compute` on a view, or a query-time
+* arithmetic `$select` entry) as SQL, in IEEE double on every dialect: each
+* literal is cast with {@link SqlDialect.castDouble}; `+ - *` render as
+* `(l op r)`, `/` as `(l / NULLIF(r, 0))` (division by zero is NULL), unary
+* minus as `(-x)` and `coalesce` as `COALESCE(…)`. `leaf` renders a field
+* reference as raw SQL, which is cast to double here — or, as `{ double }`,
+* SQL that already is a double (a nested computed column) and stays as is.
+*
+* The one renderer of both paths, so declared and query-time arithmetic
+* cannot diverge.
+*
+* @param fail - the error to throw for a failure (default `DbError`:
+*   `AGG_EXPR_NOT_SUPPORTED` without `castDouble`, `INVALID_QUERY` for a
+*   non-finite literal).
+* @since 0.1.148
+*/
+function renderArith(dialect, node, leaf, fail = defaultFailure) {
+	const cast = dialect.castDouble?.bind(dialect);
+	if (!cast) throw fail("no-cast");
+	const render = (e) => {
+		if (typeof e === "number") {
+			if (!Number.isFinite(e)) throw fail("non-finite");
+			return cast(String(e));
+		}
+		if ("field" in e) {
+			const sql = leaf(e.field);
+			return typeof sql === "string" ? cast(sql) : sql.double;
+		}
+		const args = e.args.map(render);
+		switch (e.op) {
+			case "neg": return `(-${args[0]})`;
+			case "coalesce": return `COALESCE(${args.join(", ")})`;
+			case "/": return `(${args[0]} / NULLIF(${args[1]}, 0))`;
+			default: return `(${args[0]} ${e.op} ${args[1]})`;
+		}
+	};
+	return render(node);
+}
+function defaultFailure(reason) {
+	return reason === "no-cast" ? aggregateExpressionsNotSupported() : new DbError("INVALID_QUERY", [{
+		path: "$select",
+		message: "Expression literal is not finite"
+	}]);
+}
+/** The error of a numeric overflow that is no arithmetic expression's (`INVALID_QUERY`, `path` `""`). */
+function numericOutOfRangeError() {
+	return new DbError("INVALID_QUERY", [{
+		path: "",
+		message: "Numeric value out of range"
+	}]);
+}
+/** The error of a double overflow in aggregate arithmetic (`INVALID_QUERY`, `path` `$select`). */
+function arithOverflowError() {
+	return new DbError("INVALID_QUERY", [{
+		path: "$select",
+		message: "Arithmetic overflow"
+	}]);
+}
+//#endregion
 //#region src/filter-builder.ts
 /**
 * Creates a dialect-specific filter visitor for `walkFilter`.
@@ -427,15 +514,23 @@ const AGG_FN_SQL = {
 */
 function renderAggCall(fn, arg, path) {
 	assertAggregateFn(fn, path);
-	return fn === "countDistinct" ? `COUNT(DISTINCT ${arg})` : `${AGG_FN_SQL[fn]}(${arg})`;
+	if (fn === "countDistinct") return `COUNT(DISTINCT ${arg})`;
+	return `${AGG_FN_SQL[fn]}(${arg})`;
 }
-/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)` / `COUNT(DISTINCT "region")`. */
-function aggFnSql(dialect, expr) {
-	const field = expr.$field === "*" ? "*" : dialect.quoteIdentifier(expr.$field);
-	return renderAggCall(expr.$fn, field);
+/**
+* `MIN` / `MAX` of a column the engine may not aggregate directly: a boolean
+* on a dialect with {@link SqlDialect.booleanAggregates} (PostgreSQL has no
+* `MIN(boolean)`) renders its stand-in.
+*/
+function pickSql(dialect, select, fn, column, sql) {
+	const bool = select?.sources.get(column)?.designType === "boolean" ? dialect.booleanAggregates?.[fn] : void 0;
+	return bool ? `${bool}(${sql})` : renderAggCall(fn, sql);
 }
-function buildAggExpr(dialect, expr) {
-	return `${aggFnSql(dialect, expr)} AS ${dialect.quoteIdentifier(resolveAlias(expr))}`;
+/** The bare aggregate call, e.g. `SUM("amount")` / `COUNT(*)` / `COUNT(DISTINCT "region")`. */
+function aggFnSql(dialect, select, expr) {
+	if (expr.$field === "*") return renderAggCall(expr.$fn, "*");
+	const field = dialect.quoteIdentifier(expr.$field);
+	return expr.$fn === "min" || expr.$fn === "max" ? pickSql(dialect, select, expr.$fn, expr.$field, field) : renderAggCall(expr.$fn, field);
 }
 const BUCKET_UNIT_SET = new Set(BUCKET_UNITS);
 const WEEK_START_SET = new Set(WEEK_STARTS);
@@ -483,25 +578,52 @@ function groupKeySql(dialect, controls, key) {
 	const bucket = controls.$select?.bucketByAlias(key);
 	return bucket ? bucketSql(dialect, bucket) : dialect.quoteIdentifier(key);
 }
+/** Alias of the derived table `first` / `last` aggregates read from. */
+const ROWS_ALIAS = "__as_rows";
+/** The derived-table column of the `i`-th `first` / `last` entry. */
+const firstLastColumn = (i) => `__as_fl${i}`;
+/**
+* The SQL each computed alias stands for where an alias is not usable
+* (HAVING; other expressions): an aggregate's call, a `first` / `last`
+* derived column (aggregated: constant within its group), a row-level
+* expression aggregate's call, and every group-level expression rendered over
+* those (in dependency order, operands cast to double). A grouped column
+* renders as its quoted name.
+*/
+function aliasSqlMap(dialect, controls) {
+	const map = /* @__PURE__ */ new Map();
+	const select = controls.$select;
+	const quote = (name) => dialect.quoteIdentifier(name);
+	for (const expr of select?.aggregates ?? []) map.set(resolveAlias(expr), aggFnSql(dialect, select, expr));
+	for (const e of select?.exprAggregates ?? []) map.set(e.alias, renderAggCall(e.fn, renderArith(dialect, e.expr, quote)));
+	(select?.firstLast ?? []).forEach((fl, i) => {
+		const col = quote(firstLastColumn(i));
+		map.set(fl.alias, dialect.anyValue ? dialect.anyValue(col, select?.sources.get(fl.column)) : renderAggCall("min", col));
+	});
+	for (const e of select?.exprs ?? []) map.set(e.alias, renderArith(dialect, e.expr, (name) => map.get(name) ?? quote(name)));
+	return map;
+}
 /**
 * ` HAVING <predicate>` (leading space) + params for `controls.$having`, or
 * `undefined` when there is nothing to render. Shared by the row and the
 * count builders so both filter the same group set.
 *
-* A key that names an aggregate alias (`$as`, else `fn_field`) renders the
-* aggregate expression itself — `SUM("amount") > ?` — because PostgreSQL does
-* not allow a SELECT alias in HAVING (MySQL and SQLite tolerate it, so the
-* expression form keeps all three identical). A calendar-bucket alias renders
-* its bucket expression ({@link groupKeySql}), or its quoted alias when the
-* dialect sets `SqlDialect.bucketAliasInHaving` (`havingGroupRef`). Other keys
-* (grouped columns) render as plain columns.
+* A key that names a computed alias (`$as`, else `fn_field`) renders what the
+* alias stands for — `SUM("amount") > ?`, an expression's arithmetic — because
+* PostgreSQL does not allow a SELECT alias in HAVING (MySQL and SQLite
+* tolerate it, so the expression form keeps all three identical). A
+* calendar-bucket alias renders its bucket expression ({@link groupKeySql}),
+* or its quoted alias when the dialect sets `SqlDialect.bucketAliasInHaving`
+* (`havingGroupRef`). Other keys (grouped columns) render as plain columns.
+* `aliasSql` is the query's {@link aliasSqlMap} when the caller has built it.
 */
-function havingClause(dialect, controls) {
+function havingClause(dialect, controls, aliasSql) {
 	const having = controls.$having;
 	if (!having) return void 0;
-	const exprByAlias = /* @__PURE__ */ new Map();
-	for (const expr of controls.$select?.aggregates ?? []) exprByAlias.set(resolveAlias(expr), aggFnSql(dialect, expr));
+	const exprByAlias = aliasSql ?? aliasSqlMap(dialect, controls);
+	const refs = /* @__PURE__ */ new Set();
 	const fragment = walkFilter(having, createFilterVisitor(dialect, { columnRef: (field) => {
+		refs.add(field);
 		const aggExpr = exprByAlias.get(field);
 		if (aggExpr) return aggExpr;
 		const bucket = controls.$select?.bucketByAlias(field);
@@ -510,43 +632,103 @@ function havingClause(dialect, controls) {
 	if (!fragment || fragment.sql === EMPTY_AND.sql) return void 0;
 	return {
 		sql: ` HAVING ${fragment.sql}`,
-		params: fragment.params
+		params: fragment.params,
+		refs
 	};
 }
 /** `<bucket expr> AS "alias"` for every calendar bucket in `$select`. */
 function bucketSelectParts(dialect, controls) {
 	return (controls.$select?.buckets ?? []).map((bucket) => `${bucketSql(dialect, bucket)} AS ${dialect.quoteIdentifier(bucket.alias)}`);
 }
+/** ` GROUP BY <keys>` (leading space), or `""` for the whole table as one group. */
+function groupByClause(dialect, controls) {
+	const keys = controls.$groupBy ?? [];
+	return keys.length ? ` GROUP BY ${keys.map((key) => groupKeySql(dialect, controls, key)).join(", ")}` : "";
+}
+/** Whether any of the HAVING keys is a `first` / `last` alias, or an expression over one. */
+function readsFirstLast(select, refs) {
+	if (!select?.firstLast) return false;
+	const firstLast = new Set(select.firstLast.map((fl) => fl.alias));
+	const names = new Map((select.exprs ?? []).map((e) => [e.alias, e.names]));
+	const visit = (name, seen) => {
+		if (firstLast.has(name)) return true;
+		const deps = names.get(name);
+		if (!deps || seen.has(name)) return false;
+		seen.add(name);
+		return deps.some((dep) => visit(dep, seen));
+	};
+	return [...refs].some((key) => visit(key, /* @__PURE__ */ new Set()));
+}
+/**
+* The columns the outer query reads from the derived table of a `first` /
+* `last` aggregate: group keys (a bucket's source for its alias), plain
+* `$select` fields, aggregate fields and the leaves of row-level expressions.
+* The `$rowOrder` columns and the `first` / `last` sources stay inside the
+* window; a group-level expression, `$having` and `$sort` read aliases or
+* group keys only.
+*/
+function rowColumns(controls) {
+	const select = controls.$select;
+	const columns = /* @__PURE__ */ new Set();
+	for (const key of controls.$groupBy ?? []) if (!select?.bucketByAlias(key)) columns.add(key);
+	for (const bucket of select?.buckets ?? []) columns.add(bucket.field);
+	for (const field of select?.asArray ?? []) columns.add(field);
+	for (const expr of select?.aggregates ?? []) if (expr.$field !== "*") columns.add(expr.$field);
+	for (const e of select?.exprAggregates ?? []) for (const name of e.names) columns.add(name);
+	return [...columns];
+}
+/**
+* The row source of an aggregate: `FROM <table> WHERE <where>`; with `first` /
+* `last` (and `withRows`) a derived table instead — the table's rows that
+* pass the WHERE, only the columns {@link rowColumns} lists, plus one
+* `FIRST_VALUE(col) OVER (PARTITION BY <group keys> ORDER BY <rowOrder>)`
+* column per entry (`last` over the reversed order). Each group then reads its
+* representative row's value as an aggregate (constant within the group). The
+* WHERE moves inside unchanged, so the bind parameters keep their order.
+*/
+function aggSource(dialect, table, where, controls, withRows) {
+	const quotedTable = dialect.quoteTable(table);
+	const firstLast = controls.$select?.firstLast;
+	const rowOrder = controls.$select?.rowOrder;
+	if (!withRows || !firstLast?.length || !rowOrder?.length) return `FROM ${quotedTable} WHERE ${where.sql}`;
+	const groupBy = controls.$groupBy;
+	const partition = groupBy?.length ? `PARTITION BY ${groupBy.map((key) => groupKeySql(dialect, controls, key)).join(", ")} ` : "";
+	const order = (reverse) => rowOrder.map((k) => orderKeySql(dialect, dialect.quoteIdentifier(k.column), k.desc !== reverse)).join(", ");
+	return `FROM (SELECT ${[...rowColumns(controls).map((column) => dialect.quoteIdentifier(column)), ...firstLast.map((fl, i) => {
+		const col = dialect.quoteIdentifier(firstLastColumn(i));
+		return `FIRST_VALUE(${dialect.quoteIdentifier(fl.column)}) OVER (${partition}ORDER BY ${order(fl.fn === "last")}) AS ${col}`;
+	})].join(", ")} FROM ${quotedTable} WHERE ${where.sql}) AS ${dialect.quoteIdentifier(ROWS_ALIAS)}`;
+}
 /**
 * Builds a SELECT ... GROUP BY statement with aggregate functions.
 *
 * SELECT lists the plain grouped columns, then `<bucket expr> AS "alias"`
-* per calendar bucket, then the aggregates. Bucket expressions are
+* per calendar bucket, then every computed alias (aggregates, row-level
+* expression aggregates, `first` / `last`, group-level expressions — the
+* order of `UniquSelect.computedAliases`). Bucket expressions are
 * parameter-free, so the bind parameters are exactly those of the same query
 * without buckets (WHERE, HAVING, LIMIT, OFFSET).
 */
 function buildAggregateSelect(dialect, table, where, controls) {
+	const select = controls.$select;
 	const selectParts = [];
-	const plainFields = controls.$select?.asArray;
-	if (plainFields) for (const f of plainFields) selectParts.push(dialect.quoteIdentifier(f));
+	for (const f of select?.asArray ?? []) selectParts.push(dialect.quoteIdentifier(f));
 	selectParts.push(...bucketSelectParts(dialect, controls));
-	const aggregates = controls.$select?.aggregates;
-	if (aggregates) for (const expr of aggregates) selectParts.push(buildAggExpr(dialect, expr));
-	let sql = `SELECT ${selectParts.length > 0 ? selectParts.join(", ") : "*"} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	let aliasSql;
+	if (select?.exprAggregates || select?.firstLast || select?.exprs) {
+		aliasSql = aliasSqlMap(dialect, controls);
+		for (const alias of select.computedAliases) selectParts.push(`${aliasSql.get(alias)} AS ${dialect.quoteIdentifier(alias)}`);
+	} else for (const expr of select?.aggregates ?? []) selectParts.push(`${aggFnSql(dialect, select, expr)} AS ${dialect.quoteIdentifier(resolveAlias(expr))}`);
+	let sql = `SELECT ${selectParts.length > 0 ? selectParts.join(", ") : "*"} ${aggSource(dialect, table, where, controls, true)}${groupByClause(dialect, controls)}`;
 	const params = [...where.params];
-	const groupBy = controls.$groupBy;
-	if (groupBy?.length) {
-		const groupCols = groupBy.map((key) => groupKeySql(dialect, controls, key)).join(", ");
-		sql += ` GROUP BY ${groupCols}`;
-	}
-	const having = havingClause(dialect, controls);
+	const having = havingClause(dialect, controls, aliasSql);
 	if (having) {
 		sql += having.sql;
 		params.push(...having.params);
 	}
 	if (controls.$sort) {
 		const orderParts = [];
-		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(orderKeySql(dialect, dialect.quoteIdentifier(col), dir === -1));
 		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
 	}
 	if (controls.$limit !== void 0) {
@@ -567,21 +749,30 @@ function buildAggregateSelect(dialect, table, where, controls) {
 * Builds a COUNT query for the number of distinct groups — the groups that
 * survive `$having` when one is given (the same predicate the row query
 * renders, so `$count` agrees with the row set). Returns `{ count: N }` when
-* executed.
+* executed. The rows come straight from the table, unless `$having` reads a
+* `first` / `last` value (or an expression over one): only then the window
+* derived table is built.
 */
 function buildAggregateCount(dialect, table, where, controls) {
 	const groupFields = controls.$groupBy;
 	const having = havingClause(dialect, controls);
 	const countCol = `COUNT(*) AS ${dialect.quoteIdentifier("count")}`;
-	if (!groupFields?.length && !having) return finalizeParams(dialect, {
-		sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
-		params: where.params
-	});
-	const groupBy = groupFields?.length ? ` GROUP BY ${groupFields.map((key) => groupKeySql(dialect, controls, key)).join(", ")}` : "";
+	if (!groupFields?.length && !having) {
+		if ((controls.$select?.computedAliases.length ?? 0) > 0) return finalizeParams(dialect, {
+			sql: `SELECT 1 AS ${dialect.quoteIdentifier("count")}`,
+			params: []
+		});
+		return finalizeParams(dialect, {
+			sql: `SELECT ${countCol} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`,
+			params: where.params
+		});
+	}
+	const from = aggSource(dialect, table, where, controls, !!having && readsFirstLast(controls.$select, having.refs));
+	const groupBy = groupByClause(dialect, controls);
 	let inner = "COUNT(*)";
 	if (groupBy) inner = bucketSelectParts(dialect, controls).join(", ") || "1";
 	return finalizeParams(dialect, {
-		sql: `SELECT ${countCol} FROM (SELECT ${inner} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
+		sql: `SELECT ${countCol} FROM (SELECT ${inner} ${from}${groupBy}${having?.sql ?? ""}) AS ${dialect.quoteIdentifier("_groups")}`,
 		params: [...where.params, ...having?.params ?? []]
 	});
 }
@@ -647,30 +838,16 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 function viewComputeExpr(dialect, c, byPath, resolveFieldRef, grouped = false, cache = /* @__PURE__ */ new Map()) {
 	const cached = cache.get(c.viewPath);
 	if (cached !== void 0) return cached;
-	const cast = dialect.castDouble?.bind(dialect);
-	if (!cast) throw new Error(`View column "${c.viewColumn}": computed view columns are not supported by this adapter`);
-	const render = (e) => {
-		if (typeof e === "number") {
-			if (!Number.isFinite(e)) throw new Error(`View column "${c.viewColumn}": non-finite literal in @db.compute`);
-			return cast(String(e));
-		}
-		if ("field" in e) {
-			const leaf = byPath.get(e.field);
-			if (!leaf) throw new Error(`View column "${c.viewColumn}": "${e.field}" is not a column of the view`);
-			if (leaf.expr !== void 0) return viewComputeExpr(dialect, leaf, byPath, resolveFieldRef, grouped, cache);
-			if (leaf.aggFn) return cast(viewAggExpr(dialect, leaf, resolveFieldRef));
-			const source = viewSourceExpr(dialect, leaf);
-			return cast(grouped && leaf.json ? `MIN(${source})` : source);
-		}
-		const args = e.args.map(render);
-		switch (e.op) {
-			case "neg": return `(-${args[0]})`;
-			case "coalesce": return `COALESCE(${args.join(", ")})`;
-			case "/": return `(${args[0]} / NULLIF(${args[1]}, 0))`;
-			default: return `(${args[0]} ${e.op} ${args[1]})`;
-		}
+	const fail = (reason) => /* @__PURE__ */ new Error(reason === "no-cast" ? `View column "${c.viewColumn}": computed view columns are not supported by this adapter` : `View column "${c.viewColumn}": non-finite literal in @db.compute`);
+	const leaf = (field) => {
+		const mapping = byPath.get(field);
+		if (!mapping) throw new Error(`View column "${c.viewColumn}": "${field}" is not a column of the view`);
+		if (mapping.expr !== void 0) return { double: viewComputeExpr(dialect, mapping, byPath, resolveFieldRef, grouped, cache) };
+		if (mapping.aggFn) return viewAggExpr(dialect, mapping, resolveFieldRef);
+		const source = viewSourceExpr(dialect, mapping);
+		return grouped && mapping.json ? `MIN(${source})` : source;
 	};
-	const sql = render(c.expr);
+	const sql = renderArith(dialect, c.expr, leaf, fail);
 	cache.set(c.viewPath, sql);
 	return sql;
 }
@@ -694,10 +871,7 @@ function firstRowOn(dialect, join, target, condition, resolveFieldRef) {
 		type: join.targetType,
 		field: first.key
 	});
-	return `${key} = (SELECT ${key} FROM ${target} WHERE ${condition} ORDER BY ${first.order.map(({ ref, desc }) => {
-		const nulls = dialect.nullsSortLargest ? desc ? " NULLS LAST" : " NULLS FIRST" : "";
-		return `${resolveFieldRef(ref)} ${desc ? "DESC" : "ASC"}${nulls}`;
-	}).join(", ")} LIMIT 1)`;
+	return `${key} = (SELECT ${key} FROM ${target} WHERE ${condition} ORDER BY ${first.order.map(({ ref, desc }) => orderKeySql(dialect, resolveFieldRef(ref), desc)).join(", ")} LIMIT 1)`;
 }
 /**
 * Builds a CREATE VIEW statement from a view plan and column mappings.
@@ -778,6 +952,21 @@ function insertManyColumns(rows) {
 	return [...columns];
 }
 /**
+* Splits `rows` into batches that stay under the driver's bind-parameter limit
+* (PostgreSQL ~65535, MySQL packet size): `maxParams` (default 60000) divided
+* by the column count. Returns the shared column union and the batches.
+*/
+function chunkInsertRows(rows, maxParams = 6e4) {
+	const columns = insertManyColumns(rows);
+	const size = columns.length > 0 ? Math.max(1, Math.floor(maxParams / columns.length)) : rows.length;
+	const batches = [];
+	for (let offset = 0; offset < rows.length; offset += size) batches.push(rows.slice(offset, offset + size));
+	return {
+		columns,
+		batches
+	};
+}
+/**
 * Builds a multi-row `INSERT … VALUES (…), (…)` statement over `columns`
 * (default: {@link insertManyColumns} of `rows`). A row lacking a column gets
 * `DEFAULT` — exactly what a single-row INSERT omitting it stores. Callers
@@ -1253,4 +1442,4 @@ function parseRegexString(value) {
 	};
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, PARTITION_ROW_NUMBER_ALIAS, SEARCH_SOURCE_ALIAS, SQL_DEFAULT, VECTOR_DISTANCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, chunkInsertRows, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orderKeySql, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, renderArith, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.147",
+  "version": "0.1.149",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -37,12 +37,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@uniqu/core": "^0.1.12",
-    "unplugin-atscript": "^0.1.99"
+    "@uniqu/core": "^0.1.13",
+    "unplugin-atscript": "^0.1.100"
   },
   "peerDependencies": {
-    "@uniqu/core": "^0.1.12",
-    "@atscript/db": "^0.1.147"
+    "@uniqu/core": "^0.1.13",
+    "@atscript/db": "^0.1.149"
   },
   "scripts": {
     "build": "vp pack",