@scalar/json-magic 0.8.2 → 0.8.3

package/src/diff/merge.ts

@@ -1,136 +0,0 @@
-import type { Difference } from '@/diff/diff'
-import { Trie } from '@/diff/trie'
-import { isArrayEqual, isKeyCollisions, mergeObjects } from '@/diff/utils'
-
-/**
- * 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 = <T>(diff1: Difference<T>[], diff2: Difference<T>[]) => {
-  // 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<{ index: number; changes: Difference<T> }>()
-
-  // Create the trie
-  for (const [index, diff] of diff1.entries()) {
-    trie.addPath(diff.path, { index, changes: diff })
-  }
-
-  const skipDiff1 = new Set<number>()
-  const skipDiff2 = new Set<number>()
-
-  // 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<number, [Difference<T>[], Difference<T>[]]>()
-  // 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<number, [Difference<T>[], Difference<T>[]]>()
-
-  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: [Difference<T>[], Difference<T>[]][] = [...conflictsMap1.values(), ...conflictsMap2.values()]
-
-  // Filter all changes that should be skipped because of conflicts
-  // or auto conflict resolution
-  const diffs: Difference<T>[] = [
-    ...diff1.filter((_, index) => !skipDiff1.has(index)),
-    ...diff2.filter((_, index) => !skipDiff2.has(index)),
-  ]
-
-  return { diffs, conflicts }
-}

package/src/diff/trie.test.ts

@@ -1,30 +0,0 @@
-import { Trie } from '@/diff/trie'
-import { describe, expect, test, vi } from 'vitest'
-
-describe('trie', () => {
-  test('should correctly find matched', () => {
-    const trie = new Trie<number>()
-
-    trie.addPath(['a', 'b', 'c'], 1)
-    trie.addPath(['a', 'b', 'd'], 2)
-    trie.addPath(['a', 'b', 'c', 'd'], 3)
-    trie.addPath(['a', 'b', 'c', 'd', 'e', 'f'], 4)
-    trie.addPath(['a', 'b'], 5)
-
-    /**
-     * created trie:
-     *
-     * (a, null) -> (b, 5) -> (c, 1) -> (d, 3) -> (e, null) -> (f, 4)
-     *          \-> (d, 2)
-     */
-
-    const fn = vi.fn()
-    trie.findMatch(['a', 'b', 'c'], fn)
-
-    expect(fn).toHaveBeenCalledTimes(4)
-    expect(fn).toHaveBeenNthCalledWith(1, 5)
-    expect(fn).toHaveBeenNthCalledWith(2, 4)
-    expect(fn).toHaveBeenNthCalledWith(3, 3)
-    expect(fn).toHaveBeenNthCalledWith(4, 1)
-  })
-})

package/src/diff/trie.ts

@@ -1,113 +0,0 @@
-/**
- * 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> {
-  constructor(
-    public value: Value | null,
-    public children: Record<string, TrieNode<Value>>,
-  ) {}
-}
-
-/**
- * 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<Value> {
-  private root: TrieNode<Value>
-  constructor() {
-    this.root = new TrieNode<Value>(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: string[], value: Value) {
-    let current = this.root
-    for (const dir of path) {
-      if (current.children[dir]) {
-        current = current.children[dir]
-      } else {
-        current.children[dir] = new TrieNode<Value>(null, {})
-        current = current.children[dir]
-      }
-    }
-
-    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: string[], callback: (value: Value) => void) {
-    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
-    }
-
-    const dfs = (current: TrieNode<Value> | undefined) => {
-      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)
-  }
-}

package/src/diff/utils.test.ts

@@ -1,169 +0,0 @@
-import { isArrayEqual, isKeyCollisions, mergeObjects } from '@/diff/utils'
-import { describe, expect, test } from 'vitest'
-
-describe('isKeyCollisions', () => {
-  test.each([
-    [
-      {
-        a: 1,
-      },
-      {
-        a: {
-          hello: 1,
-        },
-      },
-    ],
-    ['hello', 'hi'],
-    [{ a: { b: { c: 1 } } }, { a: { b: { c: 2 } }, c: 1 }],
-  ])('should return true', (a, b) => {
-    expect(isKeyCollisions(a, b)).toBe(true)
-  })
-
-  test.each([
-    [
-      {
-        a: {
-          b: 1,
-        },
-      },
-      {
-        a: {
-          c: 1,
-        },
-      },
-    ],
-    [{ a: { b: { c: 1 } } }, { a: { b: { d: 1 } }, c: 1 }],
-  ])('should return false', (a, b) => {
-    expect(isKeyCollisions(a, b)).toBe(false)
-  })
-})
-
-describe('mergeObjects', () => {
-  test('should merge objects that does not have any conflicting keys', () => {
-    const a = {
-      a: 'Hello',
-    }
-
-    const b = {
-      b: 'Hello',
-    }
-
-    expect(mergeObjects(a, b)).toEqual({
-      a: a.a,
-      b: b.b,
-    })
-  })
-
-  test('should merge objects correctly even when they have the same key with the same value', () => {
-    const a = {
-      a: 'Hello',
-    }
-
-    const b = {
-      a: 'Hello',
-    }
-
-    expect(mergeObjects(a, b)).toEqual({
-      a: a.a,
-    })
-  })
-
-  test('should deeply merge the objects', () => {
-    const a = {
-      a: {
-        b: {
-          c: {
-            d: 1,
-          },
-        },
-      },
-    }
-
-    const b = {
-      a: {
-        b: {
-          d: {
-            e: 1,
-          },
-        },
-      },
-    }
-
-    expect(mergeObjects(a, b)).toEqual({
-      a: {
-        b: {
-          c: {
-            d: 1,
-          },
-          d: {
-            e: 1,
-          },
-        },
-      },
-    })
-  })
-
-  test('should deeply merge the objects when there is same keys', () => {
-    const a = {
-      a: {
-        b: {
-          c: {
-            d: 1,
-          },
-        },
-      },
-    }
-
-    const b = {
-      a: {
-        b: {
-          c: {
-            d: 1,
-          },
-        },
-      },
-      b: 1,
-    }
-
-    expect(mergeObjects(a, b)).toEqual({
-      a: {
-        b: {
-          c: {
-            d: 1,
-          },
-        },
-      },
-      b: 1,
-    })
-  })
-})
-
-describe('isArrayEqual', () => {
-  test.each([
-    [
-      ['a', 'b', 'c'],
-      ['a', 'b', 'c'],
-    ],
-    [
-      [1, 2, 3],
-      [1, 2, 3],
-    ],
-    // @ts-expect-error
-  ])('should return true', (a, b) => expect(isArrayEqual(a, b)).toEqual(true))
-
-  test.each([
-    [
-      ['a', 'b', 'c'],
-      ['a', 'b'],
-    ],
-    [
-      [1, 2, 4],
-      [1, 2, 3],
-    ],
-    [
-      [2, 2, 4],
-      [1, 2, 3],
-    ],
-    // @ts-expect-error
-  ])('should return false', (a, b) => expect(isArrayEqual(a, b)).toEqual(false))
-})

package/src/diff/utils.ts

@@ -1,111 +0,0 @@
-/**
- * Deep check for objects for collisions
- * Check primitives if their values are different
- *
- * @param a - First value to compare
- * @param b - Second value to compare
- * @returns true if there is a collision, false otherwise
- *
- * @example
- * // Objects with different values for same key
- * isKeyCollisions({ a: 1 }, { a: 2 }) // true
- *
- * // Objects with different types
- * isKeyCollisions({ a: 1 }, { a: '1' }) // true
- *
- * // Objects with no collisions
- * isKeyCollisions({ a: 1 }, { b: 2 }) // false
- *
- * // Nested objects with collision
- * isKeyCollisions({ a: { b: 1 } }, { a: { b: 2 } }) // true
- */
-export const isKeyCollisions = (a: unknown, b: unknown) => {
-  if (typeof a !== typeof b) {
-    return true
-  }
-
-  if (typeof a === 'object' && typeof b === 'object' && a !== null && b !== null) {
-    const keys = new Set([...Object.keys(a), ...Object.keys(b)])
-
-    for (const key of keys) {
-      if (a[key] !== undefined && b[key] !== undefined) {
-        if (isKeyCollisions(a[key], b[key])) {
-          return true
-        }
-      }
-    }
-    return false
-  }
-
-  // We handle all primitives here
-  return a !== b
-}
-
-/**
- * Deep merges two objects, combining their properties recursively.
- *
- * ⚠️ Note: This operation assumes there are no key collisions between the objects.
- * Use isKeyCollisions() to check for collisions before merging.
- *
- * @param a - Target object to merge into
- * @param b - Source object to merge from
- * @returns The merged object (mutates and returns a)
- *
- * @example
- * // Simple merge
- * const a = { name: 'John' }
- * const b = { age: 30 }
- * mergeObjects(a, b) // { name: 'John', age: 30 }
- *
- * // Nested merge
- * const a = { user: { name: 'John' } }
- * const b = { user: { age: 30 } }
- * mergeObjects(a, b) // { user: { name: 'John', age: 30 } }
- */
-export const mergeObjects = (a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> => {
-  for (const key in b) {
-    if (!(key in a)) {
-      a[key] = b[key]
-    } else {
-      const aValue = a[key]
-      const bValue = b[key]
-
-      if (typeof aValue === 'object' && aValue !== null && typeof bValue === 'object' && bValue !== null) {
-        a[key] = mergeObjects(aValue as Record<string, unknown>, bValue as Record<string, unknown>)
-      }
-    }
-  }
-
-  return a
-}
-
-/**
- * Checks if two arrays have the same elements in the same order.
- *
- * @param a - First array to compare
- * @param b - Second array to compare
- * @returns True if arrays have same length and elements, false otherwise
- *
- * @example
- * // Arrays with same elements
- * isArrayEqual([1, 2, 3], [1, 2, 3]) // true
- *
- * // Arrays with different elements
- * isArrayEqual([1, 2, 3], [1, 2, 4]) // false
- *
- * // Arrays with different lengths
- * isArrayEqual([1, 2], [1, 2, 3]) // false
- */
-export const isArrayEqual = <T>(a: T[], b: T[]) => {
-  if (a.length !== b.length) {
-    return false
-  }
-
-  for (let i = 0; i <= a.length; ++i) {
-    if (a[i] !== b[i]) {
-      return false
-    }
-  }
-
-  return true
-}