@rotorsoft/act 0.42.0 → 0.44.0

package/dist/index.cjs

@@ -46,6 +46,7 @@ __export(index_exports, {
   InMemoryStore: () => InMemoryStore,
   InvariantError: () => InvariantError,
   LogLevels: () => LogLevels,
+  NonRetryableError: () => NonRetryableError,
   PackageSchema: () => PackageSchema,
   QuerySchema: () => QuerySchema,
   SNAP_EVENT: () => SNAP_EVENT,
@@ -286,7 +287,8 @@ var Errors = {
   ValidationError: "ERR_VALIDATION",
   InvariantError: "ERR_INVARIANT",
   ConcurrencyError: "ERR_CONCURRENCY",
-  StreamClosedError: "ERR_STREAM_CLOSED"
+  StreamClosedError: "ERR_STREAM_CLOSED",
+  NonRetryableError: "ERR_NON_RETRYABLE"
 };
 var ValidationError = class extends Error {
   constructor(target, payload, details) {
@@ -329,6 +331,15 @@ var StreamClosedError = class extends Error {
     this.name = Errors.StreamClosedError;
   }
 };
+var NonRetryableError = class extends Error {
+  /** The original failure, if any. Mirrors the standard `Error.cause` shape. */
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = Errors.NonRetryableError;
+    this.cause = options?.cause;
+  }
+};
 
 // src/utils.ts
 var import_zod3 = require("zod");
@@ -597,6 +608,20 @@ var InMemoryStream = class {
     this._leased_by = void 0;
     this._leased_until = void 0;
   }
+  /**
+   * Clear the blocked flag and lease bookkeeping without touching the
+   * watermark. Returns true if the stream was actually blocked (and is
+   * now flipped); false otherwise.
+   */
+  unblock() {
+    if (!this._blocked) return false;
+    this._blocked = false;
+    this._retry = -1;
+    this._error = "";
+    this._leased_by = void 0;
+    this._leased_until = void 0;
+    return true;
+  }
 };
 var InMemoryStore = class {
   // stored events
@@ -832,19 +857,81 @@ var InMemoryStore = class {
     return leases.map((l) => this._streams.get(l.stream)?.block(l, l.error)).filter((l) => !!l);
   }
   /**
-   * Reset watermarks for the given streams to -1, clearing retry, blocked,
-   * error, and lease state so they can be replayed from the beginning.
-   * @param streams - Stream names to reset.
+   * Build a predicate from a {@link StreamFilter}. Compiled regexes are
+   * cached in the closure so callers can apply it across the streams
+   * map without re-compiling per iteration.
+   */
+  _filterPredicate(filter) {
+    const streamRe = filter.stream && !filter.stream_exact ? new RegExp(filter.stream) : void 0;
+    const sourceRe = filter.source && !filter.source_exact ? new RegExp(filter.source) : void 0;
+    return (s) => {
+      if (filter.stream !== void 0) {
+        if (filter.stream_exact ? s.stream !== filter.stream : !streamRe.test(s.stream))
+          return false;
+      }
+      if (filter.source !== void 0) {
+        if (s.source === void 0) return false;
+        if (filter.source_exact ? s.source !== filter.source : !sourceRe.test(s.source))
+          return false;
+      }
+      if (filter.blocked !== void 0 && s.blocked !== filter.blocked)
+        return false;
+      return true;
+    };
+  }
+  /**
+   * Reset watermarks to -1, clearing retry, blocked, error, and lease
+   * state so the matched streams can be replayed from the beginning.
+   * Accepts either an explicit list of names or a {@link StreamFilter}.
+   *
+   * @param input - Stream names or a filter selecting the streams to reset.
    * @returns Count of streams that were actually reset.
    */
-  async reset(streams) {
+  async reset(input) {
     await sleep();
     let count = 0;
-    for (const name of streams) {
-      const s = this._streams.get(name);
-      if (s) {
-        s.reset();
-        count++;
+    if (Array.isArray(input)) {
+      for (const name of input) {
+        const s = this._streams.get(name);
+        if (s) {
+          s.reset();
+          count++;
+        }
+      }
+    } else {
+      const matches = this._filterPredicate(input);
+      for (const s of this._streams.values()) {
+        if (matches(s)) {
+          s.reset();
+          count++;
+        }
+      }
+    }
+    return count;
+  }
+  /**
+   * Clear the blocked flag (and retry / error / lease) on the matched
+   * streams without touching the watermark. Streams that aren't blocked
+   * at call time are silently skipped. Accepts either an explicit list
+   * of names or a {@link StreamFilter}. The filter form always restricts
+   * to blocked streams — passing `blocked: false` matches nothing.
+   * See {@link Store.unblock}.
+   *
+   * @param input - Stream names or a filter selecting the streams to unblock.
+   * @returns Count of streams that were actually flipped (were blocked).
+   */
+  async unblock(input) {
+    await sleep();
+    let count = 0;
+    if (Array.isArray(input)) {
+      for (const name of input) {
+        const s = this._streams.get(name);
+        if (s?.unblock()) count++;
+      }
+    } else {
+      const matches = this._filterPredicate({ ...input, blocked: true });
+      for (const s of this._streams.values()) {
+        if (matches(s) && s.unblock()) count++;
       }
     }
     return count;
@@ -860,21 +947,10 @@ var InMemoryStore = class {
    */
   async prioritize(filter, priority) {
     await sleep();
-    const streamRe = filter.stream && !filter.stream_exact ? new RegExp(filter.stream) : void 0;
-    const sourceRe = filter.source && !filter.source_exact ? new RegExp(filter.source) : void 0;
+    const matches = this._filterPredicate(filter);
     let count = 0;
     for (const s of this._streams.values()) {
-      if (filter.stream !== void 0) {
-        if (filter.stream_exact ? s.stream !== filter.stream : !streamRe.test(s.stream))
-          continue;
-      }
-      if (filter.source !== void 0) {
-        if (s.source === void 0) continue;
-        if (filter.source_exact ? s.source !== filter.source : !sourceRe.test(s.source))
-          continue;
-      }
-      if (filter.blocked !== void 0 && s.blocked !== filter.blocked)
-        continue;
+      if (!matches(s)) continue;
       if (s.priority !== priority) {
         s.setPriority(priority);
         count++;
@@ -926,6 +1002,77 @@ var InMemoryStore = class {
     }
     return { maxEventId: this._events.length - 1, count };
   }
+  /**
+   * Per-stream aggregated stats — see {@link Store.query_stats}.
+   *
+   * Single forward scan over the in-memory event list, accumulating per
+   * stream. The "cheap heads" cost tier from durable adapters doesn't
+   * apply here (InMemory has no indexes); correctness is the goal, perf
+   * is a non-issue.
+   *
+   * Scope rules:
+   * - Array `input` — explicit stream names, regardless of subscription.
+   * - Filter `input` — `stream`/`stream_exact` match against event-bearing
+   *   stream names; `source`/`source_exact`/`blocked` require a
+   *   corresponding subscription in `_streams` (those are subscription
+   *   concepts, not event concepts). Empty filter `{}` matches every
+   *   event-bearing stream.
+   */
+  async query_stats(input, options) {
+    await sleep();
+    const exclude = new Set(options?.exclude ?? []);
+    const wantTail = options?.tail ?? false;
+    const wantCount = options?.count ?? false;
+    const wantNames = options?.names ?? false;
+    const before = options?.before;
+    const arrayTargets = Array.isArray(input) ? new Set(input) : null;
+    const filter = Array.isArray(input) ? null : input;
+    const streamRe = filter?.stream && !filter.stream_exact ? new RegExp(filter.stream) : void 0;
+    const scopeCache = /* @__PURE__ */ new Map();
+    const inScope = (stream) => {
+      const cached = scopeCache.get(stream);
+      if (cached !== void 0) return cached;
+      let ok = true;
+      if (arrayTargets) {
+        ok = arrayTargets.has(stream);
+      } else if (filter?.stream !== void 0) {
+        ok = filter.stream_exact ? stream === filter.stream : (
+          // biome-ignore lint/style/noNonNullAssertion: streamRe set when stream is regex
+          streamRe.test(stream)
+        );
+      }
+      scopeCache.set(stream, ok);
+      return ok;
+    };
+    const acc = /* @__PURE__ */ new Map();
+    for (const e of this._events) {
+      if (before !== void 0 && e.id >= before) continue;
+      if (!inScope(e.stream)) continue;
+      if (exclude.has(e.name)) continue;
+      let a = acc.get(e.stream);
+      if (!a) {
+        a = { head: e, count: 0 };
+        if (wantTail) a.tail = e;
+        if (wantNames) a.names = {};
+        acc.set(e.stream, a);
+      }
+      a.head = e;
+      a.count++;
+      if (wantNames) {
+        const n = String(e.name);
+        a.names[n] = (a.names[n] ?? 0) + 1;
+      }
+    }
+    const out = /* @__PURE__ */ new Map();
+    for (const [stream, a] of acc) {
+      const stats = { head: a.head };
+      if (wantTail) stats.tail = a.tail;
+      if (wantCount) stats.count = a.count;
+      if (wantNames) stats.names = a.names;
+      out.set(stream, stats);
+    }
+    return out;
+  }
   /**
    * Atomically truncates streams and seeds each with a snapshot or tombstone.
    * @param targets - Streams to truncate with optional snapshot state and meta.
@@ -1127,24 +1274,18 @@ async function runCloseCycle(targets, deps) {
   return { truncated, skipped };
 }
 async function scanStreamHeads(streams) {
+  const stats = await store2().query_stats(streams, {
+    exclude: [SNAP_EVENT]
+  });
   const out = /* @__PURE__ */ new Map();
-  await Promise.all(
-    streams.map(async (s) => {
-      let maxId = -1;
-      let version = -1;
-      let lastEventName = "";
-      await store2().query(
-        (e) => {
-          if (e.name === TOMBSTONE_EVENT || maxId !== -1) return;
-          maxId = e.id;
-          version = e.version;
-          lastEventName = e.name;
-        },
-        { stream: s, stream_exact: true, backward: true, limit: 1 }
-      );
-      if (maxId >= 0) out.set(s, { maxId, version, lastEventName });
-    })
-  );
+  for (const [stream, { head }] of stats) {
+    if (head.name === TOMBSTONE_EVENT) continue;
+    out.set(stream, {
+      maxId: head.id,
+      version: head.version,
+      lastEventName: head.name
+    });
+  }
   return out;
 }
 async function partitionBySafety(streamInfo, reactiveEventsSize, skipped) {
@@ -1777,9 +1918,12 @@ function computeBackoffDelay(retry, opts) {
 function finalize(lease, handled, at, error, options, logger) {
   if (!error) return { lease, handled, at };
   logger.error(error);
-  const block2 = lease.retry >= options.maxRetries && options.blockOnError;
+  const nonRetryable = error instanceof NonRetryableError;
+  const block2 = options.blockOnError && (nonRetryable || lease.retry >= options.maxRetries);
   if (block2)
-    logger.error(`Blocking ${lease.stream} after ${lease.retry} retries.`);
+    logger.error(
+      nonRetryable ? `Blocking ${lease.stream} on non-retryable error.` : `Blocking ${lease.stream} after ${lease.retry} retries.`
+    );
   const nextAttemptAt = !block2 && options.backoff ? Date.now() + computeBackoffDelay(lease.retry, options.backoff) : void 0;
   return {
     lease,
@@ -2919,13 +3063,81 @@ var Act = class {
    * @see {@link Store.reset} for the underlying store primitive
    * @see {@link settle} for the debounced full-catch-up loop
    */
-  async reset(streams) {
+  async reset(input) {
+    return this._scoped(async () => {
+      const count = await store2().reset(input);
+      if (count > 0 && this._reactive_events.size > 0) this._drain.arm();
+      return count;
+    });
+  }
+  /**
+   * Clear the blocked flag on streams without replaying their history.
+   *
+   * Use this to recover from a poison message after fixing the
+   * underlying issue — the stream resumes from the next event after the
+   * last successful ack, not from the beginning. Compare with
+   * {@link reset}, which rebuilds from event 0 (suitable for projection
+   * rebuilds, wrong for "I fixed the bug, please retry").
+   *
+   * Wraps `store().unblock(streams)` and raises the orchestrator's
+   * internal "needs drain" flag so a settled app picks up the now-free
+   * streams on the next cycle. Equivalent to calling `store().unblock(...)`
+   * directly, but `store().unblock(...)` alone leaves the flag
+   * untouched.
+   *
+   * @param streams - Stream names to unblock
+   * @returns Count of streams that were actually flipped (were blocked)
+   *
+   * @example Recover from a 4xx webhook after fixing the bug
+   * ```typescript
+   * await app.unblock(["webhooks-out-customer-42"]);
+   * // The stream resumes from the next event, not from zero.
+   * ```
+   *
+   * @see {@link Store.unblock} for the underlying store primitive
+   * @see {@link reset} for the rebuild-from-zero alternative
+   */
+  async unblock(input) {
     return this._scoped(async () => {
-      const count = await store2().reset(streams);
+      const count = await store2().unblock(input);
       if (count > 0 && this._reactive_events.size > 0) this._drain.arm();
       return count;
     });
   }
+  /**
+   * Return every currently-blocked stream position. Convenience wrapper
+   * around `store().query_streams(cb, { blocked: true })` for the common
+   * "show me what's broken" operational query.
+   *
+   * Results are ordered by stream name, paginated by `limit` (default
+   * 100). Pass `after` to fetch the next page (keyset cursor on the
+   * stream name). For richer queries — including blocked + source
+   * filters, or full unblocked introspection — drop to
+   * `store().query_streams(...)` directly.
+   *
+   * @returns Array of {@link StreamPosition} for currently-blocked streams.
+   *
+   * @example Discover and recover
+   * ```typescript
+   * const blocked = await app.blocked_streams();
+   * console.table(blocked.map(({ stream, retry, error }) => ({ stream, retry, error })));
+   *
+   * // Operator investigates, then bulk-unblocks the family:
+   * await app.unblock({ stream: "^webhooks-out-" });
+   * ```
+   */
+  async blocked_streams(options) {
+    return this._scoped(async () => {
+      const positions = [];
+      await store2().query_streams(
+        (p) => {
+          positions.push(p);
+        },
+        { blocked: true, after: options?.after, limit: options?.limit }
+      );
+      return positions;
+    });
+  }
   /**
    * Bulk-update scheduling priority for streams matching `filter`.
    *
@@ -3382,6 +3594,7 @@ function action_builder(state2) {
   InMemoryStore,
   InvariantError,
   LogLevels,
+  NonRetryableError,
   PackageSchema,
   QuerySchema,
   SNAP_EVENT,