Skip to content

fix(jco): invalid TypeScript types for @bytecodealliance/jco API#1506

Merged
vados-cosmonic merged 2 commits into
bytecodealliance:mainfrom
youngspe:fix-jco-types
May 19, 2026
Merged

fix(jco): invalid TypeScript types for @bytecodealliance/jco API#1506
vados-cosmonic merged 2 commits into
bytecodealliance:mainfrom
youngspe:fix-jco-types

Conversation

@youngspe
Copy link
Copy Markdown
Contributor

@youngspe youngspe commented May 19, 2026

Currently the TypeScript types for @bytecodealliance/jco are broken. There are threeissues:

  1. The api references obj/wasm-tools.js but in npm publish the type declarations are generated before obj/ is populated. This causes types to be emitted as any instead of their actual types. For example:
  • Expected:

    export function metadataAdd(binary: Uint8Array, metadata: tools.ProducersFields): Promise<Uint8Array>;
  • Actual:

    export function metadataAdd(binary: Parameters<any>[0], metadata: Parameters<any>[1]): Promise<ReturnType<any>>;
  1. The parameter and return types specified in the doc comments in src/api.js reference nonexistent exports of obj/wasm-tools.js. For example, Parameters<import('../obj/wasm-tools.js').metadataAdd>[0] effectively resolves to any because there is no type called import('./obj/wasm-tools.js').metadataAdd. This was likely intended to be Parameters<typeof import('../obj/wasm-tools.js').tools.metadataAdd>[0], which resolves to Uint8Array.
  2. src/api.js has relative exports from ./cmd/opt.js etc. but the types for the cmd directory are kept in src while the rest of the types are in types. This means types/api.d.ts tries to reference types/cmd/opt.d.ts but there's no file there so TypeScript can't resolve it. This makes the opt, transpile, and types exports completely untyped.

This change does the following:

  • Modify xtask build .. so that tsc is run after the components referenced by the API are transpiled.
  • Modify packages/jco/tsconfig.json:
    • Change include to just "src" because TypeScript already recursively searches included directories
    • Remove exclude:
      • There's no node_modules or test directories under src/ to exclude from compilation, and exclude won't have an effect on files not referenced by include.
      • Removing src/cmd/** means type declarations for files in src/cmd/ are generated under types/cmd/ so relative imports from types/ work as expected.
      • *.d.ts files don't need to be excluded because tsc doesn't generate any output files for them.
    • Add "rootDir": "src". This is already implied, but ts5.9 gives a deprecation warning because it's required in ts6.0
  • Remove declaration files from src/cmd/ and regenerate types/.
  • Modify packages/jco/src/api.js:
    • Make parameter types explicit and removed the return types as they can be inferred.
    • Add // @ts-check to enable type checking for just that file to ensure that the parameters are consistent with the functions from wasm-tools.js

In case it looks like it from this description, this PR is not AI-generated, I just like over-explaining and making nested lists

@youngspe
Copy link
Copy Markdown
Contributor Author

Hm, just realizing those functions being referenced from '../obj/wasm-tools.js` don't actually exist.

@youngspe
Copy link
Copy Markdown
Contributor Author

Hm, just realizing those functions being referenced from '../obj/wasm-tools.js` don't actually exist.

I made the parameter types in the JSDoc comments for api.js explicit and removed the return types as they can be inferred. I also added // @ts-check to enable type checking for just that file to ensure that the parameters are consistent with the functions from wasm-tools.js

Comment thread packages/jco/src/api.js
vados-cosmonic
vados-cosmonic previously approved these changes May 19, 2026
Copy link
Copy Markdown
Collaborator

@vados-cosmonic vados-cosmonic left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 🚀

Thanks @youngspe for adding this -- let's get the tests running and merge this.

@vados-cosmonic
Copy link
Copy Markdown
Collaborator

One thing I'll do is squash and rename your commits -- since our conventional commits check is failing -- and a fmt.

@vados-cosmonic vados-cosmonic added this pull request to the merge queue May 19, 2026
@github-merge-queue github-merge-queue Bot removed this pull request from the merge queue due to failed status checks May 19, 2026
@vados-cosmonic vados-cosmonic added this pull request to the merge queue May 19, 2026
@github-merge-queue github-merge-queue Bot removed this pull request from the merge queue due to failed status checks May 19, 2026
@vados-cosmonic vados-cosmonic added this pull request to the merge queue May 19, 2026
Merged via the queue into bytecodealliance:main with commit d1bdce8 May 19, 2026
40 checks passed
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