jskits/openapi-chain: Kind-safe OpenAPI shopper for complicated and huge APIs. Requests observe the doc’s parameter types, media varieties and encodings precisely. Fluent paths, scoped CLI era and an openapi-fetch adapter. · GitHub

openapi-chain compiles the serialization guidelines an OpenAPI doc declares (parameter type,
explode, allowReserved and content material, request media varieties, and type and multipart Encoding
Objects) and applies them to each request. A build-time CLI generates varieties and metadata scoped to
the paths you name, so giant paperwork keep reasonably priced to type-check and to ship. Calls use a fluent
path API with no generated endpoint code and no runtime dependencies.

The pnpm monorepo incorporates three publishable packages: openapi-chain,
@openapi-chain/cli, and @openapi-chain/question. The runtime
retains its present bundle identify and entry factors. See the
bundle migration information for CLI and question import adjustments and launch
availability.

The primary request under makes use of the Objects schema. Your chain follows
your individual schema: static path segments turn out to be properties, {parameters} turn out to be operate calls, and
HTTP strategies turn out to be request capabilities.

• Actual wire serialization: the strict shopper sends what the doc specifies and rejects
  representations it can not encode as an alternative of guessing. The
  wire comparability executes 20 declarations by each purchasers:
  openapi-fetch 0.17.0 sends a request with completely different values, media kind or lacking parameters in 16
  of them, and differs solely in percent-encoding or listing spacing in 3 extra.
• Scoped era for big paperwork: one CLI config produces full declarations, a path scope
  and matching runtime metadata. On the pinned GitHub REST doc, scoping a 40-operation client
  diminished openapi-chain’s TypeScript 7 examine time from 0.49 s to 0.045 s
  (real-schema measurements).
• Typed requests and responses: infer parameters, request media varieties and status-correlated
  outcomes from the chosen operation.
• Preserve openapi-fetch if you happen to already use it: openapi-chain/openapi-fetch applies the identical
  serialization to an present openapi-fetch shopper
  (adapter information).
• Small schema-free core: the default shopper has a 3.5 KiB gzip finances, enforced by a
  reproducible measurement examine; its bundle measurement and per-request overhead are
  in the identical vary as openapi-fetch
  (shopper comparability).
• Customizable requests: operation-typed extensions and Fetch-compatible transports help
  application-specific serialization, authentication and parsing.

Select the strict shopper when your doc declares non-default parameter types, parameter
content material, cookie parameters, non-JSON media varieties or type and multipart encoding, and the server
is dependent upon them. Select the CLI’s scoped era when a big doc makes type-checking or
metadata supply costly. In case your API solely makes use of JSON our bodies and default parameter types,
openapi-fetch and openapi-chain’s core are comparable in measurement and velocity; choose the decision type you
choose. With out scoping, openapi-chain’s fluent varieties price extra to examine than openapi-fetch’s on the
measured GitHub and Stripe paperwork.

For a printed launch with this API:

pnpm add openapi-chain
pnpm add -D @openapi-chain/cli

Save the Objects doc as openapi.json, then create openapi-chain.config.json:

{
  "schema": "./openapi.json",
  "outDir": "./src/generated/api",
  "paths": ["/items/{id}"]
}

Generate varieties and metadata collectively:

pnpm exec openapi-chain generate
pnpm exec openapi-chain generate --check

In src/shopper.ts, use the generated scope and metadata for the primary request:

import { createStrictClient } from 'openapi-chain/strict';
import { metadata } from './generated/api/metadata.js';
import kind { ScopedPaths } from './generated/api/scope.js';

const api = createStrictClient<ScopedPaths>({
  baseUrl: 'https://api.instance.com',
  metadata,
});
const merchandise = await api.objects('42').get();
console.log(merchandise.identify);

Substitute the instance URL together with your service. The minimal supported software compiler is TypeScript
6.0.3; set up it in a brand new software if TypeScript is just not already current. CI pins 6.0.3 and
7.0.2. TypeScript 7.0.2 is really helpful for big schemas and editor responsiveness. The CLI
privately installs TypeScript 5.9.3 for era, so this path wants no generator peer override.
See compiler compatibility and
path scoping.

These docs describe the present supply API. The supply manifests present the checkout variations:
runtime, CLI, and
question adapter. An put in npm launch could expose a special API.
To do that precise implementation, observe
the native tarball client examine. Era
produces declarations and metadata, not endpoint shopper code.

The bundle exports ESM and CommonJS. Its Node.js engine vary is
^22.22.1 || ^24.11.0 || >=26.0.0. Browser use requires commonplace Fetch APIs and a bundler or ESM
setup; Chromium has an integration suite. Allow TypeScript strict mode and embody DOM varieties. See
setup and compatibility.

Core requires an specific contentType every time a physique is provided. Strict can infer a single
declared concrete media kind and implements extra serialization guidelines. Each expose the identical
fluent path API and operation-local extensions. The programmatic compiler stays out there for
handbook workflows and OpenAPI 3.2 metadata; the official CLI at the moment generates OpenAPI 3.0/3.1
varieties and metadata. See the help matrix earlier than selecting serialization
conduct.

The generated strict shopper above retains the doc, CLI and compiler out of browser bundles. For
giant schemas, observe the single-scope workflow.

For an present core software, observe the migration information and evaluate
consultant requests earlier than switching. Core can not detect lacking serialization guidelines from erased
varieties; HTTP 200 is just not proof of an accurate filter.

Generate paths and metadata from the identical schema revision. Strict checks request construction and
supported wire encodings; it’s not a JSON Schema validator. Response validation, authentication
and retries are software obligations.

By default, calls return parsed success knowledge and throw HttpError for non-2xx responses. Use
throwOnError: false to obtain a typed consequence as an alternative:

import { createStrictClient } from 'openapi-chain/strict';
import { metadata } from './generated/api/metadata.js';
import kind { ScopedPaths } from './generated/api/scope.js';

const api = createStrictClient<ScopedPaths>({
  baseUrl: 'https://api.instance.com',
  metadata,
  throwOnError: false,
});

attempt {
  const consequence = await api.objects('42').get();
  if (consequence.okay) console.log(consequence.knowledge.identify);
  else console.error(consequence.standing, consequence.knowledge.error);
} catch (error) {
  // Community, cancellation, serialization and parsing failures nonetheless reject.
  console.error(error);
}

Response varieties assume the server follows the schema. For runtime validation, binary knowledge or
streaming, use a response extension. Core defaults to JSON/textual content parsing;
strict additionally returns ArrayBuffer for different media. See the complete
response contract.

Begin with CONTRIBUTING.md. Report bugs or request options in
GitHub Points; embody the entry level, bundle
model and a minimal schema. Report vulnerabilities by the safety course of.

The separate @openapi-chain/cli bundle gives the openapi-chain generate command for native
OpenAPI 3.0/3.1 JSON/YAML paperwork. One config produces full kind declarations, scoped shopper
varieties, chosen runtime metadata and a provenance manifest. generate --check detects drift with out
writing recordsdata.

See the CLI information and runnable scoped instance. CLI
dependencies stay separate from the runtime bundle and browser bundles.

MIT