@querykitjs/core 2.0.0 → 2.1.0

package/dist/internal.d.cts

@@ -1,5 +1,5 @@
-import { SkippedCondition, SortDirection, Sort, CursorMeta, InfiniteMeta, OffsetMeta, Relations, QueryLimits, Filterable } from './index.cjs';
-export { Z as isRaw } from './raw-Bx8c-TrC.cjs';
+import { SkippedCondition, SortDirection, Sort, CursorMeta, InfiniteMeta, OffsetMeta, Relations, QueryLimits, Filterable, FilterOperator } from './index.cjs';
+export { Z as isRaw } from './raw-AiElbDzC.cjs';
 
 /**
  * Opaque cursor tokens for keyset pagination, shared by every adapter so a token
@@ -53,7 +53,7 @@ interface NormalizedSortItem {
  * 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; task 021 B14).
+ * `site: "sort"` (a `QueryKitError` under strict).
  */
 declare function normalizeSort(sort?: Sort, diag?: Diagnostics): NormalizedSortItem[];
 
@@ -71,7 +71,7 @@ declare function clampPage(requested: number | undefined): number;
 declare function clampOffset(requested: number | undefined): number;
 declare function offsetMeta(page: number, perPage: number, totalItems: number): OffsetMeta;
 /**
- * `withTotal: false` (task 013): rows fetched with `perPage + 1` and no count →
+ * `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): {
@@ -90,7 +90,7 @@ interface CursorPageOptions {
     hasCursor: boolean;
     /** The row field the tokens are read from. */
     cursorField: string;
-    /** The primary-key field — the tie-break value in every token (task 012). */
+    /** The primary-key field — the tie-break value in every token. */
     idField: string;
     /** Signs the tokens (registry `cursorSecret`). */
     secret?: string;
@@ -113,7 +113,7 @@ declare function refuseEmptyFilter(source: string, method: "updateWhere" | "dele
 
 /**
  * A repository `scope` (the server's RBAC / tenancy filter) split once for every
- * adapter (task 014): equality values and `{ in: [...] }` lists.
+ * adapter: equality values and `{ in: [...] }` lists.
  */
 /** One scope condition, in the shape every adapter's `buildWhere` reads. */
 interface ScopeCondition {
@@ -152,7 +152,7 @@ interface WithDialect {
 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 (task 008). It runs on the raw,
+ * 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.
@@ -190,9 +190,9 @@ declare function likeWildcards(pattern: string): number;
 declare const offsetOf: (page: number | undefined, perPage: number | undefined) => number;
 
 /**
- * The server-side request policy every adapter applies (task 009): which fields
+ * 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`, task 008).
+ * 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
@@ -245,5 +245,132 @@ interface Policy {
 }
 declare function resolvePolicy(options: PolicyOptions): Policy;
 
-export { checkWith, clampOffset, clampPage, clampPageSize, createContextStore, cursorPage, decodeCursor, decodeCursorToken, encodeCursor, encodeCursorToken, findFilterLimitViolation, formatLimit, infinitePage, isAllRows, isEmptyFilter, isLikeOperator, likeWildcards, normalizeSort, offsetMeta, offsetOf, offsetPageWithoutTotal, refuseEmptyFilter, reportSkip, resolvePolicy, scopeConditions, scopeDefaults };
-export type { ContextStore, CursorPageOptions, CursorToken, Diagnostics, FilterLimits, LimitPath, LimitViolation, NormalizedSortItem, Policy, PolicyOptions, ScopeCondition, WithDialect };
+/**
+ * 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 };

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
-import { SkippedCondition, SortDirection, Sort, CursorMeta, InfiniteMeta, OffsetMeta, Relations, QueryLimits, Filterable } from './index.js';
-export { Z as isRaw } from './raw-Bx8c-TrC.js';
+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
@@ -53,7 +53,7 @@ interface NormalizedSortItem {
  * 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; task 021 B14).
+ * `site: "sort"` (a `QueryKitError` under strict).
  */
 declare function normalizeSort(sort?: Sort, diag?: Diagnostics): NormalizedSortItem[];
 
@@ -71,7 +71,7 @@ declare function clampPage(requested: number | undefined): number;
 declare function clampOffset(requested: number | undefined): number;
 declare function offsetMeta(page: number, perPage: number, totalItems: number): OffsetMeta;
 /**
- * `withTotal: false` (task 013): rows fetched with `perPage + 1` and no count →
+ * `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): {
@@ -90,7 +90,7 @@ interface CursorPageOptions {
     hasCursor: boolean;
     /** The row field the tokens are read from. */
     cursorField: string;
-    /** The primary-key field — the tie-break value in every token (task 012). */
+    /** The primary-key field — the tie-break value in every token. */
     idField: string;
     /** Signs the tokens (registry `cursorSecret`). */
     secret?: string;
@@ -113,7 +113,7 @@ declare function refuseEmptyFilter(source: string, method: "updateWhere" | "dele
 
 /**
  * A repository `scope` (the server's RBAC / tenancy filter) split once for every
- * adapter (task 014): equality values and `{ in: [...] }` lists.
+ * adapter: equality values and `{ in: [...] }` lists.
  */
 /** One scope condition, in the shape every adapter's `buildWhere` reads. */
 interface ScopeCondition {
@@ -152,7 +152,7 @@ interface WithDialect {
 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 (task 008). It runs on the raw,
+ * 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.
@@ -190,9 +190,9 @@ declare function likeWildcards(pattern: string): number;
 declare const offsetOf: (page: number | undefined, perPage: number | undefined) => number;
 
 /**
- * The server-side request policy every adapter applies (task 009): which fields
+ * 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`, task 008).
+ * 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
@@ -245,5 +245,132 @@ interface Policy {
 }
 declare function resolvePolicy(options: PolicyOptions): Policy;
 
-export { checkWith, clampOffset, clampPage, clampPageSize, createContextStore, cursorPage, decodeCursor, decodeCursorToken, encodeCursor, encodeCursorToken, findFilterLimitViolation, formatLimit, infinitePage, isAllRows, isEmptyFilter, isLikeOperator, likeWildcards, normalizeSort, offsetMeta, offsetOf, offsetPageWithoutTotal, refuseEmptyFilter, reportSkip, resolvePolicy, scopeConditions, scopeDefaults };
-export type { ContextStore, CursorPageOptions, CursorToken, Diagnostics, FilterLimits, LimitPath, LimitViolation, NormalizedSortItem, Policy, PolicyOptions, ScopeCondition, WithDialect };
+/**
+ * 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 };

package/dist/internal.js

@@ -1,5 +1,5 @@
-import { QueryKitError, resolveLimits, isRaw } from './chunk-NHNDPIPM.js';
-export { isRaw } from './chunk-NHNDPIPM.js';
+import { QueryKitError, resolveLimits, isRaw, FILTER_OPERATORS } from './chunk-XEETYJA3.js';
+export { isRaw } from './chunk-XEETYJA3.js';
 
 // src/internal/cursor.ts
 function encodeCursor(value) {
@@ -283,7 +283,7 @@ function filterRules(options, canonical) {
 function resolvePolicy(options) {
   let limits = resolveLimits(options.limits), canonical = (key) => options.fieldOf(key) ?? key, rules = filterRules(options, canonical), sortable = new Set((options.sortable ?? [options.primaryKey, ...options.createdAt ? [options.createdAt] : []]).map(canonical)), refuse = (site, key, reason, operation) => {
     throw new QueryKitError({ source: options.source, site, key, reason, ...operation ? { operation } : {} });
-  }, checkCondition = (node) => {
+  }, checkCondition2 = (node) => {
     let key = String(node.key), field = options.fieldOf(key);
     if (field === void 0) return;
     let operation = typeof node.operation == "string" ? node.operation : "=", rule = rules.get(field);
@@ -300,7 +300,7 @@ function resolvePolicy(options) {
       let pending = Array.isArray(filter) ? [...filter] : [filter];
       for (; pending.length > 0; ) {
         let node = pending.pop();
-        isRecord2(node) && ("key" in node ? checkCondition(node) : Array.isArray(node.and) ? pending.push(...node.and) : Array.isArray(node.or) ? pending.push(...node.or) : "not" in node ? pending.push(node.not) : !isRaw(node) && !options.isNative?.(node) && refuse("filter", Object.keys(node)[0] ?? "", "forbidden-key"));
+        isRecord2(node) && ("key" in node ? checkCondition2(node) : Array.isArray(node.and) ? pending.push(...node.and) : Array.isArray(node.or) ? pending.push(...node.or) : "not" in node ? pending.push(node.not) : !isRaw(node) && !options.isNative?.(node) && refuse("filter", Object.keys(node)[0] ?? "", "forbidden-key"));
       }
     },
     checkSort(sort) {
@@ -322,6 +322,149 @@ function resolvePolicy(options) {
   };
 }
 
-export { checkWith, clampOffset, clampPage, clampPageSize, createContextStore, cursorPage, decodeCursor, decodeCursorToken, encodeCursor, encodeCursorToken, findFilterLimitViolation, formatLimit, infinitePage, isAllRows, isEmptyFilter, isLikeOperator, likeWildcards, normalizeSort, offsetMeta, offsetOf, offsetPageWithoutTotal, refuseEmptyFilter, reportSkip, resolvePolicy, scopeConditions, scopeDefaults };
+// src/internal/wire-checks.ts
+var ALL_OPERATORS = /* @__PURE__ */ new Set(FILTER_OPERATORS), isRecord3 = (value) => typeof value == "object" && value !== null && !Array.isArray(value), isScalar2 = (value) => value === null || typeof value == "string" || typeof value == "boolean" || typeof value == "number" && Number.isFinite(value), isFilterValue = (value) => Array.isArray(value) ? value.every(isScalar2) : isScalar2(value), label = (value) => {
+  try {
+    return String(value);
+  } catch {
+    return Object.prototype.toString.call(value);
+  }
+}, wireIssue = (key, path, args = {}) => ({ path, key, args });
+function checkCondition(node, path, walk) {
+  if (!isRecord3(node)) {
+    walk.issues.push(wireIssue("querykit.filter.invalid_node", path));
+    return;
+  }
+  let { key, operation, value } = node;
+  if (typeof key != "string") {
+    walk.issues.push(wireIssue("querykit.filter.missing_key", path));
+    return;
+  }
+  walk.allowedKeys && !walk.allowedKeys.has(key) && walk.issues.push(wireIssue("querykit.filter.unknown_key", path, { key }));
+  let operator;
+  operation !== void 0 && (typeof operation == "string" && walk.operators.has(operation) ? operator = operation : walk.issues.push(wireIssue("querykit.filter.invalid_operator", [...path, "operation"], { operation: label(operation) }))), value !== void 0 && !isFilterValue(value) && walk.issues.push(wireIssue("querykit.filter.invalid_value", [...path, "value"])), walk.strictValue && operator !== void 0 && checkValueShape(operator, value, [...path, "value"], walk);
+}
+function checkValueShape(operator, value, path, walk) {
+  let key = (operator === "in" || operator === "notIn") && !Array.isArray(value) ? "querykit.filter.value_requires_array" : (operator === "between" || operator === "notBetween") && (!Array.isArray(value) || value.length !== 2) ? "querykit.filter.value_requires_tuple" : (operator === "isNull" || operator === "isNotNull") && value !== void 0 ? "querykit.filter.value_forbidden" : void 0;
+  key && walk.issues.push(wireIssue(key, path, { operation: operator }));
+}
+function walkGroup(group, depth, path, walk) {
+  if (!Array.isArray(group)) {
+    walk.issues.push(wireIssue("querykit.filter.invalid_group", path));
+    return;
+  }
+  group.forEach((child, index) => walkNode(child, depth + 1, [...path, index], walk));
+}
+function walkNode(node, depth, path, walk) {
+  if (depth > walk.maxDepth) {
+    walk.issues.push(wireIssue("querykit.filter.max_depth", path, { max: walk.maxDepth }));
+    return;
+  }
+  if (!isRecord3(node)) {
+    walk.issues.push(wireIssue("querykit.filter.invalid_node", path));
+    return;
+  }
+  "key" in node ? checkCondition(node, path, walk) : "and" in node ? walkGroup(node.and, depth, [...path, "and"], walk) : "or" in node ? walkGroup(node.or, depth, [...path, "or"], walk) : "not" in node ? walkNode(node.not, depth + 1, [...path, "not"], walk) : walk.issues.push(wireIssue("querykit.filter.missing_key", path));
+}
+function checkFilter(value, options = {}) {
+  if (value === void 0) return [];
+  let limits = resolveLimits(options), violation = findFilterLimitViolation(value, limits);
+  if (violation) {
+    let key = violation.limit === "maxDepth" ? "querykit.filter.max_depth" : "querykit.limit.exceeded";
+    return [wireIssue(key, violation.path, { limit: violation.limit, max: violation.max })];
+  }
+  let walk = {
+    issues: [],
+    allowedKeys: options.allowedKeys ? new Set(options.allowedKeys) : void 0,
+    operators: options.allowedOperators ? new Set(options.allowedOperators) : ALL_OPERATORS,
+    maxDepth: limits.maxDepth,
+    strictValue: options.strictValue ?? false
+  };
+  return Array.isArray(value) ? value.forEach((item, index) => checkCondition(item, [index], walk)) : walkNode(value, 1, [], walk), walk.issues;
+}
+function checkSort(value, options = {}) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) return [wireIssue("querykit.sort.not_array", [])];
+  let { maxSortFields } = resolveLimits(options);
+  if (value.length > maxSortFields) return [wireIssue("querykit.limit.exceeded", [], { limit: "maxSortFields", max: maxSortFields })];
+  let allowedKeys = options.allowedKeys ? new Set(options.allowedKeys) : void 0, issues = [];
+  return value.forEach((item, index) => {
+    if (!isRecord3(item)) {
+      issues.push(wireIssue("querykit.sort.invalid_item", [index]));
+      return;
+    }
+    let { key, direction } = item;
+    if (typeof key != "string") {
+      issues.push(wireIssue("querykit.sort.missing_key", [index]));
+      return;
+    }
+    allowedKeys && !allowedKeys.has(key) && issues.push(wireIssue("querykit.sort.unknown_key", [index], { key })), direction !== void 0 && direction !== "asc" && direction !== "desc" && issues.push(wireIssue("querykit.sort.invalid_direction", [index, "direction"]));
+  }), issues;
+}
+var prefixed = (path, issues) => issues.map((found) => ({ ...found, path: [...path, ...found.path] })), accepts = (expected, value) => expected === "object" ? isRecord3(value) : expected === "string or null" ? value === null || typeof value == "string" : typeof value === expected, typed = (expected) => (value, path, issues) => {
+  accepts(expected, value) || issues.push(wireIssue("querykit.params.invalid_type", path, { expected: `${expected === "object" ? "an" : "a"} ${expected}` }));
+}, oneOf = (values) => (value, path, issues) => {
+  (typeof value != "string" || !values.includes(value)) && issues.push(wireIssue("querykit.params.invalid_enum", path, { values: values.join(", ") }));
+}, integer = (min, max, overLimit) => (value, path, issues) => {
+  typeof value != "number" || !Number.isFinite(value) ? issues.push(wireIssue("querykit.params.invalid_type", path, { expected: "a number" })) : Number.isInteger(value) ? value < min ? issues.push(wireIssue("querykit.params.out_of_range", path, { min })) : value > max && overLimit ? issues.push(wireIssue("querykit.limit.exceeded", path, { limit: overLimit, max })) : value > max && issues.push(wireIssue("querykit.params.out_of_range", path, { max })) : issues.push(wireIssue("querykit.params.not_integer", path));
+}, checkColumns = (value, path, issues) => {
+  if (typed("object")(value, path, issues), isRecord3(value)) for (let [name, flag] of Object.entries(value)) typed("boolean")(flag, [...path, name], issues);
+}, serverOwnedCheck = (field) => field === "columns" ? checkColumns : typed(field === "with" ? "object" : "boolean");
+function fieldChecks(kind, options, limits) {
+  let checks = /* @__PURE__ */ new Map();
+  checks.set("filter", (value, path, issues) => issues.push(...prefixed(path, checkFilter(value, limits)))), kind !== "cursor" && checks.set("sort", (value, path, issues) => issues.push(...prefixed(path, checkSort(value, limits))));
+  for (let field of options.allow ?? []) checks.set(field, serverOwnedCheck(field));
+  let maxLimit = options.maxLimit ?? 200;
+  return kind === "offset" ? (checks.set("page", integer(1, Number.POSITIVE_INFINITY)), checks.set("perPage", integer(1, options.maxPerPage ?? 200)), checks.set("withTotal", typed("boolean"))) : kind === "infinite" ? (checks.set("limit", integer(1, maxLimit)), checks.set("offset", integer(0, limits.maxOffset, "maxOffset"))) : (checks.set("limit", integer(1, maxLimit)), checks.set("cursor", typed("string or null")), checks.set("cursorKey", typed("string")), checks.set("order", oneOf(["asc", "desc"])), checks.set("direction", oneOf(["forward", "backward"]))), checks;
+}
+function checkParams(kind, value, options = {}) {
+  if (!isRecord3(value)) return { issues: [wireIssue("querykit.params.invalid_type", [], { expected: "an object" })] };
+  let limits = resolveLimits(options.limits), checks = fieldChecks(kind, options, limits), issues = [], accepted = {};
+  for (let [name, field] of Object.entries(value)) {
+    let check = checks.get(name);
+    if (!check || field === void 0) continue;
+    let before = issues.length;
+    check(field, [name], issues), issues.length === before && (accepted[name] = field);
+  }
+  if (kind === "offset" && issues.length === 0) {
+    let page = typeof accepted.page == "number" ? accepted.page : void 0, perPage = typeof accepted.perPage == "number" ? accepted.perPage : void 0;
+    offsetOf(page, perPage) > limits.maxOffset && issues.push(wireIssue("querykit.limit.exceeded", ["page"], { limit: "maxOffset", max: limits.maxOffset }));
+  }
+  return issues.length ? { issues } : { value: accepted, issues };
+}
+
+// src/internal/messages.ts
+var QUERYKIT_MESSAGES_EN = {
+  "querykit.filter.invalid_node": "{path} must be a filter condition or an and/or/not group",
+  "querykit.filter.missing_key": "{path} is missing the required `key` string",
+  "querykit.filter.unknown_key": "{path}: `{key}` is not an allowed filter key",
+  "querykit.filter.invalid_operator": "{path}: `{operation}` is not a supported filter operator",
+  "querykit.filter.invalid_value": "{path} must be a string, number, boolean, null, or an array of those",
+  "querykit.filter.invalid_group": "{path} must be an array of filter nodes",
+  "querykit.filter.max_depth": "{path} exceeds maxDepth ({max})",
+  "querykit.filter.value_requires_array": "{path}: `{operation}` requires an array value",
+  "querykit.filter.value_requires_tuple": "{path}: `{operation}` requires exactly two values",
+  "querykit.filter.value_forbidden": "{path}: `{operation}` must not carry a value",
+  "querykit.sort.not_array": "{path} must be an array of { key, direction } items",
+  "querykit.sort.invalid_item": "{path} must be an object with a `key` string",
+  "querykit.sort.missing_key": "{path} is missing the required `key` string",
+  "querykit.sort.unknown_key": "{path}: `{key}` is not an allowed sort key",
+  "querykit.sort.invalid_direction": "{path}: direction must be `asc` or `desc`",
+  "querykit.limit.exceeded": "{path} exceeds {limit} ({max})"
+}, QUERYKIT_PARAMS_MESSAGES_EN = {
+  "querykit.params.invalid_type": "{path} must be {expected}",
+  "querykit.params.not_integer": "{path} must be an integer",
+  // args carry only the crossed bound (`min` or `max`), so the text names neither
+  "querykit.params.out_of_range": "{path} is out of the allowed range",
+  "querykit.params.invalid_enum": "{path} must be one of: {values}"
+}, PLACEHOLDER = /\{(\w+)\}/g, interpolate = (template, args) => template.replace(PLACEHOLDER, (match, name) => {
+  let value = args[name];
+  return value === void 0 ? match : String(value);
+});
+function formatMessage(key, args = {}, catalog = QUERYKIT_MESSAGES_EN) {
+  return interpolate(catalog[key], args);
+}
+
+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 };
 //# sourceMappingURL=internal.js.map
 //# sourceMappingURL=internal.js.map