@fgv/ts-json 4.6.0 → 5.0.0-10

package/lib/packlets/diff/detailedDiff.js

@@ -0,0 +1,342 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonDiff = jsonDiff;
+exports.jsonEquals = jsonEquals;
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const ts_utils_1 = require("@fgv/ts-utils");
+const utils_1 = require("./utils");
+/**
+ * Internal recursive diff function that builds the change list.
+ */
+function diffRecursive(obj1, obj2, path, options, changes) {
+    const pathPrefix = path ? `${path}${options.pathSeparator}` : '';
+    // Handle primitive values
+    if ((0, ts_json_base_1.isJsonPrimitive)(obj1) || (0, ts_json_base_1.isJsonPrimitive)(obj2)) {
+        if (!(0, utils_1.deepEquals)(obj1, obj2)) {
+            changes.push({
+                path,
+                type: 'modified',
+                oldValue: obj1,
+                newValue: obj2
+            });
+        }
+        else if (options.includeUnchanged) {
+            changes.push({
+                path,
+                type: 'unchanged',
+                oldValue: obj1,
+                newValue: obj2
+            });
+        }
+        return;
+    }
+    // Handle arrays
+    if ((0, ts_json_base_1.isJsonArray)(obj1) && (0, ts_json_base_1.isJsonArray)(obj2)) {
+        if (options.arrayOrderMatters) {
+            // Ordered array comparison
+            const maxLength = Math.max(obj1.length, obj2.length);
+            for (let i = 0; i < maxLength; i++) {
+                const itemPath = `${pathPrefix}${i}`;
+                if (i >= obj1.length) {
+                    changes.push({
+                        path: itemPath,
+                        type: 'added',
+                        newValue: obj2[i]
+                    });
+                }
+                else if (i >= obj2.length) {
+                    changes.push({
+                        path: itemPath,
+                        type: 'removed',
+                        oldValue: obj1[i]
+                    });
+                }
+                else {
+                    diffRecursive(obj1[i], obj2[i], itemPath, options, changes);
+                }
+            }
+        }
+        else {
+            // Unordered array comparison - simplified approach
+            // This is a basic implementation; a more sophisticated approach would use
+            // algorithms like longest common subsequence for better matching
+            const processed = new Set();
+            // Find matching elements
+            for (let i = 0; i < obj1.length; i++) {
+                let found = false;
+                for (let j = 0; j < obj2.length; j++) {
+                    if (!processed.has(j) && (0, utils_1.deepEquals)(obj1[i], obj2[j])) {
+                        processed.add(j);
+                        found = true;
+                        if (options.includeUnchanged) {
+                            changes.push({
+                                path: `${pathPrefix}${i}`,
+                                type: 'unchanged',
+                                oldValue: obj1[i],
+                                newValue: obj2[j]
+                            });
+                        }
+                        break;
+                    }
+                }
+                if (!found) {
+                    changes.push({
+                        path: `${pathPrefix}${i}`,
+                        type: 'removed',
+                        oldValue: obj1[i]
+                    });
+                }
+            }
+            // Find added elements
+            for (let j = 0; j < obj2.length; j++) {
+                if (!processed.has(j)) {
+                    changes.push({
+                        path: `${pathPrefix}${j}`,
+                        type: 'added',
+                        newValue: obj2[j]
+                    });
+                }
+            }
+        }
+        return;
+    }
+    // Handle one array, one non-array
+    if ((0, ts_json_base_1.isJsonArray)(obj1) || (0, ts_json_base_1.isJsonArray)(obj2)) {
+        changes.push({
+            path,
+            type: 'modified',
+            oldValue: obj1,
+            newValue: obj2
+        });
+        return;
+    }
+    // Handle objects
+    if ((0, ts_json_base_1.isJsonObject)(obj1) && (0, ts_json_base_1.isJsonObject)(obj2)) {
+        const keys1 = new Set(Object.keys(obj1));
+        const keys2 = new Set(Object.keys(obj2));
+        const allKeys = new Set([...keys1, ...keys2]);
+        for (const key of allKeys) {
+            const keyPath = path ? `${path}${options.pathSeparator}${key}` : key;
+            if (!keys1.has(key)) {
+                changes.push({
+                    path: keyPath,
+                    type: 'added',
+                    newValue: obj2[key]
+                });
+            }
+            else if (!keys2.has(key)) {
+                changes.push({
+                    path: keyPath,
+                    type: 'removed',
+                    oldValue: obj1[key]
+                });
+            }
+            else {
+                diffRecursive(obj1[key], obj2[key], keyPath, options, changes);
+            }
+        }
+        return;
+    }
+    /* c8 ignore next 9 - defensive code path that should never be reached with valid JsonValue types */
+    // Handle mixed object types
+    changes.push({
+        path,
+        type: 'modified',
+        oldValue: obj1,
+        newValue: obj2
+    });
+}
+/**
+ * Performs a deep diff comparison between two JSON values.
+ *
+ * This function provides detailed change tracking by analyzing every difference
+ * between two JSON structures. It returns a list of specific changes with paths,
+ * making it ideal for debugging, logging, change analysis, and understanding
+ * exactly what has changed between two data states.
+ *
+ * **Key Features:**
+ * - Deep recursive comparison of nested objects and arrays
+ * - Precise path tracking using dot notation (e.g., "user.profile.name")
+ * - Support for all JSON value types: objects, arrays, primitives, null
+ * - Configurable array comparison (ordered vs unordered)
+ * - Optional inclusion of unchanged values for complete comparisons
+ *
+ * **Use Cases:**
+ * - Debugging data changes in applications
+ * - Generating change logs or audit trails
+ * - Validating API responses against expected data
+ * - Creating detailed diff reports for data synchronization
+ *
+ * @param obj1 - The first JSON value to compare (often the "before" state)
+ * @param obj2 - The second JSON value to compare (often the "after" state)
+ * @param options - Optional configuration for customizing diff behavior
+ * @returns A Result containing the diff result with all detected changes
+ *
+ * @example Basic usage with objects
+ * ```typescript
+ * const before = { name: "John", age: 30, city: "NYC" };
+ * const after = { name: "Jane", age: 30, country: "USA" };
+ *
+ * const result = jsonDiff(before, after);
+ * if (result.success) {
+ *   result.value.changes.forEach(change => {
+ *     console.log(`${change.path}: ${change.type}`);
+ *     // Output:
+ *     // name: modified
+ *     // city: removed
+ *     // country: added
+ *   });
+ * }
+ * ```
+ *
+ * @example With arrays and nested structures
+ * ```typescript
+ * const user1 = {
+ *   profile: { name: "John", hobbies: ["reading"] },
+ *   settings: { theme: "dark" }
+ * };
+ * const user2 = {
+ *   profile: { name: "John", hobbies: ["reading", "gaming"] },
+ *   settings: { theme: "light", notifications: true }
+ * };
+ *
+ * const result = jsonDiff(user1, user2);
+ * if (result.success) {
+ *   console.log(result.value.changes);
+ *   // [
+ *   //   { path: "profile.hobbies.1", type: "added", newValue: "gaming" },
+ *   //   { path: "settings.theme", type: "modified", oldValue: "dark", newValue: "light" },
+ *   //   { path: "settings.notifications", type: "added", newValue: true }
+ *   // ]
+ * }
+ * ```
+ *
+ * @example Using options for custom behavior
+ * ```typescript
+ * const options: IJsonDiffOptions = {
+ *   includeUnchanged: true,        // Include unchanged properties
+ *   pathSeparator: '/',            // Use '/' instead of '.' in paths
+ *   arrayOrderMatters: false       // Treat arrays as unordered sets
+ * };
+ *
+ * const result = jsonDiff(obj1, obj2, options);
+ * ```
+ *
+ * @see {@link IDiffResult} for the structure of returned results
+ * @see {@link IDiffChange} for details about individual changes
+ * @see {@link IJsonDiffOptions} for available configuration options
+ * @see {@link jsonThreeWayDiff} for an alternative API focused on actionable results
+ * @see {@link jsonEquals} for simple equality checking without change details
+ *
+ * @public
+ */
+function jsonDiff(obj1, obj2, options = {}) {
+    const opts = Object.assign({ includeUnchanged: false, pathSeparator: '.', arrayOrderMatters: true }, options);
+    const changes = [];
+    diffRecursive(obj1, obj2, '', opts, changes);
+    const result = {
+        changes,
+        identical: changes.length === 0 || changes.every((c) => c.type === 'unchanged')
+    };
+    return (0, ts_utils_1.succeed)(result);
+}
+/**
+ * A simpler helper function that returns true if two JSON values are deeply equal.
+ *
+ * This function provides a fast boolean check for JSON equality without the overhead
+ * of tracking individual changes. It performs the same deep comparison logic as
+ * {@link Diff.jsonDiff} but returns only a true/false result, making it ideal for
+ * conditional logic and validation scenarios.
+ *
+ * **Key Features:**
+ * - Deep recursive comparison of all nested structures
+ * - Handles all JSON types: objects, arrays, primitives, null
+ * - Object property order independence
+ * - Array order significance (index positions matter)
+ * - Performance optimized for equality checking
+ *
+ * **Use Cases:**
+ * - Conditional logic based on data equality
+ * - Input validation and testing assertions
+ * - Caching and memoization keys
+ * - Quick checks before expensive diff operations
+ *
+ * @param obj1 - The first JSON value to compare
+ * @param obj2 - The second JSON value to compare
+ * @returns True if the values are deeply equal, false otherwise
+ *
+ * @example Basic equality checking
+ * ```typescript
+ * // Objects with same structure and values
+ * const user1 = { name: "John", hobbies: ["reading", "gaming"] };
+ * const user2 = { name: "John", hobbies: ["reading", "gaming"] };
+ * console.log(jsonEquals(user1, user2)); // true
+ *
+ * // Different property order (still equal)
+ * const obj1 = { a: 1, b: 2 };
+ * const obj2 = { b: 2, a: 1 };
+ * console.log(jsonEquals(obj1, obj2)); // true
+ *
+ * // Different values
+ * const before = { status: "pending" };
+ * const after = { status: "completed" };
+ * console.log(jsonEquals(before, after)); // false
+ * ```
+ *
+ * @example With nested structures
+ * ```typescript
+ * const config1 = {
+ *   database: { host: "localhost", port: 5432 },
+ *   features: ["auth", "cache"]
+ * };
+ * const config2 = {
+ *   database: { host: "localhost", port: 5432 },
+ *   features: ["auth", "cache"]
+ * };
+ *
+ * if (jsonEquals(config1, config2)) {
+ *   console.log("Configurations are identical");
+ * }
+ * ```
+ *
+ * @example Array order sensitivity
+ * ```typescript
+ * const list1 = [1, 2, 3];
+ * const list2 = [3, 2, 1];
+ * console.log(jsonEquals(list1, list2)); // false - order matters
+ *
+ * const list3 = [1, 2, 3];
+ * const list4 = [1, 2, 3];
+ * console.log(jsonEquals(list3, list4)); // true - same order
+ * ```
+ *
+ * @see {@link Diff.jsonDiff} for detailed change analysis when equality fails
+ * @see {@link jsonThreeWayDiff} for actionable difference results
+ *
+ * @public
+ */
+function jsonEquals(obj1, obj2) {
+    return (0, utils_1.deepEquals)(obj1, obj2);
+}
+//# sourceMappingURL=detailedDiff.js.map

package/lib/packlets/diff/detailedDiff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detailedDiff.js","sourceRoot":"","sources":["../../../src/packlets/diff/detailedDiff.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { JsonValue, isJsonObject, isJsonArray, isJsonPrimitive } from '@fgv/ts-json-base';\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { deepEquals } from './utils';\n\n/**\n * JSON Diff Utilities for TypeScript\n *\n * This module provides comprehensive tools for comparing JSON values and identifying\n * differences between them. It offers two complementary approaches:\n *\n * ## **Detailed Diff API** (`jsonDiff`)\n * Best for analysis, debugging, and understanding specific changes:\n * - Returns a list of individual changes with exact paths and values\n * - Ideal for logging, change tracking, and detailed analysis\n * - Configurable options for array handling and path notation\n *\n * ## **Three-Way Diff API** (`jsonThreeWayDiff`)\n * Best for applying changes and programmatic manipulation:\n * - Returns three objects representing removed, unchanged, and added data\n * - Perfect for merging, UI displays, and actionable results\n * - Treats arrays as atomic units for simpler handling\n *\n * ## **Simple Equality** (`jsonEquals`)\n * Fast boolean check for JSON equality without change details.\n *\n * **Key Features:**\n * - Deep recursive comparison of nested structures\n * - Support for all JSON types: objects, arrays, primitives, null\n * - TypeScript-first with comprehensive type safety\n * - Result pattern for consistent error handling\n * - Extensive TSDoc documentation with practical examples\n *\n * @example Quick comparison of the two main APIs\n * ```typescript\n * const before = { name: \"John\", age: 30, city: \"NYC\" };\n * const after = { name: \"Jane\", age: 30, country: \"USA\" };\n *\n * // Detailed analysis\n * const detailed = jsonDiff(before, after);\n * // Returns: [\n * //   { path: \"name\", type: \"modified\", oldValue: \"John\", newValue: \"Jane\" },\n * //   { path: \"city\", type: \"removed\", oldValue: \"NYC\" },\n * //   { path: \"country\", type: \"added\", newValue: \"USA\" }\n * // ]\n *\n * // Actionable objects\n * const actionable = jsonThreeWayDiff(before, after);\n * // Returns: {\n * //   onlyInA: { name: \"John\", city: \"NYC\" },\n * //   unchanged: { age: 30 },\n * //   onlyInB: { name: \"Jane\", country: \"USA\" }\n * // }\n *\n * // Apply changes: { ...unchanged, ...onlyInB }\n * // Revert changes: { ...unchanged, ...onlyInA }\n * ```\n */\n\n/**\n * Type of change detected in a JSON diff operation.\n *\n * - `'added'` - Property exists only in the second object\n * - `'removed'` - Property exists only in the first object\n * - `'modified'` - Property exists in both objects but with different values\n * - `'unchanged'` - Property exists in both objects with identical values (only included when `includeUnchanged` is true)\n *\n * @public\n */\nexport type DiffChangeType = 'added' | 'removed' | 'modified' | 'unchanged';\n\n/**\n * Represents a single change in a JSON diff operation.\n *\n * Each change describes a specific difference between two JSON values, including\n * the location of the change and the old/new values involved.\n *\n * @example\n * ```typescript\n * // Example changes from diffing { name: \"John\", age: 30 } vs { name: \"Jane\", city: \"NYC\" }\n * const changes: IDiffChange[] = [\n *   { path: \"name\", type: \"modified\", oldValue: \"John\", newValue: \"Jane\" },\n *   { path: \"age\", type: \"removed\", oldValue: 30 },\n *   { path: \"city\", type: \"added\", newValue: \"NYC\" }\n * ];\n * ```\n *\n * @public\n */\nexport interface IDiffChange {\n  /**\n   * The path to the changed value using dot notation.\n   *\n   * For nested objects, uses dots to separate levels (e.g., \"user.profile.name\").\n   * For arrays, uses numeric indices (e.g., \"items.0.id\", \"tags.2\").\n   * Empty string indicates the root value itself changed.\n   *\n   * @example \"user.name\", \"items.0.id\", \"settings.theme\", \"\"\n   */\n  path: string;\n\n  /**\n   * The type of change that occurred.\n   *\n   * @see {@link DiffChangeType} for detailed descriptions of each change type.\n   */\n  type: DiffChangeType;\n\n  /**\n   * The value in the first object.\n   *\n   * - Present for `'removed'` and `'modified'` changes\n   * - Present for `'unchanged'` changes when `includeUnchanged` is true\n   * - Undefined for `'added'` changes\n   */\n  oldValue?: JsonValue;\n\n  /**\n   * The value in the second object.\n   *\n   * - Present for `'added'` and `'modified'` changes\n   * - Present for `'unchanged'` changes when `includeUnchanged` is true\n   * - Undefined for `'removed'` changes\n   */\n  newValue?: JsonValue;\n}\n\n/**\n * Result of a JSON diff operation containing all detected changes.\n *\n * This interface provides detailed information about every difference found\n * between two JSON values, making it ideal for analysis, debugging, and\n * understanding exactly what changed.\n *\n * @example\n * ```typescript\n * const result: IDiffResult = {\n *   changes: [\n *     { path: \"name\", type: \"modified\", oldValue: \"John\", newValue: \"Jane\" },\n *     { path: \"hobbies.1\", type: \"added\", newValue: \"gaming\" }\n *   ],\n *   identical: false\n * };\n * ```\n *\n * @see {@link IDiffChange} for details about individual change objects\n * @see {@link Diff.jsonDiff} for the function that produces this result\n * @public\n */\nexport interface IDiffResult {\n  /**\n   * Array of all changes detected between the two JSON objects.\n   *\n   * Changes are ordered by the path where they occur. For nested structures,\n   * parent changes appear before child changes.\n   */\n  changes: IDiffChange[];\n\n  /**\n   * True if the objects are identical, false otherwise.\n   *\n   * When true, the `changes` array will be empty (unless `includeUnchanged`\n   * option was used, in which case it may contain 'unchanged' entries).\n   */\n  identical: boolean;\n}\n\n/**\n * Options for customizing JSON diff behavior.\n *\n * These options allow you to control how the diff algorithm processes\n * different types of JSON structures and what information is included\n * in the results.\n *\n * @example\n * ```typescript\n * // Include unchanged values and use custom path separator\n * const options: IJsonDiffOptions = {\n *   includeUnchanged: true,\n *   pathSeparator: '/',\n *   arrayOrderMatters: false\n * };\n *\n * const result = jsonDiff(obj1, obj2, options);\n * ```\n *\n * @public\n */\nexport interface IJsonDiffOptions {\n  /**\n   * If true, includes unchanged values in the result.\n   *\n   * When enabled, the diff result will include entries with `type: 'unchanged'`\n   * for properties that exist in both objects with identical values. This can\n   * be useful for displaying complete side-by-side comparisons.\n   *\n   * @defaultValue false\n   */\n  includeUnchanged?: boolean;\n\n  /**\n   * Custom path separator for nested property paths.\n   *\n   * Controls the character used to separate levels in nested object paths.\n   * For example, with separator `'/'`, a nested property would be reported\n   * as `\"user/profile/name\"` instead of `\"user.profile.name\"`.\n   *\n   * @defaultValue \".\"\n   * @example \"/\", \"-\\>\", \"::\"\n   */\n  pathSeparator?: string;\n\n  /**\n   * If true, treats arrays as ordered lists where position matters.\n   * If false, treats arrays as unordered sets.\n   *\n   * When `true` (default), array changes are reported by index position:\n   * `[1,2,3]` vs `[1,3,2]` shows modifications at indices 1 and 2.\n   *\n   * When `false`, arrays are compared as sets: `[1,2,3]` vs `[1,3,2]`\n   * may be considered equivalent (simplified unordered comparison).\n   *\n   * @defaultValue true\n   */\n  arrayOrderMatters?: boolean;\n}\n\n/**\n * Internal recursive diff function that builds the change list.\n */\nfunction diffRecursive(\n  obj1: JsonValue,\n  obj2: JsonValue,\n  path: string,\n  options: Required<IJsonDiffOptions>,\n  changes: IDiffChange[]\n): void {\n  const pathPrefix = path ? `${path}${options.pathSeparator}` : '';\n\n  // Handle primitive values\n  if (isJsonPrimitive(obj1) || isJsonPrimitive(obj2)) {\n    if (!deepEquals(obj1, obj2)) {\n      changes.push({\n        path,\n        type: 'modified',\n        oldValue: obj1,\n        newValue: obj2\n      });\n    } else if (options.includeUnchanged) {\n      changes.push({\n        path,\n        type: 'unchanged',\n        oldValue: obj1,\n        newValue: obj2\n      });\n    }\n    return;\n  }\n\n  // Handle arrays\n  if (isJsonArray(obj1) && isJsonArray(obj2)) {\n    if (options.arrayOrderMatters) {\n      // Ordered array comparison\n      const maxLength = Math.max(obj1.length, obj2.length);\n      for (let i = 0; i < maxLength; i++) {\n        const itemPath = `${pathPrefix}${i}`;\n\n        if (i >= obj1.length) {\n          changes.push({\n            path: itemPath,\n            type: 'added',\n            newValue: obj2[i]\n          });\n        } else if (i >= obj2.length) {\n          changes.push({\n            path: itemPath,\n            type: 'removed',\n            oldValue: obj1[i]\n          });\n        } else {\n          diffRecursive(obj1[i], obj2[i], itemPath, options, changes);\n        }\n      }\n    } else {\n      // Unordered array comparison - simplified approach\n      // This is a basic implementation; a more sophisticated approach would use\n      // algorithms like longest common subsequence for better matching\n      const processed = new Set<number>();\n\n      // Find matching elements\n      for (let i = 0; i < obj1.length; i++) {\n        let found = false;\n        for (let j = 0; j < obj2.length; j++) {\n          if (!processed.has(j) && deepEquals(obj1[i], obj2[j])) {\n            processed.add(j);\n            found = true;\n            if (options.includeUnchanged) {\n              changes.push({\n                path: `${pathPrefix}${i}`,\n                type: 'unchanged',\n                oldValue: obj1[i],\n                newValue: obj2[j]\n              });\n            }\n            break;\n          }\n        }\n        if (!found) {\n          changes.push({\n            path: `${pathPrefix}${i}`,\n            type: 'removed',\n            oldValue: obj1[i]\n          });\n        }\n      }\n\n      // Find added elements\n      for (let j = 0; j < obj2.length; j++) {\n        if (!processed.has(j)) {\n          changes.push({\n            path: `${pathPrefix}${j}`,\n            type: 'added',\n            newValue: obj2[j]\n          });\n        }\n      }\n    }\n    return;\n  }\n\n  // Handle one array, one non-array\n  if (isJsonArray(obj1) || isJsonArray(obj2)) {\n    changes.push({\n      path,\n      type: 'modified',\n      oldValue: obj1,\n      newValue: obj2\n    });\n    return;\n  }\n\n  // Handle objects\n  if (isJsonObject(obj1) && isJsonObject(obj2)) {\n    const keys1 = new Set(Object.keys(obj1));\n    const keys2 = new Set(Object.keys(obj2));\n    const allKeys = new Set([...keys1, ...keys2]);\n\n    for (const key of allKeys) {\n      const keyPath = path ? `${path}${options.pathSeparator}${key}` : key;\n\n      if (!keys1.has(key)) {\n        changes.push({\n          path: keyPath,\n          type: 'added',\n          newValue: obj2[key]\n        });\n      } else if (!keys2.has(key)) {\n        changes.push({\n          path: keyPath,\n          type: 'removed',\n          oldValue: obj1[key]\n        });\n      } else {\n        diffRecursive(obj1[key], obj2[key], keyPath, options, changes);\n      }\n    }\n    return;\n  }\n  /* c8 ignore next 9 - defensive code path that should never be reached with valid JsonValue types */\n\n  // Handle mixed object types\n  changes.push({\n    path,\n    type: 'modified',\n    oldValue: obj1,\n    newValue: obj2\n  });\n}\n\n/**\n * Performs a deep diff comparison between two JSON values.\n *\n * This function provides detailed change tracking by analyzing every difference\n * between two JSON structures. It returns a list of specific changes with paths,\n * making it ideal for debugging, logging, change analysis, and understanding\n * exactly what has changed between two data states.\n *\n * **Key Features:**\n * - Deep recursive comparison of nested objects and arrays\n * - Precise path tracking using dot notation (e.g., \"user.profile.name\")\n * - Support for all JSON value types: objects, arrays, primitives, null\n * - Configurable array comparison (ordered vs unordered)\n * - Optional inclusion of unchanged values for complete comparisons\n *\n * **Use Cases:**\n * - Debugging data changes in applications\n * - Generating change logs or audit trails\n * - Validating API responses against expected data\n * - Creating detailed diff reports for data synchronization\n *\n * @param obj1 - The first JSON value to compare (often the \"before\" state)\n * @param obj2 - The second JSON value to compare (often the \"after\" state)\n * @param options - Optional configuration for customizing diff behavior\n * @returns A Result containing the diff result with all detected changes\n *\n * @example Basic usage with objects\n * ```typescript\n * const before = { name: \"John\", age: 30, city: \"NYC\" };\n * const after = { name: \"Jane\", age: 30, country: \"USA\" };\n *\n * const result = jsonDiff(before, after);\n * if (result.success) {\n *   result.value.changes.forEach(change => {\n *     console.log(`${change.path}: ${change.type}`);\n *     // Output:\n *     // name: modified\n *     // city: removed\n *     // country: added\n *   });\n * }\n * ```\n *\n * @example With arrays and nested structures\n * ```typescript\n * const user1 = {\n *   profile: { name: \"John\", hobbies: [\"reading\"] },\n *   settings: { theme: \"dark\" }\n * };\n * const user2 = {\n *   profile: { name: \"John\", hobbies: [\"reading\", \"gaming\"] },\n *   settings: { theme: \"light\", notifications: true }\n * };\n *\n * const result = jsonDiff(user1, user2);\n * if (result.success) {\n *   console.log(result.value.changes);\n *   // [\n *   //   { path: \"profile.hobbies.1\", type: \"added\", newValue: \"gaming\" },\n *   //   { path: \"settings.theme\", type: \"modified\", oldValue: \"dark\", newValue: \"light\" },\n *   //   { path: \"settings.notifications\", type: \"added\", newValue: true }\n *   // ]\n * }\n * ```\n *\n * @example Using options for custom behavior\n * ```typescript\n * const options: IJsonDiffOptions = {\n *   includeUnchanged: true,        // Include unchanged properties\n *   pathSeparator: '/',            // Use '/' instead of '.' in paths\n *   arrayOrderMatters: false       // Treat arrays as unordered sets\n * };\n *\n * const result = jsonDiff(obj1, obj2, options);\n * ```\n *\n * @see {@link IDiffResult} for the structure of returned results\n * @see {@link IDiffChange} for details about individual changes\n * @see {@link IJsonDiffOptions} for available configuration options\n * @see {@link jsonThreeWayDiff} for an alternative API focused on actionable results\n * @see {@link jsonEquals} for simple equality checking without change details\n *\n * @public\n */\nexport function jsonDiff(\n  obj1: JsonValue,\n  obj2: JsonValue,\n  options: IJsonDiffOptions = {}\n): Result<IDiffResult> {\n  const opts: Required<IJsonDiffOptions> = {\n    includeUnchanged: false,\n    pathSeparator: '.',\n    arrayOrderMatters: true,\n    ...options\n  };\n\n  const changes: IDiffChange[] = [];\n  diffRecursive(obj1, obj2, '', opts, changes);\n\n  const result: IDiffResult = {\n    changes,\n    identical: changes.length === 0 || changes.every((c) => c.type === 'unchanged')\n  };\n\n  return succeed(result);\n}\n\n/**\n * A simpler helper function that returns true if two JSON values are deeply equal.\n *\n * This function provides a fast boolean check for JSON equality without the overhead\n * of tracking individual changes. It performs the same deep comparison logic as\n * {@link Diff.jsonDiff} but returns only a true/false result, making it ideal for\n * conditional logic and validation scenarios.\n *\n * **Key Features:**\n * - Deep recursive comparison of all nested structures\n * - Handles all JSON types: objects, arrays, primitives, null\n * - Object property order independence\n * - Array order significance (index positions matter)\n * - Performance optimized for equality checking\n *\n * **Use Cases:**\n * - Conditional logic based on data equality\n * - Input validation and testing assertions\n * - Caching and memoization keys\n * - Quick checks before expensive diff operations\n *\n * @param obj1 - The first JSON value to compare\n * @param obj2 - The second JSON value to compare\n * @returns True if the values are deeply equal, false otherwise\n *\n * @example Basic equality checking\n * ```typescript\n * // Objects with same structure and values\n * const user1 = { name: \"John\", hobbies: [\"reading\", \"gaming\"] };\n * const user2 = { name: \"John\", hobbies: [\"reading\", \"gaming\"] };\n * console.log(jsonEquals(user1, user2)); // true\n *\n * // Different property order (still equal)\n * const obj1 = { a: 1, b: 2 };\n * const obj2 = { b: 2, a: 1 };\n * console.log(jsonEquals(obj1, obj2)); // true\n *\n * // Different values\n * const before = { status: \"pending\" };\n * const after = { status: \"completed\" };\n * console.log(jsonEquals(before, after)); // false\n * ```\n *\n * @example With nested structures\n * ```typescript\n * const config1 = {\n *   database: { host: \"localhost\", port: 5432 },\n *   features: [\"auth\", \"cache\"]\n * };\n * const config2 = {\n *   database: { host: \"localhost\", port: 5432 },\n *   features: [\"auth\", \"cache\"]\n * };\n *\n * if (jsonEquals(config1, config2)) {\n *   console.log(\"Configurations are identical\");\n * }\n * ```\n *\n * @example Array order sensitivity\n * ```typescript\n * const list1 = [1, 2, 3];\n * const list2 = [3, 2, 1];\n * console.log(jsonEquals(list1, list2)); // false - order matters\n *\n * const list3 = [1, 2, 3];\n * const list4 = [1, 2, 3];\n * console.log(jsonEquals(list3, list4)); // true - same order\n * ```\n *\n * @see {@link Diff.jsonDiff} for detailed change analysis when equality fails\n * @see {@link jsonThreeWayDiff} for actionable difference results\n *\n * @public\n */\nexport function jsonEquals(obj1: JsonValue, obj2: JsonValue): boolean {\n  return deepEquals(obj1, obj2);\n}\n"]}

package/lib/packlets/diff/index.d.ts

@@ -0,0 +1,3 @@
+export * from './detailedDiff';
+export * from './threeWayDiff';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/diff/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/diff/index.ts"],"names":[],"mappings":"AAsBA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/lib/packlets/diff/index.js

@@ -0,0 +1,40 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./detailedDiff"), exports);
+__exportStar(require("./threeWayDiff"), exports);
+//# sourceMappingURL=index.js.map

package/lib/packlets/diff/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/diff/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;AAEH,iDAA+B;AAC/B,iDAA+B","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nexport * from './detailedDiff';\nexport * from './threeWayDiff';\n"]}