@scalar/json-magic 0.12.20 → 0.13.2

package/dist/bundle/index.d.ts

@@ -1,3 +1,3 @@
 export type { LifecyclePlugin, LoaderPlugin, Plugin, ResolveResult } from './bundle.js';
-export { bundle, resolveAndCopyReferences } from './bundle.js';
+export { bundle, extensions, isLocalRef, prefixInternalRef, prefixInternalRefRecursive, resolveAndCopyReferences, } from './bundle.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/bundle/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bundle/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACpF,OAAO,EAAE,MAAM,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bundle/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACpF,OAAO,EACL,MAAM,EACN,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,UAAU,CAAA"}

package/dist/bundle/index.js

@@ -1 +1 @@
-export { bundle, resolveAndCopyReferences } from './bundle.js';
+export { bundle, extensions, isLocalRef, prefixInternalRef, prefixInternalRefRecursive, resolveAndCopyReferences, } from './bundle.js';

package/dist/diff/apply.d.ts

@@ -7,9 +7,25 @@ export declare class InvalidChangesDetectedError extends Error {
  * 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
+ * Paths that reach the prototype chain (`__proto__`, `constructor` or `prototype`) are rejected
+ * before anything is written, so a hostile changeset cannot poison `Object.prototype`.
+ *
+ * A change with an empty path asks to replace the document itself, which is not supported: the
+ * function writes through the parent container of each path and the root has no parent. `diff`
+ * emits such a change whenever the two documents differ at the root, which covers a different
+ * `typeof`, `null` against an object, and an array on one side against a plain object on the
+ * other. Those changesets have to be handled by the caller instead of being applied.
+ *
+ * ⚠️ `document` is mutated in place and the result shares structure with the document the diff was
+ * built from: every `add` and `update` writes the change into the document by reference, and those
+ * changes are live references into the target document `diff` compared (see `diff`). A later write
+ * into the result can therefore be seen through that document, and the other way around. Callers
+ * that need an isolated result have to deep clone the document and the changes first.
+ *
+ * @param document - The original document to apply changes to, mutated in place
  * @param diff - Array of differences to apply, each containing a path and change type
- * @returns The modified document with all changes applied
+ * @returns The modified document with all changes applied, structurally shared with the changes
+ * @throws {InvalidChangesDetectedError} When a path is unusable, empty or reaches the prototype chain
  *
  * @example
  * const original = {

package/dist/diff/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/diff/apply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrD,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,UAAU,CAAC,CAAC,CAAC,EAAE,KACpB,CAyCF,CAAA"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/diff/apply.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrD,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,UAAU,CAAC,CAAC,CAAC,EAAE,KACpB,CAkEF,CAAA"}

package/dist/diff/apply.js

@@ -1,3 +1,4 @@
+import { isPollutionKey } from '@scalar/helpers/object/prevent-pollution';
 export class InvalidChangesDetectedError extends Error {
     constructor(message) {
         super(message);
@@ -9,9 +10,25 @@ export class InvalidChangesDetectedError extends Error {
  * 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
+ * Paths that reach the prototype chain (`__proto__`, `constructor` or `prototype`) are rejected
+ * before anything is written, so a hostile changeset cannot poison `Object.prototype`.
+ *
+ * A change with an empty path asks to replace the document itself, which is not supported: the
+ * function writes through the parent container of each path and the root has no parent. `diff`
+ * emits such a change whenever the two documents differ at the root, which covers a different
+ * `typeof`, `null` against an object, and an array on one side against a plain object on the
+ * other. Those changesets have to be handled by the caller instead of being applied.
+ *
+ * ⚠️ `document` is mutated in place and the result shares structure with the document the diff was
+ * built from: every `add` and `update` writes the change into the document by reference, and those
+ * changes are live references into the target document `diff` compared (see `diff`). A later write
+ * into the result can therefore be seen through that document, and the other way around. Callers
+ * that need an isolated result have to deep clone the document and the changes first.
+ *
+ * @param document - The original document to apply changes to, mutated in place
  * @param diff - Array of differences to apply, each containing a path and change type
- * @returns The modified document with all changes applied
+ * @returns The modified document with all changes applied, structurally shared with the changes
+ * @throws {InvalidChangesDetectedError} When a path is unusable, empty or reaches the prototype chain
  *
  * @example
  * const original = {
@@ -64,6 +81,24 @@ export const apply = (document, diff) => {
         }
         applyChange(current[path[depth]], path, d, depth + 1);
     };
+    // Reject the two kinds of unusable entry we can spot without walking the document - a root level
+    // change and a prototype reaching path - before any entry touches it. A path that does not exist
+    // is only found while traversing, so that one can still leave the document half updated.
+    for (const d of diff) {
+        // An empty path targets the document itself. We only ever write through the parent container of
+        // a path, so there is nothing to write into for the root, and the caller has to swap the
+        // document out on its own.
+        if (d.path.length === 0) {
+            throw new InvalidChangesDetectedError('Process aborted. Root-level replacement is not supported, the change targets the document itself instead of a property inside it');
+        }
+        // A path segment such as `__proto__` would make the traversal walk onto `Object.prototype` and
+        // write there, poisoning every object in the runtime. `diff` never emits these segments, so
+        // only a hand-crafted changeset reaches this guard.
+        const unsafeSegment = d.path.find(isPollutionKey);
+        if (unsafeSegment !== undefined) {
+            throw new InvalidChangesDetectedError(`Process aborted. Path ${d.path.join('.')} contains the unsafe segment "${unsafeSegment}", which can modify the prototype chain`);
+        }
+    }
     for (const d of diff) {
         applyChange(document, d.path, d);
     }

package/dist/diff/diff.d.ts

@@ -22,6 +22,16 @@ export type Difference<_T> = {
  * 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.
  *
+ * Keys that reach the prototype chain (`__proto__`, `constructor` and `prototype`) are skipped, so
+ * an untrusted document cannot produce a diff that poisons `Object.prototype` once applied.
+ *
+ * ⚠️ The returned `changes` are live references into the documents, not clones. An `add` or an
+ * `update` carries the very subtree `doc2` holds, and a `delete` carries the subtree from `doc1`,
+ * so writing into a change writes into the document it came from. This matters downstream:
+ * `merge` merges values into these objects, and `apply` writes them into its target document,
+ * which leaves the result structurally shared with `doc2`. Callers that need isolation have to
+ * deep clone the documents before diffing them, or the changes afterwards.
+ *
  * @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

package/dist/diff/diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/diff/diff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,KAAK,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,EAAE,IAAI;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,oBAyC7F,CAAA"}
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/diff/diff.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,KAAK,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,EAAE,IAAI;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,oBAkE7F,CAAA"}

package/dist/diff/diff.js

@@ -1,9 +1,20 @@
+import { isPollutionKey } from '@scalar/helpers/object/prevent-pollution';
 /**
  * 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.
  *
+ * Keys that reach the prototype chain (`__proto__`, `constructor` and `prototype`) are skipped, so
+ * an untrusted document cannot produce a diff that poisons `Object.prototype` once applied.
+ *
+ * ⚠️ The returned `changes` are live references into the documents, not clones. An `add` or an
+ * `update` carries the very subtree `doc2` holds, and a `delete` carries the subtree from `doc1`,
+ * so writing into a change writes into the document it came from. This matters downstream:
+ * `merge` merges values into these objects, and `apply` writes them into its target document,
+ * which leaves the result structurally shared with `doc2`. Callers that need isolation have to
+ * deep clone the documents before diffing them, or the changes afterwards.
+ *
  * @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
@@ -52,8 +63,31 @@ export const diff = (doc1, doc2) => {
         // 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) {
+            // A container type change (array to plain object or vice versa) is a single update.
+            // Recursing would treat array indices as object keys and produce per-key
+            // differences that corrupt the container when applied.
+            if (Array.isArray(el1) !== Array.isArray(el2)) {
+                diff.push({ path: prefix, changes: el2, type: 'update' });
+                return;
+            }
+            // Keys that reach `Object.prototype` are dropped before we recurse. `JSON.parse` turns
+            // `__proto__` into a real own property that `Object.keys` reports, so an untrusted document
+            // would otherwise make us walk the prototype chain and emit a diff that poisons every object
+            // in the runtime once applied. `apply` rejects the same segments, so nothing emitted here can
+            // be turned away later. Note that this only covers the keys compared position by position: a
+            // brand new subtree is emitted as a single value and carries its own keys along untouched.
+            const keys = [...new Set([...Object.keys(el1), ...Object.keys(el2)])].filter((key) => !isPollutionKey(key));
+            // Removed array elements are applied with `splice` (see `apply`), which re-indexes every
+            // element after the removed one. Emitting the highest index first keeps the remaining indices
+            // valid, so an array that loses more than one element still applies correctly. Please keep
+            // this ordering in place, applying the same deletes in ascending order corrupts the array.
+            // Only an array that shrinks can lose elements, so an array that grows keeps the natural
+            // ascending order. Equal length arrays cannot lose elements either, they take the reversed
+            // branch to keep the guard simple. Deletes nested inside elements are object keys rather than
+            // array indices, so they never reach `splice` and are unaffected by the order.
+            // `keys` is a fresh array, so reversing it in place is safe.
+            const orderedKeys = Array.isArray(el1) && Array.isArray(el2) && el1.length >= el2.length ? keys.reverse() : keys;
+            for (const key of orderedKeys) {
                 bfs(el1[key], el2[key], [...prefix, key]);
             }
             return;

package/dist/diff/merge.d.ts

@@ -5,8 +5,15 @@ import type { Difference } from '../diff/diff.js';
  * that arise when both diffs modify the same paths. It uses a trie data structure for
  * efficient path matching and conflict detection.
  *
+ * ⚠️ This function mutates the entries of `diff2`. When two changes on the same path can be folded
+ * together without a collision, the value from `diff1` is merged into the `changes` of the `diff2`
+ * entry, in place. Diffs built by `diff` carry live references into the documents they came from
+ * (see `diff`), so folding two changes together also writes into the document behind `diff2`.
+ * Callers that need the source documents to stay untouched have to deep clone them before diffing,
+ * or clone the changes afterwards.
+ *
  * @param diff1 - First list of differences
- * @param diff2 - Second list of differences
+ * @param diff2 - Second list of differences, whose entries are mutated, see the note above
  * @returns Object containing:
  *   - diffs: Combined list of non-conflicting differences
  *   - conflicts: Array of conflicting difference pairs that need manual resolution

package/dist/diff/merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/diff/merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAI7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE;;;CA8FtE,CAAA"}
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/diff/merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAI7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE;;;CAkGtE,CAAA"}

package/dist/diff/merge.js

@@ -6,8 +6,15 @@ import { isArrayEqual, isKeyCollisions, mergeObjects } from '../diff/utils.js';
  * that arise when both diffs modify the same paths. It uses a trie data structure for
  * efficient path matching and conflict detection.
  *
+ * ⚠️ This function mutates the entries of `diff2`. When two changes on the same path can be folded
+ * together without a collision, the value from `diff1` is merged into the `changes` of the `diff2`
+ * entry, in place. Diffs built by `diff` carry live references into the documents they came from
+ * (see `diff`), so folding two changes together also writes into the document behind `diff2`.
+ * Callers that need the source documents to stay untouched have to deep clone them before diffing,
+ * or clone the changes afterwards.
+ *
  * @param diff1 - First list of differences
- * @param diff2 - Second list of differences
+ * @param diff2 - Second list of differences, whose entries are mutated, see the note above
  * @returns Object containing:
  *   - diffs: Combined list of non-conflicting differences
  *   - conflicts: Array of conflicting difference pairs that need manual resolution
@@ -65,12 +72,16 @@ export const merge = (diff1, diff2) => {
         trie.findMatch(diff.path, (value) => {
             if (diff.type === 'delete') {
                 if (value.changes.type === 'delete') {
-                    // Keep the highest depth delete operation and skip the other
+                    // Keep the shallowest delete operation and skip the other, since deleting an
+                    // ancestor already removes everything the deeper delete would have removed.
+                    // On equal paths the first list keeps the entry and the second one is skipped.
+                    // Note the two sets are indexed differently: `value.index` points into `diff1`,
+                    // while `index` points into `diff2`.
                     if (value.changes.path.length > diff.path.length) {
                         skipDiff1.add(value.index);
                     }
                     else {
-                        skipDiff2.add(value.index);
+                        skipDiff2.add(index);
                     }
                 }
                 else {

package/dist/diff/trie.d.ts

@@ -11,8 +11,14 @@
  */
 export declare class TrieNode<Value> {
     value: Value | null;
+    /**
+     * Children are keyed by path segments taken from untrusted documents, so the map has a null
+     * prototype. A plain object would resolve `children['__proto__']` to `Object.prototype`, and
+     * `addPath` would then write onto the prototype of every object in the runtime. The map is built
+     * here rather than taken as an argument, so a caller cannot hand back a polluting one.
+     */
     children: Record<string, TrieNode<Value>>;
-    constructor(value: Value | null, children: Record<string, TrieNode<Value>>);
+    constructor(value: Value | null);
 }
 /**
  * A trie (prefix tree) data structure implementation.

package/dist/diff/trie.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trie.d.ts","sourceRoot":"","sources":["../../src/diff/trie.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,KAAK;IAEhB,KAAK,EAAE,KAAK,GAAG,IAAI;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;gBADzC,KAAK,EAAE,KAAK,GAAG,IAAI,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;CAEnD;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,IAAI,CAAC,KAAK;IACrB,OAAO,CAAC,IAAI,CAAiB;;IAK7B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK;IAcpC;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;CAgC3D"}
+{"version":3,"file":"trie.d.ts","sourceRoot":"","sources":["../../src/diff/trie.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,KAAK;IASN,KAAK,EAAE,KAAK,GAAG,IAAI;IARtC;;;;;OAKG;IACI,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAsB;gBAEnD,KAAK,EAAE,KAAK,GAAG,IAAI;CACvC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,IAAI,CAAC,KAAK;IACrB,OAAO,CAAC,IAAI,CAAiB;;IAK7B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK;IAcpC;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;CAgC3D"}

package/dist/diff/trie.js

@@ -11,10 +11,15 @@
  */
 export class TrieNode {
     value;
-    children;
-    constructor(value, children) {
+    /**
+     * Children are keyed by path segments taken from untrusted documents, so the map has a null
+     * prototype. A plain object would resolve `children['__proto__']` to `Object.prototype`, and
+     * `addPath` would then write onto the prototype of every object in the runtime. The map is built
+     * here rather than taken as an argument, so a caller cannot hand back a polluting one.
+     */
+    children = Object.create(null);
+    constructor(value) {
         this.value = value;
-        this.children = children;
     }
 }
 /**
@@ -32,7 +37,7 @@ export class TrieNode {
 export class Trie {
     root;
     constructor() {
-        this.root = new TrieNode(null, {});
+        this.root = new TrieNode(null);
     }
     /**
      * Adds a value to the trie at the specified path.
@@ -52,7 +57,7 @@ export class Trie {
                 current = current.children[dir];
             }
             else {
-                current.children[dir] = new TrieNode(null, {});
+                current.children[dir] = new TrieNode(null);
                 current = current.children[dir];
             }
         }

package/dist/diff/utils.d.ts

@@ -18,6 +18,9 @@
  *
  * // Nested objects with collision
  * isKeyCollisions({ a: { b: 1 } }, { a: { b: 2 } }) // true
+ *
+ * // An array against a plain object
+ * isKeyCollisions([1, 2], { 0: 1, 1: 2 }) // true
  */
 export declare const isKeyCollisions: (a: unknown, b: unknown) => boolean;
 /**
@@ -26,8 +29,14 @@ export declare const isKeyCollisions: (a: unknown, b: unknown) => boolean;
  * ⚠️ 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
+ * ⚠️ Note: `a` is mutated in place and the subtrees `b` contributes are attached by reference, not
+ * cloned. Those subtrees stay shared with `b`, so a later write into one of them is seen through
+ * `b` as well. A key both objects already hold keeps the subtree of `a` and merges into it, so
+ * only what `b` brings along is shared. `merge` relies on this to fold two changes into one, which
+ * is how a merge ends up writing into the documents its diffs were built from.
+ *
+ * @param a - Target object to merge into, mutated in place
+ * @param b - Source object to merge from, whose subtrees are shared with the result
  * @returns The merged object (mutates and returns a)
  *
  * @example

package/dist/diff/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/diff/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,YAoBrD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAe3G,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,YAY7C,CAAA"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/diff/utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAoCxD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAsB3G,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,YAY7C,CAAA"}

package/dist/diff/utils.js

@@ -1,3 +1,4 @@
+import { isPollutionKey } from '@scalar/helpers/object/prevent-pollution';
 /**
  * Deep check for objects for collisions
  * Check primitives if their values are different
@@ -18,14 +19,31 @@
  *
  * // Nested objects with collision
  * isKeyCollisions({ a: { b: 1 } }, { a: { b: 2 } }) // true
+ *
+ * // An array against a plain object
+ * isKeyCollisions([1, 2], { 0: 1, 1: 2 }) // true
  */
 export const isKeyCollisions = (a, b) => {
     if (typeof a !== typeof b) {
         return true;
     }
     if (typeof a === 'object' && typeof b === 'object' && a !== null && b !== null) {
+        // An array on one side and a plain object on the other is always a collision. Comparing them
+        // key by key matches array indices against object keys, so two containers that hold the same
+        // values look mergeable, and `mergeObjects` then absorbs one into the other and drops its type.
+        // The same guard lives in `diff`, which reports a container type change as a single update.
+        if (Array.isArray(a) !== Array.isArray(b)) {
+            return true;
+        }
         const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
         for (const key of keys) {
+            // Skip the keys that reach `Object.prototype`, so this stays in step with `mergeObjects`,
+            // which drops them. Without the skip, an own `__proto__` on one side is compared against the
+            // inherited prototype of the other and reports a collision that is not really there, turning
+            // an otherwise auto-mergeable change into a manual conflict.
+            if (isPollutionKey(key)) {
+                continue;
+            }
             if (a[key] !== undefined && b[key] !== undefined) {
                 if (isKeyCollisions(a[key], b[key])) {
                     return true;
@@ -43,8 +61,14 @@ export const isKeyCollisions = (a, b) => {
  * ⚠️ 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
+ * ⚠️ Note: `a` is mutated in place and the subtrees `b` contributes are attached by reference, not
+ * cloned. Those subtrees stay shared with `b`, so a later write into one of them is seen through
+ * `b` as well. A key both objects already hold keeps the subtree of `a` and merges into it, so
+ * only what `b` brings along is shared. `merge` relies on this to fold two changes into one, which
+ * is how a merge ends up writing into the documents its diffs were built from.
+ *
+ * @param a - Target object to merge into, mutated in place
+ * @param b - Source object to merge from, whose subtrees are shared with the result
  * @returns The merged object (mutates and returns a)
  *
  * @example
@@ -60,6 +84,12 @@ export const isKeyCollisions = (a, b) => {
  */
 export const mergeObjects = (a, b) => {
     for (const key in b) {
+        // Merging into a prototype-reaching key writes straight onto the prototype of every object in
+        // the runtime, so these keys are dropped rather than merged. `diff` skips them as well, which
+        // keeps both sides of a merge consistent.
+        if (isPollutionKey(key)) {
+            continue;
+        }
         if (!(key in a)) {
             a[key] = b[key];
         }

package/package.json

@@ -10,7 +10,7 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "packages/json-magic"
   },
-  "version": "0.12.20",
+  "version": "0.13.2",
   "engines": {
     "node": ">=22"
   },
@@ -56,6 +56,11 @@
       "types": "./dist/helpers/get-segments-from-path.d.ts",
       "default": "./dist/helpers/get-segments-from-path.js"
     },
+    "./helpers/get-value-by-path": {
+      "import": "./dist/helpers/get-value-by-path.js",
+      "types": "./dist/helpers/get-value-by-path.d.ts",
+      "default": "./dist/helpers/get-value-by-path.js"
+    },
     "./helpers/is-file-path": {
       "import": "./dist/helpers/is-file-path.js",
       "types": "./dist/helpers/is-file-path.d.ts",
@@ -66,11 +71,26 @@
       "types": "./dist/helpers/is-http-url.d.ts",
       "default": "./dist/helpers/is-http-url.js"
     },
+    "./helpers/is-json-object": {
+      "import": "./dist/helpers/is-json-object.js",
+      "types": "./dist/helpers/is-json-object.d.ts",
+      "default": "./dist/helpers/is-json-object.js"
+    },
+    "./helpers/is-yaml": {
+      "import": "./dist/helpers/is-yaml.js",
+      "types": "./dist/helpers/is-yaml.d.ts",
+      "default": "./dist/helpers/is-yaml.js"
+    },
     "./helpers/normalize": {
       "import": "./dist/helpers/normalize.js",
       "types": "./dist/helpers/normalize.d.ts",
       "default": "./dist/helpers/normalize.js"
     },
+    "./helpers/set-value-at-path": {
+      "import": "./dist/helpers/set-value-at-path.js",
+      "types": "./dist/helpers/set-value-at-path.d.ts",
+      "default": "./dist/helpers/set-value-at-path.js"
+    },
     "./helpers/unescape-json-pointer": {
       "import": "./dist/helpers/unescape-json-pointer.js",
       "types": "./dist/helpers/unescape-json-pointer.d.ts",
@@ -89,10 +109,10 @@
   "dependencies": {
     "pathe": "^2.0.3",
     "yaml": "^2.9.0",
-    "@scalar/helpers": "0.10.0"
+    "@scalar/helpers": "0.11.1"
   },
   "devDependencies": {
-    "fastify": "^5.8.1",
+    "fastify": "^5.11.2",
     "vite": "8.1.5"
   },
   "scripts": {