@querykitjs/core 1.2.0 → 2.1.0

package/dist/raw-AiElbDzC.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Filter operatorlari — yagona runtime manba. `FilterOperator` tipi (`types.ts`)
+ * shundan chiqadi; `@querykitjs/zod` shu massivdan zod enum quradi.
+ */
+declare const FILTER_OPERATORS: readonly ["=", "!=", ">", ">=", "<", "<=", "eq", "ne", "gt", "gte", "lt", "lte", "like", "ilike", "notLike", "contains", "startsWith", "endsWith", "%_%", "%_", "_%", "in", "notIn", "between", "notBetween", "isNull", "isNotNull"];
+/**
+ * Qiymati **text pattern** bo'lgan operatorlar. Backend adapterlari wire qiymatni
+ * ustun/path tipiga cast qilishda shularni chetlab o'tadi — aks holda
+ * `ilike(dateColumn, "%2026%")` ISO string o'rniga `String(Date)` olardi
+ * (`"Mon Jul 28 2026 …"`). Ro'yxat ikki adapterda divergent bo'lmasligi uchun
+ * shu yerda — yagona manba.
+ */
+declare const TEXT_FILTER_OPERATORS: readonly ["like", "ilike", "notLike", "contains", "startsWith", "endsWith", "%_%", "%_", "_%"];
+
+/**
+ * `@querykitjs/core` — ORM-agnostik query DSL tiplari. Backend adapterlar
+ * (`@querykitjs/drizzle-pg`) va frontend (`@querykitjs/web`) shu bir xil kontraktga
+ * tayanadi. Tiplar ustun-kaliti (`TKey`) bo'yicha generic; adapterlar uni o'z
+ * kalit tipiga (Drizzle jadval ustuni yoki entity maydoni) ixtisoslashtiradi.
+ */
+
+/** Qo'llab-quvvatlanadigan filter operatorlari (token va nom aliaslari). */
+type FilterOperator = (typeof FILTER_OPERATORS)[number];
+/**
+ * Tiplangan kalit, lekin har qanday `string` ham qabul qilinadi. Wire (JSON) har
+ * doim string-keyed keladi va adapterlar noma'lum kalitni baribir skip qiladi —
+ * tip shunchaki haqiqatni aytsin, route'da `as` cast kerak bo'lmasin.
+ *
+ * `(string & {})` — autocomplete'ni saqlaydigan TS trick'i: IDE `TKey`
+ * variantlarini taklif qiladi, boshqa string esa xato bermaydi.
+ */
+type LooseKey<TKey extends string> = TKey | (string & {});
+/**
+ * A filter scalar. `Date` is accepted **in-memory** (adapters cast it for local
+ * queries); over the JSON wire it serializes to an ISO string, so
+ * `@querykitjs/zod` validates scalars **without** `Date` (string/number/boolean/null).
+ */
+type FilterScalar = string | number | boolean | Date | null;
+type FilterValue = FilterScalar | FilterScalar[];
+/** Bitta maydon sharti (`operation` default `"="`). */
+interface FieldCondition<TKey extends string = string> {
+    key: TKey;
+    operation?: FilterOperator;
+    value?: FilterValue;
+}
+interface AndGroup<TKey extends string = string, TRaw = never> {
+    and: FilterNode<TKey, TRaw>[];
+}
+interface OrGroup<TKey extends string = string, TRaw = never> {
+    or: FilterNode<TKey, TRaw>[];
+}
+interface NotGroup<TKey extends string = string, TRaw = never> {
+    not: FilterNode<TKey, TRaw>;
+}
+/**
+ * Filter daraxti tuguni: maydon sharti, mantiqiy guruh, yoki adapter qo'shadigan
+ * raw escape-hatch (`TRaw`, masalan Drizzle `SQL`; default `never`).
+ */
+type FilterNode<TKey extends string = string, TRaw = never> = FieldCondition<TKey> | AndGroup<TKey, TRaw> | OrGroup<TKey, TRaw> | NotGroup<TKey, TRaw> | TRaw;
+/** Public filter: daraxt/tugun yoki flat massiv (implicit AND). */
+type Filter<TKey extends string = string, TRaw = never> = FilterNode<TKey, TRaw> | FieldCondition<TKey>[];
+type SortDirection = "asc" | "desc";
+/** One sort field — `{ key, direction }`. */
+interface SortItem<TKey extends string = string> {
+    key: TKey;
+    direction?: SortDirection;
+}
+/** Sort is **always an array** of {@link SortItem} (multi-field capable). */
+type Sort<TKey extends string = string> = SortItem<TKey>[];
+/** Scope qiymati ro'yxat bo'yicha: `{ in: [...] }`; bo'sh ro'yxat — hech qanday qator. */
+interface ScopeIn {
+    in: readonly FilterScalar[];
+}
+/**
+ * Scoped repository'ning har amaliga qo'llanadigan scope: maydon → tenglik qiymati yoki `{ in: [...] }`.
+ * `create` default'lari faqat tenglik scope'laridan olinadi.
+ */
+type Scope<TKey extends string = string> = Partial<Record<TKey, FilterScalar | ScopeIn>>;
+/** Options for upsert / upsertMany — conflict target(s) + optional update set. */
+interface UpsertOptions<TKey extends string = string, TInsert = Record<string, unknown>> {
+    /** Unique/conflict key(s) whose match triggers an update instead of an insert. */
+    target: TKey | TKey[];
+    /** Columns/fields to update on conflict. Defaults to the inserted values minus `target`. */
+    set?: Partial<TInsert>;
+}
+/** Aggregate query spec — group + count/sum/avg/min/max, each keyed by field. */
+interface AggregateSpec<TKey extends string = string, TFilter = unknown> {
+    filter?: TFilter;
+    /** Group rows by these field(s); each appears in the output rows. */
+    groupBy?: TKey | TKey[];
+    count?: boolean;
+    sum?: TKey | TKey[];
+    avg?: TKey | TKey[];
+    min?: TKey | TKey[];
+    max?: TKey | TKey[];
+    withDeleted?: boolean;
+}
+/** Paginatsiyasiz umumiy wire params. */
+interface WireBaseParams {
+    filter?: Filter;
+    sort?: Sort;
+    columns?: Record<string, boolean>;
+    with?: Record<string, unknown>;
+    withDeleted?: boolean;
+}
+/** Offset (sahifali) wire params. */
+interface WireOffsetParams extends WireBaseParams {
+    page?: number;
+    perPage?: number;
+    /**
+     * `false` — umumiy son so'ralmaydi (count yo'q): `perPage + 1` qator o'qiladi,
+     * `has_next` shundan, `total_items` / `total_pages` = `null`. Default `true`.
+     */
+    withTotal?: boolean;
+}
+/** Infinite-scroll wire params. */
+interface WireInfiniteParams extends WireBaseParams {
+    limit?: number;
+    offset?: number;
+}
+/** Cursor (keyset) wire params — `sort` yo'q, tartib `order` + `direction` bilan. */
+interface WireCursorParams extends Omit<WireBaseParams, "sort"> {
+    limit?: number;
+    cursor?: string | null;
+    cursorKey?: string;
+    order?: SortDirection;
+    direction?: "forward" | "backward";
+}
+/**
+ * Shart nima uchun tashlab yuborilgani yoki rad etilgani. `forbidden-key`,
+ * `forbidden-operator` va `limit-exceeded` — server siyosati (`filterable` /
+ * `sortable` / `limits`): ular **hech qachon jim tashlanmaydi**, `strict`dan qat'i nazar
+ * `QueryKitError` bo'ladi.
+ */
+type SkipReason = "unknown-key" | "invalid-value" | "forbidden-key" | "forbidden-operator" | "limit-exceeded" | "empty-filter";
+/**
+ * Shart qayerda tashlab yuborilgani (`page` — offset chuqurligi, `mutation` — `updateWhere` / `deleteWhere` filtri,
+ * `with` — `relations` ro'yxatida yo'q relation, ustun yoki filtr).
+ */
+type SkipSite = "filter" | "sort" | "cursorKey" | "aggregate" | "page" | "mutation" | "with";
+/**
+ * Server siyosati: maydon → ruxsat etilgan operatorlar, yoki `"*"` (hammasi — faqat aniq
+ * yozilganda). Ro'yxatda yo'q maydon yoki operator `QueryKitError` beradi.
+ */
+type Filterable<TKey extends string = string> = Partial<Record<TKey, readonly FilterOperator[] | "*">>;
+/** Tashlab yuborilgan bitta shart haqida ma'lumot. */
+interface SkippedCondition {
+    /** Jadval (drizzle) yoki model (mongoose) nomi. */
+    source: string;
+    site: SkipSite;
+    key: string;
+    operation?: FilterOperator;
+    reason: SkipReason;
+}
+/** Offset (sahifali) paginatsiya meta'si. */
+interface OffsetMeta {
+    /** `withTotal: false` bilan `null` (count so'ralmagan). */
+    total_items: number | null;
+    /** `withTotal: false` bilan `null`. */
+    total_pages: number | null;
+    current_page: number;
+    per_page: number;
+    has_next: boolean;
+    has_prev: boolean;
+}
+/** Infinite-scroll paginatsiya meta'si. */
+interface InfiniteMeta {
+    limit: number;
+    offset: number;
+    count: number;
+    has_more: boolean;
+    next_offset: number | null;
+}
+/** Cursor (keyset) paginatsiya meta'si. */
+interface CursorMeta {
+    limit: number;
+    has_next: boolean;
+    has_prev: boolean;
+    next_cursor: string | null;
+    prev_cursor: string | null;
+}
+/**
+ * `updateWhere` / `deleteWhere` uchun "hamma qatorlar" — faqat shu aniq ko'rsatilsa filtrsiz
+ * mutatsiya bajariladi (scope baribir qo'llanadi). Bo'sh filtr — `QueryKitError` `empty-filter`.
+ */
+interface AllRows {
+    all: true;
+}
+/** `updateWhere` / `deleteWhere` opsiyalari: `returning: { limit }` — ta'sirlangan qatorlardan ko'pi bilan `limit` tasi. */
+interface MutationOptions {
+    returning?: false | {
+        limit: number;
+    };
+}
+/** Ta'sirlangan qatorlar soni. */
+interface MutationCount {
+    count: number;
+}
+/** `returning: { limit }` bilan: soni va ko'pi bilan `limit` ta qator. */
+interface MutationRows<TRow> extends MutationCount {
+    rows: TRow[];
+}
+/**
+ * Bitta relation uchun mijoz `with` ruxsati (R21): `columns` majburiy — ro'yxat yoki aniq `"*"`;
+ * `filterable` — relation filtrida (prisma `where`, mongoose `match`) ruxsat etilgan maydonlar;
+ * `nested` — shu relation ichidagi `with` uchun xuddi shu shakl (yo'q ⇒ ichki `with` — `forbidden-key`).
+ */
+interface RelationRule {
+    columns: readonly string[] | "*";
+    filterable?: Filterable;
+    nested?: Relations;
+}
+/** Repository `relations`: relation → {@link RelationRule}. Ro'yxatda yo'q relation — `forbidden-key`, `site: "with"`. */
+type Relations = Record<string, RelationRule>;
+
+/**
+ * Umumiy pagination default'lari — yagona manba. Backend adapter (`createRegistry`
+ * options) va frontend (`createQuery` config) shu qiymatlarni fallback sifatida
+ * ishlatadi, shuning uchun ular hech qachon bir-biridan farq qilmaydi.
+ */
+/** Offset (list) sahifa o'lchami default'i. */
+declare const DEFAULT_PER_PAGE = 20;
+/** Infinite/cursor `limit` default'i. */
+declare const DEFAULT_LIMIT = 20;
+/**
+ * `perPage` uchun yuqori chegara — cap'siz paginatsiya DoS yuzasi. Validatsiya
+ * (`@querykitjs/zod` factory'lari), backend repositorylari va frontend `createQuery`
+ * shu bitta qiymatga tayanadi, shuning uchun ular hech qachon farq qilmaydi.
+ */
+declare const DEFAULT_MAX_PER_PAGE = 200;
+/** Infinite/cursor `limit` uchun yuqori chegara. Qarang: {@link DEFAULT_MAX_PER_PAGE}. */
+declare const DEFAULT_MAX_LIMIT = 200;
+/** Longest root-to-leaf path of a filter tree, in nodes: the root is level 1, every `and`/`or`/`not` and the condition itself add one. */
+declare const DEFAULT_MAX_FILTER_DEPTH = 5;
+/** Field conditions (leaves) in one filter, across all groups. */
+declare const DEFAULT_MAX_CONDITIONS = 30;
+/** Items in one array filter value (`in`, `notIn`, …). */
+declare const DEFAULT_MAX_IN_ITEMS = 200;
+/** Characters in one string filter value, also inside an array value. */
+declare const DEFAULT_MAX_STRING_LENGTH = 256;
+/** Rows skipped before a page: `(page - 1) × perPage` for offset pagination, `offset` for infinite. Deeper pages need a cursor. */
+declare const DEFAULT_MAX_OFFSET = 10000;
+/** Fields in one `sort` array. */
+declare const DEFAULT_MAX_SORT_FIELDS = 3;
+/**
+ * Wildcards (`%`, `_`) in one `like` / `ilike` / `notLike` pattern, after a run
+ * of `%` counts as one. Each extra wildcard multiplies the matcher's backtracking
+ * (`%a%a%a…%b`), on MongoDB's regex engine and on Postgres alike.
+ */
+declare const DEFAULT_MAX_LIKE_WILDCARDS = 2;
+/** The six request limits, by the option name every package uses. */
+interface QueryLimits {
+    maxDepth: number;
+    maxConditions: number;
+    maxInItems: number;
+    maxStringLength: number;
+    maxOffset: number;
+    maxSortFields: number;
+    maxLikeWildcards: number;
+}
+/** The core defaults as one object. */
+declare const DEFAULT_QUERY_LIMITS: Readonly<QueryLimits>;
+/**
+ * The defaults with the given limits on top; an `undefined` entry keeps the
+ * default. `Infinity` turns a limit off (⚠️ a DoS surface).
+ *
+ * @example
+ * ```ts
+ * resolveLimits({ maxInItems: 50 }); // { maxDepth: 5, …, maxInItems: 50, … }
+ * ```
+ */
+declare function resolveLimits(limits?: Partial<QueryLimits>): QueryLimits;
+
+/**
+ * Brand a driver-native filter object so an adapter accepts it as a filter node.
+ * The object itself is returned (non-enumerable brand), so the driver receives
+ * exactly what you wrote.
+ *
+ * @example
+ * ```ts
+ * import { raw } from "@querykitjs/core";
+ * repo.findAll({ filter: { and: [{ key: "status", value: "active" }, raw({ posts: { some: { published: true } } })] } });
+ * ```
+ */
+declare function raw<T extends object>(value: T): T;
+/** Whether a filter node was branded with {@link raw}. */
+declare const isRaw: (node: unknown) => boolean;
+
+export { DEFAULT_LIMIT as D, TEXT_FILTER_OPERATORS as T, raw as X, resolveLimits as Y, isRaw as Z, DEFAULT_MAX_CONDITIONS as f, DEFAULT_MAX_FILTER_DEPTH as g, DEFAULT_MAX_IN_ITEMS as h, DEFAULT_MAX_LIKE_WILDCARDS as i, DEFAULT_MAX_LIMIT as j, DEFAULT_MAX_OFFSET as k, DEFAULT_MAX_PER_PAGE as l, DEFAULT_MAX_SORT_FIELDS as m, DEFAULT_MAX_STRING_LENGTH as n, DEFAULT_PER_PAGE as o, DEFAULT_QUERY_LIMITS as p, FILTER_OPERATORS as q };
+export type { AndGroup as A, SkipReason as B, CursorMeta as C, SkipSite as E, FilterValue as F, Sort as G, SortDirection as H, InfiniteMeta as I, SortItem as J, WireCursorParams as K, LooseKey as L, MutationCount as M, NotGroup as N, OrGroup as O, WireInfiniteParams as P, QueryLimits as Q, RelationRule as R, SkippedCondition as S, UpsertOptions as U, WireOffsetParams as V, WireBaseParams as W, FieldCondition as a, FilterScalar as b, FilterNode as c, AggregateSpec as d, AllRows as e, Filter as r, FilterOperator as s, Filterable as t, MutationOptions as u, MutationRows as v, OffsetMeta as w, Relations as x, Scope as y, ScopeIn as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@querykitjs/core",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "ORM-agnostic query DSL shared by querykit packages — filters, operators & wire types.",
   "type": "module",
   "author": {
@@ -23,26 +23,52 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./dist/internal.d.ts",
+        "default": "./dist/internal.js"
+      },
+      "require": {
+        "types": "./dist/internal.d.cts",
+        "default": "./dist/internal.cjs"
+      }
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "internal": [
+        "./dist/internal.d.ts"
+      ]
     }
   },
   "files": [
     "dist",
     "README.md",
     "README.en.md",
-    "LICENSE"
+    "LICENSE",
+    "skills"
   ],
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=22.12"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test:smoke": "bun run test/smoke.ts"
+    "test:smoke": "bun run test/smoke.ts && bun run test/internal.ts"
   },
   "keywords": [
     "querykit",

package/skills/querykit-core/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: querykit-core
+description: Use when code creates or reads querykit filters, sort, pagination params or response meta, writes a querykit adapter or validator, or handles QueryKitError. @querykitjs/core is the single source of the request contract shared by every querykit package (backend adapters, zod and class-validator, the web client) - filter helpers (createFilters, f), operators, wire param and meta types, pagination defaults and caps, request limits, skip diagnostics.
+---
+
+## Safety rules
+
+- DO cap page sizes with `DEFAULT_MAX_PER_PAGE` / `DEFAULT_MAX_LIMIT` (both `200`) imported from `@querykitjs/core`. Uncapped pagination is a DoS surface.
+- DON'T write your own page-size cap (`100`, `500`, …) next to querykit code; the validators, the repositories and the web client all read the core constants.
+- DO keep the request limits (`DEFAULT_QUERY_LIMITS`: filter depth `5`, conditions `30`, array items `200`, string length `256`, offset `10 000`, sort fields `3`). Raise one per schema or DTO with `limits` (`resolveLimits` fills the rest), never by turning a limit off; deeper pages than `maxOffset` go through cursor pagination.
+- DON'T redeclare `FieldCondition`, `Filter`, `Sort`, `Wire*Params` or `*Meta` in an app or an adapter; import them from `@querykitjs/core` so both ends of the wire share one type.
+- DO send dates over the wire as ISO strings. `Date` is accepted only in-memory (`FilterScalar`); adapters cast the string from the column type.
+- DON'T forward client `columns`, `with` or `withDeleted` (fields of `WireBaseParams`) to a repository unchecked; projection belongs to the server (`forcedColumns` / `allowedColumns` on the backend adapters; a client `with` opens only the repository's `relations` allow-list).
+- DO make dropped conditions visible: a backend adapter skips an unknown key or an invalid value silently unless you pass `onSkippedCondition` (receives a `SkippedCondition`) or `strict: true` (throws `QueryKitError`).
+- DON'T treat `forbidden-key` / `forbidden-operator` / `limit-exceeded` / `empty-filter` as skippable: they mean the server policy refused the request (`empty-filter`: an `updateWhere` / `deleteWhere` without a condition — pass `{ all: true }` on purpose), and adapters throw them even without `strict`.
+- DO wrap a driver-native filter object in `raw()` (from `@querykitjs/core`) when server code needs one; an unbranded object is refused as `forbidden-key`. DON'T build a `raw()` node from request data — the `filterable` policy does not look inside it.
+- DO map `QueryKitTimeoutError` (`code: "QUERYKIT_TIMEOUT"`, a read past `maxTimeMS`) to 503/504, not 400 — the request was valid.
+- DO map `QueryKitError` to HTTP 400; check `err instanceof QueryKitError`, or `err.code === "QUERYKIT_INVALID_CONDITION"` across RPC/worker boundaries. DON'T match on the message text.
+
+## When to use
+
+- Building a typed filter tree on the server or in tests (`createFilters`, `f`).
+- Typing a request body or response meta shared between backend and frontend.
+- Writing a new adapter or validator that must follow the querykit contract.
+- Reading the list of supported operators (`FILTER_OPERATORS`, `TEXT_FILTER_OPERATORS`).
+
+Backend adapters (`@querykitjs/drizzle-pg`, `@querykitjs/prisma-pg`, `@querykitjs/mongoose`), validators (`@querykitjs/zod`, `@querykitjs/class-validator`) and `@querykitjs/web` re-use these types; reach for their own skills for repository, validation or client code.
+
+## Setup
+
+```bash
+npm install @querykitjs/core
+```
+
+```ts
+import { createFilters, DEFAULT_MAX_PER_PAGE, QueryKitError, type Filter } from "@querykitjs/core";
+
+const uf = createFilters<"status">();
+const filter: Filter<"status"> = uf.eq("status", "active");
+export { filter, DEFAULT_MAX_PER_PAGE, QueryKitError };
+```
+
+## Common tasks
+
+### Build a typed filter
+
+`createFilters<TKey>()` binds the helpers to your keys; `f` is the same set without key typing. A flat array is an implicit AND; `range` returns two conditions (`>=` and `<=`) to spread into it.
+
+```ts
+import { createFilters, type Filter } from "@querykitjs/core";
+
+type UserKey = "status" | "age" | "name" | "createdAt";
+const uf = createFilters<UserKey>();
+
+export const tree: Filter<UserKey> = uf.and(uf.eq("status", "active"), uf.gte("age", 18), uf.or(uf.contains("name", "ali"), uf.isNull("name")));
+
+export const flat: Filter<UserKey> = [uf.in("status", ["active", "invited"]), ...uf.range("createdAt", "2026-01-01", "2026-12-31")];
+```
+
+### Cap a page size
+
+```ts
+import { DEFAULT_MAX_PER_PAGE, DEFAULT_PER_PAGE } from "@querykitjs/core";
+
+export function perPageFrom(raw: unknown): number {
+  const requested = typeof raw === "number" && Number.isInteger(raw) && raw > 0 ? raw : DEFAULT_PER_PAGE;
+  return Math.min(requested, DEFAULT_MAX_PER_PAGE);
+}
+```
+
+### Raise one request limit
+
+```ts
+import { DEFAULT_QUERY_LIMITS, resolveLimits, type QueryLimits } from "@querykitjs/core";
+
+// An import endpoint that filters by up to 500 ids; every other limit keeps its default.
+export const importLimits: QueryLimits = resolveLimits({ maxInItems: 500 });
+
+export const isDefaultDepth = importLimits.maxDepth === DEFAULT_QUERY_LIMITS.maxDepth;
+```
+
+### Type a request and its response meta
+
+```ts
+import type { FilterOperator, OffsetMeta, WireOffsetParams } from "@querykitjs/core";
+
+const since: FilterOperator = ">=";
+
+export const request: WireOffsetParams = {
+  filter: [
+    { key: "status", value: "active" },
+    { key: "createdAt", operation: since, value: "2026-01-01T00:00:00.000Z" },
+  ],
+  sort: [{ key: "createdAt", direction: "desc" }],
+  page: 1,
+  perPage: 20,
+};
+
+export function hasMore(meta: OffsetMeta): boolean {
+  return meta.has_next;
+}
+```
+
+### Handle dropped conditions and `QueryKitError`
+
+```ts
+import { QueryKitError, type SkippedCondition } from "@querykitjs/core";
+
+export function logSkipped(info: SkippedCondition): void {
+  console.warn(`querykit skipped ${info.site} "${info.key}" on ${info.source}: ${info.reason}`);
+}
+
+export function toHttpError(err: unknown): { status: 400; error: string; key: string } | null {
+  if (err instanceof QueryKitError) return { status: 400, error: err.message, key: err.info.key };
+  return null;
+}
+```
+
+### Check an operator coming from outside
+
+```ts
+import { FILTER_OPERATORS, TEXT_FILTER_OPERATORS, type FilterOperator } from "@querykitjs/core";
+
+export function isFilterOperator(value: string): value is FilterOperator {
+  return (FILTER_OPERATORS as readonly string[]).includes(value);
+}
+
+export function isTextOperator(operation: FilterOperator): boolean {
+  return (TEXT_FILTER_OPERATORS as readonly string[]).includes(operation);
+}
+```
+
+## Request contract
+
+The same JSON shape travels from `@querykitjs/web` through a validator to a backend repository.
+
+| Part          | Shape                                                                                        | Core type                                  |
+| ------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| condition     | `{ key, operation?, value? }` — `operation` defaults to `"="`                                | `FieldCondition`                           |
+| groups        | `{ and: [...] }`, `{ or: [...] }`, `{ not: node }`; a flat array = AND                       | `FilterNode`, `Filter`                     |
+| sort          | always an array: `[{ key, direction? }]`, `direction` `"asc"` / `"desc"`                     | `Sort`, `SortItem`                         |
+| offset page   | `page`, `perPage` (default `20`, cap `200`)                                                  | `WireOffsetParams`                         |
+| infinite      | `limit` (default `20`, cap `200`), `offset`                                                  | `WireInfiniteParams`                       |
+| cursor        | `limit`, `cursor`, `cursorKey`, `order`, `direction` (`"forward"` / `"backward"`); no `sort` | `WireCursorParams`                         |
+| response meta | snake_case: `total_items`, `per_page`, `has_next`, `next_cursor`, …                          | `OffsetMeta`, `InfiniteMeta`, `CursorMeta` |
+
+Operators: comparison `=` `!=` `>` `>=` `<` `<=` (aliases `eq` `ne` `gt` `gte` `lt` `lte`); text `like` `ilike` `notLike` `contains` `startsWith` `endsWith` (tokens `%_%` = contains, `%_` = startsWith, `_%` = endsWith); sets `in` `notIn`; ranges `between` `notBetween` (value `[min, max]`); `isNull` `isNotNull` (no value).
+
+Request limits (`QueryLimits`, defaults in `DEFAULT_QUERY_LIMITS`): `maxDepth` `5` (root-to-leaf nodes; the root and the condition each count one level), `maxConditions` `30` (field conditions across all groups), `maxInItems` `200` (items in one array value), `maxStringLength` `256` (characters in one string value, also inside an array), `maxOffset` `10000` (`(page - 1) × perPage`, or infinite `offset`), `maxSortFields` `3`, `maxLikeWildcards` `2` (`%`/`_` in one `like`/`ilike`/`notLike` pattern; a run of `%%` counts once; checked by the adapters' policy). A validator error names the limit and its value, e.g. `maxInItems (200)`.
+
+Skip diagnostics: `SkippedCondition` = `{ source, site, key, operation?, reason }`, `site` one of `filter` `sort` `cursorKey` `aggregate` `page` `mutation` `with`, `reason` one of `unknown-key` `invalid-value` (dropped, or thrown under `strict`) and `forbidden-key` `forbidden-operator` `limit-exceeded` `empty-filter` (server policy / empty mutation filter: always thrown as `QueryKitError`, never dropped). `Filterable` = field → allowed operators or `"*"`.
+
+## Mistakes to avoid
+
+- Sending `sort` as an object (`{ createdAt: "desc" }`) — it is always an array of `{ key, direction }`.
+- Putting a `Date` in a JSON body — send the ISO string; `@querykitjs/zod` validates wire scalars without `Date`.
+- Sending `between` as two values or two conditions — on the wire its `value` is one array `[min, max]`.
+- Adding `sort` to cursor params — `WireCursorParams` has no `sort`; ordering comes from `order` and `direction`.
+- Using `f` where the keys are known — `createFilters<TKey>()` catches a mistyped key at compile time.
+- Treating an empty result as "no match" while a filter key is misspelled — wire `onSkippedCondition` or `strict` first.