Skip to content

feat: types for the JavaScript APIs of h5p-verify, h5p-normalize and h5p-embed - #65

Merged
alekswebnet merged 2 commits into
fix/pack-refresh-hash-and-inputsfrom
feat/command-package-types
Oct 21, 2026
Merged

alekswebnet merged 2 commits into
fix/pack-refresh-hash-and-inputsfrom
feat/command-package-types

Conversation

@alekswebnet

Copy link
Copy Markdown
Contributor

Closes #60.

Stacked on #61, which edits two of the same files (verify.mjs, the embed's build.mjs). Merge #61 first. When its branch is deleted, GitHub moves this PR onto main, and the diff below then shows only this change.

The verifier, the normalizer and the embed package document a JavaScript API that docs/compatibility.md covers, but they shipped no declarations. A TypeScript caller got any, or error TS7016 under strict. Each package now ships declarations generated from its JSDoc.

Changes

Checked JSDoc (each package's tsconfig.json)

  • checkJs over lib/, and the embed's site/embed.js, found 176 errors: verify 75, embed 95, normalize 6.
  • All are fixed in JSDoc, with two exceptions:
    • In verify's contentChanges, Array.isArray(b) is now explicit beside Array.isArray(a). The arrayness was already checked equal one line above, so behaviour is unchanged.
    • In the normalizer, a @param comment sat above the wrong function (storedMeta instead of copyRaw); it is moved.

Generated declarations (tsconfig.types.json, pnpm types, exports)

  • pnpm types writes the entries' declarations into types/, which is not in git. It deletes the folder first, since tsc never removes a stale declaration. typecheck and prepack both run it.
  • Each exports entry names the declarations under a types condition, and files includes types/.
  • Generated rather than hand-written, because the player's one hand-written .d.mts drifted from its source.

Only the documented API

  • The helpers each entry exports for its tests are marked @internal and stripped. In the verifier that's contentChanges; in the normalizer, targetFormOf, plainRelativeName and orderEntries; in the embed, parseOrigin, parseOrigins, parseDefaultLibraries and contentSecurityPolicy.
  • With TypeScript 7, @internal on a @typedef doesn't strip it: every top-level typedef is published. Worse, its comment counts as part of the next declaration's comments, so an @internal typedef above a public function dropped the function instead. So the types only the code needs are inline, derived (ReturnType<typeof headerRules>), or declared inside the function. AGENTS.md records this.

What callers get

  • verify: verifyPackage(options: VerifyOptions): Promise<VerifyReport>, summarize(report: VerifyReport) and VerifyError. VerifyReport types report.json field by field, from the code and page.html. Its error codes, state and refreshed libraries are the player's own types.
  • normalize: normalizeArchive() returning Report, plus EntryResult, TargetForm, formatBytes() and archiveFingerprint().
  • embed: buildSite() returning BuiltSite, and EmbedError. From ./embed.js, startEmbed(), whose pack and runtime options are the element's property types.
  • VerifyError and EmbedError are public, since callers catch them. Neither was named in docs/compatibility.md before.

Docs

  • docs/compatibility.md covers "their types" for the three packages, as it already did for cmi5. VerifyReport gains fields the same way report.json does.
  • One line in each README.

Testing

tests/package-types.ts in each package imports the package by its own name, so the import goes through the types condition, and pnpm typecheck checks it.

  • It uses the API the way the README shows and refuses an unknown option with @ts-expect-error. It also expects importing the internal helper to fail.
  • That last check makes it impossible to pass without the generated declarations. With types/ deleted, TypeScript falls back to the JavaScript, finds the helper, and the check fails. I checked that.
  • The embed's file passes the runtime's and the libraries' real exports to startEmbed, so the README's bundler example is type-checked across three packages.

The packed tarballs in a fresh project: I ran pnpm pack on all three, installed the tarballs with npm outside the workspace, and type-checked a caller with TypeScript 5.9.3.

Caller's setup Result
bundler resolution, skipLibCheck: false passes, including a full check of every declaration
nodenext resolution, with skipLibCheck the three packages' own types are complete; three types reached through the player become any (see below)

Suites:

  • pnpm typecheck across the repo passes, also starting from deleted player types/, which the verifier's and the embed's declarations import from.
  • Tests: normalize 20 of 20, verify 16 of 16, embed 27 of 27.

Found on the way, not fixed here: the player's own declarations under nodenext.

  • The player's types/ imports its sibling files without extensions ('./shared/protocol'), which node16/nodenext resolution can't follow.
  • With skipLibCheck, everything reached through those imports silently becomes any: PlayerErrorDetail['code'], missingLibraries, ReadyDetail['source'].
  • This affects the player's own users on those settings, and Node pipelines calling the verifier. Under bundler resolution, everything is typed.
  • It belongs in the player's declaration output, so it should be an issue of its own.

Release

A minor version of each of the three packages: additive, and nothing in the JavaScript changes. Combined with #61's fixes, that means embed and verify go to a minor rather than a patch.

🤖 Generated with Claude Code

alekswebnet and others added 2 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.
@alekswebnet
alekswebnet merged commit 6d593a3 into fix/pack-refresh-hash-and-inputs Oct 21, 2026
2 checks passed
@alekswebnet
alekswebnet deleted the feat/command-package-types branch October 21, 2026 18:53
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.

1 participant