ts-prorm-orm 1.1.0

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

@@ -0,0 +1,503 @@
+"use strict";
+/**
+ * Typed CASE WHEN ... THEN ... ELSE ... END expression builder.
+ *
+ * `CASE WHEN` is ANSI-standard SQL (SQL-92) and is supported identically,
+ * with no syntax variation, across every dialect this ORM targets:
+ *   - mysql, mariadb: full support (searched + simple CASE)
+ *   - postgres, cockroachdb, redshift: full support (Postgres-derived)
+ *   - mssql: full support (T-SQL CASE is ANSI-compliant)
+ *   - oracle: full support (in addition to the older DECODE() function,
+ *     Oracle has supported standard CASE since 9i)
+ *   - sqlite: full support
+ *   - db2: full support
+ *   - snowflake: full support
+ *   - clickhouse: full support, including both the "searched" form
+ *     (`CASE WHEN cond THEN a END`) and the "simple" form
+ *     (`CASE expr WHEN val THEN a END`). ClickHouse also offers the
+ *     `multiIf()`/`if()` functions as engine-native alternatives, but plain
+ *     `CASE` works exactly as ANSI SQL specifies, so no dialect branching is
+ *     required here (unlike window frame extensions or JSON path functions).
+ *
+ * This module is intentionally self-contained: 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 builder resolves directly to a final SQL
+ * fragment string, which is then wrapped with the existing `literalExpr()`
+ * helper from `src/operators.ts` so it slots into `attributes: [...]` arrays
+ * exactly the way `fn()`/`col()`/`cast()`/the window-function builder do
+ * today (see `attributeToSql()` in `sql-compiler.ts`, which already knows
+ * how to render `{ __type: 'literal', sql }` and `[expr, alias]` tuples).
+ *
+ * Condition syntax: `.when()` on the searched-CASE builder (`caseWhen()`)
+ * accepts the SAME condition-object shape already used by `where:` clauses
+ * throughout this ORM (see `src/operators.ts`'s `Op` symbols and
+ * `src/query-builders/where-builder.ts`), e.g.:
+ *
+ *   { age: { [Op.gte]: 18 } }
+ *   { [Op.and]: [{ age: { [Op.gte]: 18 } }, { status: 'active' }] }
+ *   { [Op.between]: [...] } // via a field key, see below
+ *
+ * rather than inventing a new mini-language. This keeps `caseWhen().when(...)`
+ * consistent with `Model.findAll({ where: ... })` conditions. A shorthand
+ * 3-arg form, `.when(column, operator, value, thenValue)`, is also supported
+ * for ergonomic simple comparisons (mirroring `Op.where(col, op, value)`).
+ *
+ * @example
+ * ```typescript
+ * import { caseWhen, caseOf } from './query-builders/functions/conditional';
+ * import { Op, col } from '../../operators';
+ *
+ * // Searched CASE (condition-object form, same shape as `where:`)
+ * User.findAll({
+ *   attributes: [
+ *     'name',
+ *     caseWhen()
+ *       .when({ age: { [Op.gte]: 18 } }, 'adult')
+ *       .when({ age: { [Op.gte]: 13 } }, 'teen')
+ *       .else('child')
+ *       .as('ageGroup'),
+ *   ],
+ * });
+ *
+ * // Searched CASE (3-arg shorthand form)
+ * caseWhen().when('age', '>=', 18, 'adult').else('minor').as('ageGroup');
+ *
+ * // Simple CASE (CASE expr WHEN val THEN result ... END)
+ * caseOf(col('status'))
+ *   .when('active', 1)
+ *   .when('inactive', 0)
+ *   .else(null)
+ *   .as('statusFlag');
+ *
+ * // Nested CASE
+ * caseWhen()
+ *   .when({ age: { [Op.gte]: 65 } }, 'senior')
+ *   .else(caseWhen().when({ age: { [Op.gte]: 18 } }, 'adult').else('minor'))
+ *   .as('category');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleCaseBuilder = exports.CaseBuilder = void 0;
+exports.caseWhen = caseWhen;
+exports.caseOf = caseOf;
+const operators_1 = require("../../operators");
+function escapeIdentifier(name) {
+    if (name.includes('.')) {
+        return name
+            .split('.')
+            .map((part) => `"${part.replace(/"/g, '""')}"`)
+            .join('.');
+    }
+    return `"${name.replace(/"/g, '""')}"`;
+}
+function escapeStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * Render a THEN/ELSE/simple-CASE value into a SQL fragment. Distinguishes
+ * plain value literals (strings get quoted/escaped, numbers/booleans are
+ * inlined, `null` becomes SQL NULL) from typed expressions (`col()`, `fn()`,
+ * `literal()`) and from nested CASE builders, which get rendered recursively.
+ */
+function toSqlFragment(value) {
+    if (value === null)
+        return 'NULL';
+    if (value instanceof CaseBuilder || value instanceof SimpleCaseBuilder) {
+        return value.toSQL();
+    }
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'TRUE' : 'FALSE';
+    }
+    if (typeof value === 'string') {
+        return escapeStringLiteral(value);
+    }
+    if ((0, operators_1.isFnExpression)(value)) {
+        const args = value.args.map((a) => toSqlFragment(a)).join(', ');
+        return `${value.fn}(${args})`;
+    }
+    if ((0, operators_1.isColExpression)(value)) {
+        return escapeIdentifier(value.col);
+    }
+    if ((0, operators_1.isLiteralExpression)(value)) {
+        return value.sql ?? value.$literal;
+    }
+    if ((0, operators_1.isColumnReference)(value)) {
+        return escapeIdentifier(value.$col);
+    }
+    // Fallback: stringify.
+    return String(value);
+}
+/**
+ * Render a "condition target" — i.e. an argument that is either a plain
+ * value or a column reference — used when comparing a field to a value
+ * inside a condition operator (e.g. the right-hand side of `$gt`, or the
+ * two ends of a `$between`). Reuses `toSqlFragment` since the value shapes
+ * (`$col`, `$literal`, plain values) are the same.
+ */
+function toComparisonSql(value) {
+    return toSqlFragment(value);
+}
+/**
+ * Compile a `where:`-shaped condition object into a raw (inline, non-
+ * parameterized) SQL boolean expression. This is a small, self-contained
+ * subset of the logic in `src/query-builders/where-builder.ts`'s
+ * `WhereBuilder`, adapted to produce inline SQL (values are escaped
+ * directly into the string) rather than `?` placeholders + a values array,
+ * since CASE expressions are embedded as raw SQL literals via
+ * `literalExpr()` rather than run through the parameterized query pipeline.
+ *
+ * Reuses `operatorToWhereKey()` and `isColumnReference()` from
+ * `src/operators.ts` (both already exported) instead of re-implementing the
+ * Symbol -> `$op` string mapping.
+ */
+function compileCondition(condition) {
+    if (condition === null || condition === undefined) {
+        return '1=1';
+    }
+    if (typeof condition !== 'object') {
+        // A bare scalar condition doesn't make sense without a field; treat as
+        // a raw truthy/falsy literal for robustness.
+        return condition ? '1=1' : '1=0';
+    }
+    const cond = condition;
+    // Symbol-based Op.and / Op.or / Op.not
+    const symbolKeys = Object.getOwnPropertySymbols(cond);
+    for (const sym of symbolKeys) {
+        if (sym === operators_1.Op.and) {
+            const parts = cond[sym].map((c) => `(${compileCondition(c)})`);
+            return parts.join(' AND ');
+        }
+        if (sym === operators_1.Op.or) {
+            const parts = cond[sym].map((c) => `(${compileCondition(c)})`);
+            return parts.join(' OR ');
+        }
+        if (sym === operators_1.Op.not) {
+            return `NOT (${compileCondition(cond[sym])})`;
+        }
+    }
+    // String-based $and / $or / $not (same convention as WhereBuilder)
+    if ('$and' in cond) {
+        const parts = cond.$and.map((c) => `(${compileCondition(c)})`);
+        return parts.join(' AND ');
+    }
+    if ('$or' in cond) {
+        const parts = cond.$or.map((c) => `(${compileCondition(c)})`);
+        return parts.join(' OR ');
+    }
+    if ('$not' in cond) {
+        return `NOT (${compileCondition(cond.$not)})`;
+    }
+    // $where: { $col, $op: value } explicit column-reference condition
+    if ('$where' in cond) {
+        const whereClause = cond.$where;
+        const fieldSql = escapeIdentifier(whereClause.$col);
+        const opEntries = Object.entries(whereClause).filter(([k]) => k !== '$col');
+        const parts = opEntries.map(([opKey, val]) => compileFieldOperator(fieldSql, opKey, val));
+        return parts.join(' AND ') || fieldSql;
+    }
+    // Plain field conditions: { field: value } or { field: { [Op.x]: value } }
+    const fieldConditions = [];
+    for (const [field, value] of Object.entries(cond)) {
+        const fieldSql = escapeIdentifier(field);
+        if (value === null || value === undefined) {
+            fieldConditions.push(`${fieldSql} IS NULL`);
+        }
+        else if (typeof value === 'object' && !Array.isArray(value)) {
+            // Could contain Symbol operator keys (Op.gt, etc.) or string $op keys.
+            const opSymbolKeys = Object.getOwnPropertySymbols(value);
+            let handled = false;
+            for (const sym of opSymbolKeys) {
+                const opKey = (0, operators_1.operatorToWhereKey)(sym);
+                fieldConditions.push(compileFieldOperator(fieldSql, opKey, value[sym]));
+                handled = true;
+            }
+            for (const [opKey, opVal] of Object.entries(value)) {
+                fieldConditions.push(compileFieldOperator(fieldSql, opKey, opVal));
+                handled = true;
+            }
+            if (!handled) {
+                fieldConditions.push(`${fieldSql} IS NULL`);
+            }
+        }
+        else {
+            fieldConditions.push(`${fieldSql} = ${toComparisonSql(value)}`);
+        }
+    }
+    return fieldConditions.join(' AND ');
+}
+/**
+ * Compile a single `$op: value` pair (e.g. `$gt`, `$between`, `$isNull`)
+ * into a raw SQL fragment for the given already-escaped field SQL.
+ */
+function compileFieldOperator(fieldSql, opKey, value) {
+    switch (opKey) {
+        case '$eq':
+            return `${fieldSql} = ${toComparisonSql(value)}`;
+        case '$ne':
+            return `${fieldSql} != ${toComparisonSql(value)}`;
+        case '$gt':
+            return `${fieldSql} > ${toComparisonSql(value)}`;
+        case '$gte':
+            return `${fieldSql} >= ${toComparisonSql(value)}`;
+        case '$lt':
+            return `${fieldSql} < ${toComparisonSql(value)}`;
+        case '$lte':
+            return `${fieldSql} <= ${toComparisonSql(value)}`;
+        case '$like':
+            return `${fieldSql} LIKE ${toComparisonSql(value)}`;
+        case '$notLike':
+            return `${fieldSql} NOT LIKE ${toComparisonSql(value)}`;
+        case '$iLike':
+            return `${fieldSql} ILIKE ${toComparisonSql(value)}`;
+        case '$notILike':
+            return `${fieldSql} NOT ILIKE ${toComparisonSql(value)}`;
+        case '$col':
+            return `${fieldSql} = ${escapeIdentifier(String(value))}`;
+        case '$in': {
+            const values = Array.isArray(value) ? value : [];
+            if (values.length === 0)
+                return '1=0';
+            return `${fieldSql} IN (${values.map((v) => toComparisonSql(v)).join(', ')})`;
+        }
+        case '$notIn': {
+            const values = Array.isArray(value) ? value : [];
+            if (values.length === 0)
+                return '1=1';
+            return `${fieldSql} NOT IN (${values.map((v) => toComparisonSql(v)).join(', ')})`;
+        }
+        case '$between': {
+            const [start, end] = value;
+            return `${fieldSql} BETWEEN ${toComparisonSql(start)} AND ${toComparisonSql(end)}`;
+        }
+        case '$notBetween': {
+            const [start, end] = value;
+            return `${fieldSql} NOT BETWEEN ${toComparisonSql(start)} AND ${toComparisonSql(end)}`;
+        }
+        case '$isNull':
+            return value ? `${fieldSql} IS NULL` : `${fieldSql} IS NOT NULL`;
+        case '$isNotNull':
+            return value ? `${fieldSql} IS NOT NULL` : `${fieldSql} IS NULL`;
+        case '$regexp':
+            return `${fieldSql} REGEXP ${toComparisonSql(value)}`;
+        case '$notRegexp':
+            return `${fieldSql} NOT REGEXP ${toComparisonSql(value)}`;
+        case '$startsWith':
+            return `${fieldSql} LIKE ${escapeStringLiteral(`${value}%`)}`;
+        case '$notStartsWith':
+            return `${fieldSql} NOT LIKE ${escapeStringLiteral(`${value}%`)}`;
+        case '$endsWith':
+            return `${fieldSql} LIKE ${escapeStringLiteral(`%${value}`)}`;
+        case '$notEndsWith':
+            return `${fieldSql} NOT LIKE ${escapeStringLiteral(`%${value}`)}`;
+        case '$substring':
+            return `${fieldSql} LIKE ${escapeStringLiteral(`%${value}%`)}`;
+        case '$notSubstring':
+            return `${fieldSql} NOT LIKE ${escapeStringLiteral(`%${value}%`)}`;
+        default:
+            // Unknown operator: fall back to equality against the raw value to
+            // avoid silently dropping the condition.
+            return `${fieldSql} = ${toComparisonSql(value)}`;
+    }
+}
+/**
+ * Map a string comparison operator (e.g. `'>='`, `'!='`) or an `Op.*`
+ * Symbol to the `$op` key used internally, reusing `operatorToWhereKey()`
+ * for the Symbol case (same convention as `Op.where()`).
+ */
+function normalizeOperator(operator) {
+    if (typeof operator === 'symbol') {
+        return (0, operators_1.operatorToWhereKey)(operator);
+    }
+    switch (operator) {
+        case '=':
+        case '==':
+            return '$eq';
+        case '!=':
+        case '<>':
+            return '$ne';
+        case '>':
+            return '$gt';
+        case '>=':
+            return '$gte';
+        case '<':
+            return '$lt';
+        case '<=':
+            return '$lte';
+        case 'like':
+            return '$like';
+        case 'not like':
+        case 'not_like':
+            return '$notLike';
+        case 'in':
+            return '$in';
+        case 'not in':
+        case 'not_in':
+            return '$notIn';
+        case 'between':
+            return '$between';
+        case 'not between':
+        case 'not_between':
+            return '$notBetween';
+        case 'is null':
+        case 'is_null':
+            return '$isNull';
+        case 'is not null':
+        case 'is_not_null':
+            return '$isNotNull';
+        default:
+            return `$${operator}`;
+    }
+}
+/**
+ * Fluent builder for a "searched" CASE expression:
+ *   CASE WHEN cond1 THEN result1 WHEN cond2 THEN result2 ... ELSE else END
+ *
+ * Build with `caseWhen()`. Terminate with `.as(alias)` (for use directly in
+ * an `attributes: [...]` array) or `.toSQL()` / `.toLiteral()`.
+ */
+class CaseBuilder {
+    constructor() {
+        this.clauses = [];
+        this.hasElse = false;
+    }
+    when(conditionOrColumn, thenValueOrOperator, value, thenValue) {
+        // 4-arg shorthand form: .when(column, operator, value, thenValue)
+        if (typeof conditionOrColumn === 'string' && arguments.length >= 4) {
+            const opKey = normalizeOperator(thenValueOrOperator);
+            const fieldSql = escapeIdentifier(conditionOrColumn);
+            const conditionSql = compileFieldOperator(fieldSql, opKey, value);
+            this.clauses.push({ conditionSql, resultSql: toSqlFragment(thenValue) });
+            return this;
+        }
+        // 2-arg condition-object form: .when(condition, thenValue)
+        const conditionSql = compileCondition(conditionOrColumn);
+        this.clauses.push({
+            conditionSql,
+            resultSql: toSqlFragment(thenValueOrOperator),
+        });
+        return this;
+    }
+    /** Set the `ELSE <value>` branch. Optional — omitting it yields an implicit SQL NULL. */
+    else(value) {
+        this.elseSql = toSqlFragment(value);
+        this.hasElse = true;
+        return this;
+    }
+    /** Render the `CASE WHEN ... END` SQL fragment (no alias). */
+    toSQL() {
+        if (this.clauses.length === 0) {
+            throw new Error('caseWhen() requires at least one .when(condition, thenValue) branch');
+        }
+        const whenParts = this.clauses
+            .map((c) => `WHEN ${c.conditionSql} THEN ${c.resultSql}`)
+            .join(' ');
+        const elsePart = this.hasElse ? ` ELSE ${this.elseSql}` : '';
+        return `CASE ${whenParts}${elsePart} END`;
+    }
+    /**
+     * Terminal call: returns an `[expr, alias]` tuple compatible with the
+     * existing `attributes: [...]` pattern (see `attributeToSql()` in
+     * `sql-compiler.ts`, which already knows how to render
+     * `[LiteralExpression, alias]` tuples without any core changes).
+     */
+    as(alias) {
+        return [(0, operators_1.literalExpr)(this.toSQL()), alias];
+    }
+    /** Use the builder directly wherever a raw SQL literal expression is expected. */
+    toLiteral() {
+        return (0, operators_1.literalExpr)(this.toSQL());
+    }
+}
+exports.CaseBuilder = CaseBuilder;
+/**
+ * Fluent builder for a "simple" CASE expression:
+ *   CASE expr WHEN val1 THEN result1 WHEN val2 THEN result2 ... ELSE else END
+ *
+ * Build with `caseOf(expr)`. Terminate with `.as(alias)` or `.toSQL()` /
+ * `.toLiteral()`.
+ */
+class SimpleCaseBuilder {
+    constructor(expr) {
+        this.clauses = [];
+        this.hasElse = false;
+        // `expr` is typically a column reference (string column name, col(), or
+        // any other CaseValue-compatible expression).
+        this.exprSql =
+            typeof expr === 'string' ? escapeIdentifier(expr) : toSqlFragment(expr);
+    }
+    /**
+     * Add a `WHEN <value> THEN <result>` branch. Repeatable — call multiple
+     * times to add multiple branches, evaluated in order.
+     */
+    when(value, result) {
+        this.clauses.push({ valueSql: toSqlFragment(value), resultSql: toSqlFragment(result) });
+        return this;
+    }
+    /** Set the `ELSE <value>` branch. Optional — omitting it yields an implicit SQL NULL. */
+    else(value) {
+        this.elseSql = toSqlFragment(value);
+        this.hasElse = true;
+        return this;
+    }
+    /** Render the `CASE expr WHEN ... END` SQL fragment (no alias). */
+    toSQL() {
+        if (this.clauses.length === 0) {
+            throw new Error('caseOf() requires at least one .when(value, result) branch');
+        }
+        const whenParts = this.clauses
+            .map((c) => `WHEN ${c.valueSql} THEN ${c.resultSql}`)
+            .join(' ');
+        const elsePart = this.hasElse ? ` ELSE ${this.elseSql}` : '';
+        return `CASE ${this.exprSql} ${whenParts}${elsePart} END`;
+    }
+    /**
+     * Terminal call: returns an `[expr, alias]` tuple compatible with the
+     * existing `attributes: [...]` pattern.
+     */
+    as(alias) {
+        return [(0, operators_1.literalExpr)(this.toSQL()), alias];
+    }
+    /** Use the builder directly wherever a raw SQL literal expression is expected. */
+    toLiteral() {
+        return (0, operators_1.literalExpr)(this.toSQL());
+    }
+}
+exports.SimpleCaseBuilder = SimpleCaseBuilder;
+/**
+ * Start a "searched" CASE expression:
+ *   CASE WHEN cond1 THEN result1 [WHEN cond2 THEN result2 ...] [ELSE else] END
+ *
+ * @example
+ * ```typescript
+ * caseWhen()
+ *   .when({ age: { [Op.gte]: 18 } }, 'adult')
+ *   .else('minor')
+ *   .as('ageGroup')
+ * ```
+ */
+function caseWhen() {
+    return new CaseBuilder();
+}
+/**
+ * Start a "simple" CASE expression:
+ *   CASE expr WHEN val1 THEN result1 [WHEN val2 THEN result2 ...] [ELSE else] END
+ *
+ * @param expr - The expression being compared. A plain string is treated as
+ *   a column name (identifier-escaped); pass `col('name')`, `fn(...)`, or
+ *   `literal(...)` for other expression types.
+ *
+ * @example
+ * ```typescript
+ * caseOf('status')
+ *   .when('active', 1)
+ *   .when('inactive', 0)
+ *   .else(null)
+ *   .as('statusFlag')
+ * ```
+ */
+function caseOf(expr) {
+    return new SimpleCaseBuilder(expr);
+}