@rotorsoft/act 0.15.0 → 0.16.0

package/dist/index.js

@@ -697,13 +697,16 @@ var Act = class {
     dispose(() => {
       this._emitter.removeAllListeners();
       this.stop_correlations();
+      this.stop_settling();
       return Promise.resolve();
     });
   }
   _emitter = new EventEmitter();
   _drain_locked = false;
   _drain_lag2lead_ratio = 0.5;
-  _correlation_interval = void 0;
+  _correlation_timer = void 0;
+  _settle_timer = void 0;
+  _settling = false;
   emit(event, args) {
     return this._emitter.emit(event, args);
   }
@@ -953,7 +956,7 @@ var Act = class {
   /**
    * Processes pending reactions by draining uncommitted events from the event store.
    *
-   * The drain process:
+   * Runs a single drain cycle:
    * 1. Polls the store for streams with uncommitted events
    * 2. Leases streams to prevent concurrent processing
    * 3. Fetches events for each leased stream
@@ -963,7 +966,8 @@ var Act = class {
    * Drain uses a dual-frontier strategy to balance processing of new streams (lagging)
    * vs active streams (leading). The ratio adapts based on event pressure.
    *
-   * Call this method periodically in a background loop, or after committing events.
+   * Call `correlate()` before `drain()` to discover target streams. For a higher-level
+   * API that handles debouncing, correlation, and signaling automatically, use {@link settle}.
    *
    * @param options - Drain configuration options
    * @param options.streamLimit - Maximum number of streams to process per cycle (default: 10)
@@ -971,46 +975,20 @@ var Act = class {
    * @param options.leaseMillis - Lease duration in milliseconds (default: 10000)
    * @returns Drain statistics with fetched, leased, acked, and blocked counts
    *
-   * @example Basic drain loop
+   * @example In tests and scripts
    * ```typescript
-   * // Process reactions after each action
    * await app.do("createUser", target, payload);
+   * await app.correlate();
    * await app.drain();
    * ```
    *
-   * @example Background drain worker
+   * @example In production, prefer settle()
    * ```typescript
-   * setInterval(async () => {
-   *   try {
-   *     const result = await app.drain({
-   *       streamLimit: 20,
-   *       eventLimit: 50
-   *     });
-   *     if (result.acked.length) {
-   *       console.log(`Processed ${result.acked.length} streams`);
-   *     }
-   *   } catch (error) {
-   *     console.error("Drain error:", error);
-   *   }
-   * }, 5000); // Every 5 seconds
-   * ```
-   *
-   * @example With lifecycle listeners
-   * ```typescript
-   * app.on("acked", (leases) => {
-   *   console.log(`Acknowledged ${leases.length} streams`);
-   * });
-   *
-   * app.on("blocked", (blocked) => {
-   *   console.error(`Blocked ${blocked.length} streams due to errors`);
-   *   blocked.forEach(({ stream, error }) => {
-   *     console.error(`Stream ${stream}: ${error}`);
-   *   });
-   * });
-   *
-   * await app.drain();
+   * await app.do("CreateItem", target, input);
+   * app.settle(); // debounced correlate→drain, emits "settled"
    * ```
    *
+   * @see {@link settle} for debounced correlate→drain with lifecycle events
    * @see {@link correlate} for dynamic stream discovery
    * @see {@link start_correlations} for automatic correlation
    */
@@ -1239,10 +1217,10 @@ var Act = class {
    * @see {@link stop_correlations} to stop the worker
    */
   start_correlations(query = {}, frequency = 1e4, callback) {
-    if (this._correlation_interval) return false;
+    if (this._correlation_timer) return false;
     const limit = query.limit || 100;
     let after = query.after || -1;
-    this._correlation_interval = setInterval(
+    this._correlation_timer = setInterval(
       () => this.correlate({ ...query, after, limit }).then((result) => {
         after = result.last_id;
         if (callback && result.leased.length) callback(result.leased);
@@ -1269,11 +1247,77 @@ var Act = class {
    * @see {@link start_correlations}
    */
   stop_correlations() {
-    if (this._correlation_interval) {
-      clearInterval(this._correlation_interval);
-      this._correlation_interval = void 0;
+    if (this._correlation_timer) {
+      clearInterval(this._correlation_timer);
+      this._correlation_timer = void 0;
+    }
+  }
+  /**
+   * Cancels any pending or active settle cycle.
+   *
+   * @see {@link settle}
+   */
+  stop_settling() {
+    if (this._settle_timer) {
+      clearTimeout(this._settle_timer);
+      this._settle_timer = void 0;
     }
   }
+  /**
+   * Debounced, non-blocking correlate→drain cycle.
+   *
+   * Call this after `app.do()` to schedule a background drain. Multiple rapid
+   * calls within the debounce window are coalesced into a single cycle. Runs
+   * correlate→drain in a loop until the system reaches a consistent state,
+   * then emits the `"settled"` lifecycle event.
+   *
+   * @param options - Settle configuration options
+   * @param options.debounceMs - Debounce window in milliseconds (default: 10)
+   * @param options.correlate - Query filter for correlation scans (default: `{ after: -1, limit: 100 }`)
+   * @param options.maxPasses - Maximum correlate→drain loops (default: 5)
+   * @param options.streamLimit - Maximum streams per drain cycle (default: 10)
+   * @param options.eventLimit - Maximum events per stream (default: 10)
+   * @param options.leaseMillis - Lease duration in milliseconds (default: 10000)
+   *
+   * @example API mutations
+   * ```typescript
+   * await app.do("CreateItem", target, input);
+   * app.settle(); // non-blocking, returns immediately
+   *
+   * app.on("settled", (drain) => {
+   *   // notify SSE clients, invalidate caches, etc.
+   * });
+   * ```
+   *
+   * @see {@link drain} for single synchronous drain cycles
+   * @see {@link correlate} for manual correlation
+   */
+  settle(options = {}) {
+    const {
+      debounceMs = 10,
+      correlate: correlateQuery = { after: -1, limit: 100 },
+      maxPasses = 5,
+      ...drainOptions
+    } = options;
+    if (this._settle_timer) clearTimeout(this._settle_timer);
+    this._settle_timer = setTimeout(() => {
+      this._settle_timer = void 0;
+      if (this._settling) return;
+      this._settling = true;
+      (async () => {
+        let lastDrain;
+        for (let i = 0; i < maxPasses; i++) {
+          const { leased } = await this.correlate(correlateQuery);
+          if (leased.length === 0 && i > 0) break;
+          lastDrain = await this.drain(drainOptions);
+          if (!lastDrain.acked.length && !lastDrain.blocked.length) break;
+        }
+        if (lastDrain) this.emit("settled", lastDrain);
+      })().catch((err) => logger.error(err)).finally(() => {
+        this._settling = false;
+      });
+    }, debounceMs);
+  }
 };
 
 // src/merge.ts