# getTextDiff

## IMPORT

```typescript
import { getTextDiff } from "@donedeal0/superdiff";
```

***

## FORMAT

### Input

```typescript
previousText: string | null | undefined,
currentText: string | null | undefined,
options?: {
    separation?: "character" | "word" | "sentence", // "word" by default
    accuracy?: "normal" | "high", // "normal" by default
    detectMoves?: boolean // false by default
    ignoreCase?: boolean, // false by default
    ignorePunctuation?: boolean, // false by default
    locale?: Intl.Locale | string // undefined by default
  }
```

* `previousText`: the original text.
* `currentText`: the current text.
* `options`
  * `separation` whether you want a `character`, `word` or `sentence` based diff.
  * `accuracy`:
    * `normal` (default): fastest mode, simple tokenization.
    * `high`: slower but exact tokenization. Handles all language subtleties (Unicode, emoji, CJK scripts, locale‑aware segmentation when a locale is provided).
  * `detectMoves`:
    * `false` (default): optimized for readability. Token moves are ignored so insertions don’t cascade and break equality (recommended for UI diffing).
    * `true`: semantically precise, but noiser — a single insertion shifts all following tokens, breaking equality.
  * `ignoreCase`: if `true`, `hello` and `HELLO` are considered equal.
  * `ignorePunctuation`: if `true`, `hello!` and `hello` are considered equal.
  * `locale`: the locale of your text. Enables locale‑aware segmentation in high accuracy mode.

### Output

```typescript
type TextDiff = {
  type: "text";
  status: "added" | "deleted" | "equal" | "updated";
  diff: {
    value: string;
    index: number | null;
    previousValue?: string;
    previousIndex: number | null;
    status: "added" | "deleted" | "equal" | "moved" | "updated";
  }[];
};
```

***

## USAGE

**WITHOUT MOVES DETECTION**

This is the default output. Token moves are ignored so insertions don’t cascade and break equality. Updates are rendered as two entries (`added` + `deleted`). The algorithm uses [longest common subsequence (LCS)](https://en.wikipedia.org/wiki/Longest_common_subsequence), similar to GitHub diffs.

### Input

```diff
getTextDiff(
- "The brown fox jumped high",
+ "The orange cat has jumped",
{ detectMoves: false, separation: "word" }
);
```

### Output

```diff
{
      type: "text",
+     status: "updated",
      diff: [
        {
          value: 'The',
          index: 0,
          previousIndex: 0,
          status: 'equal',
        },
-       {
-         value: "brown",
-         index: null,
-         previousIndex: 1,
-         status: "deleted",
-       },
-       {
-         value: "fox",
-         index: null,
-         previousIndex: 2,
-         status: "deleted",
-       },
+       {
+         value: "orange",
+         index: 1,
+         previousIndex: null,
+         status: "added",
+       },
+       {
+         value: "cat",
+         index: 2,
+         previousIndex: null,
+         status: "added",
+       },
+       {
+         value: "has",
+         index: 3,
+         previousIndex: null,
+         status: "added",
+       },
        {
          value: "jumped",
          index: 4,
          previousIndex: 3,
          status: "equal",
        },
-       {
-         value: "high",
-         index: null,
-         previousIndex: 4,
-         status: "deleted",
-       }
      ],
}
```

**WITH MOVE DETECTION**

If you prefer a semantically precise diff, activate the `detectMoves` option. Direct token swaps are considered `updated`.

**Input**

```diff
getTextDiff(
- "The brown fox jumped high",
+ "The orange cat has jumped",
{ detectMoves: true, separation: "word" }
);
```

**Output**

```diff
{
      type: "text",
+     status: "updated",
      diff: [
        {
          value: 'The',
          index: 0,
          previousIndex: 0,
          status: 'equal',
        },
+       {
+         value: "orange",
+         index: 1,
+         previousValue: "brown",
+         previousIndex: null,
+         status: "updated",
+       },
+       {
+         value: "cat",
+         index: 2,
+         previousValue: "fox",
+         previousIndex: null,
+         status: "updated",
+       },
+       {
+         value: "has",
+         index: 3,
+         previousIndex: null,
+         status: "added",
+       },
+       {
+         value: "jumped",
+         index: 4,
+         previousIndex: 3,
+         status: "moved",
+       },
-       {
-         value: "high",
-         index: null,
-         previousIndex: 4,
-         status: "deleted",
-       }
      ],
}
```