@fgv/ts-json 5.0.1-8 → 5.0.1

package/dist/packlets/diff/threeWayDiff.js

@@ -0,0 +1,258 @@
+/*
+ * 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.
+ */
+import { succeed } from '@fgv/ts-utils';
+import { isJsonObject } from '@fgv/ts-json-base';
+import { deepEquals } from './utils';
+/**
+ * Internal function to build three-way diff for objects.
+ */
+function buildThreeWayDiffForObjects(obj1, obj2, metadata) {
+    if (!isJsonObject(obj1) || !isJsonObject(obj2)) {
+        // Handle non-object cases
+        if (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 (deepEquals(val1, val2)) {
+                // Values are identical
+                if (isJsonObject(val1) && 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 (isJsonObject(val1) && 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
+ */
+export 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 succeed(result);
+}
+//# sourceMappingURL=threeWayDiff.js.map

package/dist/packlets/diff/utils.js

@@ -0,0 +1,59 @@
+/*
+ * 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.
+ */
+import { isJsonObject, isJsonArray, isJsonPrimitive } from '@fgv/ts-json-base';
+/**
+ * Deep comparison function for JSON values that handles all JSON types.
+ */
+export function deepEquals(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (isJsonPrimitive(a) || isJsonPrimitive(b)) {
+        return a === b;
+    }
+    if (isJsonArray(a) && 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 (isJsonObject(a) && 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/dist/packlets/editor/common.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=common.js.map

package/dist/packlets/editor/index.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2023 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.
+ */
+import * as EditorRules from './rules';
+export * from './common';
+export { JsonEditor } from './jsonEditor';
+export { JsonEditorRuleBase } from './jsonEditorRule';
+export { JsonEditorState } from './jsonEditorState';
+export { PrefixedJsonMap, ReferenceMapKeyPolicy, SimpleJsonMap } from './jsonReferenceMap';
+export { EditorRules };
+//# sourceMappingURL=index.js.map