@shipworthy/openapi-tanstack-query 0.0.1 → 1.0.0

package/README.md

@@ -4,8 +4,8 @@ Typed [TanStack Query](https://tanstack.com/query) options, keys, and mutations
 for every operation in an OpenAPI 3.x document. Use it in a React (or React
 Native) app that already uses `@tanstack/react-query`. The package is a thin
 adapter over [`@shipworthy/openapi-fetch`](../openapi-fetch). Types come from
-`@shipworthy/openapi-typescript`. Code generation only writes a small `client.ts`
-that maps each `operationId` to `[METHOD, path]`. You then pass the returned
+`@shipworthy/openapi-typescript`. Code generation writes a `client.ts` with
+operation routes and, when requested, schema-based field mappings. You then pass the returned
 options to TanStack's own hooks (`useQuery`, `useMutation`, `useInfiniteQuery`,
 `useSuspenseQuery`, `queryClient.fetchQuery`, and so on). The package has no
 hooks or React provider of its own.
@@ -31,34 +31,33 @@ hooks or React provider of its own.
 bun add @shipworthy/openapi-tanstack-query @tanstack/react-query react
 ```
 
-Add the code generators as dev dependencies. `effect`,
-`@shipworthy/openapi-generator`, and `@shipworthy/openapi-transformer` are
-optional peer dependencies that only the `./generator` entry point needs. The
-CLI installs the last two. The TypeScript generator bundles TypeScript 7's AST
-modules, so your project can keep its own TypeScript version:
+Add the code generators as dev dependencies. `@shipworthy/openapi-typescript` supplies
+the schema-based case mapping used by `./generator` and generates `types.ts`.
+The TypeScript generator bundles TypeScript 7's AST modules, so your
+project can keep its own TypeScript version:
 
 ```sh
-bun add -d @shipworthy/openapi-cli @shipworthy/openapi-typescript effect@^4
+bun add -d @shipworthy/openapi-cli @shipworthy/openapi-typescript
 ```
 
-| Requirement          | Value                                                                                                                                                          |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Peer dependencies    | `@tanstack/react-query` `^5.59.0`, `react` `^18.0.0 \|\| ^19.0.0`                                                                                              |
-| Optional peers       | `effect` `^4.0.0`, `@shipworthy/openapi-generator`, and `@shipworthy/openapi-transformer`, needed only for `./generator` (the CLI and programmatic generation) |
-| Runtime dependencies | `@shipworthy/openapi-fetch` (installed automatically)                                                                                                          |
-| Module format        | `.` ships ESM and CommonJS, each with matching declarations (`.d.ts` and `.d.cts`). `./generator` is ESM only.                                                 |
-| Entry points         | `.` (runtime) and `./generator` (generator plugin), compiled JavaScript with declarations in `dist/`. A `react-native` field points at `./dist/index.js`.      |
-| Runtime              | Any environment with `fetch`, `Request`, and `Response`, or pass your own `fetch`. No TypeScript transpilation of `node_modules` is needed.                    |
-| TypeScript           | Declarations type-check with TypeScript `5.0` and later, using `NodeNext` (CommonJS or ESM) or `bundler` module resolution.                                    |
-| CLI runtime          | The `openapi` binary from `@shipworthy/openapi-cli` runs on **Node.js** `>=22.19.0` or **Bun** (`bunx --bun @shipworthy/openapi-cli`).                         |
-| OpenAPI versions     | 3.0.x and 3.1.x. 3.0 documents are upgraded to 3.1 internally. Swagger 2.x is rejected.                                                                        |
+| Requirement          | Value                                                                                                                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Peer dependencies    | `@tanstack/react-query` `^5.59.0`, `react` `^18.0.0 \|\| ^19.0.0`                                                                                                             |
+| Optional peers       | `@shipworthy/openapi-typescript`, `@shipworthy/openapi-generator`, and `@shipworthy/openapi-transformer`, needed only for `./generator` (the CLI and programmatic generation) |
+| Runtime dependencies | `@shipworthy/openapi-fetch` and `effect` (installed automatically; only `./generator` imports `effect`)                                                                       |
+| Module format        | `.` ships ESM and CommonJS, each with matching declarations (`.d.ts` and `.d.cts`). `./generator` is ESM only.                                                                |
+| Entry points         | `.` (runtime) and `./generator` (generator plugin), compiled JavaScript with declarations in `dist/`. A `react-native` field points at `./dist/index.js`.                     |
+| Runtime              | Any environment with `fetch`, `Request`, and `Response`, or pass your own `fetch`. No TypeScript transpilation of `node_modules` is needed.                                   |
+| TypeScript           | Declarations type-check with TypeScript `5.0` and later, using `NodeNext` (CommonJS or ESM) or `bundler` module resolution.                                                   |
+| CLI runtime          | The `openapi` binary from `@shipworthy/openapi-cli` runs on **Node.js** `>=22.19.0` or **Bun** (`bunx --bun @shipworthy/openapi-cli`).                                        |
+| OpenAPI versions     | 3.0.x and 3.1.x. 3.0 documents are upgraded to 3.1 internally. Swagger 2.x is rejected.                                                                                       |
 
 The runtime entry point declares no Node.js `engines` range. The CLI runtime requirement applies to code generation.
 
 `@shipworthy/openapi-cli` loads the generator with
 `import("@shipworthy/openapi-tanstack-query/generator")`. It loads
-`@shipworthy/openapi-typescript` for `types.ts`. Both packages, plus `effect`
-and `@shipworthy/openapi-generator`, must be resolvable from the directory where
+`@shipworthy/openapi-typescript` for `types.ts`. Both packages, plus
+`@shipworthy/openapi-generator`, must be resolvable from the directory where
 you run the CLI.
 
 ## Quick start
@@ -67,13 +66,14 @@ you run the CLI.
 and the CLI resolves `$ref`s:
 
 ```sh
-bunx --bun @shipworthy/openapi-cli generate tanstack-query ./openapi.json -o src/generated --name hotels
+bunx --bun @shipworthy/openapi-cli generate tanstack-query -i ./openapi.json -o src/generated/hotels
 # Or generate from a URL:
-bunx --bun @shipworthy/openapi-cli generate tanstack-query https://api.example.com/openapi.json -o src/generated --name hotels
+bunx --bun @shipworthy/openapi-cli generate tanstack-query -i https://api.example.com/openapi.json -o src/generated/hotels
 ```
 
 This writes `src/generated/hotels/types.ts` (via `@shipworthy/openapi-typescript`)
-and `src/generated/hotels/client.ts`.
+and `src/generated/hotels/client.ts`. The client name `hotels` comes from the
+output directory's name; pass `--name` to choose another.
 
 **2. Create the client and query utils once**:
 
@@ -111,15 +111,49 @@ function Hotels() {
 Inputs, response data, and error types are all inferred from the OpenAPI
 document. You do not write type arguments.
 
+### camelCase app fields
+
+Add `--camel-case` when the API uses snake_case fields and the app should use camelCase:
+
+```sh
+openapi generate tanstack-query -i ./openapi.json -o src/generated/hotels --camel-case
+```
+
+With this flag, `types.ts` uses names such as `minStars` and `hotelId`. The generated
+`createHotelsApiClient` converts typed path, query, header, and cookie parameters and JSON
+request bodies to the names declared in OpenAPI. It converts JSON success and error bodies
+back to camelCase before returning data or placing it in the TanStack Query cache:
+
+```ts
+const hotels = useQuery(hotelsApi.getHotels.queryOptions({ input: { query: { minStars: 5 } } }));
+// The request sends ?min_stars=5. A response field hotel_id is exposed as hotelId.
+```
+
+Direct calls through the generated client use the same conversion. Dictionary keys declared by
+`additionalProperties` or `patternProperties` keep their spelling, while declared fields inside
+their values are converted. Operation IDs, URLs, enum values, and the raw `Response` retain their
+API spelling. Generation fails when distinct wire fields would share a camelCase name within
+an object, including nested fields combined by `allOf`, `anyOf`, or `oneOf`. Conversion applies
+to `application/json` and `+json` bodies.
+
+Use `--wire-types` with `--camel-case` to write `wire-types.ts` alongside `types.ts`. The wire file
+has the API's field names and the same other TypeScript generation settings. For example, import
+`components` from `./generated/hotels/wire-types` to type a raw `Response` fixture or a custom `fetch`
+wrapper. `types.ts` remains the app-facing camelCase contract.
+
+JSON Pointer strings such as `errors[].pointer: "/slot_id"` keep their API spelling. Undeclared
+fields also keep their API spelling. When a response status has no matching schema and no
+`default` response in the OpenAPI document, its error body is returned without conversion.
+
 ## Generated output
 
-`openapi generate tanstack-query <input> -o <dir> --name <name>` writes the
-following into `<dir>/<name>/`:
+`openapi generate tanstack-query -i <input> -o <dir>` writes the following
+into `<dir>/`. Every file is regenerated on every successful run:
 
 - `types.ts`: `paths`, `components`, `operations`, and `webhooks` types from
-  `@shipworthy/openapi-typescript`. This file is regenerated only when it is
-  missing or stale (see [`--force`](#cli-openapi-generate-tanstack-query)).
-- `client.ts`: overwritten on every successful run. For `--name my-pets`
+  `@shipworthy/openapi-typescript`.
+- `wire-types.ts`: optional API-facing types when both `--camel-case` and `--wire-types` are set.
+- `client.ts`: for `-o src/generated/my-pets` or `--name my-pets`
   (prefix `MyPets`), it contains:
 
 ```ts
@@ -163,47 +197,56 @@ export function createMyPetsApiQueryUtils(
 
 Naming rules:
 
-- `<Prefix>` is the PascalCase form of `--name`. `-` and `_` separators are
+- The client name is `--name`, or the basename of the output directory when
+  `--name` is omitted.
+- `<Prefix>` is the PascalCase form of the client name. `-` and `_` separators are
   removed and the next character is uppercased: `hotels` becomes `Hotels`, and
   `my-pets` becomes `MyPets`.
 - The generated exports are `create<Prefix>ApiClient`, `<Prefix>ApiClient`
   (type), `create<Prefix>ApiQueryUtils`, `<Prefix>ApiPaths`,
   `<Prefix>ApiComponents`, and `<Prefix>ApiOperations`.
-- The default cache-key prefix is the raw `--name` value, such as `"my-pets"`.
+- The default cache-key prefix is the raw client name, such as `"my-pets"`.
 - Each operation is available on the query utils object by its `operationId`,
   for example `hotelsApi.getHotel`.
 
 ## CLI: `openapi generate tanstack-query`
 
-The command is provided by `@shipworthy/openapi-cli`.
+The command is provided by `@shipworthy/openapi-cli`. The `tanstack-query` plugin writes
+`client.ts` and the `types.ts` it imports into the output directory:
 
 ```
-openapi generate tanstack-query [flags] <input>
+openapi generate tanstack-query [-i <input>] -o <dir> [--name <name>] [--camel-case] [--wire-types] [--check] [TypeScript flags]
 ```
 
-| Argument / flag  | Type    | Default | Description                                                                                                                                                                |
-| ---------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `<input>`        | string  | none    | OpenAPI file path, or an `http:`, `https:`, or `file:` URL. Glob patterns (`*`) are rejected.                                                                              |
-| `--output`, `-o` | string  | none    | Directory that will contain `<name>/client.ts`.                                                                                                                            |
-| `--name`         | string  | none    | Client name. It sets the output subdirectory, the PascalCase export prefix, and the default cache-key prefix. It must match `^[a-zA-Z][a-zA-Z0-9]*(?:[-_][a-zA-Z0-9]+)*$`. |
-| `--force`        | boolean | `false` | Regenerate `types.ts` even when its stamp matches.                                                                                                                         |
+| Flag             | Type    | Default                     | Description                                                                                                                                      |
+| ---------------- | ------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--input`, `-i`  | string  | stdin                       | OpenAPI file path, or an `http:`, `https:`, or `file:` URL. Glob patterns (`*`) are rejected.                                                    |
+| `--output`, `-o` | string  | required                    | Directory that receives `client.ts` and `types.ts`.                                                                                              |
+| `--name`         | string  | output directory's basename | Client name. It sets the PascalCase export prefix and the default cache-key prefix. It must match `^[a-zA-Z][a-zA-Z0-9]*(?:[-_][a-zA-Z0-9]+)*$`. |
+| `--camel-case`   | boolean | `false`                     | Use camelCase in `types.ts` and convert declared parameter and JSON body fields in the generated client.                                         |
+| `--wire-types`   | boolean | `false`                     | Also write `wire-types.ts` with API field names. Requires `--camel-case`.                                                                        |
+| `--check`        | boolean | `false`                     | Write nothing; exit 1 when a generated file differs from the file in the output directory or is missing.                                         |
+
+When `--name` is omitted and the output directory's basename is not a valid name,
+the command fails with `Cannot derive a client name from the output directory "<basename>". Pass --name.`
 
-`types.ts` is regenerated when it is missing, or when the
-`@shipworthy/openapi-typescript@<version>:<sha256>` stamp in its header no
-longer matches. The hash covers the schema contents, not the schema's location,
-so moving the file does not trigger a rebuild.
+The `tanstack-query` plugin can be combined with other plugins in one run, for example
+`openapi generate tanstack-query zod -i openapi.json -o src/generated/hotels`, which also
+writes `zod-schema.ts` against the same `types.ts`. See the
+[CLI reference](../openapi-cli/README.md#openapi-generate-plugins) for every flag, including
+the TypeScript generation flags.
 
 Example `package.json` script:
 
 ```json
 {
   "scripts": {
-    "generate": "openapi generate tanstack-query openapi.json -o src/generated --name hotels"
+    "generate": "openapi generate tanstack-query -i openapi.json -o src/generated/hotels"
   }
 }
 ```
 
-Generation fails with exit code 1, and `client.ts` is left untouched, when:
+Generation fails with exit code 1, and no file is written, when:
 
 | Error message                          | Cause                                                    |
 | -------------------------------------- | -------------------------------------------------------- |
@@ -211,7 +254,7 @@ Generation fails with exit code 1, and `client.ts` is left untouched, when:
 | `Duplicate operationId: <id>`          | Two operations share an `operationId`.                   |
 | `Unsupported operationId: <id>`        | The id is `__proto__`, `constructor`, or `prototype`.    |
 | `Unsupported Swagger version: 2.x. …`  | The input is Swagger 2.x. Only OpenAPI 3.x is supported. |
-| `Globbing is unsupported.`             | `<input>` contains `*`.                                  |
+| `Globbing is unsupported.`             | The input contains `*`.                                  |
 
 ## Runtime API (`@shipworthy/openapi-tanstack-query`)
 
@@ -234,6 +277,11 @@ type ApiClient<Paths extends {} = {}> = Client<Paths>; // @shipworthy/openapi-fe
 
 This function creates an `@shipworthy/openapi-fetch` client.
 
+With `--camel-case`, the generated factory passes `caseMapping` to
+`createApiClient<Paths>(options)`. The underlying fetch client installs the casing middleware.
+`@shipworthy/openapi-typescript` builds the mapping from the OpenAPI schema. Use the generated
+factory so runtime values match `types.ts`.
+
 - **`baseUrl`** (required): the root URL for all requests. A trailing slash is
   removed.
 - **`authToken`** (optional): a token string, or a sync or async getter.
@@ -248,6 +296,8 @@ This function creates an `@shipworthy/openapi-fetch` client.
   through, including `fetch`, `Request`, `headers`, `querySerializer`,
   `bodySerializer`, `pathSerializer`, `requestInitExt`, and standard
   `RequestInit` fields such as `credentials`.
+- **`caseMapping`** (optional): a generated `CaseMapping`. When provided,
+  the underlying fetch client installs the casing middleware.
 
 The returned client is a full `openapi-fetch` client. You can call it directly
 (`client.GET("/hotels", { params: { query } })`) or add middleware with
@@ -486,17 +536,17 @@ import {
 } from "@shipworthy/openapi-tanstack-query/generator";
 ```
 
-| Export                               | Signature / description                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tanstackQuery`                      | `Generator<string, TanstackGenerationError>` (from `@shipworthy/openapi-generator`) with `id: "tanstack-query"`. `generate(model, options)` returns `Effect<string, TanstackGenerationError>`, which is the `client.ts` source with no header comment. Options: `prefix?: string` (export prefix, default `""`) and `name?: string` (cache-key prefix, default `prefix`). Other option shapes fail with `TanstackGenerationError`. |
-| `operationRoutes(model)`             | `Effect<Record<string, OperationRoute>, TanstackGenerationError>`. Maps each `operationId` to `[METHOD, path]`. Fails on a missing, duplicate, or reserved (`__proto__`, `constructor`, `prototype`) `operationId`.                                                                                                                                                                                                                |
-| `clientSource(prefix, name, routes)` | `string`. Prints `client.ts` source for the given export prefix, cache-key prefix, and routes.                                                                                                                                                                                                                                                                                                                                     |
-| `TanstackGenerationError`            | Effect `Schema.TaggedError` with `_tag: "TanstackGenerationError"` and `message: string`.                                                                                                                                                                                                                                                                                                                                          |
+| Export                               | Signature / description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tanstackQuery`                      | `Generator<string, TanstackGenerationError>` (from `@shipworthy/openapi-generator`) with `id: "tanstack-query"`. `generate(model, options)` returns `Effect<string, TanstackGenerationError>`, which is the `client.ts` source with no header comment. Options: `prefix?: string` (export prefix, default `""`), `name?: string` (cache-key prefix, default `prefix`), and `camelCase?: boolean` (default `false`). Other option shapes fail with `TanstackGenerationError`. |
+| `operationRoutes(model)`             | `Effect<Record<string, OperationRoute>, TanstackGenerationError>`. Maps each `operationId` to `[METHOD, path]`. Fails on a missing, duplicate, or reserved (`__proto__`, `constructor`, `prototype`) `operationId`.                                                                                                                                                                                                                                                          |
+| `clientSource(prefix, name, routes)` | `string`. Prints `client.ts` source for the given export prefix, cache-key prefix, and routes.                                                                                                                                                                                                                                                                                                                                                                               |
+| `TanstackGenerationError`            | Effect `Schema.TaggedError` with `_tag: "TanstackGenerationError"` and `message: string`.                                                                                                                                                                                                                                                                                                                                                                                    |
 
 Programmatic generation with `@shipworthy/openapi-generator`, which is what
 the CLI does:
 
-Install `@effect/platform-node@^4` as a dev dependency for the Node.js platform layer used in this example:
+Install `@effect/platform-node@4.1.4` as a dev dependency for the Node.js platform layer used in this example:
 
 ```ts
 import { NodeServices } from "@effect/platform-node";
@@ -542,29 +592,31 @@ Generated files use extensionless `./types` imports and expect TypeScript `modul
 
 ## Troubleshooting
 
-| Symptom                                                              | Fix                                                                                                                   |
-| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `<METHOD> <path>: Missing operationId` / `Duplicate operationId: …`  | Add unique `operationId`s to the OpenAPI document.                                                                    |
-| `--name must start with a letter …`                                  | Use letters and digits, with single `-` or `_` separators, such as `hotels` or `sdk-core`.                            |
-| `types.ts` was not regenerated after editing generator settings      | It is regenerated only when the schema hash or generator version changes. Pass `--force`.                             |
-| CLI cannot load `@shipworthy/openapi-tanstack-query/generator`       | Install this package, `@shipworthy/openapi-typescript`, `@shipworthy/openapi-generator`, and `effect` in the project. |
-| `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`.              |
-| `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).   |
-| Two APIs with the same `--name` overwrite each other's cache entries | Pass a different `prefix` to `create<Prefix>ApiQueryUtils(client, { prefix })`.                                       |
+| Symptom                                                                                                     | Fix                                                                                                                 |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `<METHOD> <path>: Missing operationId` / `Duplicate operationId: …`                                         | Add unique `operationId`s to the OpenAPI document.                                                                  |
+| `Invalid value for flag --name: "…". Expected: Schema validation failed: --name must start with a letter …` | Use letters and digits, with single `-` or `_` separators, such as `hotels` or `sdk-core`.                          |
+| `Cannot derive a client name from the output directory "…". Pass --name.`                                   | Rename the output directory to a valid name, or pass `--name`.                                                      |
+| CLI cannot load `@shipworthy/openapi-tanstack-query/generator`                                              | Install this package, `@shipworthy/openapi-typescript`, and `@shipworthy/openapi-generator` in the project.         |
+| `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`.            |
+| `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). |
+| Two APIs with the same client name overwrite each other's cache entries                                     | Pass a different `prefix` to `create<Prefix>ApiQueryUtils(client, { prefix })`.                                     |
 
 ## Key facts (for AI agents)
 
 - **Install:** `@shipworthy/openapi-tanstack-query`, plus peers
   `@tanstack/react-query@^5.59.0` and `react@^18 || ^19`. The runtime entry
   ships ESM and CommonJS with `.d.ts`/`.d.cts` declarations for TypeScript 5.0+.
-  For `./generator`, also install the optional peers `effect@^4`,
-  `@shipworthy/openapi-generator`, and `@shipworthy/openapi-transformer`.
+  For `./generator`, also install the optional peers
+  `@shipworthy/openapi-generator` and `@shipworthy/openapi-transformer`.
 - **Generate:** run
-  `openapi generate tanstack-query <spec> -o <dir> --name <name>` from
+  `openapi generate tanstack-query -i <spec> -o <dir> [--name <name>]` from
   `@shipworthy/openapi-cli` (`bunx --bun @shipworthy/openapi-cli`). The output is
-  `<dir>/<name>/types.ts` and `<dir>/<name>/client.ts`. Do not edit generated
+  `<dir>/types.ts` and `<dir>/client.ts`, regenerated on every run. `name`
+  defaults to the basename of `<dir>`. Add other plugins to the same run, e.g.
+  `openapi generate tanstack-query zod -i <spec> -o <dir>`. Do not edit generated
   files.
-- **Generated exports** (Prefix is the PascalCase of `name`):
+- **Generated exports** (Prefix is the PascalCase of the client name):
   `create<Prefix>ApiClient`, `create<Prefix>ApiQueryUtils`,
   `<Prefix>ApiClient`, `<Prefix>ApiPaths`, `<Prefix>ApiComponents`, and
   `<Prefix>ApiOperations`.

package/dist/generator.d.ts

@@ -3,17 +3,14 @@ import { Generator } from "@shipworthy/openapi-generator";
 import { ParsedService } from "@shipworthy/openapi-transformer";
 import { HttpMethod } from "@shipworthy/openapi-fetch";
 import "@tanstack/react-query";
-//#region src/errors.d.ts
 declare const TanstackGenerationError_base: Schema.Class<TanstackGenerationError, Schema.TaggedStruct<"TanstackGenerationError", {
   readonly message: Schema.String;
-}>, import("effect/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
 export declare class TanstackGenerationError extends TanstackGenerationError_base {}
-//#endregion
-//#region src/query-utils.d.ts
 type OperationRoute = readonly [Uppercase<HttpMethod>, string];
-//#endregion
-//#region src/generator.d.ts
 /** operationId → [METHOD, path]. Every operation needs an id. */
 export declare const operationRoutes: (model: ParsedService) => Effect.Effect<Record<string, OperationRoute>, TanstackGenerationError, never>;
 export declare const tanstackQuery: Generator<string, TanstackGenerationError>;
-//#endregion
+export {};

package/dist/generator.js

@@ -1,8 +1,8 @@
-import { Effect, Schema } from "effect";
-//#region src/errors.ts
+import { buildCaseMapping } from "@shipworthy/openapi-typescript/case-mapping";
+import { Array, Effect, Formatter, Record, Schema, pipe } from "effect";
+// src/errors.ts
 var TanstackGenerationError = class extends Schema.TaggedError()("TanstackGenerationError", { message: Schema.String }) {};
-//#endregion
-//#region src/generator.ts
+// src/generator.ts
 const blockedOperationIds = /* @__PURE__ */ new Set([
 	"__proto__",
 	"constructor",
@@ -10,7 +10,8 @@ const blockedOperationIds = /* @__PURE__ */ new Set([
 ]);
 const PluginOptions = Schema.Struct({
 	prefix: Schema.optionalKey(Schema.String),
-	name: Schema.optionalKey(Schema.String)
+	name: Schema.optionalKey(Schema.String),
+	camelCase: Schema.optionalKey(Schema.Boolean)
 });
 function reject(message) {
 	return new TanstackGenerationError({ message });
@@ -23,7 +24,7 @@ const operationRoutes = Effect.fnUntraced(function* (model) {
 		const id = operation.operationId;
 		if (!id) return yield* reject(`${label}: Missing operationId`);
 		if (blockedOperationIds.has(id)) return yield* reject(`Unsupported operationId: ${id}`);
-		if (Object.hasOwn(routes, id)) return yield* reject(`Duplicate operationId: ${id}`);
+		if (Record.has(routes, id)) return yield* reject(`Duplicate operationId: ${id}`);
 		routes[id] = [operation.method, operation.path];
 		return routes;
 	}));
@@ -33,25 +34,28 @@ const tanstackQuery = {
 	generate: Effect.fnUntraced(function* (model, options) {
 		const decoded = yield* Effect.mapError(Schema.decodeEffect(PluginOptions)(options), (cause) => reject(cause.message));
 		const prefix = decoded.prefix ?? "";
-		return clientSource(prefix, decoded.name ?? prefix, yield* operationRoutes(model));
+		return clientSource(prefix, decoded.name ?? prefix, yield* operationRoutes(model), decoded.camelCase ? yield* buildCaseMapping(model).pipe(Effect.mapError((error) => new TanstackGenerationError({ message: error.message }))) : void 0);
 	})
 };
-function clientSource(prefix, name, routes) {
-	return `import { createApiClient, createTanstackQueryUtils, type TanstackQueryUtilsOptions } from "@shipworthy/openapi-tanstack-query";
+function clientSource(prefix, name, routes, mapping) {
+	const entries = pipe(Record.collect(routes, (id, route) => `  ${Formatter.formatJson(id)}: ${Formatter.formatJson(route)},`), Array.join("\n"));
+	return `import { ${mapping ? "createApiClient, createTanstackQueryUtils, type ApiClientOptions, type TanstackQueryUtilsOptions" : "createApiClient, createTanstackQueryUtils, type TanstackQueryUtilsOptions"} } from "@shipworthy/openapi-tanstack-query";
 import type { operations, paths } from "./types";
 
 export type { paths as ${prefix}ApiPaths, components as ${prefix}ApiComponents, operations as ${prefix}ApiOperations } from "./types";
-export const create${prefix}ApiClient: typeof createApiClient<paths> = createApiClient<paths>;
+${mapping ? `const caseMapping = ${Formatter.formatJson(mapping, { space: 2 })} as const;
+
+export const create${prefix}ApiClient = (options: ApiClientOptions) =>
+  createApiClient<paths>({ ...options, caseMapping });` : `export const create${prefix}ApiClient: typeof createApiClient<paths> = createApiClient<paths>;`}
 export type ${prefix}ApiClient = ReturnType<typeof create${prefix}ApiClient>;
 
 const routes = {
-${Object.entries(routes).map(([id, route]) => `  ${JSON.stringify(id)}: ${JSON.stringify(route)},`).join("\n")}
+${entries}
 } as const;
 
 export function create${prefix}ApiQueryUtils(client: ${prefix}ApiClient, options?: Partial<TanstackQueryUtilsOptions>) {
-  return createTanstackQueryUtils<Pick<operations, keyof typeof routes>>(client, routes, { prefix: ${JSON.stringify(name)}, ...options });
+  return createTanstackQueryUtils<Pick<operations, keyof typeof routes>>(client, routes, { prefix: ${Formatter.formatJson(name)}, ...options });
 }
 `;
 }
-//#endregion
 export { TanstackGenerationError, operationRoutes, tanstackQuery };

package/dist/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _shipworthy_openapi_fetch = require("@shipworthy/openapi-fetch");
 let _tanstack_react_query = require("@tanstack/react-query");
-//#region src/client.ts
+// src/client.ts
 function createApiClient({ authToken, ...options }) {
 	const client = (0, _shipworthy_openapi_fetch.createClient)(options);
 	if (authToken !== void 0) client.use({ async onRequest({ request }) {
@@ -17,8 +17,7 @@ function createApiClient({ authToken, ...options }) {
 	} });
 	return client;
 }
-//#endregion
-//#region src/query-utils.ts
+// src/query-utils.ts
 function cacheInput(input = {}) {
 	const { header, ...rest } = input;
 	if (!header) return rest;
@@ -102,6 +101,5 @@ function createTanstackQueryUtils(client, routes, { prefix }) {
 		}];
 	}));
 }
-//#endregion
 exports.createApiClient = createApiClient;
 exports.createTanstackQueryUtils = createTanstackQueryUtils;

package/dist/index.d.cts

@@ -1,6 +1,5 @@
 import { Client, ClientOptions, ErrorResponse, HttpMethod, MediaType, RequestBodyOption, RequiredKeysOf, ResponseObjectMap, SuccessResponse } from "@shipworthy/openapi-fetch";
 import { DataTag, InfiniteData, InfiniteQueryPageParamsOptions, QueryFunction, QueryKey, QueryObserverOptions, SkipToken, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
-//#region src/client.d.ts
 type AuthToken = string | undefined | null;
 type AuthTokenProvider = () => AuthToken | Promise<AuthToken>;
 interface ApiClientOptions extends Omit<ClientOptions, "baseUrl"> {
@@ -9,8 +8,6 @@ interface ApiClientOptions extends Omit<ClientOptions, "baseUrl"> {
 }
 export declare function createApiClient<Paths extends {}>({ authToken, ...options }: ApiClientOptions): Client<Paths>;
 type ApiClient<Paths extends {} = {}> = Client<Paths>;
-//#endregion
-//#region src/operation.d.ts
 /** Preserve OpenAPI's parameter groups and add its typed request body. */
 type OperationInput<Op> = (Op extends {
   parameters: infer Parameters;
@@ -28,8 +25,6 @@ type JsonResponses<Op> = { [Status in keyof Responses<Op>]: Responses<Op>[Status
 } : Responses<Op>[Status]; };
 type OperationData<Op> = NormalizeData<SuccessResponse<JsonResponses<Op>, MediaType>>;
 type OperationError<Op> = ErrorResponse<Responses<Op>, MediaType> | Error;
-//#endregion
-//#region src/query-utils.d.ts
 type InputOf<O> = OperationInput<O>;
 type DataOf<O> = OperationData<O>;
 type ErrorOf<O> = OperationError<O>;
@@ -79,5 +74,4 @@ interface TanstackQueryUtilsOptions {
 }
 type OperationRoute = readonly [Uppercase<HttpMethod>, string];
 export declare function createTanstackQueryUtils<Operations extends Record<string, any>>(client: Client<any>, routes: { [Name in keyof Operations]: OperationRoute; }, { prefix }: TanstackQueryUtilsOptions): { [Name in keyof Operations]: OperationQueryUtils<Operations[Name]>; };
-//#endregion
 export type { ApiClient, ApiClientOptions, AuthToken, AuthTokenProvider, OperationData, OperationError, OperationInput, OperationQueryUtils, OperationRoute, TanstackQueryUtilsOptions };

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { Client, ClientOptions, ErrorResponse, HttpMethod, MediaType, RequestBodyOption, RequiredKeysOf, ResponseObjectMap, SuccessResponse } from "@shipworthy/openapi-fetch";
 import { DataTag, InfiniteData, InfiniteQueryPageParamsOptions, QueryFunction, QueryKey, QueryObserverOptions, SkipToken, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
-//#region src/client.d.ts
 type AuthToken = string | undefined | null;
 type AuthTokenProvider = () => AuthToken | Promise<AuthToken>;
 interface ApiClientOptions extends Omit<ClientOptions, "baseUrl"> {
@@ -9,8 +8,6 @@ interface ApiClientOptions extends Omit<ClientOptions, "baseUrl"> {
 }
 export declare function createApiClient<Paths extends {}>({ authToken, ...options }: ApiClientOptions): Client<Paths>;
 type ApiClient<Paths extends {} = {}> = Client<Paths>;
-//#endregion
-//#region src/operation.d.ts
 /** Preserve OpenAPI's parameter groups and add its typed request body. */
 type OperationInput<Op> = (Op extends {
   parameters: infer Parameters;
@@ -28,8 +25,6 @@ type JsonResponses<Op> = { [Status in keyof Responses<Op>]: Responses<Op>[Status
 } : Responses<Op>[Status]; };
 type OperationData<Op> = NormalizeData<SuccessResponse<JsonResponses<Op>, MediaType>>;
 type OperationError<Op> = ErrorResponse<Responses<Op>, MediaType> | Error;
-//#endregion
-//#region src/query-utils.d.ts
 type InputOf<O> = OperationInput<O>;
 type DataOf<O> = OperationData<O>;
 type ErrorOf<O> = OperationError<O>;
@@ -79,5 +74,4 @@ interface TanstackQueryUtilsOptions {
 }
 type OperationRoute = readonly [Uppercase<HttpMethod>, string];
 export declare function createTanstackQueryUtils<Operations extends Record<string, any>>(client: Client<any>, routes: { [Name in keyof Operations]: OperationRoute; }, { prefix }: TanstackQueryUtilsOptions): { [Name in keyof Operations]: OperationQueryUtils<Operations[Name]>; };
-//#endregion
 export type { ApiClient, ApiClientOptions, AuthToken, AuthTokenProvider, OperationData, OperationError, OperationInput, OperationQueryUtils, OperationRoute, TanstackQueryUtilsOptions };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createClient } from "@shipworthy/openapi-fetch";
 import { skipToken } from "@tanstack/react-query";
-//#region src/client.ts
+// src/client.ts
 function createApiClient({ authToken, ...options }) {
 	const client = createClient(options);
 	if (authToken !== void 0) client.use({ async onRequest({ request }) {
@@ -16,8 +16,7 @@ function createApiClient({ authToken, ...options }) {
 	} });
 	return client;
 }
-//#endregion
-//#region src/query-utils.ts
+// src/query-utils.ts
 function cacheInput(input = {}) {
 	const { header, ...rest } = input;
 	if (!header) return rest;
@@ -101,5 +100,4 @@ function createTanstackQueryUtils(client, routes, { prefix }) {
 		}];
 	}));
 }
-//#endregion
 export { createApiClient, createTanstackQueryUtils };

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@shipworthy/openapi-tanstack-query",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@shipworthy/openapi-fetch": "0.0.1"
+    "@shipworthy/openapi-fetch": "1.0.0",
+    "effect": "4.1.4"
   },
   "peerDependencies": {
-    "@shipworthy/openapi-generator": "0.0.1",
-    "@shipworthy/openapi-transformer": "0.0.1",
+    "@shipworthy/openapi-generator": "1.0.0",
+    "@shipworthy/openapi-transformer": "1.0.0",
+    "@shipworthy/openapi-typescript": "1.0.0",
     "@tanstack/react-query": "^5.59.0",
-    "effect": "^4.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "license": "MIT",
@@ -44,16 +45,16 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@shipworthy/openapi-generator": "0.0.1",
-    "@shipworthy/openapi-transformer": "0.0.1",
+    "@shipworthy/openapi-generator": "1.0.0",
+    "@shipworthy/openapi-transformer": "1.0.0",
+    "@shipworthy/openapi-typescript": "1.0.0",
     "@shipworthy/typescript-config": "0.0.1",
     "@tanstack/react-query": "^5.104.1",
-    "@types/node": "^24.10.3",
-    "effect": "^4.0.0",
+    "@types/node": "^26.6.6",
     "react": "^19.0.0",
-    "tsdown": "0.23.0",
+    "tsdown": "0.23.7",
     "typescript": "^7.0.2",
-    "vitest": "5.0.3"
+    "vitest": "5.1.0"
   },
   "peerDependenciesMeta": {
     "@shipworthy/openapi-generator": {
@@ -62,7 +63,7 @@
     "@shipworthy/openapi-transformer": {
       "optional": true
     },
-    "effect": {
+    "@shipworthy/openapi-typescript": {
       "optional": true
     }
   },