typeorm-extensions 2.1.0 → 2.2.0-rc.1

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

@@ -7,9 +7,9 @@ class KeyHolder {
         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) {
@@ -109,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,4 +1,5 @@
 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';
 /**
@@ -7,6 +8,11 @@ import { JsonPathSqlOptions } from './json-path.utils';
  * 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', …)`).
  *
@@ -32,6 +38,8 @@ export declare function toFieldSql(builder: WhereExpressionBuilder, field: strin
  * 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>, 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:

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

@@ -1,6 +1,6 @@
 "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");
@@ -54,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', …)`).
  *
@@ -131,11 +146,17 @@ function findColumnPath(metadata, keys) {
  * 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) {
@@ -213,6 +234,13 @@ function getTypedColumnKey(builder, callback, jsonOptions) {
     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:
@@ -242,7 +270,7 @@ function getTypedSelectionKey(builder, selection, useQuotes) {
         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 and distinct take columns only. For an expression use tableHelper().jsonColumn()`);
+                `select, order, distinct and group by take columns only. For an expression use tableHelper().jsonColumn()`);
         }
         if (useQuotes) {
             return toQuotedColumnKey(queryBuilder, resolved);

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 {};

package/dist/utils/table.utils.js

@@ -3,6 +3,105 @@ 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");
+/**
+ * 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}` : ''}` };
+}
+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}"`);
+    }
+}
+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.
@@ -20,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('.');
     },
@@ -61,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
@@ -76,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}"`);
+        }
+        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');
         }
-        return this.cast(expression, 'integer');
+        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) {
@@ -119,6 +283,37 @@ const tableHelper = (alias, options = {}) => ({
      */
     jsonPath(_columnName, jsonOperator, ...fieldNames) {
         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;