ts-prorm-orm 1.1.0

package/dist/query-builders/functions/math.js

@@ -0,0 +1,399 @@
+"use strict";
+/**
+ * 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'],
+ *   ],
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.round = round;
+exports.ceil = ceil;
+exports.floor = floor;
+exports.power = power;
+exports.sqrt = sqrt;
+exports.abs = abs;
+exports.sign = sign;
+exports.mod = mod;
+exports.random = random;
+exports.greatest = greatest;
+exports.least = least;
+exports.truncate = truncate;
+const operators_1 = require("../../operators");
+/** Identifier quote style used per dialect when rendering `col()` refs. */
+function quoteIdentifier(dialect, name) {
+    const parts = name.split('.');
+    const quoteOne = (part) => {
+        if (dialect === 'mysql' || dialect === 'mariadb') {
+            return `\`${part.replace(/`/g, '``')}\``;
+        }
+        if (dialect === 'mssql') {
+            return `[${part.replace(/]/g, ']]')}]`;
+        }
+        // postgres, sqlite, cockroachdb, redshift, db2, oracle, snowflake, clickhouse
+        return `"${part.replace(/"/g, '""')}"`;
+    };
+    return parts.map(quoteOne).join('.');
+}
+/** Escape a plain string as a single-quoted SQL string literal. */
+function quoteStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * Flatten a math-function argument (string, number, ColExpression,
+ * FnExpression, LiteralExpression) into a raw SQL fragment string.
+ *
+ * Per this module's contract: plain strings/numbers are rendered as literal
+ * SQL *values* (not identifiers) -- use `col()` to reference a column.
+ */
+function toSqlFragment(dialect, arg) {
+    if (typeof arg === 'number') {
+        return String(arg);
+    }
+    if (typeof arg === 'string') {
+        return quoteStringLiteral(arg);
+    }
+    if ((0, operators_1.isFnExpression)(arg)) {
+        const args = arg.args.map((a) => toSqlFragment(dialect, a)).join(', ');
+        return `${arg.fn}(${args})`;
+    }
+    if ((0, operators_1.isColExpression)(arg)) {
+        return quoteIdentifier(dialect, arg.col);
+    }
+    if ((0, operators_1.isLiteralExpression)(arg)) {
+        // Handles both { __type: 'literal', sql } and { $literal: sql } shapes.
+        return arg.sql ?? arg.$literal;
+    }
+    // Fallback: stringify.
+    return String(arg);
+}
+function isClickhouse(dialect) {
+    return dialect === 'clickhouse';
+}
+function isMssql(dialect) {
+    return dialect === 'mssql';
+}
+function isSqlite(dialect) {
+    return dialect === 'sqlite';
+}
+/**
+ * Build a nested CASE expression that computes GREATEST/LEAST-equivalent
+ * semantics for dialects lacking a native function (used for mssql, which
+ * has no GREATEST/LEAST before SQL Server 2022).
+ *
+ * @param comparator '>=' for GREATEST, '<=' for LEAST
+ */
+function caseBasedExtreme(dialect, values, comparator) {
+    // Build, for each candidate index i, the condition that value[i] is the
+    // extreme among all values (i.e. value[i] <comparator> value[j] for all j).
+    function build(remaining) {
+        if (remaining.length === 1) {
+            return remaining[0];
+        }
+        const [first, ...rest] = remaining;
+        const conditions = values.map((v) => `${first} ${comparator} ${v}`).join(' AND ');
+        return `CASE WHEN ${conditions} THEN ${first} ELSE ${build(rest)} END`;
+    }
+    return build(values);
+}
+/**
+ * `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.
+ */
+function round(dialect, expr, decimals) {
+    const value = toSqlFragment(dialect, expr);
+    const fnName = isClickhouse(dialect) ? 'round' : 'ROUND';
+    const args = decimals !== undefined ? `${value}, ${decimals}` : value;
+    return (0, operators_1.literal)(`${fnName}(${args})`);
+}
+/**
+ * `CEIL(value)` / `CEILING(value)`.
+ *
+ * mssql has no `CEIL` -- only `CEILING`. Every other dialect here accepts
+ * `CEIL` (ClickHouse spells it lower-case).
+ */
+function ceil(dialect, expr) {
+    const value = toSqlFragment(dialect, expr);
+    let fnName;
+    if (isMssql(dialect)) {
+        fnName = 'CEILING';
+    }
+    else if (isClickhouse(dialect)) {
+        fnName = 'ceil';
+    }
+    else {
+        fnName = 'CEIL';
+    }
+    return (0, operators_1.literal)(`${fnName}(${value})`);
+}
+/**
+ * `FLOOR(value)`. Consistent naming across all 11 dialects.
+ */
+function floor(dialect, expr) {
+    const value = toSqlFragment(dialect, expr);
+    const fnName = isClickhouse(dialect) ? 'floor' : 'FLOOR';
+    return (0, operators_1.literal)(`${fnName}(${value})`);
+}
+/**
+ * `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).
+ */
+function power(dialect, base, exponent) {
+    const b = toSqlFragment(dialect, base);
+    const e = toSqlFragment(dialect, exponent);
+    const fnName = isClickhouse(dialect) ? 'pow' : 'POWER';
+    return (0, operators_1.literal)(`${fnName}(${b}, ${e})`);
+}
+/**
+ * `SQRT(value)`. Consistent naming across all 11 dialects.
+ */
+function sqrt(dialect, expr) {
+    const value = toSqlFragment(dialect, expr);
+    const fnName = isClickhouse(dialect) ? 'sqrt' : 'SQRT';
+    return (0, operators_1.literal)(`${fnName}(${value})`);
+}
+/**
+ * `ABS(value)`. Consistent naming across all 11 dialects.
+ */
+function abs(dialect, expr) {
+    const value = toSqlFragment(dialect, expr);
+    const fnName = isClickhouse(dialect) ? 'abs' : 'ABS';
+    return (0, operators_1.literal)(`${fnName}(${value})`);
+}
+/**
+ * `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.
+ */
+function sign(dialect, expr) {
+    const value = toSqlFragment(dialect, expr);
+    if (isSqlite(dialect)) {
+        return (0, operators_1.literal)(`(CASE WHEN ${value} > 0 THEN 1 WHEN ${value} < 0 THEN -1 ELSE 0 END)`);
+    }
+    const fnName = isClickhouse(dialect) ? 'sign' : 'SIGN';
+    return (0, operators_1.literal)(`${fnName}(${value})`);
+}
+/**
+ * `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.
+ */
+function mod(dialect, dividend, divisor) {
+    const a = toSqlFragment(dialect, dividend);
+    const b = toSqlFragment(dialect, divisor);
+    if (isMssql(dialect)) {
+        return (0, operators_1.literal)(`(${a} % ${b})`);
+    }
+    if (isClickhouse(dialect)) {
+        return (0, operators_1.literal)(`modulo(${a}, ${b})`);
+    }
+    return (0, operators_1.literal)(`MOD(${a}, ${b})`);
+}
+/**
+ * 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.
+ */
+function random(dialect) {
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+        case 'mssql':
+        case 'db2':
+            return (0, operators_1.literal)('RAND()');
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+            return (0, operators_1.literal)('RANDOM()');
+        case 'oracle':
+            return (0, operators_1.literal)('DBMS_RANDOM.VALUE');
+        case 'sqlite':
+            return (0, operators_1.literal)('(0.5 + CAST(RANDOM() AS REAL) / 18446744073709551616.0)');
+        case 'snowflake':
+            return (0, operators_1.literal)('UNIFORM(0::FLOAT, 1::FLOAT, RANDOM())');
+        case 'clickhouse':
+            return (0, operators_1.literal)('randCanonical()');
+        default:
+            return (0, operators_1.literal)('RANDOM()');
+    }
+}
+/**
+ * `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(...)`.
+ */
+function greatest(dialect, ...values) {
+    if (values.length === 0) {
+        throw new Error('greatest() requires at least one value');
+    }
+    const rendered = values.map((v) => toSqlFragment(dialect, v));
+    if (rendered.length === 1) {
+        return (0, operators_1.literal)(rendered[0]);
+    }
+    if (isMssql(dialect)) {
+        return (0, operators_1.literal)(caseBasedExtreme(dialect, rendered, '>='));
+    }
+    if (isSqlite(dialect)) {
+        return (0, operators_1.literal)(`MAX(${rendered.join(', ')})`);
+    }
+    const fnName = isClickhouse(dialect) ? 'greatest' : 'GREATEST';
+    return (0, operators_1.literal)(`${fnName}(${rendered.join(', ')})`);
+}
+/**
+ * `LEAST(v1, v2, ...)`.
+ *
+ * Same quirks as {@link greatest}: mssql falls back to a nested `CASE`
+ * expression, sqlite uses scalar `MIN(v1, v2, ...)`.
+ */
+function least(dialect, ...values) {
+    if (values.length === 0) {
+        throw new Error('least() requires at least one value');
+    }
+    const rendered = values.map((v) => toSqlFragment(dialect, v));
+    if (rendered.length === 1) {
+        return (0, operators_1.literal)(rendered[0]);
+    }
+    if (isMssql(dialect)) {
+        return (0, operators_1.literal)(caseBasedExtreme(dialect, rendered, '<='));
+    }
+    if (isSqlite(dialect)) {
+        return (0, operators_1.literal)(`MIN(${rendered.join(', ')})`);
+    }
+    const fnName = isClickhouse(dialect) ? 'least' : 'LEAST';
+    return (0, operators_1.literal)(`${fnName}(${rendered.join(', ')})`);
+}
+/**
+ * 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).
+ */
+function truncate(dialect, expr, decimals) {
+    const value = toSqlFragment(dialect, expr);
+    const d = decimals ?? 0;
+    if (dialect === 'mysql' || dialect === 'mariadb') {
+        return (0, operators_1.literal)(`TRUNCATE(${value}, ${d})`);
+    }
+    if (isMssql(dialect)) {
+        return (0, operators_1.literal)(`ROUND(${value}, ${d}, 1)`);
+    }
+    if (isSqlite(dialect)) {
+        if (decimals === undefined || decimals === 0) {
+            return (0, operators_1.literal)(`trunc(${value})`);
+        }
+        const factor = Math.pow(10, decimals);
+        return (0, operators_1.literal)(`(trunc((${value}) * ${factor}) / ${factor}.0)`);
+    }
+    if (isClickhouse(dialect)) {
+        return (0, operators_1.literal)(decimals !== undefined ? `trunc(${value}, ${decimals})` : `trunc(${value})`);
+    }
+    // oracle, postgres, cockroachdb, redshift, db2, snowflake
+    return (0, operators_1.literal)(`TRUNC(${value}, ${d})`);
+}