|
| 1 | +# text-diff-patch |
| 2 | + |
| 3 | +Zero-dependency line-based diff and patch for TypeScript/JavaScript: Myers |
| 4 | +O(ND) diff producing unified-diff-style hunks, fuzzy patch application with |
| 5 | +reject reporting, and a word-level intra-line diff highlighter. |
| 6 | + |
| 7 | +## Why |
| 8 | + |
| 9 | +Most diff libraries either only diff or only apply, and few report *why* a |
| 10 | +hunk failed to apply against a shifted file. This package does both |
| 11 | +directions with zero runtime dependencies, strict TypeScript, and an |
| 12 | +explicit `fuzz` tolerance for applying patches against slightly-moved text — |
| 13 | +the case agents hit constantly when re-applying an edit to a file that |
| 14 | +changed underneath them. |
| 15 | + |
| 16 | +## Install |
| 17 | + |
| 18 | +```bash |
| 19 | +npm install text-diff-patch |
| 20 | +``` |
| 21 | + |
| 22 | +## Quickstart |
| 23 | + |
| 24 | +```ts |
| 25 | +import { createPatch, applyPatch, highlightWordDiff } from "text-diff-patch"; |
| 26 | + |
| 27 | +const patch = createPatch(oldText, newText, { oldFile: "a", newFile: "b" }); |
| 28 | +console.log(patch); // unified-diff-style string |
| 29 | + |
| 30 | +const { result, applied, rejects } = applyPatch(oldText, patch, { fuzz: 3 }); |
| 31 | +// applied: number of hunks applied; rejects: hunks that couldn't be placed |
| 32 | + |
| 33 | +highlightWordDiff("hello world", "hello there"); |
| 34 | +// "hello {-world-}{+there+}" |
| 35 | +``` |
| 36 | + |
| 37 | +## API |
| 38 | + |
| 39 | +### `myersDiff(a: string[], b: string[]): DiffOp[]` |
| 40 | +Raw Myers O(ND) line-array diff. `DiffOp = { type: "equal"|"delete"|"insert", value: string }`. |
| 41 | + |
| 42 | +### `toLines(text: string): string[]` |
| 43 | +Splits text into lines (`""` → `[]`). |
| 44 | + |
| 45 | +### `buildHunks(ops: DiffOp[], context = 3): Hunk[]` |
| 46 | +Groups a `DiffOp[]` into unified-diff hunks with `context` lines of |
| 47 | +surrounding unchanged text; adjacent changes within `2 * context` lines |
| 48 | +merge into one hunk. |
| 49 | + |
| 50 | +### `createPatch(oldText: string, newText: string, options?: CreatePatchOptions): string` |
| 51 | +Full unified-diff text. `CreatePatchOptions = { context?: number; oldFile?: string; newFile?: string }`. |
| 52 | + |
| 53 | +### `parsePatch(patchText: string): Hunk[]` |
| 54 | +Parses a unified-diff string back into `Hunk[]` (`{ oldStart, oldLines, newStart, newLines, lines }`). |
| 55 | + |
| 56 | +### `applyPatch(text: string, patch: string | Hunk[], options?: ApplyOptions): ApplyResult` |
| 57 | +Applies hunks to `text`. `ApplyOptions = { fuzz?: number }` — with `fuzz > 0`, |
| 58 | +a hunk whose exact recorded line is off is retried at nearby offsets |
| 59 | +(±1..±fuzz) before being rejected. |
| 60 | +`ApplyResult = { result: string; applied: number; rejects: RejectedHunk[] }`, |
| 61 | +`RejectedHunk = { hunk: Hunk; reason: string }`. |
| 62 | + |
| 63 | +### `tokenizeWords(line: string): string[]` |
| 64 | +Splits a line into word/whitespace tokens, exactly reconstructible via `join("")`. |
| 65 | + |
| 66 | +### `diffWords(a: string, b: string): DiffOp[]` |
| 67 | +Word-level Myers diff over tokenized lines. |
| 68 | + |
| 69 | +### `highlightWordDiff(a: string, b: string, options?: HighlightOptions): string` |
| 70 | +Renders a word-diff as one string with insertions/deletions wrapped in |
| 71 | +markers. `HighlightOptions = { insertOpen?, insertClose?, deleteOpen?, deleteClose? }` |
| 72 | +(defaults: `{+...+}` / `{-...-}`). |
| 73 | + |
| 74 | +## Limits |
| 75 | + |
| 76 | +- Line-based only — `myersDiff`/`createPatch` operate on `\n`-split lines, |
| 77 | + not characters (use `diffWords` for intra-line detail). |
| 78 | +- `applyPatch`'s fuzz search is a bounded ±N-line offset retry per hunk, not |
| 79 | + a general approximate-matching algorithm — very large shifts or heavily |
| 80 | + edited context will still reject. |
| 81 | +- No binary-file support; input is always treated as text. |
| 82 | +- `parsePatch` expects hunk bodies to use exactly one leading `' '`/`'+'`/`'-'` |
| 83 | + per line (standard unified-diff shape) — it does not tolerate tab-indented |
| 84 | + or CRLF-mixed patches. |
| 85 | + |
| 86 | +--- |
| 87 | +Part of the [ferrow-toolkit](https://github.com/Ruzylo-cloud/ferrow-toolkit) collection · Sponsored by [Ferrow](https://ferrow.ai) |
0 commit comments