# kpdecker/jsdiff architecture

> Architecture diagram of the GitHub repository kpdecker/jsdiff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kpdecker/jsdiff
- Repository: https://github.com/kpdecker/jsdiff

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% API Layer
    subgraph "API Layer"
        API["API Facade"]:::api
    end

    %% Diff Modules
    subgraph "Core Diff Modules"
        Base["Diff Base"]:::diff
        Arr["Array Diff"]:::diff
        Char["Character Diff"]:::diff
        CSS["CSS Diff"]:::diff
        JSONM["JSON Diff"]:::diff
        LineD["Line Diff"]:::diff
        Sent["Sentence Diff"]:::diff
        Word["Word Diff"]:::diff
    end

    %% Patch Modules
    subgraph "Patch Modules"
        Create["Create Patch"]:::patch
        Parse["Parse Patch"]:::patch
        Apply["Apply Patch"]:::patch
        Reverse["Reverse Patch"]:::patch
        LineEnd["Line-Ending Helpers"]:::patch
    end

    %% Convert Modules
    subgraph "Conversion Modules"
        DMP["DMP Exporter"]:::convert
        XML["XML Exporter"]:::convert
    end

    %% Utilities
    subgraph "Utilities"
        UArr["Array Helpers"]:::util
        UDist["Distance Iterator"]:::util
        UParams["Param Parsing"]:::util
        UStr["String Helpers"]:::util
    end

    %% External Interfaces
    subgraph "External Interfaces"
        NodeEnv(("Node.js Env")):::external
        ESMod(("ES Modules")):::external
        Browser(("Browser Global")):::external
        Bundle["dist/diff.js"]:::tool
    end

    %% Build & Test Tools
    subgraph "Build & Test Tools" 
        style BuildTest fill:none,stroke:#888,stroke-dasharray: 5 5
        Rollup["Rollup"]:::tool
        Babel["Babel"]:::tool
        Karma["Karma"]:::tool
        Runtime["Runtime Support"]:::tool
        TSConf["tsconfig.json"]:::tool
        Examples["Examples"]:::tool
        Tests["Test Suites"]:::tool
    end

    %% Connections
    API -->|"exports functions"| Base
    API -->|"exports functions"| Create
    API -->|"exports functions"| Parse
    API -->|"exports functions"| Apply
    API -->|"exports functions"| Reverse
    API -->|"exports functions"| DMP
    API -->|"exports functions"| XML

    Base --> Arr
    Base --> Char
    Base --> CSS
    Base --> JSONM
    Base --> LineD
    Base --> Sent
    Base --> Word

    Create -->|"uses Diff"| Base
    Create -->|"normalizes endings"| LineEnd
    Parse -->|"parses patch"| Apply
    Apply -->|"applies diff"| Base
    Reverse -->|"inverts patch"| Apply
    LineEnd -->|"uses utilities"| UStr

    DMP -->|"consumes changes"| Base
    XML -->|"consumes changes"| Base

    NodeEnv -->|require/import| API
    ESMod -->|import/export| API
    Browser -->|global window.Diff| Bundle
    Bundle -->|bundled by| Rollup

    Rollup --> Babel
    Rollup --> Runtime
    Rollup --> TSConf
    Karma --> Base
    Karma --> Create
    Karma --> DMP
    Examples --> API
    Tests --> Base

    %% Click events
    click API "https://github.com/kpdecker/jsdiff/blob/master/src/index.ts"
    click Base "https://github.com/kpdecker/jsdiff/blob/master/src/diff/base.ts"
    click Arr "https://github.com/kpdecker/jsdiff/blob/master/src/diff/array.ts"
    click Char "https://github.com/kpdecker/jsdiff/blob/master/src/diff/character.ts"
    click CSS "https://github.com/kpdecker/jsdiff/blob/master/src/diff/css.ts"
    click JSONM "https://github.com/kpdecker/jsdiff/blob/master/src/diff/json.ts"
    click LineD "https://github.com/kpdecker/jsdiff/blob/master/src/diff/line.ts"
    click Sent "https://github.com/kpdecker/jsdiff/blob/master/src/diff/sentence.ts"
    click Word "https://github.com/kpdecker/jsdiff/blob/master/src/diff/word.ts"
    click Create "https://github.com/kpdecker/jsdiff/blob/master/src/patch/create.ts"
    click Parse "https://github.com/kpdecker/jsdiff/blob/master/src/patch/parse.ts"
    click Apply "https://github.com/kpdecker/jsdiff/blob/master/src/patch/apply.ts"
    click Reverse "https://github.com/kpdecker/jsdiff/blob/master/src/patch/reverse.ts"
    click LineEnd "https://github.com/kpdecker/jsdiff/blob/master/src/patch/line-endings.ts"
    click DMP "https://github.com/kpdecker/jsdiff/blob/master/src/convert/dmp.ts"
    click XML "https://github.com/kpdecker/jsdiff/blob/master/src/convert/xml.ts"
    click UArr "https://github.com/kpdecker/jsdiff/blob/master/src/util/array.ts"
    click UDist "https://github.com/kpdecker/jsdiff/blob/master/src/util/distance-iterator.ts"
    click UParams "https://github.com/kpdecker/jsdiff/blob/master/src/util/params.ts"
    click UStr "https://github.com/kpdecker/jsdiff/blob/master/src/util/string.ts"
    click Rollup "https://github.com/kpdecker/jsdiff/blob/master/rollup.config.mjs"
    click Babel "https://github.com/kpdecker/jsdiff/blob/master/.babelrc"
    click Karma "https://github.com/kpdecker/jsdiff/blob/master/karma.conf.js"
    click Runtime "https://github.com/kpdecker/jsdiff/blob/master/runtime.js"
    click TSConf "https://github.com/kpdecker/jsdiff/blob/master/tsconfig.json"
    click Examples "https://github.com/kpdecker/jsdiff/tree/master/examples/"
    click Tests "https://github.com/kpdecker/jsdiff/tree/master/test/"

    %% Styles
    classDef api fill:#D0E6FF,stroke:#0366d6;
    classDef diff fill:#DFFFE0,stroke:#28a745;
    classDef patch fill:#FFE8C4,stroke:#d9930e;
    classDef convert fill:#F3E0FF,stroke:#6f42c1;
    classDef util fill:#E0E0E0,stroke:#6a737d;
    classDef tool fill:#F0F0F0,stroke:#888888;
    classDef external fill:#FFF0D0,stroke:#e36209,stroke-width:2px;
```
