Api-Geno

TypeScript OpenAPI client generator with runtime Zod validation, neverthrow results, and configurable Axios/Fetch adapters.

✨ Key Features

• Command-line generator: api-geno generate creates a typed client from an OpenAPI JSON file.
• Axios + Fetch adapters: Choose axios or fetch with the --http-adapter option.
• Optional Zod validation: Runtime schemas are generated by default, and can be disabled with --no-zod.
• Functional error handling: Generated requests return neverthrow Result values instead of raw exceptions.
• Config-driven generation: Supports api-geno.config.json alongside CLI flags.
• Flexible output structure: --flat, --split-services, and --emit-only-shapes allow tailored output.
• Formatting support: --format runs biome or falls back to prettier when available.
• Smart regeneration: Keeps a hash file to skip generation when inputs/options are unchanged, with --force to override.
• Auxiliary features: --report generates coverage reporting, --skip-generated-outputs prints generated files to console, and --watch rebuilds on change.

🧭 CLI Usage

bun run build
bun run ./dist/cli.js generate \
  --input api.json \
  --output generated \
  --http-adapter fetch \
  --format \
  --report

Supported flags

• -i, --input <file>: OpenAPI JSON file
• -o, --output <dir>: Output directory
• --http-adapter <adapter>: axios or fetch (default: axios)
• --error-style <style>: class, shape, or both (default: both)
• --emit-only-shapes: Emit only type shapes
• --skip-generated-outputs: Print files instead of writing them
• --force: Force regeneration
• --output-format <fmt>: Output format (ts only)
• --flat: Generate files in a single directory
• --no-zod: Disable Zod schema generation
• --split-services / --no-split-services: Control service file splitting
• --format: Format generated code after generation
• --report: Emit a schema coverage report
• -w, --watch: Watch input/config changes and regenerate

💡 Example config file

Create an api-geno.config.json to reuse common generation options:

{
  "input": "api.json",
  "output": "generated",
  "httpAdapter": "fetch",
  "format": true,
  "report": true
}

📦 Package scripts

| Script | What it does | |--------|-------------| | bun run build | Compile the generator | | bun run gen | Build and generate using api.json | | bun run check | Type-check only | | bun run lint | Run Biome lint | | bun run lint:fix | Autofix lint issues | | bun run format | Format all files | | bun run format:check | Check formatting (CI) | | bun run test | Run tests | | bun run verify | Lint + typecheck + test + build (full local CI) | | bun run release | Create a single bundled CLI binary in release/api-geno |

🧪 Run tests

bun install
bun test

🔧 Build + generate

bun run build
bun run ./dist/cli.js generate -i api.json -o ./generated --force

🤝 Contributing

bun install          # also sets up git hooks via lefthook
bun run verify       # run full check before pushing

Pre-commit hooks run lint and check automatically. Pre-push runs the full verify pipeline.

Use changesets for versioning:

bun run changeset    # describe your change

Note: api-geno is published as a CLI binary via dist/cli.js and also supports api-geno once installed globally or linked.