Hey API Builders

Hey API integration for the schema-independent Mimlet toolkit. This 3.0.0-alpha.2 line is a major-version migration on the next channel. The stable v2 line remains available separately.

The plugin discovers generated model, request and response factories from @hey-api/openapi-ts, then emits named fluent classes backed by the shared @mimlet/core runtime. Hey API and Faker are not dependencies of the neutral runtime itself.

Installation and generation

Use matching plugin and core versions. See Getting started for current registry availability, or build and install the workspace tarballs. The generated client requires the matching core runtime plus Faker. The verified generation toolchain is Hey API 0.99.0, Faker 10.5.0 and TypeScript 6.0.3. Runtime Node support starts at 22.18.0.

import { defineConfig } from '@hey-api/openapi-ts';
import { defineConfig as builders } from 'hey-api-builders';

export default defineConfig({
  input: './openapi.json',
  output: './generated',
  plugins: [
    '@hey-api/typescript',
    '@faker-js/faker',
    builders({
      definitions: true,
      requests: true,
      responses: true,
    }),
  ],
});

After generation, ordinary object models retain their familiar API:

const user = new UserBuilder().withEmail('ada@example.com').build();

Category settings (definitions, requests, responses) accept booleans, naming templates/functions, or { enabled, case, name }. Category-specific casing overrides the shared case. includeInEntry and the vendor's plugin hooks remain available. runtimeModule changes the generated runtime import specifier for controlled package layouts; it does not select a second runtime implementation or fetch that module during emission.

Migration from v2

Generated clients must install the matching @mimlet/core runtime. Regenerate clients with the upgraded plugin and keep that generated diff in the consumer migration. Do not silently release these changes as a v2 patch.

Builders retain constructor patches, with, transform, build, buildList and generated property helpers for ordinary records. Fluent subclass types are retained after configuration. Fresh per-build overrides, whole replacements, optional omission, async transforms/builds, and operation inspection now share the canonical runtime.

Object-union transitions require complete replacement rather than a partial discriminant patch. Record/non-record transitions are explicit. Lists have the core's default 10,000-item allocation budget. All patches run before transforms. Async chains retain property helpers but do not expose synchronous build methods in TypeScript. Native Date/Map values are not spread into plain objects.

The repository's migration guide explains these contracts. The archived v2 guide is retained only as historical configuration/reference documentation, not current installation advice.

Verification

Real Swagger 2, OpenAPI 3.0 and OpenAPI 3.1 fixtures are generated, compiled and executed. Negative declaration cases test incorrect properties, incomplete union transitions and async capability changes. A clean packed consumer installs the actual core/plugin tarballs, runs the real generator, compiles the generated NodeNext client, and imports its emitted ESM without source aliases.