Typescript Rewrite

[Phillip9587]

This PR is a full TypeScript rewrite of the package as suggested by @blakeembrey in #104 (comment).

It also uses tsdown to build a dual bundle: CommonJS for Node.js consumers and an ESM build for browsers and bundlers.

This is another big step for #114.

Tooling

I tried to align the tooling as much as possible with Blake's @borderless/ts-scripts but went for not using it directly. So the package now uses:

• tsdown as build tool (tsdown is powered by rolldown - the same bundler/transformer as vite 8 uses)
• vitest as testing tool with native typescript and coverage support
• eslint and typescript-eslint
• arethetypeswrong and publint for package validation
• prettier as formatter
• husky for git hooks combined with pretty-quick to format only staged files

I aligned the tooling with Blake's @borderless/ts-scripts.

It has fully backward compatible exports and does not change the modules behaviour.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​vitest/​coverage-v8@​3.2.4
	@​borderless/​ts-scripts@​0.15.0
	vitest@​3.2.4
	typescript@​5.9.3

View full report

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

[blakeembrey]

I'm not sure we need to do both ESM and CommonJS, just CommonJS should be fine for a package like this.

Also the TypeScript refactor changes exports but this didn't update the README.

[blakeembrey]

I tried to align the tooling as much as possible with Blake's @borderless/ts-scripts but went for not using it directly.

I'd love to know why. It's totally understandable to skip it as it's just something I started using once I was maintaining hundreds of packages and got sick of the config bloat of every package, as well as keeping up with minor changes/improvements to things like husky everywhere.

[blakeembrey]

The goal was to keep the build setup minimal with a single tool handling bundling and type generation, including native CJS and ESM output, without additional plugins or extra steps.

You can just do this with TypeScript though, why not use that? I'd prefer to not have any additional plugins or extra steps too, I'm just not seeing the benefit to using tsdown.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️

[Phillip9587]

Adressing: #118 (comment)

Hey @blakeembrey, Thanks for explaining your perspective. I really appreciate that you’re the one maintaining this long term, and I don’t want to make that harder for you.

In hindsight, the original PR was too broad. I should have aligned with you before bundling the TypeScript rewrite with tooling and output changes. I’ve now narrowed it to just the TypeScript rewrite, and I also migrated it to use @borderless/ts-scripts, as you’re using in your other packages, to keep things consistent.

Any misinterpretation of your comments wasn’t intentional. I may have been operating from different assumptions about direction and with a bit of excitement around improving ESM, browser, and bundler support. Sorry about that.

I would genuinely love to help maintain this library long term if you’re open to that. I’m not trying to drop a rewrite and disappear. I’m happy to share responsibility and support the agreed direction.

[blakeembrey]

Thank you. You brought some useful libraries to my attention, and I think it'd be worth rolling publint at least into the publishing workflow. Not so sure about aremytypeswrong because I can't see any value for TypeScript-native projects reading over the docs.

I also think the separation of build and tests in the CI step would be useful, so I can incorporate those into a bump of ts-scripts some time. The plus side there being all the projects will adopt these tools. It's also possible tsdown may end up being better in the long run and we could even swap that out, but for now I'm a lot more comfortable relying on the TypeScript compiler directly.

[blakeembrey]

I think it'd be acceptable to rely on web worker, DOM, or node types to avoid this. WDYT? We test in node so I'm vaguely in favor of using one of the other two, since that would confirm it works outside of node using types (as we aren't yet testing non-node envs).

We can also keep this copied if you think it's the best approach.

[Phillip9587]

I’d keep this copied for now. The TextDecoder spec doesn’t change very often, so the maintenance risk feels low.

Relying on @types/node or the dom lib would weaken our type-safety, since it would implicitly allow Node- or browser-specific APIs into the surface area. Keeping this local avoids coupling us to a specific runtime environment at the type level.

I’ll also keep an eye on whether TypeScript eventually exposes a shared lib for common WHATWG APIs (URL, TextDecoder, TextEncoder, etc.). If that happens, we can switch to that and drop the copy.

[blakeembrey]

My plan is to branch the existing main into a 1.x and release it as-is, this one will become the basis of a new major in the coming weeks. I'll be starting some work on top of this to get rid of regexes, similar in scope to jshttp/content-type#58.

[Phillip9587]

I’d be happy to help remove the regexes, as that was also my intention, for example with the hex decoding changes.
It might make sense to create a v2 branch from this PR so we can better track progress. I’d also be glad to open additional PRs to help move things forward.

[blakeembrey]

I’d be happy to help remove the regexes

Sure, I can hold off doing any work if you'd like to focus on it. Can you add benchmarks as you go too? The content-type package is a decent example. I don't mind if performance doesn't improve, the goal is to make it a bit more lenient on the parsing side (replace the custom code in multiparty), but it shouldn't degrade any.

It might make sense to create a v2 branch

I prefer to just keep main/master the latest work which makes my life easier, and branch for any legacy work instead.

[Phillip9587]

Sure, I can hold off doing any work if you'd like to focus on it. Can you add benchmarks as you go too? The content-type package is a decent example. I don't mind if performance doesn't improve, the goal is to make it a bit more lenient on the parsing side (replace the custom code in multiparty), but it shouldn't degrade any.

Thanks for holding off. I really appreciate it. As I mentioned before, I would be happy to help.

I prefer to just keep main/master the latest work which makes my life easier, and branch for any legacy work instead.

Let’s continue working in main or master once the 1.x release is out and this PR has been merged.

If you have the time, could you open a tracking issue outlining your goals for v2? It would be great to align on things like the move to ESM, supported Node versions, overall goals, and any other breaking changes so we can discuss them early.