Skip to content

Chore: Multiple type issues #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vmcruz merged 3 commits into from
Jan 14, 2026
Merged

Chore: Multiple type issues #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cae7b8c
Improves type checking and toDiffString defaults
vmcruz Jan 14, 2026
e728615
Update docs
vmcruz Jan 14, 2026
71e860a
Merge branch 'main' into chore/multiple-type-issues
vmcruz Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 40 additions & 38 deletions docs/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@

## 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]` |
| **Default** | `[ChangeType.NOOP, ChangeType.ADD, ChangeType.UPDATE, ChangeType.REMOVE]` |

```javascript
diff(a, b, { include: [ChangeType.ADD] }); // only additions
Expand All @@ -19,10 +18,11 @@ diff(a, b, {
---

#### `.exclude: ChangeType | ChangeType[]`
|||
|-|-|

| | |
| --------------- | ------------------------------------------------------------------------------- |
| **Description** | Excludes the change types from the diff result. Can be combined with `include`. |
| **Default** | `[]` |
| **Default** | `[]` |

```javascript
diff(a, b, { exclude: ChangeType.NOOP });
Expand All @@ -34,10 +34,10 @@ diff(a, b, { exclude: [ChangeType.ADD, ChangeType.NOOP] });

#### `.strict: boolean`

|||
|-|-|
| | |
| --------------- | -------------------------------------- |
| **Description** | Performs loose type check if disabled. |
| **Default** | `true` |
| **Default** | `true` |

```javascript
const a = { foo: 1 };
Expand All @@ -52,10 +52,10 @@ 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` |
| **Default** | `false` |

```javascript
const a = { foo: 'baz' };
Expand All @@ -65,27 +65,28 @@ 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' } ]
path: ['foo', { deleted: false, value: 'bar' }],
},
{ type: 'noop', str: '}', depth: 0, path: [] }
]
{ 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__' }` |
| **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.
Expand All @@ -104,10 +105,10 @@ 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)' ]` |
| | |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| **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.

Expand All @@ -119,47 +120,48 @@ 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' } ]
path: ['password', { deleted: false, value: 'secret' }],
},
{ type: 'noop', str: '}', depth: 0, path: [] }
]
{ 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!` |
| **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.` |
| **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.` |
| **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.
26 changes: 12 additions & 14 deletions docs/utils.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,14 @@ Highly configurable util that generates the diff string representation of the di
```javascript
import diff from '@sandboxed/diff';

const a = { name: "Alice", age: 25 };
const b = { name: "Alice", age: 26, city: "New York" };
const a = { name: 'Alice', age: 25 };
const b = { name: 'Alice', age: 26, city: 'New York' };

console.log(diff(a, b).toDiffString());
```

**Output**:

```
{
"name": "Alice",
Expand All @@ -27,14 +28,13 @@ console.log(diff(a, b).toDiffString());

#### Config options

| config | default | Description |
|------------|----------|-------------|
| withColors | `true` | Formats the string using AnsiColors. |
| config | default | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| withColors | `false` | 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`. |

| 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

Expand All @@ -45,8 +45,8 @@ Determines whether the inputs are structurally equal based on the diff result. I
```javascript
import diff from '@sandboxed/diff';

const a = { name: "Alice", age: 25 };
const b = { name: "Alice", age: 26, city: "New York" };
const a = { name: 'Alice', age: 25 };
const b = { name: 'Alice', age: 26, city: 'New York' };

console.log(diff(a, b).equal); // Output: false

Expand All @@ -68,9 +68,7 @@ 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
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`.
Loading