@atscript/db-sql-tools 0.1.146 → 0.1.148

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,12 +81,75 @@ 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`.
 */
 function createFilterVisitor(dialect, options) {
 	const columnRef = options?.columnRef ?? ((field) => dialect.quoteIdentifier(field));
+	const qualifier = options?.qualifier;
+	const aliasSeq = options?.aliasSeq ?? { n: 0 };
 	return {
 		comparison(field, op, value) {
 			if (op === "$geoWithin") {
@@ -153,9 +242,75 @@ function createFilterVisitor(dialect, options) {
 				sql: `NOT (${child.sql})`,
 				params: child.params
 			};
+		},
+		relation(field, op, operand) {
+			if (!(0, _atscript_db.isResolvedRelationFilter)(operand)) throw new _atscript_db.DbError("REL_FILTER_NOT_SUPPORTED", [{
+				path: field,
+				message: `Relational predicate "${op}" on "${field}" reached the SQL renderer unresolved`
+			}]);
+			return renderRelation(dialect, op, operand, qualifier ?? dialect.quoteTable(operand.source.table), aliasSeq);
 		}
 	};
 }
+/**
+* Renders one resolved relational predicate as a correlated `EXISTS`:
+*
+* ```sql
+* -- to / from
+* EXISTS (SELECT 1 FROM <target> AS "_rf1"
+*         WHERE "_rf1"."<pair.target>" = <outer>."<pair.source>" [AND …] [AND <inner>])
+* -- via
+* EXISTS (SELECT 1 FROM <junction> AS "_rf1" JOIN <target> AS "_rf2"
+*           ON "_rf2"."<toTarget.target>" = "_rf1"."<toTarget.junction>" [AND …]
+*         WHERE "_rf1"."<toSource.junction>" = <outer>."<toSource.source>" [AND …]
+*           [AND <junction filter on _rf1>] [AND <inner on _rf2>])
+* ```
+*
+* `$none` is `NOT EXISTS (…)`. Outer columns are always qualified (a bare
+* column would bind to the subquery's table on a self relation or a
+* same-named column). A NULL foreign-key component never satisfies `=`, so
+* such a row has no related row (`$some` false, `$none` true).
+*/
+function renderRelation(dialect, op, node, outer, aliasSeq) {
+	const q = (name) => dialect.quoteIdentifier(name);
+	const nextAlias = () => q(`_rf${++aliasSeq.n}`);
+	const conditions = [];
+	const params = [];
+	const addFilter = (filter, alias) => {
+		if (!filter || Object.keys(filter).length === 0) return;
+		const fragment = (0, _uniqu_core.walkFilter)(filter, createFilterVisitor(dialect, {
+			columnRef: (field) => `${alias}.${q(field)}`,
+			qualifier: alias,
+			aliasSeq
+		}));
+		if (fragment) {
+			conditions.push(fragment.sql);
+			params.push(...fragment.params);
+		}
+	};
+	let from;
+	if (node.kind === "via") {
+		const junction = node.junction;
+		if (!junction) throw new Error(`Relational predicate on "${node.nav}": a "via" relation needs a junction`);
+		const j = nextAlias();
+		const t = nextAlias();
+		const on = junction.toTarget.map((p) => `${t}.${q(p.target)} = ${j}.${q(p.junction)}`);
+		from = `${dialect.quoteTable(junction.table)} AS ${j} JOIN ${dialect.quoteTable(node.target.table)} AS ${t} ON ${on.join(" AND ")}`;
+		for (const p of junction.toSource) conditions.push(`${j}.${q(p.junction)} = ${outer}.${q(p.source)}`);
+		addFilter(junction.filter, j);
+		addFilter(node.filter, t);
+	} else {
+		const t = nextAlias();
+		from = `${dialect.quoteTable(node.target.table)} AS ${t}`;
+		for (const p of node.pairs) conditions.push(`${t}.${q(p.target)} = ${outer}.${q(p.source)}`);
+		addFilter(node.filter, t);
+	}
+	const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+	return {
+		sql: `${op === "$none" ? "NOT " : ""}EXISTS (SELECT 1 FROM ${from}${where})`,
+		params
+	};
+}
 const visitorCache = /* @__PURE__ */ new WeakMap();
 function getVisitor(dialect) {
 	let visitor = visitorCache.get(dialect);
@@ -167,10 +322,23 @@ function getVisitor(dialect) {
 }
 /**
 * Translates a filter expression into a parameterized SQL WHERE clause.
+*
+* Relational predicates (`{ nav: { $some | $none: … } }`, resolved by the
+* core into `ResolvedRelationFilter` operands) render as correlated
+* `[NOT] EXISTS (…)` subqueries; `opts.qualifier` names the outer table or
+* alias they correlate to (default: the source table — see
+* {@link TFilterVisitorOptions.qualifier}). `opts.columnRef` overrides how
+* the filter's own columns render (e.g. `t."col"` for an aliased FROM).
+* Placeholders stay positional `?` in textual order.
+*
+* @param opts - since 0.1.147
 */
-function buildWhere(dialect, filter) {
+function buildWhere(dialect, filter, opts) {
 	if (!filter || Object.keys(filter).length === 0) return EMPTY_AND;
-	return (0, _uniqu_core.walkFilter)(filter, getVisitor(dialect)) ?? EMPTY_AND;
+	return (0, _uniqu_core.walkFilter)(filter, opts || (0, _atscript_db.containsRelationFilter)(filter) ? createFilterVisitor(dialect, {
+		...opts,
+		aliasSeq: opts?.aliasSeq ?? { n: 0 }
+	}) : getVisitor(dialect)) ?? EMPTY_AND;
 }
 //#endregion
 //#region src/common.ts
@@ -215,6 +383,20 @@ function toSqlValue(value) {
 	if (typeof value === "boolean") return value ? 1 : 0;
 	return value;
 }
+/**
+* `FOREIGN KEY (…) REFERENCES <target> (…)[ ON DELETE …][ ON UPDATE …]` of a
+* foreign key over its physical columns ({@link fkColumns}); the target is
+* schema-qualified when it declares `@db.schema`. `quote` quotes one
+* identifier.
+*/
+function foreignKeySql(quote, fk) {
+	const { fields, targetFields } = (0, _atscript_db.fkColumns)(fk);
+	const target = fk.targetSchema ? `${quote(fk.targetSchema)}.${quote(fk.targetTable)}` : quote(fk.targetTable);
+	let sql = `FOREIGN KEY (${fields.map(quote).join(", ")}) REFERENCES ${target} (${targetFields.map(quote).join(", ")})`;
+	if (fk.onDelete) sql += ` ON DELETE ${refActionToSql(fk.onDelete)}`;
+	if (fk.onUpdate) sql += ` ON UPDATE ${refActionToSql(fk.onUpdate)}`;
+	return sql;
+}
 function refActionToSql(action) {
 	switch (action) {
 		case "cascade": return "CASCADE";
@@ -333,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);
@@ -389,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);
@@ -416,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) {
@@ -473,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 ?? []]
 	});
 }
@@ -532,6 +818,63 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 	return c.aggFn === "sum" ? `COALESCE(${call}, 0)` : call;
 }
 /**
+* The SQL expression of a computed view column (`@db.compute`), evaluated in
+* IEEE double on every dialect: each field and literal leaf is cast with
+* {@link SqlDialect.castDouble} (a computed leaf is already a double and is
+* inlined); `+ - *` render as `(l op r)`, `/` as `(l / NULLIF(r, 0))` —
+* division by zero is NULL — unary minus as `(-x)`, `coalesce` as
+* `COALESCE(…)`. A leaf reads its column like the SELECT list does: an
+* aggregate's call ({@link viewAggExpr}) or a dimension's source
+* ({@link viewSourceExpr}). `byPath` holds the view's mappings by `viewPath`.
+*
+* In a `grouped` view a JSON-extracted dimension leaf reads `MIN(<extract>)`:
+* the extraction is a GROUP BY key, so every row of a group holds the same
+* value, but MySQL's ONLY_FULL_GROUP_BY rejects an expression over the raw
+* JSON column (which is not itself grouped) — the aggregate form is accepted
+* everywhere and yields that same value.
+*
+* @throws when the dialect has no `castDouble`, or a leaf names no column.
+* @since 0.1.147
+*/
+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 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 = renderArith(dialect, c.expr, leaf, fail);
+	cache.set(c.viewPath, sql);
+	return sql;
+}
+/**
+* The `ON` clause of a first-row join (`join.first`): the joined row is the
+* one whose primary key equals the key of the FIRST matching target row —
+* a correlated scalar subquery
+* `"T"."id" = (SELECT "T"."id" FROM "table" AS "T" WHERE <condition> ORDER BY … LIMIT 1)`.
+* The inner `FROM` repeats the join's own target / alias text, so the
+* condition's refs to the joined scope bind to the inner row (SQL name
+* shadowing) while refs to the entry and earlier joins stay correlated to
+* the outer query. The ordering ends with the primary key, so the pick is
+* deterministic; NULL sorts first in `asc` (`nullsSortLargest` dialects
+* render `NULLS FIRST` / `NULLS LAST`). No window functions — SQLite, MySQL 8
+* and PostgreSQL render it alike.
+* @since 0.1.147
+*/
+function firstRowOn(dialect, join, target, condition, resolveFieldRef) {
+	const first = join.first;
+	const key = resolveFieldRef({
+		type: join.targetType,
+		field: first.key
+	});
+	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.
 *
 * Joins render in declaration order — `JOIN` (inner, the default) or
@@ -543,35 +886,41 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 * join target may be views.
 */
 function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
-	const selectCols = columns.map((c) => {
-		return `${c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`;
-	}).join(", ");
+	const columnByPath = new Map(columns.map((c) => [c.viewPath, c]));
+	const hasAggregates = columns.some((c) => c.aggFn);
+	const computedSql = /* @__PURE__ */ new Map();
+	/** A column's SELECT expression: computed, aggregate or plain source. */
+	const columnExpr = (c) => c.expr !== void 0 ? viewComputeExpr(dialect, c, columnByPath, resolveFieldRef, hasAggregates, computedSql) : c.aggFn ? viewAggExpr(dialect, c, resolveFieldRef) : viewSourceExpr(dialect, c);
+	const selectCols = columns.map((c) => `${columnExpr(c)} AS ${dialect.quoteIdentifier(c.viewColumn)}`).join(", ");
 	let sql = `${dialect.createViewPrefix} ${dialect.quoteTable(viewName)} AS SELECT ${selectCols} FROM ${dialect.quoteIdentifier(plan.entryTable)}`;
 	for (const join of plan.joins) {
-		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
+		const condition = queryNodeToSql(join.condition, resolveFieldRef);
 		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
 		const target = join.scope === join.targetTable ? dialect.quoteIdentifier(join.targetTable) : `${dialect.quoteIdentifier(join.targetTable)} AS ${dialect.quoteIdentifier(join.scope)}`;
+		const onClause = join.first ? firstRowOn(dialect, join, target, condition, resolveFieldRef) : condition;
 		sql += ` ${keyword} ${target} ON ${onClause}`;
 	}
 	if (plan.filter) {
 		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
 		sql += ` WHERE ${whereClause}`;
 	}
-	if (columns.some((c) => c.aggFn)) {
-		const dimensionCols = columns.filter((c) => !c.aggFn);
+	if (hasAggregates) {
+		const dimensionCols = columns.filter((c) => !c.aggFn && c.expr === void 0);
 		if (dimensionCols.length > 0) {
 			const groupByCols = dimensionCols.map((c) => viewSourceExpr(dialect, c)).join(", ");
 			sql += ` GROUP BY ${groupByCols}`;
 		}
 		if (plan.having) {
-			const columnByPath = /* @__PURE__ */ new Map();
-			for (const c of columns) columnByPath.set(c.viewPath, c);
+			let grouped;
+			const groupedColumns = () => grouped ??= new Set(dimensionCols.filter((c) => !c.json).map((c) => c.sourceColumn.toLowerCase()));
 			const havingResolver = (ref) => {
 				const col = ref.type ? void 0 : columnByPath.get(ref.field);
 				if (!col) return resolveFieldRef(ref);
+				if (col.expr !== void 0) return columnExpr(col);
 				if (col.aggFn) return viewAggExpr(dialect, col, resolveFieldRef);
 				const expr = viewSourceExpr(dialect, col);
-				return col.json ? havingGroupRef(dialect, expr, col.viewColumn) : expr;
+				if (!col.json) return expr;
+				return dialect.bucketAliasInHaving && groupedColumns().has(col.viewColumn.toLowerCase()) ? `MIN(${expr})` : havingGroupRef(dialect, expr, col.viewColumn);
 			};
 			const havingClause = queryNodeToSql(plan.having, havingResolver);
 			sql += ` HAVING ${havingClause}`;
@@ -604,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
@@ -632,11 +996,8 @@ function buildInsertMany(dialect, table, rows, columns = insertManyColumns(rows)
 function buildSelect(dialect, table, where, controls) {
 	let sql = `SELECT ${buildProjection(dialect, controls?.$select)} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
 	const params = [...where.params];
-	if (controls?.$sort) {
-		const orderParts = [];
-		for (const [col, dir] of Object.entries(controls.$sort)) orderParts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
-		if (orderParts.length > 0) sql += ` ORDER BY ${orderParts.join(", ")}`;
-	}
+	const orderBy = orderByList(dialect, controls?.$sort);
+	if (orderBy) sql += ` ORDER BY ${orderBy}`;
 	if (controls?.$limit !== void 0) {
 		sql += ` LIMIT ?`;
 		params.push(controls.$limit);
@@ -651,6 +1012,53 @@ function buildSelect(dialect, table, where, controls) {
 		params
 	});
 }
+/** `"col" ASC, "other" DESC` of a physical `$sort` — `""` when it orders nothing. */
+function orderByList(dialect, sort) {
+	if (!sort) return "";
+	const parts = [];
+	for (const [col, dir] of Object.entries(sort)) parts.push(`${dialect.quoteIdentifier(col)} ${dir === -1 ? "DESC" : "ASC"}`);
+	return parts.join(", ");
+}
+/**
+* The row-number column {@link buildPartitionedSelect} adds to every row;
+* {@link stripPartitionRowNumber} removes it from the result rows.
+* @since 0.1.147
+*/
+const PARTITION_ROW_NUMBER_ALIAS = "__atscript_rn";
+/**
+* Builds a SELECT whose `$skip` / `$limit` apply to each partition — the rows
+* sharing the values of the `partitionBy` columns (physical names) — instead
+* of to the whole result: a `ROW_NUMBER() OVER (PARTITION BY … ORDER BY
+* <$sort>)` window in a derived table, filtered on the row number. The rows
+* of each partition come out in `$sort` order (partitions interleave); every
+* row carries {@link PARTITION_ROW_NUMBER_ALIAS}. Window functions need
+* SQLite ≥ 3.25, MySQL ≥ 8.0 or MariaDB ≥ 10.2.
+* @since 0.1.147
+*/
+function buildPartitionedSelect(dialect, table, where, controls, partitionBy) {
+	const rn = dialect.quoteIdentifier(PARTITION_ROW_NUMBER_ALIAS);
+	const orderBy = orderByList(dialect, controls.$sort);
+	const window = `PARTITION BY ${partitionBy.map((col) => dialect.quoteIdentifier(col)).join(", ")}` + (orderBy ? ` ORDER BY ${orderBy}` : "");
+	const inner = `SELECT ${buildProjection(dialect, controls.$select)}, ROW_NUMBER() OVER (${window}) AS ${rn} FROM ${dialect.quoteTable(table)} WHERE ${where.sql}`;
+	const skip = controls.$skip ?? 0;
+	const limit = controls.$limit;
+	const params = [...where.params, skip];
+	let sql = `SELECT * FROM (${inner}) AS ${dialect.quoteIdentifier("__atscript_p")} WHERE ${rn} > ?`;
+	if (limit !== void 0 && limit !== null) {
+		sql += ` AND ${rn} <= ?`;
+		params.push(skip + limit);
+	}
+	sql += ` ORDER BY ${rn}`;
+	return finalizeParams(dialect, {
+		sql,
+		params
+	});
+}
+/** Removes {@link PARTITION_ROW_NUMBER_ALIAS} from rows read by {@link buildPartitionedSelect}. */
+function stripPartitionRowNumber(rows) {
+	for (const row of rows) delete row[PARTITION_ROW_NUMBER_ALIAS];
+	return rows;
+}
 /**
 * Marker value for {@link buildUpdate}: the column is assigned its DDL
 * `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
@@ -810,6 +1218,13 @@ function buildProjection(dialect, select, qualifier) {
 */
 const GEO_DISTANCE_ALIAS = "__atscript_distance";
 /**
+* Alias of the searched table inside the geo and vector search statements —
+* a filter rendered into them correlates its relational predicates to it
+* (`buildWhere(filter, { qualifier: dialect.quoteTable(SEARCH_SOURCE_ALIAS) })`).
+* @since 0.1.147
+*/
+const SEARCH_SOURCE_ALIAS = "t";
+/**
 * Builds a distance-ranked geo search SELECT:
 *
 * ```sql
@@ -1032,8 +1447,11 @@ exports.AGG_FN_SQL = AGG_FN_SQL;
 exports.EMPTY_AND = EMPTY_AND;
 exports.EMPTY_OR = EMPTY_OR;
 exports.GEO_DISTANCE_ALIAS = GEO_DISTANCE_ALIAS;
+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;
@@ -1042,31 +1460,39 @@ exports.buildGeoSearchCount = buildGeoSearchCount;
 exports.buildGeoSearchSelect = buildGeoSearchSelect;
 exports.buildInsert = buildInsert;
 exports.buildInsertMany = buildInsertMany;
+exports.buildPartitionedSelect = buildPartitionedSelect;
 exports.buildProjection = buildProjection;
 exports.buildSelect = buildSelect;
 exports.buildUpdate = buildUpdate;
 exports.buildVectorSearchCount = buildVectorSearchCount;
 exports.buildVectorSearchSelect = buildVectorSearchSelect;
 exports.buildWhere = buildWhere;
+exports.chunkInsertRows = chunkInsertRows;
 exports.createFilterVisitor = createFilterVisitor;
 exports.defaultValueForType = defaultValueForType;
 exports.defaultValueToSqlLiteral = defaultValueToSqlLiteral;
 exports.derivedColumnExpr = derivedColumnExpr;
 exports.fillReplacePayload = fillReplacePayload;
 exports.finalizeParams = finalizeParams;
+exports.foreignKeySql = foreignKeySql;
 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;
+exports.stripPartitionRowNumber = stripPartitionRowNumber;
 exports.toSqlValue = toSqlValue;
 exports.vectorDistanceSource = vectorDistanceSource;