@shipworthy/openapi-tanstack-query 0.0.1 → 0.0.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.
- package/README.md +28 -29
- package/package.json +7 -11
package/README.md
CHANGED
|
@@ -31,34 +31,33 @@ hooks or React provider of its own.
|
|
|
31
31
|
bun add @shipworthy/openapi-tanstack-query @tanstack/react-query react
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
Add the code generators as dev dependencies. `
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
CLI installs the last two. The TypeScript generator bundles TypeScript 7's AST
|
|
34
|
+
Add the code generators as dev dependencies. `@shipworthy/openapi-generator`
|
|
35
|
+
and `@shipworthy/openapi-transformer` are optional peer dependencies that only
|
|
36
|
+
the `./generator` entry point needs. The CLI installs both. The TypeScript generator bundles TypeScript 7's AST
|
|
38
37
|
modules, so your project can keep its own TypeScript version:
|
|
39
38
|
|
|
40
39
|
```sh
|
|
41
|
-
bun add -d @shipworthy/openapi-cli @shipworthy/openapi-typescript
|
|
40
|
+
bun add -d @shipworthy/openapi-cli @shipworthy/openapi-typescript
|
|
42
41
|
```
|
|
43
42
|
|
|
44
|
-
| Requirement | Value
|
|
45
|
-
| -------------------- |
|
|
46
|
-
| Peer dependencies | `@tanstack/react-query` `^5.59.0`, `react` `^18.0.0 \|\| ^19.0.0`
|
|
47
|
-
| Optional peers |
|
|
48
|
-
| Runtime dependencies | `@shipworthy/openapi-fetch` (installed automatically)
|
|
49
|
-
| Module format | `.` ships ESM and CommonJS, each with matching declarations (`.d.ts` and `.d.cts`). `./generator` is ESM only.
|
|
50
|
-
| Entry points | `.` (runtime) and `./generator` (generator plugin), compiled JavaScript with declarations in `dist/`. A `react-native` field points at `./dist/index.js`.
|
|
51
|
-
| Runtime | Any environment with `fetch`, `Request`, and `Response`, or pass your own `fetch`. No TypeScript transpilation of `node_modules` is needed.
|
|
52
|
-
| TypeScript | Declarations type-check with TypeScript `5.0` and later, using `NodeNext` (CommonJS or ESM) or `bundler` module resolution.
|
|
53
|
-
| CLI runtime | The `openapi` binary from `@shipworthy/openapi-cli` runs on **Node.js** `>=22.19.0` or **Bun** (`bunx --bun @shipworthy/openapi-cli`).
|
|
54
|
-
| OpenAPI versions | 3.0.x and 3.1.x. 3.0 documents are upgraded to 3.1 internally. Swagger 2.x is rejected.
|
|
43
|
+
| Requirement | Value |
|
|
44
|
+
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
45
|
+
| Peer dependencies | `@tanstack/react-query` `^5.59.0`, `react` `^18.0.0 \|\| ^19.0.0` |
|
|
46
|
+
| Optional peers | `@shipworthy/openapi-generator` and `@shipworthy/openapi-transformer`, needed only for `./generator` (the CLI and programmatic generation) |
|
|
47
|
+
| Runtime dependencies | `@shipworthy/openapi-fetch` and `effect` (installed automatically; only `./generator` imports `effect`) |
|
|
48
|
+
| Module format | `.` ships ESM and CommonJS, each with matching declarations (`.d.ts` and `.d.cts`). `./generator` is ESM only. |
|
|
49
|
+
| Entry points | `.` (runtime) and `./generator` (generator plugin), compiled JavaScript with declarations in `dist/`. A `react-native` field points at `./dist/index.js`. |
|
|
50
|
+
| Runtime | Any environment with `fetch`, `Request`, and `Response`, or pass your own `fetch`. No TypeScript transpilation of `node_modules` is needed. |
|
|
51
|
+
| TypeScript | Declarations type-check with TypeScript `5.0` and later, using `NodeNext` (CommonJS or ESM) or `bundler` module resolution. |
|
|
52
|
+
| CLI runtime | The `openapi` binary from `@shipworthy/openapi-cli` runs on **Node.js** `>=22.19.0` or **Bun** (`bunx --bun @shipworthy/openapi-cli`). |
|
|
53
|
+
| OpenAPI versions | 3.0.x and 3.1.x. 3.0 documents are upgraded to 3.1 internally. Swagger 2.x is rejected. |
|
|
55
54
|
|
|
56
55
|
The runtime entry point declares no Node.js `engines` range. The CLI runtime requirement applies to code generation.
|
|
57
56
|
|
|
58
57
|
`@shipworthy/openapi-cli` loads the generator with
|
|
59
58
|
`import("@shipworthy/openapi-tanstack-query/generator")`. It loads
|
|
60
|
-
`@shipworthy/openapi-typescript` for `types.ts`. Both packages, plus
|
|
61
|
-
|
|
59
|
+
`@shipworthy/openapi-typescript` for `types.ts`. Both packages, plus
|
|
60
|
+
`@shipworthy/openapi-generator`, must be resolvable from the directory where
|
|
62
61
|
you run the CLI.
|
|
63
62
|
|
|
64
63
|
## Quick start
|
|
@@ -542,23 +541,23 @@ Generated files use extensionless `./types` imports and expect TypeScript `modul
|
|
|
542
541
|
|
|
543
542
|
## Troubleshooting
|
|
544
543
|
|
|
545
|
-
| Symptom | Fix
|
|
546
|
-
| -------------------------------------------------------------------- |
|
|
547
|
-
| `<METHOD> <path>: Missing operationId` / `Duplicate operationId: …` | Add unique `operationId`s to the OpenAPI document.
|
|
548
|
-
| `--name must start with a letter …` | Use letters and digits, with single `-` or `_` separators, such as `hotels` or `sdk-core`.
|
|
549
|
-
| `types.ts` was not regenerated after editing generator settings | It is regenerated only when the schema hash or generator version changes. Pass `--force`.
|
|
550
|
-
| CLI cannot load `@shipworthy/openapi-tanstack-query/generator` | Install this package, `@shipworthy/openapi-typescript`, `@shipworthy/openapi-generator
|
|
551
|
-
| `openapi` fails to start on an older Node.js | The CLI needs Node.js `>=22.19.0`. Upgrade Node.js, or run it with `bunx --bun @shipworthy/openapi-cli`.
|
|
552
|
-
| `error instanceof Error` is false in `onError` | This is expected for HTTP errors: the error is the parsed error body. See [errors](#requests-responses-and-errors).
|
|
553
|
-
| Two APIs with the same `--name` overwrite each other's cache entries | Pass a different `prefix` to `create<Prefix>ApiQueryUtils(client, { prefix })`.
|
|
544
|
+
| Symptom | Fix |
|
|
545
|
+
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
546
|
+
| `<METHOD> <path>: Missing operationId` / `Duplicate operationId: …` | Add unique `operationId`s to the OpenAPI document. |
|
|
547
|
+
| `--name must start with a letter …` | Use letters and digits, with single `-` or `_` separators, such as `hotels` or `sdk-core`. |
|
|
548
|
+
| `types.ts` was not regenerated after editing generator settings | It is regenerated only when the schema hash or generator version changes. Pass `--force`. |
|
|
549
|
+
| CLI cannot load `@shipworthy/openapi-tanstack-query/generator` | Install this package, `@shipworthy/openapi-typescript`, and `@shipworthy/openapi-generator` in the project. |
|
|
550
|
+
| `openapi` fails to start on an older Node.js | The CLI needs Node.js `>=22.19.0`. Upgrade Node.js, or run it with `bunx --bun @shipworthy/openapi-cli`. |
|
|
551
|
+
| `error instanceof Error` is false in `onError` | This is expected for HTTP errors: the error is the parsed error body. See [errors](#requests-responses-and-errors). |
|
|
552
|
+
| Two APIs with the same `--name` overwrite each other's cache entries | Pass a different `prefix` to `create<Prefix>ApiQueryUtils(client, { prefix })`. |
|
|
554
553
|
|
|
555
554
|
## Key facts (for AI agents)
|
|
556
555
|
|
|
557
556
|
- **Install:** `@shipworthy/openapi-tanstack-query`, plus peers
|
|
558
557
|
`@tanstack/react-query@^5.59.0` and `react@^18 || ^19`. The runtime entry
|
|
559
558
|
ships ESM and CommonJS with `.d.ts`/`.d.cts` declarations for TypeScript 5.0+.
|
|
560
|
-
For `./generator`, also install the optional peers
|
|
561
|
-
`@shipworthy/openapi-generator
|
|
559
|
+
For `./generator`, also install the optional peers
|
|
560
|
+
`@shipworthy/openapi-generator` and `@shipworthy/openapi-transformer`.
|
|
562
561
|
- **Generate:** run
|
|
563
562
|
`openapi generate tanstack-query <spec> -o <dir> --name <name>` from
|
|
564
563
|
`@shipworthy/openapi-cli` (`bunx --bun @shipworthy/openapi-cli`). The output is
|
package/package.json
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@shipworthy/openapi-tanstack-query",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.2",
|
|
4
4
|
"files": [
|
|
5
5
|
"dist"
|
|
6
6
|
],
|
|
7
7
|
"dependencies": {
|
|
8
|
-
"@shipworthy/openapi-fetch": "0.0.
|
|
8
|
+
"@shipworthy/openapi-fetch": "0.0.2",
|
|
9
|
+
"effect": "^4.0.0"
|
|
9
10
|
},
|
|
10
11
|
"peerDependencies": {
|
|
11
|
-
"@shipworthy/openapi-generator": "0.0.
|
|
12
|
-
"@shipworthy/openapi-transformer": "0.0.
|
|
12
|
+
"@shipworthy/openapi-generator": "0.0.2",
|
|
13
|
+
"@shipworthy/openapi-transformer": "0.0.2",
|
|
13
14
|
"@tanstack/react-query": "^5.59.0",
|
|
14
|
-
"effect": "^4.0.0",
|
|
15
15
|
"react": "^18.0.0 || ^19.0.0"
|
|
16
16
|
},
|
|
17
17
|
"license": "MIT",
|
|
@@ -44,12 +44,11 @@
|
|
|
44
44
|
"test": "vitest run"
|
|
45
45
|
},
|
|
46
46
|
"devDependencies": {
|
|
47
|
-
"@shipworthy/openapi-generator": "0.0.
|
|
48
|
-
"@shipworthy/openapi-transformer": "0.0.
|
|
47
|
+
"@shipworthy/openapi-generator": "0.0.2",
|
|
48
|
+
"@shipworthy/openapi-transformer": "0.0.2",
|
|
49
49
|
"@shipworthy/typescript-config": "0.0.1",
|
|
50
50
|
"@tanstack/react-query": "^5.104.1",
|
|
51
51
|
"@types/node": "^24.10.3",
|
|
52
|
-
"effect": "^4.0.0",
|
|
53
52
|
"react": "^19.0.0",
|
|
54
53
|
"tsdown": "0.23.0",
|
|
55
54
|
"typescript": "^7.0.2",
|
|
@@ -61,9 +60,6 @@
|
|
|
61
60
|
},
|
|
62
61
|
"@shipworthy/openapi-transformer": {
|
|
63
62
|
"optional": true
|
|
64
|
-
},
|
|
65
|
-
"effect": {
|
|
66
|
-
"optional": true
|
|
67
63
|
}
|
|
68
64
|
},
|
|
69
65
|
"main": "./dist/index.cjs",
|