@kollors/react-codegen 2.0.0-alpha.4 → 2.0.0-alpha.6

package/README.md

@@ -2,27 +2,29 @@
 
 [Русский](README.ru.md)
 
-Generate one self-contained TypeScript client file from an OpenAPI schema, GraphQL schema and operations, or both.
-
-Requires Node.js 22 or newer and TanStack Query 5 in the consuming application.
+Generate TypeScript types, request functions, and React hooks for TanStack Query from OpenAPI and GraphQL. Each configured schema produces a separate `.ts` file.
 
 ## Install
 
+Requires Node.js 22 or newer. The application using the generated hooks must have TanStack Query 5 installed and a `QueryClientProvider` configured.
+
 ```sh
 npm install -D @kollors/react-codegen@alpha
 ```
 
-## Configuration
+The generated files include the code that sends requests. They use TanStack Query and do not require React Codegen in the application at runtime.
+
+## Configuration and generation
 
 Create `codegen.config.js`:
 
 ```js
 export default {
   auth: {
-    storage: 'localStorage', // 'localStorage' | 'sessionStorage' | 'cookie' | 'none'
+    storage: 'localStorage',
     key: 'accessToken',
-    scheme: 'Bearer', // false sends the token without a scheme
-    credentials: 'same-origin', // 'omit' | 'same-origin' | 'include'
+    scheme: 'Bearer',
+    credentials: 'same-origin',
   },
   openapi: {
     schema: './openapi.yaml',
@@ -38,53 +40,168 @@ export default {
 };
 ```
 
-Run both configured generators with:
+Run:
 
 ```sh
 npx react-codegen codegen.config.js
 ```
 
-Paths are resolved relative to the config file. A configured `openapi` section enables OpenAPI generation; a configured `graphql` section enables GraphQL generation. Omit a section to skip it. At least one section is required. Each section writes one TypeScript file. `documents` is a directory; all `.graphql` files under it, including nested directories, are included. The built-in OpenAPI generator reads and generates in memory, without third-party generators, subprocesses or intermediate files. GraphQL still uses its existing generator and a temporary subdirectory inside the package's `.react-codegen-temp` directory, removed after generation. Each completed output is staged beside its destination and published with an atomic rename.
+This example creates `src/api/openapi.ts` and `src/api/graphql.ts`. Include `openapi`, `graphql`, or both; at least one is required. Output directories are created automatically, and the two outputs must use different filenames.
+
+File paths resolve relative to the config file. The config uses an ES module default export; in a CommonJS project, use `codegen.config.mjs` and pass that filename to the command.
+
+| Setting | Required | Description or default |
+| --- | --- | --- |
+| `openapi.schema` | Yes | OpenAPI 3.0.x or 3.1.x in YAML/JSON: file path or HTTP URL |
+| `openapi.output` | Yes | Path to the generated `.ts` file |
+| `openapi.baseUrl` | No | URL prefix for requests; paths stay relative when omitted |
+| `graphql.schema` | Yes | GraphQL SDL or introspection JSON: file path or HTTP URL |
+| `graphql.documents` | Yes | Directory containing named queries, mutations, and fragments in `.graphql` files; subdirectories are included |
+| `graphql.output` | Yes | Path to the generated `.ts` file |
+| `graphql.endpoint` | No | Request endpoint; defaults to `/api/graphql` |
+| `auth` | No | Shared [authentication settings](#authentication) |
+| `openapi.auth`, `graphql.auth` | No | Replace shared authentication settings for that client |
+
+GraphQL introspection JSON can contain `__schema` or `data.__schema`. A GraphQL HTTP endpoint can also be used as `schema`: the generator requests its schema through introspection.
+
+## Using the generated code
+
+### Queries
+
+For an OpenAPI GET operation with `operationId: getPet`, use the hook inside a component or another hook:
+
+```ts
+import { useGetPet } from './api/openapi';
+
+export function usePetName(id: string) {
+  return useGetPet({ pathParams: { id } }, { select: pet => pet.name });
+}
+```
+
+For a GraphQL query named `MovieDetailsQuery` that selects `movie.title`:
+
+```ts
+import { useMovieDetailsQuery } from './api/graphql';
+
+export function useMovieTitle(id: string) {
+  return useMovieDetailsQuery({ id }, { select: data => data.movie?.title });
+}
+```
+
+Both generators provide the following helpers for queries:
+
+| Purpose | OpenAPI `getPet` | GraphQL `MovieDetailsQuery` |
+| --- | --- | --- |
+| Query hook | `useGetPet` | `useMovieDetailsQuery` |
+| Suspense hook | `useSuspenseGetPet` | `useSuspenseMovieDetailsQuery` |
+| Options for `QueryClient` | `getPetQuery` | `movieDetailsQuery` |
+| Cache key | `getPetQueryKey` | `movieDetailsQueryKey` |
+| Direct request | `fetchGetPet` | `fetchMovieDetailsQuery` |
+
+OpenAPI names come from `operationId`, or from the HTTP method and path when it is absent. GraphQL names come from the operation name. GraphQL also exports the selected result type, variable type, and document string, such as `MovieDetailsQuery`, `MovieDetailsQueryVariables`, and `MovieDetailsQueryDocument`.
+
+### Mutations
+
+OpenAPI methods other than GET and GraphQL mutations generate mutation hooks. For an OpenAPI operation with `operationId: createPet`:
+
+```ts
+import { useCreatePet, type CreatePetRequestBody } from './api/openapi';
+
+export function useSavePet() {
+  const mutation = useCreatePet();
+  return (body: CreatePetRequestBody) => mutation.mutate({ body });
+}
+```
+
+OpenAPI arguments are grouped into `pathParams`, `queryParams`, `headers`, and `body`. GraphQL arguments are the operation's variables. Required arguments follow the schema; GraphQL variables marked `!` are required unless they have a default.
+
+If no arguments are required, hooks and request functions can be called without them. Mutation hooks also allow `mutate()` and `mutateAsync()` in that case.
+
+### Skipping a query
+
+Regular query hooks accept `skipToken`:
+
+```ts
+import { skipToken } from '@tanstack/react-query';
+import { useGetPet } from './api/openapi';
+
+export function useOptionalPet(id?: string) {
+  return useGetPet(id ? { pathParams: { id } } : skipToken);
+}
+```
+
+Suspense hooks do not accept `skipToken`. Their arguments can be omitted when the operation has no required arguments.
+
+### Requests and cache keys
 
-Schema values may be local paths or URLs. `output` directories are created when needed.
+Load data through TanStack Query:
+
+```ts
+import { QueryClient } from '@tanstack/react-query';
+import { getPetQuery } from './api/openapi';
 
-## OpenAPI generator
+const queryClient = new QueryClient();
+const pet = await queryClient.fetchQuery(getPetQuery({ pathParams: { id: '42' } }));
+```
+
+To refresh cached data in the application, use its `QueryClient`:
+
+```ts
+import { useQueryClient } from '@tanstack/react-query';
+import { getPetQueryKey } from './api/openapi';
 
-Only `schema` and `output` are required. One OpenAPI 3.0.x or 3.1.x document in YAML/JSON produces one `.ts` file with types, a fetcher, request functions and TanStack Query 5 hooks. Swagger 2.0 is rejected. The generated client does not import this package. `yaml` only parses input during generation.
+export function useRefreshPet(id: string) {
+  const queryClient = useQueryClient();
+  return () => queryClient.invalidateQueries({ queryKey: getPetQueryKey({ pathParams: { id } }) });
+}
+```
 
-For `operationId: getPet`, the output includes:
+To send a request directly, without TanStack Query:
 
 ```ts
-import { useGetPet, getPetQuery, getPetQueryKey, fetchGetPet } from './api/openapi';
+import { fetchGetPet } from './api/openapi';
 
-const variables = { pathParams: { id: '42' } };
-const query = useGetPet(variables, { select: pet => pet.name });
-await queryClient.fetchQuery(getPetQuery(variables));
-await queryClient.invalidateQueries({ queryKey: getPetQueryKey(variables) });
-await fetchGetPet(variables, abortController.signal);
+const controller = new AbortController();
+const pet = await fetchGetPet({ pathParams: { id: '42' } }, controller.signal);
 ```
 
-GET generates `useX`, `useSuspenseX`, `xQuery`, `xQueryKey` and `fetchX`. Other methods generate `useX` mutations and `fetchX`, e.g. `useCreatePet().mutate({ body: pet })`. Variables group `pathParams`, `queryParams`, `headers` and `body`; required groups follow the schema. Calls with no required variables can omit the argument. Regular queries accept TanStack's `skipToken`; suspense queries require variables. Names use `operationId`, falling back to method and path; collisions report both locations.
+Calling `controller.abort()` cancels the direct request. Query hooks receive TanStack Query's cancellation signal automatically. The GraphQL request functions and helpers work the same way.
+
+Use the generated key helpers for cache operations. Keys include the endpoint or base URL and request arguments; OpenAPI keys also include request headers. Tokens read from storage and browser cookies are excluded, so clear the relevant cache when the signed-in user changes.
+
+## Authentication
 
-Query keys include the configured base URL, HTTP method, path, operation name and variables. The generated `Accept` header and explicit request headers are normalized to their serialized names and values, so equivalent `Headers`, objects and tuple arrays share a cache entry while different header values stay separate. Tokens read from storage and browser cookies are not part of the key; clear the relevant query cache when the signed-in user changes.
+Top-level `auth` applies to both clients. `openapi.auth` or `graphql.auth` replaces the whole shared section for that client.
 
-### Supported features
+Without `auth`, the generated client does not add an `Authorization` header.
 
-- Primitive types, arrays, objects, dictionaries, enums, internal `$ref`, recursive component types, `allOf` intersections, `oneOf`/`anyOf` unions. OpenAPI 3.1 also supports boolean schemas, `const` and type arrays.
-- `required` controls optional properties. `null` is included only when allowed by the schema. No blanket replacement of `null` with `undefined`. `readOnly`/`writeOnly` produce input/output variants when needed.
-- Path/header `simple` parameters; query `form`, flat `deepObject` with `explode: true`, array `spaceDelimited`/`pipeDelimited` with `explode: false`. Operation parameters override path-level parameters.
-- JSON/`+json`, text/XML as strings, binary bodies/responses as `Blob`, multipart and URL-encoded object bodies. Multiple request formats are selected in this order: JSON, `+json`, URL-encoded, multipart, other supported formats alphabetically. Responses use their actual Content-Type; successful response types form a union. `default` is a success fallback only when no explicit 2xx exists. Empty mutation responses return `undefined` with type `void`.
-- Descriptions become comments. Dates remain strings. Numeric bounds, patterns and lengths do not add runtime validation. `oneOf` becomes a TypeScript union without checking exclusivity. `discriminator` does not invent properties or values: describe the discriminator field in the schema.
+| Option | Required | Behavior |
+| --- | --- | --- |
+| `storage` | When `auth` is configured | Where to read the token; see below |
+| `key` | Unless `storage` is `none` | Name of the storage entry or cookie |
+| `scheme` | No | Header prefix; defaults to `Bearer`. Set `false` to send the token unchanged |
+| `credentials` | No | Browser cookie policy; defaults to `same-origin` |
 
-### Current limits
+| `storage` | Token source |
+| --- | --- |
+| `localStorage` | `localStorage.getItem(key)` |
+| `sessionStorage` | `sessionStorage.getItem(key)` |
+| `cookie` | Cookie named `key`, read through `document.cookie` |
+| `none` | No token is read; no authorization header is added |
 
-Generation fails with a schema location before replacing output for unsupported constructs: external `$ref` (bundle first), callbacks/webhooks, cookie parameters, parameter `content`, nested parameter objects/arrays, `allowReserved`, path `label`/`matrix`, custom form encoding, unsupported media types, and advanced JSON Schema keywords such as conditionals, `not`, dynamic references, `prefixItems`, `patternProperties` and `unevaluatedProperties`. Typed `additionalProperties` alongside named properties are rejected because a TypeScript index signature would also constrain named properties; use a separate dictionary property. Recursive types must be components; circular aliases and cyclic YAML aliases are rejected.
+| `credentials` | Browser cookies |
+| --- | --- |
+| `omit` | Do not send |
+| `same-origin` | Allow for requests to the same origin |
+| `include` | Also allow for requests to another origin |
 
-Fetch cannot send GET/HEAD bodies or TRACE requests. A GET response declared without a body is rejected because React Query cannot cache `undefined`; the generator does not replace it with `null`. Empty text responses remain empty strings. Path segments `.` and `..` are rejected before sending a request because Fetch would normalize them and change the route. Schema `servers` and `security` do not override configuration: use `baseUrl` and `auth`. Response headers are not returned separately. Generated types do not validate server responses at runtime.
+If the token is missing or empty, no authorization header is added. For `HttpOnly` cookies, which JavaScript cannot read, let the browser send them:
 
-### Migration
+```js
+auth: { storage: 'none', credentials: 'include' }
+```
 
-Regenerate the client. Usual camelCase operation names and grouped variables remain, but full export compatibility is not guaranteed. Empty context, `deepMerge`, `QueryOperation`, shared `queryKeyFn` and `@ts-nocheck` are removed. Starting with `2.0.0-alpha.4`, query keys use `[baseUrl, method, path, operationName, normalizedVariables]` instead of `[operationName, variables]`: use `xQueryKey`, update manually constructed invalidation keys and clear persisted caches when upgrading. Type names use PascalCase; punctuation and underscores separate words. Errors use `OpenapiHttpError` or ordinary `Error` instead of `ErrorWrapper`. Stricter types may require call-site fixes.
+Browser cookie and CORS rules still apply. When calling `createOpenapiFetcher` or `createGraphqlFetcher` directly, `getToken` can return the complete `Authorization` header value. This option belongs to the fetcher factories, not the codegen config.
 
 ## Programmatic API
 
@@ -92,33 +209,53 @@ Regenerate the client. Usual camelCase operation names and grouped variables rem
 import { generate, type CodegenConfig } from '@kollors/react-codegen';
 
 const config: CodegenConfig = {
-  auth: {
-    storage: 'localStorage',
-    key: 'accessToken',
-  },
-  graphql: {
-    schema: './schema.graphql',
-    documents: './src/graphql',
-    output: './src/api/graphql.ts',
-    endpoint: '/graphql',
+  openapi: {
+    schema: './openapi.yaml',
+    output: './src/api/openapi.ts',
   },
 };
 
-const result = await generate(config);
-console.log(result.outputs);
+const { outputs } = await generate(config);
+console.log(outputs);
 ```
 
-Programmatic relative paths resolve from the current working directory. `generate` returns the generated output paths.
+The settings are the same as in the CLI config. Relative paths resolve from the current working directory. `generate` returns the paths of the generated files.
+
+## Supported schemas and limits
+
+Both generators create types from the schema. They do not validate server response data at runtime. A generation error leaves the existing output files in place.
 
-## Authentication and errors
+### OpenAPI
 
-The top-level `auth` settings apply to both generated clients. Add `auth` inside `openapi` or `graphql` to replace them for that client. Supported `storage` values are `localStorage`, `sessionStorage`, `cookie`, and `none`. If `auth` is present, `storage` is required. `key` names the stored token and is required for `localStorage`, `sessionStorage`, and `cookie`; it is not used with `none`. `scheme` defaults to `Bearer`; set it to `false` to send the token unchanged. `credentials` is optional and uses the Fetch API's default `same-origin` behavior unless set to `omit` or `include`.
+- Supports OpenAPI 3.0.x and 3.1.x; Swagger 2.0 is not supported.
+- Supports objects, arrays, dictionaries, enums, internal `$ref`, recursive components, `allOf`, `oneOf`, and `anyOf`. OpenAPI 3.1 also supports `const`, boolean schemas, and type arrays.
+- `required` controls required fields; `null` is included where the schema allows it. `readOnly` fields are excluded from request types, and `writeOnly` fields from response types. Dates remain strings.
+- Supports JSON, `+json`, text/XML strings, binary data as `Blob`, multipart, and URL-encoded bodies. For multiple request formats, priority is JSON, `+json`, URL-encoded, multipart, then other supported formats alphabetically.
+- Supports path/header `simple` and query `form` parameters, flat `deepObject` with `explode: true`, and `spaceDelimited`/`pipeDelimited` arrays with `explode: false`. Nested parameter objects and arrays are not supported.
 
-If no top-level or per-section `auth` is configured, generated clients do not add an `Authorization` header. JavaScript cannot read `HttpOnly` cookies; for those, use `auth: { storage: 'none', credentials: 'include' }` and let the browser send the cookie. `graphql.endpoint` defaults to `/api/graphql`. `openapi.baseUrl` defaults to an empty prefix, leaving generated paths relative.
+External `$ref` must be bundled into one document before generation. Callbacks, webhooks, cookie parameters, parameter `content`, `allowReserved`, `label`/`matrix` path styles, and custom form encoding are not supported. Advanced JSON Schema constraints such as conditions, `not`, `dependentRequired`, `patternProperties`, and `unevaluatedProperties` cause an error with the schema location.
 
-When using the fetcher factories directly, `getToken` may provide a custom token getter; it should return the complete `Authorization` header value.
+Typed `additionalProperties` combined with named properties are not supported; put the dictionary in a separate property. Numeric bounds, patterns, and lengths are not checked at runtime. `oneOf` becomes a TypeScript union without checking that exactly one branch matches; describe the discriminator field and its values in the schema.
 
-HTTP failures are reported as `GraphqlHttpError` or `OpenapiHttpError`, with status and response details. GraphQL execution errors are reported as `GraphqlResponseError` and include all messages returned by the server.
+Use `baseUrl` and `auth` to configure requests; schema `servers` and `security` are not applied. GET responses must declare a body. Empty mutation responses return `undefined` with type `void`; a missing body where one is declared causes a request error. GET/HEAD request bodies, TRACE, and path segments `.` or `..` are rejected. Response headers are not returned separately.
+
+### GraphQL
+
+Supports named queries and mutations, fragments, aliases, interfaces, and unions. Result types describe selected fields. Select `__typename` when you need to distinguish union members.
+
+Nullable fields use `T | null`; conditional selections with `@skip` or `@include` can be optional. Lists preserve element nullability. Non-null input fields and variables with defaults can be omitted but cannot be `null`. `@oneOf` inputs require exactly one non-null field. Custom scalars use `unknown`.
+
+Subscriptions and `@defer`/`@stream` are not supported. Schema downloads do not use `auth`; use a local schema export if the schema URL requires authentication.
+
+### Request errors
+
+| Error | Details |
+| --- | --- |
+| `OpenapiHttpError` | HTTP status and response data in `data` |
+| `GraphqlHttpError` | HTTP status and response body in `body` |
+| `GraphqlResponseError` | GraphQL execution errors in `errors` and partial response data in `data` |
+
+When updating existing generated clients, see the [migration guide](docs/migration.md).
 
 ## Development
 
@@ -127,6 +264,13 @@ npm ci
 npm run verify
 ```
 
+| Directory | Contents |
+| --- | --- |
+| `src/cli/` | CLI command |
+| `src/core/` | Configuration, generation entry point, file writing, and shared utilities |
+| `src/openapi/` | OpenAPI generator and request code |
+| `src/graphql/` | GraphQL generator and request code |
+
 ## License
 
 [MIT](LICENSE)