@korajs/merge 0.6.0 → 1.0.0-beta.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { OnDeleteAction, MergeTrace, SchemaDefinition, Operation, Constraint, CollectionDefinition, HLCTimestamp, AtomicOp, FieldMergeStrategy, FieldDescriptor, CustomResolver } from '@korajs/core';
+import { OnDeleteAction, MergeTrace, SchemaDefinition, Operation, Constraint, CollectionDefinition, HLCTimestamp, AtomicOp, KoraBytesValue, FieldMergeStrategy, FieldDescriptor, CustomResolver } from '@korajs/core';
 
 /**
  * Describes an incoming relation to a target collection.
@@ -233,6 +233,42 @@ declare function lastWriteWins(localValue: unknown, remoteValue: unknown, localT
  */
 declare function addWinsSet(localArray: unknown[], remoteArray: unknown[], baseArray: unknown[]): unknown[];
 
+/**
+ * Convergent merge for `object` and `json` fields.
+ *
+ * Structured values are merged as a 3-way LWW map with add-wins key presence:
+ * two devices that edit different keys of the same object offline both keep
+ * their edits on reconnect, instead of one write clobbering the whole object.
+ *
+ * Per key, each side's action is classified against the base (the value before
+ * either operation):
+ * - wrote (added the key, or changed its value)
+ * - removed (present in base, absent now)
+ * - unchanged
+ *
+ * Resolution:
+ * - unchanged + unchanged      → base value
+ * - wrote + unchanged          → the written value
+ * - removed + unchanged        → absent
+ * - removed + removed          → absent
+ * - wrote + removed            → the write wins (add-wins: never silently drop an edit)
+ * - wrote + wrote              → recurse if both are plain objects; add-wins if both
+ *                                arrays; otherwise last-write-wins by the operations'
+ *                                HLC timestamps
+ *
+ * The result is commutative (swapping local/remote also swaps the HLCs, and HLC
+ * compare is a symmetric total order), idempotent (merging a value with itself
+ * returns it), and deterministic. Absent keys are omitted from the result.
+ *
+ * @param localValue - Local value after the local operation
+ * @param remoteValue - Remote value after the remote operation
+ * @param baseValue - Value before either operation (for 3-way diffing)
+ * @param localTs - HLC timestamp of the local operation
+ * @param remoteTs - HLC timestamp of the remote operation
+ * @returns The merged object
+ */
+declare function mergeObject(localValue: unknown, remoteValue: unknown, baseValue: unknown, localTs: HLCTimestamp, remoteTs: HLCTimestamp): Record<string, unknown>;
+
 /**
  * Result of merging two atomic operations on the same field.
  * If `merged` is false, the caller should fall back to LWW on the resolved values.
@@ -270,7 +306,7 @@ interface AtomicMergeFallback {
  */
 declare function mergeAtomicOps(localAtomicOp: AtomicOp, remoteAtomicOp: AtomicOp, baseValue: unknown): AtomicMergeResult | AtomicMergeFallback;
 
-type RichtextValue = string | Uint8Array | ArrayBuffer | null | undefined;
+type RichtextValue = string | Uint8Array | ArrayBuffer | KoraBytesValue | null | undefined;
 /**
  * Merges richtext values using Yjs CRDT updates.
  */
@@ -458,4 +494,4 @@ declare class MergeEngine {
     private mergeWithDelete;
 }
 
-export { type AtomicMergeFallback, type AtomicMergeResult, type ConstraintContext, type ConstraintResolution, type ConstraintViolation, type DeleteVsInsertResolution, type FieldMergeResult, type LWWResult, MergeEngine, type MergeIncomingRelation, type MergeInput, type MergeResult, type ReferentialCheckResult, type ReferentialMergeContext, type SideEffectOp, addWinsSet, appendOnlyMerge, applySchemaStrategy, buildMergeRelationLookup, checkConstraints, checkReferentialIntegrityOnDelete, counterMerge, lastWriteWins, maxMerge, mergeAtomicOps, mergeField, mergeRichtext, minMerge, resolveConstraintViolation, resolveDeleteVsInsertConflict, richtextToString, serverAuthoritativeMerge, stringToRichtextUpdate };
+export { type AtomicMergeFallback, type AtomicMergeResult, type ConstraintContext, type ConstraintResolution, type ConstraintViolation, type DeleteVsInsertResolution, type FieldMergeResult, type LWWResult, MergeEngine, type MergeIncomingRelation, type MergeInput, type MergeResult, type ReferentialCheckResult, type ReferentialMergeContext, type SideEffectOp, addWinsSet, appendOnlyMerge, applySchemaStrategy, buildMergeRelationLookup, checkConstraints, checkReferentialIntegrityOnDelete, counterMerge, lastWriteWins, maxMerge, mergeAtomicOps, mergeField, mergeObject, mergeRichtext, minMerge, resolveConstraintViolation, resolveDeleteVsInsertConflict, richtextToString, serverAuthoritativeMerge, stringToRichtextUpdate };

package/dist/index.js

@@ -55,21 +55,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) {
@@ -133,6 +240,11 @@ function mergeAtomicOps(localAtomicOp, remoteAtomicOp, baseValue) {
 }
 
 // src/strategies/yjs-richtext.ts
+import {
+  decodeBytesFromOpData,
+  isKoraBytesValue,
+  isLegacyNumericByteObject
+} from "@korajs/core";
 import * as Y from "yjs";
 var TEXT_KEY = "content";
 function mergeRichtext(localValue, remoteValue, baseValue) {
@@ -165,7 +277,13 @@ 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 (isKoraBytesValue(value) || isLegacyNumericByteObject(value)) {
+    const decoded = 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
@@ -252,6 +370,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 ?? {};
@@ -383,7 +533,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,
@@ -440,6 +597,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) {
@@ -1226,7 +1405,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) {
@@ -1291,11 +1470,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);
@@ -1306,9 +1482,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) {
@@ -1349,6 +1522,7 @@ export {
   maxMerge,
   mergeAtomicOps,
   mergeField,
+  mergeObject,
   mergeRichtext,
   minMerge,
   resolveConstraintViolation,