@scalar/json-magic 0.12.2 → 0.12.4

package/dist/dereference/index.js

@@ -1,5 +1 @@
-import { dereference } from "./dereference.js";
-export {
-  dereference
-};
-//# sourceMappingURL=index.js.map
+export { dereference } from './dereference.js';

package/dist/diff/apply.js

@@ -1,40 +1,73 @@
-class InvalidChangesDetectedError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidChangesDetectedError";
-  }
-}
-const apply = (document, diff) => {
-  const applyChange = (current, path, d, depth = 0) => {
-    if (path[depth] === void 0) {
-      throw new InvalidChangesDetectedError(
-        `Process aborted. Path ${path.join(".")} at depth ${depth} is undefined, check diff object`
-      );
+export class InvalidChangesDetectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidChangesDetectedError';
     }
-    if (depth >= path.length - 1) {
-      if (d.type === "add" || d.type === "update") {
-        current[path[depth]] = d.changes;
-      } else {
-        if (Array.isArray(current)) {
-          current.splice(Number.parseInt(path[depth]), 1);
-        } else {
-          delete current[path[depth]];
+}
+/**
+ * Applies a set of differences to a document object.
+ * The function traverses the document structure following the paths specified in the differences
+ * and applies the corresponding changes (add, update, or delete) at each location.
+ *
+ * @param document - The original document to apply changes to
+ * @param diff - Array of differences to apply, each containing a path and change type
+ * @returns The modified document with all changes applied
+ *
+ * @example
+ * const original = {
+ *   paths: {
+ *     '/users': {
+ *       get: { responses: { '200': { description: 'OK' } } }
+ *     }
+ *   }
+ * }
+ *
+ * const changes = [
+ *   {
+ *     path: ['paths', '/users', 'get', 'responses', '200', 'content'],
+ *     type: 'add',
+ *     changes: { 'application/json': { schema: { type: 'object' } } }
+ *   }
+ * ]
+ *
+ * const updated = apply(original, changes)
+ * // Result: original document with content added to the 200 response
+ */
+export const apply = (document, diff) => {
+    // Traverse the object and apply the change
+    const applyChange = (current, path, d, depth = 0) => {
+        if (path[depth] === undefined) {
+            throw new InvalidChangesDetectedError(`Process aborted. Path ${path.join('.')} at depth ${depth} is undefined, check diff object`);
         }
-      }
-      return;
-    }
-    if (current[path[depth]] === void 0 || typeof current[path[depth]] !== "object") {
-      throw new InvalidChangesDetectedError("Process aborted, check diff object");
+        // We reach where we want to be, now we can apply changes
+        if (depth >= path.length - 1) {
+            if (d.type === 'add' || d.type === 'update') {
+                current[path[depth]] = d.changes;
+            }
+            else {
+                // For arrays we don't use delete operator since it will leave blank spots and not actually remove the element
+                if (Array.isArray(current)) {
+                    current.splice(Number.parseInt(path[depth]), 1);
+                }
+                else {
+                    delete current[path[depth]];
+                }
+            }
+            return;
+        }
+        // Throw an error
+        // This scenario should not happen
+        // 1- if we are adding a new entry, the diff should only give us the higher level diff
+        // 2- if we are updating/deleting an entry, the path to that entry should exists
+        if (current[path[depth]] === undefined || typeof current[path[depth]] !== 'object') {
+            throw new InvalidChangesDetectedError('Process aborted, check diff object');
+        }
+        applyChange(current[path[depth]], path, d, depth + 1);
+    };
+    for (const d of diff) {
+        applyChange(document, d.path, d);
     }
-    applyChange(current[path[depth]], path, d, depth + 1);
-  };
-  for (const d of diff) {
-    applyChange(document, d.path, d);
-  }
-  return document;
-};
-export {
-  InvalidChangesDetectedError,
-  apply
+    // It is safe to cast here because this function mutates the input document
+    // to match the target type T as described by the diff changeset.
+    return document;
 };
-//# sourceMappingURL=apply.js.map

package/dist/diff/diff.js

@@ -1,33 +1,69 @@
-const diff = (doc1, doc2) => {
-  const diff2 = [];
-  const bfs = (el1, el2, prefix = []) => {
-    if (typeof el1 !== typeof el2) {
-      if (typeof el1 === "undefined") {
-        diff2.push({ path: prefix, changes: el2, type: "add" });
-        return;
-      }
-      if (typeof el2 === "undefined") {
-        diff2.push({ path: prefix, changes: el1, type: "delete" });
-        return;
-      }
-      diff2.push({ path: prefix, changes: el2, type: "update" });
-      return;
-    }
-    if (typeof el1 === "object" && typeof el2 === "object" && el1 !== null && el2 !== null) {
-      const keys = /* @__PURE__ */ new Set([...Object.keys(el1), ...Object.keys(el2)]);
-      for (const key of keys) {
-        bfs(el1[key], el2[key], [...prefix, key]);
-      }
-      return;
-    }
-    if (el1 !== el2) {
-      diff2.push({ path: prefix, changes: el2, type: "update" });
-    }
-  };
-  bfs(doc1, doc2);
-  return diff2;
+/**
+ * Get the difference between two objects.
+ *
+ * This function performs a breadth-first comparison between two objects and returns
+ * a list of operations needed to transform the first object into the second.
+ *
+ * @param doc1 - The source object to compare from
+ * @param doc2 - The target object to compare to
+ * @returns A list of operations (add/update/delete) with their paths and changes
+ *
+ * @example
+ * // Compare two simple objects
+ * const original = { name: 'John', age: 30 }
+ * const updated = { name: 'John', age: 31, city: 'New York' }
+ * const differences = diff(original, updated)
+ * // Returns:
+ * // [
+ * //   { path: ['age'], changes: 31, type: 'update' },
+ * //   { path: ['city'], changes: 'New York', type: 'add' }
+ * // ]
+ *
+ * @example
+ * // Compare nested objects
+ * const original = {
+ *   user: { name: 'John', settings: { theme: 'light' } }
+ * }
+ * const updated = {
+ *   user: { name: 'John', settings: { theme: 'dark' } }
+ * }
+ * const differences = diff(original, updated)
+ * // Returns:
+ * // [
+ * //   { path: ['user', 'settings', 'theme'], changes: 'dark', type: 'update' }
+ * // ]
+ */
+export const diff = (doc1, doc2) => {
+    const diff = [];
+    const bfs = (el1, el2, prefix = []) => {
+        // If the types are different, we know that the property has been added, deleted or updated
+        if (typeof el1 !== typeof el2) {
+            if (typeof el1 === 'undefined') {
+                diff.push({ path: prefix, changes: el2, type: 'add' });
+                return;
+            }
+            if (typeof el2 === 'undefined') {
+                diff.push({ path: prefix, changes: el1, type: 'delete' });
+                return;
+            }
+            diff.push({ path: prefix, changes: el2, type: 'update' });
+            return;
+        }
+        // We now can assume that el1 and el2 are of the same type
+        // For nested objects, we need to recursively check the properties
+        if (typeof el1 === 'object' && typeof el2 === 'object' && el1 !== null && el2 !== null) {
+            const keys = new Set([...Object.keys(el1), ...Object.keys(el2)]);
+            for (const key of keys) {
+                bfs(el1[key], el2[key], [...prefix, key]);
+            }
+            return;
+        }
+        // For primitives, we can just compare the values
+        if (el1 !== el2) {
+            diff.push({ path: prefix, changes: el2, type: 'update' });
+        }
+    };
+    // Run breadth-first search
+    bfs(doc1, doc2);
+    return diff;
 };
-export {
-  diff
-};
-//# sourceMappingURL=diff.js.map

package/dist/diff/index.js

@@ -1,9 +1,4 @@
-import { apply } from "../diff/apply.js";
-import { diff } from "../diff/diff.js";
-import { merge } from "../diff/merge.js";
-export {
-  apply,
-  diff,
-  merge
-};
-//# sourceMappingURL=index.js.map
+import { apply } from '../diff/apply.js';
+import { diff } from '../diff/diff.js';
+import { merge } from '../diff/merge.js';
+export { diff, apply, merge };

package/dist/diff/merge.js

@@ -1,61 +1,123 @@
-import { Trie } from "../diff/trie.js";
-import { isArrayEqual, isKeyCollisions, mergeObjects } from "../diff/utils.js";
-const merge = (diff1, diff2) => {
-  const trie = new Trie();
-  for (const [index, diff] of diff1.entries()) {
-    trie.addPath(diff.path, { index, changes: diff });
-  }
-  const skipDiff1 = /* @__PURE__ */ new Set();
-  const skipDiff2 = /* @__PURE__ */ new Set();
-  const conflictsMap1 = /* @__PURE__ */ new Map();
-  const conflictsMap2 = /* @__PURE__ */ new Map();
-  for (const [index, diff] of diff2.entries()) {
-    trie.findMatch(diff.path, (value) => {
-      if (diff.type === "delete") {
-        if (value.changes.type === "delete") {
-          if (value.changes.path.length > diff.path.length) {
-            skipDiff1.add(value.index);
-          } else {
-            skipDiff2.add(value.index);
-          }
-        } else {
-          skipDiff1.add(value.index);
-          skipDiff2.add(index);
-          const conflictEntry = conflictsMap2.get(index);
-          if (conflictEntry !== void 0) {
-            conflictEntry[0].push(value.changes);
-          } else {
-            conflictsMap2.set(index, [[value.changes], [diff]]);
-          }
-        }
-      }
-      if (diff.type === "add" || diff.type === "update") {
-        if (isArrayEqual(diff.path, value.changes.path) && value.changes.type !== "delete" && !isKeyCollisions(diff.changes, value.changes.changes)) {
-          skipDiff1.add(value.index);
-          if (typeof diff.changes === "object") {
-            mergeObjects(diff.changes, value.changes.changes);
-          }
-          return;
-        }
-        skipDiff1.add(value.index);
-        skipDiff2.add(index);
-        const conflictEntry = conflictsMap1.get(value.index);
-        if (conflictEntry !== void 0) {
-          conflictEntry[1].push(diff);
-        } else {
-          conflictsMap1.set(value.index, [[value.changes], [diff]]);
-        }
-      }
-    });
-  }
-  const conflicts = [...conflictsMap1.values(), ...conflictsMap2.values()];
-  const diffs = [
-    ...diff1.filter((_, index) => !skipDiff1.has(index)),
-    ...diff2.filter((_, index) => !skipDiff2.has(index))
-  ];
-  return { diffs, conflicts };
+import { Trie } from '../diff/trie.js';
+import { isArrayEqual, isKeyCollisions, mergeObjects } from '../diff/utils.js';
+/**
+ * Merges two sets of differences from the same document and resolves conflicts.
+ * This function combines changes from two diff lists while handling potential conflicts
+ * that arise when both diffs modify the same paths. It uses a trie data structure for
+ * efficient path matching and conflict detection.
+ *
+ * @param diff1 - First list of differences
+ * @param diff2 - Second list of differences
+ * @returns Object containing:
+ *   - diffs: Combined list of non-conflicting differences
+ *   - conflicts: Array of conflicting difference pairs that need manual resolution
+ *
+ * @example
+ * // Merge two sets of changes to a user profile
+ * const diff1 = [
+ *   { path: ['name'], changes: 'John', type: 'update' },
+ *   { path: ['age'], changes: 30, type: 'add' }
+ * ]
+ * const diff2 = [
+ *   { path: ['name'], changes: 'Johnny', type: 'update' },
+ *   { path: ['address'], changes: { city: 'NY' }, type: 'add' }
+ * ]
+ * const { diffs, conflicts } = merge(diff1, diff2)
+ * // Returns:
+ * // {
+ * //   diffs: [
+ * //     { path: ['age'], changes: 30, type: 'add' },
+ * //     { path: ['address'], changes: { city: 'NY' }, type: 'add' }
+ * //   ],
+ * //   conflicts: [
+ * //     [
+ * //       [{ path: ['name'], changes: 'John', type: 'update' }],
+ * //       [{ path: ['name'], changes: 'Johnny', type: 'update' }]
+ * //     ]
+ * //   ]
+ * // }
+ */
+export const merge = (diff1, diff2) => {
+    // Here we need to use a trie to optimize searching for a prefix
+    // With the naive approach time complexity of the algorithm would be
+    //                         O(n * m)
+    //                           ^   ^
+    // n is the length off diff1 |   | m length of diff2
+    //
+    // Assuming that the maximum depth of the nested objects would be constant lets say 0 <= D <= 100
+    // we try to optimize for that using the tire data structure.
+    // So the new time complexity would be O(n * D) where D is the maximum depth of the nested object
+    const trie = new Trie();
+    // Create the trie
+    for (const [index, diff] of diff1.entries()) {
+        trie.addPath(diff.path, { index, changes: diff });
+    }
+    const skipDiff1 = new Set();
+    const skipDiff2 = new Set();
+    // Keep related conflicts together for easy A, B pick conflict resolution
+    // map key is going to be conflicting index of first diff list where the diff will be
+    // a delete operation or an add/update operation with a one to many conflicts
+    const conflictsMap1 = new Map();
+    // map key will be the index from the second diff list where the diff will be
+    // a delete operation with one to many conflicts
+    const conflictsMap2 = new Map();
+    for (const [index, diff] of diff2.entries()) {
+        trie.findMatch(diff.path, (value) => {
+            if (diff.type === 'delete') {
+                if (value.changes.type === 'delete') {
+                    // Keep the highest depth delete operation and skip the other
+                    if (value.changes.path.length > diff.path.length) {
+                        skipDiff1.add(value.index);
+                    }
+                    else {
+                        skipDiff2.add(value.index);
+                    }
+                }
+                else {
+                    // Take care of updates/add on the same path (we are sure they will be on the
+                    // same path since the change comes from the same document)
+                    skipDiff1.add(value.index);
+                    skipDiff2.add(index);
+                    const conflictEntry = conflictsMap2.get(index);
+                    if (conflictEntry !== undefined) {
+                        conflictEntry[0].push(value.changes);
+                    }
+                    else {
+                        conflictsMap2.set(index, [[value.changes], [diff]]);
+                    }
+                }
+            }
+            if (diff.type === 'add' || diff.type === 'update') {
+                // For add -> add / update -> update operation we try to first see if we can merge this operations
+                if (isArrayEqual(diff.path, value.changes.path) &&
+                    value.changes.type !== 'delete' &&
+                    !isKeyCollisions(diff.changes, value.changes.changes)) {
+                    skipDiff1.add(value.index);
+                    // For non primitive values we merge object keys into diff2
+                    if (typeof diff.changes === 'object') {
+                        mergeObjects(diff.changes, value.changes.changes);
+                    }
+                    return;
+                }
+                // add/update -> delete operations always resolve in conflicts
+                skipDiff1.add(value.index);
+                skipDiff2.add(index);
+                const conflictEntry = conflictsMap1.get(value.index);
+                if (conflictEntry !== undefined) {
+                    conflictEntry[1].push(diff);
+                }
+                else {
+                    conflictsMap1.set(value.index, [[value.changes], [diff]]);
+                }
+            }
+        });
+    }
+    const conflicts = [...conflictsMap1.values(), ...conflictsMap2.values()];
+    // Filter all changes that should be skipped because of conflicts
+    // or auto conflict resolution
+    const diffs = [
+        ...diff1.filter((_, index) => !skipDiff1.has(index)),
+        ...diff2.filter((_, index) => !skipDiff2.has(index)),
+    ];
+    return { diffs, conflicts };
 };
-export {
-  merge
-};
-//# sourceMappingURL=merge.js.map

package/dist/diff/trie.js

@@ -1,82 +1,105 @@
-class TrieNode {
-  constructor(value, children) {
-    this.value = value;
-    this.children = children;
-  }
+/**
+ * Trie data structure
+ *
+ * Read more: https://en.wikipedia.org/wiki/Trie
+ */
+/**
+ * Represents a node in the trie data structure.
+ * Each node can store a value and has a map of child nodes.
+ *
+ * @template Value - The type of value that can be stored in the node
+ */
+export class TrieNode {
+    value;
+    children;
+    constructor(value, children) {
+        this.value = value;
+        this.children = children;
+    }
 }
-class Trie {
-  root;
-  constructor() {
-    this.root = new TrieNode(null, {});
-  }
-  /**
-   * Adds a value to the trie at the specified path.
-   * Creates new nodes as needed to build the path.
-   *
-   * @param path - Array of strings representing the path to store the value
-   * @param value - The value to store at the end of the path
-   *
-   * @example
-   * const trie = new Trie<number>()
-   * trie.addPath(['users', 'john', 'age'], 30)
-   */
-  addPath(path, value) {
-    let current = this.root;
-    for (const dir of path) {
-      if (current.children[dir]) {
-        current = current.children[dir];
-      } else {
-        current.children[dir] = new TrieNode(null, {});
-        current = current.children[dir];
-      }
+/**
+ * A trie (prefix tree) data structure implementation.
+ * This class provides efficient storage and retrieval of values associated with string paths.
+ *
+ * @template Value - The type of value to store at each node
+ *
+ * @example
+ * const trie = new Trie<number>()
+ * trie.addPath(['a', 'b', 'c'], 1)
+ * trie.addPath(['a', 'b', 'd'], 2)
+ * trie.findMatch(['a', 'b'], (value) => console.log(value)) // Logs: 1, 2
+ */
+export class Trie {
+    root;
+    constructor() {
+        this.root = new TrieNode(null, {});
     }
-    current.value = value;
-  }
-  /**
-   * Finds all matches along a given path in the trie.
-   * This method traverses both the exact path and all deeper paths,
-   * executing a callback for each matching value found.
-   *
-   * The search is performed in two phases:
-   * 1. Traverse the exact path, checking for matches at each node
-   * 2. Perform a depth-first search from the end of the path to find all deeper matches
-   *
-   * @param path - Array of strings representing the path to search
-   * @param callback - Function to execute for each matching value found
-   *
-   * @example
-   * const trie = new Trie<number>()
-   * trie.addPath(['a', 'b', 'c'], 1)
-   * trie.addPath(['a', 'b', 'd'], 2)
-   * trie.findMatch(['a', 'b'], (value) => console.log(value)) // Logs: 1, 2
-   */
-  findMatch(path, callback) {
-    let current = this.root;
-    for (const dir of path) {
-      if (current.value !== null) {
-        callback(current.value);
-      }
-      const next = current.children[dir];
-      if (!next) {
-        return;
-      }
-      current = next;
+    /**
+     * Adds a value to the trie at the specified path.
+     * Creates new nodes as needed to build the path.
+     *
+     * @param path - Array of strings representing the path to store the value
+     * @param value - The value to store at the end of the path
+     *
+     * @example
+     * const trie = new Trie<number>()
+     * trie.addPath(['users', 'john', 'age'], 30)
+     */
+    addPath(path, value) {
+        let current = this.root;
+        for (const dir of path) {
+            if (current.children[dir]) {
+                current = current.children[dir];
+            }
+            else {
+                current.children[dir] = new TrieNode(null, {});
+                current = current.children[dir];
+            }
+        }
+        current.value = value;
     }
-    const dfs = (current2) => {
-      for (const child of Object.keys(current2?.children ?? {})) {
-        if (current2 && Object.hasOwn(current2.children, child)) {
-          dfs(current2?.children[child]);
+    /**
+     * Finds all matches along a given path in the trie.
+     * This method traverses both the exact path and all deeper paths,
+     * executing a callback for each matching value found.
+     *
+     * The search is performed in two phases:
+     * 1. Traverse the exact path, checking for matches at each node
+     * 2. Perform a depth-first search from the end of the path to find all deeper matches
+     *
+     * @param path - Array of strings representing the path to search
+     * @param callback - Function to execute for each matching value found
+     *
+     * @example
+     * const trie = new Trie<number>()
+     * trie.addPath(['a', 'b', 'c'], 1)
+     * trie.addPath(['a', 'b', 'd'], 2)
+     * trie.findMatch(['a', 'b'], (value) => console.log(value)) // Logs: 1, 2
+     */
+    findMatch(path, callback) {
+        let current = this.root;
+        for (const dir of path) {
+            // Note: the last callback wont fire here because it will fire on the dfs
+            if (current.value !== null) {
+                callback(current.value);
+            }
+            const next = current.children[dir];
+            if (!next) {
+                return;
+            }
+            current = next;
         }
-      }
-      if (current2?.value) {
-        callback(current2.value);
-      }
-    };
-    dfs(current);
-  }
+        const dfs = (current) => {
+            for (const child of Object.keys(current?.children ?? {})) {
+                if (current && Object.hasOwn(current.children, child)) {
+                    dfs(current?.children[child]);
+                }
+            }
+            if (current?.value) {
+                callback(current.value);
+            }
+        };
+        // Dfs for the rest of the path
+        dfs(current);
+    }
 }
-export {
-  Trie,
-  TrieNode
-};
-//# sourceMappingURL=trie.js.map