@rotorsoft/act 0.15.0 → 0.16.0

package/dist/@types/act.d.ts

@@ -1,4 +1,4 @@
-import type { Actor, Committed, Drain, DrainOptions, Lease, Query, Registry, Schema, SchemaRegister, Schemas, Snapshot, State, Target } from "./types/index.js";
+import type { Actor, Committed, Drain, DrainOptions, Lease, Query, Registry, Schema, SchemaRegister, Schemas, SettleOptions, Snapshot, State, Target } from "./types/index.js";
 /**
  * @category Orchestrator
  * @see Store
@@ -31,7 +31,9 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
     private _emitter;
     private _drain_locked;
     private _drain_lag2lead_ratio;
-    private _correlation_interval;
+    private _correlation_timer;
+    private _settle_timer;
+    private _settling;
     /**
      * Emit a lifecycle event (internal use, but can be used for custom listeners).
      *
@@ -44,6 +46,7 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
     emit(event: "blocked", args: Array<Lease & {
         error: string;
     }>): boolean;
+    emit(event: "settled", args: Drain<TEvents>): boolean;
     /**
      * Register a listener for a lifecycle event ("committed", "acked", or "blocked").
      *
@@ -56,6 +59,7 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
     on(event: "blocked", listener: (args: Array<Lease & {
         error: string;
     }>) => void): this;
+    on(event: "settled", listener: (args: Drain<TEvents>) => void): this;
     /**
      * Remove a listener for a lifecycle event.
      *
@@ -68,6 +72,7 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
     off(event: "blocked", listener: (args: Array<Lease & {
         error: string;
     }>) => void): this;
+    off(event: "settled", listener: (args: Drain<TEvents>) => void): this;
     /**
      * Create a new Act orchestrator.
      *
@@ -300,7 +305,7 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
     /**
      * 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
@@ -310,7 +315,8 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      * 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)
@@ -318,46 +324,20 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      * @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
-     * ```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
+     * @example In production, prefer settle()
      * ```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
      */
@@ -485,5 +465,41 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      * @see {@link start_correlations}
      */
     stop_correlations(): void;
+    /**
+     * Cancels any pending or active settle cycle.
+     *
+     * @see {@link settle}
+     */
+    stop_settling(): void;
+    /**
+     * 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?: SettleOptions): void;
 }
 //# sourceMappingURL=act.d.ts.map

package/dist/@types/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/act.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,KAAK,EACL,SAAS,EACT,KAAK,EACL,YAAY,EACZ,KAAK,EACL,KAAK,EAEL,QAAQ,EACR,MAAM,EACN,cAAc,EACd,OAAO,EACP,QAAQ,EACR,KAAK,EACL,MAAM,EACP,MAAM,kBAAkB,CAAC;AAI1B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,GAAG,CACd,UAAU,SAAS,cAAc,CAAC,QAAQ,CAAC,EAC3C,OAAO,SAAS,OAAO,EACvB,QAAQ,SAAS,OAAO,EACxB,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAChE,MAAM,SAAS,KAAK,GAAG,KAAK;aAsEV,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO;IArE1B,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,qBAAqB,CAAO;IACpC,OAAO,CAAC,qBAAqB,CAAyC;IAEtE;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,GAAG,OAAO;IACxE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO;IAC5C,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO;IAKvE;;;;;;OAMG;IACH,EAAE,CACA,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,KAAK,IAAI,GACxD,IAAI;IACP,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI;IAC3D,EAAE,CACA,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,KAAK,IAAI,GACzD,IAAI;IAMP;;;;;;OAMG;IACH,GAAG,CACD,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,KAAK,IAAI,GACxD,IAAI;IACP,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI;IAC5D,GAAG,CACD,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,KAAK,IAAI,GACzD,IAAI;IAMP;;;;;OAKG;gBAEe,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,EAChD,OAAO,GAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAa;IASzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkFG;IACG,EAAE,CAAC,IAAI,SAAS,MAAM,QAAQ,EAClC,MAAM,EAAE,IAAI,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EACtB,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EACjC,UAAU,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC,EACvD,cAAc,UAAQ;IAcxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACG,IAAI,CACR,SAAS,SAAS,MAAM,EACxB,UAAU,SAAS,OAAO,EAC1B,WAAW,SAAS,OAAO,EAE3B,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,EAChD,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,KAAK,IAAI,GAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI,SAAS,MAAM,SAAS,GAAG,MAAM,EAC9C,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,KAAK,IAAI,GAChE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;IAiB9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACG,KAAK,CACT,KAAK,EAAE,KAAK,EACZ,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,KAAK,IAAI,GAC5D,OAAO,CAAC;QACT,KAAK,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC;QACzC,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IAWF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,WAAW,CACf,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,EAAE,CAAC;IAM/C;;;;;;;;;;OAUG;YACW,MAAM;IA4CpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACG,KAAK,CAAC,EACV,WAAgB,EAChB,UAAe,EACf,WAAoB,GACrB,GAAE,YAAiB,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAmH9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACG,SAAS,CACb,KAAK,GAAE,KAAgC,GACtC,OAAO,CAAC;QAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAwChD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsDG;IACH,kBAAkB,CAChB,KAAK,GAAE,KAAU,EACjB,SAAS,SAAS,EAClB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,GACnC,OAAO;IAkBV;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB;CAMlB"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/act.ts"],"names":[],"mappings":"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"}

package/dist/@types/types/reaction.d.ts

@@ -4,7 +4,7 @@
  * @category Types
  * Types for reactions, leases, and fetch results in the Act Framework.
  */
-import type { Actor, Committed, Dispatcher, Schema, Schemas, Snapshot } from "./action.js";
+import type { Actor, Committed, Dispatcher, Query, Schema, Schemas, Snapshot } from "./action.js";
 /**
  * Reaction handler function that processes committed events.
  *
@@ -228,4 +228,20 @@ export type Drain<TEvents extends Schemas> = {
         readonly error: string;
     }>;
 };
+/**
+ * Options for the debounced settle cycle.
+ *
+ * Extends {@link DrainOptions} with parameters that control the debounce
+ * window, the correlation query, and the maximum number of correlate→drain
+ * passes.
+ *
+ * @property debounceMs - Debounce window in milliseconds (default: 10)
+ * @property correlate - Query filter for correlation scans (default: `{ after: -1, limit: 100 }`)
+ * @property maxPasses - Maximum correlate→drain loops (default: 5)
+ */
+export type SettleOptions = DrainOptions & {
+    readonly debounceMs?: number;
+    readonly correlate?: Query;
+    readonly maxPasses?: number;
+};
 //# sourceMappingURL=reaction.d.ts.map

package/dist/@types/types/reaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reaction.d.ts","sourceRoot":"","sources":["../../../src/types/reaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reaction.d.ts","sourceRoot":"","sources":["../../../src/types/reaction.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -764,13 +764,16 @@ var Act = class {
     dispose(() => {
       this._emitter.removeAllListeners();
       this.stop_correlations();
+      this.stop_settling();
       return Promise.resolve();
     });
   }
   _emitter = new import_events.default();
   _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);
   }
@@ -1020,7 +1023,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
@@ -1030,7 +1033,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)
@@ -1038,46 +1042,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
    */
@@ -1306,10 +1284,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);
@@ -1336,11 +1314,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