How kpdecker/jsdiff works
Project type and purpose
• jsdiff is an open-source JavaScript/TypeScript library that computes text differences and unified diff patches, and applies or reverses them.
• It targets both Node.js and browser environments, exposing a single public API entrypoint (index.ts / diff.js) that exports functions like diffChars, createPatch, applyPatch, etc.
File structure
• Top-level:
• Configuration: .babelrc, rollup.config.mjs, karma.conf.js, tsconfig.json, ESLint
• Build/runtime: runtime.js (for bundling support), dist (implied by README)
• Source: src/
• Examples: examples/
• Tests: test/ and legacy tests in test-d/
• src/ splits into:
• src/diff/ – implementations of diff algorithms per token type (array.ts, character.ts, css.ts, json.ts, line.ts, sentence.ts, word.ts), and base.ts providing the core Myers-based Diff class.
• src/patch/ – patch creation (create.ts, structuredPatch in create.ts), patch application (apply.ts), parsing (parse.ts), reversing (reverse.ts), and line‐ending helpers (line-endings.ts).
• src/convert/ – exporters that convert change lists into other formats: XML (xml.ts) and Google’s DMP format (dmp.ts).
• src/util/ – shared utilities (array merging, distance iterator, param parsing, string helpers).
• src/index.ts – the public façade that imports all diff/patch/convert functions and re-exports them.
Key README insights
• The library implements an optimized Myers diff and exposes:
• Synchronous and asynchronous (callback) modes.
• Abortable (timeout, maxEditLength) modes.
• Strategies for tokenization and equality via options or subclassing.
• It bundles for browser with Rollup into diff.js / diff.min.js.
Main components and their relationships
a. Core Diff Engine
• base.ts defines abstract Diff class plus path‐tracking logic.
• Specialized subclasses or functions in src/diff/* define tokenization and equality.
b. Patch Engine
• create.ts and parse.ts build/parse unified diff patches.
• apply.ts and reverse.ts apply or invert patches.
• Relies on diff engine (diffLines) for structuredPatch and on utilities for line‐ending normalization.
c. Conversion modules
• convert/xml.ts & convert/dmp.ts transform change lists to XML or Diff-Match-Patch format.
d. API Facade (index.ts)
• Wire up named exports: diffChars, diffWords, diffLines, createPatch, applyPatch, etc.
e. Utilities
• Shared helpers under util/ (distance iterator, array helpers, string manipulations).
f. Build/Test/Examples
• Rollup, Babel, Karma for bundling and testing.
• examples/ demonstrates Node and browser usage.
• test/ and test-d/ verify functionality per module.
Architectural patterns & design principles
• Strategy pattern: each diff type defines its own tokenization and equality strategy.
• Factory/Facade: index.ts provides a single façade to create appropriate diff or patch operations.
• Modular layering: clear separation of core algorithm (Diff), patch logic, conversion logic, and utilities.
• Extensibility: consumers can subclass Diff or pass in custom tokenizers/comparators.
• Environment abstraction: code runs in ES5 environments, bundling for browser and Node.