@openmirai/typeforge 0.1.7

package/README.md

@@ -0,0 +1,268 @@
+<p align="center">
+  <img src="./assets/typeforge-logo.png" alt="Typeforge logo" width="280" />
+</p>
+
+# @openmirai/typeforge
+
+Headless **OpenAPI / Swagger → TypeScript** codegen. The CLI is `typeforge`. It reads a spec, writes typed route enums, request types, and HTTP caller functions, and never talks to a network.
+
+- **npm:** [`@openmirai/typeforge`](https://www.npmjs.com/package/@openmirai/typeforge)
+- **GitHub:** [openmirai/mirai-openapi-codegen](https://github.com/openmirai/mirai-openapi-codegen)
+
+You own `http.ts` (the `HTTPFetch` adapter). Generated files import that adapter — they do not invent axios/fetch calls inline.
+
+## Migrating from `@openmirai/openapi-codegen`
+
+Install `@openmirai/typeforge` and update package imports and scripts to use the canonical `typeforge` name. During migration, the package also exposes the legacy `openapi-codegen` binary and reads `openapi-codegen.json`, `openapi-codegen.local.json`, and the `openapiCodegen` package.json key. New projects created by `typeforge init` use the Typeforge names.
+
+## What it generates
+
+For each **source** (a named API, e.g. `atlas`), under `<apiRoot>/<source>/generated/`:
+
+| Output | Role |
+| --- | --- |
+| `types/**/*.d.ts` | Params, body, and response types per operation |
+| `functions/**/*.ts` | Typed callers (`getWidgets`, …) |
+| `routes.ts` | `Routes` string map + `RouteTargets` enum (name configurable) |
+| `runtime.ts` | Re-exports `HTTPFetch`, `httpFetch` (if singleton), routes |
+| `base.ts` | `BaseResponse<T>` when the spec uses a response envelope (or `base.d.ts` for split declaration output) |
+
+Optional:
+
+- **TanStack Query** — set `tanstackQuery: true` in `source.ts` **and** add `<apiRoot>/query-scope.ts`.
+- **Zod** — wrap a schema with `createZodValidator` from `@openmirai/typeforge/validation/zod` and pass it as `config.validateResponse`.
+
+## Install
+
+Requires **Node.js 20.11+** (LTS). Use any package manager.
+
+| Package manager | Install |
+| --- | --- |
+| npm | `npm install --save-dev @openmirai/typeforge` |
+| pnpm | `pnpm add -D @openmirai/typeforge` |
+| yarn | `yarn add -D @openmirai/typeforge` |
+| bun | `bun add -d @openmirai/typeforge` |
+
+Axios is an **optional peer**. Install `axios` only if you use `--client axios`.
+
+Add a script so every package manager resolves the CLI from `node_modules/.bin`:
+
+```json
+{
+  "scripts": {
+    "generate:types": "typeforge generate --all"
+  }
+}
+```
+
+Then run `npm run generate:types`, `pnpm run generate:types`, `yarn generate:types`, or `bun run generate:types`.
+
+## CLI usage
+
+Prefer the `package.json` script above. To invoke the binary directly:
+
+| Command | npm | pnpm | yarn | bun |
+| --- | --- | --- | --- | --- |
+| Init a source | `npx typeforge init --source atlas --client axios` | `pnpm exec typeforge init --source atlas --client axios` | `yarn typeforge init --source atlas --client axios` | `bunx typeforge init --source atlas --client axios` |
+| Generate one source | `npx typeforge generate --source atlas` | `pnpm exec typeforge generate --source atlas` | `yarn typeforge generate --source atlas` | `bunx typeforge generate --source atlas` |
+| Generate all sources | `npx typeforge generate --all` | `pnpm exec typeforge generate --all` | `yarn typeforge generate --all` | `bunx typeforge generate --all` |
+| Drift check (CI) | `npx typeforge generate --all --check` | `pnpm exec typeforge generate --all --check` | `yarn typeforge generate --all --check` | `bunx typeforge generate --all --check` |
+
+| Subcommand | Purpose |
+| --- | --- |
+| `init` | Scaffold `http.ts`, `source.ts`, `known-types.ts` |
+| `generate` | Write generated files |
+| `check` | Same as `generate --check` — exit 1 if output would change |
+| `accept-base` | Update generated `base.ts` (`base.d.ts` for split declaration output) and patch `models.ts` `BaseResponse` |
+
+`--check` and `--accept-base` cannot be combined. See [docs/cli.md](docs/cli.md) for the full command reference.
+
+## How the flow works
+
+```text
+init  →  source.ts + http.ts  →  resolve spec  →  generate  →  typed callers
+```
+
+### 1. Init a source
+
+```bash
+typeforge init --source atlas --client axios
+typeforge init --source orbit --client fetch --layout packages
+```
+
+`--client` is `axios` | `fetch` | `custom`. `--layout` is `monolith` (default, `apiRoot` = `src/api`) or `packages` (`apiRoot` = `packages/utils/src/api`).
+
+Init creates (if missing):
+
+- `typeforge.json` with `apiRoot`
+- `<apiRoot>/http.ts` — your `HTTPFetch` implementation
+- `<apiRoot>/known-types.ts` — optional schema → local type mapping
+- `<apiRoot>/<source>/source.ts` — per-API config (type-safe template)
+- `<apiRoot>/<source>/generated/` directory
+
+Existing files are skipped.
+
+### 2. Configure `source.ts`
+
+Use `defineSourceConfig` for autocomplete and compile-time checks:
+
+```ts
+import { defineSourceConfig } from "@openmirai/typeforge";
+
+export default defineSourceConfig({
+  spec: "./specs/acme.json",
+  functionsDir: "packages/utils/src/api/routes/atlas",
+  typesDir: "packages/types/src/api/atlas",
+  pathPrefix: "/api/acme/v3",
+  stripApiPrefix: true,
+  routeEnumName: "RouteTargets",
+  generationMode: "authoritative",
+  naming: "path",
+  ignorePaths: [],
+  maxRenderDepth: 50,
+  resolveMapKeyRefs: true,
+  tanstackQuery: false,
+  queryExtends: {
+    page: "page",
+    limit: "limit",
+    sortBy: "sortBy",
+    sortOrder: "sortOrder",
+    paginationTypeName: "OffsetLimitQuery",
+    paginationImportPath: "./pagination",
+    sortTypeName: "SortParams",
+    sortImportPath: "./pagination",
+  },
+});
+```
+
+Plain `export default { ... }` still works; the CLI reads config fields from the file at generate time.
+
+Re-exported types from the package root:
+
+- `SourceConfig`, `QueryExtendsConfig`, `GenerationMode`, `NamingStrategy`
+- `defineSourceConfig(config)` — identity helper for typed `source.ts`
+
+| Field | Meaning |
+| --- | --- |
+| `spec` | Project-relative spec path (used when no `--spec` / env override) |
+| `functionsDir` | Project-relative function output directory (defaults to the source's `generated/functions`) |
+| `typesDir` | Project-relative type output directory (defaults to the source's `generated/types`; a generated `base.d.ts` is placed beside this directory when customized) |
+| `pathPrefix` | Only generate operations under this prefix (e.g. `/api/acme/v3`) |
+| `ignorePaths` | Extra paths to skip |
+| `stripApiPrefix` | Strip a leading `/api` segment from route enum member names |
+| `routeEnumName` | Enum name (default `RouteTargets`) |
+| `generationMode` | `authoritative` (overwrite routes) or `merge` (keep extra enum members) |
+| `naming` | `path` or `operationId` for function names |
+| `queryExtends` | Fold page/limit/sort query params into shared pagination types |
+| `tanstackQuery` | Emit Query helpers when `query-scope.ts` exists |
+| `importBase` | Force import prefix for generated function files (overrides tsconfig aliases) |
+| `maxRenderDepth` / `resolveMapKeyRefs` | Schema renderer limits |
+| `unwrapResponseData` | Emit an envelope's `data` schema as the operation response type when the project's `HTTPFetch` already unwraps envelopes |
+
+### 3. Spec resolution (first match wins)
+
+1. `--spec <path>`
+2. Env `OPENAPI_SPEC_<KEY>` — source key uppercased, hyphens → underscores
+3. `spec` in that source’s `source.ts`
+4. `typeforge.local.json` (gitignored) map of `{ "<source>": "<path>" }`
+5. Committed snapshot `<apiRoot>/<source>/spec.json`
+
+### 4. Envelope modes
+
+Inferred from success response schemas. Details: [docs/envelope.md](docs/envelope.md).
+
+| Mode | When | Types |
+| --- | --- | --- |
+| **shared** | One envelope shape (`data` / `success` / `message`) | `BaseResponse<Unwrapped>` |
+| **raw** | No shared envelope | Spec schema as-is |
+| **mixed** | Some ops have `data`, others do not | Unwrap **per operation** when `data` exists |
+
+Set `unwrapResponseData: true` when the project's injected `HTTPFetch`
+normalizes successful envelope bodies before returning `{ data }`. Every
+operation whose success schema is recognized as an API envelope then receives
+its `data` payload type. Data-only objects and business payloads that also
+contain `success` remain raw. Metadata-only envelopes without a `data` field
+receive the `null` type,
+matching clients that normalize an omitted payload to `null`.
+The default remains envelope-preserving and is compatible with the bundled
+Axios and Fetch adapters.
+
+### 5. HTTPFetch (`http.ts`)
+
+Adapters implement `HTTPFetch` from `@openmirai/typeforge/http` (or the axios/fetch adapter packages). Methods return `Promise<{ data: TResponse }>`.
+
+- If `http.ts` **exports `httpFetch`**, generated functions call that singleton.
+- Otherwise they take `props.http: HTTPFetch` (injected).
+
+### 6. Path-alias aware imports
+
+Generated function files import types and `runtime`, and generated response
+types import the generated base declaration (`base.ts` in monolith output, or
+`base.d.ts` for split declaration output), using:
+
+1. `importBase` in `source.ts`, if set
+2. Else `compilerOptions.paths` from the nearest ancestor `tsconfig.json` with path aliases, starting at the corresponding `functionsDir` or `typesDir`
+3. Else relative paths (`../../runtime`)
+
+## Where files go
+
+`typeforge.json`:
+
+```json
+{ "apiRoot": "packages/utils/src/api" }
+```
+
+You can also set `"typeforge": { "apiRoot": "..." }` in `package.json`. The JSON file wins.
+
+**Monolith** (`--layout monolith`, default):
+
+```text
+src/api/http.ts
+src/api/known-types.ts
+src/api/models.ts                 # optional BaseResponse drift check
+src/api/query-scope.ts            # optional TanStack
+src/api/atlas/source.ts
+src/api/atlas/spec.json           # optional snapshot
+src/api/atlas/generated/…
+```
+
+**Packages layout** (`--layout packages`): typical placement is `packages/utils/src/api/<source>/`.
+
+Set `functionsDir` and `typesDir` when callers and declarations belong in
+different packages. Relative imports continue to work without aliases; when a
+nearby `tsconfig.json` maps both output roots, deep generated imports use those
+aliases automatically.
+
+## Zod (optional)
+
+```ts
+import { createZodValidator } from "@openmirai/typeforge/validation/zod";
+import { widgetListSchema } from "./widget-list";
+
+await getWidgets({
+  params: { page: 1, limit: 20 },
+  config: { validateResponse: createZodValidator(widgetListSchema) },
+});
+```
+
+## Releasing
+
+Publishes go through [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) (GitHub Actions OIDC). Do not `npm publish` from a laptop.
+
+| | Value |
+| --- | --- |
+| npm package | `@openmirai/typeforge` |
+| GitHub repo | `openmirai/mirai-openapi-codegen` |
+| Workflow | `.github/workflows/publish.yml` |
+| Tag | `v*` (e.g. `v0.1.3`) |
+
+## Develop this repo
+
+This repository uses **pnpm** for its own CI. Consumers are not required to use pnpm.
+
+```bash
+pnpm install
+pnpm verify   # format, lint, typecheck, build, coverage
+```
+
+Test layout: [test/README.md](test/README.md).

package/dist/adapters/axios/index.d.ts

@@ -0,0 +1,38 @@
+import { AxiosInstance } from "axios";
+//#region src/json/types.d.ts
+type QueryParamValue = string | number | boolean | null | undefined;
+type QueryParams = Record<string, QueryParamValue>;
+//#endregion
+//#region src/http/validate.d.ts
+type ResponseValidator<T> = (value: unknown) => T;
+//#endregion
+//#region src/http/types.d.ts
+interface HTTPFetchConfig<TParams extends object = QueryParams, TResponse = unknown> {
+  signal?: AbortSignal;
+  params?: TParams;
+  headers?: Record<string, string>;
+  validateResponse?: ResponseValidator<TResponse>;
+}
+interface HTTPFetch {
+  get<TResponse, TParams extends object = QueryParams>(route: string, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+  post<TResponse, TBody = unknown, TParams extends object = QueryParams>(route: string, body: TBody, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+  put<TResponse, TBody = unknown, TParams extends object = QueryParams>(route: string, body: TBody, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+  patch<TResponse, TBody = unknown, TParams extends object = QueryParams>(route: string, body: TBody, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+  delete<TResponse, TParams extends object = QueryParams>(route: string, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+}
+//#endregion
+//#region src/adapters/axios/index.d.ts
+declare function createAxiosAdapter(instance: AxiosInstance): HTTPFetch;
+//#endregion
+export { type HTTPFetch, type HTTPFetchConfig, createAxiosAdapter };
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/axios/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/json/types.ts","../../../src/http/validate.ts","../../../src/http/types.ts","../../../src/adapters/axios/index.ts"],"mappings":";;KAUY;KAEA,cAAc,eAAe;;;KCZ7B,kBAAkB,MAAM,mBAAmB;;;UCOtC,gBACf,yBAAyB,aACzB;EAEA,SAAS;EACT,SAAS;EACT,UAAU;EACV,mBAAmB,kBAAkB;;UAGtB;EACf,IAAI,WAAW,yBAAyB,aACtC,eACA,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;EACnB,KAAK,WAAW,iBAAiB,yBAAyB,aACxD,eACA,MAAM,OACN,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;EACnB,IAAI,WAAW,iBAAiB,yBAAyB,aACvD,eACA,MAAM,OACN,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;EACnB,MAAM,WAAW,iBAAiB,yBAAyB,aACzD,eACA,MAAM,OACN,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;EACnB,OAAO,WAAW,yBAAyB,aACzC,eACA,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;;;;iBCLL,mBAAmB,UAAU,gBAAgB"}

package/dist/adapters/axios/index.js

@@ -0,0 +1,43 @@
+//#region src/http/validate.ts
+var ResponseValidationError = class extends Error {
+	cause;
+	constructor(message, cause) {
+		super(message);
+		this.name = "ResponseValidationError";
+		this.cause = cause;
+	}
+};
+function coerceResponseData(value, validator) {
+	if (validator === void 0) return value;
+	try {
+		return validator(value);
+	} catch (error) {
+		throw new ResponseValidationError("Response validation failed", error);
+	}
+}
+//#endregion
+//#region src/adapters/axios/index.ts
+function toAxiosConfig(config) {
+	if (config === void 0) return;
+	const axiosConfig = {};
+	if (config.signal !== void 0) axiosConfig.signal = config.signal;
+	if (config.params !== void 0) axiosConfig.params = config.params;
+	if (config.headers !== void 0) axiosConfig.headers = config.headers;
+	return axiosConfig;
+}
+function mapResponse(data, config) {
+	return { data: coerceResponseData(data, config?.validateResponse) };
+}
+function createAxiosAdapter(instance) {
+	return {
+		delete: (route, config) => instance.delete(route, toAxiosConfig(config)).then((response) => mapResponse(response.data, config)),
+		get: (route, config) => instance.get(route, toAxiosConfig(config)).then((response) => mapResponse(response.data, config)),
+		patch: (route, body, config) => instance.patch(route, body, toAxiosConfig(config)).then((response) => mapResponse(response.data, config)),
+		post: (route, body, config) => instance.post(route, body, toAxiosConfig(config)).then((response) => mapResponse(response.data, config)),
+		put: (route, body, config) => instance.put(route, body, toAxiosConfig(config)).then((response) => mapResponse(response.data, config))
+	};
+}
+//#endregion
+export { createAxiosAdapter };
+
+//# sourceMappingURL=index.js.map

package/dist/adapters/axios/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/http/validate.ts","../../../src/adapters/axios/index.ts"],"sourcesContent":["export type ResponseValidator<T> = (value: unknown) => T;\n\nexport class ResponseValidationError extends Error {\n  override readonly cause: unknown;\n\n  constructor(message: string, cause: unknown) {\n    super(message);\n    this.name = \"ResponseValidationError\";\n    this.cause = cause;\n  }\n}\n\nexport function coerceResponseData<T>(\n  value: unknown,\n  validator?: ResponseValidator<T>\n): T {\n  if (validator === undefined) {\n    return value as T;\n  }\n\n  try {\n    return validator(value);\n  } catch (error) {\n    throw new ResponseValidationError(\"Response validation failed\", error);\n  }\n}\n","import type { AxiosInstance, AxiosRequestConfig } from \"axios\";\n\nimport { coerceResponseData } from \"../../http/validate\";\nimport type { HTTPFetch, HTTPFetchConfig } from \"../../http/types\";\nimport type { QueryParams } from \"../../json/types\";\n\nfunction toAxiosConfig<TParams extends object>(\n  config?: HTTPFetchConfig<TParams, unknown>\n): AxiosRequestConfig | undefined {\n  if (config === undefined) {\n    return undefined;\n  }\n\n  const axiosConfig: AxiosRequestConfig = {};\n  if (config.signal !== undefined) {\n    axiosConfig.signal = config.signal;\n  }\n  if (config.params !== undefined) {\n    axiosConfig.params = config.params;\n  }\n  if (config.headers !== undefined) {\n    axiosConfig.headers = config.headers;\n  }\n  return axiosConfig;\n}\n\nfunction mapResponse<TResponse, TParams extends object>(\n  data: unknown,\n  config?: HTTPFetchConfig<TParams, TResponse>\n): { data: TResponse } {\n  return {\n    data: coerceResponseData<TResponse>(data, config?.validateResponse),\n  };\n}\n\nexport function createAxiosAdapter(instance: AxiosInstance): HTTPFetch {\n  return {\n    delete: <TResponse, TParams extends object = QueryParams>(\n      route: string,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) =>\n      instance\n        .delete<TResponse>(route, toAxiosConfig(config))\n        .then((response) => mapResponse(response.data, config)),\n    get: <TResponse, TParams extends object = QueryParams>(\n      route: string,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) =>\n      instance\n        .get<TResponse>(route, toAxiosConfig(config))\n        .then((response) => mapResponse(response.data, config)),\n    patch: <TResponse, TBody = unknown, TParams extends object = QueryParams>(\n      route: string,\n      body: TBody,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) =>\n      instance\n        .patch<TResponse>(route, body, toAxiosConfig(config))\n        .then((response) => mapResponse(response.data, config)),\n    post: <TResponse, TBody = unknown, TParams extends object = QueryParams>(\n      route: string,\n      body: TBody,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) =>\n      instance\n        .post<TResponse>(route, body, toAxiosConfig(config))\n        .then((response) => mapResponse(response.data, config)),\n    put: <TResponse, TBody = unknown, TParams extends object = QueryParams>(\n      route: string,\n      body: TBody,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) =>\n      instance\n        .put<TResponse>(route, body, toAxiosConfig(config))\n        .then((response) => mapResponse(response.data, config)),\n  };\n}\n\nexport type { HTTPFetch, HTTPFetchConfig } from \"../../http/types\";\n"],"mappings":";AAEA,IAAa,0BAAb,cAA6C,MAAM;CACjD;CAEA,YAAY,SAAiB,OAAgB;EAC3C,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,QAAQ;CACf;AACF;AAEA,SAAgB,mBACd,OACA,WACG;CACH,IAAI,cAAc,KAAA,GAChB,OAAO;CAGT,IAAI;EACF,OAAO,UAAU,KAAK;CACxB,SAAS,OAAO;EACd,MAAM,IAAI,wBAAwB,8BAA8B,KAAK;CACvE;AACF;;;ACnBA,SAAS,cACP,QACgC;CAChC,IAAI,WAAW,KAAA,GACb;CAGF,MAAM,cAAkC,CAAC;CACzC,IAAI,OAAO,WAAW,KAAA,GACpB,YAAY,SAAS,OAAO;CAE9B,IAAI,OAAO,WAAW,KAAA,GACpB,YAAY,SAAS,OAAO;CAE9B,IAAI,OAAO,YAAY,KAAA,GACrB,YAAY,UAAU,OAAO;CAE/B,OAAO;AACT;AAEA,SAAS,YACP,MACA,QACqB;CACrB,OAAO,EACL,MAAM,mBAA8B,MAAM,QAAQ,gBAAgB,EACpE;AACF;AAEA,SAAgB,mBAAmB,UAAoC;CACrE,OAAO;EACL,SACE,OACA,WAEA,SACG,OAAkB,OAAO,cAAc,MAAM,CAAC,CAAC,CAC/C,MAAM,aAAa,YAAY,SAAS,MAAM,MAAM,CAAC;EAC1D,MACE,OACA,WAEA,SACG,IAAe,OAAO,cAAc,MAAM,CAAC,CAAC,CAC5C,MAAM,aAAa,YAAY,SAAS,MAAM,MAAM,CAAC;EAC1D,QACE,OACA,MACA,WAEA,SACG,MAAiB,OAAO,MAAM,cAAc,MAAM,CAAC,CAAC,CACpD,MAAM,aAAa,YAAY,SAAS,MAAM,MAAM,CAAC;EAC1D,OACE,OACA,MACA,WAEA,SACG,KAAgB,OAAO,MAAM,cAAc,MAAM,CAAC,CAAC,CACnD,MAAM,aAAa,YAAY,SAAS,MAAM,MAAM,CAAC;EAC1D,MACE,OACA,MACA,WAEA,SACG,IAAe,OAAO,MAAM,cAAc,MAAM,CAAC,CAAC,CAClD,MAAM,aAAa,YAAY,SAAS,MAAM,MAAM,CAAC;CAC5D;AACF"}

package/dist/adapters/fetch/index.d.ts

@@ -0,0 +1,42 @@
+//#region src/json/types.d.ts
+type QueryParamValue = string | number | boolean | null | undefined;
+type QueryParams = Record<string, QueryParamValue>;
+//#endregion
+//#region src/http/validate.d.ts
+type ResponseValidator<T> = (value: unknown) => T;
+//#endregion
+//#region src/http/types.d.ts
+interface HTTPFetchConfig<TParams extends object = QueryParams, TResponse = unknown> {
+  signal?: AbortSignal;
+  params?: TParams;
+  headers?: Record<string, string>;
+  validateResponse?: ResponseValidator<TResponse>;
+}
+interface HTTPFetch {
+  get<TResponse, TParams extends object = QueryParams>(route: string, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+  post<TResponse, TBody = unknown, TParams extends object = QueryParams>(route: string, body: TBody, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+  put<TResponse, TBody = unknown, TParams extends object = QueryParams>(route: string, body: TBody, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+  patch<TResponse, TBody = unknown, TParams extends object = QueryParams>(route: string, body: TBody, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+  delete<TResponse, TParams extends object = QueryParams>(route: string, config?: HTTPFetchConfig<TParams, TResponse>): Promise<{
+    data: TResponse;
+  }>;
+}
+//#endregion
+//#region src/adapters/fetch/index.d.ts
+interface FetchAdapterOptions {
+  baseURL?: string;
+  headers?: Record<string, string>;
+  fetch?: typeof fetch;
+}
+declare function createFetchAdapter(options?: FetchAdapterOptions): HTTPFetch;
+//#endregion
+export { FetchAdapterOptions, type HTTPFetch, type HTTPFetchConfig, createFetchAdapter };
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/fetch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/json/types.ts","../../../src/http/validate.ts","../../../src/http/types.ts","../../../src/adapters/fetch/index.ts"],"mappings":";KAUY;KAEA,cAAc,eAAe;;;KCZ7B,kBAAkB,MAAM,mBAAmB;;;UCOtC,gBACf,yBAAyB,aACzB;EAEA,SAAS;EACT,SAAS;EACT,UAAU;EACV,mBAAmB,kBAAkB;;UAGtB;EACf,IAAI,WAAW,yBAAyB,aACtC,eACA,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;EACnB,KAAK,WAAW,iBAAiB,yBAAyB,aACxD,eACA,MAAM,OACN,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;EACnB,IAAI,WAAW,iBAAiB,yBAAyB,aACvD,eACA,MAAM,OACN,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;EACnB,MAAM,WAAW,iBAAiB,yBAAyB,aACzD,eACA,MAAM,OACN,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;EACnB,OAAO,WAAW,yBAAyB,aACzC,eACA,SAAS,gBAAgB,SAAS,aACjC;IAAU,MAAM;;;;;UCnCJ;EACf;EACA,UAAU;EACV,eAAe;;iBAqED,mBACd,UAAS,sBACR"}

package/dist/adapters/fetch/index.js

@@ -0,0 +1,77 @@
+//#region src/json/types.ts
+function isJsonValue(value) {
+	if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return true;
+	if (Array.isArray(value)) return value.every(isJsonValue);
+	if (typeof value === "object" && value !== null) return Object.values(value).every(isJsonValue);
+	return false;
+}
+function parseJson(text) {
+	const parsed = JSON.parse(text);
+	if (!isJsonValue(parsed)) throw new TypeError("JSON text did not parse to a valid JSON value");
+	return parsed;
+}
+//#endregion
+//#region src/http/validate.ts
+var ResponseValidationError = class extends Error {
+	cause;
+	constructor(message, cause) {
+		super(message);
+		this.name = "ResponseValidationError";
+		this.cause = cause;
+	}
+};
+function coerceResponseData(value, validator) {
+	if (validator === void 0) return value;
+	try {
+		return validator(value);
+	} catch (error) {
+		throw new ResponseValidationError("Response validation failed", error);
+	}
+}
+//#endregion
+//#region src/adapters/fetch/index.ts
+function appendQuery(url, params) {
+	if (params === void 0 || Object.keys(params).length === 0) return url;
+	const search = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) search.append(key, String(value));
+	const query = search.toString();
+	if (query.length === 0) return url;
+	return `${url}${url.includes("?") ? "&" : "?"}${query}`;
+}
+function readResponseBody(text) {
+	if (text.length === 0) return;
+	return parseJson(text);
+}
+async function request(method, route, options, body, config) {
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	const url = appendQuery(`${options.baseURL ?? ""}${route}`, config?.params);
+	const headers = {
+		...options.headers,
+		...config?.headers
+	};
+	const init = {
+		headers,
+		method
+	};
+	if (config?.signal !== void 0) init.signal = config.signal;
+	if (body !== void 0) {
+		headers["Content-Type"] ??= "application/json";
+		init.body = JSON.stringify(body);
+	}
+	const response = await fetchImpl(url, init);
+	if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
+	return { data: coerceResponseData(readResponseBody(await response.text()), config?.validateResponse) };
+}
+function createFetchAdapter(options = {}) {
+	return {
+		delete: (route, config) => request("DELETE", route, options, void 0, config),
+		get: (route, config) => request("GET", route, options, void 0, config),
+		patch: (route, body, config) => request("PATCH", route, options, body, config),
+		post: (route, body, config) => request("POST", route, options, body, config),
+		put: (route, body, config) => request("PUT", route, options, body, config)
+	};
+}
+//#endregion
+export { createFetchAdapter };
+
+//# sourceMappingURL=index.js.map

package/dist/adapters/fetch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/json/types.ts","../../../src/http/validate.ts","../../../src/adapters/fetch/index.ts"],"sourcesContent":["export type JsonPrimitive = string | number | boolean | null;\n\nexport interface JsonObject {\n  [key: string]: JsonValue;\n}\n\nexport type JsonArray = Array<JsonValue>;\n\nexport type JsonValue = JsonPrimitive | JsonObject | JsonArray;\n\nexport type QueryParamValue = string | number | boolean | null | undefined;\n\nexport type QueryParams = Record<string, QueryParamValue>;\n\nexport function isJsonPrimitive(value: JsonValue): value is JsonPrimitive {\n  return (\n    value === null ||\n    typeof value === \"string\" ||\n    typeof value === \"number\" ||\n    typeof value === \"boolean\"\n  );\n}\n\nexport function isJsonValue(value: unknown): value is JsonValue {\n  if (\n    value === null ||\n    typeof value === \"string\" ||\n    typeof value === \"number\" ||\n    typeof value === \"boolean\"\n  ) {\n    return true;\n  }\n\n  if (Array.isArray(value)) {\n    return value.every(isJsonValue);\n  }\n\n  if (typeof value === \"object\" && value !== null) {\n    return Object.values(value).every(isJsonValue);\n  }\n\n  return false;\n}\n\nexport function isJsonObject(value: unknown): value is JsonObject {\n  return (\n    isJsonValue(value) &&\n    typeof value === \"object\" &&\n    value !== null &&\n    !Array.isArray(value)\n  );\n}\n\nexport function isJsonArray(value: unknown): value is JsonArray {\n  return Array.isArray(value) && value.every(isJsonValue);\n}\n\nexport function parseJson(text: string): JsonValue {\n  const parsed: unknown = JSON.parse(text);\n  if (!isJsonValue(parsed)) {\n    throw new TypeError(\"JSON text did not parse to a valid JSON value\");\n  }\n  return parsed;\n}\n\nexport function readJsonObject(text: string): JsonObject {\n  const parsed = parseJson(text);\n  if (!isJsonObject(parsed)) {\n    throw new TypeError(\"JSON text did not parse to a JSON object\");\n  }\n  return parsed;\n}\n\nexport function readJsonPrimitives(\n  values: JsonValue | undefined\n): Array<JsonPrimitive> {\n  if (!isJsonArray(values)) {\n    return [];\n  }\n\n  return values.filter(isJsonPrimitive);\n}\n","export type ResponseValidator<T> = (value: unknown) => T;\n\nexport class ResponseValidationError extends Error {\n  override readonly cause: unknown;\n\n  constructor(message: string, cause: unknown) {\n    super(message);\n    this.name = \"ResponseValidationError\";\n    this.cause = cause;\n  }\n}\n\nexport function coerceResponseData<T>(\n  value: unknown,\n  validator?: ResponseValidator<T>\n): T {\n  if (validator === undefined) {\n    return value as T;\n  }\n\n  try {\n    return validator(value);\n  } catch (error) {\n    throw new ResponseValidationError(\"Response validation failed\", error);\n  }\n}\n","import type { JsonValue, QueryParams } from \"../../json/types\";\nimport { parseJson } from \"../../json/types\";\nimport { coerceResponseData } from \"../../http/validate\";\nimport type { HTTPFetch, HTTPFetchConfig } from \"../../http/types\";\n\nexport interface FetchAdapterOptions {\n  baseURL?: string;\n  headers?: Record<string, string>;\n  fetch?: typeof fetch;\n}\n\nfunction appendQuery(url: string, params?: object): string {\n  if (params === undefined || Object.keys(params).length === 0) {\n    return url;\n  }\n\n  const search = new URLSearchParams();\n  for (const [key, value] of Object.entries(params)) {\n    search.append(key, String(value));\n  }\n\n  const query = search.toString();\n  if (query.length === 0) {\n    return url;\n  }\n\n  return `${url}${url.includes(\"?\") ? \"&\" : \"?\"}${query}`;\n}\n\nfunction readResponseBody(text: string): JsonValue | undefined {\n  if (text.length === 0) {\n    return undefined;\n  }\n  return parseJson(text);\n}\n\nasync function request<TResponse, TParams extends object>(\n  method: string,\n  route: string,\n  options: FetchAdapterOptions,\n  body?: unknown,\n  config?: HTTPFetchConfig<TParams, TResponse>\n): Promise<{ data: TResponse }> {\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n  const baseURL = options.baseURL ?? \"\";\n  const url = appendQuery(`${baseURL}${route}`, config?.params);\n\n  const headers: Record<string, string> = {\n    ...options.headers,\n    ...config?.headers,\n  };\n\n  const init: RequestInit = {\n    headers,\n    method,\n  };\n  if (config?.signal !== undefined) {\n    init.signal = config.signal;\n  }\n\n  if (body !== undefined) {\n    headers[\"Content-Type\"] ??= \"application/json\";\n    init.body = JSON.stringify(body);\n  }\n\n  const response = await fetchImpl(url, init);\n  if (!response.ok) {\n    throw new Error(`HTTP ${response.status} ${response.statusText}`);\n  }\n\n  const text = await response.text();\n  const parsed = readResponseBody(text);\n  return {\n    data: coerceResponseData<TResponse>(parsed, config?.validateResponse),\n  };\n}\n\nexport function createFetchAdapter(\n  options: FetchAdapterOptions = {}\n): HTTPFetch {\n  return {\n    delete: <TResponse, TParams extends object = QueryParams>(\n      route: string,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) =>\n      request<TResponse, TParams>(\"DELETE\", route, options, undefined, config),\n    get: <TResponse, TParams extends object = QueryParams>(\n      route: string,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) => request<TResponse, TParams>(\"GET\", route, options, undefined, config),\n    patch: <TResponse, TBody = unknown, TParams extends object = QueryParams>(\n      route: string,\n      body: TBody,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) => request<TResponse, TParams>(\"PATCH\", route, options, body, config),\n    post: <TResponse, TBody = unknown, TParams extends object = QueryParams>(\n      route: string,\n      body: TBody,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) => request<TResponse, TParams>(\"POST\", route, options, body, config),\n    put: <TResponse, TBody = unknown, TParams extends object = QueryParams>(\n      route: string,\n      body: TBody,\n      config?: HTTPFetchConfig<TParams, TResponse>\n    ) => request<TResponse, TParams>(\"PUT\", route, options, body, config),\n  };\n}\n\nexport type { HTTPFetch, HTTPFetchConfig } from \"../../http/types\";\n"],"mappings":";AAuBA,SAAgB,YAAY,OAAoC;CAC9D,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAO,UAAU,YACjB,OAAO,UAAU,WAEjB,OAAO;CAGT,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,MAAM,WAAW;CAGhC,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO,OAAO,OAAO,KAAK,CAAC,CAAC,MAAM,WAAW;CAG/C,OAAO;AACT;AAeA,SAAgB,UAAU,MAAyB;CACjD,MAAM,SAAkB,KAAK,MAAM,IAAI;CACvC,IAAI,CAAC,YAAY,MAAM,GACrB,MAAM,IAAI,UAAU,+CAA+C;CAErE,OAAO;AACT;;;AC7DA,IAAa,0BAAb,cAA6C,MAAM;CACjD;CAEA,YAAY,SAAiB,OAAgB;EAC3C,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,QAAQ;CACf;AACF;AAEA,SAAgB,mBACd,OACA,WACG;CACH,IAAI,cAAc,KAAA,GAChB,OAAO;CAGT,IAAI;EACF,OAAO,UAAU,KAAK;CACxB,SAAS,OAAO;EACd,MAAM,IAAI,wBAAwB,8BAA8B,KAAK;CACvE;AACF;;;ACdA,SAAS,YAAY,KAAa,QAAyB;CACzD,IAAI,WAAW,KAAA,KAAa,OAAO,KAAK,MAAM,CAAC,CAAC,WAAW,GACzD,OAAO;CAGT,MAAM,SAAS,IAAI,gBAAgB;CACnC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,GAC9C,OAAO,OAAO,KAAK,OAAO,KAAK,CAAC;CAGlC,MAAM,QAAQ,OAAO,SAAS;CAC9B,IAAI,MAAM,WAAW,GACnB,OAAO;CAGT,OAAO,GAAG,MAAM,IAAI,SAAS,GAAG,IAAI,MAAM,MAAM;AAClD;AAEA,SAAS,iBAAiB,MAAqC;CAC7D,IAAI,KAAK,WAAW,GAClB;CAEF,OAAO,UAAU,IAAI;AACvB;AAEA,eAAe,QACb,QACA,OACA,SACA,MACA,QAC8B;CAC9B,MAAM,YAAY,QAAQ,SAAS,WAAW;CAE9C,MAAM,MAAM,YAAY,GADR,QAAQ,WAAW,KACE,SAAS,QAAQ,MAAM;CAE5D,MAAM,UAAkC;EACtC,GAAG,QAAQ;EACX,GAAG,QAAQ;CACb;CAEA,MAAM,OAAoB;EACxB;EACA;CACF;CACA,IAAI,QAAQ,WAAW,KAAA,GACrB,KAAK,SAAS,OAAO;CAGvB,IAAI,SAAS,KAAA,GAAW;EACtB,QAAQ,oBAAoB;EAC5B,KAAK,OAAO,KAAK,UAAU,IAAI;CACjC;CAEA,MAAM,WAAW,MAAM,UAAU,KAAK,IAAI;CAC1C,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,MAAM,QAAQ,SAAS,OAAO,GAAG,SAAS,YAAY;CAKlE,OAAO,EACL,MAAM,mBAFO,iBAAiB,MADb,SAAS,KAAK,CAGK,GAAQ,QAAQ,gBAAgB,EACtE;AACF;AAEA,SAAgB,mBACd,UAA+B,CAAC,GACrB;CACX,OAAO;EACL,SACE,OACA,WAEA,QAA4B,UAAU,OAAO,SAAS,KAAA,GAAW,MAAM;EACzE,MACE,OACA,WACG,QAA4B,OAAO,OAAO,SAAS,KAAA,GAAW,MAAM;EACzE,QACE,OACA,MACA,WACG,QAA4B,SAAS,OAAO,SAAS,MAAM,MAAM;EACtE,OACE,OACA,MACA,WACG,QAA4B,QAAQ,OAAO,SAAS,MAAM,MAAM;EACrE,MACE,OACA,MACA,WACG,QAA4B,OAAO,OAAO,SAAS,MAAM,MAAM;CACtE;AACF"}

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+//#region src/cli.d.ts
+interface ParsedArgs {
+  command?: string;
+  /** Populated by the first --source value; kept for init (single-source) compat. */
+  source?: string;
+  /** All --source values collected for multi-source generate. */
+  sources: Array<string>;
+  spec?: string;
+  client?: "axios" | "fetch" | "custom";
+  layout?: "monolith" | "packages";
+  check?: boolean;
+  acceptBase?: boolean;
+  all?: boolean;
+}
+declare function parseArgs(argv: Array<string>): ParsedArgs;
+//#endregion
+export { parseArgs };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","names":[],"sources":["../src/cli.ts"],"mappings":";UASU;EACR;;EAEA;;EAEA,SAAS;EACT;EACA;EACA;EACA;EACA;EACA;;iBAGc,UAAU,MAAM,gBAAgB"}