Move to TypeScript

[Acconut]

This PR is an experiment to see how we can utilize TypeScript to transpile the source code into CommonJS/ESM code included in the package. The benefit is that we have type-checked source code and also don't have to manually maintain a type definition in index.d.ts.

[Murderlon]

We should consider introducing a major version and only publish ESM for both Node.js and browser.

[Murderlon]

Some recommended settings

Suggested change

	"target": "ES2018",
	"esModuleInterop": true,
	"forceConsistentCasingInFileNames": true,
	"strict": true,
	"skipLibCheck": true,
	"allowJs": true,
	"checkJs": false,
	"declaration": true,
	"esModuleInterop": true,
	"skipLibCheck": true,
	"target": "es2022",
	"allowJs": true,
	"resolveJsonModule": true,
	"moduleDetection": "force",
	"isolatedModules": true,
	"strict": true,
	"noUncheckedIndexedAccess": true,
	"sourceMap": true,
	"declaration": true,

[Acconut]

@Murderlon You mentioned that dual publishing a package containing CommonJS and ESM can lead to unexpected problems. Are there some links or resources digging more into this? Are you referring to what Node.js calls the dual package hazard? We have dual published this package for four years (since bdb6144) and didn't run into any problems and no major issues where reported to us.

By completely ditching CommonJS, I am worrying that we leave some application behind which are still using it and have a hard time upgrading to ESM (I think to recall that our website tus.io also still compiles to CommonJS, but I might get that wrong). Is this concern unjustified nowadays?

If so, it would be great if we could reduce the complexity of this package's setup.

[Murderlon]

You mentioned that dual publishing a package containing CommonJS and ESM can lead to unexpected problems. Are there some links or resources digging more into this?

This from my experience + some other prominent maintainers I talk with. All my issues in the past with a package were from dual publishing, not ESM. Examples include Preact itself and even the package dual-publish, which is supposed to solve it.

It is possible and since we already have it working it's not really a problem. But at some point we should make the jump, ESM is the future.

By completely ditching CommonJS, I am worrying that we leave some application behind which are still using it and have a hard time upgrading to ESM

Technically everyone can use it, even in a CommonJS setup:

const tusPromise = import('tus-js-client')

module.exports = tusPromise.then((tus) => tus.default)

It's not the ideal developer experience, but it's important to note that tus-js-client is close to done for tus protocol v1. It's stable and it's totally fine to stay on the previous major version if you must for a while. And even without ditching CommonJS, this would be a major version anyway, and I think it's better to have less major versions (rather than major version for TS then later again for ESM).

---

Some tools which are importent to check:

• https://github.com/wooorm/package-exports (gives errors and warnings based on our package.json)
• https://arethetypeswrong.github.io/?p=tus-js-client%404.1.0
• Information for users who now have to deal with an ESM package.

[Murderlon]

Some more warnings:
https://publint.dev/[email protected]

[Acconut]

I updated this PR to touch the export structure in package.json as little as possible and instead opened #693 to handle the restructuring of the exports in a separate PR.