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

package/lib/packlets/diff/threeWayDiff.js

@@ -0,0 +1,261 @@
+"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.jsonThreeWayDiff = jsonThreeWayDiff;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const utils_1 = require("./utils");
+/**
+ * Internal function to build three-way diff for objects.
+ */
+function buildThreeWayDiffForObjects(obj1, obj2, metadata) {
+    if (!(0, ts_json_base_1.isJsonObject)(obj1) || !(0, ts_json_base_1.isJsonObject)(obj2)) {
+        // Handle non-object cases
+        if ((0, utils_1.deepEquals)(obj1, obj2)) {
+            metadata.unchanged++;
+            return {
+                onlyInA: null,
+                unchanged: obj1,
+                onlyInB: null
+            };
+        }
+        else {
+            metadata.modified++;
+            return {
+                onlyInA: obj1,
+                unchanged: null,
+                onlyInB: obj2
+            };
+        }
+    }
+    const keys1 = new Set(Object.keys(obj1));
+    const keys2 = new Set(Object.keys(obj2));
+    const allKeys = new Set([...keys1, ...keys2]);
+    const onlyInA = {};
+    const unchanged = {};
+    const onlyInB = {};
+    let hasOnlyInA = false;
+    let hasUnchanged = false;
+    let hasOnlyInB = false;
+    for (const key of allKeys) {
+        if (!keys1.has(key)) {
+            // Property only exists in obj2
+            metadata.added++;
+            onlyInB[key] = obj2[key];
+            hasOnlyInB = true;
+        }
+        else if (!keys2.has(key)) {
+            // Property only exists in obj1
+            metadata.removed++;
+            onlyInA[key] = obj1[key];
+            hasOnlyInA = true;
+        }
+        else {
+            // Property exists in both
+            const val1 = obj1[key];
+            const val2 = obj2[key];
+            if ((0, utils_1.deepEquals)(val1, val2)) {
+                // Values are identical
+                if ((0, ts_json_base_1.isJsonObject)(val1) && (0, ts_json_base_1.isJsonObject)(val2)) {
+                    // For objects, we need to recurse to get proper metadata counts
+                    const childDiff = buildThreeWayDiffForObjects(val1, val2, metadata);
+                    if (childDiff.unchanged !== null) {
+                        unchanged[key] = childDiff.unchanged;
+                        hasUnchanged = true;
+                    }
+                }
+                else {
+                    metadata.unchanged++;
+                    unchanged[key] = val1;
+                    hasUnchanged = true;
+                }
+            }
+            else {
+                // Values are different
+                if ((0, ts_json_base_1.isJsonObject)(val1) && (0, ts_json_base_1.isJsonObject)(val2)) {
+                    // For nested objects, recurse
+                    const childDiff = buildThreeWayDiffForObjects(val1, val2, metadata);
+                    if (childDiff.onlyInA !== null) {
+                        onlyInA[key] = childDiff.onlyInA;
+                        hasOnlyInA = true;
+                    }
+                    if (childDiff.unchanged !== null) {
+                        unchanged[key] = childDiff.unchanged;
+                        hasUnchanged = true;
+                    }
+                    if (childDiff.onlyInB !== null) {
+                        onlyInB[key] = childDiff.onlyInB;
+                        hasOnlyInB = true;
+                    }
+                }
+                else {
+                    // For primitives or arrays, treat as complete replacement
+                    metadata.modified++;
+                    onlyInA[key] = val1;
+                    onlyInB[key] = val2;
+                    hasOnlyInA = true;
+                    hasOnlyInB = true;
+                }
+            }
+        }
+    }
+    return {
+        onlyInA: hasOnlyInA ? onlyInA : null,
+        unchanged: hasUnchanged ? unchanged : null,
+        onlyInB: hasOnlyInB ? onlyInB : null
+    };
+}
+/**
+ * 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
+ */
+function jsonThreeWayDiff(obj1, obj2) {
+    const metadata = {
+        removed: 0,
+        added: 0,
+        modified: 0,
+        unchanged: 0
+    };
+    const diff = buildThreeWayDiffForObjects(obj1, obj2, metadata);
+    const result = {
+        onlyInA: diff.onlyInA,
+        unchanged: diff.unchanged,
+        onlyInB: diff.onlyInB,
+        metadata,
+        identical: metadata.removed === 0 && metadata.added === 0 && metadata.modified === 0
+    };
+    return (0, ts_utils_1.succeed)(result);
+}
+//# sourceMappingURL=threeWayDiff.js.map

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

@@ -0,0 +1,6 @@
+import { JsonValue } from '@fgv/ts-json-base';
+/**
+ * Deep comparison function for JSON values that handles all JSON types.
+ */
+export declare function deepEquals(a: JsonValue, b: JsonValue): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/lib/packlets/diff/utils.js

@@ -0,0 +1,62 @@
+"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.deepEquals = deepEquals;
+const ts_json_base_1 = require("@fgv/ts-json-base");
+/**
+ * Deep comparison function for JSON values that handles all JSON types.
+ */
+function deepEquals(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if ((0, ts_json_base_1.isJsonPrimitive)(a) || (0, ts_json_base_1.isJsonPrimitive)(b)) {
+        return a === b;
+    }
+    if ((0, ts_json_base_1.isJsonArray)(a) && (0, ts_json_base_1.isJsonArray)(b)) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEquals(a[i], b[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if ((0, ts_json_base_1.isJsonObject)(a) && (0, ts_json_base_1.isJsonObject)(b)) {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length) {
+            return false;
+        }
+        for (const key of keysA) {
+            if (!(key in b) || !deepEquals(a[key], b[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=utils.js.map

package/lib/packlets/editor/common.d.ts

@@ -32,6 +32,12 @@ export 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;
 }
 /**
  * Validation options for a {@link JsonEditor | JsonEditor}.

package/lib/packlets/editor/jsonEditor.d.ts

@@ -58,6 +58,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>;
@@ -100,54 +105,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>;