@querykitjs/web 3.1.0 → 4.1.0

package/dist/{registry-B1WohYab.d.cts → registry-CEq4xFui.d.cts}

@@ -1,5 +1,49 @@
 import * as Core from '@querykitjs/core';
 
+/**
+ * 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" | "mongodb" | "drizzle-pg" | "drizzle-sqlite" | "prisma-pg";
+/** The per-relation `with` value shape for each adapter. */
+interface AdapterWithConfig {
+    mongoose: boolean | MongoosePopulate;
+    /** `never`: `@querykitjs/mongodb` loads no relations and refuses any `with` (`forbidden-key`) — load them with a second request. */
+    mongodb: never;
+    "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]>;
+
 /**
  * Filter/query DSL tiplari — `@querykitjs/core`dan, entity maydoni (`FieldKey`)
  * bilan ixtisoslashtirilgan. querykit backend (`@querykitjs/drizzle-pg`) qabul
@@ -46,6 +90,8 @@ interface Params<T = Record<string, unknown>> {
 interface ListParams<T = Record<string, unknown>> extends Params<T> {
     page?: number;
     perPage?: number;
+    /** `false` — the server runs no count; the meta totals come back `null` (sent only when given). */
+    withTotal?: boolean;
 }
 /** Infinite-scroll (limit + offset) paginatsiya kirishi. */
 interface InfiniteParams<T = Record<string, unknown>> extends Params<T> {
@@ -72,6 +118,8 @@ interface QueryPayload {
 interface ListPayload extends QueryPayload {
     page: number;
     perPage: number;
+    /** Only present when given in the input. */
+    withTotal?: boolean;
 }
 interface InfinitePayload extends QueryPayload {
     limit: number;
@@ -99,8 +147,10 @@ type RawInfiniteMeta = Partial<Core.InfiniteMeta>;
 type RawCursorMeta = Partial<Core.CursorMeta>;
 /** Offset (list) — normalizatsiya qilingan meta (camelCase). */
 interface Meta {
-    totalPages: number;
-    totalCount: number;
+    /** `null` when the request sent `withTotal: false` (no count ran). */
+    totalPages: number | null;
+    /** `null` when the request sent `withTotal: false` (no count ran). */
+    totalCount: number | null;
     currentPage: number;
     perPage: number;
     hasNext: boolean;
@@ -262,10 +312,37 @@ declare function encodeSort(sort: SortInput): string;
  * 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;
+/**
+ * The bounds the URL readers clamp to — the builder's own (`createRegistry`
+ * `defaults`); an absent one is the core default.
+ */
+interface UrlLimits {
+    perPage?: number;
+    maxPerPage?: number;
+    maxOffset?: number;
+    maxSortFields?: number;
+}
+/** {@link ListParams} read from a URL. `clamped` — the URL's page or sort was cut to the limits. */
+type UrlListParams = ListParams & {
+    clamped: boolean;
+};
+/**
+ * A list payload built from a URL. `clamped` is non-enumerable: readable in code,
+ * never serialized, so the wire payload is unchanged.
+ */
+type UrlListPayload = ListPayload & {
+    readonly clamped?: boolean;
+};
+/**
+ * searchParams → normalizatsiyalanmagan {@link ListParams} (filter/sort/page/perPage).
+ * The URL is user input: a page past `maxOffset` becomes the last allowed page and a
+ * sort past `maxSortFields` keeps its first fields, with `clamped: true` — so a
+ * hand-edited `?page=9999` never throws during render. The builders still throw
+ * for a direct call.
+ */
+declare function readListParams(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig, limits?: UrlLimits): UrlListParams;
+/** searchParams → to'liq, yuborishga tayyor {@link ListPayload} (core default limits; clamped like {@link readListParams}). */
+declare function searchParamsToPayload(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): UrlListPayload;
 /** 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). */
@@ -277,48 +354,6 @@ declare function setSort(searchParams: URLSearchParams, sort: SortInput, url?: U
 /** 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>;
 };
@@ -331,6 +366,11 @@ type ResourceCursorParams<T, A extends AdapterName> = Omit<CursorParams<T>, "wit
 type ResourceParams<T, A extends AdapterName> = Omit<Params<T>, "with"> & {
     with?: WithFor<A>;
 };
+/** `resource.search` options. */
+interface SearchOptions {
+    /** The string operator per field (default `"contains"`). */
+    operation?: "contains" | "startsWith" | "endsWith";
+}
 interface RawResponse<T, M> {
     data?: T[];
     meta?: M | null;
@@ -365,16 +405,22 @@ interface Resource<T, A extends AdapterName> {
     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>;
+    /**
+     * Search preset — OR of `operation` (default `contains`) across `fields` (one input → many columns).
+     * Each field must be `filterable` with that operator on the server.
+     */
+    search(term: string, fields: FieldKey<T>[], options?: SearchOptions): 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`). */
+    /**
+     * Build a list payload from URL search params (SSR — the non-hook `useListParams`).
+     * A page or sort past the registry limits is clamped (`clamped`, non-enumerable — never sent).
+     */
     fromSearchParams(searchParams: URLSearchParams, options: {
         schema: ListSchema;
         url?: UrlConfig;
         with?: WithFor<A>;
-    }): ListPayload;
+    }): UrlListPayload;
     /** Stable query keys for TanStack/SWR caches. */
     keys: ResourceKeys;
     /** Map a list response's meta to camelCase (`data` typed to `T`). */
@@ -395,6 +441,10 @@ interface RegistryDefaults {
     maxPerPage?: number;
     /** `limit` upper bound (core `DEFAULT_MAX_LIMIT` = 200). */
     maxLimit?: number;
+    /** Page depth bound (core `DEFAULT_MAX_OFFSET` = 10 000) — a deeper `list`/`infinite` request throws. */
+    maxOffset?: number;
+    /** Sort field count bound (core `DEFAULT_MAX_SORT_FIELDS` = 3) — more fields throw. */
+    maxSortFields?: number;
     /** `list`/`infinite` sort — `[{key,direction}]` or `["-createdAt", "id"]` shorthand. */
     sort?: SortInput;
     /** Cursor-only defaults. */
@@ -402,9 +452,16 @@ interface RegistryDefaults {
         order?: SortDirection;
     };
 }
+/** The backend registry's `timestamps` field names, so the web default sort names the same field. */
+interface RegistryTimestamps {
+    /** The createdAt field (default `"createdAt"`) — the default `list`/`infinite` sort is `[{ key: createdAt, direction: "desc" }]`. */
+    createdAt?: string;
+}
 interface RegistryConfig<A extends AdapterName> {
     adapter: A;
     defaults?: RegistryDefaults;
+    /** Same as the backend registry's `timestamps`; `defaults.sort` wins over it. */
+    timestamps?: RegistryTimestamps;
     /** Drop empty filter values built from form inputs (default `true`). */
     pruneEmpty?: boolean;
 }
@@ -431,4 +488,5 @@ interface Registry<A extends AdapterName> {
  */
 declare function createRegistry<A extends AdapterName>(config: RegistryConfig<A>): Registry<A>;
 
-export { readListParams 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, type SortItem as T, type UrlConfig as U, createFilters as V, type WithFor as W, createRegistry as X, decodeSort as Y, defineListSchema as Z, encodeSort as _, type CursorPayload as a, resetParams as a0, schemaToFilter as a1, searchParamsToPayload as a2, setPage as a3, setParam as a4, setSize as a5, setSort as a6, 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 };
+export { createFilters as $, createRegistry as a0, decodeSort as a1, defineListSchema as a2, encodeSort as a3, readListParams as a4, resetParams as a5, schemaToFilter as a6, searchParamsToPayload as a7, setPage as a8, setParam as a9, setSize as aa, setSort as ab };
+export type { AdapterName as A, RegistryTimestamps as B, CursorParams as C, DrizzleWith as D, ResourceCursorParams as E, Filter as F, ResourceInfiniteParams as G, ResourceKeys as H, InfiniteParams as I, ResourceListParams as J, ResourceParams as K, ListSchema as L, Meta as M, NotGroup as N, OrGroup as O, Params as P, QueryPayload as Q, Resource as R, SortInput as S, SearchOptions as T, UrlConfig as U, SortDirection as V, WithFor as W, SortItem as X, UrlLimits as Y, UrlListParams as Z, UrlListPayload as _, ListPayload as a, Sort as b, CursorPayload as c, InfinitePayload as d, ListParams as e, FieldCondition as f, FilterNode as g, AndGroup as h, CursorMeta as i, CursorResult as j, FieldDescriptor as k, FieldKey as l, FilterOperator as m, FilterScalar as n, FilterValue as o, InfiniteMeta as p, InfiniteResult as q, ListResult as r, MongoosePopulate as s, PrismaInclude as t, RawCursorMeta as u, RawInfiniteMeta as v, RawMeta as w, Registry as x, RegistryConfig as y, RegistryDefaults as z };

package/dist/{registry-B1WohYab.d.ts → registry-CEq4xFui.d.ts}

@@ -1,5 +1,49 @@
 import * as Core from '@querykitjs/core';
 
+/**
+ * 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" | "mongodb" | "drizzle-pg" | "drizzle-sqlite" | "prisma-pg";
+/** The per-relation `with` value shape for each adapter. */
+interface AdapterWithConfig {
+    mongoose: boolean | MongoosePopulate;
+    /** `never`: `@querykitjs/mongodb` loads no relations and refuses any `with` (`forbidden-key`) — load them with a second request. */
+    mongodb: never;
+    "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]>;
+
 /**
  * Filter/query DSL tiplari — `@querykitjs/core`dan, entity maydoni (`FieldKey`)
  * bilan ixtisoslashtirilgan. querykit backend (`@querykitjs/drizzle-pg`) qabul
@@ -46,6 +90,8 @@ interface Params<T = Record<string, unknown>> {
 interface ListParams<T = Record<string, unknown>> extends Params<T> {
     page?: number;
     perPage?: number;
+    /** `false` — the server runs no count; the meta totals come back `null` (sent only when given). */
+    withTotal?: boolean;
 }
 /** Infinite-scroll (limit + offset) paginatsiya kirishi. */
 interface InfiniteParams<T = Record<string, unknown>> extends Params<T> {
@@ -72,6 +118,8 @@ interface QueryPayload {
 interface ListPayload extends QueryPayload {
     page: number;
     perPage: number;
+    /** Only present when given in the input. */
+    withTotal?: boolean;
 }
 interface InfinitePayload extends QueryPayload {
     limit: number;
@@ -99,8 +147,10 @@ type RawInfiniteMeta = Partial<Core.InfiniteMeta>;
 type RawCursorMeta = Partial<Core.CursorMeta>;
 /** Offset (list) — normalizatsiya qilingan meta (camelCase). */
 interface Meta {
-    totalPages: number;
-    totalCount: number;
+    /** `null` when the request sent `withTotal: false` (no count ran). */
+    totalPages: number | null;
+    /** `null` when the request sent `withTotal: false` (no count ran). */
+    totalCount: number | null;
     currentPage: number;
     perPage: number;
     hasNext: boolean;
@@ -262,10 +312,37 @@ declare function encodeSort(sort: SortInput): string;
  * 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;
+/**
+ * The bounds the URL readers clamp to — the builder's own (`createRegistry`
+ * `defaults`); an absent one is the core default.
+ */
+interface UrlLimits {
+    perPage?: number;
+    maxPerPage?: number;
+    maxOffset?: number;
+    maxSortFields?: number;
+}
+/** {@link ListParams} read from a URL. `clamped` — the URL's page or sort was cut to the limits. */
+type UrlListParams = ListParams & {
+    clamped: boolean;
+};
+/**
+ * A list payload built from a URL. `clamped` is non-enumerable: readable in code,
+ * never serialized, so the wire payload is unchanged.
+ */
+type UrlListPayload = ListPayload & {
+    readonly clamped?: boolean;
+};
+/**
+ * searchParams → normalizatsiyalanmagan {@link ListParams} (filter/sort/page/perPage).
+ * The URL is user input: a page past `maxOffset` becomes the last allowed page and a
+ * sort past `maxSortFields` keeps its first fields, with `clamped: true` — so a
+ * hand-edited `?page=9999` never throws during render. The builders still throw
+ * for a direct call.
+ */
+declare function readListParams(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig, limits?: UrlLimits): UrlListParams;
+/** searchParams → to'liq, yuborishga tayyor {@link ListPayload} (core default limits; clamped like {@link readListParams}). */
+declare function searchParamsToPayload(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): UrlListPayload;
 /** 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). */
@@ -277,48 +354,6 @@ declare function setSort(searchParams: URLSearchParams, sort: SortInput, url?: U
 /** 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>;
 };
@@ -331,6 +366,11 @@ type ResourceCursorParams<T, A extends AdapterName> = Omit<CursorParams<T>, "wit
 type ResourceParams<T, A extends AdapterName> = Omit<Params<T>, "with"> & {
     with?: WithFor<A>;
 };
+/** `resource.search` options. */
+interface SearchOptions {
+    /** The string operator per field (default `"contains"`). */
+    operation?: "contains" | "startsWith" | "endsWith";
+}
 interface RawResponse<T, M> {
     data?: T[];
     meta?: M | null;
@@ -365,16 +405,22 @@ interface Resource<T, A extends AdapterName> {
     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>;
+    /**
+     * Search preset — OR of `operation` (default `contains`) across `fields` (one input → many columns).
+     * Each field must be `filterable` with that operator on the server.
+     */
+    search(term: string, fields: FieldKey<T>[], options?: SearchOptions): 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`). */
+    /**
+     * Build a list payload from URL search params (SSR — the non-hook `useListParams`).
+     * A page or sort past the registry limits is clamped (`clamped`, non-enumerable — never sent).
+     */
     fromSearchParams(searchParams: URLSearchParams, options: {
         schema: ListSchema;
         url?: UrlConfig;
         with?: WithFor<A>;
-    }): ListPayload;
+    }): UrlListPayload;
     /** Stable query keys for TanStack/SWR caches. */
     keys: ResourceKeys;
     /** Map a list response's meta to camelCase (`data` typed to `T`). */
@@ -395,6 +441,10 @@ interface RegistryDefaults {
     maxPerPage?: number;
     /** `limit` upper bound (core `DEFAULT_MAX_LIMIT` = 200). */
     maxLimit?: number;
+    /** Page depth bound (core `DEFAULT_MAX_OFFSET` = 10 000) — a deeper `list`/`infinite` request throws. */
+    maxOffset?: number;
+    /** Sort field count bound (core `DEFAULT_MAX_SORT_FIELDS` = 3) — more fields throw. */
+    maxSortFields?: number;
     /** `list`/`infinite` sort — `[{key,direction}]` or `["-createdAt", "id"]` shorthand. */
     sort?: SortInput;
     /** Cursor-only defaults. */
@@ -402,9 +452,16 @@ interface RegistryDefaults {
         order?: SortDirection;
     };
 }
+/** The backend registry's `timestamps` field names, so the web default sort names the same field. */
+interface RegistryTimestamps {
+    /** The createdAt field (default `"createdAt"`) — the default `list`/`infinite` sort is `[{ key: createdAt, direction: "desc" }]`. */
+    createdAt?: string;
+}
 interface RegistryConfig<A extends AdapterName> {
     adapter: A;
     defaults?: RegistryDefaults;
+    /** Same as the backend registry's `timestamps`; `defaults.sort` wins over it. */
+    timestamps?: RegistryTimestamps;
     /** Drop empty filter values built from form inputs (default `true`). */
     pruneEmpty?: boolean;
 }
@@ -431,4 +488,5 @@ interface Registry<A extends AdapterName> {
  */
 declare function createRegistry<A extends AdapterName>(config: RegistryConfig<A>): Registry<A>;
 
-export { readListParams 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, type SortItem as T, type UrlConfig as U, createFilters as V, type WithFor as W, createRegistry as X, decodeSort as Y, defineListSchema as Z, encodeSort as _, type CursorPayload as a, resetParams as a0, schemaToFilter as a1, searchParamsToPayload as a2, setPage as a3, setParam as a4, setSize as a5, setSort as a6, 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 };
+export { createFilters as $, createRegistry as a0, decodeSort as a1, defineListSchema as a2, encodeSort as a3, readListParams as a4, resetParams as a5, schemaToFilter as a6, searchParamsToPayload as a7, setPage as a8, setParam as a9, setSize as aa, setSort as ab };
+export type { AdapterName as A, RegistryTimestamps as B, CursorParams as C, DrizzleWith as D, ResourceCursorParams as E, Filter as F, ResourceInfiniteParams as G, ResourceKeys as H, InfiniteParams as I, ResourceListParams as J, ResourceParams as K, ListSchema as L, Meta as M, NotGroup as N, OrGroup as O, Params as P, QueryPayload as Q, Resource as R, SortInput as S, SearchOptions as T, UrlConfig as U, SortDirection as V, WithFor as W, SortItem as X, UrlLimits as Y, UrlListParams as Z, UrlListPayload as _, ListPayload as a, Sort as b, CursorPayload as c, InfinitePayload as d, ListParams as e, FieldCondition as f, FilterNode as g, AndGroup as h, CursorMeta as i, CursorResult as j, FieldDescriptor as k, FieldKey as l, FilterOperator as m, FilterScalar as n, FilterValue as o, InfiniteMeta as p, InfiniteResult as q, ListResult as r, MongoosePopulate as s, PrismaInclude as t, RawCursorMeta as u, RawInfiniteMeta as v, RawMeta as w, Registry as x, RegistryConfig as y, RegistryDefaults as z };

package/dist/vue/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var vueRouter=require('vue-router'),vue=require('vue');require('@querykitjs/core');function P(a){let t=new URLSearchParams;for(let[s,e]of Object.entries(a))for(let r of Array.isArray(e)?e:[e])r!==void 0&&t.append(s,r??"");return t}function g(a){let t={};for(let s of new Set(a.keys())){let e=a.getAll(s);t[s]=e.length>1?e:e[0]??"";}return t}var p={pageParam:"page",sizeParam:"size",sortParam:"sortType"};function A(a){return a.map(t=>typeof t=="string"?t.trim():t&&t.key?(t.direction==="desc"?"-":"")+t.key:"").filter(Boolean).join(",")}function u(a){return new URLSearchParams(a)}function S(a,t,s,e={}){let r={...p,...e},o=u(a);return o.delete(r.pageParam),s==null||s===""?o.delete(t):o.set(t,s),o}function L(a,t,s={}){let e={...p,...s},r=u(a);return r.set(e.pageParam,String(t)),r}function h(a,t,s={}){let e={...p,...s},r=u(a);return r.delete(e.pageParam),r.set(e.sizeParam,String(t)),r}function y(a,t,s={}){let e={...p,...s},r=u(a);r.delete(e.pageParam);let o=A(t);return o?r.set(e.sortParam,o):r.delete(e.sortParam),r}function U(a,t=[]){let s=new URLSearchParams;for(let e of t){let r=a.get(e);r!==null&&s.set(e,r);}return s}function R(a,t){let{schema:s,url:e,with:r}=t;return {read(o){let n=a.fromSearchParams(o,{schema:s,url:e,with:r});return {params:n,clamped:n.clamped===true}},actions(o){return {setParam:(n,m)=>S(o,n,m,e),setPage:n=>L(o,n,e),setSize:n=>h(o,n,e),setSort:n=>y(o,n,e),reset:n=>U(o,n)}}}}function f(a,t){let{schema:s,setSearchParams:e,url:r,with:o}=t,n=R(a,{schema:s,url:r,with:o}),m=vue.computed(()=>vue.toValue(t.searchParams)),d=vue.computed(()=>n.read(m.value)),c=()=>n.actions(m.value);return {params:vue.computed(()=>d.value.params),clamped:vue.computed(()=>d.value.clamped),searchParams:m,setParam:(i,x)=>e(c().setParam(i,x)),setPage:i=>e(c().setPage(i)),setSize:i=>e(c().setSize(i)),setSort:i=>e(c().setSort(i)),reset:i=>e(c().reset(i))}}function T(a,t){let s=vueRouter.useRoute(),e=vueRouter.useRouter();return f(a,{...t,searchParams:()=>P(s.query),setSearchParams:r=>{e.push({query:g(r)});}})}exports.useListParams=T;exports.useListParamsBase=f;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/vue/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/route-query.ts","../../src/url.ts","../../src/list-state.ts","../../src/vue/use-list-params-base.ts","../../src/vue/use-list-params.ts"],"names":["queryToSearchParams","query","searchParams","key","value","item","searchParamsToQuery","values","URL_DEFAULTS","encodeSort","sort","i","clone","setParam","name","url","cfg","next","setPage","page","setSize","size","setSort","encoded","resetParams","keep","createListState","resource","options","schema","withRel","params","useListParamsBase","setSearchParams","state","computed","toValue","read","actions","useListParams","route","useRoute","router","useRouter"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n^ * A route query as vue-router gives it: v4 has `string | null | (string | null)[]` per key,\n * v5 always an array. `null` is a key without `=` (`?q`).\n */\nexport type RouteQuery = Record<string, string | null | (string | null)[] | undefined>;\n\n/** Route query → search params: a repeated key keeps every value; `null` becomes an empty value. */\nexport function queryToSearchParams(query: RouteQuery): URLSearchParams {\n  const searchParams = new URLSearchParams();\n  for (const [key, value] of Object.entries(query)) {\n    for (const item of Array.isArray(value) ? value : [value]) {\n      if (item !== undefined) searchParams.append(key, item ?? \"\");\n    }\n  }\n  return searchParams;\n}\n\n/** Search params → route query for `router.push({ query })`: one value → string, a repeated key → array. */\nexport function searchParamsToQuery(searchParams: URLSearchParams): Record<string, string | string[]> {\n  const query: Record<string, string | string[]> = {};\n  for (const key of new Set(searchParams.keys())) {\n    const values = searchParams.getAll(key);\n    query[key] = values.length > 1 ? values : (values[0] ?? \"\");\n  }\n  return query;\n}\n","import { DEFAULT_MAX_OFFSET, DEFAULT_MAX_PER_PAGE, DEFAULT_MAX_SORT_FIELDS, DEFAULT_PER_PAGE } from \"@querykitjs/core\";\n\nimport { buildListParams, clampInt } from \"./query\";\nimport type { FieldDescriptor, ListSchema } from \"./schema\";\nimport type { FieldCondition, Filter, FilterNode, FilterValue, ListParams, ListPayload, Sort, SortDirection, SortInput } from \"./types\";\n\n/** URL param nomlari (sahifa/o'lcham/sort) — sozlanadigan. */\nexport interface UrlConfig {\n  pageParam?: string;\n  sizeParam?: string;\n  sortParam?: string;\n}\n\nconst URL_DEFAULTS: Required<UrlConfig> = {\n  pageParam: \"page\",\n  sizeParam: \"size\",\n  sortParam: \"sortType\",\n};\n\n/**\n * `\"-createdAt,id,-appNumber\"` → `[{ key, direction }, …]` — comma-separated,\n * order preserved, `-` prefix = `desc` (else `asc`). Empty → `undefined`.\n */\nexport function decodeSort(value: string | null | undefined): Sort | undefined {\n  if (!value) return undefined;\n  const items = value\n    .split(\",\")\n    .map(s => s.trim())\n    .filter(Boolean)\n    .map(tok => {\n      const desc = tok.startsWith(\"-\");\n      return { key: desc ? tok.slice(1) : tok, direction: (desc ? \"desc\" : \"asc\") as SortDirection };\n    })\n    .filter(i => i.key); // drop empty keys (e.g. a lone \"-\")\n  return items.length ? items : undefined;\n}\n\n/** `[{ key, direction }, …]` (or `\"-field\"` shorthand strings) → `\"-createdAt,id,-appNumber\"` (empty → `\"\"`). */\nexport function encodeSort(sort: SortInput): string {\n  return sort\n    .map(i => (typeof i === \"string\" ? i.trim() : i && i.key ? (i.direction === \"desc\" ? \"-\" : \"\") + i.key : \"\"))\n    .filter(Boolean)\n    .join(\",\");\n}\n\n/**\n * Schema + searchParams → filter. Applies `range`/`between`/`search`/`split`/\n * `default`/`trim`; empty/absent params are dropped. Returns a flat\n * `FieldCondition[]` (implicit AND), or a tree when a `search` OR-group is\n * present (`{ and: [orGroup, …conditions] }`).\n */\nexport function schemaToFilter(schema: ListSchema, searchParams: URLSearchParams): Filter {\n  const conditions: FieldCondition[] = [];\n  const groups: FilterNode[] = [];\n\n  for (const [param, d] of Object.entries(schema) as [string, FieldDescriptor][]) {\n    const key = d.key ?? param;\n\n    // range → two inclusive conditions (>= , <=)\n    if (d.range) {\n      const from = searchParams.get(d.range[0]);\n      const to = searchParams.get(d.range[1]);\n      if (from) conditions.push(cond(key, \">=\", from));\n      if (to) conditions.push(cond(key, \"<=\", to));\n      continue;\n    }\n\n    // between → one condition with a 2-tuple value\n    if (d.between) {\n      const from = searchParams.get(d.between[0]);\n      const to = searchParams.get(d.between[1]);\n      if (from && to) conditions.push(cond(key, \"between\", [from, to]));\n      continue;\n    }\n\n    // read value, falling back to `default` only when the param is ABSENT\n    // (an empty `?x=` means the user cleared the filter → prune, don't default).\n    const raw = searchParams.get(param);\n    let value: FilterValue | undefined = raw !== null ? raw : d.default;\n    if (typeof value === \"string\" && d.trim) value = value.trim();\n    if (value === undefined || value === null || value === \"\") continue;\n    if (Array.isArray(value) && value.length === 0) continue;\n\n    // search → OR of `contains` across the listed fields (needs a string)\n    if (d.search && typeof value === \"string\") {\n      groups.push({ or: d.search.map(field => cond(field, \"%_%\", value as string)) });\n      continue;\n    }\n\n    // split → comma-string → array (for `in`/`notIn`); guarded against empties\n    if (d.split && typeof value === \"string\") {\n      const delimiter = d.split === true ? \",\" : d.split;\n      const parts = value\n        .split(delimiter)\n        .map(s => s.trim())\n        .filter(Boolean);\n      if (parts.length === 0) continue;\n      value = parts;\n    }\n\n    conditions.push(cond(key, d.operation ?? \"=\", value));\n  }\n\n  return groups.length === 0 ? conditions : { and: [...groups, ...conditions] };\n}\n\nfunction cond(key: string, operation: FieldCondition[\"operation\"], value: FilterValue): FieldCondition {\n  return { key, operation, value };\n}\n\n/**\n * The bounds the URL readers clamp to — the builder's own (`createRegistry`\n * `defaults`); an absent one is the core default.\n */\nexport interface UrlLimits {\n  perPage?: number;\n  maxPerPage?: number;\n  maxOffset?: number;\n  maxSortFields?: number;\n}\n\n/** {@link ListParams} read from a URL. `clamped` — the URL's page or sort was cut to the limits. */\nexport type UrlListParams = ListParams & { clamped: boolean };\n\n/**\n * A list payload built from a URL. `clamped` is non-enumerable: readable in code,\n * never serialized, so the wire payload is unchanged.\n */\nexport type UrlListPayload = ListPayload & { readonly clamped?: boolean };\n\n/** Marks a payload with a non-enumerable `clamped` flag. */\nexport function withClamped(payload: ListPayload, clamped: boolean): UrlListPayload {\n  return Object.defineProperty(payload, \"clamped\", { value: clamped, enumerable: false });\n}\n\n/** The last page the builder accepts: `(page - 1) × perPage ≤ maxOffset`. */\nfunction lastPage(perPage: number | undefined, limits: UrlLimits): number {\n  const resolved = clampInt(perPage, limits.perPage ?? DEFAULT_PER_PAGE, limits.maxPerPage ?? DEFAULT_MAX_PER_PAGE);\n  return Math.floor((limits.maxOffset ?? DEFAULT_MAX_OFFSET) / resolved) + 1;\n}\n\n/**\n * searchParams → normalizatsiyalanmagan {@link ListParams} (filter/sort/page/perPage).\n * The URL is user input: a page past `maxOffset` becomes the last allowed page and a\n * sort past `maxSortFields` keeps its first fields, with `clamped: true` — so a\n * hand-edited `?page=9999` never throws during render. The builders still throw\n * for a direct call.\n */\nexport function readListParams(schema: ListSchema, searchParams: URLSearchParams, url: UrlConfig = {}, limits: UrlLimits = {}): UrlListParams {\n  const cfg = { ...URL_DEFAULTS, ...url };\n  const size = searchParams.get(cfg.sizeParam);\n  const perPage = size ? Number(size) : undefined;\n  const page = Math.trunc(Number(searchParams.get(cfg.pageParam))) || 1;\n  const sort = decodeSort(searchParams.get(cfg.sortParam));\n  const maxPage = lastPage(perPage, limits);\n  const maxSortFields = limits.maxSortFields ?? DEFAULT_MAX_SORT_FIELDS;\n  const isPageClamped = page > maxPage;\n  const isSortClamped = sort !== undefined && sort.length > maxSortFields;\n  return {\n    filter: schemaToFilter(schema, searchParams),\n    sort: isSortClamped ? sort.slice(0, maxSortFields) : sort,\n    page: isPageClamped ? maxPage : page,\n    perPage,\n    clamped: isPageClamped || isSortClamped,\n  };\n}\n\n/** searchParams → to'liq, yuborishga tayyor {@link ListPayload} (core default limits; clamped like {@link readListParams}). */\nexport function searchParamsToPayload(schema: ListSchema, searchParams: URLSearchParams, url?: UrlConfig): UrlListPayload {\n  const params = readListParams(schema, searchParams, url);\n  return withClamped(buildListParams(params), params.clamped);\n}\n\n/* ------------------------- URL yozish (immutable) ------------------------- */\n/* Har biri YANGI URLSearchParams qaytaradi; filter/sort o'zgarsa `page` reset. */\n\nfunction clone(searchParams: URLSearchParams): URLSearchParams {\n  return new URLSearchParams(searchParams);\n}\n\n/** Filter param'ini o'rnatadi/o'chiradi va `page`ni reset qiladi. */\nexport function setParam(searchParams: URLSearchParams, name: string, value: string | null | undefined, url: UrlConfig = {}): URLSearchParams {\n  const cfg = { ...URL_DEFAULTS, ...url };\n  const next = clone(searchParams);\n  next.delete(cfg.pageParam);\n  if (value === null || value === undefined || value === \"\") next.delete(name);\n  else next.set(name, value);\n  return next;\n}\n\n/** Sahifani o'rnatadi (`page` reset qilinmaydi). */\nexport function setPage(searchParams: URLSearchParams, page: number, url: UrlConfig = {}): URLSearchParams {\n  const cfg = { ...URL_DEFAULTS, ...url };\n  const next = clone(searchParams);\n  next.set(cfg.pageParam, String(page));\n  return next;\n}\n\n/** Sahifa o'lchamini o'rnatadi va `page`ni reset qiladi. */\nexport function setSize(searchParams: URLSearchParams, size: number, url: UrlConfig = {}): URLSearchParams {\n  const cfg = { ...URL_DEFAULTS, ...url };\n  const next = clone(searchParams);\n  next.delete(cfg.pageParam);\n  next.set(cfg.sizeParam, String(size));\n  return next;\n}\n\n/** Sortni o'rnatadi (`[{ key, direction }, …]`) va `page`ni reset qiladi. */\nexport function setSort(searchParams: URLSearchParams, sort: SortInput, url: UrlConfig = {}): URLSearchParams {\n  const cfg = { ...URL_DEFAULTS, ...url };\n  const next = clone(searchParams);\n  next.delete(cfg.pageParam);\n  const encoded = encodeSort(sort);\n  if (encoded) next.set(cfg.sortParam, encoded);\n  else next.delete(cfg.sortParam);\n  return next;\n}\n\n/** Barcha list param'larini tozalaydi (ixtiyoriy saqlanadigan kalitlar bilan). */\nexport function resetParams(searchParams: URLSearchParams, keep: string[] = []): URLSearchParams {\n  const next = new URLSearchParams();\n  for (const key of keep) {\n    const value = searchParams.get(key);\n    if (value !== null) next.set(key, value);\n  }\n  return next;\n}\n","import type { AdapterName, WithFor } from \"./adapter\";\nimport type { Resource } from \"./registry\";\nimport type { ListSchema } from \"./schema\";\nimport type { ListPayload, SortInput } from \"./types\";\nimport type { UrlConfig } from \"./url\";\nimport { resetParams, setPage, setParam, setSize, setSort } from \"./url\";\n\nexport interface ListStateOptions<A extends AdapterName> {\n  /** URL↔filter schema ({@link defineListSchema} / `resource.schema`). */\n  schema: ListSchema;\n  /** URL param names (page/size/sortType) — optional. */\n  url?: UrlConfig;\n  /** Fixed relations to load on every request (not URL-driven). */\n  with?: WithFor<A>;\n}\n\nexport interface ListStateRead {\n  /** Ready-to-send list payload (built from the URL via the resource's defaults). */\n  params: ListPayload;\n  /** The URL's page or sort was past the limits and was clamped (`?page=9999` → the last allowed page). */\n  clamped: boolean;\n}\n\n/** URL setters: each returns the NEXT search params and never mutates the given ones. */\nexport interface ListStateActions {\n  /** Set/clear a filter param (resets `page`). */\n  setParam: (name: string, value: string | null | undefined) => URLSearchParams;\n  setPage: (page: number) => URLSearchParams;\n  /** Resets `page`. */\n  setSize: (size: number) => URLSearchParams;\n  /** Resets `page`; an empty sort clears the param. */\n  setSort: (sort: SortInput) => URLSearchParams;\n  /** Clears every param except `keep`. */\n  reset: (keep?: string[]) => URLSearchParams;\n}\n\nexport interface ListState {\n  read: (searchParams: URLSearchParams) => ListStateRead;\n  actions: (searchParams: URLSearchParams) => ListStateActions;\n}\n\n/**\n * Framework-free list URL state — the logic behind `useListParams` in `@querykitjs/web/react`\n * and `@querykitjs/web/vue`, for any other framework (Svelte, Solid, vanilla). Pure: it reads\n * search params and returns the next ones; navigating is the caller's job.\n *\n * @example\n * ```ts\n * const list = createListState(users, { schema: usersSchema });\n * const { params, clamped } = list.read(new URLSearchParams(location.search));\n * history.pushState(null, \"\", `?${list.actions(new URLSearchParams(location.search)).setPage(2)}`);\n * ```\n */\nexport function createListState<T, A extends AdapterName>(resource: Resource<T, A>, options: ListStateOptions<A>): ListState {\n  const { schema, url, with: withRel } = options;\n  return {\n    read(searchParams) {\n      const params = resource.fromSearchParams(searchParams, { schema, url, with: withRel });\n      return { params, clamped: params.clamped === true };\n    },\n    actions(searchParams) {\n      return {\n        setParam: (name, value) => setParam(searchParams, name, value, url),\n        setPage: page => setPage(searchParams, page, url),\n        setSize: size => setSize(searchParams, size, url),\n        setSort: sort => setSort(searchParams, sort, url),\n        reset: keep => resetParams(searchParams, keep),\n      };\n    },\n  };\n}\n","import { computed, type ComputedRef, type MaybeRefOrGetter, toValue } from \"vue\";\n\nimport type { AdapterName, WithFor } from \"../adapter\";\nimport { createListState } from \"../list-state\";\nimport type { Resource } from \"../registry\";\nimport type { ListSchema } from \"../schema\";\nimport type { ListPayload, SortInput } from \"../types\";\nimport type { UrlConfig } from \"../url\";\n\nexport interface UseListParamsBaseOptions<A extends AdapterName> {\n  /** URL↔filter schema ({@link defineListSchema} / `resource.schema`). */\n  schema: ListSchema;\n  /** Current URL search params — a ref, a getter or a plain value (from your router). */\n  searchParams: MaybeRefOrGetter<URLSearchParams>;\n  /** Apply new search params (`(next) => void`). */\n  setSearchParams: (next: URLSearchParams) => void;\n  /** URL param names (page/size/sortType) — optional. */\n  url?: UrlConfig;\n  /** Fixed relations to load on every request (not URL-driven). */\n  with?: WithFor<A>;\n}\n\nexport interface UseListParamsResult {\n  /** Ready-to-send list payload (built from the URL via the resource's defaults). */\n  params: ComputedRef<ListPayload>;\n  /**\n   * The URL's page or sort was past the limits and was clamped (`?page=9999` → the last\n   * allowed page). The app may rewrite the URL (`setPage(params.value.page)`).\n   */\n  clamped: ComputedRef<boolean>;\n  searchParams: ComputedRef<URLSearchParams>;\n  /** Set/clear a filter param (resets `page`). */\n  setParam: (name: string, value: string | null | undefined) => void;\n  setPage: (page: number) => void;\n  setSize: (size: number) => void;\n  setSort: (sort: SortInput) => void;\n  reset: (keep?: string[]) => void;\n}\n\n/**\n * Router-agnostic list URL-state composable — the Vue twin of the React\n * `useListParamsBase`: the same reads, clamping and setters, as computed refs. Bring your\n * own `searchParams`/`setSearchParams` (Nuxt `useRoute`, a custom router, …).\n */\nexport function useListParamsBase<T, A extends AdapterName>(resource: Resource<T, A>, options: UseListParamsBaseOptions<A>): UseListParamsResult {\n  const { schema, setSearchParams, url, with: withRel } = options;\n  const state = createListState(resource, { schema, url, with: withRel });\n  const searchParams = computed(() => toValue(options.searchParams));\n  const read = computed(() => state.read(searchParams.value));\n  const actions = () => state.actions(searchParams.value);\n\n  return {\n    params: computed(() => read.value.params),\n    clamped: computed(() => read.value.clamped),\n    searchParams,\n    setParam: (name, value) => setSearchParams(actions().setParam(name, value)),\n    setPage: page => setSearchParams(actions().setPage(page)),\n    setSize: size => setSearchParams(actions().setSize(size)),\n    setSort: sort => setSearchParams(actions().setSort(sort)),\n    reset: keep => setSearchParams(actions().reset(keep)),\n  };\n}\n","import { useRoute, useRouter } from \"vue-router\";\n\nimport type { AdapterName, WithFor } from \"../adapter\";\nimport type { Resource } from \"../registry\";\nimport type { ListSchema } from \"../schema\";\nimport type { UrlConfig } from \"../url\";\nimport { queryToSearchParams, searchParamsToQuery } from \"../route-query\";\nimport { useListParamsBase, type UseListParamsResult } from \"./use-list-params-base\";\n\nexport interface UseListParamsOptions<A extends AdapterName> {\n  /** URL↔filter schema ({@link defineListSchema} / `resource.schema`). */\n  schema: ListSchema;\n  /** URL param names (page/size/sortType) — optional. */\n  url?: UrlConfig;\n  /** Fixed relations to load on every request (not URL-driven). */\n  with?: WithFor<A>;\n}\n\n/**\n * List URL-state composable — turnkey with **vue-router** 4 / 5 (`useRoute` + `useRouter`).\n * Reads filters/sort/page from the route query via the schema, builds a ready-to-send\n * payload through the `resource`, and returns URL setters that `router.push({ query })` (a\n * new history entry; filter/sort/size changes reset `page`). Does **not** fetch.\n *\n * @example\n * ```ts\n * const users = qk.resource<IUser>(\"users\");\n * const { params, setPage, setSort } = useListParams(users, { schema: usersSchema });\n * const { data } = useQuery({ queryKey: computed(() => users.keys.list(params.value)), queryFn: () => post(\"/users/list\", params.value) });\n * ```\n */\nexport function useListParams<T, A extends AdapterName>(resource: Resource<T, A>, options: UseListParamsOptions<A>): UseListParamsResult {\n  const route = useRoute();\n  const router = useRouter();\n  return useListParamsBase(resource, {\n    ...options,\n    searchParams: () => queryToSearchParams(route.query),\n    setSearchParams: next => void router.push({ query: searchParamsToQuery(next) }),\n  });\n}\n"]}

package/dist/vue/index.d.cts

@@ -0,0 +1,64 @@
+import { AdapterName, ListSchema, UrlConfig, WithFor, ListPayload, SortInput, Resource } from '../index.cjs';
+import { MaybeRefOrGetter, ComputedRef } from 'vue';
+import '@querykitjs/core';
+
+interface UseListParamsBaseOptions<A extends AdapterName> {
+    /** URL↔filter schema ({@link defineListSchema} / `resource.schema`). */
+    schema: ListSchema;
+    /** Current URL search params — a ref, a getter or a plain value (from your router). */
+    searchParams: MaybeRefOrGetter<URLSearchParams>;
+    /** Apply new search params (`(next) => void`). */
+    setSearchParams: (next: URLSearchParams) => void;
+    /** URL param names (page/size/sortType) — optional. */
+    url?: UrlConfig;
+    /** Fixed relations to load on every request (not URL-driven). */
+    with?: WithFor<A>;
+}
+interface UseListParamsResult {
+    /** Ready-to-send list payload (built from the URL via the resource's defaults). */
+    params: ComputedRef<ListPayload>;
+    /**
+     * The URL's page or sort was past the limits and was clamped (`?page=9999` → the last
+     * allowed page). The app may rewrite the URL (`setPage(params.value.page)`).
+     */
+    clamped: ComputedRef<boolean>;
+    searchParams: ComputedRef<URLSearchParams>;
+    /** Set/clear a filter param (resets `page`). */
+    setParam: (name: string, value: string | null | undefined) => void;
+    setPage: (page: number) => void;
+    setSize: (size: number) => void;
+    setSort: (sort: SortInput) => void;
+    reset: (keep?: string[]) => void;
+}
+/**
+ * Router-agnostic list URL-state composable — the Vue twin of the React
+ * `useListParamsBase`: the same reads, clamping and setters, as computed refs. Bring your
+ * own `searchParams`/`setSearchParams` (Nuxt `useRoute`, a custom router, …).
+ */
+declare function useListParamsBase<T, A extends AdapterName>(resource: Resource<T, A>, options: UseListParamsBaseOptions<A>): UseListParamsResult;
+
+interface UseListParamsOptions<A extends AdapterName> {
+    /** URL↔filter schema ({@link defineListSchema} / `resource.schema`). */
+    schema: ListSchema;
+    /** URL param names (page/size/sortType) — optional. */
+    url?: UrlConfig;
+    /** Fixed relations to load on every request (not URL-driven). */
+    with?: WithFor<A>;
+}
+/**
+ * List URL-state composable — turnkey with **vue-router** 4 / 5 (`useRoute` + `useRouter`).
+ * Reads filters/sort/page from the route query via the schema, builds a ready-to-send
+ * payload through the `resource`, and returns URL setters that `router.push({ query })` (a
+ * new history entry; filter/sort/size changes reset `page`). Does **not** fetch.
+ *
+ * @example
+ * ```ts
+ * const users = qk.resource<IUser>("users");
+ * const { params, setPage, setSort } = useListParams(users, { schema: usersSchema });
+ * const { data } = useQuery({ queryKey: computed(() => users.keys.list(params.value)), queryFn: () => post("/users/list", params.value) });
+ * ```
+ */
+declare function useListParams<T, A extends AdapterName>(resource: Resource<T, A>, options: UseListParamsOptions<A>): UseListParamsResult;
+
+export { useListParams, useListParamsBase };
+export type { UseListParamsBaseOptions, UseListParamsOptions, UseListParamsResult };