feat: Add ESM build

[drwpow]

Fixes #22 by adding an ESM build. This is backwards-compatible! It is only an additive change.

⚠️ This adds a npm run build command that is now necessary to generate the ESM files.

• Adds types that satisfy TypeScript’s requirements for dual-build packages
• Updates exports to match both Node.js’ standards as well as TypeScript’s
  • ⚠️ Verify these are backwards-compatible with all consumers! It should be, but verify
• Improves .npmignore by hiding test files and GitHub cruft from the npm package (which saves considerable network traffic, taking into account how often this package is downloaded!)

Alternatives

• The codebase could be converted to ESM, instead, with CJS generated as a side-effect. But that alternative wasn’t taken to minimize disruption.
• A bundler such as Rollup could be introduced to remove the custom one-off script. But that seemed heavier-weight, and would impact CI times far more than the current method

Checklist

• run npm run test and npm run benchmark
• tests and/or benchmarks are included
• documentation is changed or added
• commit message and code follows the Developer's Certification of Origin
  and the Code of conduct

[drwpow]

Note: RegEx replacements can be brittle in larger setups, but this seemed ideal for this package’s current lightweight setup. It’s easier to modify simple string replacements than burdening this package with some robust AST traversal + mutation + reassembly script… that only replaces a couple lines in the end.

Of course, alternatives can be discussed!

[drwpow]

Note: this seems unnecessary—copying existing .d.ts declarations 1:1. But TypeScript does require all-new declaration types for different file extensions, i.e. it won’t apply index.d.ts to both index.js and index.mjs (not even with exports—I’ve tried). This is unfortunately TypeScript behavior, and it’s not easy to bypass.

Alternately, there could be some clever type forwarding, e.g. export * from './index', but in addition to being harder to autogenerate, something could slip through the cracks compared to copying 1:1

[drwpow]

dequal ships ESM, so this package would benefit from upgrading, too

[Fdawgs]

Thanks for the PR @drwpow!
If this is being automatically built via a script then my suggestions would be:

• Add index.mjs and types/index.d.mts to .gitignore, no point committing something that gets built
• Add a "prepublish": "npm run build" script or something to that effect
• Scripts are sorted alphabetically ascending, so build should go at the top etc.

You're going to get pushback for adding an .npmignore due to fastify/skeleton#42.

Obviously wait for @fastify/libraries to chime in before actioning any of this, as my frontend knowledge is... dire.

[mcollina]

I don't think running any of our libraries in a bundle-less browser environment should be a goal (all bundlers compile cjs... React is cjs).

[jsumners]

Why is it necessary to duplicate everything?

[drwpow]

Y’all can feel free to close this if using ESM (the new language standard) isn’t a goal. That’s fine!

@Fdawgs all good suggestions! I went back-and-forth on committing generated files, just because this package didn’t have a build step (but maybe it should—I noticed some of the declarations have drifted from the runtime)

I don't think running any of our libraries in a bundle-less browser environment should be a goal (all bundlers compile cjs... React is cjs).

May be true now but ESM is the new standard. It’s also useful in edge workers (which may also be bundled behind-the-scenes, but ESM saves work)

Why is it necessary to duplicate everything?

ESM is a different module system entirely. I’d recommend reading about it on Node’s documentation but also if you inspect any universal packages you’ll find it (even dequal)

[mcollina]

ESM is a different module system entirely. I’d recommend reading about it on Node’s documentation but also if you inspect any universal packages you’ll find it (even dequal)

Ok, I will take a look.