ts-prorm-orm 1.1.0 → 1.2.1

package/dist/query-builders/functions/math.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Typed math-function builder API.
+ *
+ * Provides typed, autocomplete-friendly builders for common SQL math
+ * functions (`ROUND`, `CEIL`/`CEILING`, `FLOOR`, `POWER`, `MOD`, random
+ * number generation, `GREATEST`/`LEAST`, `TRUNC`/`TRUNCATE`, ...) across all
+ * 11 supported dialects, so callers never need to hand-write raw,
+ * dialect-specific SQL for these.
+ *
+ * This module is intentionally self-contained: it does not add any new
+ * dispatch branches to the shared SQL compiler. Every builder resolves
+ * directly to a final, dialect-correct SQL fragment string, which is then
+ * wrapped with the existing `literal()` helper from `src/operators.ts` so it
+ * slots into `attributes: [...]`, `where`, etc. exactly the way `fn()`/
+ * `col()`/`cast()` do today.
+ *
+ * Dialect quirks verified while building this (do not assume symmetry with
+ * Postgres/MySQL):
+ *
+ *  - `RANDOM()`/`RAND()` do NOT uniformly return a float in `[0, 1)`:
+ *      - mysql / mariadb / mssql / db2: `RAND()` -> float in [0, 1).
+ *      - postgres / cockroachdb / redshift: `RANDOM()` -> float in [0, 1).
+ *      - sqlite: `RANDOM()` returns a *signed 64-bit integer*
+ *        (-2^63 .. 2^63-1), NOT a [0,1) float. It must be normalized.
+ *      - snowflake: `RANDOM()` returns a random *64-bit integer* as well
+ *        (not [0,1)); the documented way to get a uniform float is
+ *        `UNIFORM(0::FLOAT, 1::FLOAT, RANDOM())`.
+ *      - oracle: no `RANDOM()`/`RAND()` at all -- must use
+ *        `DBMS_RANDOM.VALUE`.
+ *      - clickhouse: `rand()` returns a `UInt32` (0 .. 2^32-1), NOT [0,1).
+ *        The [0,1) equivalent is `randCanonical()`.
+ *
+ *  - `CEIL` vs `CEILING`: T-SQL (mssql) has no `CEIL` function at all --
+ *    only `CEILING`. All other dialects here accept `CEIL`.
+ *
+ *  - `GREATEST`/`LEAST`: not supported natively before SQL Server 2022, so
+ *    mssql gets a portable nested-`CASE` fallback here (works on every
+ *    supported SQL Server version, not just 2022+). sqlite has no
+ *    `GREATEST`/`LEAST` keywords either, but its scalar `MAX`/`MIN` (called
+ *    with 2+ arguments) behave exactly like `GREATEST`/`LEAST`, so that is
+ *    used instead.
+ *
+ *  - `MOD`: mssql has no `MOD()` function -- only the `%` operator.
+ *    clickhouse's function is named `modulo`, not `mod`.
+ *
+ *  - `TRUNCATE`/`TRUNC`: MySQL/MariaDB use `TRUNCATE(value, decimals)`;
+ *    Oracle/Postgres/CockroachDB/Redshift/DB2/Snowflake use
+ *    `TRUNC(value, decimals)`; mssql has neither -- truncation is done via
+ *    `ROUND(value, decimals, 1)` (the undocumented-looking-but-real third
+ *    "truncate instead of round" argument of T-SQL's `ROUND`); sqlite's
+ *    `trunc()` math-extension function only takes a single argument (no
+ *    decimals), so a `TRUNC(value * 10^n) / 10^n` fallback is used when
+ *    `decimals` is supplied.
+ *
+ *  - ClickHouse function names are matched to ClickHouse's own lower-case
+ *    documented spelling (`round`, `floor`, `ceil`, `abs`, `sign`, `pow`,
+ *    `modulo`, `trunc`, `greatest`, `least`, `rand`, `randCanonical`) rather
+ *    than upper-cased ANSI style, since not all of them have registered
+ *    case-insensitive aliases.
+ *
+ * @example
+ * ```typescript
+ * import { round, power, random, greatest } from './query-builders/functions/math';
+ * import { col } from '../../operators';
+ *
+ * User.findAll({
+ *   attributes: [
+ *     [round('postgres', col('price'), 2), 'roundedPrice'],
+ *     [power('postgres', col('base'), 2), 'squared'],
+ *     [random('postgres'), 'rnd'],
+ *     [greatest('mssql', col('a'), col('b'), 10), 'best'],
+ *   ],
+ * });
+ * ```
+ */
+import { type FnExpression, type ColExpression, type LiteralExpression } from '../../operators';
+import type { Dialect } from '../../types/index';
+/**
+ * Acceptable argument types for math-function builders: plain numbers/
+ * strings (treated as literal SQL values), or other typed expressions
+ * (`col()`, `fn()`, `literal()`).
+ */
+export type SqlExpr = string | number | ColExpression | FnExpression | LiteralExpression | {
+    $literal: string;
+};
+/**
+ * `ROUND(value[, decimals])`
+ *
+ * ANSI-consistent across all 11 dialects: MySQL, MariaDB, Postgres, MSSQL,
+ * Oracle, SQLite (math-functions extension, 3.35+), CockroachDB, Redshift,
+ * DB2, Snowflake, and ClickHouse all accept an optional second `decimals`
+ * argument with the same semantics.
+ */
+export declare function round(dialect: Dialect, expr: SqlExpr, decimals?: number): {
+    $literal: string;
+};
+/**
+ * `CEIL(value)` / `CEILING(value)`.
+ *
+ * mssql has no `CEIL` -- only `CEILING`. Every other dialect here accepts
+ * `CEIL` (ClickHouse spells it lower-case).
+ */
+export declare function ceil(dialect: Dialect, expr: SqlExpr): {
+    $literal: string;
+};
+/**
+ * `FLOOR(value)`. Consistent naming across all 11 dialects.
+ */
+export declare function floor(dialect: Dialect, expr: SqlExpr): {
+    $literal: string;
+};
+/**
+ * `POWER(base, exponent)`.
+ *
+ * Consistent across all 11 dialects (SQLite's math-functions extension
+ * registers both `pow` and `power` as synonyms; ClickHouse registers `pow`
+ * and `power` as synonyms too -- lower-cased here for ClickHouse).
+ */
+export declare function power(dialect: Dialect, base: SqlExpr, exponent: SqlExpr): {
+    $literal: string;
+};
+/**
+ * `SQRT(value)`. Consistent naming across all 11 dialects.
+ */
+export declare function sqrt(dialect: Dialect, expr: SqlExpr): {
+    $literal: string;
+};
+/**
+ * `ABS(value)`. Consistent naming across all 11 dialects.
+ */
+export declare function abs(dialect: Dialect, expr: SqlExpr): {
+    $literal: string;
+};
+/**
+ * `SIGN(value)` -- returns -1/0/1.
+ *
+ * Every dialect here has a native `SIGN()` function EXCEPT sqlite, whose
+ * built-in math-functions extension does not include `sign` at all -- so a
+ * portable `CASE` expression is used for sqlite instead.
+ */
+export declare function sign(dialect: Dialect, expr: SqlExpr): {
+    $literal: string;
+};
+/**
+ * `MOD(dividend, divisor)`.
+ *
+ * mssql has no `MOD()` function at all -- only the `%` operator, so mssql
+ * renders `(dividend % divisor)`. ClickHouse's function is named `modulo`
+ * (not `mod`). Every other dialect here has a native `MOD(a, b)` function.
+ */
+export declare function mod(dialect: Dialect, dividend: SqlExpr, divisor: SqlExpr): {
+    $literal: string;
+};
+/**
+ * Random value in `[0, 1)`, using the REAL per-dialect function/expression
+ * (deliberately not assumed symmetric):
+ *
+ *  - mysql / mariadb: `RAND()`
+ *  - postgres / cockroachdb / redshift: `RANDOM()`
+ *  - mssql: `RAND()`
+ *  - oracle: `DBMS_RANDOM.VALUE` (no `RAND()`/`RANDOM()` exists in Oracle)
+ *  - db2: `RAND()`
+ *  - sqlite: `RANDOM()` returns a signed 64-bit *integer*, not a [0,1)
+ *    float -- normalized here via `(0.5 + RANDOM() / 18446744073709551616.0)`.
+ *  - snowflake: `RANDOM()` also returns a 64-bit integer, not [0,1) --
+ *    normalized here via `UNIFORM(0::FLOAT, 1::FLOAT, RANDOM())`, which is
+ *    Snowflake's documented way to get a uniform float.
+ *  - clickhouse: `rand()` returns a `UInt32`, not [0,1) -- `randCanonical()`
+ *    is ClickHouse's documented [0,1) float generator.
+ */
+export declare function random(dialect: Dialect): {
+    $literal: string;
+};
+/**
+ * `GREATEST(v1, v2, ...)`.
+ *
+ * - mssql: no native `GREATEST` before SQL Server 2022 -- a portable nested
+ *   `CASE` expression is used so it works on every supported SQL Server
+ *   version (not just 2022+).
+ * - sqlite: no `GREATEST` keyword -- but scalar `MAX(v1, v2, ...)` (called
+ *   with 2+ args) behaves exactly like `GREATEST`, so that is used instead.
+ * - every other dialect here has native `GREATEST(...)`.
+ */
+export declare function greatest(dialect: Dialect, ...values: SqlExpr[]): {
+    $literal: string;
+};
+/**
+ * `LEAST(v1, v2, ...)`.
+ *
+ * Same quirks as {@link greatest}: mssql falls back to a nested `CASE`
+ * expression, sqlite uses scalar `MIN(v1, v2, ...)`.
+ */
+export declare function least(dialect: Dialect, ...values: SqlExpr[]): {
+    $literal: string;
+};
+/**
+ * Truncate a value toward zero (no rounding), optionally to `decimals`
+ * decimal places.
+ *
+ * - mysql / mariadb: `TRUNCATE(value, decimals)` (function name is
+ *   `TRUNCATE`, not `TRUNC`; decimals defaults to 0 when omitted).
+ * - oracle / postgres / cockroachdb / redshift / db2 / snowflake:
+ *   `TRUNC(value, decimals)`.
+ * - mssql: no `TRUNC`/`TRUNCATE` function at all -- uses the (real, if
+ *   obscure) third argument of T-SQL's `ROUND(value, decimals, function)`,
+ *   where a non-zero third argument truncates instead of rounding:
+ *   `ROUND(value, decimals, 1)`.
+ * - sqlite: the math-functions extension's `trunc(X)` only accepts a single
+ *   argument (no decimals support) -- when `decimals` is supplied, a
+ *   `TRUNC(value * 10^n) / 10^n` fallback is used.
+ * - clickhouse: `trunc(value, decimals)` (lower-case, 2-arg form supported).
+ */
+export declare function truncate(dialect: Dialect, expr: SqlExpr, decimals?: number): {
+    $literal: string;
+};

package/dist/query-builders/functions/string.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Typed string-function builders.
+ *
+ * These helpers produce dialect-correct SQL fragments for common string
+ * operations (CONCAT, SUBSTRING, TRIM, padding, etc.) so callers never need
+ * to hand-write raw SQL for the handful of functions that genuinely differ
+ * between dialects (Postgres `||` vs `CONCAT()`, Oracle `SUBSTR` vs the
+ * standard `SUBSTRING`, MSSQL `LEN` vs `LENGTH`/`CHAR_LENGTH`, etc.)
+ *
+ * This module is intentionally self-contained: it does not modify
+ * `src/operators.ts` or `src/query-builders/sql-compiler.ts`. It only reads
+ * the `literal`, `ColExpression`, `FnExpression`, and `LiteralExpression`
+ * primitives from `../../operators` and returns plain `{ $literal: string }`
+ * values (via `literal()`) that can be dropped into `attributes`, `where`,
+ * etc. exactly like any other literal expression.
+ */
+import { type ColExpression, type FnExpression, type LiteralExpression } from '../../operators';
+import type { Dialect } from '../../types/index';
+/**
+ * Column-like argument accepted by the string functions in this module.
+ *
+ * - A plain `string` is treated as a STRING LITERAL VALUE (it will be quoted
+ *   and escaped, e.g. `'hello'`), NOT as a column name. To reference a
+ *   column, wrap it with `col('columnName')`.
+ * - `ColExpression` (from `col()`), `FnExpression` (from `fn()`), and
+ *   `LiteralExpression` (from `literalExpr()`) are rendered as SQL
+ *   expressions/identifiers, not quoted as literal text.
+ */
+export type SqlExpr = string | ColExpression | FnExpression | LiteralExpression;
+/**
+ * String concatenation.
+ *
+ * - MySQL, MariaDB, MSSQL, Snowflake, ClickHouse: use the variadic
+ *   `CONCAT(a, b, c, ...)` function (all support 2+ arguments).
+ * - Postgres, CockroachDB, Redshift, SQLite, Oracle, DB2: use the `||`
+ *   operator. These dialects' `CONCAT()` function (where it exists at all)
+ *   is limited to exactly 2 arguments (Oracle, DB2), so `||` is used
+ *   uniformly for correctness with any number of parts. Postgres/CockroachDB/
+ *   SQLite treat `||` as the idiomatic concatenation operator.
+ *
+ * @param parts - Column-like arguments (columns via `col()`, nested
+ *   expressions via `fn()`, or literal string values as plain strings).
+ */
+export declare function concat(dialect: Dialect, ...parts: SqlExpr[]): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Extract a substring.
+ *
+ * - Oracle, DB2, SQLite: use `SUBSTR(expr, start, length)`. SQLite has no
+ *   built-in `SUBSTRING` function (only `substr`); Oracle/DB2 use `SUBSTR`
+ *   as their canonical name (both also happen to accept the same argument
+ *   order as the standard `SUBSTRING(expr, start, length)` form).
+ * - MSSQL: `SUBSTRING(expr, start, length)`, but MSSQL requires the length
+ *   argument. When `length` is omitted, `LEN(expr)` is used as a safe upper
+ *   bound so the result runs to the end of the string.
+ * - MySQL, MariaDB, Postgres, CockroachDB, Redshift, Snowflake, ClickHouse:
+ *   `SUBSTRING(expr, start, length)` comma-argument form, length optional.
+ *
+ * @param expr - The column/expression to extract from.
+ * @param start - 1-based start position (SQL substring indices are 1-based).
+ * @param length - Optional number of characters to extract.
+ */
+export declare function substring(dialect: Dialect, expr: SqlExpr, start: number, length?: number): LiteralExpression & {
+    $literal: string;
+};
+export interface TrimOptions {
+    /** Which side(s) to trim. Defaults to 'both'. */
+    side?: 'both' | 'leading' | 'trailing';
+    /** Characters to trim. Defaults to whitespace. */
+    chars?: string;
+}
+/**
+ * Trim whitespace (or specific characters) from a string.
+ *
+ * - Postgres, CockroachDB, Redshift, Oracle, DB2, Snowflake, MySQL, MariaDB,
+ *   ClickHouse: support the standard
+ *   `TRIM([BOTH|LEADING|TRAILING] [chars FROM] expr)` syntax.
+ * - SQLite: has no `[BOTH|LEADING|TRAILING] FROM` syntax; instead uses
+ *   `trim(expr[, chars])` / `ltrim(expr[, chars])` / `rtrim(expr[, chars])`.
+ * - MSSQL: `TRIM` (2017+) only trims both sides; for one-sided trimming we
+ *   fall back to `LTRIM`/`RTRIM`. Native `LTRIM`/`RTRIM` in MSSQL only
+ *   support a `chars` argument starting with SQL Server 2022, so when
+ *   `chars` is supplied on an older-compatible codepath it is still passed
+ *   through (SQL Server will error at runtime on versions that don't
+ *   support it — this is a documented MSSQL version limitation, not a
+ *   limitation of this helper).
+ */
+export declare function trim(dialect: Dialect, expr: SqlExpr, options?: TrimOptions): LiteralExpression & {
+    $literal: string;
+};
+/** Trim from the left only. Equivalent to `trim(dialect, expr, { side: 'leading' })`. */
+export declare function ltrim(dialect: Dialect, expr: SqlExpr, chars?: string): LiteralExpression & {
+    $literal: string;
+};
+/** Trim from the right only. Equivalent to `trim(dialect, expr, { side: 'trailing' })`. */
+export declare function rtrim(dialect: Dialect, expr: SqlExpr, chars?: string): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Uppercase a string. Identical (`UPPER(expr)`) across all 11 dialects.
+ */
+export declare function upper(dialect: Dialect, expr: SqlExpr): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Lowercase a string. Identical (`LOWER(expr)`) across all 11 dialects.
+ */
+export declare function lower(dialect: Dialect, expr: SqlExpr): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Get the character length of a string.
+ *
+ * - MySQL, MariaDB, Postgres, CockroachDB, DB2, Snowflake: use
+ *   `CHAR_LENGTH(expr)`. This is deliberately chosen over `LENGTH()` on
+ *   MySQL/MariaDB because `LENGTH()` there counts BYTES, which is wrong for
+ *   multi-byte (e.g. UTF-8) text; `CHAR_LENGTH()` always counts characters.
+ * - MSSQL: has no `CHAR_LENGTH`/`LENGTH` function at all; uses `LEN(expr)`
+ *   (already character-counting).
+ * - Redshift: uses `LEN(expr)`, its documented/idiomatic string-length
+ *   function (Redshift's SQL dialect favors `LEN` even though it is
+ *   Postgres-derived).
+ * - Oracle: uses `LENGTH(expr)` (Oracle has no `CHAR_LENGTH` keyword;
+ *   `LENGTH` already counts characters for CHAR/VARCHAR2 data).
+ * - SQLite: uses `length(expr)`, which for TEXT values already counts
+ *   characters, not bytes (SQLite has no separate `CHAR_LENGTH`).
+ * - ClickHouse: `length()` counts BYTES. For character-correct behavior
+ *   with multi-byte text, `lengthUTF8(expr)` is used instead.
+ */
+export declare function length(dialect: Dialect, expr: SqlExpr): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Replace all occurrences of a substring.
+ * `REPLACE(expr, search, replacement)` is identical across all 11 dialects.
+ */
+export declare function replace(dialect: Dialect, expr: SqlExpr, search: string, replacement: string): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Left-pad a string to a target length.
+ *
+ * - MySQL, MariaDB, Postgres, CockroachDB, Redshift, Oracle, Snowflake:
+ *   native `LPAD(expr, length, pad)`.
+ * - ClickHouse: native `leftPad(expr, length, pad)`.
+ * - MSSQL: has no `LPAD`. Workaround using `RIGHT(REPLICATE(pad, length) +
+ *   expr, length)` — replicate the pad string enough times to guarantee at
+ *   least `length` characters, prepend it to `expr`, then take the
+ *   rightmost `length` characters (matches LPAD's truncate-on-overflow
+ *   semantics).
+ * - DB2: has no `LPAD` in Db2 for LUW. Workaround using a `CASE` expression:
+ *   if the string is already >= target length, return it unchanged;
+ *   otherwise prepend enough of the repeated pad string (via `REPEAT` +
+ *   `SUBSTR`) to reach the target length.
+ * - SQLite: throws. SQLite has neither `LPAD` nor a `REPEAT` function, and
+ *   there is no safe single-expression workaround without a recursive CTE,
+ *   so this is not something a scalar SQL fragment can express correctly.
+ */
+export declare function lpad(dialect: Dialect, expr: SqlExpr, targetLength: number, padString?: string): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Right-pad a string to a target length. See {@link lpad} for per-dialect
+ * notes; the same dialects that lack `LPAD` also lack `RPAD`.
+ */
+export declare function rpad(dialect: Dialect, expr: SqlExpr, targetLength: number, padString?: string): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Split a string on a delimiter, returning an array/collection expression
+ * where the dialect has a real mechanism for it.
+ *
+ * - Postgres, CockroachDB: `STRING_TO_ARRAY(expr, delimiter)` -> `text[]`.
+ * - Redshift: `SPLIT_TO_ARRAY(expr, delimiter)` -> `SUPER` array (Redshift's
+ *   SUPER-type based array support).
+ * - Snowflake: `SPLIT(expr, delimiter)` -> `ARRAY` (variant).
+ * - ClickHouse: `splitByString(delimiter, expr)` -> `Array(String)`. Note
+ *   the argument order is reversed compared to the others (separator comes
+ *   first in ClickHouse).
+ * - MySQL, MariaDB, MSSQL, Oracle, DB2, SQLite: throw. None of these have a
+ *   clean way to produce an array/collection from a scalar expression:
+ *   - MySQL/MariaDB have no array type at all (only `SUBSTRING_INDEX` for
+ *     extracting a single part by position, which is a different contract).
+ *   - MSSQL's `STRING_SPLIT` is a table-valued function usable only in a
+ *     `FROM` clause, not as a scalar expression.
+ *   - Oracle/DB2/SQLite have no built-in split-to-array function; producing
+ *     one requires `CONNECT BY`/recursive CTE tricks that cannot be
+ *     expressed as a single SQL fragment.
+ */
+export declare function split(dialect: Dialect, expr: SqlExpr, delimiter: string): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Repeat a string N times.
+ *
+ * - MySQL, MariaDB, Postgres, CockroachDB, Redshift, DB2, Snowflake,
+ *   ClickHouse: native `REPEAT(expr, n)` (ClickHouse: `repeat(expr, n)`).
+ * - MSSQL: has no `REPEAT`; uses `REPLICATE(expr, n)`, which is exactly
+ *   equivalent.
+ * - Oracle: has no `REPEAT`. Workaround: `RPAD(expr, LENGTH(expr) * n,
+ *   expr)` — `RPAD`'s first argument already contributes one copy of
+ *   `expr`, and padding with `expr` itself out to `length(expr) * n`
+ *   characters fills in the remaining `n - 1` copies, producing `expr`
+ *   repeated exactly `n` times (requires `expr` to be non-empty, since
+ *   Oracle treats `''` as `NULL`).
+ * - SQLite: throws. SQLite has no `REPEAT` function and no safe
+ *   single-expression workaround (the zeroblob/hex tricks that exist are
+ *   fragile and only work for single-character pad values).
+ */
+export declare function repeat(dialect: Dialect, expr: SqlExpr, n: number): LiteralExpression & {
+    $literal: string;
+};
+/**
+ * Reverse a string.
+ *
+ * - MySQL, MariaDB, MSSQL, Postgres (9.1+), CockroachDB, Snowflake: native
+ *   `REVERSE(expr)`.
+ * - ClickHouse: `reverse()` reverses BYTES, not characters, which breaks
+ *   multi-byte text; `reverseUTF8(expr)` is used instead for correctness.
+ * - Oracle: no built-in `REVERSE` function for strings; there is no safe
+ *   single-expression workaround (would require a hierarchical
+ *   `CONNECT BY LEVEL` query), so this throws.
+ * - DB2: no built-in `REVERSE` scalar function in Db2 for LUW; throws for
+ *   the same reason as Oracle.
+ * - Redshift: not present in Redshift's documented string-function list
+ *   (Redshift's SQL dialect is derived from an old Postgres release that
+ *   predates Postgres's `REVERSE`); throws rather than risk incorrect SQL.
+ * - SQLite: no built-in `REVERSE` function; throws.
+ */
+export declare function reverse(dialect: Dialect, expr: SqlExpr): LiteralExpression & {
+    $literal: string;
+};

package/dist/query-builders/functions/window.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Typed window-function builder API.
+ *
+ * Provides a fluent, chainable builder for SQL window functions
+ * (`OVER (PARTITION BY ... ORDER BY ... ROWS/RANGE BETWEEN ...)`) so callers
+ * never need to hand-write raw SQL strings for `ROW_NUMBER()`, `RANK()`,
+ * `LAG()`, `LEAD()`, and friends.
+ *
+ * This module is intentionally self-contained: it does not add any new
+ * dispatch branches to the shared SQL compiler. Every builder resolves
+ * directly to a final SQL fragment string, which is then wrapped with the
+ * existing `literalExpr()`/`literal()` helpers from `src/operators.ts` so it
+ * slots into `attributes: [...]` arrays exactly the way `fn()`/`col()`/
+ * `cast()` do today (see `attributeToSql()` / `processAttribute()` in
+ * `src/query-builders/sql-compiler.ts`, which both already know how to
+ * render `{ __type: 'literal', sql }` and `[expr, alias]` tuples).
+ *
+ * @example
+ * ```typescript
+ * import { rowNumber, rank, lag, sumOver } from './query-builders/functions/window';
+ * import { col } from '../../operators';
+ *
+ * User.findAll({
+ *   attributes: [
+ *     'department',
+ *     'salary',
+ *     rowNumber().partitionBy('department').orderBy('salary', 'DESC').as('rn'),
+ *     rank().partitionBy(col('department')).orderBy(col('salary'), 'DESC').as('rnk'),
+ *     lag(col('salary'), 1).partitionBy('department').orderBy('hireDate').as('prevSalary'),
+ *     sumOver(col('salary'))
+ *       .partitionBy('department')
+ *       .orderBy('hireDate')
+ *       .rows({ start: 'unboundedPreceding', end: 'currentRow' })
+ *       .as('runningTotal'),
+ *   ],
+ * });
+ * ```
+ */
+import { type FnExpression, type ColExpression, type LiteralExpression } from '../../operators';
+import { SortDirection } from '../../types';
+/**
+ * Dialects that support ANSI-standard `OVER (...)` window function syntax.
+ * All of these are ANSI SQL:2003 window-function compatible in their modern
+ * versions:
+ *   - mysql (8.0+), mariadb (10.2+): full support
+ *   - postgres, cockroachdb, redshift: full support (Redshift/CockroachDB are
+ *     Postgres-derived and share the same syntax)
+ *   - mssql: full support since SQL Server 2012 (frame clauses since 2012)
+ *   - oracle: full support (analytic functions), including RESPECT/IGNORE NULLS
+ *   - sqlite: full support since 3.25.0 (2018)
+ *   - db2: full support (OLAP specification)
+ *   - snowflake: full support
+ *   - clickhouse: full support since 21.3+ (contrary to older assumptions,
+ *     ClickHouse does implement standard `OVER (...)` window functions, it's
+ *     just historically been a later addition than in other engines)
+ */
+export type WindowDialect = 'mysql' | 'mariadb' | 'postgres' | 'mssql' | 'oracle' | 'sqlite' | 'cockroachdb' | 'redshift' | 'db2' | 'snowflake' | 'clickhouse';
+/**
+ * Sort direction for ORDER BY within a window definition.
+ *
+ * Accepts the shared {@link SortDirection} enum (re-exported from `../../types`)
+ * in addition to the raw `'ASC'` / `'DESC'` string literals, which remain fully
+ * supported for backward compatibility.
+ *
+ * @example
+ * ```typescript
+ * // Using raw string literals (still supported)
+ * rowNumber().partitionBy('department').orderBy('salary', 'DESC')
+ *
+ * // Using the SortDirection enum
+ * import { SortDirection } from 'prorm';
+ * rowNumber().partitionBy('department').orderBy('salary', SortDirection.DESC)
+ * ```
+ */
+export type WindowOrderDirection = SortDirection | 'ASC' | 'DESC';
+/**
+ * `NULLS FIRST` / `NULLS LAST` modifier, supported by most (not all) dialects.
+ *
+ * Companion enum {@link NullsOrder} is available for the `'FIRST' | 'LAST'`
+ * string-literal union below; raw string literals continue to work unchanged.
+ *
+ * @example
+ * ```typescript
+ * // Using raw string literals (still supported)
+ * rowNumber().orderBy('salary', 'DESC', 'LAST')
+ *
+ * // Using the NullsOrder enum
+ * import { NullsOrder } from './query-builders/functions/window';
+ * rowNumber().orderBy('salary', 'DESC', NullsOrder.LAST)
+ * ```
+ */
+export declare enum NullsOrder {
+    FIRST = "FIRST",
+    LAST = "LAST"
+}
+export type WindowNulls = NullsOrder | 'FIRST' | 'LAST';
+/**
+ * A frame boundary for ROWS/RANGE clauses.
+ *  - 'unboundedPreceding' -> UNBOUNDED PRECEDING
+ *  - 'unboundedFollowing' -> UNBOUNDED FOLLOWING
+ *  - 'currentRow'         -> CURRENT ROW
+ *  - { preceding: n }     -> n PRECEDING
+ *  - { following: n }     -> n FOLLOWING
+ */
+export type WindowFrameBoundary = 'unboundedPreceding' | 'unboundedFollowing' | 'currentRow' | {
+    preceding: number;
+} | {
+    following: number;
+};
+/** A ROWS/RANGE frame clause: `BETWEEN start AND end`. */
+export interface WindowFrame {
+    start: WindowFrameBoundary;
+    end?: WindowFrameBoundary;
+}
+/**
+ * Acceptable argument types for window function calls, PARTITION BY, and
+ * ORDER BY entries: plain column names (strings), other typed expressions
+ * (`col()`, `fn()`, `literal()`), or raw numbers (e.g. offsets/defaults).
+ */
+export type WindowArg = string | number | ColExpression | FnExpression | LiteralExpression | {
+    $literal: string;
+} | null | undefined;
+/**
+ * A chainable builder that accumulates PARTITION BY / ORDER BY / frame
+ * clauses for a single window function call and renders the final
+ * `FN(args) OVER (...)` SQL fragment.
+ */
+export declare class WindowFunctionBuilder {
+    private readonly fnName;
+    private readonly fnArgs;
+    private partitions;
+    private orders;
+    private frameMode?;
+    private frame?;
+    private dialect?;
+    constructor(fnName: string, fnArgs?: WindowArg[]);
+    /**
+     * Set (or narrow) the target dialect. Only matters for the rare cases
+     * where OVER-clause syntax genuinely diverges (all listed dialects use the
+     * same ANSI-standard OVER syntax today, so this is mostly a documented
+     * escape hatch for future dialect-specific tweaks).
+     */
+    forDialect(dialect: WindowDialect): this;
+    /** Add one or more PARTITION BY columns/expressions. Repeatable/additive. */
+    partitionBy(...cols: WindowArg[]): this;
+    /**
+     * Add an ORDER BY entry to the window definition. Call multiple times to
+     * order by multiple columns; each call appends one entry.
+     */
+    orderBy(expr: WindowArg, direction?: WindowOrderDirection, nulls?: WindowNulls): this;
+    /** Set a ROWS frame clause, e.g. `ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`. */
+    rows(frame: WindowFrame): this;
+    /** Set a RANGE frame clause, e.g. `RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`. */
+    range(frame: WindowFrame): this;
+    /** Render the `FN(args) OVER (...)` SQL fragment (no alias). */
+    toSQL(): string;
+    /**
+     * Terminal call: returns an `[expr, alias]` tuple compatible with the
+     * existing `attributes: [...]` pattern (see `attributeToSql()` /
+     * `attributeToSqlWithAlias()` in `sql-compiler.ts`, both of which already
+     * know how to render `[LiteralExpression, alias]` tuples without any core
+     * changes).
+     */
+    as(alias: string): [LiteralExpression, string];
+    /**
+     * Allow the builder to be used directly wherever a raw SQL literal is
+     * expected (e.g. passed straight into `literal()`-consuming positions)
+     * without requiring `.as(...)`.
+     */
+    toLiteral(): LiteralExpression;
+}
+/** `ROW_NUMBER() OVER (...)` */
+export declare function rowNumber(): WindowFunctionBuilder;
+/** `RANK() OVER (...)` */
+export declare function rank(): WindowFunctionBuilder;
+/** `DENSE_RANK() OVER (...)` */
+export declare function denseRank(): WindowFunctionBuilder;
+/** `PERCENT_RANK() OVER (...)` */
+export declare function percentRank(): WindowFunctionBuilder;
+/** `CUME_DIST() OVER (...)` */
+export declare function cumeDist(): WindowFunctionBuilder;
+/** `NTILE(buckets) OVER (...)` */
+export declare function ntile(buckets: number): WindowFunctionBuilder;
+/** `LAG(expr[, offset[, default]]) OVER (...)` */
+export declare function lag(expr: WindowArg, offset?: number, defaultValue?: WindowArg): WindowFunctionBuilder;
+/** `LEAD(expr[, offset[, default]]) OVER (...)` */
+export declare function lead(expr: WindowArg, offset?: number, defaultValue?: WindowArg): WindowFunctionBuilder;
+/** `FIRST_VALUE(expr) OVER (...)` */
+export declare function firstValue(expr: WindowArg): WindowFunctionBuilder;
+/** `LAST_VALUE(expr) OVER (...)` */
+export declare function lastValue(expr: WindowArg): WindowFunctionBuilder;
+/** `NTH_VALUE(expr, n) OVER (...)` */
+export declare function nthValue(expr: WindowArg, n: number): WindowFunctionBuilder;
+/** `SUM(expr) OVER (...)` */
+export declare function sumOver(expr: WindowArg): WindowFunctionBuilder;
+/** `AVG(expr) OVER (...)` */
+export declare function avgOver(expr: WindowArg): WindowFunctionBuilder;
+/** `COUNT(expr | *) OVER (...)` */
+export declare function countOver(expr?: WindowArg): WindowFunctionBuilder;
+/** `MIN(expr) OVER (...)` */
+export declare function minOver(expr: WindowArg): WindowFunctionBuilder;
+/** `MAX(expr) OVER (...)` */
+export declare function maxOver(expr: WindowArg): WindowFunctionBuilder;
+/**
+ * Generic escape hatch: build a window function call for any function name
+ * not covered by the named helpers above (e.g. dialect-specific analytic
+ * functions).
+ */
+export declare function windowFn(fnName: string, ...args: WindowArg[]): WindowFunctionBuilder;