Skip to content

Convert to a TypeScript project, ship ESM only - #98

Merged
bhousel merged 2 commits into
mainfrom
typescript
Nov 12, 2026
Merged

bhousel merged 2 commits into
mainfrom
typescript

Conversation

@bhousel

@bhousel bhousel commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

Converts node-diff3 to a TypeScript project and drops the CommonJS build. Targets v4.

src/diff3.mjs is now src/diff3.ts with its types inline, so the hand-written src/diff3.d.ts is gone. tsc generates the declarations (with isolatedDeclarations on, so the public API can't change by accident), and Bun.build writes the ESM and IIFE bundles. The layout follows location-conflation: bundles in dist/js/, declarations in dist/ts/.

Types

  • No more any: everything is generic over the buffer item type, and inputs accept readonly arrays. The existing I* type names are kept.
  • New IStrippedPatchRes<T> is what stripPatch() returns and patch() accepts, so stripped patches type-check now.
  • MergeRegion<T> is a discriminated union of { ok } and { conflict }, so checking region.ok narrows the type. It's now a type alias, so code that extends MergeRegion will need updating.
  • tsconfig.json sets "types": ["bun"]. TypeScript 7 no longer loads @types/* packages automatically, and the Bun global had only been type-checking because scripts/clean.ts happens to import from bun.

Packaging

"exports": {
  "types": "./dist/ts/diff3.d.ts",
  "bun": "./src/diff3.ts",
  "import": "./dist/js/diff3.mjs",
  "require": "./dist/js/diff3.mjs",
  "browser": "./dist/js/diff3.iife.js",
  "default": "./dist/js/diff3.mjs"
}
  • ESM only. With Node 18 at end of life, require() can load the ESM build on Node 20.19+ and 22.12+.
  • require stays ahead of browser. Otherwise a bundler resolving a require() call for the browser would pick the IIFE, which has no exports.
  • browser is never chosen over import. It's kept to point readers at the IIFE.
  • Bun imports the TypeScript source directly.

Tests

The tests are now TypeScript and use node:assert, because bun:assert has no type declarations. Most of them compare the whole result at once, which also covers conflict aIndex/oIndex/bIndex (not checked before). The LCS helper now checks that the chain ends at the empty result.

Verification

  • bun run all passes: lint, types, build, 37 tests, 100% coverage.
  • Both the built dist/js/diff3.mjs and the TypeScript source give identical output to main on 330k random inputs and all benchmark workloads. Performance is unchanged within noise on Bun and Node.
  • In a scratch project with the package linked in:
    • types resolve under bundler, nodenext ESM and nodenext CJS
    • require() and import work on Node 22
    • Bun loads src/diff3.ts

Breaking changes (for the v4 changelog)

  • CommonJS build removed. require() needs Node 20.19+ or 22.12+.
  • CDN path moves from dist/diff3.iife.min.js to dist/js/diff3.iife.min.js. Pages loading @latest from the old path will break.
  • MergeRegion is now a discriminated union type alias.
  • (Already merged in Compare buffer items with strict equality #97: items are compared with ===.)

No engines.node was added on purpose. npm only warns on a mismatch, but Yarn 1 fails the install outright, even for devDependencies. The minimum is documented in the README instead.

🤖 Generated with Claude Code

Source is now src/diff3.ts with its types inline, replacing the
hand-written src/diff3.d.ts. Declarations are generated by tsc into
dist/ts/ under isolatedDeclarations; Bun.build writes the ESM and
IIFE bundles into dist/js/.

- Replace `any` with generics; inputs accept readonly arrays
- Add IStrippedPatchRes so stripPatch() output type-checks with patch()
- Make MergeRegion a discriminated union of ok and conflict regions
- Drop the CJS build; require() loads the ESM build (Node 20.19+/22.12+)
- Add a `bun` export condition pointing at the TypeScript source
- Convert tests to TypeScript with whole-result assertions
- Add tsconfig.build.json and a check:types script

BREAKING CHANGE: CommonJS build removed; the IIFE moves to
dist/js/diff3.iife.js; MergeRegion is now a type alias union.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
TypeScript 7 no longer includes @types packages automatically. The Bun
globals only type-checked because scripts/clean.ts imports from bun.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@bhousel
bhousel merged commit 5461885 into main Nov 12, 2026
1 check passed
@bhousel
bhousel deleted the typescript branch November 12, 2026 19:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant