v4.0.0

BREAKING CHANGES

👉 These changes improve the developer experience by unifying naming conventions across all diff utilities and simplifying the output format. They are minimal and should require only small updates in your codebase.

---

• Removed isEqual and isObject from the library (they are still used internally).
• Unified naming conventions across all diff:

getListDiff

• Renamed newIndex → index
• Renamed prevIndex → previousIndex
• Removed indexDiff (it can be computed from index and previousIndex if needed)
• Renamed the option referenceProperty → referenceKey

diff: {
    value: unknown;
-   newIndex: number | null;
+   index: number | null;
-   prevIndex: number | null;
+   previousIndex: number | null;
-   indexDiff: number | null;
    status: ListStatus;
  }[];

getStreamDiff:

• Renamed currentValue → value
• Renamed newIndex → index
• Renamed prevIndex → previousIndex
• Removed indexDiff (same reason as above)

diff: {
-   currentValue: unknown;
+   value: unknown;
-   newIndex: number | null;
+   index: number | null;
-   prevIndex: number | null;
+   previousIndex: number | null;
-   indexDiff: number | null;
    status: ListStatus;
  }[];

getObjectDiff:

• Renamed property → key
• Renamed currentValue → value

diff: {
-  property: string;
+  key: string;
-  currentValue: unknown;
+  value: unknown;
   previousValue: unknown;
   status: ObjectStatus;
   diff?: Diff[];
 };

v3.2.0

⚡ BOOST PERFORMANCE OF getObjectDiff & getListDiff

• Rewrote getObjectDiff and getListDiff for maximum performance.
  Due to aggressive optimizations, the code is less readable, but the performance gain justifies the tradeoff.

• Added a benchmark comparing Superdiff with its main competitors.

• Updated several dev dependencies.

📊 BENCHMARK

Environment: Node.js 24.12.0 (LTS) • MacBook Pro M2 (2023, Sequoia 15.1) • 16GB RAM.

Method: Warm up runs, then each script is executed 20 times, and we keep the median time. To minimize garbage collection and cross‑benchmark interference, all scenarios are run individually. All benchmark scripts are included so you can reproduce the results locally.

List diff

Scenario	Superdiff	arr-diff	deep-diff
10k items array	1.84 ms	32.95 ms	4.74 ms
100k items array	17.43 ms	3363.15 ms	50.36 ms

Object diff

Scenario	Superdiff	deep-object-diff	deep-diff
10k flat object keys	2.27 ms	2.44 ms	39.37 ms
100k flat object keys	29.23 ms	31.86 ms	3784.50 ms
100k nested nodes	4.25 ms	9.67 ms	16.51 ms

👉 Despite providing a full structural diff with a richer output, Superdiff is the fastest. It also scales linearly, even with deeply nested data.

#35

v3.1.2

DOCUMENTATION

Add the link to the documentation website: https://superdiff.gitbook.io/donedeal0-superdiff (#33 )

v3.1.1

Bug Fix

• Fix the subpath exports that broke the library import. (#32)

ℹ️ Please refer to the latest release note for information on the new features.

v3.1.0

FEATURE

• Add a useWorker option to streamListDiff. If set to true, the diff will be run in a worker for maximum performance. Only recommended for large lists (e.g. +100,000 items). true by default.

const diff = streamListDiff(hugeListA, hugeListB, "id", { chunksSize: 100_000,  useWorker: true });

pull request #31

BREAKING CHANGES

• Enums standardization
  • OBJECT_STATUS becomes ObjectStatus
  • LIST_STATUS becomes ListStatus
  • GRANULARITY becomes Granularity

CHORE

• Add a showWarnings option to streamListDiff
• Allow enum and unions for ListStatus
• Clean models
• Fix client and server import subpaths
• Convert Jest config to Typescript
• Update dev dependencies
• Update README.md

v3.0.0

New Feature

• streamListDiff now supports array, stream, and file inputs for maximum performance, polyvalence, and optimal memory usage. 🎸🦅 (#28).

---

Import

// If you are in a server environment
import { streamListDiff } from "@donedeal0/superdiff/server";
// If you are in a browser environment
import { streamListDiff } from "@donedeal0/superdiff/client";

Input

You can send streams, file paths, or arrays as input:

If you are in a server environment

    // for a simple array
    const stream = [{ id: 1, name: "hello" }]
    // for a large array 
    const stream = Readable.from(list, { objectMode: true });
    // for a local file
    const stream = path.resolve(__dirname, "./list.json");
   

If you are in a browser environment

    // for a simple array 
    const stream = [{ id: 1, name: "hello" }]
    // for a large array 
    const stream = new ReadableStream({
      start(controller) {
        list.forEach((value) => controller.enqueue(value));
        controller.close();
      },
    }); 
    // for a local file
    const stream = new File([JSON.stringify(file)], "file.json", { type: "application/json" }); 
    // for a file input
    const stream = e.target.files[0]; 

See the documentation for more details.

Improvement

• Improve the execution time of getObjectDiff⚡️(#30).
• Rewrite the getObjectDiff code which is now cleaner and more elegant.

Chores

• Update the documentation.
• Create two subbuilds: client and server to expose an appropriate version of streamListDiff.

BREAKING CHANGE

• streamListDiff is no longer imported from the index, but from @donedeal0/superdiff/server or @donedeal0/superdiff/client.

v2.1.0

2.1.0

New Feature

• Add a new function streamListDiff to stream the diff of two object lists. It is ideal for large lists and maximum performance 🔥 (#26).

Basic usage (see the documentation for more details)

import { streamListDiff } from "@donedeal0/superdiff";

const diff = streamListDiff([], [], "id")

diff.on("data", (chunk) => { console.log(chunk) )}
diff.on("finish", () => console.log("The full diff is available"))
diff.on("error", (err) => console.log(err))

Improvement

• Improve the execution time of getListDiff by 55.6% ⚡️(#27).

Chores

• Use SWC to speed up the tests.
• Add aliases (@models, @lib).
• Clean devDependencies.
• Restructure the codebase.
• Update the documentation.

v2.0.0

2.0.0 (2024-09-29)

Features

• simplify output (#25) (c6a186e)

Chore

• pre-commit script
• better linter
• improved CI, automated CD

BREAKING CHANGES

• subPropertiesDiff has been removed from the getObjectDiff output. There is now a single recursive diff key for more simplicity. The types have also been improved.

1.1.3

• Add the option ignoreArrayOrder to getListDiff (#23)

v1.1.2

• Fix bug when comparing an array to a non-array value (#18)
• Export types (#19)

Thanks to @mfactorial