@querykitjs/web 3.1.0 → 4.1.0

package/dist/vue/index.d.ts

@@ -0,0 +1,64 @@
+import { AdapterName, ListSchema, UrlConfig, WithFor, ListPayload, SortInput, Resource } from '../index.js';
+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 };

package/dist/vue/index.js

@@ -0,0 +1,2 @@
+import {useRoute,useRouter}from'vue-router';import {computed,toValue}from'vue';import'@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=computed(()=>toValue(t.searchParams)),d=computed(()=>n.read(m.value)),c=()=>n.actions(m.value);return {params:computed(()=>d.value.params),clamped: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=useRoute(),e=useRouter();return f(a,{...t,searchParams:()=>P(s.query),setSearchParams:r=>{e.push({query:g(r)});}})}export{T as useListParams,f as useListParamsBase};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/vue/index.js.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.js","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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@querykitjs/web",
-  "version": "3.1.0",
+  "version": "4.1.0",
   "description": "Frontend query-building for querykit — typed filters, pagination params & URL sync. Zero-dependency; you send the request.",
   "type": "module",
   "author": {
@@ -23,18 +23,62 @@
   "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"
+      }
     },
     "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/react/index.js",
-      "require": "./dist/react/index.cjs"
+      "import": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      },
+      "require": {
+        "types": "./dist/react/index.d.cts",
+        "default": "./dist/react/index.cjs"
+      }
+    },
+    "./vue": {
+      "import": {
+        "types": "./dist/vue/index.d.ts",
+        "default": "./dist/vue/index.js"
+      },
+      "require": {
+        "types": "./dist/vue/index.d.cts",
+        "default": "./dist/vue/index.cjs"
+      }
+    },
+    "./angular": {
+      "import": {
+        "types": "./dist/angular/index.d.ts",
+        "default": "./dist/angular/index.js"
+      },
+      "require": {
+        "types": "./dist/angular/index.d.cts",
+        "default": "./dist/angular/index.cjs"
+      }
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "react": [
+        "./dist/react/index.d.ts"
+      ],
+      "vue": [
+        "./dist/vue/index.d.ts"
+      ],
+      "angular": [
+        "./dist/angular/index.d.ts"
+      ]
     }
   },
   "files": [
     "dist",
+    "skills/querykit-web",
     "README.md",
     "README.en.md",
     "LICENSE"
@@ -43,31 +87,70 @@
   "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/url-state.ts && bun run test/vue.ts && bun run test/angular.ts && bun run test:real-routers",
+    "test:angular": "bun run test/angular.ts",
+    "test:real-routers": "bun run test/real-router-react.ts && bun run test/real-router-vue.ts && bun run test/real-router-angular.ts",
+    "test:url-state": "bun run test/url-state.ts",
+    "test:hook": "bun run test/hook.ts",
+    "test:vue": "bun run test/vue.ts"
   },
   "dependencies": {
-    "@querykitjs/core": "^1.2.0"
+    "@querykitjs/core": "^2.1.0"
   },
   "peerDependencies": {
-    "react": ">=18",
-    "react-router-dom": ">=6"
+    "react": "^18.3 || ^19.2.7",
+    "react-router": "^7.0 || ^8.0",
+    "vue": "^3.5",
+    "vue-router": "^4.6 || ^5",
+    "@angular/core": "^21 || ^22",
+    "@angular/router": "^21 || ^22",
+    "rxjs": "^7.8"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
     },
-    "react-router-dom": {
+    "react-router": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "vue-router": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@angular/router": {
+      "optional": true
+    },
+    "rxjs": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
-    "react": "^19.0.0",
-    "react-router-dom": "^7.0.0"
+    "@angular/common": "22.2.4",
+    "@angular/compiler": "22.2.4",
+    "@angular/core": "22.2.4",
+    "@angular/platform-browser": "22.2.4",
+    "@angular/router": "22.2.4",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "happy-dom": "21.0.4",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "react-router": "8.5.1",
+    "rxjs": "7.8.2",
+    "vue": "3.5.44",
+    "vue-router": "5.4.0"
   },
   "keywords": [
     "querykit",
@@ -78,6 +161,8 @@
     "url-state",
     "search-params",
     "react",
+    "vue",
+    "angular",
     "frontend",
     "typescript"
   ]

package/skills/querykit-web/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: querykit-web
+description: Use when frontend code builds or reads a querykit list request (@querykitjs/web, /react, /vue, /angular) - createRegistry({ adapter }), qk.resource<T>(name), f filters, sort, list / infinite / cursor payloads, withTotal, parseList / parseInfinite / parseCursor, search, adapter-aware with, defineListSchema and URL helpers (readListParams, setPage, setSort), useListParams / useListParamsBase (clamped) for React and Vue, injectListParams for Angular, createListState, fromSearchParams for SSR, query keys, or reading a 400 with isQueryKitError.
+---
+
+## Safety rules
+
+- DO treat the server as the authority: `filterable`, `sortable` and the filter limits live in the backend repository and its validator. The web package does not repeat them, so a refused filter comes back as a 400.
+- DON'T write `page` / `perPage` / `limit` math by hand. Build every payload with `resource.list` / `infinite` / `cursor` (or `buildListParams` …): `perPage` and `limit` are clamped to `200`, and an offset past `maxOffset` (`10000`) or more than `maxSortFields` (`3`) sort fields throws an `Error`. Use a cursor for deep pages.
+- DO read list state from the URL with `readListParams`, `fromSearchParams` or `useListParams`: they never throw, they clamp a too-deep `page` or too-long `sort` and report it as `clamped: true` (`clamped` is not sent to the server).
+- DON'T send `columns`, `with` or `withDeleted` unless the backend opened them on purpose (validator `allow`, repository `relations`). In `with`, name only the relations and columns the backend lists in `relations`; anything else is `forbidden-key`.
+- DO send dates as ISO strings: the wire is JSON.
+- DO read a 400 body with `isQueryKitError(body)` and use its `reason`, `site` and `key` (for example, mark the field named by `key`).
+- DO handle `withTotal: false`: `meta.totalCount` and `meta.totalPages` are then `null`, so show "next" / "previous" from `hasNext` / `hasPrev` instead of a page count.
+
+## When to use
+
+- A browser or SSR frontend (React, Next.js, Vue, Nuxt, Angular, any fetch client) that talks to a querykit backend.
+- Building list, infinite-scroll or cursor request bodies, keeping filters in the URL, and caching with TanStack Query or SWR.
+
+The package builds the payload only. You send the request yourself.
+
+## Setup
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+interface User {
+  id: number;
+  name: string;
+  status: "active" | "blocked";
+  createdAt: string;
+}
+
+export const qk = createRegistry({
+  adapter: "drizzle-pg", // "mongoose" | "mongodb" | "drizzle-pg" | "drizzle-sqlite" | "prisma-pg" — types `with` only
+  defaults: { perPage: 20, limit: 20 },
+  timestamps: { createdAt: "createdAt" }, // same name as the backend; the default sort is this field, desc
+});
+export const users = qk.resource<User>("users"); // the name is the cache-key namespace
+```
+
+## Common tasks
+
+### Filter, sort and an offset page
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+const users = createRegistry({ adapter: "prisma-pg" }).resource<{ id: number; name: string; age: number; createdAt: string }>("users");
+const { f } = users;
+
+const body = users.list({
+  filter: f.and(f.gte("age", 18), f.or(f.contains("name", "ali"), f.isNull("age"))),
+  sort: [
+    { key: "name", direction: "asc" },
+    { key: "createdAt", direction: "desc" },
+  ],
+  page: 2,
+  perPage: 20,
+  withTotal: false, // the server skips the count
+});
+const res = await fetch("/api/users/list", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+const { data, meta } = users.parseList(await res.json());
+console.log(data.length, meta.totalCount ?? "unknown", meta.hasNext);
+```
+
+### Infinite scroll and cursor payloads
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+const posts = createRegistry({ adapter: "mongoose" }).resource<{ _id: string; title: string; createdAt: string }>("posts");
+
+const feedBody = posts.infinite({ limit: 20, offset: 40 });
+const firstPage = posts.cursor({ limit: 20, order: "desc", cursorKey: "createdAt" }); // no sort on a cursor
+declare const raw: unknown;
+const feed = posts.parseInfinite(raw as Parameters<typeof posts.parseInfinite>[0]);
+const page = posts.parseCursor(raw as Parameters<typeof posts.parseCursor>[0]);
+const nextBody = posts.cursor({ limit: 20, order: "desc", cursorKey: "createdAt", cursor: page.meta.nextCursor });
+console.log(feedBody, firstPage, feed.meta.hasMore, feed.meta.nextOffset, nextBody);
+```
+
+### Search box across several fields
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+const users = createRegistry({ adapter: "drizzle-pg" }).resource<{ id: number; name: string; email: string }>("users");
+
+const filter = users.search("ali", ["name", "email"], { operation: "startsWith" }); // OR of startsWith
+const body = users.list({ filter, page: 1 });
+console.log(body);
+```
+
+### Relations with an adapter-aware `with`
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+
+const posts = createRegistry({ adapter: "drizzle-pg" }).resource<{ id: number; title: string }>("posts");
+
+// only relations and columns the backend lists in `relations`
+const body = posts.list({ with: { author: { columns: { name: true } } }, page: 1 });
+console.log(body.with);
+
+// `@querykitjs/mongodb` loads no relations: `with` is a type error there — fetch the author with a second request
+const comments = createRegistry({ adapter: "mongodb" }).resource<{ _id: string; authorId: string }>("comments");
+const page = comments.list({ page: 1 });
+console.log(page.page);
+```
+
+### Filters in the URL
+
+```ts
+import { defineListSchema, readListParams, setPage, setSort } from "@querykitjs/web";
+
+const schema = defineListSchema({
+  status: { operation: "=", default: "active" },
+  q: { search: ["name", "email"] },
+  createdAt: { range: ["fromDate", "toDate"] },
+});
+
+const read = readListParams(schema, new URLSearchParams("page=9999&size=20&q=ali"));
+console.log(read.page, read.clamped); // 501 true — clamped, never thrown
+
+let sp = new URLSearchParams(location.search);
+sp = setPage(sp, 2);
+sp = setSort(sp, [{ key: "name", direction: "asc" }]); // resets the page
+history.replaceState(null, "", `?${sp.toString()}`);
+```
+
+### React list page with `useListParams`
+
+```tsx
+import { createRegistry } from "@querykitjs/web";
+import { useListParams } from "@querykitjs/web/react";
+
+const users = createRegistry({ adapter: "mongoose" }).resource<{ _id: string; name: string; status: string }>("users");
+const usersSchema = users.schema({ name: { operation: "%_%", trim: true }, status: { operation: "=" } });
+
+export function UsersListPage() {
+  const { params, clamped, setParam, setPage } = useListParams(users, { schema: usersSchema });
+  if (clamped) setPage(params.page ?? 1); // fix a hand-edited URL
+  return (
+    <div>
+      <input placeholder="Name" onChange={event => setParam("name", event.target.value)} />
+      <pre>{JSON.stringify(users.keys.list(params))}</pre>
+    </div>
+  );
+}
+```
+
+### Vue list page with `useListParams`
+
+`@querykitjs/web/vue` has the same composables (peers `vue` ^3.5, `vue-router` 4 / 5). `params`, `clamped` and `searchParams` are computed refs; a setter calls `router.push({ query })`.
+
+```ts
+import { createRegistry } from "@querykitjs/web";
+import { useListParams } from "@querykitjs/web/vue";
+import { computed } from "vue";
+
+const users = createRegistry({ adapter: "drizzle-pg" }).resource<{ id: number; name: string; status: string }>("users");
+const usersSchema = users.schema({ name: { operation: "%_%", trim: true }, status: { operation: "=" } });
+
+// call inside <script setup> or setup()
+export function useUsersList() {
+  const { params, clamped, setParam, setPage } = useListParams(users, { schema: usersSchema });
+  if (clamped.value) setPage(params.value.page ?? 1); // fix a hand-edited URL
+  const queryKey = computed(() => users.keys.list(params.value));
+  return { params, queryKey, setName: (name: string) => setParam("name", name) };
+}
+```
+
+### Angular list page with `injectListParams`
+
+`@querykitjs/web/angular` has the same state as signals (peers `@angular/core`, `@angular/router` 21 / 22, `rxjs`). A setter calls `router.navigate`. Call it in an injection context, or Angular throws `NG0203`.
+
+```ts
+import { computed } from "@angular/core";
+import { createRegistry } from "@querykitjs/web";
+import { injectListParams } from "@querykitjs/web/angular";
+
+const users = createRegistry({ adapter: "drizzle-pg" }).resource<{ id: number; name: string; status: string }>("users");
+const usersSchema = users.schema({ name: { operation: "%_%", trim: true }, status: { operation: "=" } });
+
+// call from a component field initializer or constructor
+export function injectUsersList() {
+  const list = injectListParams(users, { schema: usersSchema });
+  const queryKey = computed(() => users.keys.list(list.params()));
+  return { list, queryKey, setName: (name: string) => list.setParam("name", name) };
+}
+```
+
+### Any other framework with `createListState`
+
+```ts
+import { createListState, createRegistry } from "@querykitjs/web";
+
+const users = createRegistry({ adapter: "prisma-pg" }).resource<{ id: number; name: string }>("users");
+const list = createListState(users, { schema: users.schema({ name: { operation: "%_%" } }) });
+
+const current = new URLSearchParams("name=ali&page=3");
+const { params } = list.read(current); // the payload to send
+const next = list.actions(current).setSort([{ key: "name", direction: "asc" }]); // new params, page reset
+history.pushState(null, "", `?${next.toString()}`);
+```
+
+### SSR payload and a refused request
+
+```ts
+import { createRegistry, isQueryKitError } from "@querykitjs/web";
+
+const users = createRegistry({ adapter: "prisma-pg" }).resource<{ id: number; name: string }>("users");
+const usersSchema = users.schema({ name: { operation: "%_%", trim: true } });
+
+export async function loadUsers(searchParams: URLSearchParams) {
+  const body = users.fromSearchParams(searchParams, { schema: usersSchema });
+  const res = await fetch("https://api.example.com/users/list", { method: "POST", body: JSON.stringify(body) });
+  const json: unknown = await res.json();
+  if (res.status === 400) {
+    const error = (json as { error?: unknown }).error;
+    if (isQueryKitError(error)) return { fieldError: { key: error.key, reason: error.reason, site: error.site } };
+  }
+  return users.parseList(json as Parameters<typeof users.parseList>[0]);
+}
+```
+
+## Request contract
+
+The same JSON shape as every querykit package (`@querykitjs/core`): conditions `{ key, operation?, value? }`, groups `{ and }` / `{ or }` / `{ not }` (a flat array = AND), `sort` always `[{ key, direction? }]`, offset `page` / `perPage` / `withTotal`, infinite `limit` / `offset`, cursor `limit` / `cursor` / `cursorKey` / `order` / `direction` (no `sort`). Meta is snake_case: `total_items`, `total_pages`, `has_next`, `has_more`, `next_offset`, `next_cursor`, `prev_cursor`. The body types are `WireOffsetParams`, `WireInfiniteParams` and `WireCursorParams`; validate with `@querykitjs/zod` or `@querykitjs/class-validator`, then pass the body as is. Refusals are `QueryKitError` with `{ source, site, key, operation?, reason }`.
+
+`parseList` / `parseInfinite` / `parseCursor` map that meta to camelCase: `totalCount`, `totalPages`, `currentPage`, `perPage`, `hasNext`, `hasPrev`; `limit`, `offset`, `count`, `hasMore`, `nextOffset`; `nextCursor`, `prevCursor`.
+
+## Mistakes to avoid
+
+- Expecting `list` / `infinite` / `cursor` to fetch: they return a plain payload object, synchronously.
+- Passing `sort` to `cursor`: cursor pages order by `cursorKey` with `order` and `direction`.
+- Computing `meta.totalCount + 1` without a `null` check: it is `null` after `withTotal: false`.
+- Validating filter size in the browser: depth, condition count and string length are checked by the server only.
+- Using `useListParams` outside react-router: use `useListParamsBase` with your own `searchParams` and `setSearchParams`.