@korajs/merge 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Constraint, MergeTrace, Operation, CollectionDefinition, HLCTimestamp, FieldDescriptor, CustomResolver } from '@korajs/core';
+import { Constraint, MergeTrace, Operation, CollectionDefinition, HLCTimestamp, AtomicOp, FieldMergeStrategy, FieldDescriptor, CustomResolver, OnDeleteAction, SchemaDefinition } from '@korajs/core';
 
 /**
  * Input to the merge engine when two concurrent operations conflict.
@@ -105,6 +105,43 @@ declare function lastWriteWins(localValue: unknown, remoteValue: unknown, localT
  */
 declare function addWinsSet(localArray: unknown[], remoteArray: unknown[], baseArray: unknown[]): 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.
+ */
+interface AtomicMergeResult {
+    merged: true;
+    value: unknown;
+    strategy: string;
+}
+/**
+ * Sentinel returned when atomic ops cannot be composed (e.g., mismatched types).
+ */
+interface AtomicMergeFallback {
+    merged: false;
+}
+/**
+ * Compose two concurrent atomic operations on the same field.
+ *
+ * When both operations expressed an atomic intent (e.g., both used op.increment()),
+ * their intents can be composed to produce a correct merged result without LWW:
+ *
+ * - increment + increment → sum of both deltas applied to base
+ * - max + max → max of all values (base, local, remote)
+ * - min + min → min of all values (base, local, remote)
+ * - append + append → base array with both appended items
+ * - remove + remove → base array with both items removed
+ *
+ * Falls back (returns { merged: false }) when atomic op types differ,
+ * since there is no meaningful composition for mixed intents.
+ *
+ * @param localAtomicOp - The atomic op from the local operation
+ * @param remoteAtomicOp - The atomic op from the remote operation
+ * @param baseValue - The field value before either operation was applied
+ * @returns The composed result, or a fallback signal to use LWW
+ */
+declare function mergeAtomicOps(localAtomicOp: AtomicOp, remoteAtomicOp: AtomicOp, baseValue: unknown): AtomicMergeResult | AtomicMergeFallback;
+
 type RichtextValue = string | Uint8Array | ArrayBuffer | null | undefined;
 /**
  * Merges richtext values using Yjs CRDT updates.
@@ -119,6 +156,51 @@ declare function richtextToString(value: RichtextValue): string;
  */
 declare function stringToRichtextUpdate(value: string): Uint8Array;
 
+/**
+ * Schema-declared merge strategies.
+ *
+ * These are invoked when a field has an explicit `mergeStrategy` declared in the schema
+ * via `t.number().merge('counter')` etc. They override the default kind-based auto-merge.
+ */
+/**
+ * Counter merge: sum of deltas from base.
+ * Both sides' changes are additive relative to the base value.
+ *
+ * Example: base=10, local=15, remote=12 → result = 10 + 5 + 2 = 17
+ */
+declare function counterMerge(localValue: unknown, remoteValue: unknown, baseValue: unknown): unknown;
+/**
+ * Max merge: keep the maximum of all concurrent values.
+ * Works for numbers and timestamps.
+ */
+declare function maxMerge(localValue: unknown, remoteValue: unknown, baseValue: unknown): unknown;
+/**
+ * Min merge: keep the minimum of all concurrent values.
+ * Works for numbers and timestamps.
+ */
+declare function minMerge(localValue: unknown, remoteValue: unknown, baseValue: unknown): unknown;
+/**
+ * Append-only merge for arrays: concatenate additions from both sides.
+ * Unlike add-wins-set, removals are ignored — items can only be added, never removed.
+ *
+ * Result = base + local additions + remote additions (preserving order)
+ */
+declare function appendOnlyMerge(localValue: unknown, remoteValue: unknown, baseValue: unknown): unknown[];
+/**
+ * Server-authoritative merge: always prefer the remote (server) value.
+ */
+declare function serverAuthoritativeMerge(_localValue: unknown, remoteValue: unknown, _baseValue: unknown): unknown;
+/**
+ * Dispatch to the appropriate schema-declared strategy.
+ *
+ * @returns The merged value, or null if the strategy is not handled here
+ *          (e.g., 'lww' and 'union' which are handled by the default autoMerge).
+ */
+declare function applySchemaStrategy(strategy: FieldMergeStrategy, localValue: unknown, remoteValue: unknown, baseValue: unknown, localTimestamp: HLCTimestamp, remoteTimestamp: HLCTimestamp): {
+    value: unknown;
+    strategyName: string;
+} | null;
+
 /**
  * Merges a single field from two concurrent operations.
  *
@@ -187,6 +269,128 @@ interface ConstraintResolution {
  */
 declare function resolveConstraintViolation(violation: ConstraintViolation, mergedRecord: Record<string, unknown>, localOp: Operation, remoteOp: Operation, baseState: Record<string, unknown>): ConstraintResolution;
 
+/**
+ * Describes an incoming relation to a target collection.
+ * Used by the delete-side referential integrity checker to know which
+ * source collections reference the collection being deleted from.
+ */
+interface MergeIncomingRelation {
+    /** Name of the relation in the schema (e.g., 'todoBelongsToProject') */
+    relationName: string;
+    /** The collection that holds the foreign key (source of the relation) */
+    sourceCollection: string;
+    /** The foreign key field in the source collection */
+    foreignKeyField: string;
+    /** What to do when the referenced record is deleted */
+    onDelete: OnDeleteAction;
+}
+/**
+ * Pluggable context for querying the database during referential integrity checks.
+ * The store layer provides the implementation; the merge package only depends on this interface.
+ */
+interface ReferentialMergeContext {
+    /** Query records in a collection matching a where clause */
+    queryRecords(collection: string, where: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    /** Check if a record exists in a collection */
+    recordExists(collection: string, recordId: string): Promise<boolean>;
+}
+/**
+ * Result of a referential integrity check on a delete operation.
+ */
+interface ReferentialCheckResult {
+    /** Whether the delete operation is allowed to proceed */
+    allowed: boolean;
+    /** Side-effect operations generated by cascade/set-null policies */
+    sideEffectOps: SideEffectOp[];
+    /** MergeTraces for every decision made (feeds DevTools) */
+    traces: MergeTrace[];
+}
+/**
+ * A side-effect operation generated during referential integrity enforcement.
+ * These are not full Operations; they describe mutations the caller must apply.
+ */
+interface SideEffectOp {
+    /** The type of mutation to apply */
+    type: 'delete' | 'update';
+    /** The collection containing the affected record */
+    collection: string;
+    /** The ID of the affected record */
+    recordId: string;
+    /** For updates: the new field values. null for deletes. */
+    data: Record<string, unknown> | null;
+    /** For updates: the previous field values. null for deletes. */
+    previousData: Record<string, unknown> | null;
+    /** The onDelete policy that produced this side effect */
+    policy: OnDeleteAction;
+    /** The relation that triggered this side effect */
+    relationName: string;
+}
+/**
+ * Result of resolving a concurrent delete-vs-insert conflict.
+ */
+interface DeleteVsInsertResolution {
+    /** Whether to block the delete or allow it */
+    action: 'block-delete' | 'allow-delete';
+    /** Any side-effect operations (for cascade/set-null after allowing delete) */
+    sideEffects: SideEffectOp[];
+    /** Trace of the resolution decision, or null if no trace needed */
+    trace: MergeTrace | null;
+}
+/**
+ * Builds a lookup map from target collection to all incoming relations.
+ *
+ * This pre-computes which collections reference a given collection via foreign keys,
+ * so that delete operations can efficiently find all relations that need enforcement.
+ *
+ * @param schema - The full schema definition with relations
+ * @returns Map from target collection name to array of incoming relations, sorted by relation name for determinism
+ *
+ * @example
+ * ```typescript
+ * const lookup = buildMergeRelationLookup(schema)
+ * // lookup.get('projects') => [{ relationName: 'todoBelongsToProject', sourceCollection: 'todos', ... }]
+ * ```
+ */
+declare function buildMergeRelationLookup(schema: SchemaDefinition): Map<string, MergeIncomingRelation[]>;
+/**
+ * Checks referential integrity when a delete operation is being applied.
+ *
+ * For each relation that targets the deleted record's collection, queries
+ * for referencing records and applies the relation's onDelete policy:
+ * - `restrict`: Blocks the delete if any references exist
+ * - `cascade`: Allows the delete and generates cascaded delete SideEffectOps
+ * - `set-null`: Allows the delete and generates update SideEffectOps to null out FKs
+ * - `no-action`: Allows the delete with no side effects (dangling references permitted)
+ *
+ * Processing is deterministic: relations are processed in sorted order by name,
+ * and referencing records within each relation are processed in sorted order by ID.
+ *
+ * @param deleteOp - The delete operation being evaluated
+ * @param schema - The full schema definition
+ * @param ctx - Database lookup context
+ * @param relationLookup - Pre-built relation lookup (optional; will be built if not provided)
+ * @returns Whether the delete is allowed, any side-effect ops, and traces for DevTools
+ */
+declare function checkReferentialIntegrityOnDelete(deleteOp: Operation, schema: SchemaDefinition, ctx: ReferentialMergeContext, relationLookup?: Map<string, MergeIncomingRelation[]>): Promise<ReferentialCheckResult>;
+/**
+ * Resolves a concurrent delete-vs-insert conflict on a referenced record.
+ *
+ * When one node deletes a record while another concurrently inserts a record
+ * that references the deleted record, we need to decide what wins.
+ *
+ * Resolution strategy depends on the relation's onDelete policy:
+ * - `restrict`: Block the delete (the insert wins — data integrity preserved)
+ * - `cascade`: Allow the delete and cascade-delete the newly inserted record
+ * - `set-null`: Allow the delete and null out the FK on the newly inserted record
+ * - `no-action`: Allow the delete (dangling reference is acceptable)
+ *
+ * @param deleteOp - The delete operation on the referenced record
+ * @param insertOp - The concurrent insert operation that references the deleted record
+ * @param relation - The relation definition connecting the two collections
+ * @returns The resolution action, side effects, and trace
+ */
+declare function resolveDeleteVsInsertConflict(deleteOp: Operation, insertOp: Operation, relation: MergeIncomingRelation): DeleteVsInsertResolution;
+
 /**
  * Three-tier merge engine for resolving concurrent operations.
  *
@@ -242,4 +446,4 @@ declare class MergeEngine {
     private mergeWithDelete;
 }
 
-export { type ConstraintContext, type ConstraintResolution, type ConstraintViolation, type FieldMergeResult, type LWWResult, MergeEngine, type MergeInput, type MergeResult, addWinsSet, checkConstraints, lastWriteWins, mergeField, mergeRichtext, resolveConstraintViolation, richtextToString, 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, mergeRichtext, minMerge, resolveConstraintViolation, resolveDeleteVsInsertConflict, richtextToString, serverAuthoritativeMerge, stringToRichtextUpdate };