Superdiff

https://donedeal0.gitbook.io/superdiff/
Admin
Superdiff provides rich and readable diffs for arrays, objects, texts, and coordinates with support...
Tokens:9,055
Snippets:63
Trust Score:9.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Usage Example

Source: https://donedeal0.gitbook.io/superdiff/features/getgeodiff

Example showing the input coordinates and the resulting output object structure.

```diff
getGeoDiff(
- [2.3522, 48.8566],
+ [-0.1278, 51.5074]
);
```

```diff
{
      type: "geo",
+     status: "updated",
      diff: {
+          coordinates: [-0.1278, 51.5074],
           previousCoordinates: [2.3522, 48.8566],
+          direction: "north-west",
+          distance: 343.56,
+          label: "343.56 kilometers",
+          unit: "kilometer"
        }
}
```

--------------------------------

### Usage with Files

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/client

Example of comparing two JSON files uploaded or stored locally.

```typescript
const previousFile = new File([JSON.stringify(previousArrayFile)], 
                              "previousArray.json", 
                              { type: "application/json" }); 
                              
const nextFile = new File([JSON.stringify(nextArrayFile)], 
                              "nextArray.json", 
                              { type: "application/json" }); 
                              
const diff = streamListDiff(previousFile, nextFile, "id", { chunksSize: 10 });
```

--------------------------------

### Usage Example for getObjectDiff

Source: https://donedeal0.gitbook.io/superdiff/features/getobjectdiff

Demonstrates comparing two objects with nested properties and arrays.

```diff
getObjectDiff(
  {
    id: 54,
    user: {
      name: "joe",
-     member: true,
-     hobbies: ["golf", "football"],
      age: 66,
    },
  },
  {
    id: 54,
    user: {
      name: "joe",
+     member: false,
+     hobbies: ["golf", "chess"],
      age: 66,
    },
  }
);
```

```diff
{
      type: "object",
+     status: "updated",
      diff: [
        {
          key: "id",
          value: 54,
          previousValue: 54,
          status: "equal",
        },
        {
          key: "user",
          value: {
            name: "joe",
            member: false,
            hobbies: ["golf", "chess"],
            age: 66,
          },
          previousValue: {
            name: "joe",
            member: true,
            hobbies: ["golf", "football"],
            age: 66,
          },
+         status: "updated",
          diff: [
            {
              key: "name",
              value: "joe",
              previousValue: "joe",
              status: "equal",
            },
+           {
+             key: "member",
+             value: false,
+             previousValue: true,
+             status: "updated",
+           },
+           {
+             key: "hobbies",
+             value: ["golf", "chess"],
+             previousValue: ["golf", "football"],
+             status: "updated",
+           },
            {
              key: "age",
              value: 66,
              previousValue: 66,
              status: "equal",
            },
          ],
        },
      ],
    }
```

--------------------------------

### Usage Example

Source: https://donedeal0.gitbook.io/superdiff/features/getlistdiff

Example of comparing two arrays using getListDiff.

```typescript
getListDiff(
- ["mbappe", "mendes", "verratti", "ruiz"],
+ ["mbappe", "messi", "ruiz"]
);
```

```diff
{
      type: "list",
+     status: "updated",
      diff: [
        {
          value: "mbappe",
          index: 0,
          previousIndex: 0,
          status: "equal",
        },
-       {
-         value: "mendes",
-         index: null,
-         previousIndex: 1,
-         status: "deleted",
-       },
-       {
-         value: "verratti",
-         index: null,
-         previousIndex: 2,
-         status: "deleted",
-       },
+       {
+         value: "messi",
+         index: 1,
+         previousIndex: null,
+         status: "added",
+       },
+       {
+         value: "ruiz",
+         index: 2,
+         previousIndex: 3,
+         status: "moved",
        },
      ],
    }
```

--------------------------------

### Install Superdiff with Bun

Source: https://donedeal0.gitbook.io/superdiff/getting-started/installation

Use this command to add Superdiff to your project's dependencies using Bun.

```bash
bun add @donedeal0/superdiff
```

--------------------------------

### Diff Example Visualization

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/client

Visual representation of the diff operation showing added and updated items.

```diff
const diff = streamListDiff(
      [ 
-       { id: 1, name: "Item 1" },  
        { id: 2, name: "Item 2" },
        { id: 3, name: "Item 3" } 
      ],
      [
+       { id: 0, name: "Item 0" }, 
        { id: 2, name: "Item 2" },
+       { id: 3, name: "Item Three" },
      ],
      "id", 
      { chunksSize: 2 }
    );
```

--------------------------------

### Input Diff Example

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

A diff output showing changes between two lists. '-' indicates deleted items, '+' indicates added items.

```diff
const diff = streamListDiff(
      [
-       { id: 1, name: "Item 1" },
        { id: 2, name: "Item 2" },
        { id: 3, name: "Item 3" }
      ],
      [
+       { id: 0, name: "Item 0" },
        { id: 2, name: "Item 2" },
+       { id: 3, name: "Item Three" },
      ],
      "id",
      { chunksSize: 2 }
    );
```

--------------------------------

### Install Superdiff with NPM

Source: https://donedeal0.gitbook.io/superdiff/getting-started/installation

Use this command to add Superdiff to your project's dependencies using NPM.

```bash
npm install @donedeal0/superdiff
```

--------------------------------

### Install Superdiff with Yarn

Source: https://donedeal0.gitbook.io/superdiff/getting-started/installation

Use this command to add Superdiff to your project's dependencies using Yarn.

```bash
yarn add @donedeal0/superdiff
```

--------------------------------

### Usage with ReadableStreams

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/client

Example of comparing two ReadableStreams containing object data.

```typescript
const previousStream = new ReadableStream({
      start(controller) {
        previousArray.forEach((value) => controller.enqueue(value));
        controller.close();
      },
    }); 
    
const nextStream = new ReadableStream({
      start(controller) {
        nextArray.forEach((value) => controller.enqueue(value));
        controller.close();
      },
    }); 
    
const diff = streamListDiff(previousStream, nextStream, "id", { chunksSize: 2 });
```

--------------------------------

### Usage with Arrays

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/client

Example of comparing two arrays of objects using a reference key.

```typescript

const diff = streamListDiff(
      [ 
        { id: 1, name: "Item 1" },  
        { id: 2, name: "Item 2" },
        { id: 3, name: "Item 3" } 
      ],
      [
        { id: 0, name: "Item 0" }, 
        { id: 2, name: "Item 2" },
        { id: 3, name: "Item Three" },
      ],
      "id", 
      { chunksSize: 2 }
    );
```

--------------------------------

### Output Event Handling

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

Example of handling 'data' events from the diff stream to process chunks of object diffs. Also shows 'finish' and 'error' event handling.

```diff
diff.on("data", (chunk) => {
      // first chunk received (2 object diffs)
      [
+       {
+         value: { id: 0, name: "Item 0" },
+         index: 0,
+         previousValue: null,
+         previousIndex: null,
+         status: "added"
+       },
-       {
-         value: null,
-         index: null,
-         previousValue: { id: 1, name: "Item 1" },
-         previousIndex: 0,
-         status: "deleted"
-       }
      ]
    // second chunk received (2 object diffs)
      [
        {
          value: { id: 2, name: "Item 2" },
          index: 1,
          previousValue: { id: 2, name: "Item 2" },
          previousIndex: 1,
          status: "equal"
        },
+       {
+         value: { id: 3, name: "Item Three" },
+         index: 2,
+         previousValue: { id: 3, name: "Item 3" },
+         previousIndex: 2,
+         status: "updated"
+       },
     ]
});

diff.on("finish", () => console.log("Your data has been processed. The full diff is available."))
diff.on("error", (err) => console.log(err))
```

--------------------------------

### Usage: File Input

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

Example of using streamListDiff with file paths. The paths should point to JSON files containing arrays of objects.

```typescript
const previousFile = path.resolve(__dirname, "./previousArrayFile.json"); 
                              
const nextFile = path.resolve(__dirname, "./previousArrayFile.json");
                              
const diff = streamListDiff(previousFile, nextFile, "id", { chunksSize: 10 });
```

--------------------------------

### getTextDiff Usage (With Moves Detection)

Source: https://donedeal0.gitbook.io/superdiff/features/gettextdiff

Example of using getTextDiff with `detectMoves: true`. This mode provides a semantically precise diff where direct token swaps are marked as 'updated'.

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

```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",
-       }
      ],
}
```

--------------------------------

### getTextDiff Usage (Without Moves Detection)

Source: https://donedeal0.gitbook.io/superdiff/features/gettextdiff

Example of using getTextDiff with `detectMoves: false`. This mode ignores token moves, rendering updates as added and deleted entries for better UI diffing.

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

```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",
-       }
      ],
}
```

--------------------------------

### Usage: Array Input

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

Example of using streamListDiff with arrays as input. The referenceKey 'id' is used for comparison, and chunksSize is set to 2.

```typescript
const diff = streamListDiff(
      [
        { id: 1, name: "Item 1" },
        { id: 2, name: "Item 2" },
        { id: 3, name: "Item 3" }
      ],
      [
        { id: 0, name: "Item 0" },
        { id: 2, name: "Item 2" },
        { id: 3, name: "Item Three" },
      ],
      "id",
      { chunksSize: 2 }
    );
```

--------------------------------

### Usage: Stream Input

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

Example of using streamListDiff with Readable streams. Ensure objectMode is set to true for streams containing objects.

```typescript
const previousStream = Readable.from(previousArray, { objectMode: true });
    
const nextStream = Readable.from(nextArray, { objectMode: true });
    
const diff = streamListDiff(previousStream, nextStream, "id", { chunksSize: 2 });
```

--------------------------------

### Import streamListDiff

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/client

Import the main function from the client package. Requires ESM support for browser environments.

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

--------------------------------

### Import getListDiff

Source: https://donedeal0.gitbook.io/superdiff/features/getlistdiff

Import the function from the package.

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

--------------------------------

### Server Input Format

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

Defines the expected types for previous and next lists, and the options object for streamListDiff. Readable streams may impact worker performance.

```typescript
prevList: Readable | FilePath | Record<string, unknown>[],
 nextList: Readable | FilePath | Record<string, unknown>[],
 referenceKey: keyof Record<string, unknown>,
 options: {
  showOnly?: ("added" | "deleted" | "moved" | "updated" | "equal")[], // [] by default
  chunksSize?: number, // 0 by default
  considerMoveAsUpdate?: boolean; // false by default
  useWorker?: boolean; // true by default
  showWarnings?: boolean; // true by default
}
```

--------------------------------

### Import getGeoDiff

Source: https://donedeal0.gitbook.io/superdiff/features/getgeodiff

Import the function from the @donedeal0/superdiff package.

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

--------------------------------

### Define streamListDiff Input Parameters

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/client

Configuration object structure for defining input lists, reference keys, and processing options.

```typescript
 prevList: ReadableStream<Record<string, unknown>> | File | Record<string, unknown>[],
 nextList: ReadableStream<Record<string, unknown>> | File | Record<string, unknown>[],
 referenceKey: keyof Record<string, unknown>,
 options: {
  showOnly?: ("added" | "deleted" | "moved" | "updated" | "equal")[], // [] by default
  chunksSize?: number, // 0 by default
  considerMoveAsUpdate?: boolean; // false by default
  useWorker?: boolean; // true by default
  showWarnings?: boolean; // true by default

}
```

--------------------------------

### Import streamListDiff Function

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

Import the necessary function for streaming list diffs from the Superdiff server module.

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

--------------------------------

### Import getObjectDiff

Source: https://donedeal0.gitbook.io/superdiff/features/getobjectdiff

Import the function from the @donedeal0/superdiff package.

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

--------------------------------

### Define getObjectDiff Input and Output Types

Source: https://donedeal0.gitbook.io/superdiff/features/getobjectdiff

The input requires two objects and optional configuration, while the output provides a recursive diff structure.

```typescript
prevData: Record<string, unknown>;
nextData: Record<string, unknown>;
options?: {
  ignoreArrayOrder?: boolean, // false by default,
  showOnly?: {
    statuses: ("added" | "deleted" | "updated" | "equal")[], // [] by default
    granularity?: "basic" | "deep" // "basic" by default
  }
}
```

```typescript
type ObjectDiff = {
  type: "object";
  status: "added" | "deleted" | "equal" | "updated";
  diff: Diff[];
};

type Diff = {
  key: string;
  value: unknown;
  previousValue: unknown;
  status: "added" | "deleted" | "equal" | "updated";
  // recursive diff in case of subproperties
  diff?: Diff[];
};
```

--------------------------------

### getTextDiff Input Parameters

Source: https://donedeal0.gitbook.io/superdiff/features/gettextdiff

Defines the input parameters for getTextDiff, including previous and current text, and an optional options object for customization.

```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
  }
```

--------------------------------

### Import getTextDiff Function

Source: https://donedeal0.gitbook.io/superdiff/features/gettextdiff

Import the getTextDiff function from the super-diff library. This is the primary function for generating text differences.

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

--------------------------------

### streamListDiff

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

Compares two lists of objects and streams the differences.

```APIDOC
## streamListDiff

### Description
Compares two lists of objects (prevList and nextList) based on a referenceKey and streams the differences in chunks. Supports input from arrays, NodeJS Readable streams, or file paths.

### Parameters
#### Request Body
- **prevList** (Readable | FilePath | Record<string, unknown>[]) - Required - The original object list.
- **nextList** (Readable | FilePath | Record<string, unknown>[]) - Required - The new object list.
- **referenceKey** (keyof Record<string, unknown>) - Required - A key common to all objects in the lists (e.g., 'id').
- **options** (Object) - Optional
  - **showOnly** (Array) - Optional - Filter results by status: 'added', 'deleted', 'moved', 'updated', or 'equal'.
  - **chunksSize** (number) - Optional - Number of object diffs per chunk (0 = 1 per chunk).
  - **considerMoveAsUpdate** (boolean) - Optional - If true, 'moved' status is treated as 'updated'.
  - **useWorker** (boolean) - Optional - If true, runs diff in a worker thread (default: true).
  - **showWarnings** (boolean) - Optional - If true, displays potential warnings in the console.

### Response
#### Success Response (Event-based)
- **data** (Event) - Emits a chunk of object diffs (Array of StreamListDiff).
- **finish** (Event) - Emits when the stream is complete.
- **error** (Event) - Emits if an error occurs.

#### Response Example
{
  "value": { "id": 0, "name": "Item 0" },
  "index": 0,
  "previousValue": null,
  "previousIndex": null,
  "status": "added"
}
```

--------------------------------

### Define getGeoDiff Input Structure

Source: https://donedeal0.gitbook.io/superdiff/features/getgeodiff

The input expects previous and new coordinates as [longitude, latitude] tuples, with optional configuration for units, accuracy, decimals, and locale.

```typescript
previousCoordinates: [number, number] | null | undefined;
  coordinates: [number, number] | null | undefined;
  options?: {
    unit?: "centimeter" | "foot" | "inch" | "kilometer" | "meter" | "mile" | "mile-scandinavian" | "millimeter" | "yard"; // "kilometer" by default
    accuracy?: "normal" | "high"; // "normal" by default
    maxDecimals?: number; // 2 by default,
    locale?: Intl.Locale | string; // "en-US" by default
  }
```

--------------------------------

### Define getListDiff Output Type

Source: https://donedeal0.gitbook.io/superdiff/features/getlistdiff

Structure of the returned diff object.

```typescript
type ListDiff = {
type ListDiff = {
  type: "list";
  status: "added" | "deleted" | "equal" | "moved" | "updated";
  diff: {
    value: unknown;
    index: number | null;
    previousIndex: number | null;
    status: "added" | "deleted" | "equal" | "moved" | "updated";
  }[];
};
```

--------------------------------

### Define getListDiff Input Format

Source: https://donedeal0.gitbook.io/superdiff/features/getlistdiff

Structure of the input parameters for the getListDiff function.

```typescript
prevList: T[];
  nextList: T[];
  options?: {
    showOnly?: ("added" | "deleted" | "moved" | "updated" | "equal")[], // [] by default
    referenceKey?: string, // "" by default
    ignoreArrayOrder?: boolean, // false by default,
    considerMoveAsUpdate?: boolean // false by default
  }
```

--------------------------------

### Server Output StreamListener Interface

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

Defines the structure of the StreamListener interface for consuming diff results. It includes event handlers for 'data', 'finish', and 'error'.

```typescript
interface StreamListener<T> {
  on(event: "data", listener: (chunk: StreamListDiff<T>[]) => void);
  on(event: "finish", listener: () => void);
  on(event: "error", listener: (error: Error) => void);
}
```

--------------------------------

### Define StreamListener and Diff Interfaces

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/client

Interfaces for handling stream events and the structure of returned diff objects.

```typescript
interface StreamListener<T> {
  on(event: "data", listener: (chunk: StreamListDiff<T>[]) => void);
  on(event: "finish", listener: () => void);
  on(event: "error", listener: (error: Error) => void);
}

type StreamListDiff<T extends Record<string, unknown>> = {
  value: T | null;
  index: number | null;
  previousValue: T | null;
  previousIndex: number | null;
  status: "added" | "deleted" | "moved" | "updated" | "equal";
};
```

--------------------------------

### React Hook for Streaming List Diffs

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/client

This React hook, `useListDiff`, fetches lists, generates a diff stream, and updates the component's state with incoming diff chunks. It's designed for efficient, real-time rendering of list changes in a React application.

```tsx
export function useListDiff() {
  const [list, setList] = useState<StreamListDiff<Data>[]>([]);
  const [isStreaming, setIsStreaming] = useState(false);
  const [isError, setIsError] = useState<Error>();

  const getListDiff = useCallback(async () => {
    setIsStreaming(true);
    const [prevList, nextList] = await fetchLists()
    const diff = streamListDiff(prevList, nextList, "id", {
      chunksSize: 50000, // Large chunks size for fewer updates
      useWorker: true,
    });

    diff.on("data", (chunk) => {
      // Schedule state updates on the next frame for smooth rendering
      requestAnimationFrame(() => {
        setList((prev) => [...prev, ...chunk]);
      });
    });
    diff.on("finish", () => setIsStreaming(false));
    diff.on("error", (err) => {
      setIsStreaming(false);
      setIsError(err);
    });
  }, []);

  useEffect(() => {
    getListDiff();
  }, [getListDiff]);

  return {
    list,
    isStreaming,
    isError,
  };
}
```

--------------------------------

### getListDiff Function

Source: https://donedeal0.gitbook.io/superdiff/features/getlistdiff

Compares two arrays and returns a structured diff object based on provided options.

```APIDOC
## getListDiff

### Description
Compares two lists (prevList and nextList) and returns a diff object detailing the status of each element.

### Parameters
#### Request Body
- **prevList** (T[]) - Required - The original list.
- **nextList** (T[]) - Required - The new list.
- **options** (Object) - Optional - Configuration for the comparison:
  - **showOnly** (Array) - Optional - Filter results by status (added, deleted, moved, updated, equal).
  - **referenceKey** (string) - Optional - Key to track object identity (e.g., 'id').
  - **ignoreArrayOrder** (boolean) - Optional - If true, treats arrays with same elements in different order as equal.
  - **considerMoveAsUpdate** (boolean) - Optional - If true, treats moved items as updated.

### Response
#### Success Response (200)
- **type** (string) - Always 'list'.
- **status** (string) - Overall status of the list comparison.
- **diff** (Array) - List of objects containing value, index, previousIndex, and status for each item.

### Request Example
getListDiff(["mbappe", "mendes", "verratti", "ruiz"], ["mbappe", "messi", "ruiz"])

### Response Example
{
  "type": "list",
  "status": "updated",
  "diff": [
    { "value": "mbappe", "index": 0, "previousIndex": 0, "status": "equal" },
    { "value": "mendes", "index": null, "previousIndex": 1, "status": "deleted" },
    { "value": "verratti", "index": null, "previousIndex": 2, "status": "deleted" },
    { "value": "messi", "index": 1, "previousIndex": null, "status": "added" },
    { "value": "ruiz", "index": 2, "previousIndex": 3, "status": "moved" }
  ]
}
```

--------------------------------

### getObjectDiff Function

Source: https://donedeal0.gitbook.io/superdiff/features/getobjectdiff

Compares two objects (prevData and nextData) and returns a structured diff object. Supports options for array order sensitivity and filtering by status or granularity.

```APIDOC
## getObjectDiff

### Description
Compares two objects and returns a detailed diff structure indicating added, deleted, equal, or updated properties.

### Parameters
#### Request Body
- **prevData** (Record<string, unknown>) - Required - The original object.
- **nextData** (Record<string, unknown>) - Required - The new object.
- **options** (Object) - Optional - Configuration for the comparison.
  - **ignoreArrayOrder** (boolean) - Optional - If true, treats arrays with same elements in different order as equal.
  - **showOnly** (Object) - Optional - Filter results by status and granularity.
    - **statuses** (Array) - Optional - Statuses to include in output.
    - **granularity** (string) - Optional - 'basic' or 'deep' filtering.

### Request Example
{
  "prevData": { "id": 54, "user": { "name": "joe", "member": true } },
  "nextData": { "id": 54, "user": { "name": "joe", "member": false } }
}

### Response
#### Success Response (200)
- **type** (string) - The type of the diff (always 'object').
- **status** (string) - Overall status of the object comparison.
- **diff** (Array) - List of differences found.

#### Response Example
{
  "type": "object",
  "status": "updated",
  "diff": [
    { "key": "id", "value": 54, "previousValue": 54, "status": "equal" },
    { "key": "user", "status": "updated", "diff": [...] }
  ]
}
```

--------------------------------

### getTextDiff Output Type

Source: https://donedeal0.gitbook.io/superdiff/features/gettextdiff

Defines the structure of the TextDiff output, detailing the type, status, and a list of differences with their values and statuses.

```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";
  }[];
};
```

--------------------------------

### getTextDiff Function

Source: https://donedeal0.gitbook.io/superdiff/features/gettextdiff

The `getTextDiff` function computes the differences between two text inputs. It supports various options to customize the diffing process, including separation granularity, accuracy, and move detection.

```APIDOC
## getTextDiff Function

### Description
Calculates the differences between two text strings, with options for customization.

### Method
Function Call

### Endpoint
N/A (Client-side function)

### Parameters
#### Input Parameters
- **previousText** (string | null | undefined) - The original text.
- **currentText** (string | null | undefined) - The current text.
- **options** (object, optional) - Configuration for the diffing process.
  - **separation** ("character" | "word" | "sentence") - The granularity of comparison. Defaults to "word".
  - **accuracy** ("normal" | "high") - The accuracy level for tokenization. Defaults to "normal".
  - **detectMoves** (boolean) - Whether to detect token moves. Defaults to `false`.
  - **ignoreCase** (boolean) - Whether to ignore case during comparison. Defaults to `false`.
  - **ignorePunctuation** (boolean) - Whether to ignore punctuation during comparison. Defaults to `false`.
  - **locale** (Intl.Locale | string) - The locale for text segmentation. Defaults to `undefined`.

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

const diffResult = getTextDiff(
  "The brown fox jumped high",
  "The orange cat has jumped",
  { detectMoves: false, separation: "word" }
);
```

### Response
#### Success Response (TextDiff Object)
- **type** (string) - Always "text".
- **status** (string) - The overall status of the diff: "added", "deleted", "equal", or "updated".
- **diff** (array) - An array of diff objects detailing the changes.
  - **value** (string) - The text value of the diff segment.
  - **index** (number | null) - The index of the segment in the current text.
  - **previousValue** (string, optional) - The text value in the previous text (for "updated" or "moved" status).
  - **previousIndex** (number | null) - The index of the segment in the previous text.
  - **status** (string) - The status of the individual segment: "added", "deleted", "equal", "moved", or "updated".

#### Response Example (detectMoves: false)
```json
{
  "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"
    }
  ]
}
```

#### Response Example (detectMoves: true)
```json
{
  "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"
    }
  ]
}
```
```

--------------------------------

### getGeoDiff Function

Source: https://donedeal0.gitbook.io/superdiff/features/getgeodiff

Calculates the geographic difference between two coordinate points.

```APIDOC
## getGeoDiff

### Description
Calculates the difference between two sets of geographic coordinates, providing the distance, direction, and status of the change.

### Parameters
#### Request Body
- **previousCoordinates** ([number, number] | null | undefined) - Required - The original coordinates [Longitude, Latitude].
- **coordinates** ([number, number] | null | undefined) - Required - The new coordinates [Longitude, Latitude].
- **options** (object) - Optional - Configuration for the calculation.
  - **unit** (string) - Optional - The unit for the returned distance (centimeter, foot, inch, kilometer, meter, mile, mile-scandinavian, millimeter, yard). Defaults to "kilometer".
  - **accuracy** (string) - Optional - Accuracy mode: "normal" (Haversine) or "high" (Vincenty). Defaults to "normal".
  - **maxDecimals** (number) - Optional - Maximum decimals for the distance. Defaults to 2.
  - **locale** (string) - Optional - Locale for the distance label. Defaults to "en-US".

### Request Example
getGeoDiff([2.3522, 48.8566], [-0.1278, 51.5074], { unit: "kilometer" });

### Response
#### Success Response
- **type** (string) - Always "geo".
- **status** (string) - The status of the change: "added", "deleted", "error", "equal", or "updated".
- **diff** (object) - The difference details including coordinates, distance, unit, label, and direction.

#### Response Example
{
  "type": "geo",
  "status": "updated",
  "diff": {
    "coordinates": [-0.1278, 51.5074],
    "previousCoordinates": [2.3522, 48.8566],
    "distance": 343.56,
    "unit": "kilometer",
    "label": "343.56 kilometers",
    "direction": "north-west"
  }
}
```

--------------------------------

### Define getGeoDiff Output Structure

Source: https://donedeal0.gitbook.io/superdiff/features/getgeodiff

The function returns a GeoDiff object containing the status of the change and detailed diff information including distance, unit, and direction.

```typescript
type GeoDiff = {
    type: "geo";
    status: "added" | "deleted" | "error" | "equal" | "updated";
    diff: {
        coordinates: [number, number] | null;
        previousCoordinates: [number, number] | null;
        distance: number;
        unit: "centimeter" | "foot" | "inch" | "kilometer" | "meter" | "mile" | "mile-scandinavian" | "millimeter" | "yard";
        label: string,
        direction: "east" | "north" | "south" | "west" | "north-east" | "north-west" | "south-east" | "south-west" | "stationary";
    };
}
};
```

--------------------------------

### StreamListDiff Type Definition

Source: https://donedeal0.gitbook.io/superdiff/features/streamlistdiff/server

Defines the structure of a single diff object within a chunk, including value, index, previous value, previous index, and status.

```typescript
type StreamListDiff<T extends Record<string, unknown>> = {
  value: T | null;
  index: number | null;
  previousValue: T | null;
  previousIndex: number | null;
  status: "added" | "deleted" | "moved" | "updated" | "equal";
};
```
Tokens:
Raw