adopt TypeScript .ts syntax

[turadg]

I don't think this is going to happen but I wanted a place to collect the benefits and blockers.

What is the Problem Being Solved?

We rely on TypeScript for Intellisense, refactoring support, and fast feedback on what will fail in tests. We use the JSDoc syntax in .js and not .ts syntax.

Kinks

• No way to opt out of typedef exports (Support for opting out of jsdoc @typedef exports microsoft/TypeScript#46011)
• Inline casts require wrapping the casted value in () which build tools remove as superfluous (example)
• No way to deprecate types (the @deprecated tag works only in .ts + jsdoc and not with plain JS.

Challenges

• Transpilation affects auditability
• Build step complicates execution

Description of the Design

Probably some form of Node module loader hook, such as https://github.com/esbuild-kit/esm-loader

Or a Node wrapping runtime: https://github.com/privatenumber/ts-runtime-comparison

There will be transpilation but audits should be of built bundles, which aren't minified.

Security Considerations

Test Plan

[turadg]

Progress in,

• more ts syntax #8335
• convert boot tests to .ts #8313
• convert all type declaration files to TS syntax (.d.ts) #8342

[dckc]

conversion to .cjs module format is problematic

case in point: #9408 (comment)

here's hoping for a .ts compiler / build tool that erases the types and does nothing else; especially no conversion to .cjs. I gather esbuild is close.

[erights]

Given recent announcements...

Let's say we assume support for a well defined subset of TS that can be, and is, turned into JS only by erasure of what is clearly only the non-JS portion of the TS code. And that any TS code (even correct TS code) outside that subset fails to compile with an explicable error. If this subset of TS does not already have a name, we should coin one.

Assuming that, and given our increasingly pervasive use of sound exo guards and patterns, and our recent helpers for bridging patterns-to-types, I think we could accept such code as production code. Not a decision yet. But I’d be interested in everyone’s view of the downsides. If no one has any downsides beyond what’s off the top of my head right now, yes, I think we could decide to do that.

Given our support for soundness, I think it is possible to learn to be adequately vigilant of the remaining unsoundness during review. Might need extra tool support to do that well, like syntax coloring to make clear what is and is not erased. But if we’re going this far I would not make those extra tools a blocker. Rather, they would just join the long list of developer tooling we need for a decent DX. Still behind tooling for a better debugging DX 😉