@korajs/merge 0.3.1 → 0.4.0

package/dist/index.js

@@ -70,6 +70,68 @@ function addWinsSet(localArray, remoteArray, baseArray) {
   return result;
 }
 
+// src/strategies/atomic-merge.ts
+function mergeAtomicOps(localAtomicOp, remoteAtomicOp, baseValue) {
+  if (localAtomicOp.type !== remoteAtomicOp.type) {
+    return { merged: false };
+  }
+  switch (localAtomicOp.type) {
+    case "increment": {
+      const base = typeof baseValue === "number" ? baseValue : 0;
+      const localDelta = localAtomicOp.value;
+      const remoteDelta = remoteAtomicOp.value;
+      return {
+        merged: true,
+        value: base + localDelta + remoteDelta,
+        strategy: "atomic-increment"
+      };
+    }
+    case "max": {
+      const base = typeof baseValue === "number" ? baseValue : Number.NEGATIVE_INFINITY;
+      const localVal = localAtomicOp.value;
+      const remoteVal = remoteAtomicOp.value;
+      return {
+        merged: true,
+        value: Math.max(base, localVal, remoteVal),
+        strategy: "atomic-max"
+      };
+    }
+    case "min": {
+      const base = typeof baseValue === "number" ? baseValue : Number.POSITIVE_INFINITY;
+      const localVal = localAtomicOp.value;
+      const remoteVal = remoteAtomicOp.value;
+      return {
+        merged: true,
+        value: Math.min(base, localVal, remoteVal),
+        strategy: "atomic-min"
+      };
+    }
+    case "append": {
+      const base = Array.isArray(baseValue) ? [...baseValue] : [];
+      base.push(localAtomicOp.value);
+      base.push(remoteAtomicOp.value);
+      return {
+        merged: true,
+        value: base,
+        strategy: "atomic-append"
+      };
+    }
+    case "remove": {
+      const base = Array.isArray(baseValue) ? [...baseValue] : [];
+      const localItem = localAtomicOp.value;
+      const remoteItem = remoteAtomicOp.value;
+      const result = base.filter((item) => item !== localItem && item !== remoteItem);
+      return {
+        merged: true,
+        value: result,
+        strategy: "atomic-remove"
+      };
+    }
+    default:
+      return { merged: false };
+  }
+}
+
 // src/strategies/yjs-richtext.ts
 import * as Y from "yjs";
 var TEXT_KEY = "content";
@@ -106,6 +168,88 @@ function toYjsUpdate(value) {
   throw new Error("Richtext value must be a string, Uint8Array, ArrayBuffer, null, or undefined.");
 }
 
+// src/strategies/schema-strategies.ts
+import "@korajs/core";
+function counterMerge(localValue, remoteValue, baseValue) {
+  const base = typeof baseValue === "number" ? baseValue : 0;
+  const local = typeof localValue === "number" ? localValue : base;
+  const remote = typeof remoteValue === "number" ? remoteValue : base;
+  const localDelta = local - base;
+  const remoteDelta = remote - base;
+  return base + localDelta + remoteDelta;
+}
+function maxMerge(localValue, remoteValue, baseValue) {
+  const vals = [];
+  if (typeof baseValue === "number") vals.push(baseValue);
+  if (typeof localValue === "number") vals.push(localValue);
+  if (typeof remoteValue === "number") vals.push(remoteValue);
+  if (vals.length === 0) return baseValue;
+  return Math.max(...vals);
+}
+function minMerge(localValue, remoteValue, baseValue) {
+  const vals = [];
+  if (typeof baseValue === "number") vals.push(baseValue);
+  if (typeof localValue === "number") vals.push(localValue);
+  if (typeof remoteValue === "number") vals.push(remoteValue);
+  if (vals.length === 0) return baseValue;
+  return Math.min(...vals);
+}
+function appendOnlyMerge(localValue, remoteValue, baseValue) {
+  const base = Array.isArray(baseValue) ? baseValue : [];
+  const local = Array.isArray(localValue) ? localValue : [];
+  const remote = Array.isArray(remoteValue) ? remoteValue : [];
+  const serialize = (v) => JSON.stringify(v);
+  const baseSet = new Set(base.map(serialize));
+  const result = [...base];
+  const resultSet = new Set(base.map(serialize));
+  for (const item of local) {
+    const s = serialize(item);
+    if (!baseSet.has(s) && !resultSet.has(s)) {
+      result.push(item);
+      resultSet.add(s);
+    }
+  }
+  for (const item of remote) {
+    const s = serialize(item);
+    if (!baseSet.has(s) && !resultSet.has(s)) {
+      result.push(item);
+      resultSet.add(s);
+    }
+  }
+  return result;
+}
+function serverAuthoritativeMerge(_localValue, remoteValue, _baseValue) {
+  return remoteValue;
+}
+function applySchemaStrategy(strategy, localValue, remoteValue, baseValue, localTimestamp, remoteTimestamp) {
+  switch (strategy) {
+    case "counter":
+      return {
+        value: counterMerge(localValue, remoteValue, baseValue),
+        strategyName: "schema-counter"
+      };
+    case "max":
+      return { value: maxMerge(localValue, remoteValue, baseValue), strategyName: "schema-max" };
+    case "min":
+      return { value: minMerge(localValue, remoteValue, baseValue), strategyName: "schema-min" };
+    case "append-only":
+      return {
+        value: appendOnlyMerge(localValue, remoteValue, baseValue),
+        strategyName: "schema-append-only"
+      };
+    case "server-authoritative":
+      return {
+        value: serverAuthoritativeMerge(localValue, remoteValue, baseValue),
+        strategyName: "schema-server-authoritative"
+      };
+    case "lww":
+    case "union":
+      return null;
+    default:
+      return null;
+  }
+}
+
 // src/engine/field-merger.ts
 function mergeField(fieldName, localOp, remoteOp, baseState, fieldDescriptor, resolver) {
   const startTime = Date.now();
@@ -175,6 +319,53 @@ function mergeField(fieldName, localOp, remoteOp, baseState, fieldDescriptor, re
       startTime
     );
   }
+  const localAtomicOp = localOp.atomicOps?.[fieldName];
+  const remoteAtomicOp = remoteOp.atomicOps?.[fieldName];
+  if (localAtomicOp !== void 0 && remoteAtomicOp !== void 0) {
+    const atomicResult = mergeAtomicOps(
+      localAtomicOp,
+      remoteAtomicOp,
+      baseValue
+    );
+    if (atomicResult.merged) {
+      return createResult(
+        atomicResult.value,
+        fieldName,
+        localOp,
+        remoteOp,
+        localValue,
+        remoteValue,
+        baseValue,
+        atomicResult.strategy,
+        1,
+        startTime
+      );
+    }
+  }
+  if (fieldDescriptor.mergeStrategy !== null && fieldDescriptor.mergeStrategy !== void 0) {
+    const schemaResult = applySchemaStrategy(
+      fieldDescriptor.mergeStrategy,
+      localValue,
+      remoteValue,
+      baseValue,
+      localOp.timestamp,
+      remoteOp.timestamp
+    );
+    if (schemaResult !== null) {
+      return createResult(
+        schemaResult.value,
+        fieldName,
+        localOp,
+        remoteOp,
+        localValue,
+        remoteValue,
+        baseValue,
+        schemaResult.strategyName,
+        1,
+        startTime
+      );
+    }
+  }
   return autoMerge(
     fieldName,
     localOp,
@@ -369,13 +560,13 @@ function matchesWhere(record, where) {
 }
 
 // src/constraints/resolvers.ts
-import { HybridLogicalClock as HybridLogicalClock2 } from "@korajs/core";
+import { HybridLogicalClock as HybridLogicalClock3 } from "@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 = HybridLogicalClock2.compare(localOp.timestamp, remoteOp.timestamp);
+      const comparison = HybridLogicalClock3.compare(localOp.timestamp, remoteOp.timestamp);
       const winner = comparison >= 0 ? localOp : remoteOp;
       const resolvedRecord = applyWinnerFields(mergedRecord, winner, violation.fields);
       return createResolution(
@@ -389,7 +580,7 @@ function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp,
       );
     }
     case "first-write-wins": {
-      const comparison = HybridLogicalClock2.compare(localOp.timestamp, remoteOp.timestamp);
+      const comparison = HybridLogicalClock3.compare(localOp.timestamp, remoteOp.timestamp);
       const winner = comparison <= 0 ? localOp : remoteOp;
       const resolvedRecord = applyWinnerFields(mergedRecord, winner, violation.fields);
       return createResolution(
@@ -405,7 +596,7 @@ function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp,
     case "priority-field": {
       const priorityField = constraint.priorityField;
       if (priorityField === void 0) {
-        const comparison = HybridLogicalClock2.compare(localOp.timestamp, remoteOp.timestamp);
+        const comparison = HybridLogicalClock3.compare(localOp.timestamp, remoteOp.timestamp);
         const winner2 = comparison >= 0 ? localOp : remoteOp;
         const resolvedRecord2 = applyWinnerFields(mergedRecord, winner2, violation.fields);
         return createResolution(
@@ -449,7 +640,7 @@ function resolveConstraintViolation(violation, mergedRecord, localOp, remoteOp,
     }
     case "custom": {
       if (constraint.resolve === void 0) {
-        const comparison = HybridLogicalClock2.compare(localOp.timestamp, remoteOp.timestamp);
+        const comparison = HybridLogicalClock3.compare(localOp.timestamp, remoteOp.timestamp);
         const winner = comparison >= 0 ? localOp : remoteOp;
         const resolvedRecord2 = applyWinnerFields(mergedRecord, winner, violation.fields);
         return createResolution(
@@ -540,8 +731,426 @@ function extractFields(record, fields) {
   return result;
 }
 
+// src/constraints/referential-integrity.ts
+import "@korajs/core";
+function buildMergeRelationLookup(schema) {
+  const lookup = /* @__PURE__ */ new Map();
+  const relationNames = Object.keys(schema.relations).sort();
+  for (const relationName of relationNames) {
+    const relation = schema.relations[relationName];
+    if (relation === void 0) {
+      continue;
+    }
+    const targetCollection = relation.to;
+    const existing = lookup.get(targetCollection) ?? [];
+    existing.push({
+      relationName,
+      sourceCollection: relation.from,
+      foreignKeyField: relation.field,
+      onDelete: relation.onDelete
+    });
+    lookup.set(targetCollection, existing);
+  }
+  for (const [, relations] of lookup) {
+    relations.sort(
+      (a, b) => a.relationName < b.relationName ? -1 : a.relationName > b.relationName ? 1 : 0
+    );
+  }
+  return lookup;
+}
+async function checkReferentialIntegrityOnDelete(deleteOp, schema, ctx, relationLookup) {
+  const lookup = relationLookup ?? buildMergeRelationLookup(schema);
+  const incomingRelations = lookup.get(deleteOp.collection);
+  if (incomingRelations === void 0 || incomingRelations.length === 0) {
+    return { allowed: true, sideEffectOps: [], traces: [] };
+  }
+  const allSideEffects = [];
+  const allTraces = [];
+  for (const relation of incomingRelations) {
+    const startTime = Date.now();
+    const referencingRecords = await ctx.queryRecords(relation.sourceCollection, {
+      [relation.foreignKeyField]: deleteOp.recordId
+    });
+    const sortedRecords = [...referencingRecords].sort((a, b) => {
+      const idA = String(a.id ?? "");
+      const idB = String(b.id ?? "");
+      return idA < idB ? -1 : idA > idB ? 1 : 0;
+    });
+    if (sortedRecords.length === 0) {
+      const trace = createReferentialTrace(
+        deleteOp,
+        relation,
+        `referential-${relation.onDelete}`,
+        null,
+        null,
+        true,
+        startTime
+      );
+      allTraces.push(trace);
+      continue;
+    }
+    switch (relation.onDelete) {
+      case "restrict": {
+        const trace = createReferentialTrace(
+          deleteOp,
+          relation,
+          "referential-restrict",
+          sortedRecords.map((r) => String(r.id ?? "")),
+          null,
+          false,
+          startTime
+        );
+        allTraces.push(trace);
+        return {
+          allowed: false,
+          sideEffectOps: [],
+          traces: allTraces
+        };
+      }
+      case "cascade": {
+        for (const record of sortedRecords) {
+          const recordId = String(record.id ?? "");
+          allSideEffects.push({
+            type: "delete",
+            collection: relation.sourceCollection,
+            recordId,
+            data: null,
+            previousData: null,
+            policy: "cascade",
+            relationName: relation.relationName
+          });
+        }
+        const trace = createReferentialTrace(
+          deleteOp,
+          relation,
+          "referential-cascade",
+          sortedRecords.map((r) => String(r.id ?? "")),
+          sortedRecords.map((r) => ({ type: "delete", recordId: String(r.id ?? "") })),
+          true,
+          startTime
+        );
+        allTraces.push(trace);
+        break;
+      }
+      case "set-null": {
+        for (const record of sortedRecords) {
+          const recordId = String(record.id ?? "");
+          const previousValue = record[relation.foreignKeyField];
+          allSideEffects.push({
+            type: "update",
+            collection: relation.sourceCollection,
+            recordId,
+            data: { [relation.foreignKeyField]: null },
+            previousData: { [relation.foreignKeyField]: previousValue },
+            policy: "set-null",
+            relationName: relation.relationName
+          });
+        }
+        const trace = createReferentialTrace(
+          deleteOp,
+          relation,
+          "referential-set-null",
+          sortedRecords.map((r) => String(r.id ?? "")),
+          sortedRecords.map((r) => ({
+            type: "update",
+            recordId: String(r.id ?? ""),
+            field: relation.foreignKeyField,
+            newValue: null
+          })),
+          true,
+          startTime
+        );
+        allTraces.push(trace);
+        break;
+      }
+      case "no-action": {
+        const trace = createReferentialTrace(
+          deleteOp,
+          relation,
+          "referential-no-action",
+          sortedRecords.map((r) => String(r.id ?? "")),
+          null,
+          true,
+          startTime
+        );
+        allTraces.push(trace);
+        break;
+      }
+    }
+  }
+  return {
+    allowed: true,
+    sideEffectOps: allSideEffects,
+    traces: allTraces
+  };
+}
+function resolveDeleteVsInsertConflict(deleteOp, insertOp, relation) {
+  const startTime = Date.now();
+  switch (relation.onDelete) {
+    case "restrict": {
+      const trace = createDeleteVsInsertTrace(
+        deleteOp,
+        insertOp,
+        relation,
+        "referential-restrict",
+        "block-delete",
+        startTime
+      );
+      return {
+        action: "block-delete",
+        sideEffects: [],
+        trace
+      };
+    }
+    case "cascade": {
+      const sideEffect = {
+        type: "delete",
+        collection: relation.sourceCollection,
+        recordId: insertOp.recordId,
+        data: null,
+        previousData: null,
+        policy: "cascade",
+        relationName: relation.relationName
+      };
+      const trace = createDeleteVsInsertTrace(
+        deleteOp,
+        insertOp,
+        relation,
+        "referential-cascade",
+        "allow-delete",
+        startTime
+      );
+      return {
+        action: "allow-delete",
+        sideEffects: [sideEffect],
+        trace
+      };
+    }
+    case "set-null": {
+      const fkValue = insertOp.data !== null ? insertOp.data[relation.foreignKeyField] : void 0;
+      const sideEffect = {
+        type: "update",
+        collection: relation.sourceCollection,
+        recordId: insertOp.recordId,
+        data: { [relation.foreignKeyField]: null },
+        previousData: { [relation.foreignKeyField]: fkValue ?? null },
+        policy: "set-null",
+        relationName: relation.relationName
+      };
+      const trace = createDeleteVsInsertTrace(
+        deleteOp,
+        insertOp,
+        relation,
+        "referential-set-null",
+        "allow-delete",
+        startTime
+      );
+      return {
+        action: "allow-delete",
+        sideEffects: [sideEffect],
+        trace
+      };
+    }
+    case "no-action": {
+      const trace = createDeleteVsInsertTrace(
+        deleteOp,
+        insertOp,
+        relation,
+        "referential-no-action",
+        "allow-delete",
+        startTime
+      );
+      return {
+        action: "allow-delete",
+        sideEffects: [],
+        trace
+      };
+    }
+  }
+}
+function createReferentialTrace(deleteOp, relation, strategy, referencingRecordIds, sideEffects, allowed, startTime) {
+  return {
+    operationA: deleteOp,
+    // For referential integrity checks, operationB is the same as operationA
+    // because we are checking constraints against the delete operation itself,
+    // not merging two conflicting operations.
+    operationB: deleteOp,
+    field: `${relation.sourceCollection}.${relation.foreignKeyField}`,
+    strategy,
+    inputA: { recordId: deleteOp.recordId, collection: deleteOp.collection },
+    inputB: referencingRecordIds,
+    base: null,
+    output: { allowed, sideEffects },
+    tier: 2,
+    constraintViolated: `referential:${relation.relationName}`,
+    duration: Date.now() - startTime
+  };
+}
+function createDeleteVsInsertTrace(deleteOp, insertOp, relation, strategy, action, startTime) {
+  return {
+    operationA: deleteOp,
+    operationB: insertOp,
+    field: `${relation.sourceCollection}.${relation.foreignKeyField}`,
+    strategy,
+    inputA: { type: "delete", recordId: deleteOp.recordId, collection: deleteOp.collection },
+    inputB: { type: "insert", recordId: insertOp.recordId, collection: insertOp.collection },
+    base: null,
+    output: { action },
+    tier: 2,
+    constraintViolated: `referential:${relation.relationName}`,
+    duration: Date.now() - startTime
+  };
+}
+
+// src/engine/merge-engine.ts
+import { HybridLogicalClock as HybridLogicalClock6 } from "@korajs/core";
+
+// src/constraints/state-machine-constraint.ts
+import { HybridLogicalClock as HybridLogicalClock5, validateTransition } from "@korajs/core";
+function isValid(sm, from, to) {
+  const constraint = {
+    field: sm.field,
+    collection: "",
+    transitions: sm.transitions
+  };
+  return validateTransition(constraint, from, to).valid;
+}
+function resolveStateMachineMerge(fieldName, localOp, remoteOp, baseState, stateMachine) {
+  const startTime = Date.now();
+  const baseValue = baseState[fieldName];
+  const localData = localOp.data ?? {};
+  const remoteData = remoteOp.data ?? {};
+  const localValue = localData[fieldName];
+  const remoteValue = remoteData[fieldName];
+  const baseStateStr = typeof baseValue === "string" ? baseValue : "";
+  const localStr = typeof localValue === "string" ? localValue : baseStateStr;
+  const remoteStr = typeof remoteValue === "string" ? remoteValue : baseStateStr;
+  const localChanged = fieldName in localData;
+  const remoteChanged = fieldName in remoteData;
+  if (localChanged && !remoteChanged) {
+    const valid = isValid(stateMachine, baseStateStr, localStr);
+    return makeResult(
+      valid ? localStr : baseStateStr,
+      fieldName,
+      localOp,
+      remoteOp,
+      localValue,
+      baseValue,
+      baseValue,
+      valid ? "state-machine-no-conflict-local" : "state-machine-invalid-local",
+      valid ? null : `Invalid transition from "${baseStateStr}" to "${localStr}"`,
+      startTime
+    );
+  }
+  if (!localChanged && remoteChanged) {
+    const valid = isValid(stateMachine, baseStateStr, remoteStr);
+    return makeResult(
+      valid ? remoteStr : baseStateStr,
+      fieldName,
+      localOp,
+      remoteOp,
+      baseValue,
+      remoteValue,
+      baseValue,
+      valid ? "state-machine-no-conflict-remote" : "state-machine-invalid-remote",
+      valid ? null : `Invalid transition from "${baseStateStr}" to "${remoteStr}"`,
+      startTime
+    );
+  }
+  if (!localChanged && !remoteChanged) {
+    return makeResult(
+      baseStateStr,
+      fieldName,
+      localOp,
+      remoteOp,
+      baseValue,
+      baseValue,
+      baseValue,
+      "state-machine-no-conflict-unchanged",
+      null,
+      startTime
+    );
+  }
+  const localValid = isValid(stateMachine, baseStateStr, localStr);
+  const remoteValid = isValid(stateMachine, baseStateStr, remoteStr);
+  if (localValid && remoteValid) {
+    const comparison = HybridLogicalClock5.compare(localOp.timestamp, remoteOp.timestamp);
+    const winner = comparison >= 0 ? localStr : remoteStr;
+    return makeResult(
+      winner,
+      fieldName,
+      localOp,
+      remoteOp,
+      localValue,
+      remoteValue,
+      baseValue,
+      "state-machine-lww",
+      null,
+      startTime
+    );
+  }
+  if (localValid && !remoteValid) {
+    return makeResult(
+      localStr,
+      fieldName,
+      localOp,
+      remoteOp,
+      localValue,
+      remoteValue,
+      baseValue,
+      "state-machine-valid-wins",
+      `Remote transition from "${baseStateStr}" to "${remoteStr}" is invalid; local "${localStr}" wins`,
+      startTime
+    );
+  }
+  if (!localValid && remoteValid) {
+    return makeResult(
+      remoteStr,
+      fieldName,
+      localOp,
+      remoteOp,
+      localValue,
+      remoteValue,
+      baseValue,
+      "state-machine-valid-wins",
+      `Local transition from "${baseStateStr}" to "${localStr}" is invalid; remote "${remoteStr}" wins`,
+      startTime
+    );
+  }
+  return makeResult(
+    baseStateStr,
+    fieldName,
+    localOp,
+    remoteOp,
+    localValue,
+    remoteValue,
+    baseValue,
+    "state-machine-both-invalid",
+    `Both transitions invalid from "${baseStateStr}": local to "${localStr}", remote to "${remoteStr}". Keeping base state.`,
+    startTime
+  );
+}
+function isStateMachineField(collectionDef, fieldName) {
+  return collectionDef.stateMachine !== void 0 && collectionDef.stateMachine.field === fieldName;
+}
+function makeResult(value, field, operationA, operationB, inputA, inputB, base, strategy, constraintViolated, startTime) {
+  const trace = {
+    operationA,
+    operationB,
+    field,
+    strategy,
+    inputA,
+    inputB,
+    base,
+    output: value,
+    tier: 2,
+    constraintViolated,
+    duration: Date.now() - startTime
+  };
+  return { value, trace };
+}
+
 // src/engine/merge-engine.ts
-import { HybridLogicalClock as HybridLogicalClock3 } from "@korajs/core";
 var MergeEngine = class {
   /**
    * Merge two concurrent operations with all three tiers.
@@ -619,6 +1228,20 @@ var MergeEngine = class {
       if (fieldDef === void 0) {
         continue;
       }
+      if (collectionDef.stateMachine !== void 0 && isStateMachineField(collectionDef, fieldName)) {
+        const smResult = resolveStateMachineMerge(
+          fieldName,
+          local,
+          remote,
+          baseState,
+          collectionDef.stateMachine
+        );
+        mergedData[fieldName] = smResult.value;
+        if (smResult.trace.strategy !== "state-machine-no-conflict-unchanged") {
+          traces.push(smResult.trace);
+        }
+        continue;
+      }
       const resolver = collectionDef.resolvers[fieldName];
       const result = mergeField(fieldName, local, remote, baseState, fieldDef, resolver);
       mergedData[fieldName] = result.value;
@@ -638,7 +1261,7 @@ var MergeEngine = class {
    */
   mergeWithDelete(input) {
     const { local, remote } = input;
-    const comparison = HybridLogicalClock3.compare(local.timestamp, remote.timestamp);
+    const comparison = HybridLogicalClock6.compare(local.timestamp, remote.timestamp);
     if (comparison >= 0) {
       if (local.type === "delete") {
         return { mergedData: {}, traces: [], appliedOperation: "local" };
@@ -707,12 +1330,22 @@ function determineAppliedOperation(traces) {
 export {
   MergeEngine,
   addWinsSet,
+  appendOnlyMerge,
+  applySchemaStrategy,
+  buildMergeRelationLookup,
   checkConstraints,
+  checkReferentialIntegrityOnDelete,
+  counterMerge,
   lastWriteWins,
+  maxMerge,
+  mergeAtomicOps,
   mergeField,
   mergeRichtext,
+  minMerge,
   resolveConstraintViolation,
+  resolveDeleteVsInsertConflict,
   richtextToString,
+  serverAuthoritativeMerge,
   stringToRichtextUpdate
 };
 //# sourceMappingURL=index.js.map