perf: loading 292 ES API Zod schemas allocates 373 MB of heap

[Kiryous]

Summary

Importing all 292 ES API schemas (src/es/apis.ts) allocates ~373 MB of heap memory. The CLI currently runs as a short-lived process so this doesn't cause OOM, but it's a significant footprint that will grow as more APIs are added and could become a problem if the CLI is used as a long-running process (daemon, language server, agent loop).

For context, the Kibana workflows team hit OOM at 800-1000 MB when loading ~1000 API schemas through Zod. At 373 MB for 292 APIs, the CLI is already at ~47% of that threshold.

Environment

• CLI: 0.1.0-alpha.1 (commit 1b91960)
• Node: v25.6.1
• OS: Darwin 25.4.0 arm64

Repro

node --expose-gc -e '
gc();
const before = process.memoryUsage().heapUsed;
import("./dist/es/apis.js").then(mod => {
  gc();
  const after = process.memoryUsage().heapUsed;
  console.log("Heap before:", (before / 1024 / 1024).toFixed(1), "MB");
  console.log("Heap after:", (after / 1024 / 1024).toFixed(1), "MB");
  console.log("Delta:", ((after - before) / 1024 / 1024).toFixed(1), "MB");
  console.log("API count:", mod.allApis.length);
})
'

Result

Heap before: 2.8 MB
Heap after:  376.2 MB
Delta:       373.4 MB
API count:   292

Additionally, generating JSON Schema output (--help --json) for all APIs produces 22 MB total:

Total JSON Schemas generated: 292
Total JSON Schema bytes:      21,948,227

Why this matters

• The docs chat command (added in feat: add elastic docs commands (search, ask, chat, read) #147) keeps the process alive for interactive sessions — 373 MB baseline for every chat session.
• Zod v4 was found to worsen memory consumption in Kibana (kibana#262948).
• Agent/LLM workflows may run many CLI invocations in sequence; forking 373 MB per invocation adds up.
• Adding more APIs (the ES spec has 400+) will push this higher.

Possible approaches

• Lazy loading: Only instantiate schemas for the command being invoked, not all 292 on startup.
• Schema splitting: Move each API's schema into a separate chunk that's imported on demand.
• Codegen optimization: Investigate whether the schema graph has excessive duplication (shared types like QueryDslQueryContainer may be instantiated multiple times via z.lazy()).

[JoshMock]

Lazy-loading is probably the right move. Doing so at the cli.ts level was a critical perf enhancement to avoid every command having a 10-15s startup time. 😆 This just takes the optimization a level deeper.

[MattDevy]

Dug into this and the downstream fix isn't tractable — the memory floor is in the generated schemas themselves. Filed elastic/elastic-client-generator-js#161 with the full diagnostic.

TL;DR from that issue:

Scenario	Heap delta
schemas/_types.ts alone	226 MB
One leaf API (apis/bulk.ts)	226 MB (transitively loads _global → _types)
Full barrel (292 APIs)	375 MB

So the foundation is a hard 226 MB floor — importing any single API pays the full amount. Per-API cost is only ~0.5 MB on top. That means per-command lazy dispatch in the CLI would save at most ~149 MB (40%), while leaving the 226 MB floor untouched. Not worth the added complexity downstream.

Real-world RSS: elastic --help 68 MB vs. elastic es --help 599 MB — the 9× gap is entirely schema evaluation.

Keeping this issue open as a tracker; the real fix lands in the generator. I'll update here once upstream has a direction.

[axw]

Yesterday I found that elastic stack es ping with a local ES takes ~1s, compared to ~1ms with the equivalent curl command. Claude suggested that most of that time was due to loading the monolithic schema. I can confirm that with this branch, ping is now ~170ms.

[MattDevy]

Yesterday I found that elastic stack es ping with a local ES takes ~1s, compared to ~1ms with the equivalent curl command. Claude suggested that most of that time was due to loading the monolithic schema. I can confirm that with this branch, ping is now ~170ms.

@axw thanks for the feedback! I have a bit more cleanup and cross-repo wiring to do to get #218 ready for review