@fgv/ts-json 5.0.1-8 → 5.0.1

package/dist/packlets/converters/jsonConverter.js

@@ -0,0 +1,299 @@
+/*
+ * Copyright (c) 2020 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 } from '@fgv/ts-json-base';
+import { Conversion, captureResult, fail, succeed } from '@fgv/ts-utils';
+import { defaultExtendVars } from '../context';
+import { EditorRules, JsonEditor } from '../editor';
+/**
+ * Merges an optionally supplied partial set of {@link IJsonConverterOptions | options} with
+ * the default converter options and taking all dynamic rules into account (e.g. template usage enabled
+ * if variables are supplied and disabled if not),  producing a fully-resolved set of
+ * {@link IJsonConverterOptions | IJsonConverterOptions}.
+ * @param partial - An optional partial {@link IJsonConverterOptions | IJsonConverterOptions}
+ * to be merged.
+ * @public
+ */
+export function mergeDefaultJsonConverterOptions(partial) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const haveVars = (partial === null || partial === void 0 ? void 0 : partial.vars) !== undefined;
+    const haveRefs = (partial === null || partial === void 0 ? void 0 : partial.refs) !== undefined;
+    const extender = (partial === null || partial === void 0 ? void 0 : partial.hasOwnProperty('extendVars')) ? partial.extendVars : defaultExtendVars;
+    const haveExtender = extender !== undefined;
+    const namesDefault = (_a = partial === null || partial === void 0 ? void 0 : partial.useNameTemplates) !== null && _a !== void 0 ? _a : haveVars;
+    const conditionsDefault = (_b = partial === null || partial === void 0 ? void 0 : partial.useConditionalNames) !== null && _b !== void 0 ? _b : namesDefault;
+    const options = {
+        useValueTemplates: (_c = partial === null || partial === void 0 ? void 0 : partial.useValueTemplates) !== null && _c !== void 0 ? _c : haveVars,
+        useNameTemplates: namesDefault,
+        useConditionalNames: conditionsDefault,
+        flattenUnconditionalValues: (_d = partial === null || partial === void 0 ? void 0 : partial.flattenUnconditionalValues) !== null && _d !== void 0 ? _d : conditionsDefault,
+        useMultiValueTemplateNames: (_e = partial === null || partial === void 0 ? void 0 : partial.useMultiValueTemplateNames) !== null && _e !== void 0 ? _e : (haveExtender && namesDefault),
+        useReferences: (_f = partial === null || partial === void 0 ? void 0 : partial.useReferences) !== null && _f !== void 0 ? _f : haveRefs,
+        onInvalidPropertyName: (_g = partial === null || partial === void 0 ? void 0 : partial.onInvalidPropertyName) !== null && _g !== void 0 ? _g : 'error',
+        onInvalidPropertyValue: (_h = partial === null || partial === void 0 ? void 0 : partial.onInvalidPropertyValue) !== null && _h !== void 0 ? _h : 'error',
+        onUndefinedPropertyValue: (_j = partial === null || partial === void 0 ? void 0 : partial.onUndefinedPropertyValue) !== null && _j !== void 0 ? _j : 'ignore',
+        extendVars: extender
+    };
+    if (partial === null || partial === void 0 ? void 0 : partial.vars) {
+        options.vars = partial.vars;
+    }
+    if (partial === null || partial === void 0 ? void 0 : partial.refs) {
+        options.refs = partial.refs;
+    }
+    return options;
+}
+/**
+ * Creates a new {@link IJsonContext | JSON context} using values supplied in an optional partial
+ * {@link IJsonConverterOptions | converter options}.
+ * @param partial - Optional partial {@link IJsonConverterOptions | IJsonConverterOptions} used to
+ * populate the context.
+ * @public
+ */
+export function contextFromConverterOptions(partial) {
+    const context = {};
+    if (partial === null || partial === void 0 ? void 0 : partial.vars) {
+        context.vars = partial.vars;
+    }
+    if (partial === null || partial === void 0 ? void 0 : partial.refs) {
+        context.refs = partial.refs;
+    }
+    if (partial === null || partial === void 0 ? void 0 : partial.hasOwnProperty('extendVars')) {
+        context.extendVars = partial.extendVars;
+    }
+    return context.vars || context.refs || context.extendVars ? context : undefined;
+}
+/**
+ * Creates a new {@link JsonEditor | JsonEditor} from an optionally supplied partial
+ * {@link IJsonConverterOptions | JSON converter options}.
+ * Expands supplied options with default values and constructs an editor with
+ * matching configuration and defined rules.
+ * @param partial - Optional partial {@link IJsonConverterOptions | IJsonConverterOptions}
+ * used to create the editor.
+ * @public
+ */
+export function converterOptionsToEditor(partial) {
+    const converterOptions = mergeDefaultJsonConverterOptions(partial);
+    const context = contextFromConverterOptions(partial);
+    const validation = {
+        onInvalidPropertyName: converterOptions.onInvalidPropertyName,
+        onInvalidPropertyValue: converterOptions.onInvalidPropertyValue,
+        onUndefinedPropertyValue: converterOptions.onUndefinedPropertyValue
+    };
+    const editorOptions = { context, validation };
+    const rules = [];
+    if (converterOptions.useNameTemplates || converterOptions.useValueTemplates) {
+        const templateOptions = Object.assign(Object.assign({}, editorOptions), { useNameTemplates: converterOptions.useNameTemplates, useValueTemplates: converterOptions.useValueTemplates });
+        rules.push(new EditorRules.TemplatedJsonEditorRule(templateOptions));
+    }
+    if (converterOptions.useConditionalNames || converterOptions.flattenUnconditionalValues) {
+        const conditionalOptions = Object.assign(Object.assign({}, editorOptions), { flattenUnconditionalValues: converterOptions.flattenUnconditionalValues });
+        rules.push(new EditorRules.ConditionalJsonEditorRule(conditionalOptions));
+    }
+    if (converterOptions.useMultiValueTemplateNames) {
+        rules.push(new EditorRules.MultiValueJsonEditorRule(editorOptions));
+    }
+    if (converterOptions.useReferences) {
+        rules.push(new EditorRules.ReferenceJsonEditorRule(editorOptions));
+    }
+    return JsonEditor.create(editorOptions, rules);
+}
+/**
+ * A thin wrapper to allow an arbitrary {@link JsonEditor | JsonEditor} to be used via the
+ * \@fgv/ts-utils `Converter` pattern.
+ * @public
+ */
+export class JsonEditorConverter extends Conversion.BaseConverter {
+    /**
+     * Constructs a new {@link JsonEditor | JsonEditor}Converter which uses the supplied editor
+     * @param editor -
+     */
+    constructor(editor) {
+        super((from, __self, context) => this._convert(from, context), editor.options.context);
+        this.editor = editor;
+    }
+    /**
+     * Constructs a new {@link JsonEditor | JsonEditor}Converter which uses the supplied editor
+     * @param editor -
+     */
+    static createWithEditor(editor) {
+        return captureResult(() => new JsonEditorConverter(editor));
+    }
+    /**
+     * Gets a derived converter which fails if the resulting converted
+     * `JsonValue` is not a `JsonObject`.
+     */
+    object() {
+        return this.map((jv) => {
+            if (!isJsonObject(jv)) {
+                return fail(`Cannot convert "${JSON.stringify(jv)}" to JSON object.`);
+            }
+            return succeed(jv);
+        });
+    }
+    /**
+     * Gets a derived converter which fails if the resulting converted
+     * `JsonValue` is not a `JsonArray`.
+     */
+    array() {
+        return this.map((jv) => {
+            if (!Array.isArray(jv) || typeof jv !== 'object') {
+                return fail(`Cannot convert "${JSON.stringify(jv)}" to JSON array.`);
+            }
+            return succeed(jv);
+        });
+    }
+    _convert(from, context) {
+        return this.editor.clone(from, context);
+    }
+}
+/**
+ * An \@fgv/ts-utils `Converter` from `unknown` to type-safe JSON, optionally
+ * rendering any string property names or values using mustache with a supplied view.
+ * @public
+ */
+export class JsonConverter extends JsonEditorConverter {
+    /**
+     * Constructs a new {@link JsonConverter | JsonConverter} with
+     * supplied or default options.
+     * @param options - Optional partial {@link IJsonConverterOptions | options}
+     * to configure the converter.
+     */
+    constructor(options) {
+        const editor = converterOptionsToEditor(options).orThrow();
+        super(editor);
+    }
+    /**
+     * Creates a new {@link JsonConverter | JsonConverter}.
+     * @param options - Optional partial {@link IJsonConverterOptions | options}
+     * to configure the converter.
+     * @returns `Success` with a new {@link JsonConverter | JsonConverter}, or `Failure`
+     * with an informative message if an error occurs.
+     */
+    static create(options) {
+        return captureResult(() => new JsonConverter(options));
+    }
+}
+/**
+ * An \@fgv/ts-utils `Converter` from `unknown` to type-safe JSON
+ * with mustache template rendering and multi-value property name rules enabled
+ * regardless of initial context.
+ * @public
+ */
+export class TemplatedJsonConverter extends JsonEditorConverter {
+    /**
+     * Constructs a new {@link TemplatedJsonConverter | TemplatedJsonConverter} with
+     * supplied or default options.
+     * @param options - Optional partial {@link TemplatedJsonConverterOptions | options}
+     * to configure the converter.
+     */
+    constructor(options) {
+        options = Object.assign(Object.assign({}, options), TemplatedJsonConverter.templateOptions);
+        const editor = converterOptionsToEditor(options).orThrow();
+        super(editor);
+    }
+    /**
+     * Constructs a new {@link TemplatedJsonConverter | TemplatedJsonConverter} with
+     * supplied or default options.
+     * @param options - Optional partial {@link TemplatedJsonConverterOptions | options}
+     * to configure the converter.
+     */
+    static create(options) {
+        return captureResult(() => new TemplatedJsonConverter(options));
+    }
+}
+/**
+ * Default {@link IJsonConverterOptions | JSON converter options}
+ * to enable templated conversion.
+ */
+TemplatedJsonConverter.templateOptions = {
+    useNameTemplates: true,
+    useValueTemplates: true,
+    useMultiValueTemplateNames: true,
+    useConditionalNames: false,
+    flattenUnconditionalValues: false
+};
+/**
+ * An \@fgv/ts-utils `Converter` from `unknown` to type-safe JSON with mustache
+ * template rendering, multi-value property name and conditional property
+ * name rules enabled regardless of initial context.
+ * @public
+ */
+export class ConditionalJsonConverter extends JsonEditorConverter {
+    /**
+     * Constructs a new {@link ConditionalJsonConverter | ConditionalJsonConverter} with supplied or
+     * default options.
+     * @param options - Optional partial {@link ConditionalJsonConverterOptions | configuration or context}
+     * for the converter.
+     */
+    constructor(options) {
+        options = Object.assign(Object.assign({}, options), ConditionalJsonConverter.conditionalOptions);
+        const editor = converterOptionsToEditor(options).orThrow();
+        super(editor);
+    }
+    /**
+     * Constructs a new {@link ConditionalJsonConverter | ConditionalJsonConverter} with supplied or
+     * default options.
+     * @param options - Optional partial {@link ConditionalJsonConverterOptions | configuration or context}
+     * for the converter.
+     */
+    static create(options) {
+        return captureResult(() => new ConditionalJsonConverter(options));
+    }
+}
+/**
+ * Default {@link IJsonConverterOptions | JSON converter options}
+ * to enable conditional conversion.
+ */
+ConditionalJsonConverter.conditionalOptions = Object.assign(Object.assign({}, TemplatedJsonConverter.templateOptions), { useConditionalNames: true, flattenUnconditionalValues: true });
+/**
+ * A \@fgv/ts-utils `Converter` from `unknown` to type-safe JSON with mustache
+ * template rendering, multi-value property name, conditional property
+ * name, and external reference rules enabled regardless of initial context.
+ * @public
+ */
+export class RichJsonConverter extends JsonEditorConverter {
+    /**
+     * Constructs a new {@link RichJsonConverter | RichJsonConverter} with supplied or
+     * default options.
+     * @param options - Optional partial {@link RichJsonConverterOptions | configuration or context}
+     * for the converter.
+     */
+    constructor(options) {
+        options = Object.assign(Object.assign({}, options), RichJsonConverter.richOptions);
+        const editor = converterOptionsToEditor(options).orThrow();
+        super(editor);
+    }
+    /**
+     * Constructs a new {@link RichJsonConverter | RichJsonConverter} with supplied or
+     * default options
+     * @param options - Optional partial {@link RichJsonConverterOptions | configuration or context}
+     * for the converter.
+     */
+    static create(options) {
+        return captureResult(() => new RichJsonConverter(options));
+    }
+}
+/**
+ * Default {@link IJsonConverterOptions | JSON converter options}
+ * to enable rich conversion.
+ */
+RichJsonConverter.richOptions = Object.assign(Object.assign({}, ConditionalJsonConverter.conditionalOptions), { useReferences: true });
+//# sourceMappingURL=jsonConverter.js.map

package/dist/packlets/diff/detailedDiff.js

@@ -0,0 +1,338 @@
+/*
+ * 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';
+import { succeed } from '@fgv/ts-utils';
+import { deepEquals } from './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 (isJsonPrimitive(obj1) || isJsonPrimitive(obj2)) {
+        if (!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 (isJsonArray(obj1) && 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) && 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 (isJsonArray(obj1) || isJsonArray(obj2)) {
+        changes.push({
+            path,
+            type: 'modified',
+            oldValue: obj1,
+            newValue: obj2
+        });
+        return;
+    }
+    // Handle objects
+    if (isJsonObject(obj1) && 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
+ */
+export 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 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
+ */
+export function jsonEquals(obj1, obj2) {
+    return deepEquals(obj1, obj2);
+}
+//# sourceMappingURL=detailedDiff.js.map

package/dist/packlets/diff/index.js

@@ -0,0 +1,24 @@
+/*
+ * 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.
+ */
+export * from './detailedDiff';
+export * from './threeWayDiff';
+//# sourceMappingURL=index.js.map