Idiomorph not published with types

[myabc]

This would be great to have in downstream projects, e.g. here: https://github.com/opf/openproject/blob/dev/frontend/src/typings/idiomorph.d.ts

[botandrose]

Hi @myabc, thanks for the suggestion. I'm not super familiar with typescript so a few questions:

1. What exactly does it mean to publish types? Is it just including a .d.ts file in the NPM package? Does it need to be referenced in package.json? Anything else?
2. If we do this, what problem or problems are we solving?
3. Are there any possible downsides to doing this that you can see?
4. Is there a way we can automate this as part of the release process?

[myabc]

Hi @botandrose, thanks for the quick reply!

1. What "publishing types" means

There are two parts to this – both needed:

• Ship the .d.ts in the npm tarball — it's in files (or just not gitignored), so it rides along in the same package. No separate registry/upload; types travel with the JS.
• Point package.json at it so TypeScript knows where to look: top-level types field + a types condition in each exports entry. TS reads those to resolve declarations for an import.

That's it. One caveat: the .d.ts has to be module-shaped (export ...) matching the entry — a global declare var won't resolve. Hence we generate from the ESM bundle, not src.

Since code speaks a thousand words, it's probably worth taking a look at #153

2. Problems solved (from a consumers perspective at least)

1. Consumers get autocomplete + type-checking out of the box.
2. Kills hand-maintained idiomorph.d.ts copies ➡️ no drift between guessed types and real API.
3. TypeScript stops treating the lib as any.

The second one is a personal pain point for me. In addition to the typings for OpenProject, I contribute to typings for Turbo, another downstream project. Typings might have helped wiith this particular drift scenario: DefinitelyTyped/DefinitelyTyped#75138

3. Downsides

• Types become public API. Breaking a type now matters for semver; people file type bugs. _that said, it seems like the Idiomorph API has remained pretty stable, so this might not be such a big issue)
• Generated-from-JSDoc can be wrong — we already caught the morph() return-type bug. Shipping wrong types is arguably worse than none.
• Loose spots remain where JSDoc is thin (e.g. callbacks typed broadly).
• Small build/repo cost: extra tsc step, more generated artefacts in the repo (e.g. dist/*.d.ts)

IMO this is probably still worth it, but we would need to treat the generated output as something to eyeball, not juyst trust blindly.

4. Automating in release

Mostly done already done — npm run dist (release step 3) now runs types, so declarations regenerate every release.

Let me know if you need any more info! thanks again!