Skip to content

perf: 20–35× faster generation, input immutability, benchmark / usage / skills docs pages - #3

Merged
hunghg255 merged 9 commits into
mainfrom
claude/upbeat-brown-xyue6m
Sep 25, 2026
Merged

hunghg255 merged 9 commits into
mainfrom
claude/upbeat-brown-xyue6m

Conversation

@hunghg255

Copy link
Copy Markdown
Owner

Summary

Performance (no change to generated output)

  • Cache compiled Eta templates and included template contents (keyed by value).
  • Load typescript lazily.
  • Replace lodash-es with es-toolkit. Stop deep-merging documents into the config.
  • Remove O(routes × components) lookups and other redundant work.
  • Format modular output files concurrently.
  • Never change the input document, and stop deep-copying it:
    • parse results live in a ParsedSchemaCache (WeakMap) instead of $parsed on the schema;
    • fixes (resolver, fixSwaggerSchema, discriminator mapping, items without type) are copy-on-write;
    • the input is still deep-copied when custom code is configured (hasCustomSchemaCode: hooks, schemaParsers, templates, extraTemplates, codeGenConstructs, primitiveTypeConstructs).

Safety net

  • Output identity was checked by hashing 27 option combinations and by recording all 168 generations in the test suite: 0 diffs against the previous code.
  • New tests/core/input-immutability.test.ts: generates from deep-frozen inputs with 4 documents × 4 option sets, and checks the hooks case.
  • New npm run test:immutability (STA_FREEZE=1): runs the whole suite with frozen inputs. Added to CI.

Benchmark vs acacode/swagger-typescript-api 13.13.0 (npm run bench:compare)

Median time with a warm process:

Scenario es original Speedup
petstore default 7.8 ms 74.2 ms 9.5×
medium default 107 ms 2182 ms 20.4×
large default 494 ms 11302 ms 22.9×
large modular 426 ms 14854 ms 34.9×
large extract 1033 ms 27309 ms 26.4×

Peak memory is 2–3× lower. Every measurement runs in its own process. Results are stored in docs/lib/benchmark/results.json.

Docs site

  • /benchmark: chart (generation / cold run / memory), results table, method, caveats, and environment.
  • /usage: how to use the generated client (base URL, headers, auth, passing an instance, errors, cancellation, modular output), with type-checked snippets.
  • /skills: introduces the agent skill, with links.
  • Header navigation updated; README gets a Performance section.

Agent skill

  • skills/swagger-typescript-api-es: SKILL.md and references rewritten for the current behaviour; new references/usage.md.

Test plan

  • npm test: 852 tests pass
  • npm run test:immutability passes
  • npm run typecheck, npm run lint, npm run fmt:check, npm run build
  • docs: tsc, 184 unit tests, next build, 34 Playwright e2e tests

🤖 Generated with Claude Code

https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3


Generated by Claude Code

Eta.render() recompiled the template on every call (once per route, model and
include), which dominated generation time. Compile each template source once and
reuse the function. ~2.4x faster on a 1500 schemas / 3000 operations spec
(4.7s -> 2.0s), byte-identical output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
- typescript is imported only when toJS is used (was ~400ms at startup)
- included template files are read once per template paths
- fix: explicit type for the compiled template cache (d.ts build failed)
- npm run bench: benchmark of the built package on small / medium / large specs
- tests for the caches, lazy typescript and cache isolation between generations

CLI on a small spec: ~800ms -> ~400ms; 1500 schemas / 3000 operations:
~3.4s -> ~2.1s. Output unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
…into the config

- es-toolkit/compat for lodash semantics (utils._ in templates keeps the same
  functions), core es-toolkit cloneDeep for whole documents
- config.update replaces spec / swaggerSchema / originalSchema by reference
  instead of deep-merging them, and the no-op onInit update is skipped
  (each copied the whole schema)
- validate that paths / components / definitions are objects: the error for an
  invalid document relied on a lodash merge quirk
- tests: update semantics, onInit, input spec not mutated, document validation

~15% faster generation of a 1500 schemas / 3000 operations spec in-process,
~20% on a 300 / 600 one; byte-identical output on 27 spec / option combinations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
- index parsed components once per route parsing instead of scanning (and
  formatting the name of) every component for each request / response type:
  3.4M -> 22k formatName calls on a 1500 schemas / 3000 operations spec
- Map / Set lookups for component $refs and reserved names (were linear scans)
- memoize pascalCase / internalCase, pool random bytes for route ids
- don't deep-copy a document the resolver parsed itself (file / URL)
- tests: file vs spec output equality, index consistency when internals are
  changed from outside, id format

In-process generation of the large spec: 1.5s -> 0.7s; CLI 2.2s -> 1.3s.
Byte-identical output on 27 spec / option combinations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
Templates are still rendered one after another (a render can set flags read
by later ones), only the async formatting of the files runs concurrently.
~16% faster modular generation of a 1500 schemas / 3000 operations spec,
byte-identical output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
The parser cached its results on the schema objects (`schema.$parsed`) and
fixed documents in place, so every document had to be deep-copied (resolver,
original schema, schema walker).

- parse results live in ParsedSchemaCache (WeakMap). Copies of schemas carry
  the parse result of their source (inherit / cloneDeep), exactly as the
  enumerable $parsed property was copied, so the output is unchanged
- the fixes are applied to copies: items without type, discriminator mapping,
  default info, swagger 2 paths, fixSwaggerSchema consumes / produces / params
- documents are deep-copied only when custom code (hooks, schema parsers,
  templates, type constructs) could change them (config.hasCustomSchemaCode)
- $parsed removed from the SchemaObject type

Safety net: byte-identical output for all 168 spec / option combinations of the
test suite (recorded before / after) and 27 fixture combinations; new
input-immutability tests with deep-frozen documents; npm run test:immutability
runs the whole suite with frozen inputs (added to CI).

~25% faster in-process generation of a large spec, ~14% faster CLI run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
…nerated client usage

- SKILL.md: triggers, install, quick start, gotchas (CLI values, precedence,
  schema source, undici download, optional body/query params, encoding, oxfmt)
- references/options.md: every option with defaults, hooks with signatures,
  CLI flag table, exported API
- references/patterns.md: 11 recipes
- references/usage.md (new): fetch / axios / singleHttpClient / modular client usage

All TypeScript snippets type-check (strict) against clients generated from the
petstore fixture.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
- bench/compare: installs swagger-typescript-api (13.13.0) in its own folder and
  runs both libraries on the same documents and options (output: false), each
  measurement in a separate process: warm generation (median), cold run
  (import + one generation), peak RSS, output size; npm run bench:compare
- /benchmark page: headline tiles, per-document chart (generation / cold run /
  memory) with tooltips and validated colours, full results table, method,
  caveats, environment and how to reproduce
- README: Performance section with the results

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
- /usage: create the client (fetch / axios / own axios instance), call endpoints,
  headers and auth (injectHeaders, securityWorker + setSecurityData, secure
  routes), shared HttpClient, modular output, errors, cancellation, files,
  customFetch, React Query / SWR, Node.js, typing tips; fetch / axios tabs;
  every snippet type-checked against generated clients
- /skills: what the agent skill is and covers, install (npx skills add or
  manual), example prompts, file list and SKILL.md preview read at build time
- navigation: Docs, Usage, Playground, Benchmark, Skills (header, footer, links
  from the docs and landing pages); e2e tests for both pages

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NH5YqLdEWZQ4vnZ1Hdq8L3
@vercel

vercel Bot commented Sep 25, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
swagger-typescript-api-es Ready Ready Preview Sep 25, 2026 2:37am UTC

@hunghg255
hunghg255 merged commit f71b8e4 into main Sep 25, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
Preview — f0bf017a Deployed Sep 25, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants