@atscript/db-sql-tools 0.1.146 → 0.1.148

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AtscriptQueryFieldRef, AtscriptQueryNode, DbControls, TDbDefaultFn, TDbFieldMeta, 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";
 
@@ -34,8 +34,10 @@ interface SqlDialect {
   geoWithin?(quotedCol: string, circle: TGeoCircle): TSqlFragment;
   /**
    * Calendar-bucket label expression over one column: TEXT `'YYYY-MM-DD'`
-   * (the local calendar date of the bucket's first day in `b.tz`), or NULL for
-   * a NULL source or one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
+   * (the local calendar date of the bucket's first day in `b.tz`; for unit
+   * `hour`, `'YYYY-MM-DDTHH:00'`, the local wall-clock hour — truncate the
+   * zone's wall time, never the UTC instant), or NULL for a NULL source or
+   * one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
    * `quotedCol` is already quoted; `b.fd` identifies the storage kind.
    *
    * The expression must be PARAMETER-FREE — inline the zone with
@@ -83,6 +85,56 @@ interface SqlDialect {
    * @since 0.1.136
    */
   jsonExtract?(quotedCol: string, path: readonly string[], type: TViewJsonType): string;
+  /**
+   * `expr` cast to an IEEE double — how a computed view column
+   * (`@db.compute`) evaluates every field / literal leaf, so `7 / 2 = 3.5`
+   * everywhere (no integer division, no DECIMAL rounding): SQLite
+   * `CAST(x AS REAL)`, MySQL `CAST(x AS DOUBLE)`, PostgreSQL
+   * `CAST(x AS DOUBLE PRECISION)`. Parameter-free. Dialects without it fail
+   * view sync with `computed view columns are not supported by this adapter`.
+   * @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` /
+   * `DESC NULLS LAST`, keeping the uniform "NULL is the smallest value"
+   * ordering SQLite, MySQL and MongoDB have natively.
+   * @since 0.1.147
+   */
+  nullsSortLargest?: boolean;
   /** e.g. 'CREATE VIEW IF NOT EXISTS' or 'CREATE OR REPLACE VIEW' */
   createViewPrefix: string;
   /** Returns a parameter placeholder for the given 1-based index. When absent, '?' is used. */
@@ -93,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"}'`).
@@ -108,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 {
   /**
@@ -117,6 +212,35 @@ interface TFilterVisitorOptions {
    * expression (`SUM("amount")`) — PostgreSQL rejects SELECT aliases in HAVING.
    */
   columnRef?: (field: string) => string;
+  /**
+   * The quoted outer table or alias that relational predicates
+   * (`{ nav: { $some | $none: … } }`) correlate to: their `EXISTS` subqueries
+   * compare the related rows with `<qualifier>."<column>"`. Defaults to the
+   * predicate's source table (`dialect.quoteTable(node.source.table)`), which
+   * is right for every statement whose FROM is the bare table; a statement
+   * that aliases its FROM (`FROM "items" AS "t"`) must pass that alias here.
+   *
+   * @since 0.1.147
+   */
+  qualifier?: string;
+  /**
+   * Alias sequence of the relational-predicate subqueries (`_rf1`, `_rf2`, …),
+   * shared by the visitors of one statement so nested predicates get distinct
+   * aliases. A visitor created without one starts its own.
+   *
+   * @internal
+   * @since 0.1.147
+   */
+  aliasSeq?: TRelationAliasSeq;
+}
+/**
+ * Alias counter of the relational-predicate subqueries of one statement.
+ *
+ * @internal
+ * @since 0.1.147
+ */
+interface TRelationAliasSeq {
+  n: number;
 }
 /**
  * Creates a dialect-specific filter visitor for `walkFilter`.
@@ -124,8 +248,18 @@ interface TFilterVisitorOptions {
 declare function createFilterVisitor(dialect: SqlDialect, options?: TFilterVisitorOptions): FilterVisitor<TSqlFragment>;
 /**
  * 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
  */
-declare function buildWhere(dialect: SqlDialect, filter: FilterExpr): TSqlFragment;
+declare function buildWhere(dialect: SqlDialect, filter: FilterExpr, opts?: TFilterVisitorOptions): TSqlFragment;
 //#endregion
 //#region src/geo.d.ts
 /**
@@ -135,6 +269,13 @@ declare function buildWhere(dialect: SqlDialect, filter: FilterExpr): TSqlFragme
  * across dialects, so the public name can't be used directly.
  */
 declare 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
+ */
+declare const SEARCH_SOURCE_ALIAS = "t";
 /** The query controls a geo search page reads — an adapter passes its `query.controls` as-is. */
 interface TGeoSearchControls {
   $limit?: number;
@@ -260,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
@@ -272,6 +422,25 @@ declare function buildInsertMany(dialect: SqlDialect, table: string, rows: reado
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  */
 declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+/**
+ * The row-number column {@link buildPartitionedSelect} adds to every row;
+ * {@link stripPartitionRowNumber} removes it from the result rows.
+ * @since 0.1.147
+ */
+declare 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
+ */
+declare function buildPartitionedSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls, partitionBy: readonly string[]): TSqlFragment;
+/** Removes {@link PARTITION_ROW_NUMBER_ALIAS} from rows read by {@link buildPartitionedSelect}. */
+declare function stripPartitionRowNumber<R extends Record<string, unknown>>(rows: R[]): R[];
 /**
  * Marker value for {@link buildUpdate}: the column is assigned its DDL
  * `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
@@ -376,6 +545,13 @@ declare function jsonDollarPath(path: readonly string[]): string;
 declare function sqlTimeZoneLiteral(tz: string): string;
 /** Converts a JS value to a SQL-bindable parameter. Objects/arrays -> JSON, booleans -> 0/1. */
 declare function toSqlValue(value: unknown): unknown;
+/**
+ * `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.
+ */
+declare function foreignKeySql(quote: (name: string) => string, fk: TDbForeignKey): string;
 declare function refActionToSql(action: TDbReferentialAction): string;
 /** Returns a safe SQL DEFAULT literal for a given design type. */
 declare function defaultValueForType(designType: string): string;
@@ -403,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
@@ -420,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).
  */
@@ -429,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
@@ -446,4 +626,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_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, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, 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, TDbReferentialAction, TFieldOps, TResolvedBucket, TViewColumnMapping, TViewJsonType, TViewPlan, UniquSelect } from "@atscript/db";
 import { TDbAggregateFn } from "@atscript/db/agg";
 
 //#region src/dialect.d.ts
@@ -34,8 +34,10 @@ interface SqlDialect {
   geoWithin?(quotedCol: string, circle: TGeoCircle): TSqlFragment;
   /**
    * Calendar-bucket label expression over one column: TEXT `'YYYY-MM-DD'`
-   * (the local calendar date of the bucket's first day in `b.tz`), or NULL for
-   * a NULL source or one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
+   * (the local calendar date of the bucket's first day in `b.tz`; for unit
+   * `hour`, `'YYYY-MM-DDTHH:00'`, the local wall-clock hour — truncate the
+   * zone's wall time, never the UTC instant), or NULL for a NULL source or
+   * one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
    * `quotedCol` is already quoted; `b.fd` identifies the storage kind.
    *
    * The expression must be PARAMETER-FREE — inline the zone with
@@ -83,6 +85,56 @@ interface SqlDialect {
    * @since 0.1.136
    */
   jsonExtract?(quotedCol: string, path: readonly string[], type: TViewJsonType): string;
+  /**
+   * `expr` cast to an IEEE double — how a computed view column
+   * (`@db.compute`) evaluates every field / literal leaf, so `7 / 2 = 3.5`
+   * everywhere (no integer division, no DECIMAL rounding): SQLite
+   * `CAST(x AS REAL)`, MySQL `CAST(x AS DOUBLE)`, PostgreSQL
+   * `CAST(x AS DOUBLE PRECISION)`. Parameter-free. Dialects without it fail
+   * view sync with `computed view columns are not supported by this adapter`.
+   * @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` /
+   * `DESC NULLS LAST`, keeping the uniform "NULL is the smallest value"
+   * ordering SQLite, MySQL and MongoDB have natively.
+   * @since 0.1.147
+   */
+  nullsSortLargest?: boolean;
   /** e.g. 'CREATE VIEW IF NOT EXISTS' or 'CREATE OR REPLACE VIEW' */
   createViewPrefix: string;
   /** Returns a parameter placeholder for the given 1-based index. When absent, '?' is used. */
@@ -93,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"}'`).
@@ -108,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 {
   /**
@@ -117,6 +212,35 @@ interface TFilterVisitorOptions {
    * expression (`SUM("amount")`) — PostgreSQL rejects SELECT aliases in HAVING.
    */
   columnRef?: (field: string) => string;
+  /**
+   * The quoted outer table or alias that relational predicates
+   * (`{ nav: { $some | $none: … } }`) correlate to: their `EXISTS` subqueries
+   * compare the related rows with `<qualifier>."<column>"`. Defaults to the
+   * predicate's source table (`dialect.quoteTable(node.source.table)`), which
+   * is right for every statement whose FROM is the bare table; a statement
+   * that aliases its FROM (`FROM "items" AS "t"`) must pass that alias here.
+   *
+   * @since 0.1.147
+   */
+  qualifier?: string;
+  /**
+   * Alias sequence of the relational-predicate subqueries (`_rf1`, `_rf2`, …),
+   * shared by the visitors of one statement so nested predicates get distinct
+   * aliases. A visitor created without one starts its own.
+   *
+   * @internal
+   * @since 0.1.147
+   */
+  aliasSeq?: TRelationAliasSeq;
+}
+/**
+ * Alias counter of the relational-predicate subqueries of one statement.
+ *
+ * @internal
+ * @since 0.1.147
+ */
+interface TRelationAliasSeq {
+  n: number;
 }
 /**
  * Creates a dialect-specific filter visitor for `walkFilter`.
@@ -124,8 +248,18 @@ interface TFilterVisitorOptions {
 declare function createFilterVisitor(dialect: SqlDialect, options?: TFilterVisitorOptions): FilterVisitor<TSqlFragment>;
 /**
  * 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
  */
-declare function buildWhere(dialect: SqlDialect, filter: FilterExpr): TSqlFragment;
+declare function buildWhere(dialect: SqlDialect, filter: FilterExpr, opts?: TFilterVisitorOptions): TSqlFragment;
 //#endregion
 //#region src/geo.d.ts
 /**
@@ -135,6 +269,13 @@ declare function buildWhere(dialect: SqlDialect, filter: FilterExpr): TSqlFragme
  * across dialects, so the public name can't be used directly.
  */
 declare 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
+ */
+declare const SEARCH_SOURCE_ALIAS = "t";
 /** The query controls a geo search page reads — an adapter passes its `query.controls` as-is. */
 interface TGeoSearchControls {
   $limit?: number;
@@ -260,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
@@ -272,6 +422,25 @@ declare function buildInsertMany(dialect: SqlDialect, table: string, rows: reado
  * Builds a SELECT statement with optional sort, limit, offset, projection.
  */
 declare function buildSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls?: DbControls): TSqlFragment;
+/**
+ * The row-number column {@link buildPartitionedSelect} adds to every row;
+ * {@link stripPartitionRowNumber} removes it from the result rows.
+ * @since 0.1.147
+ */
+declare 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
+ */
+declare function buildPartitionedSelect(dialect: SqlDialect, table: string, where: TSqlFragment, controls: DbControls, partitionBy: readonly string[]): TSqlFragment;
+/** Removes {@link PARTITION_ROW_NUMBER_ALIAS} from rows read by {@link buildPartitionedSelect}. */
+declare function stripPartitionRowNumber<R extends Record<string, unknown>>(rows: R[]): R[];
 /**
  * Marker value for {@link buildUpdate}: the column is assigned its DDL
  * `DEFAULT` (`SET "col" = DEFAULT`, no bound parameter). Produced by
@@ -376,6 +545,13 @@ declare function jsonDollarPath(path: readonly string[]): string;
 declare function sqlTimeZoneLiteral(tz: string): string;
 /** Converts a JS value to a SQL-bindable parameter. Objects/arrays -> JSON, booleans -> 0/1. */
 declare function toSqlValue(value: unknown): unknown;
+/**
+ * `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.
+ */
+declare function foreignKeySql(quote: (name: string) => string, fk: TDbForeignKey): string;
 declare function refActionToSql(action: TDbReferentialAction): string;
 /** Returns a safe SQL DEFAULT literal for a given design type. */
 declare function defaultValueForType(designType: string): string;
@@ -403,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
@@ -420,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).
  */
@@ -429,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
@@ -446,4 +626,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_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, buildProjection, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, 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 };