@jsondelta/merge 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jsondelta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+<p align="center">
+  <img src="logo.svg" width="128" height="128" alt="@jsondelta/merge">
+</p>
+
+<h1 align="center">@jsondelta/merge</h1>
+
+<p align="center">
+  Zig-powered three-way JSON merge with conflict detection. Merge concurrent edits, detect collisions, keep the base value for conflicts.
+</p>
+
+<p align="center">
+  <a href="https://github.com/jsondelta/merge/actions/workflows/test.yml"><img src="https://github.com/jsondelta/merge/actions/workflows/test.yml/badge.svg" alt="test"></a>
+  <a href="https://www.npmjs.com/package/@jsondelta/merge"><img src="https://img.shields.io/npm/v/@jsondelta/merge" alt="npm"></a>
+</p>
+
+## Install
+
+```
+npm install @jsondelta/merge
+```
+
+## Usage
+
+```js
+import { merge } from '@jsondelta/merge'
+
+const base = { title: 'Draft', body: 'Hello', status: 'open' }
+const left = { title: 'Draft', body: 'Hello world', status: 'open' }
+const right = { title: 'Final', body: 'Hello', status: 'review' }
+
+const { doc, conflicts } = merge(base, left, right)
+// doc: { title: 'Final', body: 'Hello world', status: 'review' }
+// conflicts: []
+```
+
+The default import selects the fastest available backend: WebAssembly or pure JS fallback. You can also import a specific backend directly:
+
+```js
+import { merge } from '@jsondelta/merge/fallback'
+import { merge } from '@jsondelta/merge/wasm'
+```
+
+## Real-world examples
+
+### Merging concurrent edits in a collaborative editor
+
+```js
+import { merge } from '@jsondelta/merge'
+
+const base = {
+  title: 'Q1 Report',
+  sections: [
+    { heading: 'Revenue', body: 'Revenue grew 12% YoY.' },
+    { heading: 'Costs', body: 'Operating costs remained flat.' }
+  ],
+  metadata: { author: 'alice', version: 1 }
+}
+
+// alice updates the revenue figure and bumps the version
+const alice = {
+  title: 'Q1 Report',
+  sections: [
+    { heading: 'Revenue', body: 'Revenue grew 15% YoY, beating estimates.' },
+    { heading: 'Costs', body: 'Operating costs remained flat.' }
+  ],
+  metadata: { author: 'alice', version: 2 }
+}
+
+// bob updates the title and costs section
+const bob = {
+  title: 'Q1 Financial Report',
+  sections: [
+    { heading: 'Revenue', body: 'Revenue grew 12% YoY.' },
+    { heading: 'Costs', body: 'Operating costs decreased 3%.' }
+  ],
+  metadata: { author: 'alice', version: 1 }
+}
+
+const { doc, conflicts } = merge(base, alice, bob)
+// doc.title === 'Q1 Financial Report'
+// doc.sections[0].body === 'Revenue grew 15% YoY, beating estimates.'
+// doc.sections[1].body === 'Operating costs decreased 3%.'
+// doc.metadata.version === 2
+// conflicts === []
+```
+
+### Merging configuration with conflict detection
+
+```js
+import { merge } from '@jsondelta/merge'
+
+const base = { database: { host: 'localhost', port: 5432 }, logging: { level: 'info' } }
+const staging = { database: { host: 'staging.db', port: 5432 }, logging: { level: 'debug' } }
+const production = { database: { host: 'prod.db', port: 5432 }, logging: { level: 'warn' } }
+
+const { doc, conflicts } = merge(base, staging, production)
+// doc.database.host stays 'localhost' (conflict - both changed it differently)
+// doc.logging.level stays 'info' (conflict)
+// conflicts.length === 2
+```
+
+## API
+
+### `merge(base, left, right)`
+
+Three-way merge of JSON-compatible values.
+
+- `base` - the common ancestor
+- `left` - the left (or "ours") revision
+- `right` - the right (or "theirs") revision
+- Returns `{ doc, conflicts }`
+
+**`doc`** contains all non-conflicting changes applied to the base. Conflicting paths retain the base value - neither side wins automatically.
+
+**`conflicts`** is an array of conflict objects, each with `left` and `right` properties containing the conflicting operations from each side. Operations follow the `@jsondelta/diff` delta format:
+
+```js
+{
+  left: { op: 'replace', path: ['level'], old: 'info', new: 'debug' },
+  right: { op: 'replace', path: ['level'], old: 'info', new: 'warn' }
+}
+```
+
+When both sides make the same change to the same path, it is not a conflict - the change is applied once.
+
+## Conflict detection
+
+Two operations conflict when their paths overlap (one is a prefix of the other, or they are equal) and the operations differ.
+
+| Left | Right | Result |
+|------|-------|--------|
+| Changes `a.b` | Changes `a.c` | Both applied (no overlap) |
+| Changes `a.b` to X | Changes `a.b` to X | Applied once (identical) |
+| Changes `a.b` to X | Changes `a.b` to Y | Conflict |
+| Replaces `a` entirely | Changes `a.b` | Conflict (ancestor/descendant) |
+| Removes `a.b` | Changes `a.b` | Conflict |
+
+## How it works
+
+The merge engine is written in Zig and compiled to WebAssembly. It diffs the base against both revisions, partitions the resulting operations into clean (non-overlapping) and conflicting sets, and applies the clean operations to produce the merged document.
+
+The pure JS fallback uses `@jsondelta/diff` and `@jsondelta/patch` under the hood.
+
+**Architecture:**
+1. **WebAssembly** - Self-contained Zig engine with embedded diff and patch logic. Near-native speed, no JS dependencies at runtime
+2. **Pure JS fallback** - Uses `@jsondelta/diff` and `@jsondelta/patch`. Always works
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@jsondelta/merge",
+  "version": "1.0.0",
+  "description": "Zig-powered three-way JSON merge with conflict detection",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./fallback": {
+      "types": "./types/fallback.d.ts",
+      "default": "./src/fallback.js"
+    },
+    "./wasm": {
+      "types": "./types/wasm.d.ts",
+      "default": "./src/wasm.js"
+    }
+  },
+  "files": [
+    "src",
+    "wasm",
+    "types"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npx tsc --declaration --allowJs --emitDeclarationOnly --skipLibCheck --target es2020 --module nodenext --moduleResolution nodenext --strict false --esModuleInterop true --outDir ./types src/index.js src/fallback.js src/wasm.js"
+  },
+  "keywords": [
+    "json",
+    "merge",
+    "three-way",
+    "conflict",
+    "zig",
+    "wasm",
+    "performance"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsondelta/merge.git"
+  },
+  "dependencies": {
+    "@jsondelta/diff": "^1.0.0",
+    "@jsondelta/patch": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/fallback.js

@@ -0,0 +1,113 @@
+import { diff } from '@jsondelta/diff/fallback'
+import { patch } from '@jsondelta/patch/fallback'
+
+/**
+ * Three-way merge of JSON-compatible values.
+ * @param {*} base - Common ancestor
+ * @param {*} left - Left revision
+ * @param {*} right - Right revision
+ * @returns {{ doc: *, conflicts: Array<{ left: Object, right: Object }> }}
+ */
+function merge(base, left, right) {
+  const leftDelta = diff(base, left)
+  const rightDelta = diff(base, right)
+
+  if (leftDelta.length === 0 && rightDelta.length === 0) {
+    return { doc: structuredClone(base), conflicts: [] }
+  }
+  if (leftDelta.length === 0) {
+    return { doc: structuredClone(right), conflicts: [] }
+  }
+  if (rightDelta.length === 0) {
+    return { doc: structuredClone(left), conflicts: [] }
+  }
+
+  const conflicts = []
+  const cleanLeft = []
+  const rightConsumed = new Set()
+
+  for (const lOp of leftDelta) {
+    let hasConflict = false
+
+    for (let ri = 0; ri < rightDelta.length; ri++) {
+      const rOp = rightDelta[ri]
+      if (!pathsOverlap(lOp.path, rOp.path)) continue
+
+      rightConsumed.add(ri)
+
+      if (opsEqual(lOp, rOp)) {
+        if (!hasConflict) cleanLeft.push(lOp)
+        hasConflict = 'equal'
+      } else {
+        hasConflict = true
+        conflicts.push({ left: lOp, right: rOp })
+      }
+    }
+
+    if (!hasConflict) {
+      cleanLeft.push(lOp)
+    }
+  }
+
+  const cleanRight = []
+  for (let ri = 0; ri < rightDelta.length; ri++) {
+    if (!rightConsumed.has(ri)) cleanRight.push(rightDelta[ri])
+  }
+
+  const cleanOps = [...cleanLeft, ...cleanRight]
+  const doc = cleanOps.length > 0 ? patch(base, cleanOps) : structuredClone(base)
+
+  return { doc, conflicts }
+}
+
+function pathsOverlap(a, b) {
+  const min = Math.min(a.length, b.length)
+  for (let i = 0; i < min; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
+function opsEqual(a, b) {
+  if (a.op !== b.op) return false
+  if (!pathsEqual(a.path, b.path)) return false
+  if (a.op === 'replace') return deepEqual(a.old, b.old) && deepEqual(a.new, b.new)
+  return deepEqual(a.value, b.value)
+}
+
+function pathsEqual(a, b) {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true
+  if (a === null || b === null) return a === b
+  if (typeof a !== typeof b) return false
+  if (typeof a !== 'object') return false
+
+  const aArr = Array.isArray(a)
+  const bArr = Array.isArray(b)
+  if (aArr !== bArr) return false
+
+  if (aArr) {
+    if (a.length !== b.length) return false
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false
+    }
+    return true
+  }
+
+  const aKeys = Object.keys(a)
+  const bKeys = Object.keys(b)
+  if (aKeys.length !== bKeys.length) return false
+  for (const key of aKeys) {
+    if (!(key in b) || !deepEqual(a[key], b[key])) return false
+  }
+  return true
+}
+
+export { merge }

package/src/index.js

@@ -0,0 +1,14 @@
+import { merge as fallbackMerge } from './fallback.js'
+
+let merge = fallbackMerge
+let backend = 'fallback'
+
+try {
+  const wasm = await import('./wasm.js')
+  merge = wasm.merge
+  backend = 'wasm'
+} catch {
+  // using fallback
+}
+
+export { merge, backend }

package/src/wasm.js

@@ -0,0 +1,50 @@
+import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const wasmPath = join(__dirname, '..', 'wasm', 'merge.wasm')
+const wasmBuffer = readFileSync(wasmPath)
+const wasmModule = new WebAssembly.Module(wasmBuffer)
+const wasmInstance = new WebAssembly.Instance(wasmModule)
+const wasm = wasmInstance.exports
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+function callWasm(fn, ...jsonArgs) {
+  const buffers = jsonArgs.map(arg => encoder.encode(JSON.stringify(arg)))
+  const ptrs = buffers.map(buf => {
+    const ptr = wasm.alloc(buf.length)
+    if (!ptr) throw new Error('wasm allocation failed')
+    new Uint8Array(wasm.memory.buffer).set(buf, ptr)
+    return { ptr, len: buf.length }
+  })
+
+  const args = ptrs.flatMap(p => [p.ptr, p.len])
+  const resultLen = fn(...args)
+
+  for (const p of ptrs) wasm.dealloc(p.ptr, p.len)
+
+  if (resultLen < 0) throw new Error('wasm merge failed')
+
+  const resultPtr = wasm.getResultPtr()
+  const resultBytes = new Uint8Array(wasm.memory.buffer.slice(resultPtr, resultPtr + resultLen))
+  const result = JSON.parse(decoder.decode(resultBytes))
+
+  wasm.freeResult()
+  return result
+}
+
+/**
+ * Three-way merge of JSON-compatible values using the Zig WASM engine.
+ * @param {*} base - Common ancestor
+ * @param {*} left - Left revision
+ * @param {*} right - Right revision
+ * @returns {{ doc: *, conflicts: Array<{ left: Object, right: Object }> }}
+ */
+function merge(base, left, right) {
+  return callWasm(wasm.merge, base, left, right)
+}
+
+export { merge }

package/types/fallback.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Three-way merge of JSON-compatible values.
+ * @param {*} base - Common ancestor
+ * @param {*} left - Left revision
+ * @param {*} right - Right revision
+ * @returns {{ doc: *, conflicts: Array<{ left: Object, right: Object }> }}
+ */
+export function merge(base: any, left: any, right: any): {
+    doc: any;
+    conflicts: Array<{
+        left: any;
+        right: any;
+    }>;
+};

package/types/index.d.ts

@@ -0,0 +1,3 @@
+export let merge: typeof fallbackMerge;
+export let backend: string;
+import { merge as fallbackMerge } from './fallback.js';

package/types/wasm.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Three-way merge of JSON-compatible values using the Zig WASM engine.
+ * @param {*} base - Common ancestor
+ * @param {*} left - Left revision
+ * @param {*} right - Right revision
+ * @returns {{ doc: *, conflicts: Array<{ left: Object, right: Object }> }}
+ */
+export function merge(base: any, left: any, right: any): {
+    doc: any;
+    conflicts: Array<{
+        left: any;
+        right: any;
+    }>;
+};