@qvac/sdk 0.15.0: model constants fail to typecheck under moduleResolution nodenext (runtime OK)

[patilswapnilv]

SDK version: @qvac/sdk 0.15.0 · Runtime: Node 24.x · OS: macOS Darwin arm64

Summary: Bundled model constants (e.g. LLAMA_3_2_1B_INST_Q4_0) exist at runtime but tsc reports TS2305 under moduleResolution: "nodenext".

Steps to reproduce:

1. Fresh package with "type": "module" and @qvac/sdk@0.15.0.
2. tsconfig.json:

   {
     "compilerOptions": {
       "module": "nodenext",
       "moduleResolution": "nodenext",
       "strict": true,
       "skipLibCheck": true,
       "noEmit": true
     }
   }

3. Typecheck:

   import { LLAMA_3_2_1B_INST_Q4_0 } from "@qvac/sdk"; // TS2305

4. Runtime (same install) succeeds:

   node --input-type=module -e "import('@qvac/sdk/models').then(m => \
     console.log('LLAMA_3_2_1B_INST_Q4_0' in m))"
   # -> true  (448 exports present)

Same failure for @qvac/sdk/models and other constants (GTE_LARGE_FP16, BCI_EMBEDDER, …).

Expected: Constants type-resolve the way docs/JSDoc show the import.

Actual:

error TS2305: Module '"@qvac/sdk"' has no exported member 'LLAMA_3_2_1B_INST_Q4_0'.

Runtime still works.

Likely cause: The registry barrel re-exports via extensionless export * from './models' in the shipped .d.ts. nodenext ESM type resolution does not follow that; moduleResolution: "bundler" does (and matches tsx/esbuild at runtime).

Suggested fix / workaround:

• Fix: Ship .d.ts re-exports with explicit .js extensions (or a types entry nodenext can follow) so Node-ESM projects typecheck out of the box.
• Workaround: Use moduleResolution: "bundler" (what qvac-cookbook uses in tsconfig.base.json).

Context: Hit this while building recipe 01 (completion streaming) for qvac-cookbook. Highest-signal types/runtime gap found while consuming the SDK as a Node-ESM TypeScript app.

[victorchimakanu]

Confirmed, and the cause sits one level below the barrel file.

The exports map is not the problem. ./models carries an explicit types condition pointing at ./dist/models/registry/index.d.ts, which is what nodenext wants. The break happens after tsc runs.

The build is tsc followed by scripts/resolve-aliases.mjs, a post-compile pass that walks dist and adds the file extensions Node ESM needs. Inside its fixDirectoryImports step it chooses the extension like this:

const extension = targetExtension === '.d.ts' ? '' : '.js'

A .js file gets .js appended. A .d.ts file gets nothing. Both halves are visible in the shipped package:

dist/index.js     export * from "./models/registry/index.js";
dist/index.d.ts   export * from "./models/registry/index";

Runtime resolves because that specifier is complete. nodenext type resolution does not follow the extensionless one, so the star re-export contributes no members and every model constant reports TS2305. moduleResolution: "bundler" accepts the extensionless form, which is why your workaround holds.

The same thing repeats one hop down, which is why the subpath import fails too even though its exports entry is correct:

dist/models/registry/index.d.ts   export * from "./models";

Two things worth flagging beyond what you hit. First, this is not specific to the model constants. That rewrite runs over every .d.ts in dist, so deep type resolution under nodenext is affected the same way throughout the package. Second, the fix belongs in the build script rather than in source, since index.ts is written extensionless on purpose and tsc preserves what it is given.

The change is to emit .js for declaration files too. TypeScript expects the .js specifier inside a .d.ts and maps it to the sibling .d.ts, so writing ./models/registry/index.js in index.d.ts is correct and fixes nodenext without changing the runtime output.

Raising this with the SDK team.

[localhost41]

Reproduced this on current main and prepared a surgical fix plus regression coverage. The resolver now emits runtime .js specifiers for internal references in declaration output, and the test verifies both the rewritten declarations and an actual tsc pass under moduleResolution: "NodeNext".

Local validation completed:

• focused resolver regression: pass
• SDK typecheck: pass
• full SDK build (lint, tsc, alias rewrite): pass

I am preparing the upstream PR now.

[victorchimakanu]

Any update on the PR? Happy to take a look once you open it.

[localhost41]

Thanks for following up — opened it here: #3381

The fix is in the post-build resolver, with a regression test that runs an actual NodeNext typecheck against both SDK entry points. I also verified the generated tarball in a clean Node 24 project. Appreciate you taking a look.

[victorchimakanu]

PR #3381 is now open with the fix — updates the post-build alias resolver to emit .js specifiers on declaration imports, not just runtime imports, so moduleResolution: "NodeNext" can follow the re-export chain. Should unblock your tsconfig setup once it merges. #3381