@scalar/json-magic 0.13.0 → 0.13.3

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @scalar/json-magic
 
+## 0.13.3
+
+## 0.13.2
+
+### Patch Changes
+
+- [#9941](https://github.com/scalar/scalar/pull/9941): Republish every package through npm trusted publishing. No functional changes.
+
+## 0.13.1
+
+### Patch Changes
+
+- [#9900](https://github.com/scalar/scalar/pull/9900): Emit array deletions highest-index-first in diff so removing more than one element applies correctly. Before, `diff({ items: [1, 2, 3, 4] }, { items: [1] })` emitted the deletes in ascending index order, and because `apply` removes array elements with `splice`, every delete after the first hit a stale index and left elements behind (`{ items: [1, 3] }`). Deletes on arrays are now ordered from the end of the array, so `apply(a, diff(a, b))` round-trips for arrays that lose any number of elements.
+- [#9906](https://github.com/scalar/scalar/pull/9906): Treat an array and a plain object on the same path as a merge conflict. `isKeyCollisions` compared the two containers key by key, so an array and an object holding the same values under the same indices looked mergeable:
+
+  ```ts
+  isKeyCollisions([1, 2], { 0: 1, 1: 2 }) // → false, so the two were merged
+  mergeObjects([1, 2], { 0: 1, 1: 2 }) // → [1, 2], the object silently absorbed
+  ```
+
+  In practice that meant one side turning `servers: ['https://example.com']` into `servers: { 0: 'https://example.com' }` merged cleanly and lost the container the user picked. Both sides now surface as a conflict to resolve, matching the guard `diff` already applies when a container changes type.
+
+- [#9904](https://github.com/scalar/scalar/pull/9904): Stop the diff utilities from writing through the prototype chain. Documents reach them from remote fetches and user files, and `JSON.parse` turns `__proto__` into a real own property, so `apply({}, diff({}, JSON.parse('{"__proto__": {"polluted": "yes"}}')))` used to write onto `Object.prototype` and poison every object in the runtime. `diff`, `isKeyCollisions` and `mergeObjects` now skip the `__proto__`, `constructor` and `prototype` keys, the trie backing `merge` keys its children on a null prototype, and `apply` rejects any changeset containing one of those segments with an `InvalidChangesDetectedError` before it touches the document.
+
+  This does change behaviour for documents that legitimately carry a property with one of those names, which JSON allows and a schema is free to describe. `diff` no longer compares such a property, so editing it on its own is not reported as a change, and a merge that previously surfaced it as a conflict now merges cleanly. The property still travels along when its parent object is added or updated wholesale, because a new subtree is emitted as a single value. This trade-off matches `preventPollution`, which the rest of the codebase already applies to untrusted keys.
+
+  `@scalar/helpers` gains an `isPollutionKey` predicate next to the existing `preventPollution`, so the list of dangerous keys lives in one place.
+
+- [#9907](https://github.com/scalar/scalar/pull/9907): Explain the root-level change `apply` cannot handle, and document that `diff`, `merge` and `apply` share references with the documents they work on.
+
+  A change with an empty path asks to replace the document itself, which `apply` cannot do since it writes through the parent container of each path. It used to fail with `Process aborted. Path  at depth 0 is undefined, check diff object` halfway through a changeset, and now says so up front and leaves the document untouched:
+
+  ```ts
+  // `diff` emits a change with an empty path whenever the two documents differ at the root
+  apply({ name: 'John' }, [{ path: [], changes: [1, 2], type: 'update' }])
+  // InvalidChangesDetectedError: Process aborted. Root-level replacement is not supported, the
+  // change targets the document itself instead of a property inside it
+  ```
+
+  The changes a diff carries are live references into the documents it compared, so `merge` writes into the document behind its second diff list and an applied document stays structurally shared with the diff. That contract is now spelled out on `diff`, `merge` and `apply` — deep clone the documents when a caller needs isolation.
+
+- [#9902](https://github.com/scalar/scalar/pull/9902): Skip the correct entry when `merge` resolves a delete against a delete. The matching entry was skipped using an index into the first diff list to address the second one, so whenever the two matching deletes sat at different positions in their lists, an unrelated change was silently dropped and the shared delete was duplicated. Merging `[delete x, delete a]` with `[delete a, delete y]` returned `[delete x, delete a, delete a]` instead of `[delete x, delete a, delete y]`.
+
+  One case changes for the worse and is pinned by a test: when a delete is subsumed by a delete on the other side that itself ends up in `conflicts`, the subsumed delete is dropped from the result. That gap already existed, but skipping the wrong index used to hide it for some orderings of the second diff list, so it is now consistent rather than order-dependent.
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -1,11 +1,10 @@
-# json-magic
+# @scalar/json-magic
 
 [![Version](https://img.shields.io/npm/v/%40scalar/json-magic)](https://www.npmjs.com/package/@scalar/json-magic)
 [![Downloads](https://img.shields.io/npm/dm/%40scalar/json-magic)](https://www.npmjs.com/package/@scalar/json-magic)
 [![License](https://img.shields.io/npm/l/%40scalar%2Fjson-magic)](https://www.npmjs.com/package/@scalar/json-magic)
 [![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
 
-
 A collection of utilities for working with JSON objects, including diffing, conflict resolution, bundling and more.
 
 ---
@@ -21,9 +20,41 @@ Scalar is an open-source API platform for teams who want beautiful developer int
 
 ---
 
+## Installation
+
+```bash
+npm add @scalar/json-magic
+```
+
+## Entry points
+
+There is no root export. Every module is imported from its own entry point, so you only pay for what you use.
+
+| Entry point | Exports |
+| --- | --- |
+| `@scalar/json-magic/bundle` | `bundle`, `isLocalRef`, `prefixInternalRef`, `prefixInternalRefRecursive`, `resolveAndCopyReferences`, plus the `Plugin`, `LoaderPlugin`, `LifecyclePlugin` and `ResolveResult` types |
+| `@scalar/json-magic/bundle/plugins/browser` | `fetchUrls`, `parseJson`, `parseYaml` |
+| `@scalar/json-magic/bundle/plugins/node` | `fetchUrls`, `parseJson`, `parseYaml`, `readFiles` |
+| `@scalar/json-magic/bundle/value-generator` | `getHash`, `generateUniqueValue`, `uniqueValueGeneratorFactory` |
+| `@scalar/json-magic/dereference` | `dereference` |
+| `@scalar/json-magic/diff` | `diff`, `merge`, `apply`, the `Difference` type |
+| `@scalar/json-magic/magic-proxy` | `createMagicProxy`, `getRaw` |
+| `@scalar/json-magic/helpers/*` | Small standalone helpers, see [Helpers](#helpers) |
+
+## Which module do I need?
+
+| I want to … | Use |
+| --- | --- |
+| Pull external `$ref` documents into a single self-contained document | [`bundle`](#bundle) |
+| Read through `$ref` pointers without rewriting the document | [`magic-proxy`](#magic-proxy) |
+| Resolve every `$ref`, internal and external, in one call | [`dereference`](#dereference) |
+| Compare two documents and merge concurrent edits | [`diff`](#diff) |
+
 ## bundle
 
-Bundle external references in a json object
+`bundle` walks a JSON object, resolves every external `$ref` (URLs, local files, or anything a custom loader plugin can handle) and embeds the result into the document itself. The original `$ref` values are rewritten to point at the embedded copies, so the output is a single self-contained document.
+
+External documents are stored under the `x-ext` key, and the mapping between the generated keys and their original URLs is stored under `x-ext-urls`. Both keys are configurable, see [Options](#options).
 
 ### Quick start
 
@@ -31,23 +62,36 @@ Bundle external references in a json object
 import { bundle } from '@scalar/json-magic/bundle'
 import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
 
-const result = await bundle({
- $ref: 'http://example.com/document.json' 
-}, {
-  plugins: [fetchUrls()],
-  treeShake: false,
-})
+const result = await bundle(
+  { $ref: 'http://example.com/document.json' },
+  {
+    plugins: [fetchUrls()],
+    treeShake: false,
+  },
+)
 
-// get the bundled json object
+// The bundled document
 console.log(result)
 ```
 
-#### Plugins
+When the input is an object it is modified in place, and the same object is returned. When the input is a string it is resolved with the given plugins first.
+
+### Loaders
+
+A loader plugin teaches the bundler how to read one kind of reference. Import loaders from `@scalar/json-magic/bundle/plugins/browser` in the browser, or from `@scalar/json-magic/bundle/plugins/node` in Node.js. The Node entry point is a superset: it adds `readFiles`, which needs filesystem access.
+
+| Loader | Handles | Available in |
+| --- | --- | --- |
+| `fetchUrls` | `http://` and `https://` references | browser, node |
+| `readFiles` | Local file paths | node |
+| `parseJson` | A raw JSON string passed as the input | browser, node |
+| `parseYaml` | A raw YAML string passed as the input | browser, node |
 
-If you are on a browser environment import plugins from `@scalar/json-magic/bundle/plugins/browser` while if you are on a node environment you can import from `@scalar/json-magic/bundle/plugins/node`
+You can combine as many loaders as you need. The first one whose `validate` returns `true` wins.
 
-##### fetchUrls
-This plugins handles all external urls. It works for both node.js and browser environment
+#### fetchUrls
+
+Resolves remote documents over HTTP. It works in both Node.js and the browser.
 
 ```ts
 import { bundle } from '@scalar/json-magic/bundle'
@@ -59,102 +103,104 @@ const document = {
   paths: {},
   components: {
     schemas: {
-      User: { $ref: 'https://example.com/user-schema.json#' }
-    }
-  }
+      User: { $ref: 'https://example.com/user-schema.json#' },
+    },
+  },
 }
 
-// This will bundle all external documents and turn all references from external into internal
+// This bundles all external documents and turns external references into internal ones
 await bundle(document, {
   plugins: [fetchUrls()],
-  treeShake: true  // <------  This flag will try to remove any unused part of the external document
+  // Removes the parts of the external documents that are not referenced
+  treeShake: true,
 })
 
 console.log(document)
 ```
 
-###### Limiting the number of concurrent requests
+##### Limiting the number of concurrent requests
 
 ```ts
+import { bundle } from '@scalar/json-magic/bundle'
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
+
 await bundle(document, {
   plugins: [
     fetchUrls({
-      limit: 10, // it should run at most 10 requests at the same time
+      // Run at most 10 requests at the same time
+      limit: 10,
     }),
   ],
-  treeShake: false
+  treeShake: false,
 })
-
 ```
 
-###### Custom headers
-To pass custom headers to requests for specific domains you can configure the fetch plugin like the example
+##### Custom headers
+
+Headers are matched against the host of the reference, so a token is only ever sent to the domains you list.
 
 ```ts
-await bundle(
-  document,
-  {
-    plugins: [
-      fetchUrls({
-        // Pass custom headers
-        // The header will only be attached to the list of domains
-        headers: [
-          {
-            domains: ['example.com'],
-            headers: {
-              'Authorization': 'Bearer <TOKEN>'
-            }
-          }
-        ]
-      }),
-      readFiles(),
-    ],
-    treeShake: false
-  },
-)
+import { bundle } from '@scalar/json-magic/bundle'
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
+
+await bundle(document, {
+  plugins: [
+    fetchUrls({
+      headers: [
+        {
+          domains: ['example.com'],
+          headers: {
+            Authorization: 'Bearer <TOKEN>',
+          },
+        },
+      ],
+    }),
+  ],
+  treeShake: false,
+})
 ```
 
-###### Custom fetch function
-For advanced use cases like proxying requests or implementing custom network logic, you can provide your own fetch implementation. This allows you to handle things like CORS restrictions, custom authentication flows, or request/response transformations.
+##### Custom fetch function
+
+For advanced use cases like proxying requests or implementing custom network logic, you can provide your own fetch implementation. This allows you to handle things like CORS restrictions, custom authentication flows, or request and response transformations.
 
 ```ts
-await bundle(
-  document,
-  {
-    plugins: [
-      fetchUrls({
-        // Custom fetcher function
-        fetch: async (input, init) => {
-          console.log('Custom fetch logic')
-          return fetch(input, init)
-        },
-      })
-      readFiles(),
-    ],
-    treeShake: false
-  },
-)
+import { bundle } from '@scalar/json-magic/bundle'
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
+
+await bundle(document, {
+  plugins: [
+    fetchUrls({
+      fetch: async (input, init) => {
+        console.log('Custom fetch logic')
+        return fetch(input, init)
+      },
+    }),
+  ],
+  treeShake: false,
+})
 ```
 
-###### Bundle from remote url
+##### Bundle from a remote URL
+
+The input itself can be a URL, as long as a loader can handle it.
 
 ```ts
-const result = await bundle(
-  'https://example.com/openapi.json',
-  {
-    plugins: [
-      fetchUrls(),
-    ],
-    treeShake: false
-  },
-)
+import { bundle } from '@scalar/json-magic/bundle'
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
 
-// Bundled document
+const result = await bundle('https://example.com/openapi.json', {
+  plugins: [fetchUrls()],
+  treeShake: false,
+})
+
+// The bundled document
 console.log(result)
 ```
 
-##### readFiles
-This plugins handles local files. Only works on node.js environment
+#### readFiles
+
+Resolves local files. This loader only works in a Node.js environment.
 
 ```ts
 import { bundle } from '@scalar/json-magic/bundle'
@@ -166,91 +212,137 @@ const document = {
   paths: {},
   components: {
     schemas: {
-      User: { $ref: './user-schema.json#' }
-    }
-  }
+      User: { $ref: './user-schema.json#' },
+    },
+  },
 }
 
-// This will bundle all external documents and turn all references from external into internal
 await bundle(document, {
   plugins: [readFiles()],
-  treeShake: false
+  treeShake: false,
 })
 
 console.log(document)
 ```
 
-###### Bundle from local file
-You can pass the file path directly but make sure to have the correct plugins to handle reading from the local files
+##### Bundle from a local file
+
+You can pass the file path directly, as long as `readFiles` is registered to read it.
 
 ```ts
-const result = await bundle(
-  './input.json',
-  {
-    plugins: [
-      readFiles(),
-    ],
-    treeShake: false
-  },
-)
+import { bundle } from '@scalar/json-magic/bundle'
+import { readFiles } from '@scalar/json-magic/bundle/plugins/node'
 
-// Bundled document
+const result = await bundle('./input.json', {
+  plugins: [readFiles()],
+  treeShake: false,
+})
+
+// The bundled document
 console.log(result)
 ```
 
-##### parseJson
+A document that mixes remote and local references needs both loaders:
+
+```ts
+import { bundle } from '@scalar/json-magic/bundle'
+import { fetchUrls, readFiles } from '@scalar/json-magic/bundle/plugins/node'
+
+await bundle('./openapi.json', {
+  plugins: [readFiles(), fetchUrls()],
+  treeShake: false,
+})
+```
+
+#### parseJson
+
+Accepts a raw JSON string as the input.
 
-You can pass raw json string as input
 ```ts
 import { bundle } from '@scalar/json-magic/bundle'
 import { parseJson } from '@scalar/json-magic/bundle/plugins/browser'
 
-const result = await bundle(
-  '{ "openapi": "3.1.1" }',
-  {
-    plugins: [
-      parseJson(),
-    ],
-    treeShake: false
-  },
-)
+const result = await bundle('{ "openapi": "3.1.1" }', {
+  plugins: [parseJson()],
+  treeShake: false,
+})
 
-// Bundled document
+// The bundled document
 console.log(result)
 ```
 
-##### parseYaml
+#### parseYaml
+
+Accepts a raw YAML string as the input.
 
-You can pass raw yaml string as input
 ```ts
 import { bundle } from '@scalar/json-magic/bundle'
 import { parseYaml } from '@scalar/json-magic/bundle/plugins/browser'
 
-const result = await bundle(
-  'openapi: "3.1.1"\n',
-  {
-    plugins: [
-      parseYaml(),
-    ],
-    treeShake: false
-  },
-)
+const result = await bundle('openapi: "3.1.1"\n', {
+  plugins: [parseYaml()],
+  treeShake: false,
+})
 
-// Bundled document
+// The bundled document
 console.log(result)
 ```
 
-#### Bundler Options
+#### Writing a custom loader
+
+A loader is a plain object, so you can resolve references from anywhere: a database, an in-memory map, or a custom protocol.
+
+```ts
+import { bundle, type LoaderPlugin } from '@scalar/json-magic/bundle'
+
+const workspaceFiles: LoaderPlugin = {
+  type: 'loader',
+  validate: (value) => value.startsWith('workspace:'),
+  exec: async (value) => {
+    const raw = await readFromWorkspace(value.replace('workspace:', ''))
+
+    if (raw === undefined) {
+      return { ok: false }
+    }
+
+    return { ok: true, data: JSON.parse(raw), raw }
+  },
+}
+
+await bundle(document, {
+  plugins: [workspaceFiles],
+  treeShake: false,
+})
+```
+
+`exec` returns `{ ok: true, data, raw }` on success and `{ ok: false }` on failure. A failed resolution is reported through the `onResolveError` hook and logged as a warning, it does not throw.
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `plugins` | `Plugin[]` | — | Loader and lifecycle plugins used during bundling. Required. |
+| `treeShake` | `boolean` | — | Only keep the parts of external documents that are actually referenced. Required. |
+| `depth` | `number` | unlimited | How deeply nested `$ref` pointers are followed. See the note below. |
+| `root` | `UnknownObject` | the input | Base document to write external documents into, used for partial bundling. |
+| `origin` | `string` | the input | Base path used to resolve relative references. |
+| `cache` | `Map<string, Promise<ResolveResult>>` | new map | Cache of in-flight resolutions, reused across `bundle` calls to avoid refetching. |
+| `visitedNodes` | `Set<unknown>` | new set | Nodes that have already been bundled, used to avoid re-bundling during partial bundles. |
+| `urlMap` | `boolean` | `false` | Keep the mapping of generated keys to their original URLs in the output. |
+| `externalDocumentsKey` | `string` | `'x-ext'` | Key that holds the bundled external documents. |
+| `externalDocumentsMappingsKey` | `string` | `'x-ext-urls'` | Key that holds the mapping between generated keys and original URLs. |
+| `compress` | `(value: string) => string \| Promise<string>` | hash | Function used to shorten URLs and file paths into document keys. |
+| `hooks` | `object` | — | Lifecycle hooks, see [Hooks](#hooks). |
 
-##### depth
+#### depth
 
-The `depth` option controls how deeply the bundler will resolve `$ref` references. When you set `depth` to a number, the bundler will only follow references up to that level of nesting. This is useful for creating partial bundles or limiting resource usage.
+The `depth` option controls how deeply the bundler resolves `$ref` references. When you set `depth` to a number, the bundler only follows references up to that level of nesting. This is useful for creating partial bundles or limiting resource usage.
 
-**Note:** When using `depth`, the resulting bundle may not be fully self-contained—some nested references deeper than the specified depth may remain unresolved. If you use `depth` together with the `visitedNodes` option, be aware that parent nodes may be marked as visited even if their child references have not been fully resolved yet. Use this option with care if you require a complete bundle.
+**Note:** When using `depth`, the resulting bundle may not be fully self-contained, since nested references deeper than the given depth stay unresolved. If you use `depth` together with `visitedNodes`, be aware that parent nodes may be marked as visited even if their child references have not been fully resolved yet. Use this option with care if you require a complete bundle.
 
 ```ts
-import { bundle } from '@scalar/openapi-parser'
-import { fetchUrls } from '@scalar/openapi-parser/plugins-browser'
+import { bundle } from '@scalar/json-magic/bundle'
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
 
 await bundle(input, {
   plugins: [fetchUrls()],
@@ -259,13 +351,13 @@ await bundle(input, {
 })
 ```
 
-##### externalDocumentsKey
+#### externalDocumentsKey
 
-The `externalDocumentsKey` option controls the key used to store external references. This key will contain all bundled external documents. The key is used to maintain a clean separation between the main OpenAPI document and its bundled external references. **Defaults** to `x-ext`.
+The `externalDocumentsKey` option controls the key used to store external references. This key contains all bundled external documents, which keeps a clean separation between the main document and its bundled references. **Defaults** to `x-ext`.
 
 ```ts
-import { bundle } from '@scalar/openapi-parser'
-import { fetchUrls } from '@scalar/openapi-parser/plugins-browser'
+import { bundle } from '@scalar/json-magic/bundle'
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
 
 await bundle(input, {
   plugins: [fetchUrls()],
@@ -274,65 +366,140 @@ await bundle(input, {
 })
 ```
 
-##### externalDocumentsMappingsKey
+#### externalDocumentsMappingsKey
 
-The `externalDocumentsMappingsKey` option controls the key used to maintain a mapping between hashed keys and their original URLs. This mapping is essential for tracking the source of bundled references. **Defaults** to `x-ext-urls`.
+The `externalDocumentsMappingsKey` option controls the key used to maintain a mapping between generated keys and their original URLs. This mapping is essential for tracking the source of bundled references. It is removed from the output of a full bundle unless `urlMap` is enabled. **Defaults** to `x-ext-urls`.
 
 ```ts
-import { bundle } from '@scalar/openapi-parser'
-import { fetchUrls } from '@scalar/openapi-parser/plugins-browser'
+import { bundle } from '@scalar/json-magic/bundle'
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
 
 await bundle(input, {
   plugins: [fetchUrls()],
   treeShake: false,
   urlMap: true,
-  externalDocumentsKey: 'x-external-urls',
+  externalDocumentsMappingsKey: 'x-external-urls',
+})
+```
+
+### Hooks
+
+Hooks let you observe and extend the bundling process, which is handy for progress reporting and error tracking.
+
+| Hook | Called when |
+| --- | --- |
+| `onResolveStart` | The bundler starts resolving a `$ref` |
+| `onResolveSuccess` | A `$ref` was resolved successfully |
+| `onResolveError` | A `$ref` could not be resolved |
+| `onBeforeNodeProcess` | Before a node is processed, may be async |
+| `onAfterNodeProcess` | After a node is processed, may be async |
+
+```ts
+import { bundle } from '@scalar/json-magic/bundle'
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
+
+const errors: string[] = []
+
+await bundle(document, {
+  plugins: [fetchUrls()],
+  treeShake: true,
+  hooks: {
+    onResolveStart: (node) => console.log('Resolving:', node.$ref),
+    onResolveSuccess: (node) => console.log('Resolved:', node.$ref),
+    onResolveError: (node) => errors.push(`Failed to resolve ${node.$ref}`),
+  },
+})
+```
+
+The same hooks can be shipped as a reusable lifecycle plugin, which is then passed alongside the loaders:
+
+```ts
+import { bundle, type LifecyclePlugin } from '@scalar/json-magic/bundle'
+import { fetchUrls } from '@scalar/json-magic/bundle/plugins/browser'
+
+const logProgress: LifecyclePlugin = {
+  type: 'lifecycle',
+  onResolveSuccess: (node) => console.log('Resolved:', node.$ref),
+}
+
+await bundle(document, {
+  plugins: [fetchUrls(), logProgress],
+  treeShake: false,
 })
 ```
 
 ## dereference
 
-Dereference all `$ref` pointers in a JSON object, resolving both internal and external references.
+`dereference` resolves the `$ref` pointers of a document and returns the result wrapped in a [magic proxy](#magic-proxy), so referenced values are read through the `$ref-value` property.
 
-The `dereference` function can operate in two modes:
+It works in two modes:
 
-- **Synchronous (`sync: true`)**: Only internal references (within the same object) are resolved. The result is wrapped in a magic proxy for reactive access. No network requests are made.
-- **Asynchronous (`sync: false` or omitted)**: Both internal and external references (e.g., URLs) are resolved. The function returns a Promise that resolves to the fully dereferenced object, also wrapped in a magic proxy.
+- **Synchronous (`sync: true`)**: only internal references are resolved, no network requests are made, and the result is returned directly.
+- **Asynchronous (`sync: false`, the default)**: external references are bundled into the document first, so both internal and external references resolve. A Promise is returned.
 
 ### Options
 
-- `sync` (`boolean`):  
-  - If `true`, resolves only internal references synchronously.
-  - If `false` (default), resolves both internal and external references asynchronously and returns a Promise.
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sync` | `boolean` | `false` | Resolve internal references only, without returning a Promise. |
+| `plugins` | `Plugin[]` | `[fetchUrls()]` | Loaders used to resolve external references in async mode. |
 
-The result is an object with a `success` property. If dereferencing fails (e.g., due to unresolved external references), the result will include an `errors` array describing the issues encountered.
+The result is an object with a `success` property. On success it carries the dereferenced `data`, and on failure it carries an `errors` array describing the references that could not be resolved.
 
 ```ts
 import { dereference } from '@scalar/json-magic/dereference'
 
 const result = dereference({ a: 'hello', b: { $ref: '#/a' } }, { sync: true })
 
-// Resolve internal references synchronously
-console.log(result)
+if (result.success) {
+  // 'hello'
+  console.log(result.data.b['$ref-value'])
+}
 ```
 
-To resolve also external references you need to set `sync: false`
+To resolve external references as well, drop `sync` (or set it to `false`) and await the result.
 
 ```ts
 import { dereference } from '@scalar/json-magic/dereference'
 
-const result = await dereference({ a: 'hello', b: { $ref: 'http://example.com/document.json#/somepath' } }, { sync: false })
+const result = await dereference({
+  a: 'hello',
+  b: { $ref: 'http://example.com/document.json#/somepath' },
+})
 
-// Result with all internal and external references resolved
-console.log(result)
+if (result.success) {
+  console.log(result.data)
+} else {
+  console.error(result.errors)
+}
+```
+
+To resolve references from somewhere other than HTTP, pass your own loaders:
+
+```ts
+import { dereference } from '@scalar/json-magic/dereference'
+import { fetchUrls, readFiles } from '@scalar/json-magic/bundle/plugins/node'
+
+const result = await dereference(document, {
+  plugins: [readFiles(), fetchUrls()],
+})
 ```
 
 ## diff
 
-This package provides a way to compare two json objects and get the differences, resolve conflicts and return conflicts that need to be resolved manually.
+Compare two JSON objects, merge changes made in parallel, and surface the conflicts that need to be resolved manually.
 
-### Quickstart
+| Function | Description |
+| --- | --- |
+| `diff(base, updated)` | Returns the list of `add`, `update` and `delete` changes that turn `base` into `updated` |
+| `merge(diffA, diffB)` | Combines two changesets made against the same base into `{ diffs, conflicts }` |
+| `apply(base, diffs)` | Applies a changeset to a document and returns it |
 
+These three functions work on the documents themselves, not on copies of them. `apply` mutates the document it is given, `merge` merges one changeset into the entries of the other, and the changes a diff carries are live references into the documents that were compared. That means an applied document keeps sharing subtrees with the document it was diffed against, and a merge writes into the document behind its second changeset. Deep clone the documents before diffing them whenever you need the originals to stay untouched — cloning only the document you apply to is not enough.
+
+`apply` throws an `InvalidChangesDetectedError` when a change points at a path that does not exist, when a change targets the document itself (an empty path, which a diff produces whenever the two documents differ at the root), and when a path reaches the prototype chain through `__proto__`, `constructor` or `prototype`.
+
+### Quickstart
 
 ```ts
 import { apply, diff, merge } from '@scalar/json-magic/diff'
@@ -366,19 +533,30 @@ const objectV2 = {
 }
 
 // Merge the changes of both versions with the same parent object
-const { diffs, conflicts } = merge(
-  diff(baseObject, objectV1),
-  diff(baseObject, objectV2),
-)
+const { diffs, conflicts } = merge(diff(baseObject, objectV1), diff(baseObject, objectV2))
 
 // Apply changes from v1 and v2 to the parent object to get the final object
 const finalDocument = apply(baseObject, diffs)
 ```
 
+### Conflicts
+
+`merge` only returns the changes it can combine safely. When both sides touch the same path, the pair is returned in `conflicts` for you to resolve, and it is left out of `diffs`.
+
+```ts
+import { diff, merge } from '@scalar/json-magic/diff'
+
+const { diffs, conflicts } = merge(diff(base, mine), diff(base, theirs))
+
+for (const [mineChanges, theirChanges] of conflicts) {
+  // Decide which side wins, then push the winner onto diffs
+  diffs.push(...mineChanges)
+}
+```
 
 ## magic-proxy
 
-A javascript proxy which resolves internal references when accessing a property
+A JavaScript proxy that resolves internal references as you access properties. Nothing is copied or rewritten: the underlying document keeps its `$ref` pointers, and referenced values are read on demand through the virtual `$ref-value` property. Resolved values are cached, and proxies are stable for the same target object, which makes it safe to use with reactive frameworks like Vue.
 
 ### Quick start
 
@@ -388,30 +566,71 @@ import { createMagicProxy, getRaw } from '@scalar/json-magic/magic-proxy'
 const result = createMagicProxy({
   a: 'hello',
   b: {
-    $ref: '#/a'
-  }
+    $ref: '#/a',
+  },
 })
 
-/**
- * Output:
- * {
- *  a: 'hello',
- *  b: {
- *    $ref: '#/a',
- *    '$ref-value': 'hello'
- *  }
- * }
- */
-console.log(result)
+// 'hello', resolved on access
+console.log(result.b['$ref-value'])
+
+// '#/a', the original pointer is still there
+console.log(result.b.$ref)
 
-const rawObject = getRaw(result)
 /**
+ * getRaw returns the untouched object:
  * {
- *  a: 'hello',
- *  b: {
- *    $ref: '#/a'
- *  }
+ *   a: 'hello',
+ *   b: {
+ *     $ref: '#/a'
+ *   }
  * }
  */
+const rawObject = getRaw(result)
 console.log(rawObject)
-```
+```
+
+Deeply nested values are proxied too, so `$ref-value` works at any depth. Writes pass through to the underlying object, and writing to `$ref-value` updates the value the reference points at.
+
+Properties prefixed with `__scalar_` are treated as internal: they read as `undefined`, they are left out of `Object.keys`, and `in` checks return `false`. Pass `{ showInternal: true }` to expose them.
+
+```ts
+const proxy = createMagicProxy({ __scalar_meta: 'hidden' }, { showInternal: true })
+
+// 'hidden'
+console.log(proxy.__scalar_meta)
+```
+
+## Helpers
+
+Standalone helpers, each with its own entry point.
+
+| Helper | Description |
+| --- | --- |
+| `@scalar/json-magic/helpers/escape-json-pointer` | Escape `~` and `/` in a JSON pointer segment |
+| `@scalar/json-magic/helpers/unescape-json-pointer` | Reverse of `escapeJsonPointer` |
+| `@scalar/json-magic/helpers/get-segments-from-path` | Split a JSON pointer into unescaped segments |
+| `@scalar/json-magic/helpers/get-value-by-path` | Read the value at a list of path segments |
+| `@scalar/json-magic/helpers/set-value-at-path` | Write a value at a JSON pointer, creating missing nodes |
+| `@scalar/json-magic/helpers/is-file-path` | Check whether a string looks like a file path |
+| `@scalar/json-magic/helpers/is-http-url` | Check whether a string is an HTTP or HTTPS URL |
+| `@scalar/json-magic/helpers/is-json-object` | Check whether a string is a JSON object |
+| `@scalar/json-magic/helpers/is-yaml` | Check whether a string is valid YAML |
+| `@scalar/json-magic/helpers/normalize` | Parse a JSON or YAML string into an object |
+
+```ts
+import { getValueByPath } from '@scalar/json-magic/helpers/get-value-by-path'
+
+const { value } = getValueByPath({ components: { schemas: { User: { type: 'object' } } } }, [
+  'components',
+  'schemas',
+  'User',
+])
+```
+
+## Community
+
+We are API nerds. You too? Let's chat on Discord: <https://discord.gg/scalar>
+
+## License
+
+The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).

package/dist/bundle/index.d.ts

@@ -1,3 +1,3 @@
 export type { LifecyclePlugin, LoaderPlugin, Plugin, ResolveResult } from './bundle.js';
-export { bundle, isLocalRef, prefixInternalRef, prefixInternalRefRecursive, 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,UAAU,EAAE,iBAAiB,EAAE,0BAA0B,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, isLocalRef, prefixInternalRef, prefixInternalRefRecursive, 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,oBAiD7F,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
@@ -59,8 +70,24 @@ export const diff = (doc1, doc2) => {
                 diff.push({ path: prefix, changes: el2, type: 'update' });
                 return;
             }
-            const keys = new Set([...Object.keys(el1), ...Object.keys(el2)]);
-            for (const key of keys) {
+            // 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.13.0",
+  "version": "0.13.3",
   "engines": {
     "node": ">=22"
   },
@@ -109,10 +109,10 @@
   "dependencies": {
     "pathe": "^2.0.3",
     "yaml": "^2.9.0",
-    "@scalar/helpers": "0.10.0"
+    "@scalar/helpers": "0.11.2"
   },
   "devDependencies": {
-    "fastify": "^5.8.1",
+    "fastify": "^5.11.2",
     "vite": "8.1.5"
   },
   "scripts": {