@fgv/ts-json 5.0.0-0 → 5.0.0-11

package/dist/ts-json.d.ts

@@ -230,6 +230,86 @@ export { Converters }
  */
 export declare function defaultExtendVars(base: TemplateVars | undefined, values: VariableValue[]): Result<TemplateVars | undefined>;
 
+declare namespace Diff {
+    export {
+        jsonDiff,
+        jsonEquals,
+        DiffChangeType,
+        IDiffChange,
+        IDiffResult,
+        IJsonDiffOptions,
+        jsonThreeWayDiff,
+        IThreeWayDiffMetadata,
+        IThreeWayDiff
+    }
+}
+export { Diff }
+
+/**
+ * JSON Diff Utilities for TypeScript
+ *
+ * This module provides comprehensive tools for comparing JSON values and identifying
+ * differences between them. It offers two complementary approaches:
+ *
+ * ## **Detailed Diff API** (`jsonDiff`)
+ * Best for analysis, debugging, and understanding specific changes:
+ * - Returns a list of individual changes with exact paths and values
+ * - Ideal for logging, change tracking, and detailed analysis
+ * - Configurable options for array handling and path notation
+ *
+ * ## **Three-Way Diff API** (`jsonThreeWayDiff`)
+ * Best for applying changes and programmatic manipulation:
+ * - Returns three objects representing removed, unchanged, and added data
+ * - Perfect for merging, UI displays, and actionable results
+ * - Treats arrays as atomic units for simpler handling
+ *
+ * ## **Simple Equality** (`jsonEquals`)
+ * Fast boolean check for JSON equality without change details.
+ *
+ * **Key Features:**
+ * - Deep recursive comparison of nested structures
+ * - Support for all JSON types: objects, arrays, primitives, null
+ * - TypeScript-first with comprehensive type safety
+ * - Result pattern for consistent error handling
+ * - Extensive TSDoc documentation with practical examples
+ *
+ * @example Quick comparison of the two main APIs
+ * ```typescript
+ * const before = { name: "John", age: 30, city: "NYC" };
+ * const after = { name: "Jane", age: 30, country: "USA" };
+ *
+ * // Detailed analysis
+ * const detailed = jsonDiff(before, after);
+ * // Returns: [
+ * //   { path: "name", type: "modified", oldValue: "John", newValue: "Jane" },
+ * //   { path: "city", type: "removed", oldValue: "NYC" },
+ * //   { path: "country", type: "added", newValue: "USA" }
+ * // ]
+ *
+ * // Actionable objects
+ * const actionable = jsonThreeWayDiff(before, after);
+ * // Returns: {
+ * //   onlyInA: { name: "John", city: "NYC" },
+ * //   unchanged: { age: 30 },
+ * //   onlyInB: { name: "Jane", country: "USA" }
+ * // }
+ *
+ * // Apply changes: { ...unchanged, ...onlyInB }
+ * // Revert changes: { ...unchanged, ...onlyInA }
+ * ```
+ */
+/**
+ * Type of change detected in a JSON diff operation.
+ *
+ * - `'added'` - Property exists only in the second object
+ * - `'removed'` - Property exists only in the first object
+ * - `'modified'` - Property exists in both objects but with different values
+ * - `'unchanged'` - Property exists in both objects with identical values (only included when `includeUnchanged` is true)
+ *
+ * @public
+ */
+declare type DiffChangeType = 'added' | 'removed' | 'modified' | 'unchanged';
+
 declare namespace EditorRules {
     export {
         IConditionalJsonKeyResult,
@@ -276,6 +356,98 @@ declare interface IConditionalJsonRuleOptions extends Partial<IJsonEditorOptions
     flattenUnconditionalValues?: boolean;
 }
 
+/**
+ * Represents a single change in a JSON diff operation.
+ *
+ * Each change describes a specific difference between two JSON values, including
+ * the location of the change and the old/new values involved.
+ *
+ * @example
+ * ```typescript
+ * // Example changes from diffing { name: "John", age: 30 } vs { name: "Jane", city: "NYC" }
+ * const changes: IDiffChange[] = [
+ *   { path: "name", type: "modified", oldValue: "John", newValue: "Jane" },
+ *   { path: "age", type: "removed", oldValue: 30 },
+ *   { path: "city", type: "added", newValue: "NYC" }
+ * ];
+ * ```
+ *
+ * @public
+ */
+declare interface IDiffChange {
+    /**
+     * The path to the changed value using dot notation.
+     *
+     * For nested objects, uses dots to separate levels (e.g., "user.profile.name").
+     * For arrays, uses numeric indices (e.g., "items.0.id", "tags.2").
+     * Empty string indicates the root value itself changed.
+     *
+     * @example "user.name", "items.0.id", "settings.theme", ""
+     */
+    path: string;
+    /**
+     * The type of change that occurred.
+     *
+     * @see {@link DiffChangeType} for detailed descriptions of each change type.
+     */
+    type: DiffChangeType;
+    /**
+     * The value in the first object.
+     *
+     * - Present for `'removed'` and `'modified'` changes
+     * - Present for `'unchanged'` changes when `includeUnchanged` is true
+     * - Undefined for `'added'` changes
+     */
+    oldValue?: JsonValue;
+    /**
+     * The value in the second object.
+     *
+     * - Present for `'added'` and `'modified'` changes
+     * - Present for `'unchanged'` changes when `includeUnchanged` is true
+     * - Undefined for `'removed'` changes
+     */
+    newValue?: JsonValue;
+}
+
+/**
+ * Result of a JSON diff operation containing all detected changes.
+ *
+ * This interface provides detailed information about every difference found
+ * between two JSON values, making it ideal for analysis, debugging, and
+ * understanding exactly what changed.
+ *
+ * @example
+ * ```typescript
+ * const result: IDiffResult = {
+ *   changes: [
+ *     { path: "name", type: "modified", oldValue: "John", newValue: "Jane" },
+ *     { path: "hobbies.1", type: "added", newValue: "gaming" }
+ *   ],
+ *   identical: false
+ * };
+ * ```
+ *
+ * @see {@link IDiffChange} for details about individual change objects
+ * @see {@link Diff.jsonDiff} for the function that produces this result
+ * @public
+ */
+declare interface IDiffResult {
+    /**
+     * Array of all changes detected between the two JSON objects.
+     *
+     * Changes are ordered by the path where they occur. For nested structures,
+     * parent changes appear before child changes.
+     */
+    changes: IDiffChange[];
+    /**
+     * True if the objects are identical, false otherwise.
+     *
+     * When true, the `changes` array will be empty (unless `includeUnchanged`
+     * option was used, in which case it may contain 'unchanged' entries).
+     */
+    identical: boolean;
+}
+
 /**
  * A specialized JSON editor which does a deep clone of a supplied `JsonValue`.
  * @public
@@ -397,6 +569,64 @@ export declare interface IJsonConverterOptions {
     onUndefinedPropertyValue: 'error' | 'ignore';
 }
 
+/**
+ * Options for customizing JSON diff behavior.
+ *
+ * These options allow you to control how the diff algorithm processes
+ * different types of JSON structures and what information is included
+ * in the results.
+ *
+ * @example
+ * ```typescript
+ * // Include unchanged values and use custom path separator
+ * const options: IJsonDiffOptions = {
+ *   includeUnchanged: true,
+ *   pathSeparator: '/',
+ *   arrayOrderMatters: false
+ * };
+ *
+ * const result = jsonDiff(obj1, obj2, options);
+ * ```
+ *
+ * @public
+ */
+declare interface IJsonDiffOptions {
+    /**
+     * If true, includes unchanged values in the result.
+     *
+     * When enabled, the diff result will include entries with `type: 'unchanged'`
+     * for properties that exist in both objects with identical values. This can
+     * be useful for displaying complete side-by-side comparisons.
+     *
+     * @defaultValue false
+     */
+    includeUnchanged?: boolean;
+    /**
+     * Custom path separator for nested property paths.
+     *
+     * Controls the character used to separate levels in nested object paths.
+     * For example, with separator `'/'`, a nested property would be reported
+     * as `"user/profile/name"` instead of `"user.profile.name"`.
+     *
+     * @defaultValue "."
+     * @example "/", "-\>", "::"
+     */
+    pathSeparator?: string;
+    /**
+     * If true, treats arrays as ordered lists where position matters.
+     * If false, treats arrays as unordered sets.
+     *
+     * When `true` (default), array changes are reported by index position:
+     * `[1,2,3]` vs `[1,3,2]` shows modifications at indices 1 and 2.
+     *
+     * When `false`, arrays are compared as sets: `[1,2,3]` vs `[1,3,2]`
+     * may be considered equivalent (simplified unordered comparison).
+     *
+     * @defaultValue true
+     */
+    arrayOrderMatters?: boolean;
+}
+
 /**
  * Merge options for a {@link JsonEditor | JsonEditor}.
  * @public
@@ -408,6 +638,12 @@ export declare interface IJsonEditorMergeOptions {
      * - `'replace'`: Existing array is completely replaced with the new array
      */
     arrayMergeBehavior: ArrayMergeBehavior;
+    /**
+     * Controls whether null values should be treated as property deletion during merge operations.
+     * - `false` (default): Null values are merged normally, setting the property to null
+     * - `true`: Null values delete the property from the target object during merge
+     */
+    nullAsDelete?: boolean;
 }
 
 /**
@@ -607,6 +843,151 @@ declare interface ITemplatedJsonRuleOptions extends Partial<IJsonEditorOptions>
     useValueTemplates?: boolean;
 }
 
+/**
+ * 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
+ */
+declare 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;
+}
+
+/**
+ * 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
+ */
+declare 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;
+}
+
 /**
  * A simple validating {@link JsonConverter | JSON converter}. Converts unknown to
  * JSON or fails if the unknown contains any invalid JSON values.
@@ -759,6 +1140,92 @@ export declare class JsonConverter extends JsonEditorConverter {
     static create(options?: Partial<IJsonConverterOptions>): Result<JsonConverter>;
 }
 
+/**
+ * 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
+ */
+declare function jsonDiff(obj1: JsonValue, obj2: JsonValue, options?: IJsonDiffOptions): Result<IDiffResult>;
+
 /**
  * Possible `DetailedResult` details for various editor operations.
  * @public
@@ -819,6 +1286,11 @@ export declare class JsonEditor implements IJsonCloneEditor {
      */
     static getDefaultRules(options?: IJsonEditorOptions): Result<IJsonEditorRule[]>;
     /**
+     * Creates a complete IJsonEditorOptions object from partial options, filling in
+     * default values for any missing properties. This ensures all editor instances
+     * have consistent, complete configuration including validation rules and merge behavior.
+     * @param options - Optional partial editor options to merge with defaults
+     * @returns Success with complete editor options, or Failure if validation fails
      * @internal
      */
     protected static _getDefaultOptions(options?: Partial<IJsonEditorOptions>): Result<IJsonEditorOptions>;
@@ -861,54 +1333,78 @@ export declare class JsonEditor implements IJsonCloneEditor {
      */
     clone(src: JsonValue, context?: IJsonContext): DetailedResult<JsonValue, JsonEditFailureReason>;
     /**
-     *
-     * @param target -
-     * @param src -
-     * @param state -
-     * @returns
+     * Merges properties from a source object into a target object, applying editor rules and
+     * null-as-delete logic. This is the core merge implementation that handles property-by-property
+     * merging with rule processing and deferred property handling.
+     * @param target - The target object to merge properties into
+     * @param src - The source object containing properties to merge
+     * @param state - The editor state containing options and context
+     * @returns Success with the modified target object, or Failure with error details
      * @internal
      */
     protected _mergeObjectInPlace(target: JsonObject, src: JsonObject, state: JsonEditorState): Result<JsonObject>;
     /**
-     *
-     * @param src -
-     * @param context -
-     * @returns
+     * Creates a deep clone of a JSON array by recursively cloning each element.
+     * Each array element is cloned using the main clone method, preserving the
+     * editor's rules and validation settings.
+     * @param src - The source JSON array to clone
+     * @param context - Optional JSON context for cloning operations
+     * @returns Success with the cloned array, or Failure with error details
      * @internal
      */
     protected _cloneArray(src: JsonArray, context?: IJsonContext): DetailedResult<JsonArray, JsonEditFailureReason>;
     /**
-     *
-     * @param target -
-     * @param key -
-     * @param newValue -
-     * @param state -
-     * @returns
+     * Merges a single cloned property value into a target object. This method handles
+     * the core merge logic including null-as-delete behavior, array merging, and
+     * recursive object merging. The null-as-delete check occurs before primitive
+     * handling to ensure null values can signal property deletion.
+     * @param target - The target object to merge the property into
+     * @param key - The property key being merged
+     * @param newValue - The cloned value to merge (from source object)
+     * @param state - The editor state containing merge options and context
+     * @returns Success with the merged value, or Failure with error details
      * @internal
      */
     protected _mergeClonedProperty(target: JsonObject, key: string, newValue: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
     /**
-     *
-     * @param key -
-     * @param value -
-     * @param state -
-     * @returns
+     * Applies editor rules to a single property during merge operations. This method
+     * iterates through all configured editor rules to process the property, handling
+     * templates, conditionals, multi-value properties, and references.
+     * @param key - The property key to edit
+     * @param value - The property value to edit
+     * @param state - The editor state containing rules and context
+     * @returns Success with transformed property object, or Failure if rules cannot process
      * @internal
      */
     protected _editProperty(key: string, value: JsonValue, state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
     /**
-     *
-     * @param value -
-     * @param state -
-     * @returns
+     * Applies editor rules to a single JSON value during clone operations. This method
+     * iterates through all configured editor rules to process the value, handling
+     * templates, conditionals, multi-value expressions, and references.
+     * @param value - The JSON value to edit and transform
+     * @param state - The editor state containing rules and context
+     * @returns Success with transformed value, or Failure if rules cannot process
      * @internal
      */
     protected _editValue(value: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
     /**
-     *
-     * @param target -
-     * @param state -
-     * @returns
+     * Clone an object without applying null-as-delete behavior.
+     * This preserves null values during cloning so they can be used for deletion signaling during merge.
+     * @param target - The target object to clone into
+     * @param src - The source object to clone
+     * @param state - The editor state
+     * @returns The cloned object
+     * @internal
+     */
+    protected _cloneObjectWithoutNullAsDelete(target: JsonObject, src: JsonObject, state: JsonEditorState): DetailedResult<JsonObject, JsonEditFailureReason>;
+    /**
+     * Finalizes the merge operation by processing any deferred properties and merging
+     * them into the target object. Deferred properties are those that require special
+     * processing after the initial merge phase, such as references that depend on
+     * other properties being resolved first.
+     * @param target - The target object that has been merged
+     * @param state - The editor state containing deferred properties and rules
+     * @returns Success with the finalized target object, or Failure with error details
      * @internal
      */
     protected _finalizeAndMerge(target: JsonObject, state: JsonEditorState): DetailedResult<JsonObject, JsonEditFailureReason>;
@@ -1091,6 +1587,83 @@ export declare class JsonEditorState {
  */
 export declare type JsonEditorValidationRules = 'invalidPropertyName' | 'invalidPropertyValue' | 'undefinedPropertyValue';
 
+/**
+ * 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
+ */
+declare function jsonEquals(obj1: JsonValue, obj2: JsonValue): boolean;
+
 /**
  * A simple validating {@link JsonConverter | JSON converter}. Converts unknown
  * to a `JsonObject`, or fails if the `unknown` contains invalid
@@ -1113,6 +1686,124 @@ export declare type JsonPropertyEditFailureReason = JsonEditFailureReason | 'def
  */
 export declare type JsonReferenceMapFailureReason = 'unknown' | 'error';
 
+/**
+ * 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
+ */
+declare function jsonThreeWayDiff(obj1: JsonValue, obj2: JsonValue): Result<IThreeWayDiff>;
+
 /**
  * Type representing either a `Map\<string, T\>` or a `Record\<string, T\>`.
  * @public