typeorm-extensions 2.0.0 → 2.2.0-rc.0

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,5 +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/interfaces/config.interface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Compile-time options of the library, switched on by augmenting this interface in your project:
+ *
+ * ```ts
+ * declare module 'typeorm-extensions' {
+ *   interface TypeormExtensionsConfig {
+ *     strictParams: true;
+ *   }
+ * }
+ * ```
+ *
+ * - `strictParams`: typed where methods check their value against the type of the column the callback
+ *   selects (`whereTyped(q => q.price, '>', '10')` doesn't compile for a `number` column). Applies to calls
+ *   without an explicit type argument: `whereTyped<Joins>(…)` keeps unchecked parameters.
+ */
+export interface TypeormExtensionsConfig {
+}

package/dist/types/interfaces/config.interface.js

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

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

@@ -2,3 +2,4 @@ export * from './ordering.interface';
 export * from './pagination.interface';
 export * from './period.interface';
 export * from './cursor-pagination.interface';
+export * from './config.interface';

package/dist/types/interfaces/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./ordering.interface"), exports);
 __exportStar(require("./pagination.interface"), exports);
 __exportStar(require("./period.interface"), exports);
 __exportStar(require("./cursor-pagination.interface"), exports);
+__exportStar(require("./config.interface"), exports);

package/dist/types/modules/proxy-callback.types.d.ts

@@ -4,25 +4,49 @@ import { ColumnValueType } from "./column.types";
 import { UnwrapArray } from "../util-types";
 export type ProxyColumnValueType = ColumnValueType | ':value';
 type ProxyPropertyType<V> = NonNullable<V> extends readonly (infer U)[] ? NonNullable<U> : NonNullable<V>;
+/** Objects that are column values, not relations or JSON objects to go into. */
+type ProxyLeafObject = Date | ArrayBufferView | ArrayBuffer;
+type IsProxyBranch<V> = ProxyPropertyType<V> extends ProxyLeafObject ? false : ProxyPropertyType<V> extends object ? true : false;
+declare const jsonColumn: unique symbol;
+/**
+ * Marks an entity property as a JSON column for typed callbacks, which then go into it at any depth:
+ * `(e) => e.details.meta.endTs` is `"e"."details" -> 'meta' ->> 'endTs'` in where methods. Without it a typed key
+ * stops at `alias.column` (`e.details.outcome`), as it does for relations. Values are assignable both ways.
+ *
+ * @example
+ * @Column({ type: 'jsonb' })
+ * details: Json<ExecutionDetails>;
+ */
+export type Json<T> = T & {
+    readonly [jsonColumn]?: true;
+};
+type IsJsonColumn<V> = typeof jsonColumn extends keyof NonNullable<V> ? true : false;
+type IsJsonObject<V> = NonNullable<V> extends ProxyLeafObject | readonly unknown[] ? false : NonNullable<V> extends object ? true : false;
+/** Inside a JSON column: objects to go into at any depth, while arrays and dates are values. */
+type JsonPathProxy<T> = {
+    [K in keyof T as K extends typeof jsonColumn ? never : K]-?: IsJsonObject<T[K]> extends true ? JsonPathProxy<NonNullable<T[K]>> : T[K];
+};
+type JsonColumnProxy<V> = NonNullable<V> extends readonly unknown[] ? V : JsonPathProxy<NonNullable<V>>;
 /**
  * End of a typed key path. Typed keys are `column` or `alias.column` (`relation.column`),
  * so an object at the second level (a nested relation, a JSON sub-object) can be selected
  * as a whole but not dereferenced further: `u => u.images.user.email` is a compile error.
- * Address deeper relations by their join alias with an alias-keyed type instead.
+ * Address deeper relations by their join alias with an alias-keyed type instead, and mark
+ * JSON columns with {@link Json} to go deeper into them.
  */
 export interface KeyPathEnd {
     readonly __keyPathEnd: never;
 }
 type ProxySecondLevel<T> = {
-    [K in keyof T]-?: ProxyPropertyType<T[K]> extends object ? KeyPathEnd : T[K];
+    [K in keyof T]-?: IsJsonColumn<T[K]> extends true ? JsonColumnProxy<T[K]> : IsProxyBranch<T[K]> extends true ? KeyPathEnd : T[K];
 };
 /**
  * Type of the proxy passed to typed callbacks: two levels (`column` or `alias.column`),
  * with arrays unwrapped (`user.images.url` for `images: ImageEntity[]`) and optional
- * properties made required.
+ * properties made required. A {@link Json} column is open at any depth.
  */
 export type DeepUnwrapArray<T> = {
-    [K in keyof T]-?: ProxyPropertyType<T[K]> extends object ? ProxySecondLevel<ProxyPropertyType<T[K]>> : T[K];
+    [K in keyof T]-?: IsJsonColumn<T[K]> extends true ? JsonColumnProxy<T[K]> : IsProxyBranch<T[K]> extends true ? ProxySecondLevel<ProxyPropertyType<T[K]>> : T[K];
 };
 export type KeyProxyCallback<T extends ObjectLiteral> = (proxy: DeepUnwrapArray<T>) => ProxyColumnValueType | Array<ProxyColumnValueType>;
 export type RelationalKeyProxyCallback<T extends ObjectLiteral> = (proxy: DeepUnwrapArray<EntityOnlyWithRelations<T>>) => ProxyColumnValueType;

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

@@ -0,0 +1,45 @@
+import type { TypeormExtensionsConfig } from '../interfaces/config.interface';
+import type { TypedWhereOptions } from '../extensions/typed-where.types';
+import type { ArgsType } from '../util-types';
+declare const unsetType: unique symbol;
+/**
+ * Default of the `Type` argument of typed methods. Tells a call without a type argument, whose proxy is
+ * typed by the query builder's entity, from an explicit `whereTyped<Joins>(…)`.
+ */
+export interface UnsetType {
+    readonly [unsetType]: true;
+}
+/** Blocks inference from this position, so the column type comes from the callback alone (`NoInfer` before TypeScript 5.4). */
+type NoInferType<T> = [T][T extends unknown ? 0 : never];
+/** Whether `Type` was left out; an explicit `<any>` is assignable to `UnsetType` but was given. */
+type IsUnset<Type> = 0 extends 1 & Type ? false : [Type] extends [UnsetType] ? true : false;
+export type TypeOrDefault<Type, Default> = IsUnset<Type> extends true ? Default : Type;
+type IsStrict<Type> = TypeormExtensionsConfig extends {
+    strictParams: true;
+} ? IsUnset<Type> : false;
+/** A column's value as a parameter: never `null` / `undefined` (they turn `= :value` into `= NULL`); a date may be a string. */
+export type ParamValue<Value> = NonNullable<Value> extends Date ? Date | string : NonNullable<Value>;
+type IsValueObject<P> = [P] extends [Date | ArrayBufferView | ArrayBuffer | readonly unknown[]] ? true : false;
+/**
+ * The value itself, or a `{ name: value }` params object. A plain object value (a JSON column) can only be
+ * passed in a params object: at runtime a plain object always is one.
+ */
+type DirectOrField<P> = [P] extends [object] ? IsValueObject<P> extends true ? P | Readonly<Record<string, P>> : Readonly<Record<string, P>> : P | Readonly<Record<string, P>>;
+type Trim<S extends string> = S extends ` ${infer Rest}` ? Trim<Rest> : S extends `${infer Rest} ` ? Trim<Rest> : S;
+type NoValueOperator = 'IS NULL' | 'IS NOT NULL' | 'IS TRUE' | 'IS NOT TRUE' | 'IS FALSE' | 'IS NOT FALSE' | 'IS UNKNOWN' | 'IS NOT UNKNOWN';
+type ComparisonOperator = '=' | '!=' | '<>' | '>' | '<' | '>=' | '<=';
+type DistinctOperator = 'IS DISTINCT FROM' | 'IS NOT DISTINCT FROM';
+type NullOperator = 'IS' | 'IS NOT';
+type ListOperator = 'IN' | 'NOT IN';
+type PatternOperator = 'LIKE' | 'NOT LIKE' | 'ILIKE' | 'NOT ILIKE';
+type LooseWhereArgs = [parameters?: unknown, options?: TypedWhereOptions];
+type ValueArgs<P> = [parameters: DirectOrField<P>, options?: TypedWhereOptions];
+type StrictWhereArgs<Operator extends string, Value> = Uppercase<Trim<Operator>> extends infer Op ? Op extends NoValueOperator ? [parameters?: undefined, options?: TypedWhereOptions] : Op extends ComparisonOperator ? ValueArgs<ParamValue<Value>> : Op extends DistinctOperator ? ValueArgs<ParamValue<Value> | null> : Op extends NullOperator ? ValueArgs<null> : Op extends ListOperator ? ValueArgs<readonly ParamValue<Value>[]> : Op extends PatternOperator ? ValueArgs<string> : LooseWhereArgs : never;
+/**
+ * Parameters and options of `whereTyped`. With `strictParams` the parameter is checked against the column type
+ * for the operators it knows; conditions written as SQL (`'BETWEEN :from AND :to'`, `'= true'`) aren't checked.
+ */
+export type TypedWhereArgs<Type, Operator extends string, Value> = IsStrict<Type> extends true ? StrictWhereArgs<NoInferType<Operator>, NoInferType<Value>> : LooseWhereArgs;
+/** Values of `whereIsInTyped` / `whereIsAnyTyped`; with `strictParams`, of the column's type. */
+export type TypedArrayArg<Type, Value> = IsStrict<Type> extends true ? readonly ParamValue<NoInferType<Value>>[] : ArgsType;
+export {};

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

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

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

@@ -0,0 +1,13 @@
+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. */
+export type TypedRoot<Entity> = Entity extends TypedRootMark<infer Root> ? Root extends ObjectLiteral ? Root : 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/json-path.utils.d.ts

@@ -0,0 +1,22 @@
+import type { ColumnMetadata } from 'typeorm/metadata/ColumnMetadata';
+import type { DatabaseType } from 'typeorm';
+/** `->>` gives the value as text (as an SQL value on SQLite), `->` as JSON. */
+export type JsonAccessor = 'text' | 'json';
+export declare const isJsonColumn: (column: ColumnMetadata) => boolean;
+/** `-> 'settings' ->> 'theme'`: every key but the last one with `->`, the last one with `jsonOperator`. */
+export declare function buildJsonPath(fieldNames: readonly string[], jsonOperator: '->>' | '->'): string;
+export interface JsonPathSqlOptions {
+    /** Defaults to `'text'`. */
+    accessor?: JsonAccessor;
+    /** The value the path is compared with: on PostgreSQL a `'text'` path is cast to its type. */
+    value?: unknown;
+    /** Compares a `'text'` path as a timestamp whatever `value` is, since a period also takes date strings. */
+    asTimestamp?: boolean;
+}
+/**
+ * SQL for a path inside a JSON column: `"exec"."details" -> 'meta' ->> 'endTs'`, cast on PostgreSQL to the
+ * type of the compared value (`CAST(… AS numeric)`). A `simple-json` column is text there, so it is cast to
+ * `jsonb` first. SQLite (3.38+) has the same operators, and `->>` gives SQL values, so it needs no cast, except
+ * for a timestamp: there it is rewritten in the format TypeORM stores dates and binds `Date` parameters in.
+ */
+export declare function toJsonPathSql(driver: DatabaseType | undefined, columnSql: string, column: ColumnMetadata, jsonPath: readonly string[], { accessor, value, asTimestamp }?: JsonPathSqlOptions): string;

package/dist/utils/json-path.utils.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJsonPathSql = exports.buildJsonPath = exports.isJsonColumn = void 0;
+const sql_utils_1 = require("./sql.utils");
+const JSON_COLUMN_TYPES = ['json', 'jsonb', 'simple-json'];
+const isJsonColumn = (column) => JSON_COLUMN_TYPES.includes(String(column.type));
+exports.isJsonColumn = isJsonColumn;
+/** Wraps a JSON key in single quotes, doubling any quote inside it (standard SQL string literal). */
+const toJsonKeyLiteral = (fieldName) => `'${String(fieldName).replace(/'/g, "''")}'`;
+/** `-> 'settings' ->> 'theme'`: every key but the last one with `->`, the last one with `jsonOperator`. */
+function buildJsonPath(fieldNames, jsonOperator) {
+    return fieldNames
+        .map((fieldName, index) => `${index === fieldNames.length - 1 ? jsonOperator : '->'} ${toJsonKeyLiteral(fieldName)}`)
+        .join(' ');
+}
+exports.buildJsonPath = buildJsonPath;
+const isDate = (value) => Object.prototype.toString.call(value) === '[object Date]';
+/**
+ * PostgreSQL type to compare a `->>` value (text) with `value` as: text compares `'9' >= '10'` as true.
+ * An array (IN, ANY) is typed by its first value; strings and unknown values stay text.
+ */
+function getJsonTextCast(value) {
+    const sample = Array.isArray(value) ? value.find((item) => item !== null && item !== undefined) : value;
+    if (typeof sample === 'number' || typeof sample === 'bigint') {
+        return 'numeric';
+    }
+    if (typeof sample === 'boolean') {
+        return 'boolean';
+    }
+    if (isDate(sample)) {
+        return 'timestamptz';
+    }
+    return undefined;
+}
+/**
+ * SQL for a path inside a JSON column: `"exec"."details" -> 'meta' ->> 'endTs'`, cast on PostgreSQL to the
+ * type of the compared value (`CAST(… AS numeric)`). A `simple-json` column is text there, so it is cast to
+ * `jsonb` first. SQLite (3.38+) has the same operators, and `->>` gives SQL values, so it needs no cast, except
+ * for a timestamp: there it is rewritten in the format TypeORM stores dates and binds `Date` parameters in.
+ */
+function toJsonPathSql(driver, columnSql, column, jsonPath, { accessor = 'text', value, asTimestamp = false } = {}) {
+    const path = buildJsonPath(jsonPath, accessor === 'json' ? '->' : '->>');
+    const isTimestamp = asTimestamp && accessor === 'text';
+    if ((0, sql_utils_1.isSqliteLikeDriver)(driver)) {
+        const sql = `${columnSql} ${path}`;
+        return isTimestamp ? `strftime('%Y-%m-%d %H:%M:%f', ${sql})` : sql;
+    }
+    if (!(0, sql_utils_1.isPostgresLikeDriver)(driver)) {
+        throw new TypeError(`Typed keys into a JSON column (${column.propertyPath}.${jsonPath.join('.')}) are supported on PostgreSQL and SQLite, ` +
+            `not on ${driver !== null && driver !== void 0 ? driver : 'a query without a connection'}`);
+    }
+    const source = String(column.type) === 'simple-json' ? `CAST(${columnSql} AS jsonb)` : columnSql;
+    const sql = `${source} ${path}`;
+    const cast = isTimestamp ? 'timestamptz' : accessor === 'text' ? getJsonTextCast(value) : undefined;
+    return cast ? `CAST(${sql} AS ${cast})` : sql;
+}
+exports.toJsonPathSql = toJsonPathSql;

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];