ts-prorm-orm 1.1.0

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

@@ -0,0 +1,695 @@
+"use strict";
+/**
+ * Typed date/time function builder API.
+ *
+ * Date truncation, date arithmetic (add/subtract), date-difference, "current
+ * date/time" helpers, and best-effort date formatting differ WILDLY across
+ * the 11 SQL dialects this ORM supports (Postgres `DATE_TRUNC`, MySQL
+ * `DATE_ADD`/`DATEDIFF`, MSSQL `DATEADD`/`DATEDIFF`, Oracle `TRUNC`/
+ * `ADD_MONTHS`, SQLite `strftime`/`julianday`, etc). This module gives callers
+ * a single typed entry point per capability so they never have to hand-write
+ * dialect-specific SQL strings themselves.
+ *
+ * This module is intentionally self-contained, mirroring the approach taken
+ * in `src/query-builders/functions/window.ts`: it does NOT add any new
+ * dispatch branches to the shared SQL compiler (`src/query-builders/
+ * sql-compiler.ts`) or to `src/operators.ts`. Every function below computes
+ * a final, dialect-correct SQL fragment string directly and wraps it with the
+ * existing `literal()` helper from `src/operators.ts` so it slots into
+ * `attributes: [...]` / `where` clauses exactly the way `fn()`/`col()`/
+ * `cast()`/`extract()` do today.
+ *
+ * @example
+ * ```typescript
+ * import { dateTrunc, dateAdd, dateDiff, now, formatDate } from './query-builders/functions/datetime';
+ * import { col } from '../../operators';
+ *
+ * User.findAll({
+ *   attributes: [
+ *     'id',
+ *     dateTrunc('postgres', 'month', col('createdAt')).as('signupMonth'),
+ *     dateAdd('postgres', col('createdAt'), 30, 'day').as('trialEnds'),
+ *     dateDiff('mysql', 'day', col('startDate'), col('endDate')).as('durationDays'),
+ *     now('sqlite').as('rightNow'),
+ *     formatDate('postgres', col('createdAt'), 'YYYY-MM-DD').as('createdAtStr'),
+ *   ],
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dateTrunc = dateTrunc;
+exports.dateAdd = dateAdd;
+exports.dateSub = dateSub;
+exports.dateDiff = dateDiff;
+exports.now = now;
+exports.currentDate = currentDate;
+exports.currentTimestamp = currentTimestamp;
+exports.formatDate = formatDate;
+const operators_1 = require("../../operators");
+function makeExpression(sql) {
+    const lit = (0, operators_1.literal)(sql);
+    return {
+        __type: 'literal',
+        sql,
+        $literal: lit.$literal,
+        as(alias) {
+            return [this, alias];
+        },
+    };
+}
+function isDateTimeExpression(value) {
+    return value && value.__type === 'literal' && typeof value.sql === 'string' && typeof value.as === 'function';
+}
+/**
+ * Escape a plain identifier (or `table.column` dotted path) using ANSI
+ * double-quote convention. This mirrors `escapeIdentifier()` in
+ * `window.ts` for consistency across the `functions/` family; the shared
+ * compiler normalizes/re-quotes identifiers per dialect downstream the same
+ * way it already does for `col()`/`fn()` output.
+ */
+function escapeIdentifier(name) {
+    if (name.includes('.')) {
+        return name
+            .split('.')
+            .map((part) => `"${part.replace(/"/g, '""')}"`)
+            .join('.');
+    }
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/** Format a JS Date as a portable `'YYYY-MM-DD HH:MM:SS'` SQL string literal. */
+function formatDateLiteral(date) {
+    const iso = date.toISOString(); // e.g. 2024-01-02T03:04:05.000Z
+    const value = iso.replace('T', ' ').replace('Z', '').replace(/\.\d+$/, '');
+    return `'${value}'`;
+}
+/**
+ * Flatten a date/time argument (string column name, ColExpression,
+ * FnExpression, LiteralExpression, DateTimeExpression, Date, number) into a
+ * raw SQL fragment string. Plain strings are treated as column names (same
+ * convention as `extract()`/`fn()`/`col()` in `src/operators.ts`).
+ */
+function toSqlFragment(arg) {
+    if (arg === null || arg === undefined)
+        return 'NULL';
+    if (typeof arg === 'number')
+        return String(arg);
+    if (arg instanceof Date)
+        return formatDateLiteral(arg);
+    if (typeof arg === 'string')
+        return escapeIdentifier(arg);
+    if (isDateTimeExpression(arg))
+        return arg.sql;
+    if ((0, operators_1.isFnExpression)(arg)) {
+        const args = arg.args.map((a) => toSqlFragment(a)).join(', ');
+        return `${arg.fn}(${args})`;
+    }
+    if ((0, operators_1.isColExpression)(arg))
+        return escapeIdentifier(arg.col);
+    if ((0, operators_1.isLiteralExpression)(arg)) {
+        return '$literal' in arg ? arg.$literal : arg.sql;
+    }
+    // Fallback: stringify
+    return String(arg);
+}
+function isPostgresLikeTrunc(dialect) {
+    // Postgres, CockroachDB, and Redshift all support the real DATE_TRUNC('unit', expr)
+    // function with identical syntax/unit-name semantics (Redshift and CockroachDB are
+    // both Postgres-wire/SQL-derived and inherit this function verbatim).
+    return dialect === 'postgres' || dialect === 'cockroachdb' || dialect === 'redshift';
+}
+// ============================================================================
+// dateTrunc
+// ============================================================================
+/**
+ * Truncate a date/timestamp expression down to the start of the given unit
+ * boundary (year/quarter/month/week/day/hour/minute/second).
+ *
+ * Dialect notes:
+ * - postgres / cockroachdb / redshift: native `DATE_TRUNC('unit', expr)`.
+ * - mysql / mariadb: NO native DATE_TRUNC exists (verified) — built via
+ *   `DATE_FORMAT`/string-concat + `STR_TO_DATE` workarounds.
+ * - mssql: uses `DATETRUNC(datepart, expr)`, added in SQL Server 2022. For
+ *   older MSSQL versions there is no native equivalent; this targets modern
+ *   SQL Server.
+ * - oracle: `TRUNC(expr, fmt)`. Oracle's TRUNC only truncates down to
+ *   hour/minute ('HH24'/'MI'); truncating to 'second' is a no-op since DATE
+ *   values already carry second precision, so `expr` is returned unchanged.
+ * - sqlite: no native function — built via `strftime()`/string-concat.
+ * - db2: no native DATE_TRUNC — built via `VARCHAR_FORMAT`/`TIMESTAMP_FORMAT`
+ *   round-tripping (Db2's TO_CHAR/TO_DATE equivalents) plus `DAYOFWEEK()`
+ *   for week truncation.
+ * - snowflake: native `DATE_TRUNC('unit', expr)`.
+ * - clickhouse: dedicated `toStartOfYear`/`toStartOfQuarter`/`toStartOfMonth`/
+ *   `toStartOfWeek`/`toStartOfDay`/`toStartOfHour`/`toStartOfMinute`/
+ *   `toStartOfSecond` functions (genuinely different function-per-unit API,
+ *   not a single parameterized function).
+ */
+function dateTrunc(dialect, unit, expr) {
+    const e = toSqlFragment(expr);
+    if (isPostgresLikeTrunc(dialect) || dialect === 'snowflake') {
+        return makeExpression(`DATE_TRUNC('${unit}', ${e})`);
+    }
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb': {
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`DATE_FORMAT(${e}, '%Y-01-01 00:00:00')`);
+                case 'quarter':
+                    return makeExpression(`STR_TO_DATE(CONCAT(DATE_FORMAT(${e}, '%Y-'), LPAD((QUARTER(${e}) - 1) * 3 + 1, 2, '0'), '-01 00:00:00'), '%Y-%m-%d %H:%i:%s')`);
+                case 'month':
+                    return makeExpression(`DATE_FORMAT(${e}, '%Y-%m-01 00:00:00')`);
+                case 'week':
+                    return makeExpression(`DATE_SUB(DATE(${e}), INTERVAL WEEKDAY(${e}) DAY)`);
+                case 'day':
+                    return makeExpression(`DATE_FORMAT(${e}, '%Y-%m-%d 00:00:00')`);
+                case 'hour':
+                    return makeExpression(`DATE_FORMAT(${e}, '%Y-%m-%d %H:00:00')`);
+                case 'minute':
+                    return makeExpression(`DATE_FORMAT(${e}, '%Y-%m-%d %H:%i:00')`);
+                case 'second':
+                    return makeExpression(`DATE_FORMAT(${e}, '%Y-%m-%d %H:%i:%s')`);
+            }
+            break;
+        }
+        case 'mssql': {
+            // SQL Server 2022+ DATETRUNC(datepart, date) accepts these unit names directly.
+            return makeExpression(`DATETRUNC(${unit}, ${e})`);
+        }
+        case 'oracle': {
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`TRUNC(${e}, 'YYYY')`);
+                case 'quarter':
+                    return makeExpression(`TRUNC(${e}, 'Q')`);
+                case 'month':
+                    return makeExpression(`TRUNC(${e}, 'MM')`);
+                case 'week':
+                    return makeExpression(`TRUNC(${e}, 'IW')`);
+                case 'day':
+                    return makeExpression(`TRUNC(${e}, 'DD')`);
+                case 'hour':
+                    return makeExpression(`TRUNC(${e}, 'HH24')`);
+                case 'minute':
+                    return makeExpression(`TRUNC(${e}, 'MI')`);
+                case 'second':
+                    // Oracle DATE has only second precision already; no smaller truncation exists.
+                    return makeExpression(`${e}`);
+            }
+            break;
+        }
+        case 'sqlite': {
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`strftime('%Y-01-01 00:00:00', ${e})`);
+                case 'quarter':
+                    return makeExpression(`(strftime('%Y-', ${e}) || printf('%02d', ((CAST(strftime('%m', ${e}) AS INTEGER) - 1) / 3) * 3 + 1) || '-01 00:00:00')`);
+                case 'month':
+                    return makeExpression(`strftime('%Y-%m-01 00:00:00', ${e})`);
+                case 'week':
+                    return makeExpression(`date(${e}, '-' || strftime('%w', ${e}) || ' days')`);
+                case 'day':
+                    return makeExpression(`strftime('%Y-%m-%d 00:00:00', ${e})`);
+                case 'hour':
+                    return makeExpression(`strftime('%Y-%m-%d %H:00:00', ${e})`);
+                case 'minute':
+                    return makeExpression(`strftime('%Y-%m-%d %H:%M:00', ${e})`);
+                case 'second':
+                    return makeExpression(`strftime('%Y-%m-%d %H:%M:%S', ${e})`);
+            }
+            break;
+        }
+        case 'db2': {
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`TIMESTAMP_FORMAT(VARCHAR_FORMAT(${e}, 'YYYY') || '-01-01 00:00:00', 'YYYY-MM-DD HH24:MI:SS')`);
+                case 'quarter':
+                    return makeExpression(`TIMESTAMP_FORMAT(VARCHAR_FORMAT(${e}, 'YYYY') || '-' || LPAD((QUARTER(${e}) - 1) * 3 + 1, 2, '0') || '-01 00:00:00', 'YYYY-MM-DD HH24:MI:SS')`);
+                case 'month':
+                    return makeExpression(`TIMESTAMP_FORMAT(VARCHAR_FORMAT(${e}, 'YYYY-MM') || '-01 00:00:00', 'YYYY-MM-DD HH24:MI:SS')`);
+                case 'week':
+                    return makeExpression(`(CAST(${e} AS DATE) - (DAYOFWEEK(${e}) - 1) DAYS)`);
+                case 'day':
+                    return makeExpression(`TIMESTAMP_FORMAT(VARCHAR_FORMAT(${e}, 'YYYY-MM-DD') || ' 00:00:00', 'YYYY-MM-DD HH24:MI:SS')`);
+                case 'hour':
+                    return makeExpression(`TIMESTAMP_FORMAT(VARCHAR_FORMAT(${e}, 'YYYY-MM-DD HH24') || ':00:00', 'YYYY-MM-DD HH24:MI:SS')`);
+                case 'minute':
+                    return makeExpression(`TIMESTAMP_FORMAT(VARCHAR_FORMAT(${e}, 'YYYY-MM-DD HH24:MI') || ':00', 'YYYY-MM-DD HH24:MI:SS')`);
+                case 'second':
+                    return makeExpression(`TIMESTAMP_FORMAT(VARCHAR_FORMAT(${e}, 'YYYY-MM-DD HH24:MI:SS'), 'YYYY-MM-DD HH24:MI:SS')`);
+            }
+            break;
+        }
+        case 'clickhouse': {
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`toStartOfYear(${e})`);
+                case 'quarter':
+                    return makeExpression(`toStartOfQuarter(${e})`);
+                case 'month':
+                    return makeExpression(`toStartOfMonth(${e})`);
+                case 'week':
+                    return makeExpression(`toStartOfWeek(${e})`);
+                case 'day':
+                    return makeExpression(`toStartOfDay(${e})`);
+                case 'hour':
+                    return makeExpression(`toStartOfHour(${e})`);
+                case 'minute':
+                    return makeExpression(`toStartOfMinute(${e})`);
+                case 'second':
+                    return makeExpression(`toStartOfSecond(${e})`);
+            }
+            break;
+        }
+    }
+    // Should be unreachable for supported dialects, but keep a safe fallback.
+    return makeExpression(`DATE_TRUNC('${unit}', ${e})`);
+}
+// ============================================================================
+// dateAdd / dateSub
+// ============================================================================
+function dateAddInternal(dialect, expr, signedAmount, unit) {
+    const e = toSqlFragment(expr);
+    const amount = signedAmount;
+    switch (dialect) {
+        case 'postgres':
+        case 'cockroachdb': {
+            // Native interval arithmetic.
+            const sign = amount < 0 ? '-' : '+';
+            return makeExpression(`${e} ${sign} INTERVAL '${Math.abs(amount)} ${unit}'`);
+        }
+        case 'redshift': {
+            // Redshift has a genuine DATEADD(datepart, number, date) function (SQL-Server-like),
+            // distinct from Postgres's interval-literal arithmetic even though Redshift is
+            // otherwise Postgres-derived.
+            return makeExpression(`DATEADD(${unit}, ${amount}, ${e})`);
+        }
+        case 'mysql':
+        case 'mariadb': {
+            const fn = amount < 0 ? 'DATE_SUB' : 'DATE_ADD';
+            return makeExpression(`${fn}(${e}, INTERVAL ${Math.abs(amount)} ${unit.toUpperCase()})`);
+        }
+        case 'mssql': {
+            return makeExpression(`DATEADD(${unit}, ${amount}, ${e})`);
+        }
+        case 'oracle': {
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`ADD_MONTHS(${e}, ${amount * 12})`);
+                case 'month':
+                    return makeExpression(`ADD_MONTHS(${e}, ${amount})`);
+                case 'day':
+                    return makeExpression(`(${e} + ${amount})`);
+                case 'hour':
+                    return makeExpression(`(${e} + ${amount} / 24)`);
+                case 'minute':
+                    return makeExpression(`(${e} + ${amount} / 1440)`);
+                case 'second':
+                    return makeExpression(`(${e} + ${amount} / 86400)`);
+            }
+            break;
+        }
+        case 'sqlite': {
+            const plural = `${unit}${Math.abs(amount) === 1 ? '' : 's'}`;
+            const sign = amount < 0 ? '-' : '+';
+            return makeExpression(`datetime(${e}, '${sign}${Math.abs(amount)} ${plural}')`);
+        }
+        case 'db2': {
+            const sign = amount < 0 ? '-' : '+';
+            const unitWord = `${unit.toUpperCase()}${Math.abs(amount) === 1 ? '' : 'S'}`;
+            return makeExpression(`(${e} ${sign} ${Math.abs(amount)} ${unitWord})`);
+        }
+        case 'snowflake': {
+            return makeExpression(`DATEADD(${unit}, ${amount}, ${e})`);
+        }
+        case 'clickhouse': {
+            // ClickHouse supports ANSI-style INTERVAL arithmetic directly.
+            const sign = amount < 0 ? '-' : '+';
+            return makeExpression(`${e} ${sign} INTERVAL ${Math.abs(amount)} ${unit.toUpperCase()}`);
+        }
+    }
+    // Fallback (unreachable for supported dialects).
+    return makeExpression(`${e} + INTERVAL '${amount} ${unit}'`);
+}
+/**
+ * Add `amount` units of time to a date/timestamp expression.
+ * See dialect notes on {@link dateTrunc} / module doc for the general
+ * per-dialect divergence rationale; per-function notes:
+ * - postgres/cockroachdb: `expr + INTERVAL 'n unit'`.
+ * - redshift: `DATEADD(unit, n, expr)` (SQL-Server-style function, NOT interval
+ *   arithmetic, despite being Postgres-derived).
+ * - mysql/mariadb: `DATE_ADD(expr, INTERVAL n UNIT)`.
+ * - mssql/snowflake: `DATEADD(unit, n, expr)`.
+ * - oracle: day-level uses plain `+`/`-` arithmetic (Oracle DATE math is in
+ *   days); month/year use `ADD_MONTHS`; hour/minute/second are expressed as
+ *   fractional-day arithmetic.
+ * - sqlite: `datetime(expr, '+n units')`.
+ * - db2: labeled-duration arithmetic, e.g. `expr + n DAYS`.
+ * - clickhouse: ANSI `expr + INTERVAL n UNIT`.
+ */
+function dateAdd(dialect, expr, amount, unit) {
+    return dateAddInternal(dialect, expr, amount, unit);
+}
+/**
+ * Subtract `amount` units of time from a date/timestamp expression.
+ * Equivalent to `dateAdd(dialect, expr, -amount, unit)` — see {@link dateAdd}
+ * for per-dialect SQL notes.
+ */
+function dateSub(dialect, expr, amount, unit) {
+    return dateAddInternal(dialect, expr, -amount, unit);
+}
+// ============================================================================
+// dateDiff
+// ============================================================================
+/**
+ * Compute the difference between two date/timestamp expressions
+ * (`end - start`) expressed in the given unit.
+ *
+ * Dialect notes (this is the function with the widest genuine divergence):
+ * - mysql/mariadb: `TIMESTAMPDIFF(UNIT, start, end)` (native, all units).
+ * - mssql/snowflake: `DATEDIFF(unit, start, end)` (native, all units).
+ * - redshift: also has a genuine native `DATEDIFF(datepart, start, end)`
+ *   function (SQL-Server-style), unlike Postgres which has no such function.
+ * - clickhouse: native `dateDiff('unit', start, end)`.
+ * - postgres/cockroachdb: NO native DATEDIFF — day uses date subtraction
+ *   (`end::date - start::date`), sub-day units use
+ *   `EXTRACT(EPOCH FROM (end - start))` scaled, and year/month are computed
+ *   from `EXTRACT(YEAR/MONTH FROM ...)` components.
+ * - oracle: NO native DATEDIFF — DATE subtraction yields a day count
+ *   (`TRUNC(end) - TRUNC(start)` for whole days, scaled for other sub-day
+ *   units); month/year use `MONTHS_BETWEEN`.
+ * - sqlite: NO native DATEDIFF — built on `julianday()` differences (day and
+ *   sub-day units) and `strftime('%Y'/'%m', ...)` component differences
+ *   (month/year, since julianday-based month math is not calendar-exact).
+ * - db2: NO native DATEDIFF — built from `DAYS()` (whole-day difference) and
+ *   `MIDNIGHT_SECONDS()` (intra-day seconds) for day/sub-day units, and
+ *   `YEAR()`/`MONTH()` component differences for month/year.
+ */
+function dateDiff(dialect, unit, start, end) {
+    const s = toSqlFragment(start);
+    const e = toSqlFragment(end);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb': {
+            return makeExpression(`TIMESTAMPDIFF(${unit.toUpperCase()}, ${s}, ${e})`);
+        }
+        case 'mssql':
+        case 'snowflake':
+        case 'redshift': {
+            return makeExpression(`DATEDIFF(${unit}, ${s}, ${e})`);
+        }
+        case 'clickhouse': {
+            return makeExpression(`dateDiff('${unit}', ${s}, ${e})`);
+        }
+        case 'postgres':
+        case 'cockroachdb': {
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`(EXTRACT(YEAR FROM ${e}) - EXTRACT(YEAR FROM ${s}))`);
+                case 'quarter':
+                    return makeExpression(`(((EXTRACT(YEAR FROM ${e}) - EXTRACT(YEAR FROM ${s})) * 4) + (EXTRACT(QUARTER FROM ${e}) - EXTRACT(QUARTER FROM ${s})))`);
+                case 'month':
+                    return makeExpression(`(((EXTRACT(YEAR FROM ${e}) - EXTRACT(YEAR FROM ${s})) * 12) + (EXTRACT(MONTH FROM ${e}) - EXTRACT(MONTH FROM ${s})))`);
+                case 'week':
+                    return makeExpression(`FLOOR((CAST(${e} AS DATE) - CAST(${s} AS DATE)) / 7)`);
+                case 'day':
+                    return makeExpression(`(CAST(${e} AS DATE) - CAST(${s} AS DATE))`);
+                case 'hour':
+                    return makeExpression(`(EXTRACT(EPOCH FROM (${e} - ${s})) / 3600)`);
+                case 'minute':
+                    return makeExpression(`(EXTRACT(EPOCH FROM (${e} - ${s})) / 60)`);
+                case 'second':
+                    return makeExpression(`EXTRACT(EPOCH FROM (${e} - ${s}))`);
+            }
+            break;
+        }
+        case 'oracle': {
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`(MONTHS_BETWEEN(${e}, ${s}) / 12)`);
+                case 'quarter':
+                    return makeExpression(`(MONTHS_BETWEEN(${e}, ${s}) / 3)`);
+                case 'month':
+                    return makeExpression(`MONTHS_BETWEEN(${e}, ${s})`);
+                case 'week':
+                    return makeExpression(`((${e} - ${s}) / 7)`);
+                case 'day':
+                    return makeExpression(`(TRUNC(${e}) - TRUNC(${s}))`);
+                case 'hour':
+                    return makeExpression(`((${e} - ${s}) * 24)`);
+                case 'minute':
+                    return makeExpression(`((${e} - ${s}) * 1440)`);
+                case 'second':
+                    return makeExpression(`((${e} - ${s}) * 86400)`);
+            }
+            break;
+        }
+        case 'sqlite': {
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`(CAST(strftime('%Y', ${e}) AS INTEGER) - CAST(strftime('%Y', ${s}) AS INTEGER))`);
+                case 'quarter':
+                    return makeExpression(`(((CAST(strftime('%Y', ${e}) AS INTEGER) - CAST(strftime('%Y', ${s}) AS INTEGER)) * 4) + ((CAST(strftime('%m', ${e}) AS INTEGER) - 1) / 3 - (CAST(strftime('%m', ${s}) AS INTEGER) - 1) / 3))`);
+                case 'month':
+                    return makeExpression(`(((CAST(strftime('%Y', ${e}) AS INTEGER) - CAST(strftime('%Y', ${s}) AS INTEGER)) * 12) + (CAST(strftime('%m', ${e}) AS INTEGER) - CAST(strftime('%m', ${s}) AS INTEGER)))`);
+                case 'week':
+                    return makeExpression(`CAST((julianday(${e}) - julianday(${s})) / 7 AS INTEGER)`);
+                case 'day':
+                    return makeExpression(`CAST(julianday(${e}) - julianday(${s}) AS INTEGER)`);
+                case 'hour':
+                    return makeExpression(`((julianday(${e}) - julianday(${s})) * 24)`);
+                case 'minute':
+                    return makeExpression(`((julianday(${e}) - julianday(${s})) * 1440)`);
+                case 'second':
+                    return makeExpression(`((julianday(${e}) - julianday(${s})) * 86400)`);
+            }
+            break;
+        }
+        case 'db2': {
+            const totalSeconds = `((DAYS(${e}) - DAYS(${s})) * 86400 + (MIDNIGHT_SECONDS(${e}) - MIDNIGHT_SECONDS(${s})))`;
+            switch (unit) {
+                case 'year':
+                    return makeExpression(`(YEAR(${e}) - YEAR(${s}))`);
+                case 'quarter':
+                    return makeExpression(`(((YEAR(${e}) - YEAR(${s})) * 4) + (QUARTER(${e}) - QUARTER(${s})))`);
+                case 'month':
+                    return makeExpression(`(((YEAR(${e}) - YEAR(${s})) * 12) + (MONTH(${e}) - MONTH(${s})))`);
+                case 'week':
+                    return makeExpression(`((DAYS(${e}) - DAYS(${s})) / 7)`);
+                case 'day':
+                    return makeExpression(`(DAYS(${e}) - DAYS(${s}))`);
+                case 'hour':
+                    return makeExpression(`(${totalSeconds} / 3600)`);
+                case 'minute':
+                    return makeExpression(`(${totalSeconds} / 60)`);
+                case 'second':
+                    return makeExpression(totalSeconds);
+            }
+            break;
+        }
+    }
+    // Fallback (unreachable for supported dialects).
+    return makeExpression(`DATEDIFF(${unit}, ${s}, ${e})`);
+}
+// ============================================================================
+// now / currentDate / currentTimestamp
+// ============================================================================
+/**
+ * Current date-and-time (instant), dialect-appropriate.
+ * - mysql/mariadb: `NOW()`
+ * - postgres/cockroachdb/redshift: `NOW()`
+ * - mssql: `GETDATE()`
+ * - oracle: `SYSTIMESTAMP`
+ * - sqlite: `datetime('now')`
+ * - db2: `CURRENT TIMESTAMP` (special register, no parentheses)
+ * - snowflake: `CURRENT_TIMESTAMP()`
+ * - clickhouse: `now()`
+ */
+function now(dialect) {
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+            return makeExpression('NOW()');
+        case 'mssql':
+            return makeExpression('GETDATE()');
+        case 'oracle':
+            return makeExpression('SYSTIMESTAMP');
+        case 'sqlite':
+            return makeExpression(`datetime('now')`);
+        case 'db2':
+            return makeExpression('CURRENT TIMESTAMP');
+        case 'snowflake':
+            return makeExpression('CURRENT_TIMESTAMP()');
+        case 'clickhouse':
+            return makeExpression('now()');
+    }
+    return makeExpression('NOW()');
+}
+/**
+ * Current date (no time component), dialect-appropriate.
+ * - mysql/mariadb: `CURDATE()`
+ * - postgres/cockroachdb/redshift: `CURRENT_DATE`
+ * - mssql: `CAST(GETDATE() AS DATE)`
+ * - oracle: `TRUNC(SYSDATE)`
+ * - sqlite: `date('now')`
+ * - db2: `CURRENT DATE` (special register)
+ * - snowflake: `CURRENT_DATE()`
+ * - clickhouse: `today()`
+ */
+function currentDate(dialect) {
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+            return makeExpression('CURDATE()');
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+            return makeExpression('CURRENT_DATE');
+        case 'mssql':
+            return makeExpression('CAST(GETDATE() AS DATE)');
+        case 'oracle':
+            return makeExpression('TRUNC(SYSDATE)');
+        case 'sqlite':
+            return makeExpression(`date('now')`);
+        case 'db2':
+            return makeExpression('CURRENT DATE');
+        case 'snowflake':
+            return makeExpression('CURRENT_DATE()');
+        case 'clickhouse':
+            return makeExpression('today()');
+    }
+    return makeExpression('CURRENT_DATE');
+}
+/**
+ * Current timestamp (ANSI-standard spelling where available), dialect-appropriate.
+ * - mysql/mariadb/postgres/cockroachdb/redshift/db2: `CURRENT_TIMESTAMP`
+ * - mssql: `CURRENT_TIMESTAMP` (ANSI synonym for `GETDATE()`)
+ * - oracle: `CURRENT_TIMESTAMP` (session-timezone-aware; distinct from `SYSTIMESTAMP`)
+ * - sqlite: `CURRENT_TIMESTAMP` (SQLite keyword, UTC)
+ * - snowflake: `CURRENT_TIMESTAMP()`
+ * - clickhouse: `now()` (no distinct `CURRENT_TIMESTAMP`; `now()` is the canonical form)
+ */
+function currentTimestamp(dialect) {
+    switch (dialect) {
+        case 'snowflake':
+            return makeExpression('CURRENT_TIMESTAMP()');
+        case 'clickhouse':
+            return makeExpression('now()');
+        default:
+            return makeExpression('CURRENT_TIMESTAMP');
+    }
+}
+// ============================================================================
+// formatDate
+// ============================================================================
+/**
+ * Format a date/timestamp expression as a string.
+ *
+ * IMPORTANT: format-token translation here is BEST-EFFORT for a common
+ * subset of tokens, NOT a full strftime-compatible formatting engine. Only
+ * the following tokens are recognized in the input `format` string (case
+ * sensitive, matched longest-first so e.g. `HH24` is not partially consumed
+ * by `HH`):
+ *   - `YYYY` - 4-digit year
+ *   - `MM`   - 2-digit month (01-12)
+ *   - `DD`   - 2-digit day of month (01-31)
+ *   - `HH24` - 2-digit hour, 24-hour clock (00-23)
+ *   - `HH`   - 2-digit hour, 12-hour clock (01-12)
+ *   - `MI`   - 2-digit minute (00-59)
+ *   - `SS`   - 2-digit second (00-59)
+ * Any other characters in `format` (literal separators like `-`, `/`, `:`,
+ * spaces, etc) are passed through unchanged, best-effort, per dialect.
+ *
+ * Dialect notes:
+ * - postgres/cockroachdb/redshift/oracle: `TO_CHAR(expr, format)` — these
+ *   tokens map onto TO_CHAR's native template natively, so the format string
+ *   passes through unchanged.
+ * - mysql/mariadb: `DATE_FORMAT(expr, format)`, tokens translated to `%Y`,
+ *   `%m`, `%d`, `%H`, `%h`, `%i`, `%s`.
+ * - mssql: `FORMAT(expr, format)`, tokens translated to .NET-style `yyyy`,
+ *   `MM`, `dd`, `HH`, `hh`, `mm`, `ss`.
+ * - sqlite: `strftime(format, expr)`, tokens translated to `%Y`, `%m`, `%d`,
+ *   `%H`, `%I`, `%M`, `%S`.
+ * - db2: `VARCHAR_FORMAT(expr, format)` (Db2's TO_CHAR-equivalent); tokens
+ *   pass through unchanged like Oracle/Postgres.
+ * - snowflake: `TO_VARCHAR(expr, format)`; tokens pass through unchanged.
+ * - clickhouse: `formatDateTime(expr, format)`, tokens translated to `%Y`,
+ *   `%m`, `%d`, `%H`, `%I`, `%i`, `%S` (ClickHouse's directives are
+ *   MySQL-`strftime`-like, notably using `%i` for minutes like MySQL).
+ */
+function formatDate(dialect, expr, format) {
+    const e = toSqlFragment(expr);
+    const translate = (tokenMap) => {
+        // Replace longest tokens first (HH24 before HH) to avoid partial matches.
+        const tokens = Object.keys(tokenMap).sort((a, b) => b.length - a.length);
+        const pattern = new RegExp(tokens.join('|'), 'g');
+        return format.replace(pattern, (match) => tokenMap[match]);
+    };
+    switch (dialect) {
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+        case 'oracle': {
+            return makeExpression(`TO_CHAR(${e}, '${format}')`);
+        }
+        case 'mysql':
+        case 'mariadb': {
+            const translated = translate({
+                YYYY: '%Y',
+                MM: '%m',
+                DD: '%d',
+                HH24: '%H',
+                HH: '%h',
+                MI: '%i',
+                SS: '%s',
+            });
+            return makeExpression(`DATE_FORMAT(${e}, '${translated}')`);
+        }
+        case 'mssql': {
+            const translated = translate({
+                YYYY: 'yyyy',
+                MM: 'MM',
+                DD: 'dd',
+                HH24: 'HH',
+                HH: 'hh',
+                MI: 'mm',
+                SS: 'ss',
+            });
+            return makeExpression(`FORMAT(${e}, '${translated}')`);
+        }
+        case 'sqlite': {
+            const translated = translate({
+                YYYY: '%Y',
+                MM: '%m',
+                DD: '%d',
+                HH24: '%H',
+                HH: '%I',
+                MI: '%M',
+                SS: '%S',
+            });
+            return makeExpression(`strftime('${translated}', ${e})`);
+        }
+        case 'db2': {
+            return makeExpression(`VARCHAR_FORMAT(${e}, '${format}')`);
+        }
+        case 'snowflake': {
+            return makeExpression(`TO_VARCHAR(${e}, '${format}')`);
+        }
+        case 'clickhouse': {
+            const translated = translate({
+                YYYY: '%Y',
+                MM: '%m',
+                DD: '%d',
+                HH24: '%H',
+                HH: '%I',
+                MI: '%i',
+                SS: '%S',
+            });
+            return makeExpression(`formatDateTime(${e}, '${translated}')`);
+        }
+    }
+    return makeExpression(`TO_CHAR(${e}, '${format}')`);
+}