@querykitjs/core 1.2.0 → 2.1.0

package/dist/internal.d.ts

@@ -0,0 +1,376 @@
+import { SkippedCondition, SortDirection, Sort, CursorMeta, InfiniteMeta, OffsetMeta, Relations, QueryLimits, Filterable, FilterOperator } from './index.js';
+export { Z as isRaw } from './raw-AiElbDzC.js';
+
+/**
+ * Opaque cursor tokens for keyset pagination, shared by every adapter so a token
+ * is interchangeable between them. A token is the base64url encoding of
+ * `{ v: <cursor value> }`; dates travel as ISO strings.
+ */
+declare function encodeCursor(value: unknown): string;
+/** The cursor value, or `undefined` for a missing or undecodable token. */
+declare function decodeCursor(cursor?: string | null): unknown | undefined;
+interface CursorToken {
+    k: string | number | boolean;
+    id: string | number | boolean;
+}
+/** A v2 token for a row's cursor value and primary key; signed when `secret` is given. */
+declare function encodeCursorToken(payload: {
+    k: unknown;
+    id: unknown;
+}, secret?: string): Promise<string>;
+/**
+ * The `{ k, id }` of a v2 token, `undefined` for no token. A v1 token, a
+ * non-scalar `k` / `id`, a missing or wrong signature (with `secret`) or
+ * anything undecodable throws `QueryKitError` — invalid-value, site cursorKey,
+ * `key` the cursor key in use (the same key as an adapter's cast error).
+ */
+declare function decodeCursorToken(token: string | null | undefined, options: {
+    source: string;
+    secret?: string;
+    key?: string;
+}): Promise<CursorToken | undefined>;
+
+interface Diagnostics {
+    /** Table (drizzle), model (prisma, mongoose) — reported as `source`. */
+    source: string;
+    strict: boolean;
+    onSkipped?: (info: SkippedCondition) => void;
+}
+declare function reportSkip(diag: Diagnostics | undefined, info: Omit<SkippedCondition, "source">): void;
+
+interface ContextStore<TContext extends object> {
+    get(): TContext | undefined;
+    /** Run `fn` with `patch` merged over the current context. */
+    run<T>(patch: TContext, fn: () => T): T;
+}
+declare function createContextStore<TContext extends object>(): ContextStore<TContext>;
+
+interface NormalizedSortItem {
+    key: string;
+    direction: SortDirection;
+}
+/**
+ * The wire `sort` array with a direction on every item. An item without a `key`
+ * (`null`, `{}`) is dropped — sort comes from the client, and a malformed item
+ * must not crash the query — and, with `diag`, reported as `invalid-value` on
+ * `site: "sort"` (a `QueryKitError` under strict).
+ */
+declare function normalizeSort(sort?: Sort, diag?: Diagnostics): NormalizedSortItem[];
+
+/**
+ * Page-size clamping and the three pagination metas, computed once for every
+ * adapter so `total_pages`, `has_more`, `next_cursor` … mean the same thing on
+ * all of them. Adapters only fetch rows; these functions turn rows into a page.
+ */
+
+/** A requested page size, defaulted, truncated, at least 1 and at most `max`. */
+declare function clampPageSize(requested: number | undefined, fallback: number, max: number): number;
+/** A requested page number: an integer, at least 1. */
+declare function clampPage(requested: number | undefined): number;
+/** A requested offset: an integer, at least 0. */
+declare function clampOffset(requested: number | undefined): number;
+declare function offsetMeta(page: number, perPage: number, totalItems: number): OffsetMeta;
+/**
+ * `withTotal: false`: rows fetched with `perPage + 1` and no count →
+ * the page and its meta; the extra row only signals `has_next`, totals are `null`.
+ */
+declare function offsetPageWithoutTotal<T>(rows: readonly T[], page: number, perPage: number): {
+    data: T[];
+    meta: OffsetMeta;
+};
+/** Rows fetched with `limit + 1` → the page and its meta (the extra row only signals `has_more`). */
+declare function infinitePage<T>(rows: readonly T[], limit: number, offset: number): {
+    data: T[];
+    meta: InfiniteMeta;
+};
+interface CursorPageOptions {
+    limit: number;
+    direction: "forward" | "backward";
+    /** A cursor was supplied (the request continues from a previous page). */
+    hasCursor: boolean;
+    /** The row field the tokens are read from. */
+    cursorField: string;
+    /** The primary-key field — the tie-break value in every token. */
+    idField: string;
+    /** Signs the tokens (registry `cursorSecret`). */
+    secret?: string;
+}
+/**
+ * Rows fetched with `limit + 1` in query order → the page in display order and
+ * its meta. A backward page is fetched reversed and flipped back here.
+ */
+declare function cursorPage<T extends Record<string, unknown>>(rows: readonly T[], options: CursorPageOptions): Promise<{
+    data: T[];
+    meta: CursorMeta;
+}>;
+
+/** `{ all: true }` — and nothing else — asks for every row (the scope still applies). */
+declare function isAllRows(filter: unknown): boolean;
+/** `undefined`, `null`, `[]` or `{}`: no condition at all. */
+declare function isEmptyFilter(filter: unknown): boolean;
+/** A mutation without a condition — also one whose every condition was skipped. */
+declare function refuseEmptyFilter(source: string, method: "updateWhere" | "deleteWhere"): never;
+
+/**
+ * A repository `scope` (the server's RBAC / tenancy filter) split once for every
+ * adapter: equality values and `{ in: [...] }` lists.
+ */
+/** One scope condition, in the shape every adapter's `buildWhere` reads. */
+interface ScopeCondition {
+    key: string;
+    operation: "=" | "in";
+    value: unknown;
+}
+/** The scope as conditions: `{ k: v }` → `k = v`, `{ k: { in: [...] } }` → `k in [...]`. */
+declare function scopeConditions(scope: Record<string, unknown> | undefined): ScopeCondition[];
+/** The values `create` / `upsert` fill in: the equality scopes only (a list has no single value). */
+declare function scopeDefaults(scope: Record<string, unknown> | undefined): Record<string, unknown>;
+
+/** How one adapter spells a relation's options. */
+interface WithDialect {
+    /** Column selection: drizzle `columns`, prisma / mongoose `select`. */
+    columns: string;
+    /** Nested relations: drizzle `with`, prisma `include`, mongoose `populate`. */
+    nested: string;
+    /** Row filters: prisma `where`, mongoose `match`; drizzle none (its `where` is code, not JSON). */
+    filters: readonly string[];
+    /** Logical keys inside a filter, walked into: prisma `AND` / `OR` / `NOT`, mongoose `$and` / `$or` / `$nor`. */
+    logical: readonly string[];
+    /** Options that only page: drizzle `limit` / `offset`, prisma `take` / `skip`, mongoose `options.limit` / `options.skip`. */
+    paging: readonly string[];
+    /** A sort whose keys must be allowed columns: prisma `orderBy`. */
+    orderBy?: string;
+    /** An options bag whose keys must be `paging` keys: mongoose `options`. */
+    options?: string;
+}
+/**
+ * The checked `with`: every relation in `relations`, every selected column in its
+ * `columns`, every filter field in its `filterable`, every nested relation in its
+ * `nested`. A relation asked for with `true` (or without a selection) gets its
+ * listed columns selected, so a column list is never widened to the full row.
+ */
+declare function checkWith(withValue: unknown, relations: Relations | undefined, dialect: WithDialect, source: string, path?: string): Record<string, unknown> | undefined;
+
+/**
+ * The filter-limit walk shared by the validators. It runs on the raw,
+ * unvalidated payload **before** any recursive schema sees it, so it is
+ * iterative — no recursion at all, whatever the payload's depth — and a
+ * 10 000-level `not` chain is rejected after `maxDepth + 1` steps.
+ *
+ * Only size is judged here. Shape errors (a missing `key`, a bad operator) are
+ * the validator's job — a malformed node is skipped, not reported.
+ */
+
+/** Where in the filter a limit was crossed — object keys and array indexes, from the root. */
+type LimitPath = (string | number)[];
+interface LimitViolation {
+    limit: keyof QueryLimits;
+    max: number;
+    path: LimitPath;
+}
+/** The limits the walk checks. */
+type FilterLimits = Pick<QueryLimits, "maxDepth" | "maxConditions" | "maxInItems" | "maxStringLength">;
+/** `maxInItems (200)` — the form every package's error text uses. */
+declare const formatLimit: (limit: keyof QueryLimits, max: number) => string;
+/**
+ * The first limit the filter crosses, depth-first in document order, or
+ * `undefined` when it is within all four. A flat array (implicit AND) puts its
+ * conditions at level 1. Key order mirrors the validators: `key` first, then
+ * `and`, `or`, `not`.
+ */
+declare function findFilterLimitViolation(filter: unknown, limits: FilterLimits): LimitViolation | undefined;
+/** Whether an operator takes a SQL LIKE pattern. */
+declare const isLikeOperator: (operation: string) => boolean;
+/**
+ * Unescaped wildcards in a LIKE pattern, a run of `%` counted once (`%%a%` ⇒ 2).
+ * A backslash escapes the next character, as in the adapters' LIKE translation.
+ */
+declare function likeWildcards(pattern: string): number;
+/** Rows an offset-paginated request skips: `(page - 1) × perPage`, with the core default page size. */
+declare const offsetOf: (page: number | undefined, perPage: number | undefined) => number;
+
+/**
+ * The server-side request policy every adapter applies: which fields
+ * a client may filter by and with which operators (`filterable`), which it may
+ * sort and page by (`sortable`), and the request limits (`limits`).
+ *
+ * A plain object that is not a condition, a group, a branded `raw()` node or a
+ * driver-native object (`isNative`) is refused as well (R19): it would otherwise
+ * reach the driver as its own `where`, past `filterable`.
+ *
+ * A refused request never reaches the driver and is never dropped silently:
+ * every check throws `QueryKitError`, whatever `strict` / `onSkippedCondition`
+ * say. A key the model does not have is **not** the policy's business — it goes
+ * on to the adapter's own `unknown-key` handling, unchanged.
+ */
+
+interface PolicyOptions {
+    /** Table / model name for the error. */
+    source: string;
+    /** Wire key → the model's canonical field name, or `undefined` when the model has no such field. */
+    fieldOf: (key: string) => string | undefined;
+    /** Canonical primary-key field — the last-resort safe default. */
+    primaryKey: string;
+    /** Canonical `createdAt` field when the model has one (default `sortable`). */
+    createdAt?: string;
+    filterable?: Filterable;
+    sortable?: readonly string[];
+    allowedColumns?: readonly string[];
+    forcedColumns?: Readonly<Record<string, unknown>>;
+    limits?: Partial<QueryLimits>;
+    /**
+     * A driver object that cannot come from JSON and stands for itself (drizzle `SQL`).
+     * Anything else that is not a condition, a group or a {@link isRaw} node is refused (R19).
+     */
+    isNative?: (node: object) => boolean;
+}
+interface Policy {
+    readonly limits: QueryLimits;
+    /** Limits, then every condition's field and operator. */
+    checkFilter(filter: unknown): void;
+    /** Field count, then every sort field. */
+    checkSort(sort: readonly {
+        key?: unknown;
+    }[] | undefined): void;
+    checkCursorKey(key: string): void;
+    /** Offset pagination: the clamped `page` × `perPage`. Infinite: the clamped `offset`. */
+    checkPage(page: {
+        page: number;
+        perPage: number;
+    } | {
+        offset: number;
+    }): void;
+    /** A `groupBy` / `sum` / `avg` / `min` / `max` field must be filterable. */
+    checkAggregateKey(key: string): void;
+}
+declare function resolvePolicy(options: PolicyOptions): Policy;
+
+/**
+ * Wire-contract checks for validator authors: the filter, the sort and the
+ * pagination params exactly as they arrive from JSON. Framework-free and
+ * text-free — an issue carries a path, a message key and its arguments; each
+ * validator renders its own message. The size walk runs first, iteratively, so
+ * an oversized payload never reaches the recursive shape check.
+ */
+
+type WireFilterIssueKey = "querykit.filter.invalid_node" | "querykit.filter.missing_key" | "querykit.filter.unknown_key" | "querykit.filter.invalid_operator" | "querykit.filter.invalid_value" | "querykit.filter.invalid_group" | "querykit.filter.max_depth" | "querykit.filter.value_requires_array" | "querykit.filter.value_requires_tuple" | "querykit.filter.value_forbidden" | "querykit.limit.exceeded";
+type WireSortIssueKey = "querykit.sort.not_array" | "querykit.sort.invalid_item" | "querykit.sort.missing_key" | "querykit.sort.unknown_key" | "querykit.sort.invalid_direction" | "querykit.limit.exceeded";
+type WireParamsIssueKey = "querykit.params.invalid_type" | "querykit.params.not_integer" | "querykit.params.out_of_range" | "querykit.params.invalid_enum";
+type WireIssueKey = WireFilterIssueKey | WireSortIssueKey | WireParamsIssueKey;
+/** Message arguments: strings and numbers only, so any message catalog can interpolate them. */
+type WireIssueArgs = Record<string, string | number>;
+/** One rejected spot: object keys and array indexes from the checked value, the message key and its arguments. */
+interface WireIssue<TKey extends WireIssueKey = WireIssueKey> {
+    path: LimitPath;
+    key: TKey;
+    args: WireIssueArgs;
+}
+interface WireFilterOptions extends Partial<Pick<QueryLimits, "maxDepth" | "maxConditions" | "maxInItems" | "maxStringLength">> {
+    /** Only these keys may be filtered on; another key is an issue. Absent — any string key. */
+    allowedKeys?: readonly string[];
+    /** Absent — every core operator. */
+    allowedOperators?: readonly FilterOperator[];
+    /** `in`/`notIn` need an array, `between`/`notBetween` exactly two values, `isNull`/`isNotNull` no value. */
+    strictValue?: boolean;
+}
+interface WireSortOptions extends Partial<Pick<QueryLimits, "maxSortFields">> {
+    /** Only these keys may be sorted on. */
+    allowedKeys?: readonly string[];
+}
+/** Request fields only the server may set; a client sends them only where `allow` opens them. */
+type WireServerOwnedField = "columns" | "with" | "withDeleted";
+/** The same names and defaults as the `@querykitjs/zod` params factories. */
+interface WireParamsOptions {
+    /** Default `DEFAULT_MAX_PER_PAGE` (200). */
+    maxPerPage?: number;
+    /** Default `DEFAULT_MAX_LIMIT` (200). */
+    maxLimit?: number;
+    limits?: Partial<QueryLimits>;
+    allow?: readonly WireServerOwnedField[];
+}
+type WireParamsKind = "offset" | "infinite" | "cursor";
+interface WireParamsResult {
+    /** The accepted fields only (unknown and closed server-owned fields stripped); absent when there are issues. */
+    value?: Record<string, unknown>;
+    issues: WireIssue[];
+}
+/**
+ * Checks a wire filter (a node, or a flat array as an implicit AND). An empty
+ * list means valid; `undefined` is valid. A crossed size limit is the only issue.
+ *
+ * @example
+ * ```ts
+ * checkFilter({ key: "age", operation: "~" }); // [{ path: ["operation"], key: "querykit.filter.invalid_operator", args: { operation: "~" } }]
+ * ```
+ */
+declare function checkFilter(value: unknown, options?: WireFilterOptions): WireIssue<WireFilterIssueKey>[];
+/** Checks a wire sort, `{ key, direction }[]`. An empty list means valid; `undefined` is valid. */
+declare function checkSort(value: unknown, options?: WireSortOptions): WireIssue<WireSortIssueKey>[];
+/**
+ * Checks offset, infinite or cursor params the way the `@querykitjs/zod`
+ * factories do: unknown fields and closed server-owned fields are stripped,
+ * `(page - 1) × perPage` stays within `maxOffset`, and a cursor request has no `sort`.
+ *
+ * @example
+ * ```ts
+ * checkParams("offset", { page: 2, perPage: 201 }).issues;
+ * // [{ path: ["perPage"], key: "querykit.params.out_of_range", args: { max: 200 } }]
+ * ```
+ */
+declare function checkParams(kind: WireParamsKind, value: unknown, options?: WireParamsOptions): WireParamsResult;
+
+/**
+ * English message texts for the wire-check issue keys, shared by the
+ * validators so a rejected payload reads the same everywhere. `{placeholder}`s
+ * are filled from the issue's `args`; `{path}` is the issue path as text.
+ */
+/**
+ * The filter, sort and limit messages — the canonical key list of
+ * `@querykitjs/class-validator`, which also ships `uz` and `ru` catalogs for it.
+ */
+declare const QUERYKIT_MESSAGES_EN: {
+    readonly "querykit.filter.invalid_node": "{path} must be a filter condition or an and/or/not group";
+    readonly "querykit.filter.missing_key": "{path} is missing the required `key` string";
+    readonly "querykit.filter.unknown_key": "{path}: `{key}` is not an allowed filter key";
+    readonly "querykit.filter.invalid_operator": "{path}: `{operation}` is not a supported filter operator";
+    readonly "querykit.filter.invalid_value": "{path} must be a string, number, boolean, null, or an array of those";
+    readonly "querykit.filter.invalid_group": "{path} must be an array of filter nodes";
+    readonly "querykit.filter.max_depth": "{path} exceeds maxDepth ({max})";
+    readonly "querykit.filter.value_requires_array": "{path}: `{operation}` requires an array value";
+    readonly "querykit.filter.value_requires_tuple": "{path}: `{operation}` requires exactly two values";
+    readonly "querykit.filter.value_forbidden": "{path}: `{operation}` must not carry a value";
+    readonly "querykit.sort.not_array": "{path} must be an array of { key, direction } items";
+    readonly "querykit.sort.invalid_item": "{path} must be an object with a `key` string";
+    readonly "querykit.sort.missing_key": "{path} is missing the required `key` string";
+    readonly "querykit.sort.unknown_key": "{path}: `{key}` is not an allowed sort key";
+    readonly "querykit.sort.invalid_direction": "{path}: direction must be `asc` or `desc`";
+    readonly "querykit.limit.exceeded": "{path} exceeds {limit} ({max})";
+};
+/** The pagination-params messages (`checkParams`); kept apart so the class-validator catalogs keep their key set. */
+declare const QUERYKIT_PARAMS_MESSAGES_EN: {
+    readonly "querykit.params.invalid_type": "{path} must be {expected}";
+    readonly "querykit.params.not_integer": "{path} must be an integer";
+    readonly "querykit.params.out_of_range": "{path} is out of the allowed range";
+    readonly "querykit.params.invalid_enum": "{path} must be one of: {values}";
+};
+/** A filter, sort or limit message key. */
+type QueryKitMessageKey = keyof typeof QUERYKIT_MESSAGES_EN;
+/** One language's full catalog — every key required, so a new key breaks every catalog at compile time. */
+type QueryKitMessageCatalog = Record<QueryKitMessageKey, string>;
+/** Interpolation arguments. */
+type MessageArgs = Record<string, string | number>;
+/** Fills `{name}` placeholders from `args`; a placeholder with no argument stays as it is, so a message is never empty. */
+declare const interpolate: (template: string, args: MessageArgs) => string;
+/**
+ * The message for `key` from `catalog` (default English), placeholders filled.
+ *
+ * @example
+ * ```ts
+ * formatMessage("querykit.limit.exceeded", { path: "filter", limit: "maxConditions", max: 30 });
+ * // "filter exceeds maxConditions (30)"
+ * ```
+ */
+declare function formatMessage(key: QueryKitMessageKey, args?: MessageArgs, catalog?: QueryKitMessageCatalog): string;
+
+export { QUERYKIT_MESSAGES_EN, QUERYKIT_PARAMS_MESSAGES_EN, checkFilter, checkParams, checkSort, checkWith, clampOffset, clampPage, clampPageSize, createContextStore, cursorPage, decodeCursor, decodeCursorToken, encodeCursor, encodeCursorToken, findFilterLimitViolation, formatLimit, formatMessage, infinitePage, interpolate, isAllRows, isEmptyFilter, isLikeOperator, likeWildcards, normalizeSort, offsetMeta, offsetOf, offsetPageWithoutTotal, refuseEmptyFilter, reportSkip, resolvePolicy, scopeConditions, scopeDefaults };
+export type { ContextStore, CursorPageOptions, CursorToken, Diagnostics, FilterLimits, LimitPath, LimitViolation, MessageArgs, NormalizedSortItem, Policy, PolicyOptions, QueryKitMessageCatalog, QueryKitMessageKey, ScopeCondition, WireFilterIssueKey, WireFilterOptions, WireIssue, WireIssueArgs, WireIssueKey, WireParamsIssueKey, WireParamsKind, WireParamsOptions, WireParamsResult, WireServerOwnedField, WireSortIssueKey, WireSortOptions, WithDialect };