@openmirai/typeforge

@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
• GitHub: openmirai/typeforge

You own http.ts (the HTTPFetch adapter). Generated files import that adapter — they do not invent axios/fetch calls inline.

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 24+ (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:

{
  "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 for the full command reference.

How the flow works

init  →  source.ts + http.ts  →  resolve spec  →  generate  →  typed callers

1. Init a source

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:

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.

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:

{ "apiRoot": "packages/utils/src/api" }

You can also set "typeforge": { "apiRoot": "..." } in package.json. The JSON file wins.

Monolith (--layout monolith, default):

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)

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 (GitHub Actions OIDC). Do not npm publish from a laptop.

	Value
npm package	@openmirai/typeforge
GitHub repo	openmirai/typeforge
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.

pnpm install
pnpm verify   # format, lint, typecheck, build, coverage

Test layout: test/README.md.