@rotorsoft/act 0.29.1 → 0.30.1

package/dist/index.js

@@ -1033,24 +1033,22 @@ var Act = class {
    * }
    * ```
    *
-   * @example Reaction triggering another action
+   * @example Reaction triggering another action (reactingTo auto-injected)
    * ```typescript
    * const app = act()
    *   .withState(Order)
    *   .withState(Inventory)
    *   .on("OrderPlaced")
-   *     .do(async (event, context) => {
-   *       // This action is triggered by an event
-   *       const result = await context.app.do(
+   *     .do(async function reduceInventory(event, _stream, app) {
+   *       // Inside reaction handlers, reactingTo is auto-injected when omitted.
+   *       // The triggering event is used by default, maintaining the correlation chain.
+   *       await app.do(
    *         "reduceStock",
-   *         {
-   *           stream: "inventory-1",
-   *           actor: event.meta.causation.action.actor
-   *         },
-   *         { amount: event.data.items.length },
-   *         event // Pass event for correlation tracking
+   *         { stream: "inventory-1", actor: { id: "sys", name: "system" } },
+   *         { amount: event.data.items.length }
    *       );
-   *       return result;
+   *       // To use a different correlation, pass reactingTo explicitly:
+   *       // await app.do("reduceStock", target, payload, customEvent);
    *     })
    *     .to("inventory-1")
    *   .build();
@@ -1186,6 +1184,11 @@ var Act = class {
    * This is called by the main `drain` loop after fetching new events.
    * It handles reactions, supporting retries, blocking, and error handling.
    *
+   * Each handler receives a scoped `IAct` proxy that auto-injects the
+   * triggering event as `reactingTo` when `do()` is called without it,
+   * maintaining correlation chains by default (#587). Handlers can still
+   * pass an explicit `reactingTo` to override this behavior.
+   *
    * @internal
    * @param lease The lease to handle
    * @param payloads The reactions to handle
@@ -1196,10 +1199,24 @@ var Act = class {
     const stream = lease.stream;
     let at = payloads.at(0).event.id, handled = 0;
     lease.retry > 0 && logger3.warn(`Retrying ${stream}@${at} (${lease.retry}).`);
+    const doAction = this.do.bind(this);
+    const scopedApp = {
+      do: doAction,
+      load: this.load.bind(this),
+      query: this.query.bind(this),
+      query_array: this.query_array.bind(this)
+    };
     for (const payload of payloads) {
       const { event, handler, options } = payload;
+      scopedApp.do = (action2, target, payload2, reactingTo, skipValidation) => doAction(
+        action2,
+        target,
+        payload2,
+        reactingTo ?? event,
+        skipValidation
+      );
       try {
-        await handler(event, stream, this);
+        await handler(event, stream, scopedApp);
         at = event.id;
         handled++;
       } catch (error) {
@@ -1605,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.
    *
@@ -1772,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)
@@ -1802,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);
@@ -1818,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(() => {