Initial TypeScript setup and conversion (CJS to ESM, ES5 class functions to ES6 classes) by ericyhwang · Pull Request #705 · share/sharedb

ericyhwang · 2026-04-09T21:59:18Z

This PR covers TypeScript setup, file renames, then using codemods to convert CommonJS to ES modules and ES5 class functions to ES6 classes.

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. The newer testing libraries actually don't run on Node 18, so I'm dropping that version from our CI in this PR.

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 640885e. 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

Update to latest dev dependencies (eslint, mocha, chai, nyc, sinon)
- ESLint now requires the newer "flat config". I used the eslint migration tool to produce eslint.config.js based on the existing .eslintrc.js.
- sinon@19 started stubbing nextTick by default, which causes some tests using fake timers to fail. To fix them, I used the new option clock.setTickMode({mode: 'nextAsync'});, which automatically progresses any immediate-style timers like nextTick.
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.
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.
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.

…o changes

…ttached to the class functions for better codemod porting

…es.ts

Node 18 has been EoL for a year. Also, dev deps sinon 19+, chai 5+, and sinon-chai 4+ require at least Node 20, since require(esm) was only backported as far back as Node 20 - https://joyeecheung.github.io/blog/2025/12/30/require-esm-in-node-js-from-experiment-to-stability/\#Backporting-require-esm-to-v22-and-v20-LTS

…anscluded from sharedb-mongo tests

alecgibson · 2026-04-10T15:52:58Z

.github/workflows/test.yml

-        - 18
        - 20
        - 22
+        - 24


To try to keep this PR smaller, can we move all the dependency / environment bumps into a separate PR that we can merge first?

Sure, I can cherry-pick those. Do you have a preference for getting the dep updates into master, or just into the typescript staging branch?

Let's get it on master. I'm generally of the opinion that the more stuff we can get into master as early as possible, the less painful things will be later.

alecgibson · 2026-04-10T15:57:15Z

.github/workflows/test.yml

    - name: Install
      run: npm install
    - name: Lint
+      if: github.ref_name != 'typescript' && github.base_ref != 'typescript' # Remove this condition after TS code lints cleanly


Again, to try to keep this as close to master as possible, can we just update our eslint config to ignore src/?

ericyhwang · 2026-04-10T16:17:22Z

Also, I did see that in the sharedb-mongo tests, the Node process is left hanging after all the tests pass.

I started looking into it with why-is-node-running yesterday, but didn't have time to get to the bottom of it before dinner. Current line of investigation is some interaction between newer sinon/fake-timers (which fakes more timer APIs) and the real Mongo driver.

alecgibson

Some notes on the "[codemod] Run jscodeshift codemod-cjs-to-esm.ts and codemod-es5-classes.ts" commit — please disregard if addressed later.

Note to self: I've looked at everything in this commit except agent.ts, whose no-whitespace diff wouldn't render in GH.

I'll try to continue reviewing on Monday.

alecgibson · 2026-04-10T16:03:21Z

src/client/presence/doc-presence-emitter.ts

+  _docs;
+  _forwarders;
+  _emitters;
+
+  constructor() {
+    this._docs = Object.create(null);
+    this._forwarders = Object.create(null);
+    this._emitters = Object.create(null);
+  }


Can we just inline these declaration statements and remove this unneeded constructor()?

That we'd want to do manually later, and not via codemod here.

Field initializers have more restrictions than constructor assignments, e.g. they can't rely on constructor params, always run prior to the main constructor body, etc.. In a codemod that's aiming for safety, trying to infer whether it's OK to convert an assignment to an initializer is more trouble than it's worth.

alecgibson · 2026-04-10T16:04:35Z

src/client/presence/doc-presence-emitter.ts

+  _docs;
+  _forwarders;
+  _emitters;


I guess again not one for a patch bump, but we may want to consider making these private at some point in the future.

private fields would break any consumers who may use the internals. While the underscore indicates that they really shouldn't use those fields, I admit that for tests, I've sometimes hooked into the internals of libraries. 😅

alecgibson · 2026-04-10T16:07:06Z

src/client/presence/doc-presence-emitter.ts

-  util.digAndRemove(this._emitters, doc.collection, doc.id);
-  util.digAndRemove(this._docs, doc.collection, doc.id);
-};
+import util = require('../../util');


I've honestly lost track in all of the CJS vs ESM nonsense — is import = require well behaved and interoperable? Any reason we're not using import ... from everywhere? I assume the latter requires type definitions(?)

https://www.typescriptlang.org/docs/handbook/2/modules.html#es-module-syntax-with-commonjs-behavior

The TS-specific syntax import __ = require(__) directly compiles to a CJS require().

For the ESM import syntax import __ from __, when TS is outputting as CJS, it includes a shim in the each JS output file to enable importing modules both an ESM default export someModule.default as well as a CJS "whole-module" export someModule.

Here's a TS Playground snippet showing the difference:
https://www.typescriptlang.org/play/?target=1&module=1#code/JYWwDg9gTgLgBGAhjAFgUQM4gCIFMBmiArgDYwCS408+UEIcA5EqowNwBQoksCyKAYQBWGAEq4AjkWBRccALxxZUmbgAUzfowCUnDi3RY8hUhSqwAdEIjAAdmt37+wsZOmyrN+46A

Since I wanted to keep the JS output as close to the CJS original as possible for now, I opted for the direct analogue import __ = require.

If we want to output ESM instead of CJS in the future, then we'd have to switch to import __ from __ syntax, but that's easy enough to do with another codemod.

alecgibson · 2026-04-10T16:11:42Z

src/client/presence/remote-doc-presence.ts

+RemotePresence.prototype._handleCreateDel = function() {
+  this._cacheOp(null);
+  this._setPendingPresence();
+};
+
+RemotePresence.prototype._handleLoad = function() {
+  this.value = null;
+  this._pending = null;
+  this._opCache = null;
+  this.presence._updateRemotePresence(this);


This got skipped by the converter, presumably because I typoed this in the original code 🙈

Heh, yeah, it's sticking these onto the base class. We can either fix it afterwards, or fix it in the JS now in a separate PR and I'll re-run the codemods.

alecgibson · 2026-04-10T16:18:21Z

src/db/index.ts

+DB.prototype.projectsSnapshots = false;
+DB.prototype.disableSubscribe = false;


Do these need converting into instance properties?

Naively switching to an instance property with field initializer would technically be a breaking change, since it's possible some user code is referencing DB.prototype.projectsSnapshots, to read or change the default value.

Prototype property related breakages were an issue we ran into with Derby-related conversions, so I'd updated our codemods back then to be more conservative with prototype properties. For these, I started with the safer approach from the get-go.

We will want to declare them as fields so the type system knows about them. I was going to do that manually later, but maybe the codemod can insert a field declaration...

alecgibson · 2026-04-10T16:20:05Z

src/backend.ts

+export = Backend;
+emitter.mixin(Backend);
+
+Backend.prototype.MIDDLEWARE_ACTIONS = {


Should this be an instance property?

See above comment about how changing from prototype property to instance property is technically a breaking change.

alecgibson · 2026-04-10T16:20:15Z

src/backend.ts

+  submit: 'submit'
+};
+
+Backend.prototype.SNAPSHOT_TYPES = {


Instance property?

alecgibson · 2026-04-10T16:21:08Z

src/error.ts

+ShareDBError.prototype = Object.create(Error.prototype);
+ShareDBError.prototype.constructor = ShareDBError;
+ShareDBError.prototype.name = 'ShareDBError';


This doesn't feel right

This is unchanged from the original JS code:

sharedb/lib/error.js

Lines 11 to 13 in b6deed8

ShareDBError.prototype = Object.create(Error.prototype);

ShareDBError.prototype.constructor = ShareDBError;

ShareDBError.prototype.name = 'ShareDBError';

It's just relocated out of the class body.

I'm guessing it's so that you can do a check like if (errorInstance.name === 'ShareDBError')

ericyhwang · 2026-04-11T01:02:20Z

I've moved the dev dependency upgrades to #706 and fixed the issue with the hanging Mocha process.

I might create a new PR for the TS changes after the next round of feedback, instead of dealing with rebasing, since the codemods make it easy to re-construct the changes. TBD, I'll decide next week.

ericyhwang added 7 commits April 8, 2026 14:16

Upgrade dev dependencies (eslint, mocha, chai, nyc, sinon)

0bd0434

Set up TypeScript, rename all lib/**/*.js files to src/**/*.ts with n…

257de57

…o changes

Move some module.exports statements up, so class JSDoc comments are a…

6ea4c9f

…ttached to the class functions for better codemod porting

Update tsconfig and do light refactoring to make codemod more reliable

aa2f6b3

[codemod] Run jscodeshift codemod-cjs-to-esm.ts and codemod-es5-class…

e8c2157

…es.ts

Remove old .eslintrc.js

ddf26c5

Run tsc before tests, ignoring TS errors for now

330c74e

ericyhwang requested a review from alecgibson April 9, 2026 21:59

ericyhwang added 5 commits April 9, 2026 15:02

Run CI on PRs/pushes to "typescript" staging branch

1800fac

Skip CI linting of TS code for now

919b0af

(tests) Remove extraneous clock.setTickMode

1c2b270

Add sinon clock uninstall to query-subscribe tests, since they are tr…

b2fdd15

…anscluded from sharedb-mongo tests

alecgibson reviewed Apr 10, 2026

View reviewed changes

ericyhwang marked this pull request as draft April 11, 2026 00:59

		DB.prototype.projectsSnapshots = false;
		DB.prototype.disableSubscribe = false;

	ShareDBError.prototype = Object.create(Error.prototype);
	ShareDBError.prototype.constructor = ShareDBError;
	ShareDBError.prototype.name = 'ShareDBError';

Conversation

ericyhwang commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Next steps

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ericyhwang commented Apr 10, 2026

Uh oh!

alecgibson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ericyhwang commented Apr 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ericyhwang commented Apr 9, 2026 •

edited

Loading