typeorm-extensions 1.3.5 → 2.1.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,6 @@
 export * from './extensions';
 export * from './types/interfaces';
 export * from './types/extensions';
+export type { Json } from './types/modules/proxy-callback.types';
+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/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/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,5 @@
 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

@@ -16,3 +16,6 @@ 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);
+__exportStar(require("./config.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,54 @@
 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>;
+/** 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, 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]-?: 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. A {@link Json} column is open at any depth.
+ */
+export type DeepUnwrapArray<T> = {
+    [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;
+export type NonRelationalKeyProxyCallback<T extends ObjectLiteral> = (proxy: EntityWithoutRelations<UnwrapArray<T>>) => ProxyColumnValueType;
+export {};

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