@korajs/merge 0.6.0 → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr. Obed Ehoneah
+
+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/dist/index.cjs

@@ -42,6 +42,7 @@ __export(index_exports, {
   maxMerge: () => maxMerge,
   mergeAtomicOps: () => mergeAtomicOps,
   mergeField: () => mergeField,
+  mergeObject: () => mergeObject,
   mergeRichtext: () => mergeRichtext,
   minMerge: () => minMerge,
   resolveConstraintViolation: () => resolveConstraintViolation,
@@ -109,21 +110,128 @@ function addWinsSet(localArray, remoteArray, baseArray) {
   for (const item of baseArray) {
     addIfNew(serialize(item), item);
   }
+  const additions = /* @__PURE__ */ new Map();
   for (const item of localArray) {
     const s = serialize(item);
-    if (addedLocal.has(s)) {
-      addIfNew(s, item);
+    if (addedLocal.has(s) && !additions.has(s)) {
+      additions.set(s, item);
     }
   }
   for (const item of remoteArray) {
     const s = serialize(item);
-    if (addedRemote.has(s)) {
-      addIfNew(s, item);
+    if (addedRemote.has(s) && !additions.has(s)) {
+      additions.set(s, item);
     }
   }
+  for (const s of [...additions.keys()].sort()) {
+    addIfNew(s, additions.get(s));
+  }
   return result;
 }
 
+// src/strategies/object-merge.ts
+function mergeObject(localValue, remoteValue, baseValue, localTs, remoteTs) {
+  const local = asPlainObject(localValue);
+  const remote = asPlainObject(remoteValue);
+  const base = asPlainObject(baseValue);
+  if (local === null || remote === null) {
+    const winner = lastWriteWins(localValue, remoteValue, localTs, remoteTs).value;
+    return asPlainObject(winner) ?? {};
+  }
+  const baseObj = base ?? {};
+  const result = {};
+  const keys = /* @__PURE__ */ new Set([
+    ...Object.keys(local),
+    ...Object.keys(remote),
+    ...Object.keys(baseObj)
+  ]);
+  for (const key of keys) {
+    const inLocal = key in local;
+    const inRemote = key in remote;
+    const inBase = key in baseObj;
+    const localVal = local[key];
+    const remoteVal = remote[key];
+    const baseVal = baseObj[key];
+    const localWrote = inLocal && (!inBase || !valuesEqual(localVal, baseVal));
+    const remoteWrote = inRemote && (!inBase || !valuesEqual(remoteVal, baseVal));
+    const localRemoved = !inLocal && inBase;
+    const remoteRemoved = !inRemote && inBase;
+    if (localWrote && remoteWrote) {
+      result[key] = mergeWrittenValues(localVal, remoteVal, baseVal, localTs, remoteTs);
+      continue;
+    }
+    if (localWrote && !remoteRemoved) {
+      result[key] = localVal;
+      continue;
+    }
+    if (remoteWrote && !localRemoved) {
+      result[key] = remoteVal;
+      continue;
+    }
+    if (localWrote && remoteRemoved) {
+      result[key] = localVal;
+      continue;
+    }
+    if (remoteWrote && localRemoved) {
+      result[key] = remoteVal;
+      continue;
+    }
+    if (localRemoved || remoteRemoved) {
+      continue;
+    }
+    if (inBase) {
+      result[key] = baseVal;
+    }
+  }
+  return result;
+}
+function mergeWrittenValues(localVal, remoteVal, baseVal, localTs, remoteTs) {
+  if (asPlainObject(localVal) !== null && asPlainObject(remoteVal) !== null) {
+    return mergeObject(localVal, remoteVal, baseVal, localTs, remoteTs);
+  }
+  if (Array.isArray(localVal) && Array.isArray(remoteVal)) {
+    const baseArr = Array.isArray(baseVal) ? baseVal : [];
+    return addWinsSet(localVal, remoteVal, baseArr);
+  }
+  return lastWriteWins(localVal, remoteVal, localTs, remoteTs).value;
+}
+function asPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== null && proto !== Object.prototype) {
+    return null;
+  }
+  return value;
+}
+function valuesEqual(a, b) {
+  if (a === b) {
+    return true;
+  }
+  return stableStringify(a) === stableStringify(b);
+}
+function stableStringify(value) {
+  return JSON.stringify(sortKeysDeep(value));
+}
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortKeysDeep);
+  }
+  if (typeof value === "object" && value !== null) {
+    const proto = Object.getPrototypeOf(value);
+    if (proto === null || proto === Object.prototype) {
+      const record = value;
+      const sorted = {};
+      for (const key of Object.keys(record).sort()) {
+        sorted[key] = sortKeysDeep(record[key]);
+      }
+      return sorted;
+    }
+  }
+  return value;
+}
+
 // src/strategies/atomic-merge.ts
 function mergeAtomicOps(localAtomicOp, remoteAtomicOp, baseValue) {
   if (localAtomicOp.type !== remoteAtomicOp.type) {
@@ -187,6 +295,7 @@ function mergeAtomicOps(localAtomicOp, remoteAtomicOp, baseValue) {
 }
 
 // src/strategies/yjs-richtext.ts
+var import_core2 = require("@korajs/core");
 var Y = __toESM(require("yjs"), 1);
 var TEXT_KEY = "content";
 function mergeRichtext(localValue, remoteValue, baseValue) {
@@ -219,11 +328,17 @@ function toYjsUpdate(value) {
   if (value instanceof ArrayBuffer) {
     return new Uint8Array(value);
   }
-  throw new Error("Richtext value must be a string, Uint8Array, ArrayBuffer, null, or undefined.");
+  if ((0, import_core2.isKoraBytesValue)(value) || (0, import_core2.isLegacyNumericByteObject)(value)) {
+    const decoded = (0, import_core2.decodeBytesFromOpData)(value);
+    return decoded instanceof Uint8Array ? decoded : stringToRichtextUpdate(decoded);
+  }
+  throw new Error(
+    "Richtext value must be a string, Uint8Array, ArrayBuffer, tagged { $koraBytes } object, null, or undefined."
+  );
 }
 
 // src/strategies/schema-strategies.ts
-var import_core2 = require("@korajs/core");
+var import_core3 = require("@korajs/core");
 function counterMerge(localValue, remoteValue, baseValue) {
   const base = typeof baseValue === "number" ? baseValue : 0;
   const local = typeof localValue === "number" ? localValue : base;
@@ -306,6 +421,38 @@ function applySchemaStrategy(strategy, localValue, remoteValue, baseValue, local
 
 // src/engine/field-merger.ts
 function mergeField(fieldName, localOp, remoteOp, baseState, fieldDescriptor, resolver) {
+  const result = mergeFieldInner(fieldName, localOp, remoteOp, baseState, fieldDescriptor, resolver);
+  if (fieldDescriptor.kind === "secret") {
+    return {
+      value: result.value,
+      trace: {
+        ...result.trace,
+        operationA: redactOperationField(result.trace.operationA, fieldName),
+        operationB: redactOperationField(result.trace.operationB, fieldName),
+        inputA: SECRET_REDACTED,
+        inputB: SECRET_REDACTED,
+        base: result.trace.base == null ? result.trace.base : SECRET_REDACTED,
+        output: SECRET_REDACTED
+      }
+    };
+  }
+  return result;
+}
+var SECRET_REDACTED = "[secret]";
+function redactOperationField(operation, field) {
+  const redactRecord = (record) => {
+    if (record === null || !(field in record)) {
+      return record;
+    }
+    return { ...record, [field]: SECRET_REDACTED };
+  };
+  return {
+    ...operation,
+    data: redactRecord(operation.data),
+    previousData: redactRecord(operation.previousData)
+  };
+}
+function mergeFieldInner(fieldName, localOp, remoteOp, baseState, fieldDescriptor, resolver) {
   const startTime = Date.now();
   const localData = localOp.data ?? {};
   const remoteData = remoteOp.data ?? {};
@@ -437,7 +584,14 @@ function autoMerge(fieldName, localOp, remoteOp, localValue, remoteValue, baseVa
     case "number":
     case "boolean":
     case "enum":
-    case "timestamp": {
+    case "timestamp":
+    // A blob field's value is a small content-addressed reference; concurrent
+    // replacements of the whole reference resolve by last-write-wins (the bytes
+    // themselves are immutable and deduplicated by hash in the blob store).
+    case "blob":
+    // A secret field's stored value (ciphertext or hash) resolves by
+    // last-write-wins; the merge never sees or emits plaintext (redacted below).
+    case "secret": {
       const lwwResult = lastWriteWins(
         localValue,
         remoteValue,
@@ -494,6 +648,28 @@ function autoMerge(fieldName, localOp, remoteOp, localValue, remoteValue, baseVa
         startTime
       );
     }
+    case "object":
+    case "json": {
+      const merged = mergeObject(
+        localValue,
+        remoteValue,
+        baseValue,
+        localOp.timestamp,
+        remoteOp.timestamp
+      );
+      return createResult(
+        merged,
+        fieldName,
+        localOp,
+        remoteOp,
+        localValue,
+        remoteValue,
+        baseValue,
+        "object-lww-map",
+        1,
+        startTime
+      );
+    }
   }
 }
 function createResult(value, field, operationA, operationB, inputA, inputB, base, strategy, tier, startTime) {
@@ -614,13 +790,13 @@ function matchesWhere(record, where) {
 }
 
 // src/constraints/resolvers.ts
-var import_core3 = require("@korajs/core");
+var import_core4 = require("@korajs/core");
 function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp, baseState) {
   const startTime = Date.now();
   const { constraint } = violation;
   switch (constraint.onConflict) {
     case "last-write-wins": {
-      const comparison = import_core3.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+      const comparison = import_core4.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
       const winner = comparison >= 0 ? localOp : remoteOp;
       const resolvedRecord = applyWinnerFields(mergedRecord, winner, violation.fields);
       return createResolution(
@@ -634,7 +810,7 @@ function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp,
       );
     }
     case "first-write-wins": {
-      const comparison = import_core3.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+      const comparison = import_core4.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
       const winner = comparison <= 0 ? localOp : remoteOp;
       const resolvedRecord = applyWinnerFields(mergedRecord, winner, violation.fields);
       return createResolution(
@@ -650,7 +826,7 @@ function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp,
     case "priority-field": {
       const priorityField = constraint.priorityField;
       if (priorityField === void 0) {
-        const comparison = import_core3.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+        const comparison = import_core4.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
         const winner2 = comparison >= 0 ? localOp : remoteOp;
         const resolvedRecord2 = applyWinnerFields(mergedRecord, winner2, violation.fields);
         return createResolution(
@@ -694,7 +870,7 @@ function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp,
     }
     case "custom": {
       if (constraint.resolve === void 0) {
-        const comparison = import_core3.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+        const comparison = import_core4.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
         const winner = comparison >= 0 ? localOp : remoteOp;
         const resolvedRecord2 = applyWinnerFields(mergedRecord, winner, violation.fields);
         return createResolution(
@@ -786,7 +962,7 @@ function extractFields(record, fields) {
 }
 
 // src/constraints/referential-integrity.ts
-var import_core4 = require("@korajs/core");
+var import_core5 = require("@korajs/core");
 function buildMergeRelationLookup(schema) {
   const lookup = /* @__PURE__ */ new Map();
   const relationNames = Object.keys(schema.relations).sort();
@@ -1057,17 +1233,17 @@ function createDeleteVsInsertTrace(deleteOp, insertOp, relation, strategy, actio
 }
 
 // src/engine/merge-engine.ts
-var import_core6 = require("@korajs/core");
+var import_core7 = require("@korajs/core");
 
 // src/constraints/state-machine-constraint.ts
-var import_core5 = require("@korajs/core");
+var import_core6 = require("@korajs/core");
 function isValid(sm, from, to) {
   const constraint = {
     field: sm.field,
     collection: "",
     transitions: sm.transitions
   };
-  return (0, import_core5.validateTransition)(constraint, from, to).valid;
+  return (0, import_core6.validateTransition)(constraint, from, to).valid;
 }
 function resolveStateMachineMerge(fieldName, localOp, remoteOp, baseState, stateMachine) {
   const startTime = Date.now();
@@ -1128,7 +1304,7 @@ function resolveStateMachineMerge(fieldName, localOp, remoteOp, baseState, state
   const localValid = isValid(stateMachine, baseStateStr, localStr);
   const remoteValid = isValid(stateMachine, baseStateStr, remoteStr);
   if (localValid && remoteValid) {
-    const comparison = import_core5.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+    const comparison = import_core6.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
     const winner = comparison >= 0 ? localStr : remoteStr;
     return makeResult(
       winner,
@@ -1280,7 +1456,7 @@ var MergeEngine = class {
    */
   mergeFields(input) {
     const { local, remote, baseState, collectionDef } = input;
-    const allFields = collectAffectedFields(local, remote, baseState, collectionDef);
+    const allFields = collectAffectedFields(local, remote);
     const mergedData = {};
     const traces = [];
     for (const fieldName of allFields) {
@@ -1322,7 +1498,7 @@ var MergeEngine = class {
    */
   mergeWithDelete(input) {
     const { local, remote } = input;
-    const comparison = import_core6.HybridLogicalClock.compare(local.timestamp, remote.timestamp);
+    const comparison = import_core7.HybridLogicalClock.compare(local.timestamp, remote.timestamp);
     if (comparison >= 0) {
       if (local.type === "delete") {
         return { mergedData: {}, traces: [], appliedOperation: "local", sideEffects: [] };
@@ -1345,11 +1521,8 @@ var MergeEngine = class {
     };
   }
 };
-function collectAffectedFields(local, remote, baseState, collectionDef) {
+function collectAffectedFields(local, remote) {
   const fields = /* @__PURE__ */ new Set();
-  for (const fieldName of Object.keys(collectionDef.fields)) {
-    fields.add(fieldName);
-  }
   if (local.data !== null) {
     for (const fieldName of Object.keys(local.data)) {
       fields.add(fieldName);
@@ -1360,9 +1533,6 @@ function collectAffectedFields(local, remote, baseState, collectionDef) {
       fields.add(fieldName);
     }
   }
-  for (const fieldName of Object.keys(baseState)) {
-    fields.add(fieldName);
-  }
   return fields;
 }
 function determineAppliedOperation(traces) {
@@ -1404,6 +1574,7 @@ function determineAppliedOperation(traces) {
   maxMerge,
   mergeAtomicOps,
   mergeField,
+  mergeObject,
   mergeRichtext,
   minMerge,
   resolveConstraintViolation,