typeorm-extensions 2.0.0 → 2.2.0-rc.0

package/dist/utils/parameter.utils.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withUniqueParameterNames = void 0;
+const sql_utils_1 = require("./sql.utils");
+// TypeORM's placeholder syntax, `:name` and `:...name`, as its drivers match it
+const PARAMETER_PLACEHOLDER = /:(\.\.\.)?([A-Za-z0-9_.]+)/g;
+/**
+ * Renames the parameters of a subquery to unique names, in its SQL and in its parameters. A query
+ * has one parameter namespace, so two subqueries with a `:status` each would otherwise both read
+ * whichever value was set last. Placeholders that aren't keys of `parameters` stay as they are.
+ */
+function withUniqueParameterNames(sql, parameters) {
+    const names = new Map(Object.keys(parameters).map((name) => [name, (0, sql_utils_1.createUniqueParameterName)(name)]));
+    const renamedSql = sql.replace(PARAMETER_PLACEHOLDER, (placeholder, spread, name) => {
+        const unique = names.get(name);
+        return unique ? `:${spread !== null && spread !== void 0 ? spread : ''}${unique}` : placeholder;
+    });
+    const renamedParameters = Object.fromEntries(Object.entries(parameters).map(([name, value]) => [names.get(name), value]));
+    return [renamedSql, renamedParameters];
+}
+exports.withUniqueParameterNames = withUniqueParameterNames;

package/dist/utils/period.utils.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.attachPeriodFilter = void 0;
 const sql_utils_1 = require("./sql.utils");
 const where_utils_1 = require("./where.utils");
+const time_zone_utils_1 = require("./time-zone.utils");
 const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
 /** `'2024-01-31'` as a UTC midnight Date, or a `TypeError` if it is not a calendar date (`'2024-02-30'`). */
 function parseDateOnly(value, name) {
@@ -63,7 +64,10 @@ function getBoundCondition(boundary, name, include) {
  * `(a OR b) AND column >= …`. `column` is already quoted.
  */
 function attachPeriodFilter(builder, column, periodFilter, options) {
-    const { includeFrom = true, includeTo = true } = options !== null && options !== void 0 ? options : {};
+    const { includeFrom = true, includeTo = true, timeZone } = options !== null && options !== void 0 ? options : {};
+    if (timeZone) {
+        (0, time_zone_utils_1.assertTimeZone)(timeZone);
+    }
     const bounds = [
         { name: 'periodFrom', include: includeFrom },
         { name: 'periodTo', include: includeTo },
@@ -75,7 +79,8 @@ function attachPeriodFilter(builder, column, periodFilter, options) {
         }
         const { operator, value } = getBoundCondition(boundary, name, include);
         const paramName = (0, sql_utils_1.createUniqueParameterName)(name);
-        (0, where_utils_1.andWhereNarrowing)(builder, `${column} ${operator} :${paramName}`, { [paramName]: value });
+        const bound = timeZone && typeof value === 'string' ? (0, time_zone_utils_1.readInTimeZone)(value, timeZone, name) : value;
+        (0, where_utils_1.andWhereNarrowing)(builder, `${column} ${operator} :${paramName}`, { [paramName]: bound });
     }
     return builder;
 }

package/dist/utils/prototype.utils.d.ts

@@ -1,5 +1,9 @@
+export type PatchPrototypeOptions = {
+    /** Leave a method the target already has, own or inherited: TypeORM's, or another library's. */
+    onlyMissing?: boolean;
+};
 export declare function patchPrototype<T extends {
     prototype: any;
 }, S extends {
     prototype: any;
-}>(target: T, source: S): void;
+}>(target: T, source: S, options?: PatchPrototypeOptions): void;

package/dist/utils/prototype.utils.js

@@ -2,8 +2,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.patchPrototype = void 0;
-function patchPrototype(target, source) {
+function patchPrototype(target, source, options = {}) {
     for (const method of Object.keys(source.prototype)) {
+        if (options.onlyMissing && method in target.prototype) {
+            continue;
+        }
         target.prototype[method] = source.prototype[method];
     }
 }

package/dist/utils/proxy-key.utils.d.ts

@@ -1,9 +1,9 @@
-import { ObjectLiteral } from 'typeorm';
+import { DatabaseType, ObjectLiteral } from 'typeorm';
 import { KeyProxyCallback } from '../types/modules/proxy-callback.types';
 export declare class KeyHolder {
     private _keys;
     constructor(_keys?: string[]);
-    toSql(length?: number, useQuotes?: boolean): string;
+    toSql(length?: number, useQuotes?: boolean, driver?: DatabaseType): string;
     toString(length?: number): string;
     valueOf(): string;
     [Symbol.toPrimitive](): string;
@@ -21,7 +21,12 @@ export declare class KeyProxy {
 }
 /** Typed keys are `column` or `alias.column`: a deeper path can't be mapped to a query alias. */
 export declare const MAX_KEY_DEPTH = 2;
-export declare const getKeyHolder: <Type extends ObjectLiteral>(callback: KeyHolder | KeyProxyCallback<Type>) => KeyHolder | Array<KeyHolder>;
+export declare const createKeyTooDeepError: (keys: string[]) => TypeError;
+/**
+ * Keys of a typed callback. Paths deeper than `alias.column` throw, unless `allowDeepPaths` is set by a caller
+ * that checks them against the query's metadata (paths into JSON columns).
+ */
+export declare const getKeyHolder: <Type extends ObjectLiteral>(callback: KeyHolder | KeyProxyCallback<Type>, allowDeepPaths?: boolean) => KeyHolder | Array<KeyHolder>;
 export declare const getKey: <Type extends ObjectLiteral>(callback: string | KeyHolder | KeyProxyCallback<Type>) => string;
 /**
  * Alias to prefix a single-level key with: a string, or a function called only when it is needed,
@@ -32,4 +37,4 @@ export type KeyPrefix = string | (() => string | undefined);
  * SQL key of a typed callback: `(u) => u.id` → `prefix.id`, `(u) => u.images.url` → `images.url`
  * (an `alias.column` path keeps its own alias). Strings are returned as is.
  */
-export declare const getSqlKeyFromProxyCallback: <Type extends ObjectLiteral>(callback: string | KeyHolder | KeyProxyCallback<Type>, addPrefix?: KeyPrefix, useQuotes?: boolean) => string | string[];
+export declare const getSqlKeyFromProxyCallback: <Type extends ObjectLiteral>(callback: string | KeyHolder | KeyProxyCallback<Type>, addPrefix?: KeyPrefix, useQuotes?: boolean, driver?: DatabaseType) => string | string[];

package/dist/utils/proxy-key.utils.js

@@ -1,15 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSqlKeyFromProxyCallback = exports.getKey = exports.getKeyHolder = exports.MAX_KEY_DEPTH = exports.KeyProxy = exports.TypedProxy = exports.KeyHolder = void 0;
+exports.getSqlKeyFromProxyCallback = exports.getKey = exports.getKeyHolder = exports.createKeyTooDeepError = exports.MAX_KEY_DEPTH = exports.KeyProxy = exports.TypedProxy = exports.KeyHolder = void 0;
 const sql_utils_1 = require("./sql.utils");
 class KeyHolder {
     constructor(_keys = []) {
         this._keys = _keys;
         this._keys = [..._keys];
     }
-    toSql(length = 2, useQuotes) {
+    toSql(length = 2, useQuotes, driver) {
         const string = this.toString(length);
-        const sql = useQuotes ? (0, sql_utils_1.stringToSQLIdentifier)(string) : string;
+        const sql = useQuotes ? (0, sql_utils_1.stringToSQLIdentifier)(string, driver) : string;
         return sql;
     }
     toString(length = 2) {
@@ -71,24 +71,31 @@ KeyProxy.defaultHandler = {
 };
 /** Typed keys are `column` or `alias.column`: a deeper path can't be mapped to a query alias. */
 exports.MAX_KEY_DEPTH = 2;
+const createKeyTooDeepError = (keys) => new TypeError(`Typed key "${keys.join('.')}" is ${keys.length} levels deep, but typed methods support only ` +
+    `"column" or "alias.column", or a path into a JSON column in where methods. Join the nested relation and ` +
+    `address it by its alias with an alias-keyed type, e.g. type Joins = { someAlias: SomeEntity }; (j) => j.someAlias.column`);
+exports.createKeyTooDeepError = createKeyTooDeepError;
 const assertKeyDepth = (keyHolder) => {
     const keys = keyHolder.getKeys();
     if (keys.length > exports.MAX_KEY_DEPTH) {
-        throw new TypeError(`Typed key "${keys.join('.')}" is ${keys.length} levels deep, but typed methods support only ` +
-            `"column" or "alias.column". Join the nested relation and address it by its alias ` +
-            `with an alias-keyed type, e.g. type Joins = { someAlias: SomeEntity }; (j) => j.someAlias.column`);
+        throw (0, exports.createKeyTooDeepError)(keys);
     }
     return keyHolder;
 };
-const getKeyHolder = (callback) => {
+/**
+ * Keys of a typed callback. Paths deeper than `alias.column` throw, unless `allowDeepPaths` is set by a caller
+ * that checks them against the query's metadata (paths into JSON columns).
+ */
+const getKeyHolder = (callback, allowDeepPaths = false) => {
+    const check = allowDeepPaths ? (keyHolder) => keyHolder : assertKeyDepth;
     if (typeof callback !== 'function') {
         if (callback instanceof KeyHolder) {
-            return assertKeyDepth(callback);
+            return check(callback);
         }
     }
     const keyHolder = callback(KeyProxy.create());
     // fail loudly instead of silently dropping levels beyond `alias.column`
-    return Array.isArray(keyHolder) ? keyHolder.map(assertKeyDepth) : assertKeyDepth(keyHolder);
+    return Array.isArray(keyHolder) ? keyHolder.map(check) : check(keyHolder);
 };
 exports.getKeyHolder = getKeyHolder;
 const getKey = (callback) => {
@@ -102,26 +109,26 @@ exports.getKey = getKey;
  * SQL key of a typed callback: `(u) => u.id` → `prefix.id`, `(u) => u.images.url` → `images.url`
  * (an `alias.column` path keeps its own alias). Strings are returned as is.
  */
-const getSqlKeyFromProxyCallback = (callback, addPrefix, useQuotes) => {
+const getSqlKeyFromProxyCallback = (callback, addPrefix, useQuotes, driver) => {
     if (typeof callback === 'string')
         return callback;
     const keyHolder = (0, exports.getKeyHolder)(callback);
     if (Array.isArray(keyHolder)) {
-        return keyHolder.map((holder) => (0, exports.getSqlKeyFromProxyCallback)(holder, addPrefix, useQuotes));
+        return keyHolder.map((holder) => (0, exports.getSqlKeyFromProxyCallback)(holder, addPrefix, useQuotes, driver));
     }
     // if select is like this: (proxy) => proxy.relation.column
     if (keyHolder.getKeys().length > 1) {
         // return unchanged
-        return keyHolder.toSql(undefined, useQuotes);
+        return keyHolder.toSql(undefined, useQuotes, driver);
     }
     // else if select is one layer depth like this: (proxy) => proxy.column
     // then add alias before the key; resolve the alias only now, a path above doesn't need it
     const prefix = typeof addPrefix === 'function' ? addPrefix() : addPrefix;
     if (typeof prefix === 'string' && prefix.length >= 1) {
         // a new holder: a KeyHolder passed in by the caller must stay as it was
-        return new KeyHolder([prefix, ...keyHolder.getKeys()]).toSql(undefined, useQuotes);
+        return new KeyHolder([prefix, ...keyHolder.getKeys()]).toSql(undefined, useQuotes, driver);
     }
-    return keyHolder.toSql(undefined, useQuotes);
+    return keyHolder.toSql(undefined, useQuotes, driver);
 };
 exports.getSqlKeyFromProxyCallback = getSqlKeyFromProxyCallback;
 // example of typed select

package/dist/utils/query-builder.utils.d.ts

@@ -1,11 +1,18 @@
 import type { ObjectLiteral, WhereExpressionBuilder } from 'typeorm';
+import type { ColumnMetadata } from 'typeorm/metadata/ColumnMetadata';
 import type { KeyProxyCallback } from '../types/modules/proxy-callback.types';
+import { JsonPathSqlOptions } from './json-path.utils';
 /**
  * Database name of an entity property's column (`@Column({ name })`), looked up in the metadata of
  * a query alias (the main alias when `aliasName` is undefined). `undefined` when the alias has no
  * entity or the property isn't a column.
  */
 export declare function getColumnDatabaseName(builder: WhereExpressionBuilder, aliasName: string | undefined, propertyPath: string): string | undefined;
+/**
+ * The entity column a field names, the way `toFieldSql` resolves it: `alias.property` or
+ * `alias.column_name` on an alias with an entity, or a database column name of the main alias.
+ */
+export declare function findFieldColumn(builder: WhereExpressionBuilder, field: string): ColumnMetadata | undefined;
 /**
  * SQL for a field passed as a string to the untyped methods (`whereIsIn('user.first-name', …)`).
  *
@@ -27,15 +34,18 @@ export declare function toFieldSql(builder: WhereExpressionBuilder, field: strin
  *
  * The property is mapped to its database column name (`@Column({ name })`, embedded columns)
  * through the metadata of the alias it belongs to (see `resolveTypedKey`). Aliases without
- * metadata (subqueries) and unknown properties keep the property name.
+ * metadata (subqueries) and unknown properties keep the property name. A path into a JSON column
+ * gives its JSON accessor, cast on PostgreSQL to the type of `jsonOptions.value`.
  */
-export declare function getTypedColumnKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, callback: KeyProxyCallback<Type>): string | string[];
+export declare function getTypedColumnKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, callback: KeyProxyCallback<Type>, jsonOptions?: JsonPathSqlOptions): string | string[];
+/** Whether a typed callback selects a path inside a JSON column, `u => u.metadata.tags`, rather than a column. */
+export declare function isTypedJsonPath<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, callback: KeyProxyCallback<Type>): boolean;
 /**
  * Quoted column of a typed callback that must select exactly one column
  * (`whereIsAnyTyped`, `whereArrayContainsTyped`, …). Throws a `TypeError` for several columns:
  * one condition per column has no single obvious meaning (AND? OR?), so don't guess.
  */
-export declare function getTypedSingleColumnKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, callback: KeyProxyCallback<Type>, methodName: string): string;
+export declare function getTypedSingleColumnKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, callback: KeyProxyCallback<Type>, methodName: string, jsonOptions?: JsonPathSqlOptions): string;
 /**
  * Key for typed select / order / distinct on a SelectQueryBuilder.
  *

package/dist/utils/query-builder.utils.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTypedSelectionKey = exports.getTypedSingleColumnKey = exports.getTypedColumnKey = exports.toFieldSql = exports.getColumnDatabaseName = void 0;
+exports.getTypedSelectionKey = exports.getTypedSingleColumnKey = exports.isTypedJsonPath = exports.getTypedColumnKey = exports.toFieldSql = exports.findFieldColumn = exports.getColumnDatabaseName = void 0;
 const proxy_key_utils_1 = require("./proxy-key.utils");
+const json_path_utils_1 = require("./json-path.utils");
 const sql_utils_1 = require("./sql.utils");
 /**
  * Whether single-level typed keys are qualified with the main alias (`user.firstName`).
@@ -53,6 +54,21 @@ function findColumn(metadata, name) {
     var _a;
     return ((_a = metadata.columns.find((column) => column.databaseName === name)) !== null && _a !== void 0 ? _a : metadata.findColumnWithPropertyPath(name));
 }
+/**
+ * The entity column a field names, the way `toFieldSql` resolves it: `alias.property` or
+ * `alias.column_name` on an alias with an entity, or a database column name of the main alias.
+ */
+function findFieldColumn(builder, field) {
+    var _a;
+    const queryBuilder = builder;
+    const dot = field.indexOf('.');
+    if (dot > 0) {
+        const metadata = getAliasMetadata(queryBuilder, field.slice(0, dot));
+        return metadata && findColumn(metadata, field.slice(dot + 1));
+    }
+    return (_a = getAliasMetadata(queryBuilder, undefined)) === null || _a === void 0 ? void 0 : _a.columns.find((column) => column.databaseName === field);
+}
+exports.findFieldColumn = findFieldColumn;
 /**
  * SQL for a field passed as a string to the untyped methods (`whereIsIn('user.first-name', …)`).
  *
@@ -94,12 +110,34 @@ function toFieldSql(builder, field) {
     return (0, sql_utils_1.stringToSQLIdentifier)(field, (0, sql_utils_1.getDriverType)(builder));
 }
 exports.toFieldSql = toFieldSql;
+/**
+ * The column that `keys` name in an entity: the longest prefix of the keys that is a column's property path
+ * (`address.city` for an embedded entity). The keys after it are a path inside the column, allowed only in a
+ * JSON column (`details` + `['meta', 'endTs']`). `undefined` when no prefix is a column, or a column that isn't
+ * JSON is followed by more keys (a relation's join column, `user` in `user.email`).
+ */
+function findColumnPath(metadata, keys) {
+    for (let length = keys.length; metadata && length >= 1; length--) {
+        const propertyPath = keys.slice(0, length).join('.');
+        const column = metadata.findColumnWithPropertyPath(propertyPath);
+        if (!column) {
+            continue;
+        }
+        if (length === keys.length) {
+            return { propertyPath, column };
+        }
+        return (0, json_path_utils_1.isJsonColumn)(column) ? { propertyPath, column, jsonPath: keys.slice(length) } : undefined;
+    }
+    return undefined;
+}
 /**
  * Splits typed keys into the alias and the property path they refer to:
  * - `t => t.status` → the query's main alias + `status` (no alias on UPDATE / DELETE);
  * - `j => j.t.status`, `u => u.images.url` → the first key, when it is an alias of the query;
  * - `p => p.address.city` → when the first key isn't an alias but the main entity has a column
  *   with that path (an embedded entity), the main alias + `address.city`;
+ * - `e => e.details.meta.endTs`, `j => j.e.details.outcome` → a JSON column of the alias' entity
+ *   followed by the keys inside it (`jsonPath`), at any depth;
  * - anything else → the first key as the alias (an alias the query builder doesn't know yet,
  *   e.g. `q => q.base.chatRoomId` before `.from(…, 'base')`).
  *
@@ -108,6 +146,20 @@ exports.toFieldSql = toFieldSql;
  * before `from()` the property name is used as the column name.
  */
 function resolveTypedKey(queryBuilder, keys) {
+    var _a, _b;
+    const resolved = resolveTypedKeyPath(queryBuilder, keys);
+    // deeper than `alias.column` only inside a JSON column: a nested relation can't be mapped to an alias
+    if (!resolved.jsonPath && keys.length > proxy_key_utils_1.MAX_KEY_DEPTH) {
+        throw (0, proxy_key_utils_1.createKeyTooDeepError)(keys);
+    }
+    const column = (_a = resolved.column) !== null && _a !== void 0 ? _a : (_b = resolved.metadata) === null || _b === void 0 ? void 0 : _b.findColumnWithPropertyPath(resolved.propertyPath);
+    // a @CalculatedColumn: TypeORM would write "alias"."property", a column the table doesn't have
+    if ((column === null || column === void 0 ? void 0 : column.isVirtualProperty) && !column.query) {
+        throw new TypeError(`${keys.join('.')} is a @CalculatedColumn, not a column of the table: use the SQL expression that fills it`);
+    }
+    return resolved;
+}
+function resolveTypedKeyPath(queryBuilder, keys) {
     const prefixing = isAliasPrefixingEnabled(queryBuilder);
     if (keys.length === 1) {
         const aliasName = prefixing ? requireMainAliasName(queryBuilder, keys[0]) : undefined;
@@ -122,59 +174,80 @@ function resolveTypedKey(queryBuilder, keys) {
     const mainAlias = expressionMap === null || expressionMap === void 0 ? void 0 : expressionMap.mainAlias;
     // UPDATE / DELETE have no alias to qualify with: `u => u.user.firstName` is `"firstName"` there
     if (!prefixing && (mainAlias === null || mainAlias === void 0 ? void 0 : mainAlias.name) === firstKey) {
+        const metadata = getAliasMetadata(queryBuilder, undefined);
         return {
             aliasName: undefined,
             propertyPath: restKeys.join('.'),
-            metadata: getAliasMetadata(queryBuilder, undefined),
+            metadata,
+            ...findColumnPath(metadata, restKeys),
         };
     }
     const queryAlias = expressionMap === null || expressionMap === void 0 ? void 0 : expressionMap.aliases.find((alias) => alias.name === firstKey);
     if (!queryAlias && mainAlias) {
         const mainMetadata = getAliasMetadata(queryBuilder, undefined);
-        const embeddedPath = keys.join('.');
-        if (mainMetadata === null || mainMetadata === void 0 ? void 0 : mainMetadata.findColumnWithPropertyPath(embeddedPath)) {
+        const columnPath = findColumnPath(mainMetadata, keys);
+        if (columnPath) {
             return {
                 aliasName: prefixing ? mainAlias.name : undefined,
-                propertyPath: embeddedPath,
                 metadata: mainMetadata,
+                ...columnPath,
             };
         }
     }
+    const metadata = (queryAlias === null || queryAlias === void 0 ? void 0 : queryAlias.hasMetadata) ? queryAlias.metadata : undefined;
     return {
         aliasName: firstKey,
         propertyPath: restKeys.join('.'),
-        metadata: (queryAlias === null || queryAlias === void 0 ? void 0 : queryAlias.hasMetadata) ? queryAlias.metadata : undefined,
+        metadata,
+        ...findColumnPath(metadata, restKeys),
     };
 }
-/** `"alias"."column"` (or `"column"` without an alias) with the database column name. */
-function toQuotedColumnKey(queryBuilder, { aliasName, propertyPath, metadata }) {
+/**
+ * `"alias"."column"` (or `"column"` without an alias) with the database column name, followed by the path
+ * inside a JSON column: `"exec"."details" -> 'meta' ->> 'endTs'` (see `toJsonPathSql`).
+ */
+function toQuotedColumnKey(queryBuilder, { aliasName, propertyPath, metadata, column, jsonPath }, jsonOptions) {
     var _a, _b;
-    const column = (_b = (_a = metadata === null || metadata === void 0 ? void 0 : metadata.findColumnWithPropertyPath(propertyPath)) === null || _a === void 0 ? void 0 : _a.databaseName) !== null && _b !== void 0 ? _b : propertyPath;
-    return aliasName === undefined
-        ? queryBuilder.escape(column)
-        : `${queryBuilder.escape(aliasName)}.${queryBuilder.escape(column)}`;
+    const columnName = (_b = (_a = (column !== null && column !== void 0 ? column : metadata === null || metadata === void 0 ? void 0 : metadata.findColumnWithPropertyPath(propertyPath))) === null || _a === void 0 ? void 0 : _a.databaseName) !== null && _b !== void 0 ? _b : propertyPath;
+    const columnSql = aliasName === undefined
+        ? queryBuilder.escape(columnName)
+        : `${queryBuilder.escape(aliasName)}.${queryBuilder.escape(columnName)}`;
+    if (!column || !jsonPath) {
+        return columnSql;
+    }
+    const driver = (0, sql_utils_1.getDriverType)(queryBuilder);
+    return (0, json_path_utils_1.toJsonPathSql)(driver, columnSql, column, jsonPath, jsonOptions);
 }
 /**
  * SQL key for a typed callback on `builder`: `"alias"."column"`, or `"column"` on UPDATE / DELETE.
  *
  * The property is mapped to its database column name (`@Column({ name })`, embedded columns)
  * through the metadata of the alias it belongs to (see `resolveTypedKey`). Aliases without
- * metadata (subqueries) and unknown properties keep the property name.
+ * metadata (subqueries) and unknown properties keep the property name. A path into a JSON column
+ * gives its JSON accessor, cast on PostgreSQL to the type of `jsonOptions.value`.
  */
-function getTypedColumnKey(builder, callback) {
+function getTypedColumnKey(builder, callback, jsonOptions) {
     const queryBuilder = builder;
-    const toKey = (keyHolder) => toQuotedColumnKey(queryBuilder, resolveTypedKey(queryBuilder, keyHolder.getKeys()));
-    const keyHolder = (0, proxy_key_utils_1.getKeyHolder)(callback);
+    const toKey = (keyHolder) => toQuotedColumnKey(queryBuilder, resolveTypedKey(queryBuilder, keyHolder.getKeys()), jsonOptions);
+    // the depth is checked against the query's metadata, where a JSON column may be deeper
+    const keyHolder = (0, proxy_key_utils_1.getKeyHolder)(callback, true);
     return Array.isArray(keyHolder) ? keyHolder.map(toKey) : toKey(keyHolder);
 }
 exports.getTypedColumnKey = getTypedColumnKey;
+/** Whether a typed callback selects a path inside a JSON column, `u => u.metadata.tags`, rather than a column. */
+function isTypedJsonPath(builder, callback) {
+    const keyHolder = (0, proxy_key_utils_1.getKeyHolder)(callback, true);
+    return (!Array.isArray(keyHolder) &&
+        Boolean(resolveTypedKey(builder, keyHolder.getKeys()).jsonPath));
+}
+exports.isTypedJsonPath = isTypedJsonPath;
 /**
  * Quoted column of a typed callback that must select exactly one column
  * (`whereIsAnyTyped`, `whereArrayContainsTyped`, …). Throws a `TypeError` for several columns:
  * one condition per column has no single obvious meaning (AND? OR?), so don't guess.
  */
-function getTypedSingleColumnKey(builder, callback, methodName) {
-    const key = getTypedColumnKey(builder, callback);
+function getTypedSingleColumnKey(builder, callback, methodName, jsonOptions) {
+    const key = getTypedColumnKey(builder, callback, jsonOptions);
     if (Array.isArray(key)) {
         throw new TypeError(`${methodName} expects the callback to select a single column, got ${key.length}: ${key.join(', ')}`);
     }
@@ -195,6 +268,10 @@ function getTypedSelectionKey(builder, selection, useQuotes) {
     const queryBuilder = builder;
     const toKey = (keyHolder) => {
         const resolved = resolveTypedKey(queryBuilder, keyHolder.getKeys());
+        if (resolved.jsonPath) {
+            throw new TypeError(`Typed key "${keyHolder.getKeys().join('.')}" points into the JSON column "${resolved.propertyPath}": ` +
+                `select, order, distinct and group by take columns only. For an expression use tableHelper().jsonColumn()`);
+        }
         if (useQuotes) {
             return toQuotedColumnKey(queryBuilder, resolved);
         }

package/dist/utils/sql.utils.d.ts

@@ -3,6 +3,8 @@ export declare const wrapWithDoubleQoutes: (str: string) => string;
 export declare const wrapWithBackQoutes: (str: string) => string;
 /** MySQL, MariaDB and Aurora MySQL: backtick identifiers, `<=>` null-safe comparison. */
 export declare const isMysqlLikeDriver: (driver?: DatabaseType) => boolean;
+/** PostgreSQL and the databases speaking its dialect. */
+export declare const isPostgresLikeDriver: (driver?: DatabaseType) => boolean;
 /** SQLite drivers: `IS` / `IS NOT` are null-safe comparisons. */
 export declare const isSqliteLikeDriver: (driver?: DatabaseType) => boolean;
 /** Database type of the query builder's connection, e.g. `'postgres'`; undefined without one. */

package/dist/utils/sql.utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertArrayType = exports.createUniqueParameterName = exports.stringToSQLValue = exports.stringToSQLIdentifier = exports.quoteIdentifierPath = exports.quoteIdentifier = exports.getDriverType = exports.isSqliteLikeDriver = exports.isMysqlLikeDriver = exports.wrapWithBackQoutes = exports.wrapWithDoubleQoutes = void 0;
+exports.assertArrayType = exports.createUniqueParameterName = exports.stringToSQLValue = exports.stringToSQLIdentifier = exports.quoteIdentifierPath = exports.quoteIdentifier = exports.getDriverType = exports.isSqliteLikeDriver = exports.isPostgresLikeDriver = 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;
@@ -29,6 +29,10 @@ const SQLITE_LIKE_DRIVERS = [
     'nativescript',
     'react-native',
 ];
+const POSTGRES_LIKE_DRIVERS = ['postgres', 'aurora-postgres', 'cockroachdb'];
+/** PostgreSQL and the databases speaking its dialect. */
+const isPostgresLikeDriver = (driver) => driver !== undefined && POSTGRES_LIKE_DRIVERS.includes(driver);
+exports.isPostgresLikeDriver = isPostgresLikeDriver;
 /** SQLite drivers: `IS` / `IS NOT` are null-safe comparisons. */
 const isSqliteLikeDriver = (driver) => driver !== undefined && SQLITE_LIKE_DRIVERS.includes(driver);
 exports.isSqliteLikeDriver = isSqliteLikeDriver;

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

@@ -1,6 +1,8 @@
-import { ObjectLiteral } from "typeorm";
+import { DatabaseType, ObjectLiteral } from "typeorm";
 export type TableHelperOptions = {
     useQuotes?: boolean;
+    /** The database the SQL is for: MySQL and MariaDB quote identifiers with backticks. Double quotes without it. */
+    driver?: DatabaseType;
 };
 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];
@@ -17,6 +19,60 @@ export type TableHelperCountOptions = {
      */
     syntax?: 'case' | 'filter';
 };
+export type TableHelperJsonOptions = {
+    /** `jsonb_build_object` / `jsonb_agg` instead of the `json` functions. PostgreSQL only. */
+    jsonb?: boolean;
+};
+type ColumnName<T> = keyof T & string;
+export type TableHelperJsonAggOptions<T> = TableHelperJsonOptions & {
+    /** Orders the array by a column of the helper's table, ascending or in the given direction. Not on MySQL. */
+    orderBy?: AggregateOrder<T>;
+    /**
+     * Aggregates only the rows that match, e.g. `images.isNotNull('id')`: after a LEFT JOIN without a match
+     * the row has `NULL` columns, which would otherwise come out as `[{"id": null}]`. Not on MySQL.
+     */
+    filter?: string;
+};
+/** Keys of the entity whose values are numbers. */
+type NumericColumnName<T> = {
+    [K in keyof T & string]: [NonNullable<T[K]>] extends [number | bigint] ? K : never;
+}[keyof T & string];
+type AggregateOrder<T> = ColumnName<T> | readonly [ColumnName<T>, 'ASC' | 'DESC'];
+export type TableHelperSumOptions = {
+    /** Sums only the rows that match this condition, e.g. `t.where('status', "= 'paid'")`. */
+    filter?: string;
+    /** How `filter` is written, as for `count`: `'case'` (default) or `'filter'` (PostgreSQL and SQLite 3.30+). */
+    syntax?: 'case' | 'filter';
+};
+export type TableHelperArrayAggOptions<T> = {
+    /** `array_agg(DISTINCT column)`: each value once. Then `orderBy` can only be the aggregated column. */
+    distinct?: boolean;
+    /** Orders the array by a column of the helper's table, ascending or in the given direction. */
+    orderBy?: AggregateOrder<T>;
+    /** Aggregates only the rows that match, e.g. `images.isNotNull('id')` after a LEFT JOIN without a match. */
+    filter?: string;
+};
+/** A column of the helper's table whose property is a `Date`. */
+type DateColumnName<T> = {
+    [K in keyof T & string]: [NonNullable<T[K]>] extends [Date] ? K : never;
+}[keyof T & string];
+/** A date column of the helper's table, or an SQL expression: `{ sql: 'MAX("order"."paidAt")' }`. */
+export type TableHelperExpression<T> = DateColumnName<T> | {
+    sql: string;
+};
+/**
+ * A time zone: a name or an ISO 8601 offset (`'Europe/Kyiv'`, `'UTC'`, `'+02:00'` = UTC+2), written into the SQL as an escaped string
+ * literal; a column of the helper's table, `{ column: 'timezone' }`, with an optional `fallback` zone for `NULL`;
+ * or an SQL expression, `{ sql: services.column('timezone') }`.
+ */
+export type TableHelperTimeZone<T> = string | {
+    column: ColumnName<T>;
+    fallback?: string;
+} | {
+    sql: string;
+};
+/** The units of PostgreSQL's `date_trunc`. */
+export type DateTruncUnit = 'microseconds' | 'milliseconds' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'decade' | 'century' | 'millennium';
 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,
@@ -51,7 +107,8 @@ export declare const tableHelper: <T extends ObjectLiteral>(alias?: string, opti
     /** 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`.
+     * 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
@@ -62,6 +119,41 @@ export declare const tableHelper: <T extends ObjectLiteral>(alias?: string, opti
      * // CAST(COUNT(*) FILTER (WHERE "user"."status" = 'active') AS integer)
      */
     count(columnName?: keyof T | undefined, countOptions?: TableHelperCountOptions): string;
+    /**
+     * 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: NumericColumnName<T>, sumOptions?: TableHelperSumOptions): string;
+    /**
+     * 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: ColumnName<T>, aggOptions?: TableHelperArrayAggOptions<T>): string;
+    /**
+     * 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: readonly ColumnName<T>[] | Readonly<Record<string, ColumnName<T>>>, jsonOptions?: TableHelperJsonOptions): string;
+    /**
+     * 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: string, aggOptions?: TableHelperJsonAggOptions<T>): string;
     /** Returns `CAST(expression AS type)`. */
     cast(expression: string, type: string): string;
     /**
@@ -82,5 +174,23 @@ export declare const tableHelper: <T extends ObjectLiteral>(alias?: string, opti
      * 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;
+    /**
+     * 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: TableHelperExpression<T>, timeZone: TableHelperTimeZone<T>): string;
+    /**
+     * 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: DateTruncUnit, value: TableHelperExpression<T>, timeZone?: TableHelperTimeZone<T> | undefined): string;
 };
 export {};