@fgv/ts-json 5.0.0-2 → 5.0.0-21

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/index.d.ts

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

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/threeWayDiff.d.ts

@@ -0,0 +1,263 @@
+import { Result } from '@fgv/ts-utils';
+import { JsonValue } from '@fgv/ts-json-base';
+/**
+ * Metadata about the differences found in a three-way diff.
+ *
+ * Provides summary statistics about the types and quantities of changes
+ * detected between two JSON values, making it easy to understand the
+ * overall scope of differences at a glance.
+ *
+ * @example
+ * ```typescript
+ * const metadata: IThreeWayDiffMetadata = {
+ *   removed: 2,    // 2 properties only in first object
+ *   added: 1,      // 1 property only in second object
+ *   modified: 3,   // 3 properties changed between objects
+ *   unchanged: 5   // 5 properties identical in both objects
+ * };
+ *
+ * console.log(`Total changes: ${metadata.added + metadata.removed + metadata.modified}`);
+ * console.log(`Stability: ${metadata.unchanged / (metadata.unchanged + metadata.modified) * 100}%`);
+ * ```
+ *
+ * @public
+ */
+export interface IThreeWayDiffMetadata {
+    /**
+     * Number of properties that exist only in the first object.
+     *
+     * These represent data that was removed when transitioning from
+     * the first object to the second object.
+     */
+    removed: number;
+    /**
+     * Number of properties that exist only in the second object.
+     *
+     * These represent new data that was added when transitioning from
+     * the first object to the second object.
+     */
+    added: number;
+    /**
+     * Number of properties that exist in both objects but have different values.
+     *
+     * These represent data that was modified during the transition between objects.
+     * For arrays, this counts entire array replacements as single modifications.
+     */
+    modified: number;
+    /**
+     * Number of properties that exist in both objects with identical values.
+     *
+     * These represent stable data that remained consistent between the two objects.
+     */
+    unchanged: number;
+}
+/**
+ * Result of a three-way JSON diff operation.
+ *
+ * This interface provides an actionable representation of differences between
+ * two JSON values by separating them into three distinct objects. This approach
+ * makes it easy to apply changes, display side-by-side comparisons, perform
+ * merges, or programmatically work with the differences.
+ *
+ * **Key Benefits:**
+ * - **Actionable Results**: Objects can be directly used for merging or applying changes
+ * - **UI-Friendly**: Perfect for side-by-side diff displays with clear visual separation
+ * - **Merge-Ready**: Simplified three-way merge operations
+ * - **Structured Data**: Maintains original JSON structure rather than flattened paths
+ *
+ * @example Basic usage
+ * ```typescript
+ * const result: IThreeWayDiff = {
+ *   onlyInA: { name: "John", city: "NYC" },      // Original or removed data
+ *   unchanged: { age: 30 },                      // Stable data
+ *   onlyInB: { name: "Jane", country: "USA" },  // New or modified data
+ *   metadata: { added: 1, removed: 1, modified: 1, unchanged: 1 },
+ *   identical: false
+ * };
+ *
+ * // Apply changes: merge unchanged + onlyInB
+ * const updated = { ...result.unchanged, ...result.onlyInB };
+ * // Result: { age: 30, name: "Jane", country: "USA" }
+ *
+ * // Revert changes: merge unchanged + onlyInA
+ * const reverted = { ...result.unchanged, ...result.onlyInA };
+ * // Result: { age: 30, name: "John", city: "NYC" }
+ * ```
+ *
+ * @see {@link IThreeWayDiffMetadata} for metadata structure details
+ * @see {@link jsonThreeWayDiff} for the function that produces this result
+ * @see {@link Diff.jsonDiff} for an alternative detailed change-list approach
+ *
+ * @public
+ */
+export interface IThreeWayDiff {
+    /**
+     * Contains properties that exist only in the first object, plus the first object's
+     * version of any properties that exist in both but have different values.
+     *
+     * This object represents the "old" or "source" state and can be used for:
+     * - Reverting changes by merging with `unchanged`
+     * - Displaying what was removed or changed from the original
+     * - Understanding the baseline state before modifications
+     *
+     * Will be `null` if no properties are unique to the first object.
+     */
+    onlyInA: JsonValue;
+    /**
+     * Contains properties that exist in both objects with identical values.
+     *
+     * This object represents the stable, consistent data between both inputs
+     * and can be used for:
+     * - The foundation for merging operations
+     * - Identifying what remained constant during changes
+     * - Building complete objects by combining with other parts
+     *
+     * Will be `null` if no properties are shared between the objects.
+     */
+    unchanged: JsonValue;
+    /**
+     * Contains properties that exist only in the second object, plus the second object's
+     * version of any properties that exist in both but have different values.
+     *
+     * This object represents the "new" or "target" state and can be used for:
+     * - Applying changes by merging with `unchanged`
+     * - Displaying what was added or changed in the update
+     * - Understanding the desired end state after modifications
+     *
+     * Will be `null` if no properties are unique to the second object.
+     */
+    onlyInB: JsonValue;
+    /**
+     * Summary metadata about the differences found.
+     *
+     * Provides counts of added, removed, modified, and unchanged properties
+     * for quick assessment of the scope and nature of changes.
+     */
+    metadata: IThreeWayDiffMetadata;
+    /**
+     * True if the objects are identical, false otherwise.
+     *
+     * When `true`, both `onlyInA` and `onlyInB` will be `null`, and `unchanged`
+     * will contain the complete shared structure. The metadata will show zero
+     * added, removed, and modified properties.
+     */
+    identical: boolean;
+}
+/**
+ * Performs a three-way diff comparison between two JSON values, returning separate
+ * objects containing the differences and similarities.
+ *
+ * This function provides an alternative to {@link Diff.jsonDiff} that focuses on actionable
+ * results rather than detailed change analysis. Instead of a list of individual changes,
+ * it returns three objects that can be directly used for merging, UI display, or
+ * programmatic manipulation.
+ *
+ * **Key Features:**
+ * - **Actionable Results**: Returns objects ready for immediate use in merging operations
+ * - **Simplified Array Handling**: Arrays are treated as atomic values for cleaner results
+ * - **Structural Preservation**: Maintains original JSON structure rather than flattened paths
+ * - **UI-Optimized**: Perfect for side-by-side diff displays and change visualization
+ * - **Merge-Friendly**: Designed specifically for three-way merge scenarios
+ *
+ * **Array Handling:**
+ * Unlike {@link Diff.jsonDiff}, this function treats arrays as complete units. If arrays differ,
+ * the entire array appears in the appropriate result object rather than computing
+ * element-by-element deltas. This approach is simpler and more predictable for most
+ * use cases involving data updates and synchronization.
+ *
+ * **Use Cases:**
+ * - Applying configuration updates while preserving unchanged settings
+ * - Creating side-by-side diff displays in user interfaces
+ * - Building three-way merge tools for data synchronization
+ * - Implementing undo/redo functionality with granular control
+ * - Generating patch objects for API updates
+ *
+ * @param obj1 - The first JSON value to compare (often the "before" or "source" state)
+ * @param obj2 - The second JSON value to compare (often the "after" or "target" state)
+ * @returns A Result containing the three-way diff with separate objects and metadata
+ *
+ * @example Basic usage for applying changes
+ * ```typescript
+ * const original = { name: "John", age: 30, city: "NYC", active: true };
+ * const updated = { name: "Jane", age: 30, country: "USA", active: true };
+ *
+ * const result = jsonThreeWayDiff(original, updated);
+ * if (result.success) {
+ *   const { onlyInA, unchanged, onlyInB } = result.value;
+ *
+ *   // Apply changes: merge unchanged + onlyInB
+ *   const applied = { ...unchanged, ...onlyInB };
+ *   console.log(applied); // { age: 30, active: true, name: "Jane", country: "USA" }
+ *
+ *   // Revert changes: merge unchanged + onlyInA
+ *   const reverted = { ...unchanged, ...onlyInA };
+ *   console.log(reverted); // { age: 30, active: true, name: "John", city: "NYC" }
+ * }
+ * ```
+ *
+ * @example UI-friendly diff display
+ * ```typescript
+ * const result = jsonThreeWayDiff(userBefore, userAfter);
+ * if (result.success) {
+ *   const { onlyInA, unchanged, onlyInB, metadata } = result.value;
+ *
+ *   // Display summary
+ *   console.log(`Changes: ${metadata.added} added, ${metadata.removed} removed, ${metadata.modified} modified`);
+ *
+ *   // Show removed/old values in red
+ *   if (onlyInA) displayInColor(onlyInA, 'red');
+ *
+ *   // Show unchanged values in gray
+ *   if (unchanged) displayInColor(unchanged, 'gray');
+ *
+ *   // Show added/new values in green
+ *   if (onlyInB) displayInColor(onlyInB, 'green');
+ * }
+ * ```
+ *
+ * @example Nested objects and array handling
+ * ```typescript
+ * const config1 = {
+ *   database: { host: "localhost", port: 5432 },
+ *   features: ["auth", "logging"],
+ *   version: "1.0"
+ * };
+ * const config2 = {
+ *   database: { host: "production.db", port: 5432 },
+ *   features: ["auth", "logging", "metrics"],  // Array treated as complete unit
+ *   version: "1.1"
+ * };
+ *
+ * const result = jsonThreeWayDiff(config1, config2);
+ * if (result.success) {
+ *   // result.value.onlyInA = { database: { host: "localhost" }, features: ["auth", "logging"], version: "1.0" }
+ *   // result.value.unchanged = { database: { port: 5432 } }
+ *   // result.value.onlyInB = { database: { host: "production.db" }, features: ["auth", "logging", "metrics"], version: "1.1" }
+ * }
+ * ```
+ *
+ * @example Conditional updates based on changes
+ * ```typescript
+ * const result = jsonThreeWayDiff(currentState, newState);
+ * if (result.success && !result.value.identical) {
+ *   const { metadata } = result.value;
+ *
+ *   if (metadata.modified > 0) {
+ *     console.log("Critical settings changed - requires restart");
+ *   } else if (metadata.added > 0) {
+ *     console.log("New features enabled");
+ *   } else if (metadata.removed > 0) {
+ *     console.log("Features disabled");
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link IThreeWayDiff} for the structure of returned results
+ * @see {@link IThreeWayDiffMetadata} for metadata details
+ * @see {@link Diff.jsonDiff} for detailed change-by-change analysis
+ * @see {@link jsonEquals} for simple equality checking
+ *
+ * @public
+ */
+export declare function jsonThreeWayDiff(obj1: JsonValue, obj2: JsonValue): Result<IThreeWayDiff>;
+//# sourceMappingURL=threeWayDiff.d.ts.map