Initial TypeScript setup and conversion (CJS to ESM, ES5 class functions to ES6 classes)

[ericyhwang]

Summary

Set up TypeScript, do file renames from *.js to *.ts, then run codemods to convert CommonJS to ES modules and ES5 class functions to ES6 classes.

This is a redo of #705 without the dev dependency upgrades, which I moved out into #706 and are already merged into master.

Couple bigger codemod changes here on top of the older PR:

• Non-function prototype properties, e.g. Backend.prototype.MIDDLEWARE_ACTIONS = ..., are declared as fields, with the assignment moved into static blocks to reduce the diff size.
• Comments on prototype property assignments are ported over to the class field definitions. If such comments are one or more single-line // comments, they are converted to JSDoc-style /** */ comments.

Goals

It targets the typescript branch, which we can use to stage the TypeScript changes until they're ready to merge into main. Making smaller intermediate PRs into that branch will make things easier to review.

For now, my goal with the typescript staging branch is to end up with TS source code that compiles into JS output compatible with the current JS source, so we could publish it a minor version. In a future major version, we can choose to update the compile target to drop ES5 support, especially if we want to start using things like async/await without the extra verboseness of downleveling.

We should probably major version soon anyways, since Node 18's been EoL for a year, and Node 20's about to reach EoL.

Reviewer tips and notes

• I recommend going through the commits one by one.
• Unfortunately, GitHub's new diff viewer doesn't respect the "Ignore whitespace" option when you have it show a file with a large diff, so for the codemod commit, it'd be better to pull this typescript-initial branch down and locally view the commit's diff, e.g. in your editor.
• If you would like to compare the original JS source with the tsc-produced JS output, I have that pushed up to the typescript-cjs-class-codemods-js-outputs branch, in commit a4afeec. Similarly, it's better to pull the branch and compare locally.

Let me know if you want to schedule time to go through this on a call!

Changes

1. Set up TypeScript, rename all lib/**/*.js files to src/**/*.ts with no changes
   • Doing a commit with simple moves/renames guarantees that Git can detect the renames, making it easier to use git blame and other history spelunking tools on the "new" TS files.
2. Pre-codemod manual changes
   • Move some module.exports statements up. Some class JSDoc comments were attached to the module.exports lines. Moving them so the comments are attached to the class functions means the codemod (next step) can do a better job porting the comments over to the ES6 class.
   • Minor tweaks to next-tick.ts and util.ts to eliminate duplicate declaration issues post-codemod.
3. Run jscodeshift codemod-cjs-to-esm.ts and codemod-es5-classes.ts
   • Codemods run really fast, and a given codemod and input will consistently produce the same output, unlike LLM-based gen AI. That said, I did use gen AI to help write these codemods.
   • Background and details:
     • Many years ago, for Lever's TS conversions, I hand-wrote the codemods. LLMs were still in relative infancy and not as well-known back then.
     • Since I no longer have access to Lever code, I've made new ground-up codemods with gen-AI assistance, focused on converting ShareDB source code.
     • Specifically, I used Google's Antigravity IDE (their agent-focused editor) with a mix of Gemini 3.1 Pro and Gemini 3 Flash models. It did a pretty good job, though as expected I did have to go through many rounds of prompting and refining requirements to handle various cases.
     • At the end, I went through and re-read all the code in the codemods, doing light refactoring and adding comments as needed.
   • The codemods - they're gists for now until I get around to putting them in their own repo:
     • https://gist.github.com/ericyhwang/4ef3a6b02d0b86a4a7beda4d57520ccb
     • https://gist.github.com/ericyhwang/32046cc7bcf569c34fda1afefa4d4b0c

Next steps

First thing after this PR is to go through the many TS compilation errors and fix them. Most fall into these categories:

• Declaring more class fields/methods, missing either due to assignments outside the constructor or due to inheritance from built-in classes not being able to use extends
• Marking optional params
• Typings for properties added onto object literals after initial creation

Then it'll be adding stronger types, likely based on our DefinitelyTyped definitions; doing more cleanup as needed; and converting test files to TS.

[coveralls]

Coverage is 94.637% — typescript-initial-2 into typescript. No base build found for typescript.

[alecgibson]

Why? JSDoc or something?

[alecgibson]

How did you decide this?

[alecgibson]

(Switching to ESM at some point is going to be fun 🙄 )

[alecgibson]

I'm not sure I like this. On a selfish note, I think this will pollute our own code's types, because we run backend.js even in the browser 😅

But from a less selfish perspective, this shouldn't apply to client/ which is designed for browser consumption. I think we possibly want 2 different tsconfig.json files? One for backend stuff, and one for client?

In an ideal world I think backend and client would be 2 separate packages in a monorepo, but that's obviously out of scope of this change.

[alecgibson]

😢 Why?