Skip to content

feat: types for h5p-verify, h5p-normalize and h5p-embed, and the player's under nodenext - #66

Merged
alekswebnet merged 3 commits into
mainfrom
fix/pack-refresh-hash-and-inputs
Oct 21, 2026
Merged

alekswebnet merged 3 commits into
mainfrom
fix/pack-refresh-hash-and-inputs

Conversation

@alekswebnet

Copy link
Copy Markdown
Contributor

Closes #60.

#65 was stacked on #61 and merged into #61's branch, fix/pack-refresh-hash-and-inputs, an hour after #61 itself had gone into main. GitHub did not retarget it, because the branch was still there. This PR brings the two commits #65 added on top of that branch to main:

The first is described in full in #65. Below is the second.

The player's declarations under nodenext

The problem. The player's types/ imported its sibling files without an extension ('./shared/protocol').

  • tsc copies an import specifier into the declarations as written.
  • node16 and nodenext resolution only follow a relative import that names its file.
  • So for a caller on those settings, everything reached through those imports was any with skipLibCheck, and an error without it. That includes PlayerErrorDetail['code'], missingLibraries and ReadyDetail['source'].
  • That affects the player's own users, and the verifier's and embed's new types, which import the player's.
  • Under bundler resolution, everything was typed.

The fix. The player's relative imports now name their file ('./shared/protocol.js'), as cmi5's already do.

  • The change is mechanical: 125 specifiers in 30 files, plus the one sync-h5p-assets writes into the generated pack-index.ts.
  • Vite, esbuild and Vitest resolve ./x.js to the x.ts beside it, so the bundles are the same code:
Bundle Built before and after
h5p-sw.js, h5p-sw-mount.js byte-identical
h5p-player.js, h5p-jobs.js identical once the minifier's short names are masked; the same size

The short names moved because esbuild picks them by character frequency in the source, and the added .js strings shift it.

The check. tests/package-types.ts imports the player by its own name and is compiled by tsconfig.consumer.json, now part of the player's pnpm typecheck.

  • It uses nodenext with skipLibCheck off, so a declaration that imports something a caller can't resolve is an error.
  • skipDefaultLibCheck is on, because the DOM and WebWorker libs clash when checked together.
  • It expects four type errors with @ts-expect-error, which go missing if those types become any.
  • It is kept out of tsconfig.test.json, where the source's H5PPlayerElement would meet the declarations' one.
  • Before the fix, it failed with the missing expected errors and "Relative import paths need explicit file extensions". After the fix, it passes.

Testing

arethetypeswrong 0.18.5 on the packed player:

Resolution Extensionless, as 1.1.0 ships With .js
node16, ESM caller 🥴 internal resolution error 🟢
bundler 🟢 🟢

The rest of its output is the same before and after: ./sw doesn't resolve under node10, which reads no exports, and CommonJS callers can only use a dynamic import, as with any ESM-only package.

  • pnpm typecheck passes across the repo, and pnpm test:unit passes in every package.
  • A full pnpm test passed everything except one verifier test, "fails a package without its libraries". It hung past its 120 s bound in that run and passed when run alone, in 5 s. The player it drives is the same code before and after, so this change isn't the cause. CI here runs it again.

Release

🤖 Generated with Claude Code

alekswebnet and others added 3 commits October 21, 2026 20:06
…h5p-embed

The three command packages document a JavaScript API that
docs/compatibility.md covers, and shipped no declarations: a TypeScript
caller got `any`, or TS7016 under strict.

- checkJs over each package's sources, and the 176 errors it found fixed
  in JSDoc (verify 75, embed 95, normalize 6): types only, but for one
  condition made explicit in verify's contentChanges and a JSDoc comment
  the normalizer had above the wrong function.
- Declarations generated from the JSDoc at pack time and in typecheck
  (`pnpm types`, into types/, not in git), named by a `types` condition
  on each exports entry. Generated, not hand-written: the player's one
  hand-written .d.mts drifted.
- Only the documented API: the helpers each entry exports for its tests
  are @internal and stripped. Every top-level @typedef is exported, so
  the types only the code needs stay inline or local.
- VerifyReport types report.json field by field; the error, state and
  refreshed libraries come from the player's own types. startEmbed's
  pack and runtime are the element's property types.
- tests/package-types.ts in each imports the package by its name and is
  type-checked; it cannot pass without the generated declarations.

Closes #60.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… NodeNext resolution

- Updated import statements across multiple files to include `.js` extensions, ensuring compatibility with NodeNext module resolution.
- Added `tests/package-types.ts` to verify the package's TypeScript declarations as seen by a caller under NodeNext.
- Modified `tsconfig.consumer.json` to configure TypeScript for consumer testing, ensuring strict type checking without skipping library checks.
feat: types for the JavaScript APIs of h5p-verify, h5p-normalize and h5p-embed
@alekswebnet
alekswebnet merged commit 94ca901 into main Oct 21, 2026
8 checks passed
@alekswebnet
alekswebnet deleted the fix/pack-refresh-hash-and-inputs branch October 21, 2026 18:54
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.

Types for the JavaScript APIs of h5p-verify, h5p-normalize and h5p-embed

1 participant