typeorm-extensions 2.0.0 → 2.2.0-rc.0

package/dist/utils/table.utils.js

@@ -2,18 +2,106 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tableHelper = void 0;
 const sql_utils_1 = require("./sql.utils");
-/** Wraps a JSON key in single quotes, doubling any quote inside it (standard SQL string literal). */
-function toJsonKeyLiteral(fieldName) {
-    return `'${String(fieldName).replace(/'/g, "''")}'`;
+const json_path_utils_1 = require("./json-path.utils");
+/**
+ * The argument of an aggregate and the clause after it for a `filter` written with `syntax`:
+ * `CASE WHEN filter THEN argument END`, or `argument` and ` FILTER (WHERE filter)`.
+ */
+function filtered(method, argument, filter, syntax = 'case', driver) {
+    if (syntax !== 'case' && syntax !== 'filter') {
+        throw new TypeError(`tableHelper.${method}(): syntax is 'case' or 'filter', got "${String(syntax)}"`);
+    }
+    if (filter && syntax === 'filter' && (0, sql_utils_1.isMysqlLikeDriver)(driver)) {
+        throw new TypeError(`tableHelper.${method}(): MySQL / MariaDB have no FILTER (WHERE …), use syntax 'case'`);
+    }
+    if (!filter) {
+        return { argument, suffix: '' };
+    }
+    return syntax === 'case'
+        ? { argument: `CASE WHEN ${filter} THEN ${argument} END`, suffix: '' }
+        : { argument, suffix: ` FILTER (WHERE ${filter})` };
+}
+/** `orderBy` of an aggregate: its column, and the SQL after the argument, ` ORDER BY column [direction]`. */
+function aggregateOrder(method, orderBy, toSql) {
+    const [column, direction] = (typeof orderBy === 'string' ? [orderBy] : orderBy);
+    if (direction !== undefined && direction !== 'ASC' && direction !== 'DESC') {
+        throw new TypeError(`tableHelper.${method}(): the order is 'ASC' or 'DESC', got "${String(direction)}"`);
+    }
+    return { column, sql: ` ORDER BY ${toSql(column)}${direction ? ` ${direction}` : ''}` };
 }
-function buildJsonPath(fieldNames, jsonOperator) {
-    let result = '';
-    for (let i = 0; i < fieldNames.length; i++) {
-        const op = i === fieldNames.length - 1 ? jsonOperator : '->';
-        result += `${result ? ' ' : ''}${op} ${toJsonKeyLiteral(fieldNames[i])}`;
+const DATE_TRUNC_UNITS = [
+    'microseconds',
+    'milliseconds',
+    'second',
+    'minute',
+    'hour',
+    'day',
+    'week',
+    'month',
+    'quarter',
+    'year',
+    'decade',
+    'century',
+    'millennium',
+];
+function assertPostgres(method, driver) {
+    if (driver !== undefined && !(0, sql_utils_1.isPostgresLikeDriver)(driver)) {
+        throw new TypeError(`tableHelper.${method}(): PostgreSQL only, the driver is "${driver}"`);
     }
-    return result;
 }
+function toExpression(value, toColumn) {
+    return typeof value === 'string' ? toColumn(value) : value.sql;
+}
+function toTimeZone(method, timeZone, toColumn) {
+    if (typeof timeZone === 'string') {
+        if (!timeZone.trim()) {
+            throw new TypeError(`tableHelper.${method}(): the time zone is empty`);
+        }
+        return sqlString(toPostgresZone(timeZone));
+    }
+    if ('sql' in timeZone) {
+        return timeZone.sql;
+    }
+    const column = toColumn(timeZone.column);
+    return timeZone.fallback === undefined
+        ? column
+        : `COALESCE(${column}, ${sqlString(toPostgresZone(timeZone.fallback))})`;
+}
+const ISO_OFFSET = /^([+-])(\d{2}):?(\d{2})?$/;
+/**
+ * PostgreSQL reads `'+02:00'` as a POSIX zone, whose offsets count west: UTC−2. An ISO 8601 offset is
+ * written as the POSIX zone of the same offset, `'<+0200>-02:00'`, so `'+02:00'` is UTC+2 as everywhere else.
+ */
+function toPostgresZone(timeZone) {
+    const offset = ISO_OFFSET.exec(timeZone.trim());
+    if (offset === null) {
+        return timeZone;
+    }
+    const [, sign, hours, minutes = '00'] = offset;
+    return `<${sign}${hours}${minutes}>${sign === '+' ? '-' : '+'}${hours}:${minutes}`;
+}
+/** The JSON functions of a database: PostgreSQL's unless the driver is MySQL / MariaDB or SQLite. */
+function jsonFunctions(driver, jsonb) {
+    const mysql = (0, sql_utils_1.isMysqlLikeDriver)(driver);
+    if (jsonb && (mysql || (0, sql_utils_1.isSqliteLikeDriver)(driver))) {
+        throw new TypeError(`tableHelper: jsonb is PostgreSQL's, the driver is "${driver}"`);
+    }
+    if (mysql) {
+        return { mysql, object: 'JSON_OBJECT', agg: 'JSON_ARRAYAGG', emptyArray: 'JSON_ARRAY()' };
+    }
+    if ((0, sql_utils_1.isSqliteLikeDriver)(driver)) {
+        return { mysql, object: 'json_object', agg: 'json_group_array', emptyArray: 'json_array()' };
+    }
+    // PostgreSQL's when no driver is given; SQL Server, Oracle and the rest have functions of their own
+    if (driver !== undefined && !(0, sql_utils_1.isPostgresLikeDriver)(driver)) {
+        throw new TypeError(`tableHelper: the JSON functions are PostgreSQL's, MySQL / MariaDB's and SQLite's, the driver is "${driver}"`);
+    }
+    const type = jsonb ? 'jsonb' : 'json';
+    // CAST, not `::json`: TypeORM would read `:json` as a parameter
+    return { mysql, object: `${type}_build_object`, agg: `${type}_agg`, emptyArray: `CAST('[]' AS ${type})` };
+}
+// MySQL reads a backslash in a string as an escape (unless NO_BACKSLASH_ESCAPES): `\'` would end the literal
+const sqlString = (value, driver) => `'${((0, sql_utils_1.isMysqlLikeDriver)(driver) ? value.replace(/\\/g, '\\\\') : value).replace(/'/g, "''")}'`;
 /**
  * Creates a type-safe SQL helper for building column references, WHERE expressions,
  * JOIN clauses, and JSONB accessors for a given entity type.
@@ -31,13 +119,13 @@ const tableHelper = (alias, options = {}) => ({
      * identifier, so names with other characters work too: `"user"."first-name"`.
      */
     column(columnName, alias) {
-        const { useQuotes = true } = options;
+        const { useQuotes = true, driver } = options;
         const tableAlias = alias !== null && alias !== void 0 ? alias : this.alias;
         const column = String(columnName);
         if (!useQuotes) {
             return [tableAlias, column].filter(Boolean).join('.');
         }
-        return [tableAlias ? (0, sql_utils_1.quoteIdentifierPath)(tableAlias) : undefined, (0, sql_utils_1.quoteIdentifier)(column)]
+        return [tableAlias ? (0, sql_utils_1.quoteIdentifierPath)(tableAlias, driver) : undefined, (0, sql_utils_1.quoteIdentifier)(column, driver)]
             .filter(Boolean)
             .join('.');
     },
@@ -72,7 +160,8 @@ const tableHelper = (alias, options = {}) => ({
         return this.where(columnName, 'IS NOT NULL');
     },
     /**
-     * Returns `CAST(COUNT("alias"."column") AS integer)`: the rows where the column isn't `NULL`.
+     * Returns `CAST(COUNT("alias"."column") AS integer)`: the rows where the column isn't `NULL`. With the `driver` option
+     * MySQL casts `AS SIGNED`, a `BIGINT`, which its TypeORM driver returns as a string by default.
      * Without a column it is `COUNT(*)`, all the rows of the result, in every database. To count the rows
      * of a table joined with LEFT JOIN, count one of its non-null columns: `images.count('id')`.
      * @example
@@ -87,21 +176,85 @@ const tableHelper = (alias, options = {}) => ({
             throw new TypeError('tableHelper.count(): the second argument is an options object, e.g. { distinct: true } or { filter: "…" }');
         }
         const { distinct = false, filter, syntax = 'case' } = countOptions;
-        if (syntax !== 'case' && syntax !== 'filter') {
-            throw new TypeError(`tableHelper.count(): syntax is 'case' or 'filter', got "${String(syntax)}"`);
-        }
         const column = columnName ? this.column(columnName) : undefined;
         if (distinct && !column) {
             throw new TypeError("tableHelper.count({ distinct: true }) needs a column, e.g. count('email', { distinct: true })");
         }
         // `COUNT(*)`, not `COUNT("alias".*)`, which only PostgreSQL accepts;
         // a CASE can't return `*`: without a column, it counts 1 per matching row
-        const counted = filter && syntax === 'case' ? `CASE WHEN ${filter} THEN ${column !== null && column !== void 0 ? column : '1'} END` : column !== null && column !== void 0 ? column : '*';
-        let expression = `COUNT(${distinct ? 'DISTINCT ' : ''}${counted})`;
-        if (filter && syntax === 'filter') {
-            expression += ` FILTER (WHERE ${filter})`;
+        const { argument, suffix } = filtered('count', column !== null && column !== void 0 ? column : (filter && syntax === 'case' ? '1' : '*'), filter, syntax, options.driver);
+        // `CAST(… AS integer)` is a syntax error on MySQL
+        return this.cast(`COUNT(${distinct ? 'DISTINCT ' : ''}${argument})${suffix}`, (0, sql_utils_1.isMysqlLikeDriver)(options.driver) ? 'SIGNED' : 'integer');
+    },
+    /**
+     * Returns `COALESCE(SUM("alias"."column"), 0)`: 0, not `NULL`, for a group without rows or a LEFT JOIN
+     * without a match. Only a column whose property is a number. PostgreSQL sums integers into a `bigint`
+     * and MySQL into a `DECIMAL`, which the drivers return as strings.
+     * @example
+     * t.sum('amountCents', { filter: t.where('status', "= 'paid'") })
+     * // COALESCE(SUM(CASE WHEN "order"."status" = 'paid' THEN "order"."amountCents" END), 0)
+     */
+    sum(columnName, sumOptions = {}) {
+        const { argument, suffix } = filtered('sum', this.column(columnName), sumOptions.filter, sumOptions.syntax, options.driver);
+        return `COALESCE(SUM(${argument})${suffix}, 0)`;
+    },
+    /**
+     * Returns the PostgreSQL array of a column over the rows of a group, `{}` for a group without rows.
+     * Other databases have no arrays and throw a `TypeError`: use `jsonAgg` there.
+     * @example
+     * images.arrayAgg('id', { distinct: true, orderBy: ['id', 'DESC'], filter: images.isNotNull('id') })
+     * // COALESCE(array_agg(DISTINCT "image"."id" ORDER BY "image"."id" DESC) FILTER (WHERE "image"."id" IS NOT NULL), '{}')
+     */
+    arrayAgg(columnName, aggOptions = {}) {
+        var _a;
+        const { distinct = false, orderBy, filter } = aggOptions;
+        if (options.driver !== undefined && !(0, sql_utils_1.isPostgresLikeDriver)(options.driver)) {
+            throw new TypeError(`tableHelper.arrayAgg(): arrays are PostgreSQL's, the driver is "${options.driver}": use jsonAgg`);
+        }
+        const order = orderBy ? aggregateOrder('arrayAgg', orderBy, (column) => this.column(column)) : undefined;
+        // PostgreSQL: "in an aggregate with DISTINCT, ORDER BY expressions must appear in argument list"
+        if (distinct && order && order.column !== columnName) {
+            throw new TypeError(`tableHelper.arrayAgg(): with distinct, the array can only be ordered by "${columnName}", got "${order.column}"`);
         }
-        return this.cast(expression, 'integer');
+        const aggregate = `array_agg(${distinct ? 'DISTINCT ' : ''}${this.column(columnName)}${(_a = order === null || order === void 0 ? void 0 : order.sql) !== null && _a !== void 0 ? _a : ''})`;
+        // the untyped '{}' takes the type of the array
+        return `COALESCE(${aggregate}${filter ? ` FILTER (WHERE ${filter})` : ''}, '{}')`;
+    },
+    /**
+     * Returns a JSON object of columns, keyed by the column names or by the keys of a `{ key: column }` map.
+     * Every column is checked against the entity type.
+     * @example
+     * t.jsonBuildObject(['id', 'url'])              // json_build_object('id', "image"."id", 'url', "image"."url")
+     * t.jsonBuildObject({ imageId: 'id', src: 'url' }) // json_build_object('imageId', "image"."id", 'src', "image"."url")
+     * // MySQL: JSON_OBJECT(…), SQLite: json_object(…); { jsonb: true }: jsonb_build_object(…)
+     */
+    jsonBuildObject(columns, jsonOptions = {}) {
+        const entries = Array.isArray(columns)
+            ? columns.map((column) => [column, column])
+            : Object.entries(columns);
+        if (!entries.length) {
+            throw new TypeError('tableHelper.jsonBuildObject() needs at least one column');
+        }
+        const pairs = entries.map(([key, column]) => `${sqlString(key, options.driver)}, ${this.column(column)}`);
+        return `${jsonFunctions(options.driver, jsonOptions.jsonb).object}(${pairs.join(', ')})`;
+    },
+    /**
+     * Returns the JSON array of an expression over the rows of a group, `[]` for a group without rows
+     * (the aggregate alone gives `NULL` there). Use it with GROUP BY, or in a subquery.
+     * @example
+     * images.jsonAgg(images.jsonBuildObject(['id', 'url']), { orderBy: ['id', 'DESC'], filter: images.isNotNull('id') })
+     * // COALESCE(json_agg(json_build_object(…) ORDER BY "image"."id" DESC) FILTER (WHERE "image"."id" IS NOT NULL), CAST('[]' AS json))
+     * // MySQL: COALESCE(JSON_ARRAYAGG(…), JSON_ARRAY()), without ORDER BY and FILTER; SQLite: json_group_array(…)
+     */
+    jsonAgg(expression, aggOptions = {}) {
+        const { orderBy, filter, jsonb } = aggOptions;
+        const json = jsonFunctions(options.driver, jsonb);
+        if (json.mysql && (orderBy || filter)) {
+            throw new TypeError("tableHelper.jsonAgg(): MySQL's JSON_ARRAYAGG takes no ORDER BY and no FILTER");
+        }
+        const order = orderBy ? aggregateOrder('jsonAgg', orderBy, (column) => this.column(column)).sql : '';
+        const aggregate = `${json.agg}(${expression}${order})${filter ? ` FILTER (WHERE ${filter})` : ''}`;
+        return `COALESCE(${aggregate}, ${json.emptyArray})`;
     },
     /** Returns `CAST(expression AS type)`. */
     cast(expression, type) {
@@ -115,7 +268,7 @@ const tableHelper = (alias, options = {}) => ({
      */
     jsonColumn(columnName, jsonOperator, ...fieldNames) {
         const column = this.column(columnName);
-        const path = buildJsonPath(fieldNames, jsonOperator);
+        const path = (0, json_path_utils_1.buildJsonPath)(fieldNames, jsonOperator);
         return `${column} ${path}`;
     },
     /**
@@ -129,7 +282,38 @@ const tableHelper = (alias, options = {}) => ({
      * qb.whereTyped(u => u.metadata, `${t.jsonPath('metadata', '->>', 'role')} =`, 'admin')
      */
     jsonPath(_columnName, jsonOperator, ...fieldNames) {
-        return buildJsonPath(fieldNames, jsonOperator);
+        return (0, json_path_utils_1.buildJsonPath)(fieldNames, jsonOperator);
+    },
+    /**
+     * Returns `(expression AT TIME ZONE zone)` (PostgreSQL). A `timestamptz` gives the wall-clock `timestamp`
+     * in that zone; a `timestamp` is read as wall-clock time there and gives a `timestamptz`.
+     * A zone name is written as an escaped literal, so it is safe to take from a request.
+     * @example
+     * t.atTimeZone('paidAt', 'Europe/Kyiv')                              // ("order"."paidAt" AT TIME ZONE 'Europe/Kyiv')
+     * t.atTimeZone('startsAt', { column: 'timezone', fallback: 'UTC' }) // ("order"."startsAt" AT TIME ZONE COALESCE("order"."timezone", 'UTC'))
+     */
+    atTimeZone(value, timeZone) {
+        assertPostgres('atTimeZone', options.driver);
+        const toColumn = (column) => this.column(column);
+        return `(${toExpression(value, toColumn)} AT TIME ZONE ${toTimeZone('atTimeZone', timeZone, toColumn)})`;
+    },
+    /**
+     * Returns `date_trunc('unit', expression)` (PostgreSQL). With a time zone it is the three-argument form
+     * (PostgreSQL 12+): a `timestamptz` is truncated at the boundaries of that zone, e.g. its local midnight
+     * for `'day'`, and the result is a `timestamptz` again.
+     * @example
+     * t.dateTrunc('day', 'paidAt')                // date_trunc('day', "order"."paidAt")
+     * t.dateTrunc('day', 'paidAt', 'Europe/Kyiv') // date_trunc('day', "order"."paidAt", 'Europe/Kyiv')
+     */
+    dateTrunc(unit, value, timeZone) {
+        assertPostgres('dateTrunc', options.driver);
+        // the unit goes into the SQL as is
+        if (!DATE_TRUNC_UNITS.includes(unit)) {
+            throw new TypeError(`tableHelper.dateTrunc(): the unit is one of ${DATE_TRUNC_UNITS.join(', ')}, got "${String(unit)}"`);
+        }
+        const toColumn = (column) => this.column(column);
+        const zone = timeZone === undefined ? '' : `, ${toTimeZone('dateTrunc', timeZone, toColumn)}`;
+        return `date_trunc('${unit}', ${toExpression(value, toColumn)}${zone})`;
     }
 });
 exports.tableHelper = tableHelper;

package/dist/utils/time-zone.utils.d.ts

@@ -0,0 +1,8 @@
+/** Throws a `TypeError` for a time zone the runtime doesn't know. */
+export declare function assertTimeZone(timeZone: string): void;
+/**
+ * Reads a date (`'2024-01-31'`, its midnight) or a date-time without an offset (`'2024-01-31 10:00'`) as
+ * the wall clock of `timeZone`, and returns that instant. A date-time with an offset (`Z`, `+02:00`) is an
+ * instant already: it is returned as that `Date`. Any other string throws a `TypeError` naming `name`.
+ */
+export declare function readInTimeZone(value: string, timeZone: string, name: string): Date;

package/dist/utils/time-zone.utils.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readInTimeZone = exports.assertTimeZone = void 0;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MAX_CACHED_FORMATTERS = 500;
+const DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}(?::?\d{2})?)?)?$/i;
+const OFFSET = /^([+-])(\d{2}):?(\d{2})?$/;
+const formatters = new Map();
+function getFormatter(timeZone) {
+    let formatter = formatters.get(timeZone);
+    if (formatter === undefined) {
+        try {
+            formatter = new Intl.DateTimeFormat('en-US', {
+                timeZone,
+                hour12: false,
+                era: 'short',
+                year: 'numeric',
+                month: 'numeric',
+                day: 'numeric',
+                hour: 'numeric',
+                minute: 'numeric',
+                second: 'numeric',
+            });
+        }
+        catch {
+            throw new TypeError(`Invalid timeZone "${timeZone}": not an IANA time zone`);
+        }
+        // the keys are caller input: Intl accepts any letter case of a zone name
+        if (formatters.size >= MAX_CACHED_FORMATTERS) {
+            formatters.clear();
+        }
+        formatters.set(timeZone, formatter);
+    }
+    return formatter;
+}
+/** The wall clock of an instant in a time zone, as milliseconds of the same wall clock in UTC. */
+function getWallClock(instant, timeZone) {
+    const parts = {};
+    for (const { type, value } of getFormatter(timeZone).formatToParts(new Date(instant))) {
+        parts[type] = value;
+    }
+    const year = parts.era === 'BC' ? 1 - Number(parts.year) : Number(parts.year);
+    const wallClock = new Date(0);
+    // some ICU versions write midnight as 24 with hour12: false
+    wallClock.setUTCFullYear(year, Number(parts.month) - 1, Number(parts.day));
+    wallClock.setUTCHours(Number(parts.hour) % 24, Number(parts.minute), Number(parts.second), 0);
+    return wallClock.getTime() + (((instant % 1000) + 1000) % 1000);
+}
+/**
+ * The instant at which the wall clock of a time zone shows `wallClock` (milliseconds of that wall clock in
+ * UTC). Like PostgreSQL: a time skipped by a forward transition takes the offset before it, and a time that
+ * occurs twice is read with the offset after the transition, the later of the two instants.
+ */
+function wallClockToInstant(wallClock, timeZone) {
+    const offsets = new Set([wallClock - DAY_MS, wallClock, wallClock + DAY_MS].map((instant) => getWallClock(instant, timeZone) - instant));
+    const candidates = [...offsets].map((offset) => wallClock - offset);
+    const matching = candidates.filter((instant) => getWallClock(instant, timeZone) === wallClock);
+    return Math.max(...(matching.length > 0 ? matching : candidates));
+}
+/** Throws a `TypeError` for a time zone the runtime doesn't know. */
+function assertTimeZone(timeZone) {
+    getFormatter(timeZone);
+}
+exports.assertTimeZone = assertTimeZone;
+/**
+ * Reads a date (`'2024-01-31'`, its midnight) or a date-time without an offset (`'2024-01-31 10:00'`) as
+ * the wall clock of `timeZone`, and returns that instant. A date-time with an offset (`Z`, `+02:00`) is an
+ * instant already: it is returned as that `Date`. Any other string throws a `TypeError` naming `name`.
+ */
+function readInTimeZone(value, timeZone, name) {
+    const match = DATE_TIME.exec(value);
+    if (match === null) {
+        throw new TypeError(`Invalid ${name} "${value}": with timeZone, expected a Date, a date (YYYY-MM-DD) or a date-time ` +
+            '(YYYY-MM-DD HH:mm[:ss[.sss]]) with or without an offset');
+    }
+    const [, year, month, day, hour = '0', minute = '0', second = '0', fraction = '', offset] = match;
+    const wallClock = new Date(0);
+    wallClock.setUTCFullYear(Number(year), Number(month) - 1, Number(day));
+    // a Date keeps milliseconds: finer fractions are dropped
+    wallClock.setUTCHours(Number(hour), Number(minute), Number(second), Number(fraction.padEnd(3, '0').slice(0, 3)));
+    const roundTrip = wallClock.toISOString();
+    const expected = `${year}-${month}-${day}T${hour.padStart(2, '0')}:${minute.padStart(2, '0')}:${second.padStart(2, '0')}`;
+    if (isNaN(wallClock.getTime()) || roundTrip.slice(0, 19) !== expected) {
+        throw new TypeError(`Invalid ${name} "${value}": not a calendar date and time`);
+    }
+    if (offset === undefined) {
+        return new Date(wallClockToInstant(wallClock.getTime(), timeZone));
+    }
+    // an offset makes it an instant already; as text the databases would read it each their own way
+    return new Date(wallClock.getTime() - getOffsetMinutes(offset, value, name) * 60000);
+}
+exports.readInTimeZone = readInTimeZone;
+function getOffsetMinutes(offset, value, name) {
+    if (offset.toUpperCase() === 'Z') {
+        return 0;
+    }
+    const [, sign, hours, minutes = '00'] = OFFSET.exec(offset);
+    if (Number(hours) > 23 || Number(minutes) > 59) {
+        throw new TypeError(`Invalid ${name} "${value}": not a UTC offset`);
+    }
+    return (sign === '-' ? -1 : 1) * (Number(hours) * 60 + Number(minutes));
+}

package/dist/utils/where.utils.d.ts

@@ -1,5 +1,5 @@
 import type { ObjectLiteral, WhereExpressionBuilder } from 'typeorm';
-import type { WhereMethods } from '../types/extensions/where.types';
+import type { HavingMethods, WhereMethods } from '../types/extensions/where.types';
 export declare function getValuePlaceholder<T>(value: T, paramName?: string): string;
 /**
  * Whether `params` is a `{ name: value }` params object (a plain object or a class instance such
@@ -12,7 +12,7 @@ export declare function isParamsObject(params: unknown): params is Record<string
  * so `::type` casts and colons inside literals don't count unless they name a `params` key.
  */
 export declare function hasParamPlaceholder(conditions: string, params?: unknown): boolean;
-export declare function attachWhere<QB extends WhereExpressionBuilder>(builder: QB, method: WhereMethods, field: string, conditions: string, params?: unknown, options?: {
+export declare function attachWhere<QB extends WhereExpressionBuilder>(builder: QB, method: WhereMethods | HavingMethods, field: string, conditions: string, params?: unknown, options?: {
     addValue?: boolean;
 }): QB;
 /**

package/dist/utils/where.utils.js

@@ -49,14 +49,35 @@ function hasParamPlaceholder(conditions, params) {
     return false;
 }
 exports.hasParamPlaceholder = hasParamPlaceholder;
+/**
+ * A params object whose value goes after the condition (`'='`, `{ id: 1 }`) holds that one value. With other
+ * keys only the first was used and the rest dropped; with none the column was compared with NULL.
+ */
+function assertSingleValueParams(field, params) {
+    if (!isParamsObject(params)) {
+        return;
+    }
+    const keys = Object.keys(params);
+    if (keys.length !== 1) {
+        throw new TypeError(`Condition on "${field}": a params object without a placeholder in the condition holds the one value to compare with, ` +
+            `got ${keys.length} keys (${keys.join(', ') || 'none'}). Pass the value itself, or name the keys in the condition: '= :id'`);
+    }
+}
+/** The builder's `where` / `having` method, bound to it: only a SelectQueryBuilder has `having`. */
+function addCondition(builder, method) {
+    const add = builder[method];
+    return (condition, parameters) => add.call(builder, condition, parameters);
+}
 function attachWhere(builder, method, field, conditions, params, options) {
     let { addValue } = options || {};
     if (method && typeof field === 'string' && typeof conditions === 'string') {
+        const fieldName = field;
         field = (0, query_builder_utils_1.toFieldSql)(builder, field);
         const hasParams = typeof params !== 'undefined';
         // `addValue` defaults to `true` unless `conditions` already references one of the `params` keys
         addValue = addValue !== null && addValue !== void 0 ? addValue : !hasParamPlaceholder(conditions, params);
         if (addValue && hasParams) {
+            assertSingleValueParams(fieldName, params);
             // pick first value from params object or pass as is (a Date or a Buffer is a value too)
             const firstValue = isParamsObject(params) ? Object.values(params)[0] : params;
             // 0, false, '' are valid values like any other
@@ -69,10 +90,10 @@ function attachWhere(builder, method, field, conditions, params, options) {
                 : undefined;
             const queryParams = paramName && valueIsValid ? { [paramName]: firstValue } : undefined;
             const valuePlaceholder = getValuePlaceholder(firstValue, paramName);
-            return builder[method](`${field} ${conditions} ${valuePlaceholder}`, queryParams);
+            return addCondition(builder, method)(`${field} ${conditions} ${valuePlaceholder}`, queryParams);
         }
         else {
-            return builder[method](`${field} ${conditions}`, params);
+            return addCondition(builder, method)(`${field} ${conditions}`, params);
         }
     }
     return builder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeorm-extensions",
-  "version": "2.0.0",
+  "version": "2.2.0-rc.0",
   "description": "typeorm commonly used extensions",
   "main": "./dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,8 @@
   },
   "scripts": {
     "build": "tsc -p .",
-    "lint": "eslint . --ext .ts"
+    "lint": "eslint . --ext .ts",
+    "test:types": "tsc -p test/types"
   },
   "keywords": [
     "typeorm",
@@ -23,7 +24,7 @@
     "utils"
   ],
   "author": "koenigstag",
-  "license": "ISC",
+  "license": "MIT",
   "peerDependencies": {
     "typeorm": "^0.3.12 || ^1.0.0"
   },