typedapi-client-helpers 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to `typedapi-client-helpers` are documented in this file.
+
+## [0.3.0] - 2026-07-10
+
+### Added
+
+* Added serializer-aware wire mapping through `toWireValue()` and `fromWireValue()`.
+* Added support for exact OpenAPI property names in JSON bodies, multipart forms, query parameters, headers, cookies, path parameters, responses, and documented error bodies.
+* Added support for path, query, header, cookie, and request-body inputs in the same operation.
+* Added typed unions for documented non-success response bodies.
+* Added structured client errors for network failures, aborted requests, and malformed responses.
+* Added `ApiHttpError` for operations without a documented OpenAPI error schema.
+* Added support for local OpenAPI `$ref` values in schemas, parameters, path items, request bodies, and responses.
+* Added support for `allOf` schemas with additional local properties.
+* Added configurable frontend method naming through `typedApiMethodNameStyle`.
+* Added `typedApiPrefixMethodNamesWithController` for controller-prefixed action names.
+* Added controller-name fallback detection from TypedApi metadata, OpenAPI tags, and route paths.
+* Added `typedapi.manifest.json` containing generator, contract, source, and naming information.
+* Added `--check`, `--strict`, `--offline`, and `--verbose` generator modes.
+* Added configurable Swagger download timeouts.
+* Added global and per-request timeout support.
+* Added support for external `AbortSignal` values and combined cancellation signals.
+* Added header and cookie utilities through `mergeHeaders()`, `toRequestHeaders()`, and `toCookieHeader()`.
+* Added automated generator and runtime tests.
+
+### Changed
+
+* Generated TypeScript property names now lowercase only the first character while preserving the remainder of the OpenAPI name.
+* Generated operation IDs and TypeScript identifiers are validated and sanitized before files are written.
+* Missing operation IDs now cause a clear error by default.
+* Missing operation IDs can optionally be generated with `typedApiGenerateMissingOperationIds`.
+* Action-based names can include the controller name by default, preventing collisions between actions with the same name in different controllers.
+* Controller prefixes are not duplicated when an action name already begins with the controller name.
+* Generated method signatures now keep non-body parameters, request bodies, and request options in predictable argument groups.
+* Generated methods now use `ApiHttpError` instead of `unknown` when no backend error schema is documented.
+* Generated API output no longer contains a root `index.ts`; methods and contracts are imported directly from their generated files.
+* Body-only operations now accept their payload directly without an additional request wrapper.
+* Query-only and paginated operations now use more specific generated query types.
+* Documented backend errors are returned alongside structured TypedApi client errors.
+* Malformed JSON is now returned as a structured parse error instead of being cast to the expected response type.
+* Exceptions thrown by consumer `onSuccess` and `onError` callbacks now propagate normally.
+* Fetch header merging now uses the native `Headers` implementation.
+* File, Blob, FormData, and multipart handling is safer in SSR and Node.js environments.
+* Binary image, PDF, and octet-stream responses are handled as blobs.
+* The package build now uses a deterministic TypeScript-only ESM, CommonJS, and declaration build instead of a bundler-dependent build.
+
+### Fixed
+
+* Fixed generated-output replacement failures caused by transient Windows filesystem locks.
+* Added retries for filesystem errors encountered while replacing generated output.
+* Added rollback-protected managed-file synchronization when `src/api` cannot be renamed because an editor, TypeScript watcher, antivirus scanner, or development server holds a directory handle.
+* Preserved unmanaged files during fallback synchronization.
+* Removed stale TypedApi-generated files during fallback synchronization.
+* Removed previously generated root `index.ts` files during regeneration.
+* Fixed handling of cancel token `0`.
+* Fixed abort-controller cleanup after completed requests.
+* Fixed URLs that already contain query strings.
+* Fixed absolute URL handling.
+* Fixed duplicate generated method and type names after TypeScript normalization.
+* Fixed property-name collisions caused by first-character normalization.
+
+### Migration notes
+
+* OpenAPI 3.x is now required. Swagger 2.0 documents are rejected.
+* Regenerated method names, parameter types, property names, and method signatures may differ from version `0.2.1`.
+* Projects using `typedApiMethodNameStyle: "action"` receive controller-prefixed names by default.
+* Set `typedApiPrefixMethodNamesWithController` to `false` to generate action-only names.
+* Set `typedApiGenerateMissingOperationIds` to `true` only when operation IDs cannot be supplied by the backend.
+* Import methods from `src/api/methods/*.api.ts` and contracts from `src/api/generated/data-contracts.ts` instead of using `src/api/index.ts`.
+* Regenerate and review committed API files after upgrading; regeneration removes the old generated root `index.ts`.

package/README.md

@@ -1,220 +1,231 @@
-# typedapi-client-helpers
-
-`typedapi-client-helpers` generates a typed TypeScript fetch client from an OpenAPI/Swagger document and adds reusable helper types and functions for API results, callbacks, filtering, sorting, request parameters, and multipart uploads.
-
-The package is intended for frontend projects that want a generated API client while still keeping generated files inside their own source tree.
-
-## Installation
-
-```bash
-npm install typedapi-client-helpers
-```
-
-## Basic usage
-
-Add a generator script to your project:
-
-```json
-{
-  "scripts": {
-    "generate:api": "typedapi-generate"
-  }
-}
-```
-
-Run the generator:
-
-```bash
-npm run generate:api
-```
-
-By default, the generator first looks for a local `swagger/swagger.json` file in the project where the command is run. If that file is not available, it tries `https://localhost:7000/swagger/v1/swagger.json` and stores a validated backup copy inside this package for later runs.
-
-You can also run the command directly:
-
-```bash
-npx typedapi-generate
-```
-
-## Configuration
-
-Configuration can be supplied in the `config` section of your `package.json`, with environment variables, or with npm command-line arguments.
-
-Configuration is resolved in this order:
-
-1. environment variables;
-2. npm command-line config values;
-3. the consuming project's `package.json` config;
-4. this package's default config values;
-5. built-in fallbacks.
-
-### Package configuration
-
-```json
-{
-  "config": {
-    "swaggerUrl": "https://localhost:7000/swagger/v1/swagger.json",
-    "swaggerFile": "swagger/openapi.json",
-    "typedApiSwaggerBackupFile": "swagger/swagger.backup.json",
-    "apiOutput": "src/api",
-    "typedApiCleanOutput": true,
-    "typedApiModuleNameFirstTag": true,
-    "typedApiUseTypeOnlyImports": true,
-    "typedApiDefaultFunctionsPath": "src/defaultApiFunctions",
-    "typedApiDefaultSuccessHandler": "handleGoodResult",
-    "typedApiDefaultErrorHandler": "handleErrors",
-    "typedApiDefaultResponseAsSuccess": false,
-    "typedApiGenerateUnionEnums": false,
-    "typedApiEnumNamesAsValues": false,
-    "typedApiBaseUrl": "https://localhost:7000"
-  }
-}
-```
-
-`swaggerFile` takes precedence over `swaggerUrl` when both are configured.
-
-### OpenAPI input and backup behavior
-
-The generator resolves the OpenAPI/Swagger input as follows:
-
-1. If `swaggerFile` is configured and the file exists, that file is used and copied to the backup file.
-2. If `swaggerFile` is configured but missing, the generator uses the backup file when it exists. If no backup exists, generation fails.
-3. If `swaggerUrl` is configured, the generator downloads it, validates that the response is JSON, writes it to the backup file, and generates from that backup copy.
-4. If `swaggerUrl` is configured but unavailable, the generator uses the backup file when it exists. If no backup exists, generation fails.
-5. If neither `swaggerFile` nor `swaggerUrl` is configured, the generator tries `swagger/swagger.json` in the current project.
-6. If no local default file exists, the generator tries `https://localhost:7000/swagger/v1/swagger.json` and falls back to the backup file if the URL is unavailable.
-
-The backup prevents a temporary unavailable Swagger endpoint from breaking generation when a valid backup was created earlier.
-
-The backup file is always package-owned: `swagger/swagger.backup.json` inside `typedapi-client-helpers`. Consumers do not need to add or configure a backup file in their own project.
-
-### Configuration options
-
-| Option                             | Default                                          | Description                                                                                                    |
-| ---------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
-| `swaggerUrl`                       | `https://localhost:7000/swagger/v1/swagger.json` | URL of the OpenAPI/Swagger document. Used when no configured or default local file is available.               |
-| `swaggerFile`                      | none                                             | Local path to an OpenAPI/Swagger document. When set, this is used before `swaggerUrl`.                         |
-| `apiOutput`                        | `src/api`                                        | Directory where the generated API files are written.                                                           |
-| `typedApiCleanOutput`              | `true`                                           | Cleans generated API output before writing the new files.                                                      |
-| `typedApiModuleNameFirstTag`       | `true`                                           | Groups operations by their first OpenAPI tag, creating one controller file per tag.                            |
-| `typedApiUseTypeOnlyImports`       | `true`                                           | Generates `import type` statements for imports that are only used as types. Set to `false` for normal imports. |
-| `typedApiDefaultFunctionsPath`     | `src/defaultApiFunctions`                        | Path to the project file that exports the shared default API success and error handlers. Created when missing. |
-| `typedApiDefaultSuccessHandler`    | `handleGoodResult`                               | Export name of the default success handler imported into generated method files.                               |
-| `typedApiDefaultErrorHandler`      | `handleErrors`                                   | Export name of the default error handler imported into generated method files.                                 |
-| `typedApiDefaultResponseAsSuccess` | `false`                                          | Uses the OpenAPI `default` response as a success response when no 2xx response is available.                   |
-| `typedApiGenerateUnionEnums`       | `false`                                          | Generates enum schemas as string-literal union types instead of `as const` enum-like objects.               |
-| `typedApiEnumNamesAsValues`        | `false`                                          | When OpenAPI uses `x-enumNames`, uses those names as enum/union values instead of only as object keys.   |
-| `typedApiBaseUrl`                  | first OpenAPI server URL                         | Overrides the generated HTTP client's default `baseUrl`.                                                       |
-
-### Environment variables
-
-| Environment variable                    | Description                                                  |
-| --------------------------------------- | ------------------------------------------------------------ |
-| `SWAGGER_URL`                           | URL of the OpenAPI/Swagger document.                         |
-| `SWAGGER_FILE`                          | Local path to an OpenAPI/Swagger document.                   |
-| `API_OUTPUT`                            | Directory where generated API files are written.             |
-| `TYPED_API_CLEAN_OUTPUT`                | Cleans generated API output when set to `true`.              |
-| `TYPED_API_MODULE_NAME_FIRST_TAG`       | Groups operations by first OpenAPI tag when set to `true`.   |
-| `TYPED_API_USE_TYPE_ONLY_IMPORTS`       | Enables type-only imports when set to `true`.                |
-| `TYPED_API_DEFAULT_FUNCTIONS_PATH`      | Path to the shared default handler file.                     |
-| `TYPED_API_DEFAULT_SUCCESS_HANDLER`     | Export name of the default success handler.                  |
-| `TYPED_API_DEFAULT_ERROR_HANDLER`       | Export name of the default error handler.                    |
-| `TYPED_API_DEFAULT_RESPONSE_AS_SUCCESS` | Allows the OpenAPI `default` response to be used as success. |
-| `TYPED_API_GENERATE_UNION_ENUMS`        | Generates enum schemas as union types when set to `true`.    |
-| `TYPED_API_ENUM_NAMES_AS_VALUES`        | Generates enum-like literal values when set to `true`.       |
-| `TYPED_API_BASE_URL`                    | Overrides the generated HTTP client's default base URL.      |
-
-Example:
-
-```bash
-SWAGGER_URL=https://localhost:7000/swagger/v1/swagger.json npm run generate:api
-```
-
-### Command-line npm config
-
-```bash
-npm run generate:api --swagger-url=https://localhost:7000/swagger/v1/swagger.json
-npm run generate:api --swagger-file=swagger/openapi.json
-npm run generate:api --typed-api-swagger-backup-file=swagger/swagger.backup.json
-npm run generate:api --api-output=src/api
-npm run generate:api --typed-api-use-type-only-imports=true
-npm run generate:api --typed-api-module-name-first-tag=true
-npm run generate:api --typed-api-generate-union-enums=true
-```
-
-## Generated structure
-
-Running the generator creates a structure similar to this:
-
-```text
-src/
-└── api/
-    ├── generated/
-    │   ├── data-contracts.ts
-    │   └── http-client.ts
-    ├── methods/
-    │   ├── Product.api.ts
-    │   └── Supplier.api.ts
-    └── index.ts
-```
-
-| Folder or file                | Description                                                                                                                                                                            |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `generated/data-contracts.ts` | TypeScript models, request parameter types, const enum-like objects, and multipart payload interfaces generated from the OpenAPI schema.                                               |
-| `generated/http-client.ts`    | Function-based fetch client with request params, security worker support, custom fetch support, cancellation tokens, and content formatting. It does not generate a class.             |
-| `methods/*.api.ts`            | One generated file per controller/tag. These files export plain functions such as `getProducts`, `createProduct`, and `uploadProductFiles`; there are no generated controller classes. |
-| `index.ts`                    | Barrel file that exports contracts, HTTP client utilities, and callable methods.                                                                                                       |
-
-The generated `generated/` folder, `methods/` folder, old `controllers/` folder, and `index.ts` are cleaned each time the generator runs.
-
-The `generated/` and `methods/` folders are cleaned and recreated each time the generator runs.
-
-## Calling generated methods
-
-Generated method files export plain functions that can be called directly. The wrapper return type stays `ApiResult<T>`, so existing UI code can keep using `result.ok`, `result.status`, `result.response`, and `result.error`.
-
-```ts
-import {
-  getProducts,
-  getProductById,
-  updateProduct,
-} from "./api/methods/Product.api";
-
-const products = await getProducts([], 1, 25);
-const product = await getProductById({ id: "..." });
-await updateProduct(
-  { id: "..." },
-  { name: "Updated", sku: "SKU-1", price: 10, stock: 5, active: true },
-);
-```
-
-The generated method signatures stay close to the existing callable wrappers:
-
-```ts
-getProducts(filters?, page?, pageSize?, sortBy?, sortDirection?, options?);
-getProductById({ id }, options?);
-updateProduct({ id }, data, options?);
-uploadProductFile(data, options?);
-```
-
-`options.params` is the generated `RequestParams` type and is forwarded directly to the fetch client.
-
-### Default success and error handlers
-
-Generated method files import default handlers from `typedApiDefaultFunctionsPath` when that file exports the configured handler names. With the package defaults, the generator uses `src/defaultApiFunctions.ts` and creates it automatically when it is missing.
-
-```ts
-export function handleGoodResult<T>(
-  response: ApiSuccessResult<T>,
-): void | Promise<void> {
-  // default success behavior
-}
-
-export function handleErrors<T>(
-  error: ApiErrorResult<T>,
-): void | Promise<void> {
-  // default error behavior
-}
-```
-
-You can override the path or export names from the consuming project's `package.json` without changing generated method signatures.
+# typedapi-client-helpers
+
+A small Fetch runtime and OpenAPI 3 TypeScript generator designed to work with `TypedApi.Swagger` on ASP.NET Core.
+
+## Version 0.3 highlights
+
+- Lowercases only the first character of generated TypeScript members while preserving exact OpenAPI names on the wire.
+- Sanitizes operation IDs and rejects duplicates before writing output.
+- Can name frontend functions from either the unique OpenAPI operation ID or the original ASP.NET controller action name.
+- Supports path, query, header, cookie, and request-body inputs in the same operation.
+- Resolves local OpenAPI references for schemas, parameters, request bodies, and responses.
+- Supports `allOf` composition with local properties.
+- Generates typed unions for documented non-success responses.
+- Uses a structured `ApiHttpError` when an operation has no documented error schema.
+- Produces `typedapi.manifest.json` without creating a root API barrel file.
+- Writes generated output transactionally, with a Windows-safe in-place fallback when directory renames are blocked by editors or file watchers.
+- Adds `--check`, `--strict`, `--offline`, and `--verbose` CLI modes.
+- Improves cancellation, timeouts, header merging, SSR safety, and malformed-response handling.
+
+## Install
+
+```bash
+npm install typedapi-client-helpers@0.3.0
+```
+
+The generator expects an OpenAPI 3.x document. Swagger 2.0 documents are rejected with a clear error.
+
+## Configure generation
+
+Add settings to the consuming application's `package.json`:
+
+```json
+{
+  "scripts": {
+    "generate:api": "typedapi-generate",
+    "check:api": "typedapi-generate --check"
+  },
+  "config": {
+    "swaggerUrl": "https://localhost:7000/swagger/v1/swagger.json",
+    "apiOutput": "src/api",
+    "typedApiSwaggerBackupFile": "swagger/swagger.backup.json",
+    "typedApiDownloadTimeoutMs": 15000,
+    "typedApiCleanOutput": true,
+    "typedApiGenerateMissingOperationIds": false,
+    "typedApiMethodNameStyle": "operationId",
+    "typedApiPrefixMethodNamesWithController": true
+  }
+}
+```
+
+Run:
+
+```bash
+npm run generate:api
+```
+
+Generated output contains:
+
+```text
+src/api/
+├── generated/
+│   ├── data-contracts.ts
+│   └── http-client.ts
+├── methods/
+│   └── Products.api.ts
+└── typedapi.manifest.json
+```
+
+The generator intentionally does not create `src/api/index.ts`. Import generated methods and contracts directly from their files:
+
+```ts
+import { getProducts } from "./api/methods/Product.api";
+import type { ProductModel } from "./api/generated/data-contracts";
+```
+
+When upgrading from an earlier 0.3.0 build, the next generation removes the old generated `src/api/index.ts`. The Swagger backup belongs to the consuming project, not this npm package.
+
+## Frontend method names
+
+Choose the source of generated function names with `typedApiMethodNameStyle`:
+
+```json
+{
+  "config": {
+    "typedApiMethodNameStyle": "action",
+    "typedApiPrefixMethodNamesWithController": true
+  }
+}
+```
+
+- `"operationId"` uses the unique OpenAPI operation ID. The controller-prefix setting does not affect this mode.
+- `"action"` uses the original ASP.NET controller action name.
+- `typedApiPrefixMethodNamesWithController: true` is the default in action mode and prefixes the normalized controller name.
+- `typedApiPrefixMethodNamesWithController: false` removes the controller prefix.
+
+For an `OrderController` action named `GetOrderById`:
+
+```text
+typedApiPrefixMethodNamesWithController: true  -> orderGetOrderById(...)
+typedApiPrefixMethodNamesWithController: false -> getOrderById(...)
+```
+
+Operation-specific types follow the selected name too:
+
+```text
+true  -> OrderGetOrderByIdParams
+false -> GetOrderByIdParams
+```
+
+Action-name mode requires the matching `TypedApi.Swagger` package, which emits `x-typedapi-operation.actionName`. When the prefix is enabled, the controller name is read from `x-typedapi-operation.controllerName`, the first OpenAPI tag, or the route. If disabling the prefix creates duplicate names across controllers, generation stops with a clear collision error; enable the prefix, rename an action, or use `"operationId"`.
+
+
+## CI consistency check
+
+```bash
+typedapi-generate --check
+```
+
+This generates in memory and exits with an error when committed generated files are missing, stale, or different.
+
+Other modes:
+
+```bash
+typedapi-generate --strict   # fail instead of using a backup after a download error
+typedapi-generate --offline  # intentionally generate from the backup
+typedapi-generate --verbose  # print additional diagnostics
+```
+
+
+## Generated property names
+
+Generated interface and parameter members lowercase **only the first character**:
+
+```ts
+Files -> files
+URLValue -> uRLValue
+ProductID -> productID
+snake_case -> snake_case
+```
+
+The rest of each name is left unchanged. Generated wire metadata converts these local names back to the exact OpenAPI names for JSON, multipart forms, query parameters, headers, cookies, and path parameters. Responses and documented error bodies are converted in the opposite direction.
+
+## Generated method shape
+
+Generated methods keep parameters and request bodies as separate positional groups. Non-body parameters come first, the body comes second, and request options remain last:
+
+```ts
+await updateWarehouse(
+  { id: requireId(context.warehouseId, "Warehouse ID") },
+  warehouse,
+);
+```
+
+The generated signature is:
+
+```ts
+export async function updateWarehouse(
+  pathParams: UpdateWarehouseParams,
+  data: WarehouseRequest,
+  options: ApiMethodOptions<WarehouseModel, ApiHttpError, RequestParams> = {},
+): Promise<ApiResult<WarehouseModel, ApiHttpError>>;
+```
+
+Path operations without a body use only the params object:
+
+```ts
+await deleteSupplier({ id: requireId(context.supplierId, "Supplier ID") });
+```
+
+Body-only operations accept their payload directly:
+
+```ts
+await uploadProductFiles({ files: selectedFiles });
+```
+
+Query-only operations use a `query` argument. Operations involving headers or cookies without path parameters use `requestParams`. All generated parameter interfaces are named `OperationNameParams`; nested `path`, `query`, `headers`, `cookies`, or `body` wrappers are not generated.
+
+Request options are always last:
+
+```ts
+await updateWarehouse(pathParams, data, {
+  params: {
+    signal: abortController.signal,
+    timeoutMs: 10_000,
+    headers: new Headers({ Authorization: "Bearer ..." }),
+  },
+  onSuccess: result => console.log(result.response),
+  onError: result => console.error(result.error),
+});
+```
+
+## Typed errors
+
+When the OpenAPI document describes error response bodies, generated methods expose their generated type or union. When no error schema is documented, the method uses `ApiHttpError` instead of `unknown`:
+
+```ts
+const result = await cancelOrder({ id, reason });
+
+if (!result.ok) {
+  if (result.error.kind === "http") {
+    console.error(result.error.status, result.error.body);
+  } else {
+    // Structured TypedApi client error: network, aborted, or parse.
+    console.error(result.error);
+  }
+}
+```
+
+Malformed JSON is reported as a structured parse error instead of being cast to the expected response type. Consumer callback exceptions are allowed to propagate and are not disguised as API failures.
+
+## Runtime configuration
+
+```ts
+import { configureApiClient, setSecurityData } from "typedapi-client-helpers";
+
+configureApiClient({
+  baseUrl: "https://api.example.com",
+  timeoutMs: 15_000,
+  securityWorker: token => token
+    ? { headers: { Authorization: `Bearer ${token}` } }
+    : undefined
+});
+
+setSecurityData("access-token");
+```
+
+The runtime also exports `createApiClient`, `request`, `abortRequest`, `mergeHeaders`, `toRequestHeaders`, `toCookieHeader`, `handleApiResponse`, `buildQuery`, `toFormData`, `toWireValue`, and `fromWireValue`.
+
+## Backend pairing
+
+Use `TypedApi.Swagger` 0.3 or newer on the backend. It emits `x-typedapi.contractVersion = 1`, unique operation IDs, serializer-aware property names, and explicit pagination metadata. The generator validates the contract version before replacing generated files.