Repository navigation
feat: types for the JavaScript APIs of h5p-verify, h5p-normalize and h5p-embed - #65
Merged
alekswebnet merged 2 commits intoOct 21, 2026
Conversation
…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
merged commit Oct 21, 2026
6d593a3
into
fix/pack-refresh-hash-and-inputs
2 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #60.
Stacked on #61, which edits two of the same files (
verify.mjs, the embed'sbuild.mjs). Merge #61 first. When its branch is deleted, GitHub moves this PR ontomain, and the diff below then shows only this change.The verifier, the normalizer and the embed package document a JavaScript API that
docs/compatibility.mdcovers, but they shipped no declarations. A TypeScript caller gotany, or error TS7016 understrict. Each package now ships declarations generated from its JSDoc.Changes
Checked JSDoc (each package's
tsconfig.json)checkJsoverlib/, and the embed'ssite/embed.js, found 176 errors: verify 75, embed 95, normalize 6.contentChanges,Array.isArray(b)is now explicit besideArray.isArray(a). The arrayness was already checked equal one line above, so behaviour is unchanged.@paramcomment sat above the wrong function (storedMetainstead ofcopyRaw); it is moved.Generated declarations (
tsconfig.types.json,pnpm types,exports)pnpm typeswrites the entries' declarations intotypes/, which is not in git. It deletes the folder first, sincetscnever removes a stale declaration.typecheckandprepackboth run it.exportsentry names the declarations under atypescondition, andfilesincludestypes/..d.mtsdrifted from its source.Only the documented API
@internaland stripped. In the verifier that'scontentChanges; in the normalizer,targetFormOf,plainRelativeNameandorderEntries; in the embed,parseOrigin,parseOrigins,parseDefaultLibrariesandcontentSecurityPolicy.@internalon a@typedefdoesn't strip it: every top-level typedef is published. Worse, its comment counts as part of the next declaration's comments, so an@internaltypedef 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
verifyPackage(options: VerifyOptions): Promise<VerifyReport>,summarize(report: VerifyReport)andVerifyError.VerifyReporttypesreport.jsonfield by field, from the code andpage.html. Its error codes, state and refreshed libraries are the player's own types.normalizeArchive()returningReport, plusEntryResult,TargetForm,formatBytes()andarchiveFingerprint().buildSite()returningBuiltSite, andEmbedError. From./embed.js,startEmbed(), whosepackandruntimeoptions are the element's property types.VerifyErrorandEmbedErrorare public, since callers catch them. Neither was named indocs/compatibility.mdbefore.Docs
docs/compatibility.mdcovers "their types" for the three packages, as it already did for cmi5.VerifyReportgains fields the same wayreport.jsondoes.Testing
tests/package-types.tsin each package imports the package by its own name, so the import goes through thetypescondition, andpnpm typecheckchecks it.@ts-expect-error. It also expects importing the internal helper to fail.types/deleted, TypeScript falls back to the JavaScript, finds the helper, and the check fails. I checked that.startEmbed, so the README's bundler example is type-checked across three packages.The packed tarballs in a fresh project: I ran
pnpm packon all three, installed the tarballs with npm outside the workspace, and type-checked a caller with TypeScript 5.9.3.bundlerresolution,skipLibCheck: falsenodenextresolution, withskipLibCheckany(see below)Suites:
pnpm typecheckacross the repo passes, also starting from deleted playertypes/, which the verifier's and the embed's declarations import from.Found on the way, not fixed here: the player's own declarations under
nodenext.types/imports its sibling files without extensions ('./shared/protocol'), whichnode16/nodenextresolution can't follow.skipLibCheck, everything reached through those imports silently becomesany:PlayerErrorDetail['code'],missingLibraries,ReadyDetail['source'].bundlerresolution, everything is typed.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