typeorm-extensions 1.3.5 → 2.1.0

package/dist/utils/table.utils.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tableHelper = void 0;
+const sql_utils_1 = require("./sql.utils");
+const json_path_utils_1 = require("./json-path.utils");
+/**
+ * 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 = (0, json_path_utils_1.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 (0, json_path_utils_1.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;
+/**
+ * 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,20 +13,57 @@ function getValuePlaceholder(value, paramName) {
     return `:${paramName}`;
 }
 exports.getValuePlaceholder = getValuePlaceholder;
+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) {
-    const { addValue = true } = options || {};
+    let { addValue } = options || {};
     if (method && typeof field === 'string' && typeof conditions === 'string') {
-        field = (0, sql_utils_1.stringToSQLIdentifier)(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) {
-            // pick first value from params object or pass as is
-            const firstValue = params !== null && typeof params === 'object' && !Array.isArray(params)
-                ? Object.values(params)[0]
-                : 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
-            // null, undefined and NaN are equal to NULL
+            // 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;
@@ -40,3 +78,18 @@ function attachWhere(builder, method, field, conditions, params, options) {
     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.5",
+  "version": "2.1.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": {
@@ -13,7 +13,8 @@
   },
   "scripts": {
     "build": "tsc -p .",
-    "lint": "eslint . --ext .ts"
+    "lint": "eslint . --ext .ts",
+    "test:types": "tsc -p test/types"
   },
   "keywords": [
     "typeorm",
@@ -25,7 +26,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;