@korajs/merge 0.1.0

package/dist/index.cjs

@@ -0,0 +1,763 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MergeEngine: () => MergeEngine,
+  addWinsSet: () => addWinsSet,
+  checkConstraints: () => checkConstraints,
+  lastWriteWins: () => lastWriteWins,
+  mergeField: () => mergeField,
+  mergeRichtext: () => mergeRichtext,
+  resolveConstraintViolation: () => resolveConstraintViolation,
+  richtextToString: () => richtextToString,
+  stringToRichtextUpdate: () => stringToRichtextUpdate
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/strategies/lww.ts
+var import_core = require("@korajs/core");
+function lastWriteWins(localValue, remoteValue, localTimestamp, remoteTimestamp) {
+  const comparison = import_core.HybridLogicalClock.compare(localTimestamp, remoteTimestamp);
+  if (comparison >= 0) {
+    return { value: localValue, winner: "local" };
+  }
+  return { value: remoteValue, winner: "remote" };
+}
+
+// src/strategies/add-wins-set.ts
+function addWinsSet(localArray, remoteArray, baseArray) {
+  const serialize = (v) => JSON.stringify(v);
+  const baseSet = new Set(baseArray.map(serialize));
+  const localSet = new Set(localArray.map(serialize));
+  const remoteSet = new Set(remoteArray.map(serialize));
+  const addedLocal = /* @__PURE__ */ new Set();
+  for (const s of localSet) {
+    if (!baseSet.has(s)) {
+      addedLocal.add(s);
+    }
+  }
+  const addedRemote = /* @__PURE__ */ new Set();
+  for (const s of remoteSet) {
+    if (!baseSet.has(s)) {
+      addedRemote.add(s);
+    }
+  }
+  const removedLocal = /* @__PURE__ */ new Set();
+  for (const s of baseSet) {
+    if (!localSet.has(s)) {
+      removedLocal.add(s);
+    }
+  }
+  const removedRemote = /* @__PURE__ */ new Set();
+  for (const s of baseSet) {
+    if (!remoteSet.has(s)) {
+      removedRemote.add(s);
+    }
+  }
+  const removedByBoth = /* @__PURE__ */ new Set();
+  for (const s of removedLocal) {
+    if (removedRemote.has(s)) {
+      removedByBoth.add(s);
+    }
+  }
+  const resultSerialized = /* @__PURE__ */ new Set();
+  const result = [];
+  const addIfNew = (serialized, value) => {
+    if (!resultSerialized.has(serialized) && !removedByBoth.has(serialized)) {
+      resultSerialized.add(serialized);
+      result.push(value);
+    }
+  };
+  for (const item of baseArray) {
+    addIfNew(serialize(item), item);
+  }
+  for (const item of localArray) {
+    const s = serialize(item);
+    if (addedLocal.has(s)) {
+      addIfNew(s, item);
+    }
+  }
+  for (const item of remoteArray) {
+    const s = serialize(item);
+    if (addedRemote.has(s)) {
+      addIfNew(s, item);
+    }
+  }
+  return result;
+}
+
+// src/strategies/yjs-richtext.ts
+var Y = __toESM(require("yjs"), 1);
+var TEXT_KEY = "content";
+function mergeRichtext(localValue, remoteValue, baseValue) {
+  const mergedDoc = new Y.Doc();
+  Y.applyUpdate(mergedDoc, toYjsUpdate(baseValue));
+  Y.applyUpdate(mergedDoc, toYjsUpdate(localValue));
+  Y.applyUpdate(mergedDoc, toYjsUpdate(remoteValue));
+  return Y.encodeStateAsUpdate(mergedDoc);
+}
+function richtextToString(value) {
+  const doc = new Y.Doc();
+  Y.applyUpdate(doc, toYjsUpdate(value));
+  return doc.getText(TEXT_KEY).toString();
+}
+function stringToRichtextUpdate(value) {
+  const doc = new Y.Doc();
+  doc.getText(TEXT_KEY).insert(0, value);
+  return Y.encodeStateAsUpdate(doc);
+}
+function toYjsUpdate(value) {
+  if (value === null || value === void 0) {
+    return Y.encodeStateAsUpdate(new Y.Doc());
+  }
+  if (typeof value === "string") {
+    return stringToRichtextUpdate(value);
+  }
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  throw new Error("Richtext value must be a string, Uint8Array, ArrayBuffer, null, or undefined.");
+}
+
+// src/engine/field-merger.ts
+function mergeField(fieldName, localOp, remoteOp, baseState, fieldDescriptor, resolver) {
+  const startTime = Date.now();
+  const localData = localOp.data ?? {};
+  const remoteData = remoteOp.data ?? {};
+  const localPrevious = localOp.previousData ?? {};
+  const remotePrevious = remoteOp.previousData ?? {};
+  const localChanged = fieldName in localData;
+  const remoteChanged = fieldName in remoteData;
+  const baseValue = baseState[fieldName];
+  if (localChanged && !remoteChanged) {
+    return createResult(
+      localData[fieldName],
+      fieldName,
+      localOp,
+      remoteOp,
+      localData[fieldName],
+      baseValue,
+      baseValue,
+      "no-conflict-local",
+      1,
+      startTime
+    );
+  }
+  if (!localChanged && remoteChanged) {
+    return createResult(
+      remoteData[fieldName],
+      fieldName,
+      localOp,
+      remoteOp,
+      baseValue,
+      remoteData[fieldName],
+      baseValue,
+      "no-conflict-remote",
+      1,
+      startTime
+    );
+  }
+  if (!localChanged && !remoteChanged) {
+    return createResult(
+      baseValue,
+      fieldName,
+      localOp,
+      remoteOp,
+      baseValue,
+      baseValue,
+      baseValue,
+      "no-conflict-unchanged",
+      1,
+      startTime
+    );
+  }
+  const localValue = localData[fieldName];
+  const remoteValue = remoteData[fieldName];
+  if (resolver !== void 0) {
+    const resolved = resolver(localValue, remoteValue, baseValue);
+    return createResult(
+      resolved,
+      fieldName,
+      localOp,
+      remoteOp,
+      localValue,
+      remoteValue,
+      baseValue,
+      "custom",
+      3,
+      startTime
+    );
+  }
+  return autoMerge(
+    fieldName,
+    localOp,
+    remoteOp,
+    localValue,
+    remoteValue,
+    baseValue,
+    fieldDescriptor,
+    startTime
+  );
+}
+function autoMerge(fieldName, localOp, remoteOp, localValue, remoteValue, baseValue, fieldDescriptor, startTime) {
+  switch (fieldDescriptor.kind) {
+    case "string":
+    case "number":
+    case "boolean":
+    case "enum":
+    case "timestamp": {
+      const lwwResult = lastWriteWins(
+        localValue,
+        remoteValue,
+        localOp.timestamp,
+        remoteOp.timestamp
+      );
+      return createResult(
+        lwwResult.value,
+        fieldName,
+        localOp,
+        remoteOp,
+        localValue,
+        remoteValue,
+        baseValue,
+        "lww",
+        1,
+        startTime
+      );
+    }
+    case "array": {
+      const baseArr = Array.isArray(baseValue) ? baseValue : [];
+      const localArr = Array.isArray(localValue) ? localValue : [];
+      const remoteArr = Array.isArray(remoteValue) ? remoteValue : [];
+      const merged = addWinsSet(localArr, remoteArr, baseArr);
+      return createResult(
+        merged,
+        fieldName,
+        localOp,
+        remoteOp,
+        localValue,
+        remoteValue,
+        baseValue,
+        "add-wins-set",
+        1,
+        startTime
+      );
+    }
+    case "richtext": {
+      const merged = mergeRichtext(
+        localValue,
+        remoteValue,
+        baseValue
+      );
+      return createResult(
+        merged,
+        fieldName,
+        localOp,
+        remoteOp,
+        localValue,
+        remoteValue,
+        baseValue,
+        "crdt-text",
+        1,
+        startTime
+      );
+    }
+  }
+}
+function createResult(value, field, operationA, operationB, inputA, inputB, base, strategy, tier, startTime) {
+  const trace = {
+    operationA,
+    operationB,
+    field,
+    strategy,
+    inputA,
+    inputB,
+    base,
+    output: value,
+    tier,
+    constraintViolated: null,
+    duration: Date.now() - startTime
+  };
+  return { value, trace };
+}
+
+// src/constraints/constraint-checker.ts
+async function checkConstraints(mergedRecord, recordId, collection, collectionDef, constraintContext) {
+  const violations = [];
+  for (const constraint of collectionDef.constraints) {
+    if (constraint.type !== "referential" && constraint.where !== void 0 && !matchesWhere(mergedRecord, constraint.where)) {
+      continue;
+    }
+    const violation = await checkSingleConstraint(
+      constraint,
+      mergedRecord,
+      recordId,
+      collection,
+      constraintContext
+    );
+    if (violation !== null) {
+      violations.push(violation);
+    }
+  }
+  return violations;
+}
+async function checkSingleConstraint(constraint, mergedRecord, recordId, collection, ctx) {
+  switch (constraint.type) {
+    case "unique":
+      return checkUniqueConstraint(constraint, mergedRecord, recordId, collection, ctx);
+    case "capacity":
+      return checkCapacityConstraint(constraint, mergedRecord, collection, ctx);
+    case "referential":
+      return checkReferentialConstraint(constraint, mergedRecord, collection, ctx);
+  }
+}
+async function checkUniqueConstraint(constraint, mergedRecord, recordId, collection, ctx) {
+  const where = {};
+  for (const field of constraint.fields) {
+    where[field] = mergedRecord[field];
+  }
+  const existing = await ctx.queryRecords(collection, where);
+  const duplicates = existing.filter((r) => r.id !== recordId);
+  if (duplicates.length > 0) {
+    return {
+      constraint,
+      fields: constraint.fields,
+      message: `Unique constraint violated on fields [${constraint.fields.join(", ")}] in collection "${collection}": duplicate value(s) found`
+    };
+  }
+  return null;
+}
+async function checkCapacityConstraint(constraint, mergedRecord, collection, ctx) {
+  const where = constraint.where ?? {};
+  const count = await ctx.countRecords(collection, where);
+  if (count > 0 && constraint.fields.length > 0) {
+    const groupWhere = { ...where };
+    for (const field of constraint.fields) {
+      groupWhere[field] = mergedRecord[field];
+    }
+    const groupCount = await ctx.countRecords(collection, groupWhere);
+    if (groupCount > 1) {
+      return {
+        constraint,
+        fields: constraint.fields,
+        message: `Capacity constraint violated on fields [${constraint.fields.join(", ")}] in collection "${collection}": group count ${groupCount} exceeds limit`
+      };
+    }
+  }
+  return null;
+}
+async function checkReferentialConstraint(constraint, mergedRecord, collection, ctx) {
+  if (constraint.fields.length === 0) {
+    return null;
+  }
+  const fkField = constraint.fields[0];
+  if (fkField === void 0) {
+    return null;
+  }
+  const fkValue = mergedRecord[fkField];
+  if (fkValue === null || fkValue === void 0) {
+    return null;
+  }
+  const referencedCollection = constraint.where !== void 0 ? constraint.where.collection : void 0;
+  if (referencedCollection === void 0) {
+    return null;
+  }
+  const referenced = await ctx.queryRecords(referencedCollection, { id: fkValue });
+  if (referenced.length === 0) {
+    return {
+      constraint,
+      fields: constraint.fields,
+      message: `Referential constraint violated on field "${fkField}" in collection "${collection}": referenced record not found in "${referencedCollection}" with id "${String(fkValue)}"`
+    };
+  }
+  return null;
+}
+function matchesWhere(record, where) {
+  for (const [key, value] of Object.entries(where)) {
+    if (record[key] !== value) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// src/constraints/resolvers.ts
+var import_core2 = 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_core2.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+      const winner = comparison >= 0 ? localOp : remoteOp;
+      const resolvedRecord = applyWinnerFields(mergedRecord, winner, violation.fields);
+      return createResolution(
+        resolvedRecord,
+        violation,
+        localOp,
+        remoteOp,
+        baseState,
+        "constraint-lww",
+        startTime
+      );
+    }
+    case "first-write-wins": {
+      const comparison = import_core2.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+      const winner = comparison <= 0 ? localOp : remoteOp;
+      const resolvedRecord = applyWinnerFields(mergedRecord, winner, violation.fields);
+      return createResolution(
+        resolvedRecord,
+        violation,
+        localOp,
+        remoteOp,
+        baseState,
+        "constraint-fww",
+        startTime
+      );
+    }
+    case "priority-field": {
+      const priorityField = constraint.priorityField;
+      if (priorityField === void 0) {
+        const comparison = import_core2.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+        const winner2 = comparison >= 0 ? localOp : remoteOp;
+        const resolvedRecord2 = applyWinnerFields(mergedRecord, winner2, violation.fields);
+        return createResolution(
+          resolvedRecord2,
+          violation,
+          localOp,
+          remoteOp,
+          baseState,
+          "constraint-priority-fallback-lww",
+          startTime
+        );
+      }
+      const localPriority = getFieldValue(localOp, priorityField, mergedRecord);
+      const remotePriority = getFieldValue(remoteOp, priorityField, mergedRecord);
+      const winner = comparePriority(localPriority, remotePriority) >= 0 ? localOp : remoteOp;
+      const resolvedRecord = applyWinnerFields(mergedRecord, winner, violation.fields);
+      return createResolution(
+        resolvedRecord,
+        violation,
+        localOp,
+        remoteOp,
+        baseState,
+        "constraint-priority",
+        startTime
+      );
+    }
+    case "server-decides": {
+      const resolvedRecord = {
+        ...mergedRecord,
+        _pendingServerResolution: true
+      };
+      return createResolution(
+        resolvedRecord,
+        violation,
+        localOp,
+        remoteOp,
+        baseState,
+        "constraint-server-decides",
+        startTime
+      );
+    }
+    case "custom": {
+      if (constraint.resolve === void 0) {
+        const comparison = import_core2.HybridLogicalClock.compare(localOp.timestamp, remoteOp.timestamp);
+        const winner = comparison >= 0 ? localOp : remoteOp;
+        const resolvedRecord2 = applyWinnerFields(mergedRecord, winner, violation.fields);
+        return createResolution(
+          resolvedRecord2,
+          violation,
+          localOp,
+          remoteOp,
+          baseState,
+          "constraint-custom-fallback-lww",
+          startTime
+        );
+      }
+      const resolvedRecord = { ...mergedRecord };
+      for (const field of violation.fields) {
+        const localVal = getFieldValue(localOp, field, mergedRecord);
+        const remoteVal = getFieldValue(remoteOp, field, mergedRecord);
+        const baseVal = baseState[field];
+        resolvedRecord[field] = constraint.resolve(localVal, remoteVal, baseVal);
+      }
+      return createResolution(
+        resolvedRecord,
+        violation,
+        localOp,
+        remoteOp,
+        baseState,
+        "constraint-custom",
+        startTime
+      );
+    }
+  }
+}
+function applyWinnerFields(mergedRecord, winner, fields) {
+  const result = { ...mergedRecord };
+  const winnerData = winner.data ?? {};
+  for (const field of fields) {
+    if (field in winnerData) {
+      result[field] = winnerData[field];
+    }
+  }
+  return result;
+}
+function getFieldValue(op, field, mergedRecord) {
+  const data = op.data ?? {};
+  if (field in data) {
+    return data[field];
+  }
+  return mergedRecord[field];
+}
+function comparePriority(a, b) {
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  if (typeof a === "string" && typeof b === "string") {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
+}
+function createResolution(resolvedRecord, violation, localOp, remoteOp, baseState, strategy, startTime) {
+  const field = violation.fields.join(", ");
+  const trace = {
+    operationA: localOp,
+    operationB: remoteOp,
+    field,
+    strategy,
+    inputA: extractFieldValues(localOp, violation.fields),
+    inputB: extractFieldValues(remoteOp, violation.fields),
+    base: extractFields(baseState, violation.fields),
+    output: extractFields(resolvedRecord, violation.fields),
+    tier: 2,
+    constraintViolated: violation.message,
+    duration: Date.now() - startTime
+  };
+  return { resolvedRecord, trace };
+}
+function extractFieldValues(op, fields) {
+  const data = op.data ?? {};
+  const result = {};
+  for (const field of fields) {
+    result[field] = data[field];
+  }
+  return result;
+}
+function extractFields(record, fields) {
+  const result = {};
+  for (const field of fields) {
+    result[field] = record[field];
+  }
+  return result;
+}
+
+// src/engine/merge-engine.ts
+var import_core3 = require("@korajs/core");
+var MergeEngine = class {
+  /**
+   * Merge two concurrent operations with all three tiers.
+   *
+   * Flow:
+   * 1. Determine which fields conflict (both ops modified the same field)
+   * 2. For non-conflicting fields: take the changed value from whichever op modified it
+   * 3. For conflicting fields: Tier 3 custom resolver if exists, else Tier 1 auto-merge
+   * 4. Assemble candidate merged record
+   * 5. If constraintContext provided: run Tier 2 constraint checks and resolve violations
+   * 6. Return MergeResult with all traces
+   *
+   * @param input - The two operations, base state, and collection definition
+   * @param constraintContext - Optional DB lookup interface for Tier 2 constraints
+   * @returns The merged data and traces for DevTools
+   */
+  async merge(input, constraintContext) {
+    if (input.local.type === "delete" && input.remote.type === "delete") {
+      return {
+        mergedData: {},
+        traces: [],
+        appliedOperation: "merged"
+      };
+    }
+    if (input.local.type === "delete" || input.remote.type === "delete") {
+      return this.mergeWithDelete(input);
+    }
+    const fieldResult = this.mergeFields(input);
+    if (constraintContext !== void 0 && input.collectionDef.constraints.length > 0) {
+      const recordWithId = { id: input.local.recordId, ...fieldResult.mergedData };
+      const violations = await checkConstraints(
+        recordWithId,
+        input.local.recordId,
+        input.local.collection,
+        input.collectionDef,
+        constraintContext
+      );
+      let mergedData = fieldResult.mergedData;
+      const allTraces = [...fieldResult.traces];
+      for (const violation of violations) {
+        const resolution = resolveConstraintViolation(
+          violation,
+          mergedData,
+          input.local,
+          input.remote,
+          input.baseState
+        );
+        mergedData = resolution.resolvedRecord;
+        allTraces.push(resolution.trace);
+      }
+      return {
+        mergedData,
+        traces: allTraces,
+        appliedOperation: determineAppliedOperation(allTraces)
+      };
+    }
+    return fieldResult;
+  }
+  /**
+   * Synchronous field-level merge (Tier 1 + Tier 3 only).
+   *
+   * Useful when constraint context is unavailable or not needed.
+   * Skips Tier 2 constraint checking entirely.
+   *
+   * @param input - The two operations, base state, and collection definition
+   * @returns The merged data and traces for DevTools
+   */
+  mergeFields(input) {
+    const { local, remote, baseState, collectionDef } = input;
+    const allFields = collectAffectedFields(local, remote, baseState, collectionDef);
+    const mergedData = {};
+    const traces = [];
+    for (const fieldName of allFields) {
+      const fieldDef = collectionDef.fields[fieldName];
+      if (fieldDef === void 0) {
+        continue;
+      }
+      const resolver = collectionDef.resolvers[fieldName];
+      const result = mergeField(fieldName, local, remote, baseState, fieldDef, resolver);
+      mergedData[fieldName] = result.value;
+      if (result.trace.strategy !== "no-conflict-local" && result.trace.strategy !== "no-conflict-remote" && result.trace.strategy !== "no-conflict-unchanged") {
+        traces.push(result.trace);
+      }
+    }
+    return {
+      mergedData,
+      traces,
+      appliedOperation: determineAppliedOperation(traces)
+    };
+  }
+  /**
+   * Handle merge when one operation is a delete.
+   * Default: delete wins (LWW on the record level).
+   */
+  mergeWithDelete(input) {
+    const { local, remote } = input;
+    const comparison = import_core3.HybridLogicalClock.compare(local.timestamp, remote.timestamp);
+    if (comparison >= 0) {
+      if (local.type === "delete") {
+        return { mergedData: {}, traces: [], appliedOperation: "local" };
+      }
+      return {
+        mergedData: { ...input.baseState, ...local.data ?? {} },
+        traces: [],
+        appliedOperation: "local"
+      };
+    }
+    if (remote.type === "delete") {
+      return { mergedData: {}, traces: [], appliedOperation: "remote" };
+    }
+    return {
+      mergedData: { ...input.baseState, ...remote.data ?? {} },
+      traces: [],
+      appliedOperation: "remote"
+    };
+  }
+};
+function collectAffectedFields(local, remote, baseState, collectionDef) {
+  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);
+    }
+  }
+  if (remote.data !== null) {
+    for (const fieldName of Object.keys(remote.data)) {
+      fields.add(fieldName);
+    }
+  }
+  for (const fieldName of Object.keys(baseState)) {
+    fields.add(fieldName);
+  }
+  return fields;
+}
+function determineAppliedOperation(traces) {
+  if (traces.length === 0) {
+    return "merged";
+  }
+  let allLocal = true;
+  let allRemote = true;
+  for (const trace of traces) {
+    if (trace.strategy === "lww" || trace.strategy === "constraint-lww") {
+      if (trace.output === trace.inputA) {
+        allRemote = false;
+      } else if (trace.output === trace.inputB) {
+        allLocal = false;
+      } else {
+        allLocal = false;
+        allRemote = false;
+      }
+    } else {
+      allLocal = false;
+      allRemote = false;
+    }
+  }
+  if (allLocal) return "local";
+  if (allRemote) return "remote";
+  return "merged";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MergeEngine,
+  addWinsSet,
+  checkConstraints,
+  lastWriteWins,
+  mergeField,
+  mergeRichtext,
+  resolveConstraintViolation,
+  richtextToString,
+  stringToRichtextUpdate
+});
+//# sourceMappingURL=index.cjs.map