ts-prorm-orm 1.1.0

package/dist/query-builders/cte-builder.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * CTE (Common Table Expression) Builder
+ * Provides an ORM-like way to build CTEs without raw SQL
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CTEBuilder = void 0;
+exports.createCTEBuilder = createCTEBuilder;
+class CTEBuilder {
+    constructor() {
+        this.ctes = [];
+    }
+    /**
+     * Add a simple CTE with a base query
+     * @example
+     * cte.add('active_users', { model: User, baseCase: { where: { active: true } } })
+     * cte.add('active_users', { model: 'users', baseCase: { where: { active: true } } })
+     */
+    add(name, options) {
+        this.ctes.push({
+            name,
+            model: options?.model,
+            columns: options?.columns,
+            baseCase: options?.baseCase,
+        });
+        return this;
+    }
+    /**
+     * Add a recursive CTE for hierarchical data
+     * @example
+     * cte.addRecursive({
+     *   name: 'org_chart',
+     *   model: Employee,
+     *   anchor: { where: { managerId: null } },
+     *   recursive: { where: { '$org_chart.id$': { [Op.eq]: { [Op.col]: 'Employee.managerId' } } } }
+     * })
+     */
+    addRecursive(options) {
+        this.ctes.push({
+            name: options.name,
+            model: options.model,
+            columns: options.columns,
+            baseCase: options.anchor,
+            recursiveCase: options.recursive,
+        });
+        return this;
+    }
+    /**
+     * Get all CTEs
+     */
+    getCTEs() {
+        return this.ctes;
+    }
+    /**
+     * Get CTE names
+     */
+    getCTENames() {
+        return this.ctes.map(cte => cte.name);
+    }
+    /**
+     * Build the WITH clause SQL
+     */
+    toSQL(dialect) {
+        return this.ctes.map(cte => cte.name).join(', ');
+    }
+    /**
+     * Clear all CTEs
+     */
+    clear() {
+        this.ctes = [];
+    }
+}
+exports.CTEBuilder = CTEBuilder;
+/**
+ * Create a new CTE builder
+ */
+function createCTEBuilder() {
+    return new CTEBuilder();
+}
+exports.default = { CTEBuilder, createCTEBuilder };

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

@@ -0,0 +1,390 @@
+"use strict";
+/**
+ * Typed aggregate-function builder API.
+ *
+ * `COUNT`/`SUM`/`AVG`/`MIN`/`MAX` are already reachable through the generic
+ * `fn('SUM', col('amount'))` pattern in `src/operators.ts` because those
+ * names are ANSI-identical across every dialect this ORM supports. This
+ * module fills the real gap: aggregate functions whose *name* (and in some
+ * cases clause placement) differs per dialect, most notably string
+ * aggregation (`GROUP_CONCAT` / `STRING_AGG` / `LISTAGG` / ClickHouse's
+ * array-based approach) and array aggregation (`ARRAY_AGG` / `JSON_ARRAYAGG`
+ * / `groupArray`).
+ *
+ * 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 touch `src/operators.ts`. Every builder function computes a final,
+ * dialect-correct SQL fragment string directly and wraps it with the
+ * existing `literalExpr()` helper from `src/operators.ts` so it slots into
+ * `attributes: [...]` arrays exactly the way `fn()`/`col()`/`cast()` do
+ * today (see `attributeToSql()` in `sql-compiler.ts`, which already knows
+ * how to render `{ __type: 'literal', sql }` and `[expr, alias]` tuples).
+ *
+ * @example
+ * ```typescript
+ * import { count, countDistinct, sum, stringAgg, arrayAgg } from './query-builders/functions/aggregate';
+ * import { col } from '../../operators';
+ *
+ * User.findAll({
+ *   attributes: [
+ *     'department',
+ *     [count('postgres'), 'total'],
+ *     [countDistinct('postgres', col('email')), 'uniqueEmails'],
+ *     [stringAgg('postgres', col('name'), ', ', { orderBy: 'name' }), 'names'],
+ *     [arrayAgg('postgres', col('id')), 'ids'],
+ *   ],
+ *   group: ['department'],
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.count = count;
+exports.countDistinct = countDistinct;
+exports.sum = sum;
+exports.avg = avg;
+exports.min = min;
+exports.max = max;
+exports.stringAgg = stringAgg;
+exports.arrayAgg = arrayAgg;
+const operators_1 = require("../../operators");
+// ---------------------------------------------------------------------------
+// Shared helpers (mirrors the pattern used in ./window.ts)
+// ---------------------------------------------------------------------------
+function escapeIdentifier(name) {
+    // Support dotted "table.column" references, same convention as col().
+    if (name.includes('.')) {
+        return name
+            .split('.')
+            .map((part) => `"${part.replace(/"/g, '""')}"`)
+            .join('.');
+    }
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * Flatten an aggregate-function argument (string, ColExpression,
+ * FnExpression, LiteralExpression) into a raw SQL fragment string.
+ */
+function toSqlFragment(arg) {
+    if (typeof arg === 'string') {
+        return escapeIdentifier(arg);
+    }
+    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)) {
+        // Handles both { __type: 'literal', sql } and { $literal: sql } shapes.
+        return arg.sql ?? arg.$literal;
+    }
+    // Fallback: stringify.
+    return String(arg);
+}
+/** Escape a string literal for embedding directly in SQL (single-quote doubling). */
+function escapeStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function normalizeOrderBy(orderBy) {
+    const entries = Array.isArray(orderBy) ? orderBy : [orderBy];
+    return entries.map((entry) => typeof entry === 'string' ? { column: entry } : entry);
+}
+/** Render `col ASC, col2 DESC` (no leading "ORDER BY" keyword). */
+function renderOrderByList(orderBy) {
+    return normalizeOrderBy(orderBy)
+        .map((entry) => {
+        const colSql = escapeIdentifier(entry.column);
+        return entry.direction ? `${colSql} ${entry.direction}` : colSql;
+    })
+        .join(', ');
+}
+function unsupported(fnName, dialect, detail) {
+    throw new Error(`${fnName}() is not supported on dialect "${dialect}"${detail ? `: ${detail}` : ''}`);
+}
+// ---------------------------------------------------------------------------
+// count / countDistinct / sum / avg / min / max
+// ---------------------------------------------------------------------------
+/**
+ * `COUNT(*)` / `COUNT(expr)` — identical ANSI syntax across all 11 dialects.
+ *
+ * @example
+ * ```typescript
+ * count('postgres')            // -> COUNT(*)
+ * count('postgres', col('id')) // -> COUNT("id")
+ * ```
+ */
+function count(_dialect, expr) {
+    const argSql = expr === undefined ? '*' : toSqlFragment(expr);
+    return (0, operators_1.literalExpr)(`COUNT(${argSql})`);
+}
+/**
+ * `COUNT(DISTINCT expr)`.
+ *
+ * Verified across all 11 dialects: MySQL, MariaDB, PostgreSQL, MSSQL,
+ * Oracle, SQLite, CockroachDB, Redshift, Db2, and Snowflake all support the
+ * exact ANSI `COUNT(DISTINCT expr)` syntax. ClickHouse also parses
+ * `COUNT(DISTINCT expr)` (it desugars to an internal uniq-exact
+ * implementation), though ClickHouse users may prefer the native
+ * `uniqExact(expr)` function for clarity/performance on very large
+ * cardinalities — that's a deliberate escape hatch, not a requirement, so
+ * `COUNT(DISTINCT expr)` is used here for consistency with the other
+ * dialects.
+ */
+function countDistinct(_dialect, expr) {
+    return (0, operators_1.literalExpr)(`COUNT(DISTINCT ${toSqlFragment(expr)})`);
+}
+/**
+ * `SUM(expr)` — identical everywhere. Note: SUM of an all-NULL group (or
+ * zero input rows) returns SQL NULL (not 0) in every one of these dialects,
+ * so callers should COALESCE(...) explicitly if a numeric default is
+ * required.
+ */
+function sum(_dialect, expr) {
+    return (0, operators_1.literalExpr)(`SUM(${toSqlFragment(expr)})`);
+}
+/**
+ * `AVG(expr)` — identical everywhere. Note: integer-typed columns are
+ * averaged as an exact/decimal type in PostgreSQL, MSSQL, Oracle, Db2, and
+ * Snowflake, but MySQL/MariaDB/SQLite/ClickHouse promote to floating point;
+ * cast explicitly (e.g. `cast(col('x'), 'DECIMAL(10,2)')`) if exact decimal
+ * averaging is required across dialects.
+ */
+function avg(_dialect, expr) {
+    return (0, operators_1.literalExpr)(`AVG(${toSqlFragment(expr)})`);
+}
+/** `MIN(expr)` — identical everywhere. */
+function min(_dialect, expr) {
+    return (0, operators_1.literalExpr)(`MIN(${toSqlFragment(expr)})`);
+}
+/** `MAX(expr)` — identical everywhere. */
+function max(_dialect, expr) {
+    return (0, operators_1.literalExpr)(`MAX(${toSqlFragment(expr)})`);
+}
+// ---------------------------------------------------------------------------
+// stringAgg — the key, most syntax-divergent function in this module
+// ---------------------------------------------------------------------------
+/**
+ * String aggregation (`GROUP_CONCAT` / `STRING_AGG` / `LISTAGG` / ClickHouse
+ * array-concat), dispatched per-dialect. This is the single most
+ * error-prone aggregate across dialects, so each branch below documents the
+ * exact verified syntax.
+ *
+ * - **MySQL / MariaDB**:
+ *   `GROUP_CONCAT([DISTINCT] expr [ORDER BY col [ASC|DESC]] SEPARATOR 'delim')`
+ *   Clause order is fixed: DISTINCT, then the expression, then ORDER BY,
+ *   then SEPARATOR — SEPARATOR must come last and is a keyword, not a comma
+ *   argument.
+ *
+ * - **SQLite**: `GROUP_CONCAT(expr, 'delim')` (2-argument form; the
+ *   separator defaults to `,` if omitted). SQLite's GROUP_CONCAT does
+ *   **not** support an `ORDER BY` clause inside the function call at all —
+ *   if `options.orderBy` is passed for SQLite this throws, since silently
+ *   ignoring it would produce non-deterministic ordering that looks
+ *   intentional. Pre-sort via a subquery/CTE if ordering is required.
+ *   SQLite's DISTINCT variant (`GROUP_CONCAT(DISTINCT expr)`) is supported
+ *   but forces the default comma separator (a custom separator combined
+ *   with DISTINCT is not supported by SQLite) — this also throws if both
+ *   `distinct` and a non-default delimiter are requested together.
+ *
+ * - **PostgreSQL / CockroachDB**: `STRING_AGG([DISTINCT] expr, 'delim' [ORDER BY col [ASC|DESC]])`
+ *   — the ORDER BY clause sits *inside* the same parentheses as the
+ *   delimiter argument (no WITHIN GROUP).
+ *
+ * - **MSSQL**: `STRING_AGG(expr, 'delim') WITHIN GROUP (ORDER BY col [ASC|DESC])`
+ *   — note this is a genuinely different clause *placement* than Postgres:
+ *   the ORDER BY is a separate `WITHIN GROUP (...)` clause appended after
+ *   the function call, not inline inside the argument list. MSSQL's
+ *   `STRING_AGG` also does **not** support a `DISTINCT` argument at all
+ *   (unlike Postgres) — this throws if `distinct: true` is requested.
+ *
+ * - **Oracle / Db2**: `LISTAGG([DISTINCT] expr, 'delim') WITHIN GROUP (ORDER BY col [ASC|DESC])`
+ *   — same WITHIN GROUP placement as MSSQL. Oracle supports `DISTINCT`
+ *   inside LISTAGG since 19c; Db2 LUW's LISTAGG also supports `DISTINCT`.
+ *
+ * - **Redshift**: `LISTAGG([DISTINCT] expr, 'delim') WITHIN GROUP (ORDER BY col [ASC|DESC])`
+ *   — Redshift's aggregate string function has always been `LISTAGG`
+ *   (matching Oracle/Db2 syntax), not `STRING_AGG`. AWS did add a
+ *   Postgres-compatible `STRING_AGG` alias to Redshift more recently, but
+ *   `LISTAGG` is the long-standing, universally-available, and
+ *   ORDER-BY-capable form, so it's used here for correctness.
+ *
+ * - **Snowflake**: `LISTAGG([DISTINCT] expr, 'delim') WITHIN GROUP (ORDER BY col [ASC|DESC])`
+ *   — Snowflake's string aggregation function is `LISTAGG` (Oracle-style),
+ *   *not* `STRING_AGG` — Snowflake has no `STRING_AGG` function.
+ *
+ * - **ClickHouse**: no native `GROUP_CONCAT`/`STRING_AGG`/`LISTAGG`. The
+ *   verified, version-portable idiom is
+ *   `arrayStringConcat(groupArray(expr), 'delim')` (distinct:
+ *   `arrayStringConcat(groupUniqArray(expr), 'delim')`). Newer ClickHouse
+ *   releases (24.x+) also ship a MySQL-compatible `groupConcat(expr)`
+ *   function, but `arrayStringConcat(groupArray(...), ...)` works on every
+ *   supported version so it's used as the default here. ClickHouse's
+ *   `groupArray` has no inline `ORDER BY` sub-clause (it preserves block
+ *   processing order, not a guaranteed sort) — `options.orderBy` therefore
+ *   throws for ClickHouse; pre-sort via a subquery if ordering matters.
+ */
+function stringAgg(dialect, expr, delimiter, options = {}) {
+    const { orderBy, distinct } = options;
+    const exprSql = toSqlFragment(expr);
+    const delimSql = escapeStringLiteral(delimiter);
+    switch (dialect) {
+        case 'mysql':
+        case 'mariadb': {
+            const parts = [];
+            if (distinct)
+                parts.push('DISTINCT');
+            parts.push(exprSql);
+            let sql = `GROUP_CONCAT(${parts.join(' ')}`;
+            if (orderBy) {
+                sql += ` ORDER BY ${renderOrderByList(orderBy)}`;
+            }
+            sql += ` SEPARATOR ${delimSql})`;
+            return (0, operators_1.literalExpr)(sql);
+        }
+        case 'sqlite': {
+            if (orderBy) {
+                unsupported('stringAgg', dialect, "SQLite's GROUP_CONCAT does not support an ORDER BY clause; pre-sort via a subquery instead");
+            }
+            if (distinct) {
+                if (delimiter !== ',') {
+                    unsupported('stringAgg', dialect, 'SQLite GROUP_CONCAT(DISTINCT ...) only supports the default comma separator, not a custom delimiter');
+                }
+                return (0, operators_1.literalExpr)(`GROUP_CONCAT(DISTINCT ${exprSql})`);
+            }
+            return (0, operators_1.literalExpr)(`GROUP_CONCAT(${exprSql}, ${delimSql})`);
+        }
+        case 'postgres':
+        case 'cockroachdb': {
+            const argSql = distinct ? `DISTINCT ${exprSql}` : exprSql;
+            let sql = `STRING_AGG(${argSql}, ${delimSql}`;
+            if (orderBy) {
+                sql += ` ORDER BY ${renderOrderByList(orderBy)}`;
+            }
+            sql += ')';
+            return (0, operators_1.literalExpr)(sql);
+        }
+        case 'mssql': {
+            if (distinct) {
+                unsupported('stringAgg', dialect, 'MSSQL STRING_AGG does not support DISTINCT');
+            }
+            let sql = `STRING_AGG(${exprSql}, ${delimSql})`;
+            if (orderBy) {
+                sql += ` WITHIN GROUP (ORDER BY ${renderOrderByList(orderBy)})`;
+            }
+            return (0, operators_1.literalExpr)(sql);
+        }
+        case 'oracle':
+        case 'db2':
+        case 'redshift':
+        case 'snowflake': {
+            const argSql = distinct ? `DISTINCT ${exprSql}` : exprSql;
+            let sql = `LISTAGG(${argSql}, ${delimSql})`;
+            if (orderBy) {
+                sql += ` WITHIN GROUP (ORDER BY ${renderOrderByList(orderBy)})`;
+            }
+            return (0, operators_1.literalExpr)(sql);
+        }
+        case 'clickhouse': {
+            if (orderBy) {
+                unsupported('stringAgg', dialect, "ClickHouse's groupArray()/arrayStringConcat() has no inline ORDER BY; pre-sort via a subquery instead");
+            }
+            const arrayFn = distinct ? 'groupUniqArray' : 'groupArray';
+            return (0, operators_1.literalExpr)(`arrayStringConcat(${arrayFn}(${exprSql}), ${delimSql})`);
+        }
+        default: {
+            // Exhaustiveness guard for future Dialect additions.
+            throw new Error(`stringAgg(): unhandled dialect "${dialect}"`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// arrayAgg
+// ---------------------------------------------------------------------------
+/**
+ * Aggregate values into an array/JSON-array, dispatched per-dialect.
+ *
+ * - **PostgreSQL / CockroachDB**: native `ARRAY_AGG([DISTINCT] expr [ORDER BY col [ASC|DESC]])`.
+ * - **Snowflake**: native `ARRAY_AGG([DISTINCT] expr) [WITHIN GROUP (ORDER BY col [ASC|DESC])]`
+ *   — Snowflake's ARRAY_AGG uses the same WITHIN GROUP placement as LISTAGG,
+ *   not Postgres's inline ORDER BY.
+ * - **ClickHouse**: native `groupArray(expr)` (distinct: `groupUniqArray(expr)`);
+ *   returns ClickHouse's native Array(T) type. No inline ORDER BY support
+ *   (same limitation as `stringAgg`) — throws if `orderBy` is requested.
+ * - **MySQL (5.7.22+) / MariaDB (10.5+)**: no `ARRAY_AGG`, but both support
+ *   the real `JSON_ARRAYAGG(expr)` function, used here as a JSON-array
+ *   fallback. Neither dialect's `JSON_ARRAYAGG` supports `DISTINCT` or
+ *   `ORDER BY` — both throw if requested.
+ * - **Oracle (12.2+) / Db2 (11.5+)**: no `ARRAY_AGG`, but both support the
+ *   real SQL:2016 `JSON_ARRAYAGG(expr)` function, used as a JSON-array
+ *   fallback here too. `DISTINCT`/`ORDER BY` throw (not supported by either
+ *   engine's JSON_ARRAYAGG).
+ * - **SQLite**: no `ARRAY_AGG`, but has the real native `json_group_array(expr)`
+ *   aggregate, used as the fallback. `DISTINCT`/`ORDER BY` throw (not
+ *   supported by SQLite's json_group_array).
+ * - **MSSQL / Redshift**: no real array-aggregation concept and no reliable
+ *   scalar-aggregate JSON-array equivalent (MSSQL's JSON array construction
+ *   is via `FOR JSON PATH` on a full query shape, not an aggregate function
+ *   usable inline in a SELECT list; Redshift has no JSON_ARRAYAGG). Both
+ *   throw a clear "not supported" error rather than faking an unreliable
+ *   workaround.
+ */
+function arrayAgg(dialect, expr, options = {}) {
+    const { orderBy, distinct } = options;
+    const exprSql = toSqlFragment(expr);
+    switch (dialect) {
+        case 'postgres':
+        case 'cockroachdb': {
+            const argSql = distinct ? `DISTINCT ${exprSql}` : exprSql;
+            let sql = `ARRAY_AGG(${argSql}`;
+            if (orderBy) {
+                sql += ` ORDER BY ${renderOrderByList(orderBy)}`;
+            }
+            sql += ')';
+            return (0, operators_1.literalExpr)(sql);
+        }
+        case 'snowflake': {
+            const argSql = distinct ? `DISTINCT ${exprSql}` : exprSql;
+            let sql = `ARRAY_AGG(${argSql})`;
+            if (orderBy) {
+                sql += ` WITHIN GROUP (ORDER BY ${renderOrderByList(orderBy)})`;
+            }
+            return (0, operators_1.literalExpr)(sql);
+        }
+        case 'clickhouse': {
+            if (orderBy) {
+                unsupported('arrayAgg', dialect, "ClickHouse's groupArray() has no inline ORDER BY; pre-sort via a subquery instead");
+            }
+            const arrayFn = distinct ? 'groupUniqArray' : 'groupArray';
+            return (0, operators_1.literalExpr)(`${arrayFn}(${exprSql})`);
+        }
+        case 'mysql':
+        case 'mariadb': {
+            if (distinct || orderBy) {
+                unsupported('arrayAgg', dialect, `${dialect === 'mysql' ? 'MySQL' : 'MariaDB'}'s JSON_ARRAYAGG (used as the ARRAY_AGG fallback) does not support DISTINCT or ORDER BY`);
+            }
+            return (0, operators_1.literalExpr)(`JSON_ARRAYAGG(${exprSql})`);
+        }
+        case 'oracle':
+        case 'db2': {
+            if (distinct || orderBy) {
+                unsupported('arrayAgg', dialect, `${dialect === 'oracle' ? 'Oracle' : 'Db2'}'s JSON_ARRAYAGG (used as the ARRAY_AGG fallback) does not support DISTINCT or ORDER BY`);
+            }
+            return (0, operators_1.literalExpr)(`JSON_ARRAYAGG(${exprSql})`);
+        }
+        case 'sqlite': {
+            if (distinct || orderBy) {
+                unsupported('arrayAgg', dialect, "SQLite's json_group_array (used as the ARRAY_AGG fallback) does not support DISTINCT or ORDER BY");
+            }
+            return (0, operators_1.literalExpr)(`json_group_array(${exprSql})`);
+        }
+        case 'mssql':
+            unsupported('arrayAgg', dialect, 'MSSQL has no ARRAY_AGG or scalar JSON-array aggregate function usable in a SELECT list (FOR JSON PATH operates on whole query shapes, not individual aggregate expressions)');
+        case 'redshift':
+            unsupported('arrayAgg', dialect, 'Redshift has no ARRAY_AGG and no JSON_ARRAYAGG equivalent');
+        default: {
+            // Exhaustiveness guard for future Dialect additions.
+            throw new Error(`arrayAgg(): unhandled dialect "${dialect}"`);
+        }
+    }
+}