@codewithagents/openapi-react-query 3.12.1 → 3.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +10 -4
  2. package/package.json +10 -9
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  📖 **[Full documentation](https://openapi.codewithagents.de/openapi-react-query)**
9
9
 
10
- Generate typed [React Query v5](https://tanstack.com/query/v5) hooks from an OpenAPI 3.x spec. Run once, get a fully typed `useQuery` hook per GET endpoint and a `useMutation` hook per write operation. No hand-written boilerplate.
10
+ Generate typed [React Query v5](https://tanstack.com/query/v5) hooks from an OpenAPI 3.1 spec. Run once, get a fully typed `useQuery` hook per GET endpoint and a `useMutation` hook per write operation. No hand-written boilerplate.
11
11
 
12
12
  - **One hook per operation**: a `useQuery` variant for every GET and a `useMutation` for every write. Types are derived directly from the generated client, no duplication.
13
13
  - **`queryOptions()` factories**: a plain `xxxQueryOptions()` factory alongside every `useQuery` hook, enabling `queryClient.prefetchQuery()` in Next.js App Router server components and `<HydrationBoundary>` SSR patterns.
@@ -17,7 +17,7 @@ Generate typed [React Query v5](https://tanstack.com/query/v5) hooks from an Ope
17
17
  - **Suspense variants**: set `suspense: true` to generate `useSuspense*` hooks alongside every query hook.
18
18
  - **Prettier-clean output**: every generated file passes `prettier --check` out of the box.
19
19
 
20
- Works alongside [`openapi-zod-ts`](https://www.npmjs.com/package/openapi-zod-ts) which generates the underlying typed fetch client. All generated files are committed without running a formatter. See the [petstore demo](https://github.com/codewithagents/openapi-zod-ts/tree/main/packages/petstore-hono) for a full-stack example combining all four packages.
20
+ This package consumes the typed fetch client emitted by [`openapi-zod-ts`](https://www.npmjs.com/package/openapi-zod-ts): it has a runtime dependency on it, so `openapi-zod-ts` must run first. The generated hooks derive their data and variable types directly from that client output. It sits alongside the other generators in the toolchain, [`@codewithagents/openapi-server`](https://www.npmjs.com/package/@codewithagents/openapi-server) (service interface plus optional `hono | express | fastify | none` router) and [`@codewithagents/openapi-msw`](https://www.npmjs.com/package/@codewithagents/openapi-msw) (seeded MSW v2 handlers), plus the [`@codewithagents/api-errors`](https://www.npmjs.com/package/@codewithagents/api-errors) runtime helper. See the [petstore-fastify demo](https://github.com/codewithagents/openapi-zod-ts/tree/main/packages/petstore-fastify) for the canonical full-stack example that wires these together.
21
21
 
22
22
  ## Install
23
23
 
@@ -26,6 +26,8 @@ npm install -D @codewithagents/openapi-react-query openapi-zod-ts
26
26
  npm install @tanstack/react-query
27
27
  ```
28
28
 
29
+ `@tanstack/react-query ^5` is a peer dependency, and React Query v5 requires React 18 or later. `openapi-zod-ts` is a runtime dependency of this generator and must produce its client output first (see [Generate](#generate)).
30
+
29
31
  ## Configure
30
32
 
31
33
  See the [full configuration reference](https://openapi.codewithagents.de/openapi-react-query#configuration) in the docs for all options including `overrides` and the `--config` CLI flag.
@@ -39,7 +41,8 @@ Create `openapi-react-query.config.json` in your project root:
39
41
  "stale_time": 30000,
40
42
  "gc_time": 300000,
41
43
  "suspense": false,
42
- "auto_invalidate": false
44
+ "auto_invalidate": false,
45
+ "infinite_query": "auto"
43
46
  }
44
47
  ```
45
48
 
@@ -51,6 +54,7 @@ Create `openapi-react-query.config.json` in your project root:
51
54
  | `gc_time` | No | `300000` | `gcTime` in ms applied to all `useQuery` hooks |
52
55
  | `suspense` | No | `false` | When `true`, generates a `useSuspense*` variant alongside every query hook |
53
56
  | `auto_invalidate` | No | `false` | When `true`, mutation hooks auto-invalidate related queries on success |
57
+ | `infinite_query` | No | `'auto'` | `boolean \| 'auto'`. Generates a `useXxxInfinite` hook for paginated list operations. `'auto'` detects paginated GETs; `true` forces generation, `false` disables it |
54
58
  | `overrides` | No | none | Per-resource cache timing (see [Per-resource cache timing](#per-resource-cache-timing)) |
55
59
 
56
60
  ## Generate
@@ -90,7 +94,7 @@ export const taskKeys = {
90
94
  **queryOptions factories**: one per GET operation, for use in RSC / server-side prefetching:
91
95
 
92
96
  ```ts
93
- // Plain function — no hooks, safe to call in any context (RSC, loaders, tests)
97
+ // Plain function, no hooks, safe to call in any context (RSC, loaders, tests)
94
98
  export function listTasksQueryOptions(params?, options?) {
95
99
  return queryOptions({
96
100
  queryKey: taskKeys.list(params),
@@ -310,6 +314,8 @@ Relative paths in each config resolve from the config file's directory.
310
314
 
311
315
  The generator also produces a `test-utils.ts` file alongside `hooks.ts`. It exports `createTestQueryClient()` and `createWrapper()` to eliminate test boilerplate. See [Testing your hooks](https://openapi.codewithagents.de/openapi-react-query#testing-your-hooks) in the docs for copy-pasteable Vitest examples using MSW.
312
316
 
317
+ To mock the HTTP layer those tests hit, [`@codewithagents/openapi-msw`](https://www.npmjs.com/package/@codewithagents/openapi-msw) generates seeded MSW v2 handlers from the same OpenAPI spec, so the request mocks stay in sync with the client the hooks call.
318
+
313
319
  ## Troubleshooting
314
320
 
315
321
  See the [Troubleshooting](https://openapi.codewithagents.de/openapi-react-query#troubleshooting) section in the docs for common issues: cache not invalidating, detail hooks firing with nullish ids, and hooks not working in React Server Components.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codewithagents/openapi-react-query",
3
- "version": "3.12.1",
3
+ "version": "3.12.2",
4
4
  "description": "Generate typed React Query v5 hooks from OpenAPI 3.1 specs",
5
5
  "type": "module",
6
6
  "bin": {
@@ -15,8 +15,8 @@
15
15
  ],
16
16
  "dependencies": {
17
17
  "openapi-types": "^12.1.3",
18
- "prettier": "^3.5.3",
19
- "openapi-zod-ts": "2.0.0"
18
+ "prettier": "^3.8.4",
19
+ "openapi-zod-ts": "2.2.0"
20
20
  },
21
21
  "peerDependencies": {
22
22
  "@tanstack/react-query": "^5.0.0"
@@ -24,11 +24,11 @@
24
24
  "devDependencies": {
25
25
  "@stryker-mutator/core": "^9.6.1",
26
26
  "@stryker-mutator/vitest-runner": "^9.6.1",
27
- "@types/node": "^25.0.0",
28
- "@vitest/coverage-v8": "^4.1.7",
27
+ "@types/node": "^26.0.0",
28
+ "@vitest/coverage-v8": "^4.1.9",
29
29
  "fast-check": "^4.8.0",
30
- "typescript": "^6.0.0",
31
- "vitest": "^4.1.7"
30
+ "typescript": "^6.0.3",
31
+ "vitest": "^4.1.9"
32
32
  },
33
33
  "keywords": [
34
34
  "openapi",
@@ -57,8 +57,9 @@
57
57
  },
58
58
  "scripts": {
59
59
  "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
60
- "test": "vitest run",
61
- "test:coverage": "vitest run --coverage",
60
+ "test": "vitest run --exclude 'src/__tests__/compat-matrix.test.ts'",
61
+ "test:matrix": "vitest run src/__tests__/compat-matrix.test.ts",
62
+ "test:coverage": "vitest run --coverage --exclude 'src/__tests__/compat-matrix.test.ts'",
62
63
  "test:mutation": "stryker run",
63
64
  "lint": "tsc -p tsconfig.build.json --noEmit"
64
65
  }