# @vscode/diff

> ⚠️ **Experimental** — this package is in early development. The API may change without notice and bugs are expected. Do not depend on it for production workloads yet.

A high-performance diff library, ported from the diff algorithm used inside VS Code. Ships with two interchangeable backends:

- **TypeScript** (default) — pure JS, no native dependencies.
- **WebAssembly** — same algorithm compiled from Rust via `wasm-pack`. Typically ~1.5–3× faster on larger inputs.

Both produce identical results.

## Install

```sh
npm install @vscode/diff
```

## Usage

```ts
import { createDiffComputer } from '@vscode/diff';

// TS backend (synchronous-feeling, no init required)
const ts = await createDiffComputer();
const result = ts.computeDiff(original, modified, {
    ignoreTrimWhitespace: false,
    computeMoves: false,
});

// WASM backend (loads the .wasm module on first call)
const wasm = await createDiffComputer({ useWasm: true });
const result2 = wasm.computeDiff(original, modified);
```

`computeDiff` returns a [`DiffResult`](./src/diff/api/types.ts) containing:

- `edits` — an `AnnotatedStringEdit` describing the text-level changes (offset-based, suitable for applying directly).
- `moves` — detected block moves (when `computeMoves: true`).
- `hitTimeout` — `true` if computation exceeded `maxComputationTimeMs`.

### Options

| Option | Default | Description |
|---|---|---|
| `maxComputationTimeMs` | `0` (no limit) | Cap the diff time; falls back to a coarser result on timeout. |
| `ignoreTrimWhitespace` | `false` | Treat lines as equal when they differ only in leading/trailing whitespace. |
| `computeMoves` | `false` | Detect moved blocks. |
| `extendToSubwords` | `false` | Refine inner changes to subword boundaries. |

## Performance

Across all bundled test fixtures (46 cases, total median time in ms):

| Backend | Total | vs TS | vs native Rust |
|---|---:|---:|---:|
| TS (V8) | 113.7 | 1.00× | 2.86× slower |
| WASM | 72.5 | 0.64× | 1.82× slower |
| Native Rust (reference) | 39.8 | 0.35× | 1.00× |

Run `node scripts/bench.mjs` to reproduce.

## License

MIT — see [LICENSE](./LICENSE).