Types?

[ljharb]

(continued from #202 (comment))

Whether packages are authored in TypeScript or not, providing types for users who do use TypeScript is a good thing.

If a package is authored in TypeScript, it's very easy to emit d.ts files as a build process and publish them. If not, then it's also almost as easy to hand-write d.ts files, and import() types from them inside jsdoc comments inside JS, and run tsc on the project to typecheck it. Advantages to the jsdoc + d.ts approach include that no build process is required.

Another alternative would be to NOT ship inline types, and instead to confine types to DefinitelyTyped. The major advantages of this approach are that the semver of the types isn't conflated with the semver of the implementation, and, the TS team will help you maintain compatibility across TS versions. The major disadvantages of this approach are that it requires a separate PR to update types post-release, and it can be difficult to keep those in sync on a more complex project or one with frequent changes.

As a data point, I used to exclusively ship types in DT for my packages, but now for the smaller, single-purpose ones, I've started going with the jsdoc + d.ts approach, since those packages don't change frequently.

What should the express org do here? Decisions could result in a mandate for all org packages, or in multiple "golden paths" that each project's maintainers are free to choose from, etc.

[kibertoad]

I would avoid the DT route, TS community is strongly converging on bundling types, either handwritten or generated ones. That provides better DX for the end users, but also allows atomic commits of behaviour change + type change, which makes life of maintainers easier as well.

No strong preference on generated vs hand-written. There is a popular rumour of perf impact from generating JS code, which I never saw any well-researched proof for (for modern ES version targets)

Generated is less burden on maintainers, bundled is more control over exact code executed. Since perf never was a big topic for Express, and code correctness is not an issue, generated JS/types may be perfectly fine.

[wesleytodd]

Sorry lots of issues, is this an overlap with this? #192

[ljharb]

aha, yes, duplicate of #192 :-)