typeorm-extensions 2.1.0 → 2.2.0-rc.1

package/dist/extensions/where-exists.extension.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachExists = void 0;
+const typeorm_1 = require("typeorm");
+const SoftDeleteQueryBuilder_1 = require("typeorm/query-builder/SoftDeleteQueryBuilder");
+const prototype_utils_1 = require("../utils/prototype.utils");
+const parameter_utils_1 = require("../utils/parameter.utils");
+const existsMethods = {
+    prototype: {
+        whereExists(subQuery) {
+            return attachExists(this, 'where', subQuery, false);
+        },
+        andWhereExists(subQuery) {
+            return attachExists(this, 'andWhere', subQuery, false);
+        },
+        orWhereExists(subQuery) {
+            return attachExists(this, 'orWhere', subQuery, false);
+        },
+    },
+};
+const notExistsMethods = {
+    prototype: {
+        whereNotExists(subQuery) {
+            return attachExists(this, 'where', subQuery, true);
+        },
+        andWhereNotExists(subQuery) {
+            return attachExists(this, 'andWhere', subQuery, true);
+        },
+        orWhereNotExists(subQuery) {
+            return attachExists(this, 'orWhere', subQuery, true);
+        },
+    },
+};
+// only where the builder lacks them: SelectQueryBuilder keeps TypeORM's own whereExists /
+// andWhereExists / orWhereExists, and a later TypeORM that adds any of these keeps its own
+[typeorm_1.SelectQueryBuilder, typeorm_1.UpdateQueryBuilder, typeorm_1.DeleteQueryBuilder, SoftDeleteQueryBuilder_1.SoftDeleteQueryBuilder].forEach((builder) => {
+    (0, prototype_utils_1.patchPrototype)(builder, existsMethods, { onlyMissing: true });
+    (0, prototype_utils_1.patchPrototype)(builder, notExistsMethods, { onlyMissing: true });
+});
+// implementation
+function attachExists(builder, method, subQuery, negate) {
+    const [condition, parameters] = (0, parameter_utils_1.withUniqueParameterNames)(...getExistsCondition(subQuery));
+    return builder[method](negate ? `NOT ${condition}` : condition, parameters);
+}
+exports.attachExists = attachExists;
+/**
+ * TypeORM's EXISTS condition: the subquery selects 1, without ORDER BY, LIMIT and OFFSET. TypeORM also
+ * drops GROUP BY, which leaves a HAVING to aggregate the whole subquery: the GROUP BY stays with one.
+ */
+function getExistsCondition(subQuery) {
+    const query = subQuery
+        .clone()
+        .orderBy()
+        .offset(undefined)
+        .limit(undefined)
+        .skip(undefined)
+        .take(undefined)
+        .select('1')
+        .setOption('disable-global-order');
+    if (query.expressionMap.havings.length === 0) {
+        query.groupBy();
+    }
+    return [`EXISTS (${query.getQuery()})`, query.getParameters()];
+}

package/dist/extensions/where-relation-exists.extension.d.ts

@@ -0,0 +1,38 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import type { DeepUnwrapArray, KeyPathEnd } from '../types/modules/proxy-callback.types';
+import type { TypedRoot } from '../types/modules/typed-root.types';
+/**
+ * The relation to look in, selected by a typed callback: `user => user.images`. A relation of a joined alias
+ * (`joins => joins.owner.images`) ends the key path, so its entity type isn't known: pass it as `Related`.
+ */
+type RelationSelection<Type, Related> = (proxy: DeepUnwrapArray<Type>) => Related | KeyPathEnd | null | undefined;
+/** Narrows the rows of the related entity: `images => images.andWhere('images.url IS NOT NULL')`. */
+type RelatedCondition<Related extends ObjectLiteral> = (subQuery: SelectQueryBuilder<Related>) => unknown;
+/**
+ * `EXISTS` / `NOT EXISTS` over a relation of an entity, with the join condition taken from the relation's
+ * metadata: `andWhereRelationExists(user => user.images, 'image', (images) => images.andWhere(…))` gives
+ * `EXISTS (SELECT 1 FROM "images" "image" WHERE … AND "image"."userId" = "user"."id")`. Works for
+ * one-to-many, many-to-one, one-to-one and many-to-many (through the junction table) relations.
+ *
+ * `alias` names the related entity in the subquery and must not be an alias of the outer query.
+ * The subquery's parameters get unique names, as in `whereNotExists`.
+ */
+export interface WhereRelationExistsMethods<Entity extends ObjectLiteral> {
+    /** Sets `WHERE EXISTS (…)` over the relation, replacing the WHERE conditions set before. */
+    whereRelationExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    /** Adds `AND EXISTS (…)` over the relation. */
+    andWhereRelationExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    /** Adds `OR EXISTS (…)` over the relation. */
+    orWhereRelationExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    /** Sets `WHERE NOT EXISTS (…)` over the relation, replacing the WHERE conditions set before. */
+    whereRelationNotExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    /** Adds `AND NOT EXISTS (…)` over the relation. */
+    andWhereRelationNotExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    /** Adds `OR NOT EXISTS (…)` over the relation. */
+    orWhereRelationNotExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+}
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+    interface SelectQueryBuilder<Entity extends ObjectLiteral> extends WhereRelationExistsMethods<Entity> {
+    }
+}
+export {};

package/dist/extensions/where-relation-exists.extension.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const typeorm_1 = require("typeorm");
+const where_exists_extension_1 = require("./where-exists.extension");
+const prototype_utils_1 = require("../utils/prototype.utils");
+const query_builder_utils_1 = require("../utils/query-builder.utils");
+const where_utils_1 = require("../utils/where.utils");
+const createMethod = (method, negate) => function (relation, alias, where) {
+    return attachRelationExists(this, method, negate, relation, alias, where);
+};
+const extension = {
+    prototype: {
+        whereRelationExists: createMethod('where', false),
+        andWhereRelationExists: createMethod('andWhere', false),
+        orWhereRelationExists: createMethod('orWhere', false),
+        whereRelationNotExists: createMethod('where', true),
+        andWhereRelationNotExists: createMethod('andWhere', true),
+        orWhereRelationNotExists: createMethod('orWhere', true),
+    },
+};
+(0, prototype_utils_1.patchPrototype)(typeorm_1.SelectQueryBuilder, extension);
+// implementation
+function attachRelationExists(builder, method, negate, relationSelection, alias, where) {
+    const methodName = `${method}Relation${negate ? 'Not' : ''}Exists`;
+    const key = (0, query_builder_utils_1.getTypedSelectionKey)(builder, relationSelection);
+    if (Array.isArray(key)) {
+        throw new TypeError(`${methodName} expects the callback to select one relation, got ${key.length}: ${key.join(', ')}`);
+    }
+    const dot = key.indexOf('.');
+    const ownerAlias = key.slice(0, dot);
+    const propertyPath = key.slice(dot + 1);
+    const aliases = queryAliases(builder);
+    const owner = aliases.find((candidate) => candidate.name === ownerAlias);
+    const relation = (owner === null || owner === void 0 ? void 0 : owner.hasMetadata) ? owner.metadata.findRelationWithPropertyPath(propertyPath) : undefined;
+    if (!relation) {
+        throw new TypeError(`${methodName}: ${key} is not a relation of an entity of the query`);
+    }
+    // in the subquery the alias would hide the outer one the join condition refers to; SQLite matches
+    // names without case, so 'USER' would hide 'user' there
+    if (aliases.some((candidate) => candidate.name.toLowerCase() === alias.toLowerCase())) {
+        throw new TypeError(`${methodName}: the alias "${alias}" is already used by the query, choose another one`);
+    }
+    const column = (aliasName, columnName) => `${builder.escape(aliasName)}.${builder.escape(columnName)}`;
+    const subQuery = builder.connection
+        .createQueryBuilder()
+        .select('1')
+        .from(relation.inverseEntityMetadata.target, alias);
+    const correlation = joinCondition(relation, ownerAlias, alias, column, subQuery);
+    where === null || where === void 0 ? void 0 : where(subQuery);
+    // after the caller's conditions, so a `where` or an `orWhere` of theirs can't drop or bypass it
+    (0, where_utils_1.andWhereNarrowing)(subQuery, correlation);
+    return (0, where_exists_extension_1.attachExists)(builder, method, subQuery, negate);
+}
+/**
+ * The aliases of the query and of the queries it is part of. Inside `Brackets` the builder has the outer
+ * query's main alias but none of its joins: those are on its parent.
+ */
+function queryAliases(builder) {
+    const aliases = [];
+    // parentQueryBuilder is protected in TypeORM's types
+    let query = builder;
+    for (; query; query = query.parentQueryBuilder) {
+        const { aliases: own, mainAlias } = query.expressionMap;
+        aliases.push(...own, ...(mainAlias ? [mainAlias] : []));
+    }
+    return aliases;
+}
+const equal = (left, right) => `${left} = ${right}`;
+/** The condition between the related rows (`alias`) and the outer row (`ownerAlias`); joins the junction table of a many-to-many. */
+function joinCondition(relation, ownerAlias, alias, column, subQuery) {
+    var _a;
+    const referenced = (joinColumn) => joinColumn.referencedColumn.databaseName;
+    if (relation.isManyToMany) {
+        const junctionAlias = `${alias}_junction`;
+        // the owning side defines the junction table; from the other side its columns swap roles
+        const inverse = relation.inverseRelation;
+        const [ownerColumns, relatedColumns] = relation.isOwning
+            ? [relation.joinColumns, relation.inverseJoinColumns]
+            : [inverse.inverseJoinColumns, inverse.joinColumns];
+        subQuery.innerJoin(((_a = relation.junctionEntityMetadata) !== null && _a !== void 0 ? _a : inverse.junctionEntityMetadata).target, junctionAlias, relatedColumns.map((joinColumn) => equal(column(alias, referenced(joinColumn)), column(junctionAlias, joinColumn.databaseName))).join(' AND '));
+        return ownerColumns
+            .map((joinColumn) => equal(column(junctionAlias, joinColumn.databaseName), column(ownerAlias, referenced(joinColumn))))
+            .join(' AND ');
+    }
+    // the join columns are on the outer entity's table
+    if (relation.isManyToOne || relation.isOneToOneOwner) {
+        return relation.joinColumns
+            .map((joinColumn) => equal(column(alias, referenced(joinColumn)), column(ownerAlias, joinColumn.databaseName)))
+            .join(' AND ');
+    }
+    // one-to-many, or the inverse side of a one-to-one: the join columns are on the related table
+    return relation.inverseRelation.joinColumns
+        .map((joinColumn) => equal(column(alias, joinColumn.databaseName), column(ownerAlias, referenced(joinColumn))))
+        .join(' AND ');
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './extensions';
+export * from './decorators';
 export * from './types/interfaces';
 export * from './types/extensions';
 export type { Json } from './types/modules/proxy-callback.types';
+export type { TypedRoot, WithTypedRoot } from './types/modules/typed-root.types';
 export * from './utils/table.utils';
 export { escapeLikePattern } from './utils/search.utils';

package/dist/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.escapeLikePattern = void 0;
 __exportStar(require("./extensions"), exports);
+__exportStar(require("./decorators"), exports);
 __exportStar(require("./types/interfaces"), exports);
 __exportStar(require("./types/extensions"), exports);
 __exportStar(require("./utils/table.utils"), exports);

package/dist/types/extensions/cursor-pagination.types.d.ts

@@ -13,4 +13,9 @@ export interface ListWithCursor<Entity> {
     list: Entity[];
     /** Cursor of the next page, `null` on the last page. */
     nextCursor: string | null;
+    /**
+     * Whether a next page follows. Always known, unlike the `hasMore` of `getManyWithTotals`: the
+     * keyset query loads `pageSize + 1` rows, so it needs no total. Equivalent to `nextCursor !== null`.
+     */
+    hasMore: boolean;
 }

package/dist/types/extensions/get-many-with-totals.types.d.ts

@@ -1,12 +1,31 @@
+import type { OrderType } from '../interfaces/ordering.interface';
 import type { ApplyPaginationOptions } from './pagination.types';
 /** Also takes the pagination options, e.g. `useTakeAndSkip` for queries with joined collections. */
 export type GetManyWithTotalsOptions = ApplyPaginationOptions & {
     disableTotalsCalculation?: boolean;
     loadAll?: boolean;
 };
+/** Options of `getRawManyWithTotals`. Raw rows are paged with LIMIT / OFFSET, so there is no `useTakeAndSkip`. */
+export type GetRawManyWithTotalsOptions = Omit<GetManyWithTotalsOptions, 'useTakeAndSkip'> & {
+    /**
+     * An expression that counts the rows of the query by itself, such as `COUNT(DISTINCT "order"."user_id")`
+     * for a query grouped by `"order"."user_id"`: cheaper than counting the query as a subquery.
+     * It replaces the select list, and GROUP BY, HAVING and DISTINCT are dropped: it can't count a query with HAVING,
+     * and counts a DISTINCT query only when it is a `COUNT(DISTINCT …)` itself.
+     */
+    countExpression?: string;
+};
 export interface ListWithTotals<Entity> {
     list: Entity[];
     total: number | null;
     limit: number | null;
     offset: number | null;
+    /**
+     * Whether rows follow the page. `null` only with `loadAll`, where the page is every row.
+     * With `disableTotalsCalculation` it is still known: one row past the page is loaded and dropped,
+     * instead of counting.
+     */
+    hasMore: boolean | null;
+    /** The ORDER BY clauses the query was built with, in the order they were applied. */
+    orderBy: OrderType[];
 }

package/dist/types/extensions/index.d.ts

@@ -1,8 +1,13 @@
 export * from './pagination.types';
 export * from './order.types';
 export * from './typed-order-by.types';
+export * from './typed-group-by.types';
 export * from './get-many-with-totals.types';
 export * from './where.types';
 export * from './period.types';
 export * from './cursor-pagination.types';
 export * from './search.types';
+export * from './typed-having.types';
+export * from './union.types';
+export * from './join-lateral.types';
+export * from './query-returning.types';

package/dist/types/extensions/index.js

@@ -17,8 +17,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./pagination.types"), exports);
 __exportStar(require("./order.types"), exports);
 __exportStar(require("./typed-order-by.types"), exports);
+__exportStar(require("./typed-group-by.types"), exports);
 __exportStar(require("./get-many-with-totals.types"), exports);
 __exportStar(require("./where.types"), exports);
 __exportStar(require("./period.types"), exports);
 __exportStar(require("./cursor-pagination.types"), exports);
 __exportStar(require("./search.types"), exports);
+__exportStar(require("./typed-having.types"), exports);
+__exportStar(require("./union.types"), exports);
+__exportStar(require("./join-lateral.types"), exports);
+__exportStar(require("./query-returning.types"), exports);

package/dist/types/extensions/join-lateral.types.d.ts

@@ -0,0 +1,6 @@
+import type { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+/**
+ * The subquery of a LATERAL join: raw SQL (`SELECT … LIMIT 1`, without parentheses), a query
+ * builder, or a factory that builds it on the query builder it is given, as for TypeORM's joins.
+ */
+export type LateralSubQuery<SubEntity extends ObjectLiteral = ObjectLiteral> = string | SelectQueryBuilder<SubEntity> | ((qb: SelectQueryBuilder<ObjectLiteral>) => SelectQueryBuilder<SubEntity>);

package/dist/types/extensions/join-lateral.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/extensions/period.types.d.ts

@@ -12,4 +12,12 @@ export type ApplyPeriodOptions = {
      * `{ periodFrom: '2024-01-01', periodTo: '2024-02-01' }`.
      */
     includeTo?: boolean;
+    /**
+     * IANA time zone (`'America/New_York'`) in which a date (`'2024-01-31'`) and a date-time without an offset
+     * (`'2024-01-31 10:00'`) are read: `periodTo: '2024-01-31'` ends at midnight of February 1st in that zone.
+     * They become instants (`Date`), so it is for timestamp columns, not `date` ones. `Date`s and strings with
+     * an offset are instants already and stay as they are; other strings throw a `TypeError`, as does an
+     * unknown zone. Missing, `null` or `''`: the strings go to the database as they are.
+     */
+    timeZone?: string | null;
 };

package/dist/types/extensions/query-returning.types.d.ts

@@ -0,0 +1,11 @@
+import type { ObjectLiteral } from 'typeorm';
+/** What `queryReturning` resolves to: the same shape for every statement and every driver. */
+export interface QueryReturningResult<Row = ObjectLiteral> {
+    /** The rows the statement returned: those of a SELECT, or of a `RETURNING` clause. Empty when there are none. */
+    records: Row[];
+    /**
+     * The number of rows the driver reports for the statement, `null` when it reports none.
+     * SQLite reports none for a statement that returns rows, such as an UPDATE with `RETURNING`.
+     */
+    affected: number | null;
+}

package/dist/types/extensions/query-returning.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/extensions/typed-group-by.types.d.ts

@@ -0,0 +1,8 @@
+export type TypedGroupByOptions = {
+    /**
+     * Group by the quoted database column (`"ticket"."ticket_status"`) instead of `ticket.status`,
+     * which TypeORM maps to the column itself. TypeORM maps only aliases with metadata, so a subquery
+     * in FROM needs it on PostgreSQL, where an unquoted `sub.firstName` is folded to `firstname`.
+     */
+    useQuotes?: boolean;
+};

package/dist/types/extensions/typed-group-by.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/extensions/typed-having.types.d.ts

@@ -0,0 +1,2 @@
+/** The aggregate of `havingTyped`: `'COUNT DISTINCT'` is `COUNT(DISTINCT column)`. */
+export type TypedAggregate = 'COUNT' | 'COUNT DISTINCT' | 'SUM' | 'AVG' | 'MIN' | 'MAX';

package/dist/types/extensions/typed-having.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/extensions/union.types.d.ts

@@ -0,0 +1,12 @@
+import type { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+/** A part of a UNION: a query builder, or raw SQL whose placeholders read the outer builder's parameters. */
+export type UnionQuery = string | {
+    getQuery(): string;
+    getParameters(): ObjectLiteral;
+};
+export type UnionOptions = {
+    /** `UNION ALL`: keep duplicate rows. Defaults to `false`, `UNION`, which removes them. */
+    all?: boolean;
+};
+/** TypeORM's options of `addCommonTableExpression` (`materialized`, `columnNames`), and `all`. */
+export type UnionCteOptions = UnionOptions & NonNullable<Parameters<SelectQueryBuilder<ObjectLiteral>['addCommonTableExpression']>[2]>;

package/dist/types/extensions/union.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/extensions/where.types.d.ts

@@ -1,3 +1,4 @@
 export type WhereMethods = 'where' | 'andWhere' | 'orWhere';
+export type HavingMethods = 'having' | 'andHaving' | 'orHaving';
 export type WhereInMethods = 'whereIsIn' | 'andWhereIsIn' | 'orWhereIsIn' | 'whereIsNotIn' | 'andWhereIsNotIn' | 'orWhereIsNotIn';
 export type WhereAnyMethods = 'whereIsAny' | 'andWhereIsAny' | 'orWhereIsAny' | 'whereIsNotAny' | 'andWhereIsNotAny' | 'orWhereIsNotAny';

package/dist/types/modules/typed-root.types.d.ts

@@ -0,0 +1,17 @@
+import type { ObjectLiteral } from 'typeorm';
+declare const typedRoot: unique symbol;
+declare class TypedRootMark<Root> {
+    [typedRoot]?(): Root;
+}
+/**
+ * The entity type of a builder whose typed callbacks take another root, set with `typed<Root>()`: the entity
+ * with an optional symbol method that only types carry. Entities loaded with it are plain entities.
+ */
+export type WithTypedRoot<Entity, Root extends ObjectLiteral> = Entity & TypedRootMark<Root>;
+/**
+ * The root of a builder's typed callbacks: the one set with `typed<Root>()`, or else its entity. The key check
+ * comes first: without `strictNullChecks` an entity with an index signature (`ObjectLiteral`) matches the
+ * optional mark too, and its root would be inferred as `unknown`.
+ */
+export type TypedRoot<Entity> = typeof typedRoot extends keyof Entity ? Entity extends TypedRootMark<infer Root> ? Root extends ObjectLiteral ? Root : Entity : Entity : Entity;
+export {};

package/dist/types/modules/typed-root.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/calculated-column.utils.d.ts

@@ -0,0 +1,21 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+type ResolvedCalculatedColumn = {
+    /** The key TypeORM reads the column's value from when it builds the entity. */
+    key: string;
+    /** `Entity.property`, for error messages. */
+    label: string;
+};
+/** Whether `property` of the entity of `aliasName` (the main alias by default) is a `@CalculatedColumn`. */
+export declare function isCalculatedColumn<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, property: string, aliasName?: string): boolean;
+/** The `@CalculatedColumn` `property` of the entity of `aliasName`; throws a `TypeError` for anything else. */
+export declare function resolveCalculatedColumn<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, property: string, aliasName: string | undefined, methodName: string): ResolvedCalculatedColumn;
+/**
+ * Selects the value of a `@CalculatedColumn`, already selected with `addSelectCalculated`, a second
+ * time under a generated lower-case alias, and returns the alias to order by.
+ *
+ * The alias the entity is built from can't be ordered by: PostgreSQL folds it unquoted
+ * (`user_imagesCount` → `user_imagescount`), and quoted it breaks the DISTINCT query TypeORM pages
+ * through with `take` / `skip` and joins, which takes only select aliases it knows unquoted.
+ */
+export declare function selectCalculatedForOrder<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, property: string, aliasName: string | undefined, methodName: string): string;
+export {};

package/dist/utils/calculated-column.utils.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectCalculatedForOrder = exports.resolveCalculatedColumn = exports.isCalculatedColumn = void 0;
+const DriverUtils_1 = require("typeorm/driver/DriverUtils");
+const sql_utils_1 = require("./sql.utils");
+function findCalculatedColumn(builder, property, aliasName) {
+    const { expressionMap } = builder;
+    const alias = aliasName === undefined
+        ? expressionMap.mainAlias
+        : expressionMap.aliases.find((candidate) => candidate.name === aliasName);
+    if (!(alias === null || alias === void 0 ? void 0 : alias.hasMetadata)) {
+        return undefined;
+    }
+    return {
+        aliasName: alias.name,
+        entityName: alias.metadata.name,
+        column: alias.metadata.findColumnWithPropertyPath(property),
+    };
+}
+// @CalculatedColumn: a virtual property without the query of TypeORM's @VirtualColumn
+const isCalculated = (column) => !!(column === null || column === void 0 ? void 0 : column.isVirtualProperty) && !column.query;
+/** Whether `property` of the entity of `aliasName` (the main alias by default) is a `@CalculatedColumn`. */
+function isCalculatedColumn(builder, property, aliasName) {
+    var _a;
+    return isCalculated((_a = findCalculatedColumn(builder, property, aliasName)) === null || _a === void 0 ? void 0 : _a.column);
+}
+exports.isCalculatedColumn = isCalculatedColumn;
+/** The `@CalculatedColumn` `property` of the entity of `aliasName`; throws a `TypeError` for anything else. */
+function resolveCalculatedColumn(builder, property, aliasName, methodName) {
+    var _a;
+    const found = findCalculatedColumn(builder, property, aliasName);
+    if (!found) {
+        throw new TypeError(`${methodName}: the alias "${aliasName !== null && aliasName !== void 0 ? aliasName : (_a = builder.expressionMap.mainAlias) === null || _a === void 0 ? void 0 : _a.name}" has no entity with "${property}"`);
+    }
+    const label = `${found.entityName}.${property}`;
+    if (!isCalculated(found.column)) {
+        throw new TypeError(`${methodName}: ${label} is not a @CalculatedColumn`);
+    }
+    // shortened past the driver's alias length limit, as TypeORM does it
+    const key = DriverUtils_1.DriverUtils.buildAlias(builder.connection.driver, {}, found.aliasName, found.column.databaseName);
+    return { key, label };
+}
+exports.resolveCalculatedColumn = resolveCalculatedColumn;
+/**
+ * Selects the value of a `@CalculatedColumn`, already selected with `addSelectCalculated`, a second
+ * time under a generated lower-case alias, and returns the alias to order by.
+ *
+ * The alias the entity is built from can't be ordered by: PostgreSQL folds it unquoted
+ * (`user_imagesCount` → `user_imagescount`), and quoted it breaks the DISTINCT query TypeORM pages
+ * through with `take` / `skip` and joins, which takes only select aliases it knows unquoted.
+ */
+function selectCalculatedForOrder(builder, property, aliasName, methodName) {
+    const { key, label } = resolveCalculatedColumn(builder, property, aliasName, methodName);
+    const select = builder.expressionMap.selects.find((candidate) => candidate.aliasName === key);
+    if (!select) {
+        throw new TypeError(`${methodName}: ${label} isn't selected: select it with addSelectCalculated first`);
+    }
+    const orderAlias = (0, sql_utils_1.createUniqueParameterName)('calculated').toLowerCase();
+    // TypeORM keeps a subquery selection as its SQL, with its parameters already on the builder
+    builder.addSelect(select.selection, orderAlias);
+    return orderAlias;
+}
+exports.selectCalculatedForOrder = selectCalculatedForOrder;

package/dist/utils/parameter.utils.d.ts

@@ -0,0 +1,7 @@
+import type { ObjectLiteral } from 'typeorm';
+/**
+ * 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.
+ */
+export declare function withUniqueParameterNames(sql: string, parameters: ObjectLiteral): [string, ObjectLiteral];

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;
@@ -37,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[];