@rotorsoft/act 0.14.0 → 0.16.0

package/dist/index.js

@@ -55,12 +55,12 @@ var ZodEmpty = z.record(z.string(), z.never());
 var ActorSchema = z.object({
   id: z.string(),
   name: z.string()
-}).readonly();
+}).loose().readonly();
 var TargetSchema = z.object({
   stream: z.string(),
   actor: ActorSchema,
   expectedVersion: z.number().optional()
-}).readonly();
+}).loose().readonly();
 var CausationEventSchema = z.object({
   id: z.number(),
   name: z.string(),
@@ -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);
   }
@@ -726,7 +729,7 @@ var Act = class {
    * 5. Applies events to create new state
    * 6. Commits events to the store with optimistic concurrency control
    *
-   * @template K - Action name from registered actions
+   * @template TKey - Action name from registered actions
    * @param action - The name of the action to execute
    * @param target - Target specification with stream ID and actor context
    * @param payload - Action payload matching the action's schema
@@ -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
@@ -1412,7 +1456,18 @@ function act(states = /* @__PURE__ */ new Map(), registry = {
     },
     withProjection: (proj) => {
       mergeProjection(proj, registry.events);
-      return act(states, registry, pendingProjections);
+      return act(
+        states,
+        registry,
+        pendingProjections
+      );
+    },
+    withActor: () => {
+      return act(
+        states,
+        registry,
+        pendingProjections
+      );
     },
     on: (event) => ({
       do: (handler, options) => {
@@ -1449,7 +1504,10 @@ function act(states = /* @__PURE__ */ new Map(), registry = {
       for (const proj of pendingProjections) {
         mergeProjection(proj, registry.events);
       }
-      return new Act(registry, states);
+      return new Act(
+        registry,
+        states
+      );
     },
     events: registry.events
   };
@@ -1531,7 +1589,12 @@ function slice(states = /* @__PURE__ */ new Map(), actions = {}, events = {}, pr
     },
     withProjection: (proj) => {
       projections.push(proj);
-      return slice(states, actions, events, projections);
+      return slice(
+        states,
+        actions,
+        events,
+        projections
+      );
     },
     on: (event) => ({
       do: (handler, options) => {
@@ -1627,7 +1690,10 @@ function action_builder(state2) {
       const schema = entry[action2];
       if (action2 in state2.actions)
         throw new Error(`Duplicate action "${action2}"`);
-      const actions = { ...state2.actions, [action2]: schema };
+      const actions = {
+        ...state2.actions,
+        [action2]: schema
+      };
       const on = { ...state2.on };
       const _given = { ...state2.given };
       function given(rules) {
@@ -1651,7 +1717,10 @@ function action_builder(state2) {
       return { given, emit };
     },
     snap(snap2) {
-      return action_builder({ ...state2, snap: snap2 });
+      return action_builder({
+        ...state2,
+        snap: snap2
+      });
     },
     build() {
       return state2;