diff

diff (published to npm as “diff”, developed under the jsdiff project name) is a JavaScript text-differencing library based on Eugene Myers’ O(ND) difference algorithm. It exposes a family of functions — diffChars, diffWords, diffLines, diffSentences, diffCss, diffJson, and diffArrays — that each compute the minimal set of insertions and deletions needed to transform one input into another, at a different granularity of “token”.

Beyond raw diffing, the library includes a full unified-diff patch toolkit: createPatch/createTwoFilesPatch to generate Git-style patch text, parsePatch to read it back into structured hunks, applyPatch/applyPatches to apply hunks to a string, and reversePatch to invert a patch. It ships as dual ESM/CJS with first-class TypeScript types and has been a dependency of the JavaScript ecosystem for over a decade, powering diff views in tools ranging from CI output formatters to code-review UIs.

What You Get

• Granular diff functions — diffChars, diffWords, diffWordsWithSpace, diffLines, diffTrimmedLines, diffSentences, diffCss, diffJson, and diffArrays — each returning an ordered array of change objects marking additions, removals, and unchanged spans
• A full patch toolkit: createPatch/createTwoFilesPatch/formatPatch to generate unified-diff text, parsePatch to parse it, applyPatch/applyPatches to apply hunks, and reversePatch to invert them
• Fine-grained diff options per function — ignoreCase, ignoreWhitespace, newlineIsToken, custom comparators, Intl.Segmenter-based word tokenization, and stringifyReplacer for JSON diffing
• Abortable/async diffing via a timeout or maxEditLength option and an optional callback, so large diffs don’t block the main thread indefinitely
• Interop helpers — convertChangesToDMP and convertChangesToXML — for bridging jsdiff’s change-object format to Google’s diff-match-patch format or to XML markup
• Dual ESM/CommonJS builds with bundled TypeScript declarations and a browser-ready UMD bundle (dist/diff.js) exposing a global Diff object

Common Use Cases

• Rendering side-by-side or inline code/text diff views in editors, code-review tools, and documentation-comparison UIs
• Generating and applying Git-style unified-diff patches programmatically, e.g. for scaffolding tools that need to patch generated files
• Comparing structured JSON payloads (config files, API responses, test fixtures) with human-readable diff output
• Building CLI or CI tooling that needs to show “before vs after” text changes, such as snapshot-testing diff output or changelog generation

Under The Hood

Architecture The library is organized around a single generic Diff base class (src/diff/base.ts) that implements Myers’ O(ND) algorithm over an edit graph, tracked as a linked list of DraftChangeObject nodes per diagonal path (the bestPath array) to avoid the naive algorithm’s quadratic overextension past the graph’s edges — a documented deviation from the original paper for performance. Each concrete diff mode (src/diff/character.ts, word.ts, line.ts, sentence.ts, css.ts, json.ts, array.ts) subclasses Diff and overrides tokenize, equals, castInput, and join to define what a “token” means for that mode — a Unicode code point for diffChars, a line for diffLines, a canonicalized JSON line for diffJson. The patch toolkit (src/patch/create.ts, parse.ts, apply.ts, reverse.ts) is a separate, loosely coupled layer built on top of diffLines that serializes/deserializes the standard unified-diff hunk format, including Git-specific extended headers and C-style filename quoting for non-ASCII paths. Tech Stack Written entirely in TypeScript, targeting both CommonJS and ESM output via a dual tsc build (libcjs/, libesm/) plus a Rollup+UglifyJS browser bundle (dist/diff.js). Zero runtime dependencies. Uses Mocha/Chai/nyc for testing, ESLint with typescript-eslint for linting, and @arethetypeswrong/cli/tsd to validate the published type declarations and package exports map against real consumers. Code Quality The nyc configuration enforces 100% branch, line, function, and statement coverage (check-coverage: true with all four thresholds at 100 in package.json), and the test suite (~6,900 lines) is roughly double the size of the library’s own source (~3,700 lines), covering each diff mode and every patch operation exhaustively, including edge cases like CRLF handling, empty-file patches, and non-ASCII filename quoting. Source files are heavily commented, including a rationale comment in base.ts explicitly explaining a deliberate deviation from Myers’ published algorithm for a major performance win. API Design The public API favors small, purpose-named functions (diffChars, diffLines, createPatch, applyPatch) over a single configurable entry point, so call sites read close to plain English. Every diff function accepts a consistent options object shape (comparator, ignoreCase/ignoreWhitespace variants, timeout, callback) reused across modes, and TypeScript overloads precisely encode the differing return types for sync vs. callback vs. abortable-async calls, so consumers get accurate autocomplete and type-checking without reading the docs.