fix(ts-dsl): cache LazyTsDsl result to preserve planner import alias redirects

[awdr74100]

Summary

• LazyTsDsl.toAst() was re-invoking the thunk on every call, creating a fresh node tree each time.
  This discarded the mutations applied by the planner during the analyze() phase — specifically, the
  ~ref redirects that resolve cross-file symbol naming conflicts to their correct import aliases.
• As a result, any generated file that imported a symbol whose name conflicted with a
  locally-defined symbol would call the wrong identifier in the function body (the local symbol), even
  though the import statement correctly used an alias.
• Fixed by caching the thunk result in _result so that analyze() and toAst() operate on the same
  node instance.

Root cause

The planner resolves cross-file naming conflicts by mutating the Ref object held inside a node's
_exprInput:

dependency['~ref'] = aliasedImportSymbol  // e.g. getMembersOptions → getMembersOptions2

LazyTsDsl calls toResult() (which invokes the thunk) in both analyze() and toAst(). Because the
thunk constructs a new DSL node each time, the mutation applied during analyze() is made on an
instance that is immediately thrown away. toAst() then creates a brand-new instance — with the
original, un-mutated ~ref — and renders the wrong identifier.

Example

Given an OpenAPI spec with two endpoints:

Operation ID	Path
getMembers	GET /members
getMembersOptions	GET /members/options

When a TanStack Query plugin generates a query options wrapper for getMembers, it names it
getMembersOptions (pattern: {operationId}Options). This collides with the SDK function also named
getMembersOptions.

The planner resolves this by importing the SDK function under an alias:

// ✅ import statement — correctly aliased by planner
 import {
   getMembersOptions as getMembersOptions2,  // SDK fn for GET /members/options
   ...
 } from '../sdk.gen';

Before this fix — toAst() re-creates the node and loses the alias redirect:

// ❌ wrong: calls the local queryOptions wrapper for getMembers, not the SDK fn
 export const getMembersOptionsOptions = (...) => queryOptions({
   queryFn: async ({ queryKey, signal }) => {
     const { data } = await getMembersOptions({ ... });  // calls wrong function
     return data;
   },
 });

After this fix — the cached node retains the planner's mutation:

  // ✅ correct: calls the SDK fn for GET /members/options
  export const getMembersOptionsOptions = (...) => queryOptions({
    queryFn: async ({ queryKey, signal }) => {
      const { data } = await getMembersOptions2({ ... });
      return data;
    },
  });

Affected plugins

All plugins that use $.lazy to reference cross-file SDK symbols are affected. This includes:

• @tanstack/react-query, @tanstack/vue-query, @tanstack/svelte-query, @tanstack/solid-query,
  @tanstack/preact-query, @tanstack/angular-query-experimental (all share query-core logic)
• @pinia/colada
• swr

Changes

• packages/openapi-ts/src/ts-dsl/utils/lazy.ts — add _result cache to LazyTsDsl.toResult()

Test plan

• Verify generated @tanstack/vue-query.gen.ts calls getMembersOptions2 (the aliased SDK import) in
  getMembersOptionsOptions, not the local getMembersOptions wrapper
• Confirm the import statement still correctly has getMembersOptions as getMembersOptions2
• Confirm operations without naming conflicts are unaffected
• Run pnpm test — all existing snapshots pass

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

@awdr74100 is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 914a5ab

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pullfrog]

TL;DR — LazyTsDsl.toResult() and its Python twin LazyPyDsl.toResult() rebuilt their node tree on every call, so planner ~ref mutations applied during analyze() were discarded before toAst() ran. Caching the thunk's result preserves those mutations, fixing wrong identifiers in generated code when cross-file symbols collide with local ones. This revision adds dedicated unit tests for the cache and an end-to-end snapshot suite covering the TanStack Query queryOptions collision scenario.

Key changes

• Cache the thunk result in LazyTsDsl — Store the first _thunk(ctx) output on _result so analyze() and toAst() share the same node instance, preserving planner-applied alias redirects.
• Mirror the cache into LazyPyDsl — Apply the same _result ??= _thunk(ctx) pattern to the Python DSL so the openapi-python generator benefits from the same fix.
• Add LazyTsDsl unit tests — New lazy.test.ts asserts that toResult() returns the same instance across calls, the thunk runs exactly once, and toAst() reuses the cached node.
• Add regression spec and snapshots — New specs/3.1.x/query-options-name-conflict.yaml plus a @tanstack/react-query test case lock in the getMembersOptions vs getMembersOptions2 aliasing behaviour.

_{Summary ｜ 22 files ｜ 3 commits ｜ base: main ← fix/lazy-tsdsl-result-cache}

Shared node instance across analyze() and toAst()

Before: Each toResult() call invoked _thunk(ctx), producing a fresh node; mutations such as dependency['~ref'] = aliasedImportSymbol applied during analyze() were lost when toAst() later built a new node from scratch.
After: _result caches the first thunk invocation via ??=, so the node mutated by the planner is the same one rendered to AST.

The practical effect: when a TanStack Query wrapper name (e.g. getMembersOptions from operation getMembers) collides with an existing SDK symbol, the planner imports the SDK function under an alias (getMembersOptions as getMembersOptions2). Previously the import line was aliased correctly but the function body still called the un-aliased identifier, invoking the wrong function. With the cache, the rendered call site now uses getMembersOptions2, matching the import.

Why does the mutation get lost without caching?

The planner resolves naming conflicts by mutating the Ref object held inside a node's _exprInput during analyze(). Because the thunk constructs a brand-new DSL node on each invocation, the mutated instance is discarded as soon as analyze() returns. toAst() then calls the thunk again, gets a pristine node with the original ~ref, and renders the un-aliased identifier. Affected plugins are any that use $.lazy for cross-file SDK references — all @tanstack/*-query variants, @pinia/colada, and swr.

packages/openapi-ts/src/ts-dsl/utils/lazy.ts

Parity fix for the Python DSL

Before: LazyPyDsl.toResult() had the same thunk-rebuild bug, so any planner ~ref mutation on a Python node was dropped between analyze() and toAst().
After: _result caches the first _thunk(ctx) result so the Python generator preserves cross-file alias redirects alongside the TypeScript generator.

LazyTsDsl and LazyPyDsl are structural mirrors that both feed the shared @hey-api/codegen-core planner, so the fix is applied identically in both files.

packages/openapi-python/src/py-dsl/utils/lazy.ts

Direct unit coverage for the cache

Before: LazyTsDsl had no tests; its behaviour was exercised only indirectly through downstream generator snapshots.
After: A new lazy.test.ts pins three invariants — toResult() is referentially stable, the thunk runs exactly once, and toAst() consumes the cached node instead of re-invoking the thunk.

These assertions target the precise contract the fix introduces, so an accidental future regression (e.g. reintroducing a per-call thunk invocation) fails fast without needing to regenerate snapshots to notice.

packages/openapi-ts/src/ts-dsl/utils/__tests__/lazy.test.ts

End-to-end regression for the queryOptions collision

Before: No fixture covered the wrapper-vs-SDK naming conflict class (e.g. getMembers + getMembersOptions); existing internal-name-conflict specs only exercised intra-SDK operationId collisions.
After: A new query-options-name-conflict.yaml spec with getMembers and getMembersOptions operations is wired into the @tanstack/react-query v5 test matrix, and its generated snapshots assert the queryFn calls getMembersOptions2.

The snapshot directory includes the full generated output — @tanstack/react-query.gen.ts, sdk.gen.ts, types.gen.ts, and the standard client/core bundle — so any future change that reintroduces the bug surfaces as a visible diff on the queryFn call site.

specs/3.1.x/query-options-name-conflict.yaml · packages/openapi-ts-tests/tanstack-query/v5/test/3.1.x.test.ts · @tanstack/react-query.gen.ts · sdk.gen.ts

  ^{｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 39.55%. Comparing base (1721aa6) to head (914a5ab).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3855      +/-   ##
==========================================
- Coverage   39.58%   39.55%   -0.03%     
==========================================
  Files         532      532              
  Lines       19581    19582       +1     
  Branches     5835     5829       -6     
==========================================
- Hits         7751     7746       -5     
- Misses       9582     9585       +3     
- Partials     2248     2251       +3     

Flag	Coverage Δ
unittests	39.55% <100.00%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pullfrog]

Important

Fix is correct and minimal — verified end-to-end that the planner mutates dependency['~ref'] on the exact node handed back by toResult() during analyze(), and that pre-fix the thunk ran twice per lazy (once under the analyzer, once under the renderer), discarding that mutation. Two follow-ups before merge:

1. LazyPyDsl has the same bug. packages/openapi-python/src/py-dsl/utils/lazy.ts is a structural mirror of LazyTsDsl without the cache — its toResult() still returns this._thunk(ctx) fresh on every call. If the Python codegen hits the same planner ~ref rewrite path (which it does via the shared @hey-api/codegen-core planner), it will reproduce the same wrong-identifier symptom. Please apply the same two-line fix there.
2. No regression coverage. The existing internal-name-conflict fixture only exercises intra-SDK collisions (create, create_, create__) and does not trigger the bug — no snapshot in the repo currently contains the broken output, which means reverting this fix leaves every test passing. A minimal spec with two operations whose IDs produce the op + {op}Options collision (e.g. getMembers + getMembersOptions) wired through packages/openapi-ts-tests/tanstack-query/v5/test/3.1.x.test.ts would pin the user-visible behavior, and a tiny unit test in packages/openapi-ts/src/ts-dsl/utils/__tests__/ asserting lazy.toResult() === lazy.toResult() and thunk-invocation count would pin the caching contract itself.

Neither is strictly blocking; both would meaningfully harden the fix against future refactors.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ 𝕏}

[pullfrog]

The Python sibling packages/openapi-python/src/py-dsl/utils/lazy.ts:25-27 has the identical shape without the cache and will reproduce the same wrong-identifier symptom whenever the shared planner performs a ~ref rewrite on a LazyPyDsl-produced node. Consider applying the same two-line fix there in this PR.

[pullfrog]

The caching contract introduced here has no unit test, and no existing snapshot exercises the bug the PR fixes (the internal-name-conflict fixture only covers intra-SDK collisions). A ~15-line test in packages/openapi-ts/src/ts-dsl/utils/__tests__/ that asserts lazy.toResult() === lazy.toResult() and counts thunk invocations would prevent a future refactor from silently reintroducing the bug — the contract is purely local to this 35-line file.

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

npm i https://pkg.pr.new/@hey-api/codegen-core@3855

@hey-api/json-schema-ref-parser

npm i https://pkg.pr.new/@hey-api/json-schema-ref-parser@3855

@hey-api/nuxt

npm i https://pkg.pr.new/@hey-api/nuxt@3855

@hey-api/openapi-ts

npm i https://pkg.pr.new/@hey-api/openapi-ts@3855

@hey-api/shared

npm i https://pkg.pr.new/@hey-api/shared@3855

@hey-api/spec-types

npm i https://pkg.pr.new/@hey-api/spec-types@3855

@hey-api/types

npm i https://pkg.pr.new/@hey-api/types@3855

@hey-api/vite-plugin

npm i https://pkg.pr.new/@hey-api/vite-plugin@3855

commit: 914a5ab

[mrlubos]

@awdr74100 Can you add tests so I can reproduce?

[awdr74100]

@mrlubos

Added, please confirm again, thank you.

[mrlubos]

@pullfrog review now

[pullfrog]

Reviewed — no issues found.

Correctness, planner pass counts, clone() interaction, ctx capture, and every existing $.lazy(...) call site were verified. The unit tests pin the exact instance identity the planner's ~ref mutation relies on (first test + third test together would have failed pre-fix), and the new query-options-name-conflict snapshot is a genuine regression guard — @tanstack/react-query.gen.ts line 6 imports getMembersOptions as getMembersOptions2 and line 61 threads that alias through getMembersOptionsOptions.

One optional observation, not blocking: LazyPyDsl has no consumers in packages/openapi-python yet (it's only exposed via $.lazy in the factory), so shipping the mirror fix without a parallel unit test is defensible — but once py-dsl gains a real $.lazy call site, adding a unit test under the existing packages/openapi-python/src/py-dsl/utils/__tests__/ directory would keep the two DSLs symmetric.

  ^{｜ View workflow run ｜ 𝕏}