@rljson/db 0.0.14 → 0.0.15

package/dist/connector/connector.d.ts

@@ -1,5 +1,5 @@
 import { Socket } from '@rljson/io';
-import { AckPayload, ClientId, InsertHistoryTimeId, Route, SyncConfig, SyncEventNames } from '@rljson/rljson';
+import { AckPayload, ClientId, ConflictCallback, InsertHistoryTimeId, Route, SyncConfig, SyncEventNames } from '@rljson/rljson';
 import { Db } from '../db.ts';
 export type { ConnectorPayload } from '@rljson/rljson';
 export type ConnectorCallback = (ref: string) => Promise<any>;
@@ -9,6 +9,7 @@ export declare class Connector {
     private readonly _socket;
     private _origin;
     private _callbacks;
+    private _conflictCallbacks;
     private _isListening;
     private _sentRefsCurrent;
     private _sentRefsPrevious;
@@ -49,6 +50,18 @@ export declare class Connector {
      * @param callback - The callback to invoke with each deduplicated incoming ref
      */
     listen(callback: ConnectorCallback): void;
+    /**
+     * Registers a callback that fires when a DAG conflict is detected.
+     *
+     * A conflict occurs when the InsertHistory for this route's table
+     * has multiple "tips" (leaf nodes), indicating concurrent writes
+     * from different clients that have not yet been merged.
+     *
+     * Detection-only: the callback receives a `Conflict` object
+     * describing the branches. Resolution is left to upper layers.
+     * @param callback - Invoked with the detected Conflict
+     */
+    onConflict(callback: ConflictCallback): void;
     /**
      * Returns the current sequence number.
      * Only meaningful when `causalOrdering` is enabled.
@@ -83,6 +96,7 @@ export declare class Connector {
      * _processIncoming handles dedup so already-seen refs are filtered out.
      */
     private _registerBootstrapHandler;
+    private _registerConflictObserver;
     private _registerDbObserver;
     get socket(): Socket;
     get route(): Route;

package/dist/db.d.ts

@@ -1,6 +1,6 @@
 import { Io } from '@rljson/io';
 import { Json, JsonValue } from '@rljson/json';
-import { Edit, EditHistory, InsertHistoryRow, InsertHistoryTimeId, MultiEdit, Ref, Rljson, Route, SliceId, TableType, Tree } from '@rljson/rljson';
+import { Conflict, ConflictCallback, Edit, EditHistory, InsertHistoryRow, InsertHistoryTimeId, MultiEdit, Ref, Rljson, Route, SliceId, TableType, Tree } from '@rljson/rljson';
 import { Controller, ControllerChildProperty, ControllerRefs } from './controller/controller.ts';
 import { Core } from './core.ts';
 import { Join } from './join/join.ts';
@@ -43,6 +43,7 @@ export declare class Db {
      * Notification system to register callbacks on data changes
      */
     readonly notify: Notify;
+    private _conflictCallbacks;
     private _cache;
     /**
      * Get data from a route with optional filtering
@@ -137,6 +138,24 @@ export declare class Db {
      * Unregisters all observers from all routes
      */
     unregisterAllObservers(route: Route): void;
+    /**
+     * Registers a callback to be called when a DAG conflict is detected
+     * on the given route.
+     * @param route - The route to register the conflict callback on
+     * @param callback - The callback to invoke with the Conflict
+     */
+    registerConflictObserver(route: Route, callback: ConflictCallback): void;
+    /**
+     * Unregisters a specific conflict callback from the given route.
+     * @param route - The route to unregister the callback from
+     * @param callback - The callback to remove
+     */
+    unregisterConflictObserver(route: Route, callback: ConflictCallback): void;
+    /**
+     * Unregisters all conflict callbacks from the given route.
+     * @param route - The route to clear conflict callbacks for
+     */
+    unregisterAllConflictObservers(route: Route): void;
     /**
      * Get a controller for a specific table
      * @param tableKey - The key of the table to get the controller for
@@ -146,6 +165,22 @@ export declare class Db {
      */
     getController(tableKey: string, refs?: ControllerRefs): Promise<Controller<TableType, any, string>>;
     indexedControllers(route: Route): Promise<Record<string, Controller<any, any, any>>>;
+    /**
+     * Detects whether the InsertHistory for a table has diverged into
+     * multiple branches (multiple "tips" — leaf nodes in the DAG).
+     *
+     * A tip is a timeId that is NOT referenced as `previous` by any other
+     * InsertHistory row. Two or more tips indicate a DAG fork (conflict).
+     * @param table - The table name (without "InsertHistory" suffix)
+     * @returns A Conflict if a DAG branch is detected, or null otherwise
+     */
+    detectDagBranch(table: string): Promise<Conflict | null>;
+    /**
+     * Fires conflict callbacks registered on the route derived from the table.
+     * @param table - The table name
+     * @param conflict - The detected conflict
+     */
+    private _notifyConflict;
     /**
      * Adds an InsertHistory row to the InsertHistory table of a table
      * @param table - The table the Insert was made on

package/dist/db.js

@@ -22,6 +22,7 @@ class Connector {
   }
   _origin;
   _callbacks = [];
+  _conflictCallbacks = [];
   _isListening = false;
   // Two-generation dedup sets — bounded memory
   _sentRefsCurrent = /* @__PURE__ */ new Set();
@@ -107,6 +108,21 @@ class Connector {
     this._callbacks.push(callback);
   }
   // ...........................................................................
+  /**
+   * Registers a callback that fires when a DAG conflict is detected.
+   *
+   * A conflict occurs when the InsertHistory for this route's table
+   * has multiple "tips" (leaf nodes), indicating concurrent writes
+   * from different clients that have not yet been merged.
+   *
+   * Detection-only: the callback receives a `Conflict` object
+   * describing the branches. Resolution is left to upper layers.
+   * @param callback - Invoked with the detected Conflict
+   */
+  onConflict(callback) {
+    this._conflictCallbacks.push(callback);
+  }
+  // ...........................................................................
   /**
    * Returns the current sequence number.
    * Only meaningful when `causalOrdering` is enabled.
@@ -143,6 +159,7 @@ class Connector {
     this._registerSocketObserver();
     this._registerBootstrapHandler();
     this._registerDbObserver();
+    this._registerConflictObserver();
     if (this._syncConfig?.causalOrdering) {
       this._registerGapFillHandler();
     }
@@ -158,6 +175,7 @@ class Connector {
       this._socket.removeAllListeners(this._events.ack);
     }
     this._db.unregisterAllObservers(this._route);
+    this._db.unregisterAllConflictObservers(this._route);
     this._isListening = false;
   }
   // ...........................................................................
@@ -235,6 +253,13 @@ class Connector {
       this._processIncoming(p);
     });
   }
+  _registerConflictObserver() {
+    this._db.registerConflictObserver(this._route, (conflict) => {
+      for (const cb of this._conflictCallbacks) {
+        cb(conflict);
+      }
+    });
+  }
   _registerDbObserver() {
     this._db.registerObserver(this._route, (ins) => {
       return new Promise((resolve) => {
@@ -3092,6 +3117,7 @@ class Db {
    * Notification system to register callbacks on data changes
    */
   notify;
+  _conflictCallbacks = /* @__PURE__ */ new Map();
   _cache = /* @__PURE__ */ new Map();
   // ...........................................................................
   /**
@@ -4061,6 +4087,44 @@ class Db {
     this.notify.unregisterAll(route);
   }
   // ...........................................................................
+  /**
+   * Registers a callback to be called when a DAG conflict is detected
+   * on the given route.
+   * @param route - The route to register the conflict callback on
+   * @param callback - The callback to invoke with the Conflict
+   */
+  registerConflictObserver(route, callback) {
+    const key = route.flat;
+    this._conflictCallbacks.set(key, [
+      ...this._conflictCallbacks.get(key) || [],
+      callback
+    ]);
+  }
+  // ...........................................................................
+  /**
+   * Unregisters a specific conflict callback from the given route.
+   * @param route - The route to unregister the callback from
+   * @param callback - The callback to remove
+   */
+  unregisterConflictObserver(route, callback) {
+    const key = route.flat;
+    const callbacks = this._conflictCallbacks.get(key);
+    if (callbacks) {
+      this._conflictCallbacks.set(
+        key,
+        callbacks.filter((cb) => cb !== callback)
+      );
+    }
+  }
+  // ...........................................................................
+  /**
+   * Unregisters all conflict callbacks from the given route.
+   * @param route - The route to clear conflict callbacks for
+   */
+  unregisterAllConflictObservers(route) {
+    this._conflictCallbacks.delete(route.flat);
+  }
+  // ...........................................................................
   /**
    * Get a controller for a specific table
    * @param tableKey - The key of the table to get the controller for
@@ -4093,6 +4157,57 @@ class Db {
     return controllers;
   }
   // ...........................................................................
+  /**
+   * Detects whether the InsertHistory for a table has diverged into
+   * multiple branches (multiple "tips" — leaf nodes in the DAG).
+   *
+   * A tip is a timeId that is NOT referenced as `previous` by any other
+   * InsertHistory row. Two or more tips indicate a DAG fork (conflict).
+   * @param table - The table name (without "InsertHistory" suffix)
+   * @returns A Conflict if a DAG branch is detected, or null otherwise
+   */
+  async detectDagBranch(table) {
+    const insertHistoryTable = table + "InsertHistory";
+    const hasTable = await this.core.hasTable(insertHistoryTable);
+    if (!hasTable) return null;
+    const dump = await this.core.dumpTable(insertHistoryTable);
+    const rows = dump[insertHistoryTable]._data;
+    if (rows.length < 2) return null;
+    const referencedAsParent = /* @__PURE__ */ new Set();
+    for (const row of rows) {
+      if (row.previous) {
+        for (const p of row.previous) {
+          referencedAsParent.add(p);
+        }
+      }
+    }
+    const tips = rows.filter((row) => !referencedAsParent.has(row.timeId));
+    if (tips.length > 1) {
+      return {
+        table,
+        type: "dagBranch",
+        detectedAt: Date.now(),
+        branches: tips.map((t) => t.timeId)
+      };
+    }
+    return null;
+  }
+  // ...........................................................................
+  /**
+   * Fires conflict callbacks registered on the route derived from the table.
+   * @param table - The table name
+   * @param conflict - The detected conflict
+   */
+  _notifyConflict(table, conflict) {
+    const route = Route.fromFlat(`/${table}`);
+    const callbacks = this._conflictCallbacks.get(route.flat);
+    if (callbacks) {
+      for (const cb of callbacks) {
+        cb(conflict);
+      }
+    }
+  }
+  // ...........................................................................
   /**
    * Adds an InsertHistory row to the InsertHistory table of a table
    * @param table - The table the Insert was made on
@@ -4107,6 +4222,10 @@ class Db {
         _type: "insertHistory"
       }
     });
+    const conflict = await this.detectDagBranch(table);
+    if (conflict) {
+      this._notifyConflict(table, conflict);
+    }
   }
   // ...........................................................................
   /**