npm package: @phragon-util/diff
Description: `@phragon-util/diff` is a JavaScript library designed to find and represent differences between two objects.  It supports deep comparison of nested objects and arrays, providing an easy way to identify changes.
Author: phragon@websoftlab.com
Latest version: 0.0.1

# @phragon-util/diff

`@phragon-util/diff` is a JavaScript library designed to find and represent differences between two objects. 
It supports deep comparison of nested objects and arrays, providing an easy way to identify changes.

## Installation

You can install `@phragon-util/diff` via npm or yarn.

### Using npm

```bash
npm install @phragon-util/diff
```
### Using yarn

```bash
yarn add @phragon-util/diff
```

## Usage

The library can be used with both ES Modules (ESM) and CommonJS.

### ES Modules (ESM)

```javascript
import { diff } from '@phragon-util/diff';
```

### CommonJS

```javascript
const { diff } = require('@phragon-util/diff');
```

## API

```typescript
declare function diff<T extends object>(a: T, b: T, options?: DiffOptions): Diff[]
```
Compares two objects and returns an array of differences.

### Parameters

- `a` (T): The first object to compare.
- `b` (T): The second object to compare.
- `options` (`DiffOptions`, optional): Configuration options for the comparison.

### Options

- `ignore` (`string[]`, optional): List of properties to ignore during comparison. 
Nested property names should be dot-separated (e.g., `'parent.child'`).

- `depth` (`number`, optional): The maximum depth for displaying the differences in the result.\
The depth controls how many levels of nested properties are included in the `Diff` array.
A depth of 2 will show differences up to depth 2, even if changes are found at deeper levels.
The comparison itself is done fully regardless of this setting.
Arrays always show differences up to the first level inside the array.\
The maximum depth of nested properties to include in the output. If not specified, the default depth is 3.

### Returns

- `Diff[]`: An array of differences. Each difference includes the name, path, type, from value, and to value.

### `DiffType`

Type for the type of difference:

- `"N"`: Indicates a newly added property/element.
- `"D"`: Indicates a property/element was deleted.
- `"E"`: Indicates a property/element was edited.

## Example

In this example:

    The depth option limits the depth of the properties shown in the diff result to 2 levels deep.

```javascript
import { diff } from '@phragon-util/diff';

const obj1 = {
    name: 'Alice',
    age: 30,
    address: {
        city: 'Wonderland',
        postalCode: '12345'
    }
};

const obj2 = {
    name: 'Alice',
    age: 31,
    address: {
        city: 'Wonderland',
        postalCode: '54321'
    }
};

// depth 1
console.log(diff(obj1, obj2, { depth: 1 }));

// depth 2
console.log(diff(obj1, obj2, { depth: 2 }));
```

### Output depth 1:

```json
[
  {
    "name": "age",
    "path": ["age"],
    "type": "E",
    "from": 30,
    "to": 31
  },
  {
    "name": "address",
    "path": ["address"],
    "type": "E",
    "from": {
      "city": "Wonderland",
      "postalCode": "12345"
    },
    "to": {
      "city": "Wonderland",
      "postalCode": "54321"
    }
  }
]
```

### Output depth 2:

```json
[
  {
    "name": "age",
    "path": ["age"],
    "type": "E",
    "from": 30,
    "to": 31
  },
  {
    "name": "address.postalCode",
    "path": ["address", "postalCode"],
    "type": "E",
    "from": "12345",
    "to": "54321"
  }
]
```

## License

This library is licensed under the MIT License. See the LICENSE file for more details.