@querykitjs/web 1.0.0 → 2.0.0

package/dist/registry-DPIEOvLW.d.ts

@@ -0,0 +1,417 @@
+import * as Core from '@querykitjs/core';
+
+/**
+ * Filter/query DSL tiplari — `@querykitjs/core`dan, entity maydoni (`FieldKey`)
+ * bilan ixtisoslashtirilgan. querykit backend (`@querykitjs/drizzle-pg`) qabul
+ * qiladigan wire-format bilan mos (`{key, operation, value}`).
+ */
+
+type FilterOperator = Core.FilterOperator;
+type FilterScalar = Core.FilterScalar;
+type FilterValue = Core.FilterValue;
+/** Entity ustun (maydon) kaliti. */
+type FieldKey<T> = Extract<keyof T, string>;
+/** Bitta maydon sharti (`operation` default `"="`). */
+type FieldCondition<T = Record<string, unknown>> = Core.FieldCondition<FieldKey<T>>;
+type AndGroup<T = Record<string, unknown>> = Core.AndGroup<FieldKey<T>>;
+type OrGroup<T = Record<string, unknown>> = Core.OrGroup<FieldKey<T>>;
+type NotGroup<T = Record<string, unknown>> = Core.NotGroup<FieldKey<T>>;
+/** Filter daraxti tuguni: shart yoki mantiqiy guruh. */
+type FilterNode<T = Record<string, unknown>> = Core.FilterNode<FieldKey<T>>;
+/**
+ * Public filter: daraxt/tugun yoki flat massiv. Flat massiv implicit `AND` va
+ * legacy backend (idistr) `IFilter[]` bilan to'liq mos.
+ */
+type Filter<T = Record<string, unknown>> = Core.Filter<FieldKey<T>>;
+type SortDirection = Core.SortDirection;
+interface Sort {
+    name?: string;
+    direction?: SortDirection;
+}
+/** Sort kirishi: `"-createdAt"` (sortType string) yoki `{ name, direction }`. */
+type SortInput = string | Sort;
+interface Params<T = Record<string, unknown>> {
+    filter?: Filter<T>;
+    sort?: SortInput;
+    columns?: Record<string, boolean>;
+    /** Yuklanadigan relationlar (default `with` deb yuboriladi). */
+    with?: Record<string, unknown>;
+    /** Soft-delete qilingan qatorlarni ham qo'shish (backend read'lari uchun). */
+    withDeleted?: boolean;
+}
+/** Offset (sahifali) paginatsiya kirishi. */
+interface ListParams<T = Record<string, unknown>> extends Params<T> {
+    page?: number;
+    perPage?: number;
+}
+/** Infinite-scroll (limit + offset) paginatsiya kirishi. */
+interface InfiniteParams<T = Record<string, unknown>> extends Params<T> {
+    limit?: number;
+    offset?: number;
+}
+/** Cursor (keyset) paginatsiya kirishi. */
+interface CursorParams<T = Record<string, unknown>> extends Params<T> {
+    limit?: number;
+    cursor?: string | null;
+    cursorKey?: string;
+    order?: SortDirection;
+    direction?: "forward" | "backward";
+}
+/** Normalizatsiya qilingan payload (default field nomlari bilan). */
+interface QueryPayload {
+    filter: FilterNode | FieldCondition[];
+    sort: Sort;
+    columns: Record<string, boolean>;
+    with: Record<string, unknown>;
+}
+interface ListPayload extends QueryPayload {
+    page: number;
+    perPage: number;
+}
+interface InfinitePayload extends QueryPayload {
+    limit: number;
+    offset: number;
+}
+/** Cursor payload — `sort` o'rniga `order`/`direction` boshqaradi. */
+interface CursorPayload {
+    filter: FilterNode | FieldCondition[];
+    columns: Record<string, boolean>;
+    with: Record<string, unknown>;
+    limit: number;
+    cursor: string | null;
+    order: SortDirection;
+    direction: "forward" | "backward";
+    cursorKey?: string;
+}
+/**
+ * Xom (server, snake_case) meta tiplari — `@querykitjs/core`dan (adapter shu
+ * shaklda qaytaradi). Server ba'zi maydonlarni bermasligi mumkinligi uchun
+ * mapper'lar `Partial` qabul qiladi.
+ */
+type RawMeta = Partial<Core.OffsetMeta>;
+type RawInfiniteMeta = Partial<Core.InfiniteMeta>;
+type RawCursorMeta = Partial<Core.CursorMeta>;
+/** Offset (list) — normalizatsiya qilingan meta (camelCase). */
+interface Meta {
+    totalPages: number;
+    totalCount: number;
+    currentPage: number;
+    perPage: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/** Infinite-scroll — normalizatsiya qilingan meta. */
+interface InfiniteMeta {
+    limit: number;
+    offset: number;
+    count: number;
+    hasMore: boolean;
+    nextOffset: number | null;
+}
+/** Cursor — normalizatsiya qilingan meta. */
+interface CursorMeta {
+    limit: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+    nextCursor: string | null;
+    prevCursor: string | null;
+}
+
+/** Keys of `T` whose value is assignable to `V`. */
+type ValueKeys<T, V> = {
+    [K in keyof T]-?: NonNullable<T[K]> extends V ? Extract<K, string> : never;
+}[keyof T];
+/** String-valued field keys (for `contains`/`startsWith`/`like`/…). */
+type StringKeys<T> = ValueKeys<T, string>;
+/** Comparable field keys — string/number/bigint/Date (for `gt`/`between`/…). */
+type ComparableKeys<T> = ValueKeys<T, string | number | bigint | Date>;
+type Node<T> = FilterNode<T>;
+/**
+ * Field-type-aware filter builder: string-match operators are offered only for
+ * string fields, comparison only for comparable fields, so nonsensical filters
+ * (e.g. `contains` on a number) are compile errors. Runtime is
+ * `@querykitjs/core`'s builder unchanged.
+ */
+interface TypedFilters<T> {
+    eq<K extends FieldKey<T>>(key: K, value: FilterValue): FieldCondition<T>;
+    ne<K extends FieldKey<T>>(key: K, value: FilterValue): FieldCondition<T>;
+    gt<K extends ComparableKeys<T>>(key: K, value: FilterValue): FieldCondition<T>;
+    gte<K extends ComparableKeys<T>>(key: K, value: FilterValue): FieldCondition<T>;
+    lt<K extends ComparableKeys<T>>(key: K, value: FilterValue): FieldCondition<T>;
+    lte<K extends ComparableKeys<T>>(key: K, value: FilterValue): FieldCondition<T>;
+    between<K extends ComparableKeys<T>>(key: K, min: FilterScalar | Date, max: FilterScalar | Date): FieldCondition<T>;
+    range<K extends ComparableKeys<T>>(key: K, from: FilterScalar | Date, to: FilterScalar | Date): FieldCondition<T>[];
+    contains<K extends StringKeys<T>>(key: K, value: string): FieldCondition<T>;
+    startsWith<K extends StringKeys<T>>(key: K, value: string): FieldCondition<T>;
+    endsWith<K extends StringKeys<T>>(key: K, value: string): FieldCondition<T>;
+    like<K extends StringKeys<T>>(key: K, value: string): FieldCondition<T>;
+    ilike<K extends StringKeys<T>>(key: K, value: string): FieldCondition<T>;
+    notLike<K extends StringKeys<T>>(key: K, value: string): FieldCondition<T>;
+    in<K extends FieldKey<T>>(key: K, value: Array<string | number>): FieldCondition<T>;
+    notIn<K extends FieldKey<T>>(key: K, value: Array<string | number>): FieldCondition<T>;
+    isNull<K extends FieldKey<T>>(key: K): FieldCondition<T>;
+    isNotNull<K extends FieldKey<T>>(key: K): FieldCondition<T>;
+    and(...nodes: Node<T>[]): AndGroup<T>;
+    or(...nodes: Node<T>[]): OrGroup<T>;
+    not(node: Node<T>): NotGroup<T>;
+}
+/**
+ * Typed, ergonomic filter builder for an entity — field-name autocomplete plus
+ * field-type-aware operators (see {@link TypedFilters}).
+ *
+ * @typeParam T - the list entity type (`Buyer`, `Product`, …).
+ * @example
+ * ```ts
+ * const f = createFilters<Buyer>();
+ * const filter = f.and(f.contains("buyerName", s), f.gte("age", 18));
+ * // f.contains("age", …) → compile error (age is a number)
+ * ```
+ */
+declare function createFilters<T = Record<string, unknown>>(): TypedFilters<T>;
+
+/** Forbids the listed keys (`?: never`) so modes can't be mixed. */
+type Without<K extends string> = {
+    [P in K]?: never;
+};
+/** Filter-key override, shared by the single-key modes. */
+interface KeyBase {
+    /** Backend field key (defaults to the schema param name). */
+    key?: string;
+}
+/**
+ * **Simple** mode — one URL param → one condition. `operation` defaults to `"="`;
+ * `trim`/`default`/`split` shape the value.
+ */
+interface SimpleField extends KeyBase {
+    /** Filter operation (default `"="`). */
+    operation?: FilterOperator;
+    /** Trim the string value. */
+    trim?: boolean;
+    /** Value used when the URL param is absent. */
+    default?: FilterValue;
+    /**
+     * For array operations (`in`/`notIn`): split a comma-string into an array.
+     * `true` → delimiter `","`; or a custom delimiter. Guarded: absent/empty →
+     * pruned; parts trimmed, empties dropped.
+     */
+    split?: boolean | string;
+}
+/** **Range** mode — `[fromParam, toParam]` → two inclusive conditions (`>=`, `<=`). */
+interface RangeField extends KeyBase {
+    range: [string, string];
+}
+/** **Between** mode — `[fromParam, toParam]` → one `between` condition (2-tuple). */
+interface BetweenField extends KeyBase {
+    between: [string, string];
+}
+/** **Search** mode — one URL param → OR of `contains` across these field keys. */
+interface SearchField {
+    search: string[];
+    trim?: boolean;
+    default?: FilterValue;
+}
+/**
+ * One list field's URL→filter mapping. Exactly **one mode** per descriptor —
+ * Simple / Range / Between / Search — enforced at compile time (mixing e.g.
+ * `range` + `search`, or `range` + `between`, is a type error).
+ */
+type FieldDescriptor = (SimpleField & Without<"range" | "between" | "search">) | (RangeField & Without<"operation" | "trim" | "default" | "split" | "between" | "search">) | (BetweenField & Without<"operation" | "trim" | "default" | "split" | "range" | "search">) | (SearchField & Without<"key" | "operation" | "split" | "range" | "between">);
+/** URL param → {@link FieldDescriptor} map. */
+type ListSchema = Record<string, FieldDescriptor>;
+/**
+ * Declares a list filter schema (identity helper — preserves the literal type).
+ * Maps URL params to `{key, operation, value}` conditions so pages never build
+ * `IFilter[]` by hand.
+ *
+ * @example
+ * ```ts
+ * const buyersSchema = defineListSchema({
+ *   id: { operation: "=" },
+ *   status: { operation: "=", default: "active" },
+ *   ids: { operation: "in", split: true },
+ *   q: { search: ["name", "email"] },
+ *   createdAt: { range: ["fromDate", "toDate"] },
+ * });
+ * ```
+ */
+declare function defineListSchema<S extends ListSchema>(schema: S): S;
+
+/** URL param nomlari (sahifa/o'lcham/sort) — sozlanadigan. */
+interface UrlConfig {
+    pageParam?: string;
+    sizeParam?: string;
+    sortParam?: string;
+}
+/** `"-createdAt"` → `{ name, direction }` (bo'sh bo'lsa `undefined`). */
+declare function decodeSort(value: string | null | undefined): Sort | undefined;
+/** `{ name, direction }` → `"-createdAt"` / `"createdAt"` (nomsiz bo'lsa `""`). */
+declare function encodeSort(sort: Sort): string;
+/**
+ * Schema + searchParams → filter. Applies `range`/`between`/`search`/`split`/
+ * `default`/`trim`; empty/absent params are dropped. Returns a flat
+ * `FieldCondition[]` (implicit AND), or a tree when a `search` OR-group is
+ * present (`{ and: [orGroup, …conditions] }`).
+ */
+declare function schemaToFilter(schema: ListSchema, searchParams: URLSearchParams): Filter;
+/** searchParams → normalizatsiyalanmagan {@link ListParams} (filter/sort/page/perPage). */
+declare function readListParams(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): ListParams;
+/** searchParams → to'liq, yuborishga tayyor {@link ListPayload}. */
+declare function searchParamsToPayload(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): ListPayload;
+/** Filter param'ini o'rnatadi/o'chiradi va `page`ni reset qiladi. */
+declare function setParam(searchParams: URLSearchParams, name: string, value: string | null | undefined, url?: UrlConfig): URLSearchParams;
+/** Sahifani o'rnatadi (`page` reset qilinmaydi). */
+declare function setPage(searchParams: URLSearchParams, page: number, url?: UrlConfig): URLSearchParams;
+/** Sahifa o'lchamini o'rnatadi va `page`ni reset qiladi. */
+declare function setSize(searchParams: URLSearchParams, size: number, url?: UrlConfig): URLSearchParams;
+/** Sortni o'rnatadi (`"-createdAt"` yoki `{name,direction}`) va `page`ni reset qiladi. */
+declare function setSort(searchParams: URLSearchParams, sort: SortInput, url?: UrlConfig): URLSearchParams;
+/** Barcha list param'larini tozalaydi (ixtiyoriy saqlanadigan kalitlar bilan). */
+declare function resetParams(searchParams: URLSearchParams, keep?: string[]): URLSearchParams;
+
+/**
+ * Per-backend `with` (relation-loading) config shapes. querykit unifies
+ * filter/sort/pagination, but relation loading differs per ORM — so the registry
+ * types `with` from the chosen `adapter`. Only JSON-serializable, wire-safe
+ * options are typed; function callbacks (e.g. Drizzle `where: (f,op)=>…`) and raw
+ * SQL are deliberately **never** included — you can't send them over JSON.
+ */
+/** Mongoose `populate` config (serializable subset). */
+interface MongoosePopulate {
+    select?: string;
+    match?: Record<string, unknown>;
+    options?: Record<string, unknown>;
+    populate?: string | MongoosePopulate | Record<string, boolean | MongoosePopulate>;
+}
+/** Drizzle relational `with` config (serializable subset — no `where`/`orderBy` fns, no SQL). */
+interface DrizzleWith {
+    columns?: Record<string, boolean>;
+    with?: Record<string, boolean | DrizzleWith>;
+    limit?: number;
+    offset?: number;
+}
+/** Prisma relation config (serializable subset). */
+interface PrismaInclude {
+    select?: Record<string, boolean>;
+    include?: Record<string, boolean | PrismaInclude>;
+    where?: Record<string, unknown>;
+    orderBy?: Record<string, unknown>;
+    take?: number;
+    skip?: number;
+}
+/** Supported registry backend adapters. */
+type AdapterName = "mongoose" | "drizzle-pg" | "drizzle-sqlite" | "prisma-pg";
+/** The per-relation `with` value shape for each adapter. */
+interface AdapterWithConfig {
+    mongoose: boolean | MongoosePopulate;
+    "drizzle-pg": boolean | DrizzleWith;
+    "drizzle-sqlite": boolean | DrizzleWith;
+    "prisma-pg": boolean | PrismaInclude;
+}
+/** `with` map typed for an adapter: relation name → its config (boolean or object). */
+type WithFor<A extends AdapterName> = Record<string, AdapterWithConfig[A]>;
+
+type ResourceListParams<T, A extends AdapterName> = Omit<ListParams<T>, "with"> & {
+    with?: WithFor<A>;
+};
+type ResourceInfiniteParams<T, A extends AdapterName> = Omit<InfiniteParams<T>, "with"> & {
+    with?: WithFor<A>;
+};
+type ResourceCursorParams<T, A extends AdapterName> = Omit<CursorParams<T>, "with"> & {
+    with?: WithFor<A>;
+};
+type ResourceParams<T, A extends AdapterName> = Omit<Params<T>, "with"> & {
+    with?: WithFor<A>;
+};
+interface RawResponse<T, M> {
+    data?: T[];
+    meta?: M | null;
+}
+interface ListResult<T> {
+    data: T[];
+    meta: Meta;
+}
+interface InfiniteResult<T> {
+    data: T[];
+    meta: InfiniteMeta;
+}
+interface CursorResult<T> {
+    data: T[];
+    meta: CursorMeta;
+}
+interface ResourceKeys {
+    all: readonly unknown[];
+    list(payload: unknown): readonly unknown[];
+    infinite(payload: unknown): readonly unknown[];
+    cursor(payload: unknown): readonly unknown[];
+    detail(id: unknown): readonly unknown[];
+}
+interface Resource<T, A extends AdapterName> {
+    /** Build an offset (page) payload. */
+    list(input?: ResourceListParams<T, A>): ListPayload;
+    /** Build an infinite (limit/offset) payload. */
+    infinite(input?: ResourceInfiniteParams<T, A>): InfinitePayload;
+    /** Build a cursor (keyset) payload. */
+    cursor(input?: ResourceCursorParams<T, A>): CursorPayload;
+    /** Build a paginationless payload (filter/sort/columns/with). */
+    params(input?: ResourceParams<T, A>): QueryPayload;
+    /** Filter builder typed to `T`'s fields. */
+    f: ReturnType<typeof createFilters<T>>;
+    /** Search preset — OR of `contains` across `fields` (e.g. one input → many columns). */
+    search(term: string, fields: FieldKey<T>[]): Filter<T>;
+    /** Declare a URL↔filter schema (identity helper). */
+    schema<S extends ListSchema>(s: S): S;
+    /** Build a list payload from URL search params (SSR — the non-hook `useListParams`). */
+    fromSearchParams(searchParams: URLSearchParams, options: {
+        schema: ListSchema;
+        url?: UrlConfig;
+        with?: WithFor<A>;
+    }): ListPayload;
+    /** Stable query keys for TanStack/SWR caches. */
+    keys: ResourceKeys;
+    /** Map a list response's meta to camelCase (`data` typed to `T`). */
+    parseList(raw?: RawResponse<T, RawMeta> | null): ListResult<T>;
+    parseInfinite(raw?: RawResponse<T, RawInfiniteMeta> | null): InfiniteResult<T>;
+    parseCursor(raw?: RawResponse<T, RawCursorMeta> | null): CursorResult<T>;
+}
+interface RegistryDefaults {
+    /** `list` page size. */
+    perPage?: number;
+    /** `infinite` + `cursor` page size. */
+    limit?: number;
+    /** `list`/`infinite` sort (`"-createdAt"` or `{name,direction}`). */
+    sort?: SortInput;
+    /** Cursor-only defaults. */
+    cursor?: {
+        order?: SortDirection;
+    };
+}
+interface RegistryConfig<A extends AdapterName> {
+    adapter: A;
+    defaults?: RegistryDefaults;
+    /** Drop empty filter values built from form inputs (default `true`). */
+    pruneEmpty?: boolean;
+}
+interface Registry<A extends AdapterName> {
+    readonly adapter: A;
+    /** Entity-typed builders + filters + schema + keys + parsers. `name` = cache-key namespace (required, must be unique). */
+    resource<T>(name: string): Resource<T, A>;
+    /** Registry-level meta parsing (entity-agnostic — `data: unknown[]`). */
+    parseList(raw?: RawResponse<unknown, RawMeta> | null): ListResult<unknown>;
+    parseInfinite(raw?: RawResponse<unknown, RawInfiniteMeta> | null): InfiniteResult<unknown>;
+    parseCursor(raw?: RawResponse<unknown, RawCursorMeta> | null): CursorResult<unknown>;
+}
+/**
+ * Create a web query registry — configure defaults + backend adapter once, then
+ * `registry.resource<T>()` yields entity-typed, adapter-aware query builders,
+ * filters, a URL↔filter schema, cache keys and meta parsers.
+ *
+ * @example
+ * ```ts
+ * export const qk = createRegistry({ adapter: "mongoose", defaults: { perPage: 20, sort: "-createdAt" } });
+ * const users = qk.resource<IUser>("users");
+ * const body = users.list({ filter: users.f.eq("status", "active"), page });
+ * ```
+ */
+declare function createRegistry<A extends AdapterName>(config: RegistryConfig<A>): Registry<A>;
+
+export { resetParams as $, type AdapterName as A, type ResourceCursorParams as B, type CursorParams as C, type DrizzleWith as D, type ResourceInfiniteParams as E, type Filter as F, type ResourceKeys as G, type ResourceListParams as H, type InfiniteParams as I, type ResourceParams as J, type SortDirection as K, type ListParams as L, type Meta as M, type NotGroup as N, type OrGroup as O, type Params as P, type QueryPayload as Q, type RawCursorMeta as R, type Sort as S, createFilters as T, type UrlConfig as U, createRegistry as V, type WithFor as W, decodeSort as X, defineListSchema as Y, encodeSort as Z, readListParams as _, type CursorPayload as a, schemaToFilter as a0, searchParamsToPayload as a1, setPage as a2, setParam as a3, setSize as a4, setSort as a5, type InfinitePayload as b, type ListPayload as c, type FieldCondition as d, type FilterNode as e, type SortInput as f, type AndGroup as g, type CursorMeta as h, type CursorResult as i, type FieldDescriptor as j, type FieldKey as k, type FilterOperator as l, type FilterScalar as m, type FilterValue as n, type InfiniteMeta as o, type InfiniteResult as p, type ListResult as q, type ListSchema as r, type MongoosePopulate as s, type PrismaInclude as t, type RawInfiniteMeta as u, type RawMeta as v, type Registry as w, type RegistryConfig as x, type RegistryDefaults as y, type Resource as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@querykitjs/web",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Frontend query-building for querykit — typed filters, pagination params & URL sync. Zero-dependency; you send the request.",
   "type": "module",
   "author": {
@@ -50,19 +50,24 @@
     "test:smoke": "bun run test/smoke.ts"
   },
   "dependencies": {
-    "@querykitjs/core": "1.0.0"
+    "@querykitjs/core": "^1.0.0"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "react-router-dom": ">=6"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
-    "react": "^19.0.0"
+    "react": "^19.0.0",
+    "react-router-dom": "^7.0.0"
   },
   "keywords": [
     "querykit",

package/dist/url-BpslCTRx.d.cts

@@ -1,180 +0,0 @@
-import * as _querykitjs_core from '@querykitjs/core';
-
-/**
- * Filter/query DSL tiplari — `@querykitjs/core`dan, entity maydoni (`FieldKey`)
- * bilan ixtisoslashtirilgan. querykit backend (`@querykitjs/drizzle-pg`) qabul
- * qiladigan wire-format bilan mos (`{key, operation, value}`).
- */
-
-type FilterOperator = _querykitjs_core.FilterOperator;
-type FilterScalar = _querykitjs_core.FilterScalar;
-type FilterValue = _querykitjs_core.FilterValue;
-/** Entity ustun (maydon) kaliti. */
-type FieldKey<T> = Extract<keyof T, string>;
-/** Bitta maydon sharti (`operation` default `"="`). */
-type FieldCondition<T = Record<string, unknown>> = _querykitjs_core.FieldCondition<FieldKey<T>>;
-type AndGroup<T = Record<string, unknown>> = _querykitjs_core.AndGroup<FieldKey<T>>;
-type OrGroup<T = Record<string, unknown>> = _querykitjs_core.OrGroup<FieldKey<T>>;
-type NotGroup<T = Record<string, unknown>> = _querykitjs_core.NotGroup<FieldKey<T>>;
-/** Filter daraxti tuguni: shart yoki mantiqiy guruh. */
-type FilterNode<T = Record<string, unknown>> = _querykitjs_core.FilterNode<FieldKey<T>>;
-/**
- * Public filter: daraxt/tugun yoki flat massiv. Flat massiv implicit `AND` va
- * legacy backend (idistr) `IFilter[]` bilan to'liq mos.
- */
-type Filter<T = Record<string, unknown>> = _querykitjs_core.Filter<FieldKey<T>>;
-type SortDirection = _querykitjs_core.SortDirection;
-interface Sort {
-    name?: string;
-    direction?: SortDirection;
-}
-/** Sort kirishi: `"-createdAt"` (sortType string) yoki `{ name, direction }`. */
-type SortInput = string | Sort;
-interface Params<T = Record<string, unknown>> {
-    filter?: Filter<T>;
-    sort?: SortInput;
-    columns?: Record<string, boolean>;
-    /** Yuklanadigan relationlar (default `with` deb yuboriladi). */
-    with?: Record<string, unknown>;
-    /** Soft-delete qilingan qatorlarni ham qo'shish (backend read'lari uchun). */
-    withDeleted?: boolean;
-}
-/** Offset (sahifali) paginatsiya kirishi. */
-interface ListParams<T = Record<string, unknown>> extends Params<T> {
-    page?: number;
-    perPage?: number;
-}
-/** Infinite-scroll (limit + offset) paginatsiya kirishi. */
-interface InfiniteParams<T = Record<string, unknown>> extends Params<T> {
-    limit?: number;
-    offset?: number;
-}
-/** Cursor (keyset) paginatsiya kirishi. */
-interface CursorParams<T = Record<string, unknown>> extends Params<T> {
-    limit?: number;
-    cursor?: string | null;
-    cursorKey?: string;
-    order?: SortDirection;
-    direction?: "forward" | "backward";
-}
-/** Normalizatsiya qilingan payload (default field nomlari bilan). */
-interface QueryPayload {
-    filter: FilterNode | FieldCondition[];
-    sort: Sort;
-    columns: Record<string, boolean>;
-    with: Record<string, unknown>;
-}
-interface ListPayload extends QueryPayload {
-    page: number;
-    perPage: number;
-}
-interface InfinitePayload extends QueryPayload {
-    limit: number;
-    offset: number;
-}
-/** Cursor payload — `sort` o'rniga `order`/`direction` boshqaradi. */
-interface CursorPayload {
-    filter: FilterNode | FieldCondition[];
-    columns: Record<string, boolean>;
-    with: Record<string, unknown>;
-    limit: number;
-    cursor: string | null;
-    order: SortDirection;
-    direction: "forward" | "backward";
-    cursorKey?: string;
-}
-/**
- * Xom (server, snake_case) meta tiplari — `@querykitjs/core`dan (adapter shu
- * shaklda qaytaradi). Server ba'zi maydonlarni bermasligi mumkinligi uchun
- * mapper'lar `Partial` qabul qiladi.
- */
-type RawMeta = Partial<_querykitjs_core.OffsetMeta>;
-type RawInfiniteMeta = Partial<_querykitjs_core.InfiniteMeta>;
-type RawCursorMeta = Partial<_querykitjs_core.CursorMeta>;
-/** Offset (list) — normalizatsiya qilingan meta (camelCase). */
-interface Meta {
-    totalPages: number;
-    totalCount: number;
-    currentPage: number;
-    perPage: number;
-    hasNext: boolean;
-    hasPrev: boolean;
-}
-/** Infinite-scroll — normalizatsiya qilingan meta. */
-interface InfiniteMeta {
-    limit: number;
-    offset: number;
-    count: number;
-    hasMore: boolean;
-    nextOffset: number | null;
-}
-/** Cursor — normalizatsiya qilingan meta. */
-interface CursorMeta {
-    limit: number;
-    hasNext: boolean;
-    hasPrev: boolean;
-    nextCursor: string | null;
-    prevCursor: string | null;
-}
-
-/**
- * Bitta list maydonining deklarativ ta'rifi: URL param → filter shartiga qanday
- * aylantirilishi. `key` berilmasa param nomi ishlatiladi; `operation` default `=`.
- */
-interface FieldDescriptor {
-    /** Backend ustun kaliti (default — schema'dagi param nomi). */
-    key?: string;
-    /** Filter operatori (default `"="`). */
-    operation?: FilterOperator;
-    /** String qiymatni trim qilish. */
-    trim?: boolean;
-    /** Diapazon: `[fromParam, toParam]` URL param nomlari → `>=` va `<=` shartlar. */
-    range?: [string, string];
-}
-/** URL param → {@link FieldDescriptor} tavsiflar to'plami. */
-type ListSchema = Record<string, FieldDescriptor>;
-/**
- * List filter schema'sini e'lon qiladi (identity helper — tiplarni saqlaydi).
- * URL param'larni `{key, operation}` shartlariga bog'laydi, shu bilan har
- * sahifada qo'lda `IFilter[]` qurishni bartaraf qiladi.
- *
- * @example
- * ```ts
- * const buyersSchema = defineListSchema({
- *   id: { operation: "=" },
- *   buyerName: { operation: "%_%", trim: true },
- *   status: { operation: "=" },
- *   createdAt: { range: ["fromDate", "toDate"] },
- * });
- * ```
- */
-declare function defineListSchema<S extends ListSchema>(schema: S): S;
-
-/** URL param nomlari (sahifa/o'lcham/sort) — sozlanadigan. */
-interface UrlConfig {
-    pageParam?: string;
-    sizeParam?: string;
-    sortParam?: string;
-}
-/** `"-createdAt"` → `{ name, direction }` (bo'sh bo'lsa `undefined`). */
-declare function decodeSort(value: string | null | undefined): Sort | undefined;
-/** `{ name, direction }` → `"-createdAt"` / `"createdAt"` (nomsiz bo'lsa `""`). */
-declare function encodeSort(sort: Sort): string;
-/** Schema + searchParams → `FieldCondition[]` (bo'sh param'lar tashlanadi). */
-declare function schemaToFilter(schema: ListSchema, searchParams: URLSearchParams): FieldCondition[];
-/** searchParams → normalizatsiyalanmagan {@link ListParams} (filter/sort/page/perPage). */
-declare function readListParams(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): ListParams;
-/** searchParams → to'liq, yuborishga tayyor {@link ListPayload}. */
-declare function searchParamsToPayload(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): ListPayload;
-/** Filter param'ini o'rnatadi/o'chiradi va `page`ni reset qiladi. */
-declare function setParam(searchParams: URLSearchParams, name: string, value: string | null | undefined, url?: UrlConfig): URLSearchParams;
-/** Sahifani o'rnatadi (`page` reset qilinmaydi). */
-declare function setPage(searchParams: URLSearchParams, page: number, url?: UrlConfig): URLSearchParams;
-/** Sahifa o'lchamini o'rnatadi va `page`ni reset qiladi. */
-declare function setSize(searchParams: URLSearchParams, size: number, url?: UrlConfig): URLSearchParams;
-/** Sortni o'rnatadi (`"-createdAt"` yoki `{name,direction}`) va `page`ni reset qiladi. */
-declare function setSort(searchParams: URLSearchParams, sort: SortInput, url?: UrlConfig): URLSearchParams;
-/** Barcha list param'larini tozalaydi (ixtiyoriy saqlanadigan kalitlar bilan). */
-declare function resetParams(searchParams: URLSearchParams, keep?: string[]): URLSearchParams;
-
-export { type AndGroup as A, setSize as B, type CursorParams as C, setSort as D, type FieldKey as F, type InfiniteParams as I, type ListParams as L, type Meta as M, type NotGroup as N, type OrGroup as O, type Params as P, type QueryPayload as Q, type RawCursorMeta as R, type Sort as S, type UrlConfig as U, type CursorPayload as a, type InfinitePayload as b, type ListPayload as c, type Filter as d, type FieldCondition as e, type FilterNode as f, type SortInput as g, type CursorMeta as h, type RawInfiniteMeta as i, type InfiniteMeta as j, type RawMeta as k, type FieldDescriptor as l, type FilterOperator as m, type FilterScalar as n, type FilterValue as o, type ListSchema as p, type SortDirection as q, decodeSort as r, defineListSchema as s, encodeSort as t, readListParams as u, resetParams as v, schemaToFilter as w, searchParamsToPayload as x, setPage as y, setParam as z };