@sandboxed/diff 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2025 Víctor Cruz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @sandboxed/diff
+
+A **zero dependency, high-performance, security-conscious** JavaScript diffing library for comparing complex data structures with ease.
+
+## Features
+
+- ⚡️ **Zero dependencies** – lightweight and no external libraries required
+- 📝 Detects **additions, deletions, and modifications**
+- 💡 Supports **Primitives, Objects, Arrays, Maps, and Sets**
+- 🔄 **Handles circular references** safely
+- 🛠️ **Highly configurable** to fit different use cases
+- 🚨 **Built with security in mind** to prevent prototype pollution and other risks
+- 💻 Works in both **Node.js and browser environments**
+
+## Installation
+
+```
+npm install @sandboxed/diff
+
+yarn add @sandboxed/diff
+```
+
+### Supports `esm` and `cjs`
+
+Works with both ESM (`import`) and CJS (`require`). Use the syntax that matches your environment:
+
+```javascript
+// ESM
+import diff, { ChangeType } from '@sandboxed/diff';
+
+// CJS option 1
+const diff = require('@sandboxed/diff').default;
+const { ChangeType } = require('@sandboxed/diff');
+
+// CJS option 2
+const { default: diff, ChangeType } = require('@sandboxed/diff');
+```
+
+## Usage
+
+#### `diff(lhs: any, rhs: any, config?: DiffConfig): Diff`
+
+```javascript
+import diff, { ChangeType } from '@sandboxed/diff';
+
+const a = { name: "Alice", age: 25 };
+const b = { name: "Alice", age: 26, city: "New York" };
+
+const result = diff(a, b);
+
+console.log(result);
+console.log(result.toDiffString());
+console.log(result.equal); // false
+```
+
+**Output**:
+
+```javascript
+[
+  { type: 'noop', str: '{', depth: 0, path: [] },
+  {
+    type: 'noop',
+    str: '"name": "Alice",',
+    depth: 1,
+    path: [ 'name', { deleted: false, value: 'Alice' } ]
+  },
+  {
+    type: 'remove',
+    str: '"age": 25,',
+    depth: 1,
+    path: [ 'age', { deleted: true, value: 25 } ]
+  },
+  {
+    type: 'update',
+    str: '"age": 26,',
+    depth: 1,
+    path: [ 'age', { deleted: false, value: 26 } ]
+  },
+  {
+    type: 'add',
+    str: '"city": "New York",',
+    depth: 1,
+    path: [ 'city', { deleted: false, value: 'New York' } ]
+  },
+  { type: 'noop', str: '}', depth: 0, path: [] }
+]
+
+// ---
+
+{
+   "name": "Alice",
+-  "age": 25,
+!  "age": 26,
++  "city": "New York",
+}
+```
+
+## Config
+
+| option | Description |
+|-|-|
+|[config.include](/docs/config.md#include-changetype--changetype)| Include only these change types from the diff result. Can be combined with `exclude`. |
+|[config.exclude](/docs/config.md#exclude-changetype--changetype)| Excludes the change types from the diff result. Can be combined with `include`. |
+|[config.strict](/docs/config.md#strict-boolean)| Performs loose type check if disabled. |
+|[config.showUpdatedOnly](/docs/config.md#showupdatedonly-boolean)| `@sandboxed/diff` creates a `ChangeType.REMOVE` entry for every `ChangeType.UPDATE`. This flags prevents this behavior. |
+|[config.pathHints](/docs/config.md#pathhints-pathints)| Hashmap of `map` and `set` path hints. These strings will be used in the `path` array to provide a hit about the object's type. |
+|[config.redactKeys](/docs/config.md#redactkeys-arraystring)| List of keys that should be redacted from the output. Works with `string` based keys and serialized `Symbol`. |
+|[config.maxDepth](/docs/config.md#maxdepth-number)| Max depth that the diffing function can traverse. |
+|[config.maxKeys](/docs/config.md#maxkeys-number)| Max keys the diffing function can traverse. |
+|[config.timeout](/docs/config.md#timeout-number)| Milliseconds before throwing a timeout error. |
+
+## Utils
+
+| util | Description |
+|-|-|
+|[toDiffString](/docs/utils.md#diff-string-output)| Generates the diff string representation of the diff result. |
+|[equal](/docs/utils.md#equality-detection)| Determines whether the inputs are structurally equal based on the diff result. |
+
+## Motivation
+
+Many diffing libraries are optimized for either structured output or human-readable text, but rarely both. `@sandboxed/diff` is designed to provide a structured diff result along with a utility to generate a string representation, making it easy to use in both programmatic logic and UI rendering.
+
+Trade-off: It may be **slower than other libraries**, but if you prioritize structured diffs with a built-in string representation, `@sandboxed/diff` is a great fit.
+
+## LICENSE
+
+[MIT](LICENSE)

package/docs/config.md

@@ -0,0 +1,165 @@
+
+## Config
+
+#### `.include: ChangeType | ChangeType[]`
+
+|||
+|-|-|
+| **Description** | Include only these change types from the diff result. Can be combined with `exclude`. |
+| **Default** | `[ChangeType.NOOP, ChangeType.ADD, ChangeType.UPDATE, ChangeType.REMOVE]` |
+
+```javascript
+diff(a, b, { include: [ChangeType.ADD] }); // only additions
+
+diff(a, b, {
+  include: [ChangeType.ADD, ChangeType.NOOP],
+}); // only additions + unchanged data
+```
+
+---
+
+#### `.exclude: ChangeType | ChangeType[]`
+|||
+|-|-|
+| **Description** | Excludes the change types from the diff result. Can be combined with `include`. |
+| **Default** | `[]` |
+
+```javascript
+diff(a, b, { exclude: ChangeType.NOOP });
+
+diff(a, b, { exclude: [ChangeType.ADD, ChangeType.NOOP] });
+```
+
+---
+
+#### `.strict: boolean`
+
+|||
+|-|-|
+| **Description** | Performs loose type check if disabled. |
+| **Default** | `true` |
+
+```javascript
+const a = { foo: 1 };
+const b = { foo: '1' };
+
+console.log(diff(a, b).equal); // false
+
+console.log(diff(a, b, { strict: false }).equal); // true
+```
+
+---
+
+#### `.showUpdatedOnly: boolean`
+
+|||
+|-|-|
+| **Description** | `@sandboxed/diff` creates a `ChangeType.REMOVE` entry for every `ChangeType.UPDATE`. This flags prevents this behavior. |
+| **Default** | `false` |
+
+```javascript
+const a = { foo: 'baz' };
+const b = { foo: 'bar' };
+
+console.log(diff(a, b, { showUpdatedOnly: true }));
+```
+
+**Output**:
+```javascript
+[
+  { type: 'noop', str: '{', depth: 0, path: [] },
+  {
+    type: 'update',
+    str: '"foo": "bar",',
+    depth: 1,
+    path: [ 'foo', { deleted: false, value: 'bar' } ]
+  },
+  { type: 'noop', str: '}', depth: 0, path: [] }
+]
+```
+
+---
+
+#### `.pathHints: PatHints`
+
+|||
+|-|-|
+| **Description** | Hashmap of `map` and `set` path hints. These strings will be used in the `path` array to provide a hit about the object's type. |
+| **Default** | `{ map: '__MAP__', set: '__SET__' }` |
+
+⚠️ Warning: **Complex keys are not recursively diffed**, they are treated as references only.
+**Assume that any string entry in the path array comes from plain objects, and numeric entries come from arrays**. Without these hints, tracking back to the origin can be difficult, though can be disabled if not needed.
+
+```javascript
+const a = new Map([['foo', 'baz']]);
+const b = new Map([['foo', 'bar']]);
+
+const result = diff(a, b, { showUpdatedOnly: true });
+
+// "foo: bar" update
+console.log(result[1].path); // ['__MAP__', 'foo', { deleted: false, value: 'bar' }]
+```
+
+---
+
+#### `.redactKeys: Array<string>`
+
+|||
+|-|-|
+| **Description** | List of keys that should be redacted from the output. Works with `string` based keys and serialized `Symbol`.|
+|**Default** | `[ 'password', 'secret', 'token', 'Symbol(password)', 'Symbol (secret)', 'Symbol(token)' ]` |
+
+⚠️ Warning: Only the result `str` is redacted, the `path` array still contains the reference to the actual values. Be careful when using this for logging.
+
+```javascript
+const a = { password: 'pwd' };
+const b = { password: 'secret' };
+
+console.log(diff(a, b, { showUpdatedOnly: true }));
+```
+
+**Output**:
+```javascript
+[
+  { type: 'noop', str: '{', depth: 0, path: [] },
+  {
+    type: 'update',
+    str: '"password": "*****",',
+    depth: 1,
+    path: [ 'password', { deleted: false, value: 'secret' } ]
+  },
+  { type: 'noop', str: '}', depth: 0, path: [] }
+]
+```
+
+---
+
+#### `.maxDepth: number`
+
+|||
+|-|-|
+| **Description** | Max depth that the diffing function can traverse. Throws when reaching the max. |
+| **Default** | `50` |
+| **Throws** | `Max depth exceeded!` |
+
+---
+
+#### `.maxKeys: number`
+
+|||
+|-|-|
+| **Description** | Max keys the diffing function can traverse. Throws when reaching the max. |
+|**Default** | `50` |
+|**Throws** | `Object is too big to continue! Aborting.` |
+
+---
+
+#### `.timeout: number`
+
+|||
+|-|-|
+| **Description** | Milliseconds before throwing a timeout error. |
+|**Default** | `1000` |
+|**Throws** | `Diff took too much time! Aborting.` |
+
+⚠️ Warning: The diffing function does not check for object size in memory. The process can still hang if the system is unable to handle the object in memory.

package/docs/utils.md

@@ -0,0 +1,76 @@
+## Utils
+
+### Diff string output
+
+**`.toDiffString(config?: DiffStringConfig): string`**
+
+Highly configurable util that generates the diff string representation of the diff result:
+
+```javascript
+import diff from '@sandboxed/diff';
+
+const a = { name: "Alice", age: 25 };
+const b = { name: "Alice", age: 26, city: "New York" };
+
+console.log(diff(a, b).toDiffString());
+```
+
+**Output**:
+```
+{
+   "name": "Alice",
+-  "age": 25,
+!  "age": 26,
++  "city": "New York",
+}
+```
+
+#### Config options
+
+|   config   | default  | Description |
+|------------|----------|-------------|
+| withColors | `true`   | Formats the string using AnsiColors. |
+| colors     | `object` | Hashmap for coloring each line based on type: `[ChangeType]: (string) => string`. Should be compatible with `chalk`. |
+| symbols    | `object` | Hashmap for prefixing each line based on type: `[ChangeType]: string`. |
+| wrapper    | `[]` | Array with `string` entries. Wraps the result between the first two strings. |
+| indentSize | `2` | Whitespace after the `config.symbols`. Indentation is done using `space`. |
+
+
+### Equality detection
+
+**`.equal: boolen`**
+
+Determines whether the inputs are structurally equal based on the diff result. It ignores any `ChangeType.NOOP` items.
+
+```javascript
+import diff from '@sandboxed/diff';
+
+const a = { name: "Alice", age: 25 };
+const b = { name: "Alice", age: 26, city: "New York" };
+
+console.log(diff(a, b).equal); // Output: false
+
+// --
+
+const c = { name: 'Alice', foo: new Set([1, 2, 'test']) };
+const d = { name: 'Alice', foo: new Set(['test', 2, 1]) };
+
+console.log(diff(c, d).equal); // Output: true
+```
+
+### ⚠️ Warning
+
+Be aware that `.equal` is affected by the diff result. Should be used with caution when `cofig.include` or `config.exclude` are provided.
+
+```javascript
+import diff, { ChangeType } from '@sandboxed/diff';
+
+const a = { name: 'Alice', foo: new Set([1, 2, 'test']) };
+const b = { name: 'Alice', bar: new Set(['test', 2, 1]) };
+
+console.log(
+  diff(a, b, { exclude: [ChangeType.ADD, ChangeType.REMOVE] }).equal
+); // Output: true
+```
+
+Given that the diff result will not detect the changes in **`foo`**(`ChangeType.REMOVE`) or **`bar`** (`ChangeType.ADD`), the diff result will contain only `ChangeType.NOOP`, causing `.equal` to be `true`.