typeorm-extensions 1.3.4 → 2.0.0

package/dist/utils/sql.utils.js

@@ -1,19 +1,81 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createUniqueParameterName = exports.stringToSQLValue = exports.stringToSQLIdentifier = exports.wrapWithBackQoutes = exports.wrapWithDoubleQoutes = void 0;
+exports.assertArrayType = exports.createUniqueParameterName = exports.stringToSQLValue = exports.stringToSQLIdentifier = exports.quoteIdentifierPath = exports.quoteIdentifier = exports.getDriverType = exports.isSqliteLikeDriver = exports.isMysqlLikeDriver = exports.wrapWithBackQoutes = exports.wrapWithDoubleQoutes = void 0;
 const common_utils_1 = require("./common.utils");
 const wrapWithDoubleQoutes = (str) => str.includes('"') ? str : `"${str}"`;
 exports.wrapWithDoubleQoutes = wrapWithDoubleQoutes;
 const wrapWithBackQoutes = (str) => str.includes('`') ? str : '`' + str + '`';
 exports.wrapWithBackQoutes = wrapWithBackQoutes;
-const stringToSQLIdentifier = (str, driver) => str.includes('.')
-    ? str
-        .split('.')
-        .map((val) => (driver === null || driver === void 0 ? void 0 : driver.includes('mysql'))
-        ? (0, exports.wrapWithBackQoutes)(val)
-        : (0, exports.wrapWithDoubleQoutes)(val))
-        .join('.')
-    : (0, exports.wrapWithDoubleQoutes)(str);
+const BACKTICK = '`';
+// one identifier: unquoted (user, firstName) or already quoted ("user", `user`, "a""b")
+const UNQUOTED_IDENTIFIER = '[\\p{L}_][\\p{L}\\p{N}_$]*';
+const DOUBLE_QUOTED_IDENTIFIER = '"(?:[^"]|"")+"';
+const BACK_QUOTED_IDENTIFIER = `${BACKTICK}(?:[^${BACKTICK}]|${BACKTICK}${BACKTICK})+${BACKTICK}`;
+const IDENTIFIER = `(?:${UNQUOTED_IDENTIFIER}|${DOUBLE_QUOTED_IDENTIFIER}|${BACK_QUOTED_IDENTIFIER})`;
+// `id`, `user.id`, `"user"."id"`, `schema.table.column`, optionally ending with `.*`
+const IDENTIFIER_PATH = new RegExp(`^${IDENTIFIER}(?:\\.${IDENTIFIER})*(?:\\.\\*)?$`, 'u');
+const IDENTIFIER_PATH_SEGMENT = new RegExp(`${IDENTIFIER}|\\*`, 'gu');
+/** MySQL, MariaDB and Aurora MySQL: backtick identifiers, `<=>` null-safe comparison. */
+const isMysqlLikeDriver = (driver) => driver === 'mysql' || driver === 'mariadb' || driver === 'aurora-mysql';
+exports.isMysqlLikeDriver = isMysqlLikeDriver;
+// `string[]`: TypeORM 1.0 removed the `sqlite` driver from `DatabaseType`, 0.3.x still has it
+const SQLITE_LIKE_DRIVERS = [
+    'sqlite',
+    'better-sqlite3',
+    'sqljs',
+    'capacitor',
+    'cordova',
+    'expo',
+    'nativescript',
+    'react-native',
+];
+/** SQLite drivers: `IS` / `IS NOT` are null-safe comparisons. */
+const isSqliteLikeDriver = (driver) => driver !== undefined && SQLITE_LIKE_DRIVERS.includes(driver);
+exports.isSqliteLikeDriver = isSqliteLikeDriver;
+/** Database type of the query builder's connection, e.g. `'postgres'`; undefined without one. */
+function getDriverType(builder) {
+    var _a, _b, _c;
+    return (_c = (_b = (_a = builder.connection) === null || _a === void 0 ? void 0 : _a.driver) === null || _b === void 0 ? void 0 : _b.options) === null || _c === void 0 ? void 0 : _c.type;
+}
+exports.getDriverType = getDriverType;
+/**
+ * Quotes one identifier, whatever characters it has: `first-name` → `"first-name"`, a `"` inside is
+ * doubled. An already quoted identifier is kept. For names known to be identifiers (columns, aliases).
+ */
+const quoteIdentifier = (name, driver) => {
+    const mysql = (0, exports.isMysqlLikeDriver)(driver);
+    const quote = mysql ? BACKTICK : '"';
+    if (name.length >= 2 && name.startsWith(quote) && name.endsWith(quote)) {
+        return name;
+    }
+    return `${quote}${name.split(quote).join(quote + quote)}${quote}`;
+};
+exports.quoteIdentifier = quoteIdentifier;
+/**
+ * Quotes an alias or a table: as a path when it is one (`schema.table` → `"schema"."table"`),
+ * otherwise as one identifier (`user-1` → `"user-1"`).
+ */
+const quoteIdentifierPath = (path, driver) => IDENTIFIER_PATH.test(path) ? (0, exports.stringToSQLIdentifier)(path, driver) : (0, exports.quoteIdentifier)(path, driver);
+exports.quoteIdentifierPath = quoteIdentifierPath;
+/**
+ * Quotes an identifier path: `user.id` → `"user"."id"`, `user.*` → `"user".*`.
+ * Already quoted segments are kept. Anything that isn't a path of identifiers
+ * (`COALESCE(a.x, b.x)`, `LOWER(u.email)`, `u.id::text`, `*`) is returned as is.
+ */
+const stringToSQLIdentifier = (str, driver) => {
+    var _a;
+    if (!IDENTIFIER_PATH.test(str)) {
+        return str;
+    }
+    const quote = (0, exports.isMysqlLikeDriver)(driver)
+        ? exports.wrapWithBackQoutes
+        : exports.wrapWithDoubleQoutes;
+    return ((_a = str.match(IDENTIFIER_PATH_SEGMENT)) !== null && _a !== void 0 ? _a : [])
+        .map((segment) => segment === '*' || segment.startsWith('"') || segment.startsWith(BACKTICK)
+        ? segment
+        : quote(segment))
+        .join('.');
+};
 exports.stringToSQLIdentifier = stringToSQLIdentifier;
 const stringToSQLValue = (str) => `'${str}'`;
 exports.stringToSQLValue = stringToSQLValue;
@@ -22,3 +84,19 @@ const createUniqueParameterName = (prefix) => {
     return `${prefix || 'param'}_${uniqueCode}`;
 };
 exports.createUniqueParameterName = createUniqueParameterName;
+// a type name, optionally schema-qualified, multi-word (`character varying`), with a
+// modifier (`varchar(255)`) and array brackets: `uuid[]`, `public.order_status[]`, `"MyEnum"[]`
+const TYPE_NAME_PART = '(?:[A-Za-z_][\\w$]*|"(?:[^"]|"")+")';
+const ARRAY_TYPE_PATTERN = new RegExp(`^${TYPE_NAME_PART}(?:\\.${TYPE_NAME_PART})*(?: ${TYPE_NAME_PART})*` +
+    `(?:\\(\\d+(?:, ?\\d+)?\\))?(?:\\[\\d*\\])*$`);
+/**
+ * Returns `arrayType` if it is a type name (`uuid[]`, `public.order_status[]`, `varchar(36)[]`),
+ * throws a `TypeError` otherwise: the type is inserted into the SQL as is.
+ */
+function assertArrayType(arrayType) {
+    if (typeof arrayType !== 'string' || !ARRAY_TYPE_PATTERN.test(arrayType)) {
+        throw new TypeError(`Invalid array type "${arrayType}": expected a type name like "uuid[]"`);
+    }
+    return arrayType;
+}
+exports.assertArrayType = assertArrayType;

package/dist/utils/table.utils.d.ts

@@ -0,0 +1,86 @@
+import { ObjectLiteral } from "typeorm";
+export type TableHelperOptions = {
+    useQuotes?: boolean;
+};
+type JsonFieldTuple<T, Depth extends 0[] = []> = Depth['length'] extends 4 ? [string, ...string[]] : {
+    [K in keyof T & string]: [NonNullable<T[K]>] extends [Record<string, unknown>] ? [K, ...JsonFieldTuple<NonNullable<T[K]>, [...Depth, 0]>] | [K] : [K];
+}[keyof T & string];
+export type TableHelperCountOptions = {
+    /** `COUNT(DISTINCT column)`: count the different values of the column. Needs a column. */
+    distinct?: boolean;
+    /** Count only the rows that match this condition, e.g. `t.where('status', "= 'active'")`. */
+    filter?: string;
+    /**
+     * How `filter` is written:
+     * - `'case'` (default): `COUNT(CASE WHEN filter THEN column END)`, in every database;
+     * - `'filter'`: `COUNT(column) FILTER (WHERE filter)`, PostgreSQL and SQLite 3.30+ only, a few percent faster on PostgreSQL.
+     */
+    syntax?: 'case' | 'filter';
+};
+export type JsonFieldRest<V> = [NonNullable<V>] extends [Record<string, unknown>] ? JsonFieldTuple<NonNullable<V>> : string[];
+/**
+ * Creates a type-safe SQL helper for building column references, WHERE expressions,
+ * JOIN clauses, and JSONB accessors for a given entity type.
+ *
+ * @example
+ * const t = tableHelper<UserEntity>('user');
+ * t.column('email')              // → "user"."email"
+ * t.where('id', '= :id')        // → "user"."id" = :id
+ * t.jsonColumn('metadata', '->>', 'role')  // → "user"."metadata" ->> 'role'
+ */
+export declare const tableHelper: <T extends ObjectLiteral>(alias?: string, options?: TableHelperOptions) => {
+    alias: string | undefined;
+    /**
+     * Returns a quoted SQL column identifier, e.g. `"alias"."column"`. The column is always quoted as one
+     * identifier, so names with other characters work too: `"user"."first-name"`.
+     */
+    column(columnName: keyof T, alias?: string): string;
+    /** Returns a column identifier optionally followed by an expression, e.g. `"user"."id" = :id`. */
+    where(columnName: keyof T, expression?: string): string;
+    /** Returns an unquoted join path, e.g. `user.images`. Needs the helper's alias, or `alias`. */
+    join(relation: keyof T, alias?: string): string;
+    /**
+     * Returns a column with a JOIN ON expression, e.g. `"user"."id" = "images"."userId"`.
+     * The expression is inserted as is: build its columns with another `tableHelper`
+     * (`t.joinOn('id', '= ' + images.column('userId'))`), since unquoted camelCase names
+     * like `images.userId` are folded to lowercase by PostgreSQL unless TypeORM rewrites them.
+     */
+    joinOn(thisColumn: keyof T, expression: string): string;
+    /** Returns `"alias"."column" IS NULL`. */
+    isNull(columnName: keyof T): string;
+    /** Returns `"alias"."column" IS NOT NULL`. */
+    isNotNull(columnName: keyof T): string;
+    /**
+     * Returns `CAST(COUNT("alias"."column") AS integer)`: the rows where the column isn't `NULL`.
+     * 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
+     * t.count('email', { distinct: true })              // CAST(COUNT(DISTINCT "user"."email") AS integer)
+     * t.count(undefined, { filter: t.where('status', "= 'active'") })
+     * // CAST(COUNT(CASE WHEN "user"."status" = 'active' THEN 1 END) AS integer)
+     * t.count(undefined, { filter: t.where('status', "= 'active'"), syntax: 'filter' })
+     * // CAST(COUNT(*) FILTER (WHERE "user"."status" = 'active') AS integer)
+     */
+    count(columnName?: keyof T | undefined, countOptions?: TableHelperCountOptions): string;
+    /** Returns `CAST(expression AS type)`. */
+    cast(expression: string, type: string): string;
+    /**
+     * Returns a full JSONB column access expression.
+     * @example
+     * t.jsonColumn('metadata', '->>', 'role')             // → "user"."metadata" ->> 'role'
+     * t.jsonColumn('metadata', '->>', 'settings', 'theme') // → "user"."metadata" -> 'settings' ->> 'theme'
+     */
+    jsonColumn<K extends keyof T>(columnName: K, jsonOperator: '->>' | '->', ...fieldNames: JsonFieldRest<T[K]>): string;
+    /**
+     * Returns only the JSONB operator fragment (without the column).
+     * Useful inside `whereTyped` conditions strings.
+     * @example
+     * t.jsonPath('metadata', '->>', 'role')              // → ->> 'role'
+     * t.jsonPath('metadata', '->>', 'settings', 'theme') // → -> 'settings' ->> 'theme'
+     *
+     * // Combined with whereTyped:
+     * qb.whereTyped(u => u.metadata, `${t.jsonPath('metadata', '->>', 'role')} =`, 'admin')
+     */
+    jsonPath<K_1 extends keyof T>(_columnName: K_1, jsonOperator: '->>' | '->', ...fieldNames: JsonFieldRest<T[K_1]>): string;
+};
+export {};

package/dist/utils/table.utils.js

@@ -0,0 +1,135 @@
+"use strict";
+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, "''")}'`;
+}
+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])}`;
+    }
+    return result;
+}
+/**
+ * Creates a type-safe SQL helper for building column references, WHERE expressions,
+ * JOIN clauses, and JSONB accessors for a given entity type.
+ *
+ * @example
+ * const t = tableHelper<UserEntity>('user');
+ * t.column('email')              // → "user"."email"
+ * t.where('id', '= :id')        // → "user"."id" = :id
+ * t.jsonColumn('metadata', '->>', 'role')  // → "user"."metadata" ->> 'role'
+ */
+const tableHelper = (alias, options = {}) => ({
+    alias,
+    /**
+     * Returns a quoted SQL column identifier, e.g. `"alias"."column"`. The column is always quoted as one
+     * identifier, so names with other characters work too: `"user"."first-name"`.
+     */
+    column(columnName, alias) {
+        const { useQuotes = true } = 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)]
+            .filter(Boolean)
+            .join('.');
+    },
+    /** Returns a column identifier optionally followed by an expression, e.g. `"user"."id" = :id`. */
+    where(columnName, expression) {
+        const column = this.column(columnName);
+        return [column, expression].filter(Boolean).join(' ');
+    },
+    /** Returns an unquoted join path, e.g. `user.images`. Needs the helper's alias, or `alias`. */
+    join(relation, alias) {
+        const tableAlias = alias !== null && alias !== void 0 ? alias : this.alias;
+        if (!tableAlias) {
+            throw new TypeError(`tableHelper().join('${String(relation)}') needs an alias: tableHelper('user').join('${String(relation)}')`);
+        }
+        return `${tableAlias}.${String(relation)}`;
+    },
+    /**
+     * Returns a column with a JOIN ON expression, e.g. `"user"."id" = "images"."userId"`.
+     * The expression is inserted as is: build its columns with another `tableHelper`
+     * (`t.joinOn('id', '= ' + images.column('userId'))`), since unquoted camelCase names
+     * like `images.userId` are folded to lowercase by PostgreSQL unless TypeORM rewrites them.
+     */
+    joinOn(thisColumn, expression) {
+        return this.where(thisColumn, expression);
+    },
+    /** Returns `"alias"."column" IS NULL`. */
+    isNull(columnName) {
+        return this.where(columnName, 'IS NULL');
+    },
+    /** Returns `"alias"."column" IS NOT NULL`. */
+    isNotNull(columnName) {
+        return this.where(columnName, 'IS NOT NULL');
+    },
+    /**
+     * Returns `CAST(COUNT("alias"."column") AS integer)`: the rows where the column isn't `NULL`.
+     * 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
+     * t.count('email', { distinct: true })              // CAST(COUNT(DISTINCT "user"."email") AS integer)
+     * t.count(undefined, { filter: t.where('status', "= 'active'") })
+     * // CAST(COUNT(CASE WHEN "user"."status" = 'active' THEN 1 END) AS integer)
+     * t.count(undefined, { filter: t.where('status', "= 'active'"), syntax: 'filter' })
+     * // CAST(COUNT(*) FILTER (WHERE "user"."status" = 'active') AS integer)
+     */
+    count(columnName, countOptions = {}) {
+        if (typeof countOptions !== 'object' || countOptions === null) {
+            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})`;
+        }
+        return this.cast(expression, 'integer');
+    },
+    /** Returns `CAST(expression AS type)`. */
+    cast(expression, type) {
+        return `CAST(${expression} AS ${type})`;
+    },
+    /**
+     * Returns a full JSONB column access expression.
+     * @example
+     * t.jsonColumn('metadata', '->>', 'role')             // → "user"."metadata" ->> 'role'
+     * t.jsonColumn('metadata', '->>', 'settings', 'theme') // → "user"."metadata" -> 'settings' ->> 'theme'
+     */
+    jsonColumn(columnName, jsonOperator, ...fieldNames) {
+        const column = this.column(columnName);
+        const path = buildJsonPath(fieldNames, jsonOperator);
+        return `${column} ${path}`;
+    },
+    /**
+     * Returns only the JSONB operator fragment (without the column).
+     * Useful inside `whereTyped` conditions strings.
+     * @example
+     * t.jsonPath('metadata', '->>', 'role')              // → ->> 'role'
+     * t.jsonPath('metadata', '->>', 'settings', 'theme') // → -> 'settings' ->> 'theme'
+     *
+     * // Combined with whereTyped:
+     * qb.whereTyped(u => u.metadata, `${t.jsonPath('metadata', '->>', 'role')} =`, 'admin')
+     */
+    jsonPath(_columnName, jsonOperator, ...fieldNames) {
+        return buildJsonPath(fieldNames, jsonOperator);
+    }
+});
+exports.tableHelper = tableHelper;

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

@@ -1,6 +1,23 @@
-import type { WhereExpressionBuilder } from 'typeorm';
+import type { ObjectLiteral, WhereExpressionBuilder } from 'typeorm';
 import type { WhereMethods } from '../types/extensions/where.types';
 export declare function getValuePlaceholder<T>(value: T, paramName?: string): string;
-export declare function attachWhere<QB extends WhereExpressionBuilder>(builder: QB, method: WhereMethods, field: string, conditions: string, value?: unknown, options?: {
+/**
+ * Whether `params` is a `{ name: value }` params object (a plain object or a class instance such
+ * as a DTO), rather than the value itself (a primitive, an array, a `Date`, a `Buffer`).
+ */
+export declare function isParamsObject(params: unknown): params is Record<string, unknown>;
+/**
+ * Checks whether `conditions` already references a key of `params` as a TypeORM
+ * named parameter (`:key` or `:...key`). Matches parameters the same way TypeORM does,
+ * 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?: {
     addValue?: boolean;
 }): QB;
+/**
+ * Adds an AND condition that narrows the whole WHERE clause. TypeORM's `andWhere` doesn't group
+ * the conditions before it, so after `.where(a).orWhere(b)` it gives `a OR b AND c`, i.e.
+ * `a OR (b AND c)`. Existing conditions with an OR are wrapped first: `(a OR b) AND c`.
+ */
+export declare function andWhereNarrowing<QB extends WhereExpressionBuilder>(builder: QB, condition: string, parameters?: ObjectLiteral): QB;

package/dist/utils/where.utils.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.attachWhere = exports.getValuePlaceholder = void 0;
+exports.andWhereNarrowing = exports.attachWhere = exports.hasParamPlaceholder = exports.isParamsObject = exports.getValuePlaceholder = void 0;
 const sql_utils_1 = require("./sql.utils");
+const query_builder_utils_1 = require("./query-builder.utils");
 function getValuePlaceholder(value, paramName) {
     if (value === undefined || value === null || paramName === undefined) {
         return 'NULL';
@@ -12,30 +13,83 @@ function getValuePlaceholder(value, paramName) {
     return `:${paramName}`;
 }
 exports.getValuePlaceholder = getValuePlaceholder;
-function attachWhere(builder, method, field, conditions, value, options) {
-    const { addValue = true } = options || {};
+const isDate = (value) => Object.prototype.toString.call(value) === '[object Date]';
+/**
+ * Objects that are parameter values themselves, not `{ name: value }` params objects:
+ * `Date`, and binary data (`Buffer`, typed arrays, `ArrayBuffer`).
+ */
+const isValueObject = (value) => isDate(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer;
+/**
+ * Whether `params` is a `{ name: value }` params object (a plain object or a class instance such
+ * as a DTO), rather than the value itself (a primitive, an array, a `Date`, a `Buffer`).
+ */
+function isParamsObject(params) {
+    return (params !== null &&
+        typeof params === 'object' &&
+        !Array.isArray(params) &&
+        !isValueObject(params));
+}
+exports.isParamsObject = isParamsObject;
+/**
+ * Checks whether `conditions` already references a key of `params` as a TypeORM
+ * named parameter (`:key` or `:...key`). Matches parameters the same way TypeORM does,
+ * so `::type` casts and colons inside literals don't count unless they name a `params` key.
+ */
+function hasParamPlaceholder(conditions, params) {
+    if (!isParamsObject(params)) {
+        return false;
+    }
+    const placeholderRegex = /:(?:\.\.\.)?([A-Za-z0-9_.]+)/g;
+    let match;
+    while ((match = placeholderRegex.exec(conditions)) !== null) {
+        if (Object.prototype.hasOwnProperty.call(params, match[1])) {
+            return true;
+        }
+    }
+    return false;
+}
+exports.hasParamPlaceholder = hasParamPlaceholder;
+function attachWhere(builder, method, field, conditions, params, options) {
+    let { addValue } = options || {};
     if (method && typeof field === 'string' && typeof conditions === 'string') {
-        field = (0, sql_utils_1.stringToSQLIdentifier)(field);
-        if (addValue) {
-            // is object (not primitive, null or array)
-            const firstValue = value !== null && typeof value === 'object' && !Array.isArray(value)
-                ? Object.values(value)[0]
-                : value;
+        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) {
+            // 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
-            // null is a valid value, but undefined and NaN are not
+            // null, undefined, NaN and invalid dates are equal to NULL
             const valueIsValid = firstValue !== undefined &&
-                (typeof firstValue === 'number' ? !isNaN(firstValue) : true);
+                (typeof firstValue === 'number' ? !isNaN(firstValue) : true) &&
+                (isDate(firstValue) ? !isNaN(firstValue.getTime()) : true);
             const paramName = valueIsValid
                 ? (0, sql_utils_1.createUniqueParameterName)(method)
                 : undefined;
-            const params = paramName && valueIsValid ? { [paramName]: firstValue } : undefined;
+            const queryParams = paramName && valueIsValid ? { [paramName]: firstValue } : undefined;
             const valuePlaceholder = getValuePlaceholder(firstValue, paramName);
-            return builder[method](`${field} ${conditions} ${valuePlaceholder}`, params);
+            return builder[method](`${field} ${conditions} ${valuePlaceholder}`, queryParams);
         }
         else {
-            return builder[method](`${field} ${conditions}`, value);
+            return builder[method](`${field} ${conditions}`, params);
         }
     }
     return builder;
 }
 exports.attachWhere = attachWhere;
+/**
+ * Adds an AND condition that narrows the whole WHERE clause. TypeORM's `andWhere` doesn't group
+ * the conditions before it, so after `.where(a).orWhere(b)` it gives `a OR b AND c`, i.e.
+ * `a OR (b AND c)`. Existing conditions with an OR are wrapped first: `(a OR b) AND c`.
+ */
+function andWhereNarrowing(builder, condition, parameters) {
+    const expressionMap = builder.expressionMap;
+    const wheres = expressionMap === null || expressionMap === void 0 ? void 0 : expressionMap.wheres;
+    if (wheres === null || wheres === void 0 ? void 0 : wheres.some((where) => where.type === 'or')) {
+        // a nested clause list is rendered in parentheses
+        expressionMap.wheres = [{ type: 'simple', condition: wheres }];
+    }
+    return builder.andWhere(condition, parameters);
+}
+exports.andWhereNarrowing = andWhereNarrowing;

package/helpers/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "typeorm-extensions/helpers",
+  "private": true,
+  "main": "../dist/helpers.js",
+  "types": "../dist/helpers.d.ts",
+  "sideEffects": false
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "typeorm-extensions",
-  "version": "1.3.4",
+  "version": "2.0.0",
   "description": "typeorm commonly used extensions",
   "main": "./dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist", "LICENSE", "README.md", "package.json"],
+  "files": ["dist", "helpers", "LICENSE", "README.md", "package.json"],
   "type": "commonjs",
   "homepage": "https://koenigstag.github.io/typeorm-extensions/",
   "repository": {
@@ -25,7 +25,7 @@
   "author": "koenigstag",
   "license": "ISC",
   "peerDependencies": {
-    "typeorm": "^0.3.12"
+    "typeorm": "^0.3.12 || ^1.0.0"
   },
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^7.1.1",

package/dist/utils/identifier.utils.d.ts

@@ -1,15 +0,0 @@
-export declare class Identifier {
-    readonly field: string;
-    readonly alias?: string | undefined;
-    private readonly useDoubleQuotes?;
-    private readonly useAlias;
-    constructor(field: string, alias?: string | undefined, useDoubleQuotes?: boolean | undefined);
-    fieldAsAlias(): string;
-    fieldIdentifier(): string;
-    get aliasSql(): string | undefined;
-    get fieldSql(): string;
-    private calcUseAlias;
-    static fieldToSql(field: string, useDoubleQuotes?: boolean): string;
-    static aliasToSql(alias: string | undefined, useDoubleQuotes?: boolean): string | undefined;
-    static toIdentifier(value: string, useDoubleQuotes?: boolean): string;
-}

package/dist/utils/identifier.utils.js

@@ -1,45 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Identifier = void 0;
-const sql_utils_1 = require("./sql.utils");
-class Identifier {
-    constructor(field, alias, useDoubleQuotes) {
-        this.field = field;
-        this.alias = alias;
-        this.useDoubleQuotes = useDoubleQuotes;
-        this.useAlias = this.calcUseAlias();
-    }
-    fieldAsAlias() {
-        if (this.useAlias) {
-            return `${this.fieldSql} AS ${this.aliasSql}`;
-        }
-        return this.fieldSql;
-    }
-    fieldIdentifier() {
-        if (this.useAlias) {
-            return `${this.aliasSql}.${this.fieldSql}`;
-        }
-        return this.fieldSql;
-    }
-    get aliasSql() {
-        return Identifier.aliasToSql(this.alias, this.useDoubleQuotes);
-    }
-    get fieldSql() {
-        return Identifier.fieldToSql(this.field, this.useDoubleQuotes);
-    }
-    /* PRIVATE */
-    calcUseAlias() {
-        return !!this.alias && !this.field.includes('.');
-    }
-    /* STATIC */
-    static fieldToSql(field, useDoubleQuotes) {
-        return this.toIdentifier(field, useDoubleQuotes);
-    }
-    static aliasToSql(alias, useDoubleQuotes) {
-        return alias ? this.toIdentifier(alias, useDoubleQuotes) : undefined;
-    }
-    static toIdentifier(value, useDoubleQuotes) {
-        return useDoubleQuotes ? (0, sql_utils_1.stringToSQLIdentifier)(value) : value;
-    }
-}
-exports.Identifier = Identifier;