diff-leven 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kushal
+
+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,220 @@
+# diff-leven
+
+> Git-like diff between two strings or objects, powered by the Levenshtein distance algorithm
+
+[![npm version](https://badge.fury.io/js/diff-leven.svg)](https://badge.fury.io/js/diff-leven)
+[![npm](https://img.shields.io/npm/dm/diff-leven.svg)](https://www.npmjs.com/package/diff-leven)
+![License](https://img.shields.io/npm/l/diff-leven.svg)
+
+---
+
+## ✨ Features
+
+- **Advanced Diff Generation**: Uses the Levenshtein distance algorithm for meaningful diffs
+- **Multiple Data Type Support**:
+  - Objects (including nested structures)
+  - Arrays (smart matching by content similarity)
+  - Strings (character-level differences)
+  - Numbers, Booleans, and any serializable value
+- **Rich Output Options**:
+  - Terminal-friendly colorized output (toggleable)
+  - Git-style diff format with clear additions/removals
+- **Flexible Configuration**:
+  - `color`: Toggle color output (default: `true`)
+  - `keysOnly`: Compare only object structure/keys (default: `false`)
+  - `full`: Output the entire object tree, not just differences (default: `false`)
+  - `outputKeys`: Always include specified keys in output for objects with differences
+  - `ignoreKeys`: Skip specified keys when comparing objects
+  - `ignoreValues`: Ignore value differences, focus on structure
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install
+
+```bash
+npm install diff-leven
+```
+
+### 2. Usage
+
+```js
+const { diff } = require('diff-leven');
+
+console.log(diff({ foo: 'bar' }, { foo: 'baz' }));
+// Output:
+//  {
+// -  foo: "bar"
+// +  foo: "baz"
+//  }
+```
+
+---
+
+## 🛠️ API Reference
+
+### `diff(a, b, options?)`
+
+Compare two values (strings, objects, arrays, etc.) and return a formatted diff string.
+
+#### **Parameters**
+
+- `a`, `b`: Anything serializable (object, array, string, number, etc.)
+- `options` _(optional object)_:
+  - `color` _(boolean)_: Use colors in output (default: `true`)
+  - `keysOnly` _(boolean)_: Only compare object keys (default: `false`)
+  - `full` _(boolean)_: Output the entire JSON tree (default: `false`)
+  - `outputKeys` _(string[])_: Always include these keys in output (default: `[]`)
+  - `ignoreKeys` _(string[])_: Ignore these keys when comparing (default: `[]`)
+  - `ignoreValues` _(boolean)_: Ignore value differences (default: `false`)
+
+#### **Returns**
+
+- A string representing the diff between `a` and `b`.
+
+### `diffRaw(a, b, options?)`
+
+Compare two values (strings, objects, arrays, etc.) and return a structured diff result object.
+
+#### **Parameters**
+
+- `a`, `b`: Anything serializable (object, array, string, number, etc.)
+- `options` _(optional object)_:
+  - `color` _(boolean)_: Use colors in output (default: `true`)
+  - `keysOnly` _(boolean)_: Only compare object keys (default: `false`)
+  - `full` _(boolean)_: Output the entire JSON tree (default: `false`)
+  - `outputKeys` _(string[])_: Always include these keys in output (default: `[]`)
+  - `ignoreKeys` _(string[])_: Ignore these keys when comparing (default: `[]`)
+  - `ignoreValues` _(boolean)_: Ignore value differences (default: `false`)
+
+#### **Returns**
+
+- A structured object representing the diff between `a` and `b`.
+
+#### **Examples**
+
+```js
+const { diff, diffRaw } = require('diff-leven');
+
+// Basic diff (string output)
+console.log(diff({ foo: 'bar' }, { foo: 'baz' }));
+// Output:
+//  {
+// -  foo: "bar"
+// +  foo: "baz"
+//  }
+
+// Raw diff object
+const rawDiff = diffRaw({ foo: 'bar' }, { foo: 'baz' });
+console.log(JSON.stringify(rawDiff, null, 2));
+// Output:
+// {
+//   "type": "changed",
+//   "path": [],
+//   "oldValue": { "foo": "bar" },
+//   "newValue": { "foo": "baz" },
+//   "children": [
+//     {
+//       "type": "changed",
+//       "path": ["foo"],
+//       "oldValue": "bar",
+//       "newValue": "baz"
+//     }
+//   ]
+// }
+
+// No colors
+console.log(diff({ foo: 'bar' }, { foo: 'baz' }, { color: false }));
+// Output:
+//  {
+// -  foo: "bar"
+// +  foo: "baz"
+//  }
+
+// Full output
+console.log(diff({ foo: 'bar', b: 3 }, { foo: 'baz', b: 3 }, { full: true }));
+// Output:
+//  {
+// -  foo: "bar"
+// +  foo: "baz"
+//    b: 3
+//  }
+
+// Ignore keys
+console.log(
+  diff({ foo: 'bar', b: 3 }, { foo: 'baz', b: 3 }, { ignoreKeys: ['b'] }),
+);
+// Output:
+//  {
+// -  foo: "bar"
+// +  foo: "baz"
+//  }
+
+// Ignore values
+console.log(
+  diff({ foo: 'bar', b: 3 }, { foo: 'baz', b: 3 }, { ignoreValues: true }),
+);
+// Output showing structural differences only
+
+// Output specific keys
+console.log(
+  diff({ foo: 'bar', b: 3 }, { foo: 'baz', b: 3 }, { outputKeys: ['foo'] }),
+);
+// Output:
+//  {
+// -  foo: "bar"
+// +  foo: "baz"
+//  }
+
+// Combine options
+console.log(
+  diff(
+    { foo: 'bar', b: 3 },
+    { foo: 'baz', b: 3 },
+    {
+      keysOnly: true,
+      ignoreKeys: ['b'],
+      ignoreValues: true,
+      outputKeys: ['foo'],
+      full: true,
+      color: false,
+    },
+  ),
+);
+```
+
+---
+
+## ⚙️ Options Matrix
+
+| Option         | Type     | Default | Description                                  |
+| -------------- | -------- | ------- | -------------------------------------------- |
+| `color`        | boolean  | true    | Use colorized output                         |
+| `keysOnly`     | boolean  | false   | Only compare object keys                     |
+| `full`         | boolean  | false   | Output the entire object tree                |
+| `outputKeys`   | string[] | []      | Always include these keys in output          |
+| `ignoreKeys`   | string[] | []      | Ignore these keys when comparing             |
+| `ignoreValues` | boolean  | false   | Ignore value differences, focus on structure |
+
+---
+
+## 📦 Examples
+
+See [`examples/basic.js`](examples/basic.js) for more usage patterns.
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repo
+2. Create your feature branch (`git checkout -b feature/YourFeature`)
+3. Commit your changes (`git commit -am 'Add new feature'`)
+4. Push to the branch (`git push origin feature/YourFeature`)
+5. Open a pull request
+
+---
+
+## 📄 License
+
+MIT © [kushalshit27](LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+/**
+ * Options for diff generation
+ */
+interface DiffOptions {
+    /**
+     * Whether to use colorized output
+     * @default true
+     */
+    color?: boolean;
+    /**
+     * Only compare object keys/structure (ignore values)
+     * @default false
+     */
+    keysOnly?: boolean;
+    /**
+     * Output the entire object tree, not just differences
+     * @default false
+     */
+    full?: boolean;
+    /**
+     * Always include these keys in output for objects with differences
+     * @default []
+     */
+    outputKeys?: string[];
+    /**
+     * Skip these keys when comparing objects
+     * @default []
+     */
+    ignoreKeys?: string[];
+    /**
+     * Ignore value differences, focus only on structure
+     * @default false
+     */
+    ignoreValues?: boolean;
+}
+/**
+ * Enum for diff change types
+ */
+declare enum DiffType {
+    ADDED = "added",
+    REMOVED = "removed",
+    CHANGED = "changed",
+    UNCHANGED = "unchanged"
+}
+/**
+ * Represents a change between two values
+ */
+interface DiffResult {
+    type: DiffType;
+    path?: string[];
+    oldValue?: any;
+    newValue?: any;
+    children?: DiffResult[];
+    /**
+     * Additional metadata about the diff, such as Levenshtein distance metrics
+     */
+    meta?: {
+        /** Levenshtein distance between strings */
+        levenDistance?: number;
+        /** Similarity ratio (0-1) where 1 means identical */
+        similarity?: number;
+        /** Any other metadata properties */
+        [key: string]: any;
+    };
+}
+/**
+ * Type for handling any serializable value
+ */
+type SerializableValue = string | number | boolean | null | undefined | {
+    [key: string]: SerializableValue;
+} | SerializableValue[];
+
+/**
+ * Compare two values and generate a detailed diff result object
+ *
+ * @param oldValue - Original value to compare from
+ * @param newValue - New value to compare against
+ * @param options - Configuration options for the diff
+ * @returns A structured diff result object
+ */
+declare function diffRaw(oldValue: SerializableValue, newValue: SerializableValue, options?: DiffOptions): DiffResult;
+/**
+ * Compare two values and generate a formatted diff string
+ *
+ * @param oldValue - Original value to compare from
+ * @param newValue - New value to compare against
+ * @param options - Configuration options for the diff
+ * @returns A formatted string representation of the diff
+ */
+declare function diff(oldValue: SerializableValue, newValue: SerializableValue, options?: DiffOptions): string;
+
+export { type DiffOptions, type DiffResult, DiffType, type SerializableValue, diff, diffRaw };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Options for diff generation
+ */
+interface DiffOptions {
+    /**
+     * Whether to use colorized output
+     * @default true
+     */
+    color?: boolean;
+    /**
+     * Only compare object keys/structure (ignore values)
+     * @default false
+     */
+    keysOnly?: boolean;
+    /**
+     * Output the entire object tree, not just differences
+     * @default false
+     */
+    full?: boolean;
+    /**
+     * Always include these keys in output for objects with differences
+     * @default []
+     */
+    outputKeys?: string[];
+    /**
+     * Skip these keys when comparing objects
+     * @default []
+     */
+    ignoreKeys?: string[];
+    /**
+     * Ignore value differences, focus only on structure
+     * @default false
+     */
+    ignoreValues?: boolean;
+}
+/**
+ * Enum for diff change types
+ */
+declare enum DiffType {
+    ADDED = "added",
+    REMOVED = "removed",
+    CHANGED = "changed",
+    UNCHANGED = "unchanged"
+}
+/**
+ * Represents a change between two values
+ */
+interface DiffResult {
+    type: DiffType;
+    path?: string[];
+    oldValue?: any;
+    newValue?: any;
+    children?: DiffResult[];
+    /**
+     * Additional metadata about the diff, such as Levenshtein distance metrics
+     */
+    meta?: {
+        /** Levenshtein distance between strings */
+        levenDistance?: number;
+        /** Similarity ratio (0-1) where 1 means identical */
+        similarity?: number;
+        /** Any other metadata properties */
+        [key: string]: any;
+    };
+}
+/**
+ * Type for handling any serializable value
+ */
+type SerializableValue = string | number | boolean | null | undefined | {
+    [key: string]: SerializableValue;
+} | SerializableValue[];
+
+/**
+ * Compare two values and generate a detailed diff result object
+ *
+ * @param oldValue - Original value to compare from
+ * @param newValue - New value to compare against
+ * @param options - Configuration options for the diff
+ * @returns A structured diff result object
+ */
+declare function diffRaw(oldValue: SerializableValue, newValue: SerializableValue, options?: DiffOptions): DiffResult;
+/**
+ * Compare two values and generate a formatted diff string
+ *
+ * @param oldValue - Original value to compare from
+ * @param newValue - New value to compare against
+ * @param options - Configuration options for the diff
+ * @returns A formatted string representation of the diff
+ */
+declare function diff(oldValue: SerializableValue, newValue: SerializableValue, options?: DiffOptions): string;
+
+export { type DiffOptions, type DiffResult, DiffType, type SerializableValue, diff, diffRaw };