@querykitjs/web 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suhrobbek Soatov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,203 @@
+<div align="right">
+
+**English** · [O'zbekcha](./README.md)
+
+</div>
+
+# @querykitjs/web
+
+> Typed **query-building** for frontends: build filter/sort/pagination payloads, map response meta, sync URL state. It **does not send requests** — you pass the payload to your own `fetch`/`axios`.
+
+React dashboards hand-write the same boilerplate on every list page: build `IFilter[]` from `searchParams`, drop empty filters, `sortType` ↔ `{name,direction}`, "reset page on any change", snake→camel meta. `@querykitjs/web` removes all of it. The payload matches what the querykit backend (`@querykitjs/drizzle-pg`) accepts.
+
+```ts
+import { buildListParams, f, mapMeta } from "@querykitjs/web";
+
+const params = buildListParams({
+  filter: f.and(f.contains("buyerName", search), f.eq("status", status)),
+  sort: "-createdAt",
+  page,
+  perPage: 20,
+});
+const { data, meta } = (await http.post("/buyers/list", params)).data; // your own axios/fetch
+setMeta(mapMeta(meta));
+```
+
+## Features
+
+- **Two filter styles** — `f.eq()...` builder AND object/array (`{key, operation, value}`). Fully compatible with legacy `IFilter[]`.
+- **Normalization** — empty-filter pruning, sort decoding. Values pass through unchanged.
+- **Declarative schema** — `defineListSchema` maps URL params → filters; kills per-page hand-building.
+- **URL-state sync** — `searchParams` ↔ params, `sortType` encode/decode, page-reset. `searchParams` is injected (router-agnostic).
+- **React hook** — `useListParams` (peer `react`, `./react` subpath).
+- **`mapMeta`** — snake→camel pagination meta.
+- **Zero dependency** — no axios/react-query/react-router/dayjs. `react` is an optional peer, only for the hook.
+
+## Install
+
+```bash
+bun add @querykitjs/web
+# For the React hook, having react in your project (peer) is enough
+```
+
+## Filters — two styles
+
+```ts
+import { createFilters } from "@querykitjs/web";
+const f = createFilters<Buyer>(); // column-name autocomplete
+
+// 1) Builder
+filter: f.and(f.contains("buyerName", s), f.eq("status", st));
+
+// 2) Object/array (like idistr) — a flat array is implicit AND
+filter: [
+  { key: "buyerName", operation: "%_%", value: s },
+  { key: "status", operation: "=", value: st },
+];
+```
+
+**Operators:** `= != > >= < <=`, `%_%`/`contains`, `%_`/`startsWith`, `_%`/`endsWith`, `like`, `ilike`, `notLike`, `in`, `notIn`, `between`, `isNull`, `isNotNull` (same set as the querykit backend). Builder helpers: `f.eq/ne/gt/gte/lt/lte`, `f.contains/startsWith/endsWith`, `f.like/ilike/notLike`, `f.in/notIn`, `f.between`, `f.range` (date range → two conditions), `f.isNull/isNotNull`, `f.and/or/not`.
+
+## Building the payload
+
+```ts
+import { buildParams, buildListParams } from "@querykitjs/web";
+
+const payload = buildListParams({
+  filter, // builder or array
+  sort: "-createdAt", // or { name, direction }
+  page,
+  perPage: 20,
+  with: { supervisor: true }, // relations (default `with`)
+});
+// -> { filter:[...pruned], sort:{name,direction}, columns, with, page, perPage }
+```
+
+Empty filters are dropped (`""`/`null`/`undefined`/`[]`), but `0`/`false` are kept. Values are sent through unchanged.
+
+## Pagination modes (offset / infinite / cursor)
+
+Three builders matching the backend's three modes. Each mode's response meta is **different**, so there's a separate mapper for each:
+
+```ts
+import { buildListParams, buildInfiniteParams, buildCursorParams, mapMeta, mapInfiniteMeta, mapCursorMeta } from "@querykitjs/web";
+
+// 1) Offset — page / perPage
+const p = buildListParams({ filter, page: 2, perPage: 20 });
+mapMeta(res.meta); // { totalPages, totalCount, currentPage, perPage, hasNext, hasPrev }
+
+// 2) Infinite — limit / offset
+const p = buildInfiniteParams({ filter, limit: 20, offset: 40 });
+mapInfiniteMeta(res.meta); // { limit, offset, count, hasMore, nextOffset }
+
+// 3) Cursor — limit / cursor / order / direction (sort is ignored)
+const p = buildCursorParams({ filter, limit: 20, cursor, order: "asc" });
+mapCursorMeta(res.meta); // { limit, hasNext, hasPrev, nextCursor, prevCursor }
+
+// withDeleted — include soft-deleted rows
+buildListParams({ filter, withDeleted: true });
+```
+
+## Declarative list schema
+
+Declare once instead of hand-building `IFilter[]` on each page:
+
+```ts
+import { defineListSchema, searchParamsToPayload } from "@querykitjs/web";
+
+const buyersSchema = defineListSchema({
+  id: { operation: "=" },
+  buyerName: { operation: "%_%", trim: true },
+  status: { operation: "=" },
+  createdAt: { range: ["fromDate", "toDate"] }, // → >= and <=
+});
+
+const params = searchParamsToPayload(buyersSchema, searchParams);
+```
+
+## React hook
+
+```tsx
+import { useSearchParams } from "react-router-dom"; // or any source
+import { useListParams } from "@querykitjs/web/react";
+
+function BuyersList() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const { params, setParam, setPage, setSort } = useListParams({
+    searchParams,
+    setSearchParams,
+    schema: buyersSchema,
+  });
+
+  const { data, meta } = useMyList(params); // your own fetch/react-query
+
+  // setParam("status", "active")  -> updates URL, resets page
+  // setPage(2), setSort("-createdAt")
+}
+```
+
+`searchParams` (`URLSearchParams`) and `setSearchParams` are injected — the library is not tied to `react-router`.
+
+## You send the request
+
+The library only handles the work **up to** the request. No transport:
+
+```ts
+// fetch
+const res = await fetch("/api/buyers/list", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(params),
+});
+const { data, meta } = await res.json();
+
+// axios
+const { data } = await http.post("/buyers/list", params);
+setMeta(mapMeta(data.meta));
+```
+
+## Other / legacy backends (custom field names)
+
+Defaults are querykit-canonical camelCase (`perPage`, `with`). For a legacy snake-case backend (e.g. idistr), configure it:
+
+```ts
+import { createQuery } from "@querykitjs/web";
+
+const q = createQuery({ perPageField: "per_page", withField: "withPopulates" });
+const params = q.list({ filter, page, perPage });
+```
+
+## API reference
+
+| Function                                       | Purpose                                |
+| ---------------------------------------------- | -------------------------------------- |
+| `createFilters<T>()` / `f`                     | typed / untyped filter builder         |
+| `buildParams(input)`                           | normalize params (no pagination)       |
+| `buildListParams(input)`                       | + `page`/`perPage` (offset)            |
+| `buildInfiniteParams(input)`                   | + `limit`/`offset` (infinite)          |
+| `buildCursorParams(input)`                     | + `limit`/`cursor`/`order`/`direction` |
+| `createQuery(config)`                          | builder with custom field names        |
+| `defineListSchema(schema)`                     | URL param → filter descriptor          |
+| `schemaToFilter(schema, sp)`                   | searchParams → `FieldCondition[]`      |
+| `searchParamsToPayload(schema, sp)`            | searchParams → full payload            |
+| `readListParams(schema, sp)`                   | searchParams → `ListParams`            |
+| `setParam/setPage/setSize/setSort/resetParams` | URL writes (immutable, page-reset)     |
+| `encodeSort/decodeSort`                        | `{name,direction}` ↔ `"-createdAt"`    |
+| `mapMeta(raw)`                                 | offset meta → camel                    |
+| `mapInfiniteMeta(raw)`                         | infinite meta → camel                  |
+| `mapCursorMeta(raw)`                           | cursor meta → camel                    |
+| `useListParams(opts)` (`/react`)               | URL-sync hook                          |
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun run lint
+bun run build       # tsup -> dist (index + react, ESM + CJS + .d.ts)
+bun run --filter @querykitjs/web test:smoke
+```
+
+## License
+
+MIT © Suhrobbek Soatov

package/README.md

@@ -0,0 +1,203 @@
+<div align="right">
+
+[English](./README.en.md) · **O'zbekcha**
+
+</div>
+
+# @querykitjs/web
+
+> Frontend uchun **tipli query-building**: filter/sort/pagination payloadini quradi, javob meta'sini map qiladi, URL-state sync beradi. **So'rov yubormaydi** — chiqqan payload'ni o'z `fetch`/`axios`ingizga uzatasiz.
+
+React dashboardlar har list sahifasida bir xil boilerplate'ni qo'lda yozadi: `searchParams`'dan `IFilter[]` qurish, bo'sh filterlarni tashlash, `sortType` ↔ `{name,direction}`, "har o'zgarishda page-reset", meta snake→camel. `@querykitjs/web` shularni bartaraf qiladi. Payload querykit backend (`@querykitjs/drizzle-pg`) qabul qiladigan formatda.
+
+```ts
+import { buildListParams, f, mapMeta } from "@querykitjs/web";
+
+const params = buildListParams({
+  filter: f.and(f.contains("buyerName", search), f.eq("status", status)),
+  sort: "-createdAt",
+  page,
+  perPage: 20,
+});
+const { data, meta } = (await http.post("/buyers/list", params)).data; // o'z axios/fetch
+setMeta(mapMeta(meta));
+```
+
+## Imkoniyatlar
+
+- **Ikkala filter uslubi** — `f.eq()...` builder VA object/massiv (`{key, operation, value}`). Legacy `IFilter[]` bilan to'liq mos.
+- **Normalizatsiya** — bo'sh filterlarni prune, sort decode. Qiymatlar o'zgartirilmasdan o'tadi.
+- **Declarative schema** — `defineListSchema` bilan URL param → filter; har sahifadagi qo'lda qurishni yo'q qiladi.
+- **URL-state sync** — `searchParams` ↔ params, `sortType` encode/decode, page-reset. `searchParams` tashqaridan olinadi (router-agnostik).
+- **React hook** — `useListParams` (peer `react`, `./react` subpath).
+- **`mapMeta`** — snake→camel pagination meta.
+- **Zero dependency** — axios/react-query/react-router/dayjs YO'Q. `react` faqat hook uchun ixtiyoriy peer.
+
+## O'rnatish
+
+```bash
+bun add @querykitjs/web
+# React hook uchun loyihangizda react bo'lishi kifoya (peer)
+```
+
+## Filter — ikkala uslub
+
+```ts
+import { createFilters } from "@querykitjs/web";
+const f = createFilters<Buyer>(); // maydon nomi autocomplete
+
+// 1) Builder
+filter: f.and(f.contains("buyerName", s), f.eq("status", st));
+
+// 2) Object/massiv (idistr kabi) — flat massiv = implicit AND
+filter: [
+  { key: "buyerName", operation: "%_%", value: s },
+  { key: "status", operation: "=", value: st },
+];
+```
+
+**Operatorlar:** `= != > >= < <=`, `%_%`/`contains`, `%_`/`startsWith`, `_%`/`endsWith`, `like`, `ilike`, `notLike`, `in`, `notIn`, `between`, `isNull`, `isNotNull` (querykit backend bilan bir xil to'plam). Builder helperlar: `f.eq/ne/gt/gte/lt/lte`, `f.contains/startsWith/endsWith`, `f.like/ilike/notLike`, `f.in/notIn`, `f.between`, `f.range` (sana diapazoni → ikki shart), `f.isNull/isNotNull`, `f.and/or/not`.
+
+## Payload qurish
+
+```ts
+import { buildParams, buildListParams } from "@querykitjs/web";
+
+const payload = buildListParams({
+  filter, // builder yoki massiv
+  sort: "-createdAt", // yoki { name, direction }
+  page,
+  perPage: 20,
+  with: { supervisor: true }, // relations (default `with`)
+});
+// -> { filter:[...pruned], sort:{name,direction}, columns, with, page, perPage }
+```
+
+Bo'sh qiymatli filterlar tashlanadi (`""`/`null`/`undefined`/`[]`), lekin `0`/`false` saqlanadi. Qiymatlar o'zgartirilmasdan yuboriladi.
+
+## Paginatsiya rejimlari (offset / infinite / cursor)
+
+Backend'ning 3 rejimiga mos 3 builder. Har birining javob meta'si **har xil**, shuning uchun alohida mapper bor:
+
+```ts
+import { buildListParams, buildInfiniteParams, buildCursorParams, mapMeta, mapInfiniteMeta, mapCursorMeta } from "@querykitjs/web";
+
+// 1) Offset — page / perPage
+const p = buildListParams({ filter, page: 2, perPage: 20 });
+mapMeta(res.meta); // { totalPages, totalCount, currentPage, perPage, hasNext, hasPrev }
+
+// 2) Infinite — limit / offset
+const p = buildInfiniteParams({ filter, limit: 20, offset: 40 });
+mapInfiniteMeta(res.meta); // { limit, offset, count, hasMore, nextOffset }
+
+// 3) Cursor — limit / cursor / order / direction (sort ishlatilmaydi)
+const p = buildCursorParams({ filter, limit: 20, cursor, order: "asc" });
+mapCursorMeta(res.meta); // { limit, hasNext, hasPrev, nextCursor, prevCursor }
+
+// withDeleted — soft-delete'lilarni ham ko'rish
+buildListParams({ filter, withDeleted: true });
+```
+
+## Declarative list schema
+
+Har sahifada qo'lda `IFilter[]` qurish o'rniga bir marta e'lon qiling:
+
+```ts
+import { defineListSchema, searchParamsToPayload } from "@querykitjs/web";
+
+const buyersSchema = defineListSchema({
+  id: { operation: "=" },
+  buyerName: { operation: "%_%", trim: true },
+  status: { operation: "=" },
+  createdAt: { range: ["fromDate", "toDate"] }, // → >= va <=
+});
+
+const params = searchParamsToPayload(buyersSchema, searchParams);
+```
+
+## React hook
+
+```tsx
+import { useSearchParams } from "react-router-dom"; // yoki boshqa manba
+import { useListParams } from "@querykitjs/web/react";
+
+function BuyersList() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const { params, setParam, setPage, setSort } = useListParams({
+    searchParams,
+    setSearchParams,
+    schema: buyersSchema,
+  });
+
+  const { data, meta } = useMyList(params); // o'z fetch/react-query
+
+  // setParam("status", "active")  -> URL yangilanadi, page reset bo'ladi
+  // setPage(2), setSort("-createdAt")
+}
+```
+
+`searchParams` (`URLSearchParams`) va `setSearchParams` tashqaridan uzatiladi — kutubxona `react-router`ga bog'lanmaydi.
+
+## So'rovni o'zingiz yuborasiz
+
+Kutubxona faqat **so'rovgacha** ishlaydi. Transport yo'q:
+
+```ts
+// fetch
+const res = await fetch("/api/buyers/list", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(params),
+});
+const { data, meta } = await res.json();
+
+// axios
+const { data } = await http.post("/buyers/list", params);
+setMeta(mapMeta(data.meta));
+```
+
+## Boshqa / legacy backend (custom field nomlari)
+
+Default querykit-canonical camelCase (`perPage`, `with`). Eski snake-backend (masalan idistr) uchun sozlang:
+
+```ts
+import { createQuery } from "@querykitjs/web";
+
+const q = createQuery({ perPageField: "per_page", withField: "withPopulates" });
+const params = q.list({ filter, page, perPage });
+```
+
+## API ma'lumotnoma
+
+| Funksiya                                       | Vazifasi                               |
+| ---------------------------------------------- | -------------------------------------- |
+| `createFilters<T>()` / `f`                     | tipli filter builder / tipsiz          |
+| `buildParams(input)`                           | params normalizatsiya (paginatsiyasiz) |
+| `buildListParams(input)`                       | + `page`/`perPage` (offset)            |
+| `buildInfiniteParams(input)`                   | + `limit`/`offset` (infinite)          |
+| `buildCursorParams(input)`                     | + `limit`/`cursor`/`order`/`direction` |
+| `createQuery(config)`                          | custom field nomlari bilan builder     |
+| `defineListSchema(schema)`                     | URL param → filter tavsifi             |
+| `schemaToFilter(schema, sp)`                   | searchParams → `FieldCondition[]`      |
+| `searchParamsToPayload(schema, sp)`            | searchParams → to'liq payload          |
+| `readListParams(schema, sp)`                   | searchParams → `ListParams`            |
+| `setParam/setPage/setSize/setSort/resetParams` | URL yozish (immutable, page-reset)     |
+| `encodeSort/decodeSort`                        | `{name,direction}` ↔ `"-createdAt"`    |
+| `mapMeta(raw)`                                 | offset meta → camel                    |
+| `mapInfiniteMeta(raw)`                         | infinite meta → camel                  |
+| `mapCursorMeta(raw)`                           | cursor meta → camel                    |
+| `useListParams(opts)` (`/react`)               | URL-sync hook                          |
+
+## Ishlab chiqish
+
+```bash
+bun install
+bun run typecheck
+bun run lint
+bun run build       # tsup -> dist (index + react, ESM + CJS + .d.ts)
+bun run --filter @querykitjs/web test:smoke
+```
+
+## Litsenziya
+
+MIT © Suhrobbek Soatov