@rotorsoft/act 0.30.0 → 0.30.1

package/dist/index.js

@@ -1622,6 +1622,46 @@ var Act = class {
       this._settle_timer = void 0;
     }
   }
+  /**
+   * Reset reaction stream watermarks and request a drain on the next
+   * `drain()` / `settle()` cycle.
+   *
+   * Use this to replay events through projections (or other reaction targets)
+   * after changing handler logic. Equivalent to calling `store().reset(streams)`
+   * directly, but also raises the orchestrator's internal "needs drain" flag —
+   * `store().reset(...)` alone leaves the flag untouched, so a settled app
+   * would short-circuit and skip the replay.
+   *
+   * Pair with `app.settle()` (or a single `app.drain()` for small streams).
+   * `settle()` loops correlate→drain until no progress is made, so one call
+   * fully catches up paginated streams without forcing callers to roll
+   * their own loop.
+   *
+   * @param streams - Reaction target streams (e.g., projection names) to reset
+   * @returns Count of streams that were actually reset
+   *
+   * @example Rebuild a projection (production)
+   * ```typescript
+   * await app.reset(["my-projection"]);
+   * app.settle({ eventLimit: 1000 });   // emits "settled" when fully replayed
+   * ```
+   *
+   * @example Rebuild a projection (tests / scripts)
+   * ```typescript
+   * await app.reset(["my-projection"]);
+   * await app.drain({ eventLimit: 1000 });   // small streams: one pass is enough
+   * ```
+   *
+   * @see {@link Store.reset} for the underlying store primitive
+   * @see {@link settle} for the debounced full-catch-up loop
+   */
+  async reset(streams) {
+    const count = await store().reset(streams);
+    if (count > 0 && this._reactive_events.size > 0) {
+      this._needs_drain = true;
+    }
+    return count;
+  }
   /**
    * Close the books — guard, archive, truncate, and optionally restart streams.
    *
@@ -1789,15 +1829,19 @@ var Act = class {
   /**
    * 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.
+   * Call this after `app.do()` (or `app.reset()`) 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 a pass makes
+   * no progress — no new subscriptions, no acks, no blocks — then emits
+   * the `"settled"` lifecycle event. This means a single `settle()` call
+   * fully catches up paginated streams (e.g. after `reset()` on a long
+   * projection) without forcing callers to loop.
    *
    * @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: 1)
+   * @param options.maxPasses - Cap on correlate→drain loops (default: `Infinity`).
+   *   Early-exit on no-progress means the cap only matters in pathological cases.
    * @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)
@@ -1819,7 +1863,7 @@ var Act = class {
     const {
       debounceMs = 10,
       correlate: correlateQuery = { after: -1, limit: 100 },
-      maxPasses = 1,
+      maxPasses = Infinity,
       ...drainOptions
     } = options;
     if (this._settle_timer) clearTimeout(this._settle_timer);
@@ -1835,9 +1879,9 @@ var Act = class {
             ...correlateQuery,
             after: this._correlation_checkpoint
           });
-          if (subscribed === 0 && i > 0) break;
           lastDrain = await this.drain(drainOptions);
-          if (!lastDrain.acked.length && !lastDrain.blocked.length) break;
+          const made_progress = subscribed > 0 || lastDrain.acked.length > 0 || lastDrain.blocked.length > 0;
+          if (!made_progress) break;
         }
         if (lastDrain) this.emit("settled", lastDrain);
       })().catch((err) => logger3.error(err)).finally(() => {