@querykitjs/web 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@querykitjs/web",
-  "version": "4.0.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": {
@@ -41,12 +41,38 @@
         "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"
       ]
     }
   },
@@ -68,15 +94,24 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test:smoke": "bun run test/smoke.ts",
-    "test:hook": "bun run test/hook.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": "^2.0.0"
+    "@querykitjs/core": "^2.1.0"
   },
   "peerDependencies": {
     "react": "^18.3 || ^19.2.7",
-    "react-router": "^7.0 || ^8.0"
+    "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": {
@@ -84,14 +119,38 @@
     },
     "react-router": {
       "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "vue-router": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@angular/router": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@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"
+    "react-router": "8.5.1",
+    "rxjs": "7.8.2",
+    "vue": "3.5.44",
+    "vue-router": "5.4.0"
   },
   "keywords": [
     "querykit",
@@ -102,6 +161,8 @@
     "url-state",
     "search-params",
     "react",
+    "vue",
+    "angular",
     "frontend",
     "typescript"
   ]

package/skills/querykit-web/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: querykit-web
-description: Use when frontend code builds or reads a querykit list request (@querykitjs/web, @querykitjs/web/react) - 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), fromSearchParams for SSR, query keys, or reading a 400 with isQueryKitError.
+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
@@ -15,7 +15,7 @@ description: Use when frontend code builds or reads a querykit list request (@qu
 
 ## When to use
 
-- A browser or SSR frontend (React, Next.js, any fetch client) that talks to a querykit backend.
+- 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.
@@ -33,7 +33,7 @@ interface User {
 }
 
 export const qk = createRegistry({
-  adapter: "drizzle-pg", // "mongoose" | "drizzle-pg" | "drizzle-sqlite" | "prisma-pg" — types `with` only
+  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
 });
@@ -103,6 +103,11 @@ const posts = createRegistry({ adapter: "drizzle-pg" }).resource<{ id: number; t
 // 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
@@ -146,6 +151,61 @@ export function UsersListPage() {
 }
 ```
 
+### 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