ts-prorm-orm 1.1.0

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

@@ -0,0 +1,518 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.concat = concat;
+exports.substring = substring;
+exports.trim = trim;
+exports.ltrim = ltrim;
+exports.rtrim = rtrim;
+exports.upper = upper;
+exports.lower = lower;
+exports.length = length;
+exports.replace = replace;
+exports.lpad = lpad;
+exports.rpad = rpad;
+exports.split = split;
+exports.repeat = repeat;
+exports.reverse = reverse;
+/**
+ * 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.
+ */
+const operators_1 = require("../../operators");
+// ==================== Internal rendering helpers ====================
+/**
+ * Quote/escape a raw string as a SQL string literal.
+ * Doubling the single quote is valid escaping syntax across all 11
+ * supported dialects (standard SQL escaping).
+ */
+function quoteStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * Quote an identifier (column name), honoring dialect-specific quoting
+ * characters and supporting dotted `table.column` references.
+ */
+function quoteIdentifier(dialect, name) {
+    const parts = name.split('.');
+    return parts.map((part) => quoteIdentifierPart(dialect, part)).join('.');
+}
+function quoteIdentifierPart(dialect, part) {
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+        case 'clickhouse':
+            return `\`${part.replace(/`/g, '``')}\``;
+        case 'mssql':
+            return `[${part.replace(/\]/g, ']]')}]`;
+        case 'oracle':
+        case 'sqlite':
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+        case 'db2':
+        case 'snowflake':
+            return `"${part.replace(/"/g, '""')}"`;
+        default:
+            return `"${part.replace(/"/g, '""')}"`;
+    }
+}
+/**
+ * Render a `SqlExpr` (column-like argument) into a raw SQL fragment.
+ *
+ * Plain strings are treated as literal string VALUES and are quoted.
+ * `ColExpression`/`FnExpression`/`LiteralExpression` objects are unwrapped
+ * and rendered as expressions/identifiers.
+ */
+function toSqlFragment(dialect, arg) {
+    if (typeof arg === 'number') {
+        return String(arg);
+    }
+    if (typeof arg === 'string') {
+        return quoteStringLiteral(arg);
+    }
+    if (arg && typeof arg === 'object') {
+        if (arg.__type === 'col') {
+            return quoteIdentifier(dialect, arg.col);
+        }
+        if (arg.__type === 'fn') {
+            const fnExpr = arg;
+            const args = fnExpr.args.map((a) => toSqlFragment(dialect, a));
+            return `${fnExpr.fn}(${args.join(', ')})`;
+        }
+        if (arg.__type === 'literal') {
+            return arg.sql;
+        }
+    }
+    // Fallback - should not normally be reached given the SqlExpr type.
+    return String(arg);
+}
+function unsupported(fnName, dialect, reason) {
+    throw new Error(`[query-builders/functions/string] ${fnName}() is not supported for dialect "${dialect}": ${reason}`);
+}
+// ==================== concat ====================
+/**
+ * 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).
+ */
+function concat(dialect, ...parts) {
+    if (parts.length === 0) {
+        throw new Error('[query-builders/functions/string] concat() requires at least one argument');
+    }
+    const rendered = parts.map((p) => toSqlFragment(dialect, p));
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+        case 'mssql':
+        case 'snowflake':
+        case 'clickhouse':
+            return wrap(`CONCAT(${rendered.join(', ')})`);
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+        case 'sqlite':
+        case 'oracle':
+        case 'db2':
+            return wrap(rendered.join(' || '));
+        default:
+            return wrap(`CONCAT(${rendered.join(', ')})`);
+    }
+}
+function wrap(sql) {
+    // `literal()` returns { $literal: string }. We also attach __type/sql so
+    // callers who want the LiteralExpression shape can use it interchangeably;
+    // both shapes are recognized by isLiteralExpression()/isRawLiteral().
+    const lit = (0, operators_1.literal)(sql);
+    return Object.assign(lit, { __type: 'literal', sql });
+}
+// ==================== substring ====================
+/**
+ * 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.
+ */
+function substring(dialect, expr, start, length) {
+    const rendered = toSqlFragment(dialect, expr);
+    switch (dialect) {
+        case 'oracle':
+        case 'db2':
+        case 'sqlite':
+            return wrap(length !== undefined ? `SUBSTR(${rendered}, ${start}, ${length})` : `SUBSTR(${rendered}, ${start})`);
+        case 'mssql': {
+            const len = length !== undefined ? String(length) : `LEN(${rendered})`;
+            return wrap(`SUBSTRING(${rendered}, ${start}, ${len})`);
+        }
+        case 'mysql':
+        case 'mariadb':
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+        case 'snowflake':
+        case 'clickhouse':
+        default:
+            return wrap(length !== undefined
+                ? `SUBSTRING(${rendered}, ${start}, ${length})`
+                : `SUBSTRING(${rendered}, ${start})`);
+    }
+}
+/**
+ * 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).
+ */
+function trim(dialect, expr, options) {
+    const side = options?.side ?? 'both';
+    const rendered = toSqlFragment(dialect, expr);
+    const chars = options?.chars;
+    switch (dialect) {
+        case 'sqlite': {
+            const fnName = side === 'leading' ? 'ltrim' : side === 'trailing' ? 'rtrim' : 'trim';
+            return wrap(chars !== undefined ? `${fnName}(${rendered}, ${quoteStringLiteral(chars)})` : `${fnName}(${rendered})`);
+        }
+        case 'mssql': {
+            if (side === 'leading') {
+                return wrap(chars !== undefined ? `LTRIM(${rendered}, ${quoteStringLiteral(chars)})` : `LTRIM(${rendered})`);
+            }
+            if (side === 'trailing') {
+                return wrap(chars !== undefined ? `RTRIM(${rendered}, ${quoteStringLiteral(chars)})` : `RTRIM(${rendered})`);
+            }
+            return wrap(chars !== undefined ? `TRIM(${quoteStringLiteral(chars)} FROM ${rendered})` : `TRIM(${rendered})`);
+        }
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+        case 'oracle':
+        case 'db2':
+        case 'snowflake':
+        case 'mysql':
+        case 'mariadb':
+        case 'clickhouse':
+        default: {
+            const sideKeyword = side === 'leading' ? 'LEADING' : side === 'trailing' ? 'TRAILING' : 'BOTH';
+            if (chars !== undefined) {
+                return wrap(`TRIM(${sideKeyword} ${quoteStringLiteral(chars)} FROM ${rendered})`);
+            }
+            return wrap(`TRIM(${sideKeyword} FROM ${rendered})`);
+        }
+    }
+}
+/** Trim from the left only. Equivalent to `trim(dialect, expr, { side: 'leading' })`. */
+function ltrim(dialect, expr, chars) {
+    return trim(dialect, expr, { side: 'leading', chars });
+}
+/** Trim from the right only. Equivalent to `trim(dialect, expr, { side: 'trailing' })`. */
+function rtrim(dialect, expr, chars) {
+    return trim(dialect, expr, { side: 'trailing', chars });
+}
+// ==================== upper / lower ====================
+/**
+ * Uppercase a string. Identical (`UPPER(expr)`) across all 11 dialects.
+ */
+function upper(dialect, expr) {
+    return wrap(`UPPER(${toSqlFragment(dialect, expr)})`);
+}
+/**
+ * Lowercase a string. Identical (`LOWER(expr)`) across all 11 dialects.
+ */
+function lower(dialect, expr) {
+    return wrap(`LOWER(${toSqlFragment(dialect, expr)})`);
+}
+// ==================== length ====================
+/**
+ * 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.
+ */
+function length(dialect, expr) {
+    const rendered = toSqlFragment(dialect, expr);
+    switch (dialect) {
+        case 'mssql':
+        case 'redshift':
+            return wrap(`LEN(${rendered})`);
+        case 'oracle':
+        case 'sqlite':
+            return wrap(`LENGTH(${rendered})`);
+        case 'clickhouse':
+            return wrap(`lengthUTF8(${rendered})`);
+        case 'mysql':
+        case 'mariadb':
+        case 'postgres':
+        case 'cockroachdb':
+        case 'db2':
+        case 'snowflake':
+        default:
+            return wrap(`CHAR_LENGTH(${rendered})`);
+    }
+}
+// ==================== replace ====================
+/**
+ * Replace all occurrences of a substring.
+ * `REPLACE(expr, search, replacement)` is identical across all 11 dialects.
+ */
+function replace(dialect, expr, search, replacement) {
+    const rendered = toSqlFragment(dialect, expr);
+    return wrap(`REPLACE(${rendered}, ${quoteStringLiteral(search)}, ${quoteStringLiteral(replacement)})`);
+}
+// ==================== lpad / rpad ====================
+/**
+ * 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.
+ */
+function lpad(dialect, expr, targetLength, padString = ' ') {
+    const rendered = toSqlFragment(dialect, expr);
+    const pad = quoteStringLiteral(padString);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+        case 'oracle':
+        case 'snowflake':
+            return wrap(`LPAD(${rendered}, ${targetLength}, ${pad})`);
+        case 'clickhouse':
+            return wrap(`leftPad(${rendered}, ${targetLength}, ${pad})`);
+        case 'mssql':
+            return wrap(`RIGHT(REPLICATE(${pad}, ${targetLength}) + ${rendered}, ${targetLength})`);
+        case 'db2':
+            return wrap(`CASE WHEN CHAR_LENGTH(${rendered}) >= ${targetLength} THEN ${rendered} ` +
+                `ELSE SUBSTR(REPEAT(${pad}, ${targetLength}), 1, ${targetLength} - CHAR_LENGTH(${rendered})) || ${rendered} END`);
+        case 'sqlite':
+            return unsupported('lpad', dialect, 'SQLite has no LPAD/REPEAT function and no safe single-expression workaround');
+        default:
+            return wrap(`LPAD(${rendered}, ${targetLength}, ${pad})`);
+    }
+}
+/**
+ * Right-pad a string to a target length. See {@link lpad} for per-dialect
+ * notes; the same dialects that lack `LPAD` also lack `RPAD`.
+ */
+function rpad(dialect, expr, targetLength, padString = ' ') {
+    const rendered = toSqlFragment(dialect, expr);
+    const pad = quoteStringLiteral(padString);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+        case 'oracle':
+        case 'snowflake':
+            return wrap(`RPAD(${rendered}, ${targetLength}, ${pad})`);
+        case 'clickhouse':
+            return wrap(`rightPad(${rendered}, ${targetLength}, ${pad})`);
+        case 'mssql':
+            return wrap(`LEFT(${rendered} + REPLICATE(${pad}, ${targetLength}), ${targetLength})`);
+        case 'db2':
+            return wrap(`CASE WHEN CHAR_LENGTH(${rendered}) >= ${targetLength} THEN ${rendered} ` +
+                `ELSE ${rendered} || SUBSTR(REPEAT(${pad}, ${targetLength}), 1, ${targetLength} - CHAR_LENGTH(${rendered})) END`);
+        case 'sqlite':
+            return unsupported('rpad', dialect, 'SQLite has no RPAD/REPEAT function and no safe single-expression workaround');
+        default:
+            return wrap(`RPAD(${rendered}, ${targetLength}, ${pad})`);
+    }
+}
+// ==================== split ====================
+/**
+ * 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.
+ */
+function split(dialect, expr, delimiter) {
+    const rendered = toSqlFragment(dialect, expr);
+    const delim = quoteStringLiteral(delimiter);
+    switch (dialect) {
+        case 'postgres':
+        case 'cockroachdb':
+            return wrap(`STRING_TO_ARRAY(${rendered}, ${delim})`);
+        case 'redshift':
+            return wrap(`SPLIT_TO_ARRAY(${rendered}, ${delim})`);
+        case 'snowflake':
+            return wrap(`SPLIT(${rendered}, ${delim})`);
+        case 'clickhouse':
+            return wrap(`splitByString(${delim}, ${rendered})`);
+        case 'mysql':
+        case 'mariadb':
+            return unsupported('split', dialect, 'no array type / split-to-array function exists; use SUBSTRING_INDEX for extracting a single part instead');
+        case 'mssql':
+            return unsupported('split', dialect, 'STRING_SPLIT is table-valued (usable only in a FROM clause), not a scalar expression');
+        case 'oracle':
+        case 'db2':
+        case 'sqlite':
+            return unsupported('split', dialect, 'no built-in split-to-array function; would require CONNECT BY/recursive-CTE tricks that cannot be expressed as a single SQL fragment');
+        default:
+            return unsupported('split', dialect, 'no known split mechanism for this dialect');
+    }
+}
+// ==================== repeat ====================
+/**
+ * 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).
+ */
+function repeat(dialect, expr, n) {
+    const rendered = toSqlFragment(dialect, expr);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+        case 'postgres':
+        case 'cockroachdb':
+        case 'redshift':
+        case 'db2':
+        case 'snowflake':
+            return wrap(`REPEAT(${rendered}, ${n})`);
+        case 'clickhouse':
+            return wrap(`repeat(${rendered}, ${n})`);
+        case 'mssql':
+            return wrap(`REPLICATE(${rendered}, ${n})`);
+        case 'oracle':
+            return wrap(`RPAD(${rendered}, LENGTH(${rendered}) * ${n}, ${rendered})`);
+        case 'sqlite':
+            return unsupported('repeat', dialect, 'SQLite has no REPEAT function and no safe single-expression workaround');
+        default:
+            return wrap(`REPEAT(${rendered}, ${n})`);
+    }
+}
+// ==================== reverse ====================
+/**
+ * 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.
+ */
+function reverse(dialect, expr) {
+    const rendered = toSqlFragment(dialect, expr);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb':
+        case 'mssql':
+        case 'postgres':
+        case 'cockroachdb':
+        case 'snowflake':
+            return wrap(`REVERSE(${rendered})`);
+        case 'clickhouse':
+            return wrap(`reverseUTF8(${rendered})`);
+        case 'oracle':
+            return unsupported('reverse', dialect, 'Oracle has no built-in REVERSE function for strings');
+        case 'db2':
+            return unsupported('reverse', dialect, 'Db2 for LUW has no built-in REVERSE scalar function');
+        case 'redshift':
+            return unsupported('reverse', dialect, 'REVERSE is not part of Redshift\'s documented string function set');
+        case 'sqlite':
+            return unsupported('reverse', dialect, 'SQLite has no built-in REVERSE function');
+        default:
+            return wrap(`REVERSE(${rendered})`);
+    }
+}