typeorm-extensions 1.3.5 → 2.0.0

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

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const typeorm_1 = require("typeorm");
+const prototype_utils_1 = require("../utils/prototype.utils");
+const query_builder_utils_1 = require("../utils/query-builder.utils");
+const sql_utils_1 = require("../utils/sql.utils");
+/* eslint-enable @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars */
+// patching
+const createWhereJsonContainsMethod = (method) => function (field, value) {
+    return attachWhereJsonContains(this, method, field, value);
+};
+const createWhereJsonHasKeyMethod = (method) => function (field, key) {
+    return attachWhereJsonHasKey(this, method, field, key);
+};
+const extension = {
+    prototype: {
+        whereJsonContains: createWhereJsonContainsMethod('where'),
+        andWhereJsonContains: createWhereJsonContainsMethod('andWhere'),
+        orWhereJsonContains: createWhereJsonContainsMethod('orWhere'),
+        whereJsonHasKey: createWhereJsonHasKeyMethod('where'),
+        andWhereJsonHasKey: createWhereJsonHasKeyMethod('andWhere'),
+        orWhereJsonHasKey: createWhereJsonHasKeyMethod('orWhere'),
+    },
+};
+const queryBuilders = [
+    typeorm_1.SelectQueryBuilder,
+    typeorm_1.UpdateQueryBuilder,
+    typeorm_1.DeleteQueryBuilder,
+];
+queryBuilders.forEach((builder) => {
+    (0, prototype_utils_1.patchPrototype)(builder, extension);
+});
+// implementation
+/**
+ * `CAST("table"."column" AS jsonb)`: makes `json` and `simple-json` (text) columns work, and is dropped by PostgreSQL
+ * for `jsonb` columns, so it doesn't stop a GIN index from being used.
+ */
+function toJsonbOperand(builder, field) {
+    return `CAST(${(0, query_builder_utils_1.toFieldSql)(builder, field)} AS jsonb)`;
+}
+function attachWhereJsonContains(builder, method, field, value) {
+    if (!method || typeof field !== 'string') {
+        return builder;
+    }
+    const json = JSON.stringify(value);
+    if (json === undefined) {
+        // `undefined` / functions have no JSON form; matching nothing or everything silently would hide the bug
+        throw new TypeError(`JSON condition on "${field}" expects a JSON value, got ${String(value)}`);
+    }
+    const paramName = (0, sql_utils_1.createUniqueParameterName)(method);
+    // CAST("table"."column" AS jsonb) @> CAST(:param AS jsonb), where :param is the JSON text
+    return builder[method](`${toJsonbOperand(builder, field)} @> CAST(:${paramName} AS jsonb)`, { [paramName]: json });
+}
+function attachWhereJsonHasKey(builder, method, field, key) {
+    if (!method || typeof field !== 'string') {
+        return builder;
+    }
+    if (typeof key !== 'string') {
+        throw new TypeError(`JSON key condition on "${field}" expects a string key, got ${String(key)}`);
+    }
+    const paramName = (0, sql_utils_1.createUniqueParameterName)(method);
+    // the `?` operator, not jsonb_exists(): only the operator can use a GIN index
+    return builder[method](`${toJsonbOperand(builder, field)} ? :${paramName}`, { [paramName]: key });
+}

package/dist/helpers.d.ts

@@ -0,0 +1,2 @@
+export * from './utils/table.utils';
+export { escapeLikePattern } from './utils/search.utils';

package/dist/helpers.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeLikePattern = void 0;
+// Side-effect-free entry point: `typeorm-extensions/helpers`.
+// Exports helpers (tableHelper, escapeLikePattern) only and patches nothing; importing the package root
+// (`typeorm-extensions`) installs every QueryBuilder extension.
+__exportStar(require("./utils/table.utils"), exports);
+var search_utils_1 = require("./utils/search.utils");
+Object.defineProperty(exports, "escapeLikePattern", { enumerable: true, get: function () { return search_utils_1.escapeLikePattern; } });

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export * from './extensions';
 export * from './types/interfaces';
 export * from './types/extensions';
+export * from './utils/table.utils';
+export { escapeLikePattern } from './utils/search.utils';

package/dist/index.js

@@ -14,6 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeLikePattern = void 0;
 __exportStar(require("./extensions"), exports);
 __exportStar(require("./types/interfaces"), exports);
 __exportStar(require("./types/extensions"), exports);
+__exportStar(require("./utils/table.utils"), exports);
+var search_utils_1 = require("./utils/search.utils");
+Object.defineProperty(exports, "escapeLikePattern", { enumerable: true, get: function () { return search_utils_1.escapeLikePattern; } });

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

@@ -0,0 +1,16 @@
+import type { CursorOrderParam } from '../interfaces/cursor-pagination.interface';
+export type GetManyWithCursorOptions<Entity> = {
+    /**
+     * Columns that order the rows, e.g. `[{ field: 'createdAt', direction: 'DESC' }]`.
+     * The primary key is appended when it isn't listed, so the order is total and no row is skipped
+     * or repeated between pages. It replaces any ORDER BY of the query.
+     */
+    orderBy: Array<CursorOrderParam<Entity>>;
+    /** Use `take` instead of `limit`, as needed for queries with joined collections. Defaults to `false`. */
+    useTakeAndSkip?: boolean;
+};
+export interface ListWithCursor<Entity> {
+    list: Entity[];
+    /** Cursor of the next page, `null` on the last page. */
+    nextCursor: string | null;
+}

package/dist/types/extensions/cursor-pagination.types.js

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

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

@@ -1,4 +1,6 @@
-export type GetManyWithTotalsOptions = {
+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;
 };

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

@@ -1,4 +1,8 @@
 export * from './pagination.types';
 export * from './order.types';
+export * from './typed-order-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';

package/dist/types/extensions/index.js

@@ -16,5 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 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("./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);

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

@@ -1,5 +1,5 @@
 export type ApplyOrderOptions = {
-    useDoubleQuotes?: boolean;
+    useQuotes?: boolean;
     alias?: string;
     alwaysAliasFields?: string[];
     resetPreviousOrder?: boolean;

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

@@ -0,0 +1,15 @@
+export type ApplyPeriodOptions = {
+    /**
+     * Include the start of the period (default `true`): `field >= periodFrom`.
+     * With `false`: `field > periodFrom`, and a date-only `periodFrom` (`'2024-01-01'`) excludes that
+     * whole day: `field >= '2024-01-02'`.
+     */
+    includeFrom?: boolean;
+    /**
+     * Include the end of the period (default `true`): `field <= periodTo`, and a date-only `periodTo`
+     * (`'2024-01-31'`) includes that whole day: `field < '2024-02-01'`.
+     * With `false`: `field < periodTo`, a half-open period such as
+     * `{ periodFrom: '2024-01-01', periodTo: '2024-02-01' }`.
+     */
+    includeTo?: boolean;
+};

package/dist/types/extensions/period.types.js

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

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

@@ -0,0 +1,68 @@
+import type { ObjectLiteral } from 'typeorm';
+import type { KeyProxyCallback } from '../modules/proxy-callback.types';
+/**
+ * Where the search value must be found in the column:
+ * - `'contains'` → `%value%`;
+ * - `'prefix'` → `value%`;
+ * - `'suffix'` → `%value`;
+ * - `'exact'` → `value` (a case-insensitive equality).
+ */
+export type LikeMatch = 'contains' | 'prefix' | 'suffix' | 'exact';
+/** A raw SQL expression to search in, used as is in parentheses: `{ sql: \`u."firstName" || ' ' || u."lastName"\` }`. */
+export type SqlExpression = {
+    sql: string;
+};
+/** A column (typed callback, may select several columns) or a raw SQL expression to search in. */
+export type SearchSelector<Type extends ObjectLiteral> = KeyProxyCallback<Type> | SqlExpression;
+export type TypedILikeOptions = {
+    /** Where the value must be found in the column. Defaults to `'contains'`. */
+    match?: LikeMatch;
+    /**
+     * Escape `%`, `_` and `\` in the value with a backslash, so they match themselves.
+     * Defaults to `true`; `false` passes the value's own wildcards through.
+     */
+    escape?: boolean;
+    /**
+     * Compare without accents (PostgreSQL `unaccent` extension): `unaccent(col) ILIKE unaccent(:p)`.
+     * `true` calls `unaccent`; a string names the function to call, e.g. an IMMUTABLE wrapper
+     * that an expression index is built on: `'immutable_unaccent'`, `'public.f_unaccent'`.
+     */
+    unaccent?: boolean | string;
+};
+export type TypedSearchOptions = TypedILikeOptions & {
+    /** A value shorter than this (after trimming) adds no condition. Defaults to 1. */
+    minLength?: number;
+};
+export type TypedLowerOptions = {
+    /**
+     * Wraps both the column and the parameter: `(sql) => \`LOWER(TRIM(${sql}))\``.
+     * Defaults to `(sql) => \`LOWER(${sql})\``. Write it exactly like the expression index
+     * the condition should use. The result must contain `sql`.
+     */
+    normalize?: (sql: string) => string;
+};
+/**
+ * pg_trgm operator, with the column on the left:
+ * - `'%'` → `col % :term`: `similarity(col, term)` is above `pg_trgm.similarity_threshold`;
+ * - `'%>'` → `col %> :term` (same as `:term <% col`): the term is similar to a word of the column,
+ *   `word_similarity(term, col)` is above `pg_trgm.word_similarity_threshold`;
+ * - `'<%'` → `col <% :term`: the column is similar to a word of the term.
+ *
+ * `%` and `%>` can use a `gin_trgm_ops` / `gist_trgm_ops` index on the column, `<%` can't.
+ */
+export type TrigramOperator = '%' | '%>' | '<%';
+export type TypedSimilarOptions = {
+    /** Defaults to `'%'`. */
+    operator?: TrigramOperator;
+};
+/**
+ * pg_trgm score function:
+ * - `'similarity'` → `similarity(col, :term)`, pairs with the `%` operator;
+ * - `'word_similarity'` → `word_similarity(:term, col)`, pairs with `%>`;
+ * - `'strict_word_similarity'` → `strict_word_similarity(:term, col)`.
+ */
+export type SimilarityFunction = 'similarity' | 'word_similarity' | 'strict_word_similarity';
+export type SimilarityScoreOptions = {
+    /** Defaults to `'similarity'`. */
+    function?: SimilarityFunction;
+};

package/dist/types/extensions/search.types.js

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

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

@@ -0,0 +1,3 @@
+export type TypedOrderByOptions = {
+    useQuotes?: boolean;
+};

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

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

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

@@ -1,7 +1,7 @@
 export type TypedWhereOptions = {
-    useDoubleQuotes?: boolean;
+    /**
+     * Append a placeholder for the value to the condition (`=` → `= :param`). Defaults to `true`,
+     * or to `false` when the condition already references a key of the parameters (`'= :id'` with `{ id }`).
+     */
     addValue?: boolean;
 };
-export type TypedWhereIsInOptions = {
-    useDoubleQuotes?: boolean;
-};

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

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

package/dist/types/interfaces/cursor-pagination.interface.d.ts

@@ -0,0 +1,16 @@
+import type { NonFunctionPropertyNames } from '../util-types';
+import type { OrderDirection } from './ordering.interface';
+/** The page to load with keyset (cursor) pagination, e.g. from query parameters. */
+export interface CursorPaginationFilter {
+    /** `nextCursor` of the previous page; missing, `null` or empty for the first page. */
+    cursor?: string | null;
+    /** Rows per page, 10 by default. */
+    pageSize?: number;
+}
+/** A column that orders the rows of keyset pagination. */
+export type CursorOrderParam<Entity> = {
+    /** Property of the main entity. The column must not be `NULL`. */
+    field: NonFunctionPropertyNames<Required<Entity>>;
+    /** `'ASC'` by default. */
+    direction?: OrderDirection;
+};

package/dist/types/interfaces/cursor-pagination.interface.js

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

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

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

package/dist/types/interfaces/index.js

@@ -16,3 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./ordering.interface"), exports);
 __exportStar(require("./pagination.interface"), exports);
+__exportStar(require("./period.interface"), exports);
+__exportStar(require("./cursor-pagination.interface"), exports);

package/dist/types/interfaces/period.interface.d.ts

@@ -0,0 +1,12 @@
+/** A period boundary: a `Date`, or a date / timestamp string the database understands (`'2024-01-31'`). */
+export type PeriodBoundary = Date | string;
+/**
+ * A period to filter rows by, e.g. from query parameters. Both ends are optional and,
+ * by default, inclusive: `periodFrom` → `field >= periodFrom`, `periodTo` → `field <= periodTo`.
+ * A date-only string (`'2024-01-31'`) stands for the whole day: `periodTo: '2024-01-31'`
+ * → `field < '2024-02-01'`. See `ApplyPeriodOptions` to exclude either end.
+ */
+export interface PeriodFilter {
+    periodFrom?: PeriodBoundary;
+    periodTo?: PeriodBoundary;
+}

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

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

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

@@ -1,7 +1,30 @@
 import { ObjectLiteral } from "typeorm";
 import { EntityOnlyWithRelations, EntityWithoutRelations } from "./relations.types";
 import { ColumnValueType } from "./column.types";
+import { UnwrapArray } from "../util-types";
 export type ProxyColumnValueType = ColumnValueType | ':value';
-export type KeyProxyCallback<T extends ObjectLiteral> = (proxy: T) => ProxyColumnValueType | Array<ProxyColumnValueType>;
-export type RelationalKeyProxyCallback<T extends ObjectLiteral> = (proxy: EntityOnlyWithRelations<T>) => ProxyColumnValueType;
-export type NonRelationalKeyProxyCallback<T extends ObjectLiteral> = (proxy: EntityWithoutRelations<T>) => ProxyColumnValueType;
+type ProxyPropertyType<V> = NonNullable<V> extends readonly (infer U)[] ? NonNullable<U> : 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.
+ */
+export interface KeyPathEnd {
+    readonly __keyPathEnd: never;
+}
+type ProxySecondLevel<T> = {
+    [K in keyof T]-?: ProxyPropertyType<T[K]> extends object ? 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.
+ */
+export type DeepUnwrapArray<T> = {
+    [K in keyof T]-?: ProxyPropertyType<T[K]> extends object ? 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;
+export type NonRelationalKeyProxyCallback<T extends ObjectLiteral> = (proxy: EntityWithoutRelations<UnwrapArray<T>>) => ProxyColumnValueType;
+export {};

package/dist/types/util-types/index.d.ts

@@ -1,4 +1,5 @@
-export type ArgsType = unknown[];
+/** Values for IN / NOT IN conditions. Readonly so `as const` arrays are accepted; the array is only read. */
+export type ArgsType = readonly unknown[];
 export type FunctionPropertyNames<T> = {
     [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
 }[keyof T] & string;
@@ -6,3 +7,4 @@ export type NonFunctionPropertyNames<T> = {
     [K in keyof T]: T[K] extends (...args: any[]) => any ? never : K;
 }[keyof T] & string;
 export type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+export type UnwrapArray<T> = T extends (infer U)[] ? U : T;

package/dist/utils/cursor.utils.d.ts

@@ -0,0 +1,31 @@
+import type { DatabaseType } from 'typeorm';
+/** A cursor that can't be decoded or doesn't belong to the query's order (e.g. tampered with). */
+export declare class InvalidCursorError extends TypeError {
+    constructor(message: string);
+}
+/** A key value in a cursor: as read from the database, or a JS Date tagged as `{ $date }`. */
+export type CursorValue = string | number | boolean;
+/** base64url-encoded JSON of the key fields and the key values of the last row. */
+export declare function encodeCursor(fields: string[], values: unknown[]): string;
+/** Key values of a cursor made for `fields`; throws `InvalidCursorError` otherwise. */
+export declare function decodeCursor(cursor: string, fields: string[]): Array<CursorValue | Date>;
+/** Databases that compare row values: `(a, b) < (1, 2)`. */
+export declare const supportsRowValueComparison: (driver?: DatabaseType) => boolean;
+/**
+ * Type to read a date / time column as text with, so the cursor keeps the database's own precision
+ * (PostgreSQL timestamps have microseconds, a JS Date only milliseconds). `undefined` when unknown.
+ */
+export declare const getTextCastType: (driver?: DatabaseType) => string | undefined;
+export type KeysetColumn = {
+    /** quoted column, e.g. `"user"."createdAt"` */
+    column: string;
+    direction: 'ASC' | 'DESC';
+    /** parameter name holding the cursor value of this column */
+    paramName: string;
+};
+/**
+ * WHERE condition for the rows after the cursor:
+ * - same direction everywhere, on databases with row values: `(a, b) > (:a, :b)`
+ * - otherwise: `a >= :a AND (a > :a OR (a = :a AND b < :b))`, where the leading bound lets an index on `a` be used
+ */
+export declare function buildKeysetCondition(keys: KeysetColumn[], useRowValues: boolean): string;

package/dist/utils/cursor.utils.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildKeysetCondition = exports.getTextCastType = exports.supportsRowValueComparison = exports.decodeCursor = exports.encodeCursor = exports.InvalidCursorError = void 0;
+const sql_utils_1 = require("./sql.utils");
+/** A cursor that can't be decoded or doesn't belong to the query's order (e.g. tampered with). */
+class InvalidCursorError extends TypeError {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidCursorError';
+    }
+}
+exports.InvalidCursorError = InvalidCursorError;
+const isDate = (value) => Object.prototype.toString.call(value) === '[object Date]';
+const toCursorValue = (value) => {
+    if (isDate(value)) {
+        return { $date: value.toISOString() };
+    }
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    return value;
+};
+// base64url of UTF-8 text, with the globals of Node 16+ and browsers (no Buffer, no @types/node)
+const toBase64Url = (text) => {
+    let binary = '';
+    new TextEncoder().encode(text).forEach((byte) => (binary += String.fromCharCode(byte)));
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+const fromBase64Url = (value) => {
+    if (!/^[A-Za-z0-9_-]*$/.test(value)) {
+        throw new InvalidCursorError('Invalid cursor: not base64url');
+    }
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4));
+    return new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+};
+/** base64url-encoded JSON of the key fields and the key values of the last row. */
+function encodeCursor(fields, values) {
+    const payload = { k: fields, v: values.map(toCursorValue) };
+    return toBase64Url(JSON.stringify(payload));
+}
+exports.encodeCursor = encodeCursor;
+const isCursorValue = (value) => typeof value === 'string' ||
+    (typeof value === 'number' && Number.isFinite(value)) ||
+    typeof value === 'boolean' ||
+    (typeof value === 'object' &&
+        value !== null &&
+        typeof value.$date === 'string');
+/** Key values of a cursor made for `fields`; throws `InvalidCursorError` otherwise. */
+function decodeCursor(cursor, fields) {
+    let payload;
+    try {
+        payload = JSON.parse(fromBase64Url(cursor));
+    }
+    catch {
+        throw new InvalidCursorError('Invalid cursor: it could not be decoded');
+    }
+    if (!payload ||
+        !Array.isArray(payload.k) ||
+        !Array.isArray(payload.v) ||
+        payload.k.length !== fields.length ||
+        payload.v.length !== fields.length ||
+        payload.k.some((field, i) => field !== fields[i]) ||
+        !payload.v.every(isCursorValue)) {
+        throw new InvalidCursorError(`Invalid cursor: it was not made for the order (${fields.join(', ')})`);
+    }
+    return payload.v.map((value) => {
+        if (typeof value !== 'object') {
+            return value;
+        }
+        const date = new Date(value.$date);
+        if (isNaN(date.getTime())) {
+            throw new InvalidCursorError('Invalid cursor: invalid date');
+        }
+        return date;
+    });
+}
+exports.decodeCursor = decodeCursor;
+/** Databases that compare row values: `(a, b) < (1, 2)`. */
+const supportsRowValueComparison = (driver) => driver === 'postgres' ||
+    driver === 'aurora-postgres' ||
+    driver === 'cockroachdb' ||
+    (0, sql_utils_1.isMysqlLikeDriver)(driver) ||
+    (0, sql_utils_1.isSqliteLikeDriver)(driver);
+exports.supportsRowValueComparison = supportsRowValueComparison;
+/**
+ * Type to read a date / time column as text with, so the cursor keeps the database's own precision
+ * (PostgreSQL timestamps have microseconds, a JS Date only milliseconds). `undefined` when unknown.
+ */
+const getTextCastType = (driver) => {
+    if (driver === 'postgres' || driver === 'aurora-postgres' || driver === 'cockroachdb' || (0, sql_utils_1.isSqliteLikeDriver)(driver)) {
+        return 'text';
+    }
+    if ((0, sql_utils_1.isMysqlLikeDriver)(driver)) {
+        return 'char';
+    }
+    if (driver === 'mssql') {
+        return 'nvarchar(max)';
+    }
+    return undefined;
+};
+exports.getTextCastType = getTextCastType;
+/**
+ * WHERE condition for the rows after the cursor:
+ * - same direction everywhere, on databases with row values: `(a, b) > (:a, :b)`
+ * - otherwise: `a >= :a AND (a > :a OR (a = :a AND b < :b))`, where the leading bound lets an index on `a` be used
+ */
+function buildKeysetCondition(keys, useRowValues) {
+    const operator = (key) => (key.direction === 'ASC' ? '>' : '<');
+    if (keys.length === 1) {
+        const [key] = keys;
+        return `${key.column} ${operator(key)} :${key.paramName}`;
+    }
+    if (useRowValues && keys.every((key) => key.direction === keys[0].direction)) {
+        const columns = keys.map((key) => key.column).join(', ');
+        const params = keys.map((key) => `:${key.paramName}`).join(', ');
+        return `(${columns}) ${operator(keys[0])} (${params})`;
+    }
+    const expand = (index) => {
+        const key = keys[index];
+        const after = `${key.column} ${operator(key)} :${key.paramName}`;
+        if (index === keys.length - 1) {
+            return after;
+        }
+        return `(${after} OR (${key.column} = :${key.paramName} AND ${expand(index + 1)}))`;
+    };
+    const [first] = keys;
+    return `(${first.column} ${operator(first)}= :${first.paramName} AND ${expand(0)})`;
+}
+exports.buildKeysetCondition = buildKeysetCondition;

package/dist/utils/order.utils.d.ts

@@ -0,0 +1,15 @@
+import type { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import type { OrderDirection } from '../types/interfaces/ordering.interface';
+import type { ArgsType } from '../types/util-types';
+/**
+ * `'ASC'` / `'DESC'` for any `OrderDirection`: `'asc'` / `'desc'` in any case, `1` / `-1`,
+ * `true` (ASC) / `false` (DESC). Anything else is the default direction (ASC).
+ */
+export declare function toSqlOrderDirection(direction: OrderDirection | undefined | null): 'ASC' | 'DESC';
+/**
+ * Selects `array_position(:values, column)` under a generated alias and orders by that alias.
+ * TypeORM can't order by a function expression together with `take` and joins
+ * (`"array_position(…" alias was not found`), but it can order by a selection alias.
+ * `column` is already quoted.
+ */
+export declare function attachOrderByArrayPosition<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, column: string, values: ArgsType, arrayType: string | undefined, replace: boolean): SelectQueryBuilder<Entity>;

package/dist/utils/order.utils.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachOrderByArrayPosition = exports.toSqlOrderDirection = void 0;
+const constants_1 = require("../constants");
+const sql_utils_1 = require("./sql.utils");
+/**
+ * `'ASC'` / `'DESC'` for any `OrderDirection`: `'asc'` / `'desc'` in any case, `1` / `-1`,
+ * `true` (ASC) / `false` (DESC). Anything else is the default direction (ASC).
+ */
+function toSqlOrderDirection(direction) {
+    if (typeof direction === 'boolean') {
+        return direction ? 'ASC' : 'DESC';
+    }
+    if (typeof direction === 'number') {
+        return direction === -1 ? 'DESC' : 'ASC';
+    }
+    if (typeof direction === 'string' && /asc|desc/i.test(direction)) {
+        return direction.toUpperCase();
+    }
+    return constants_1.defaultOrderDirection;
+}
+exports.toSqlOrderDirection = toSqlOrderDirection;
+/**
+ * Selects `array_position(:values, column)` under a generated alias and orders by that alias.
+ * TypeORM can't order by a function expression together with `take` and joins
+ * (`"array_position(…" alias was not found`), but it can order by a selection alias.
+ * `column` is already quoted.
+ */
+function attachOrderByArrayPosition(builder, column, values, arrayType, replace) {
+    if (!Array.isArray(values)) {
+        throw new TypeError(`orderByArrayPosition on "${column}" expects an array of values, got ${values}`);
+    }
+    const castTo = arrayType === undefined ? undefined : (0, sql_utils_1.assertArrayType)(arrayType);
+    const paramName = (0, sql_utils_1.createUniqueParameterName)('position');
+    // lower case: PostgreSQL folds the unquoted alias in ORDER BY
+    const selectionAlias = `array_${paramName}`.toLowerCase();
+    const parameter = castTo ? `CAST(:${paramName} AS ${castTo})` : `:${paramName}`;
+    builder
+        .addSelect(`array_position(${parameter}, ${column})`, selectionAlias)
+        .setParameter(paramName, values);
+    return replace
+        ? builder.orderBy(selectionAlias, 'ASC', 'NULLS LAST')
+        : builder.addOrderBy(selectionAlias, 'ASC', 'NULLS LAST');
+}
+exports.attachOrderByArrayPosition = attachOrderByArrayPosition;

package/dist/utils/period.utils.d.ts

@@ -0,0 +1,9 @@
+import type { WhereExpressionBuilder } from 'typeorm';
+import type { PeriodFilter } from '../types/interfaces/period.interface';
+import type { ApplyPeriodOptions } from '../types/extensions/period.types';
+/**
+ * Adds `column >= :periodFrom` and `column <= :periodTo` conditions (or their exclusive versions) with
+ * AND, so the filter narrows whatever WHERE conditions the query already has, OR ones included:
+ * `(a OR b) AND column >= …`. `column` is already quoted.
+ */
+export declare function attachPeriodFilter<QB extends WhereExpressionBuilder>(builder: QB, column: string, periodFilter: PeriodFilter | null | undefined, options?: ApplyPeriodOptions): QB;