@rotorsoft/act 0.33.1 → 0.33.3

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   TargetSchema,
   ValidationError,
   ZodEmpty
-} from "./chunk-IDEYGKT4.js";
+} from "./chunk-AGWZY6YT.js";
 
 // src/adapters/console-logger.ts
 var LEVEL_VALUES = {
@@ -67,8 +67,10 @@ var ConsoleLogger = class _ConsoleLogger {
     this.debug = threshold <= 20 ? write.bind(this, "debug", 20) : noop;
     this.trace = threshold <= 10 ? write.bind(this, "trace", 10) : noop;
   }
+  /** No-op — `console.log` has no resources to release. */
   async dispose() {
   }
+  /** @inheritDoc */
   child(bindings) {
     return new _ConsoleLogger({
       level: this.level,
@@ -193,28 +195,34 @@ var InMemoryCache = class {
   constructor(options) {
     this._entries = new LruMap(options?.maxSize ?? 1e3);
   }
+  /** @inheritDoc */
   async get(stream) {
     return this._entries.get(stream);
   }
+  /** @inheritDoc */
   async set(stream, entry) {
     this._entries.set(stream, entry);
   }
+  /** @inheritDoc */
   async invalidate(stream) {
     this._entries.delete(stream);
   }
+  /** @inheritDoc */
   async clear() {
     this._entries.clear();
   }
+  /** @inheritDoc */
   async dispose() {
     this._entries.clear();
   }
+  /** Current number of entries held by the LRU. */
   get size() {
     return this._entries.size;
   }
 };
 
 // src/utils.ts
-import { ZodError, prettifyError } from "zod";
+import { prettifyError, ZodError } from "zod";
 
 // src/config.ts
 import * as fs from "fs";
@@ -738,7 +746,7 @@ var InMemoryStore = class {
 var ExitCodes = ["ERROR", "EXIT"];
 var adapters = /* @__PURE__ */ new Map();
 function port(injector) {
-  return function(adapter) {
+  return (adapter) => {
     if (!adapters.has(injector.name)) {
       const injected = injector(adapter);
       adapters.set(injector.name, injected);
@@ -1083,8 +1091,8 @@ var CorrelateCycle = class {
   }
   /**
    * Start a periodic correlation worker. Returns false if one is already
-   * running. Errors from `correlate()` are sent to `console.error` (matches
-   * pre-extraction behavior; the timer keeps running on failure).
+   * running. Errors from `correlate()` are routed through `log()` so they
+   * land in the configured logger (the timer keeps running on failure).
    */
   startPolling(query = {}, frequency = 1e4, callback) {
     if (this._timer) return false;
@@ -1092,7 +1100,7 @@ var CorrelateCycle = class {
     this._timer = setInterval(
       () => this.correlate({ ...query, after: this._checkpoint, limit }).then((result) => {
         if (callback && result.subscribed) callback(result.subscribed);
-      }).catch(console.error),
+      }).catch((err) => log().error(err)),
       frequency
     );
     return true;
@@ -1530,8 +1538,8 @@ var block = (leases) => store().block(leases);
 var subscribe = (streams) => store().subscribe(streams);
 
 // src/internal/event-sourcing.ts
-import { patch } from "@rotorsoft/act-patch";
 import { randomUUID as randomUUID3 } from "crypto";
+import { patch } from "@rotorsoft/act-patch";
 async function snap(snapshot) {
   try {
     const { id, stream, name, meta, version } = snapshot.event;
@@ -1591,7 +1599,7 @@ async function load(me, stream, callback, asOf) {
           `Skipping unknown event "${String(e.name)}" on stream "${stream}" (id=${e.id}) \u2014 no reducer in state "${me.name}"`
         );
       }
-      callback && callback({
+      callback?.({
         event,
         state: state2,
         version,
@@ -1621,7 +1629,7 @@ async function load(me, stream, callback, asOf) {
 async function action(me, action2, target, payload, reactingTo, skipValidation = false) {
   const { stream, expectedVersion, actor } = target;
   if (!stream) throw new Error("Missing target stream");
-  payload = skipValidation ? payload : validate(action2, payload, me.actions[action2]);
+  const validated = skipValidation ? payload : validate(action2, payload, me.actions[action2]);
   const snapshot = await load(me, stream);
   if (snapshot.event?.name === TOMBSTONE_EVENT)
     throw new StreamClosedError(stream);
@@ -1632,14 +1640,14 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
       if (!valid(snapshot.state, actor))
         throw new InvariantError(
           action2,
-          payload,
+          validated,
           target,
           snapshot,
           description
         );
     });
   }
-  const result = me.on[action2](payload, snapshot, target);
+  const result = me.on[action2](validated, snapshot, target);
   if (!result) return [snapshot];
   if (Array.isArray(result) && result.length === 0) {
     return [snapshot];
@@ -1700,7 +1708,7 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
     };
   });
   const last = snapshots.at(-1);
-  const snapped = me.snap && me.snap(last);
+  const snapped = me.snap?.(last);
   cache().set(stream, {
     state: last.state,
     version: last.event.version,
@@ -1881,6 +1889,17 @@ function buildDrain(logger) {
 var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
 var DEFAULT_SETTLE_DEBOUNCE_MS = 10;
 var Act = class {
+  /**
+   * Create a new Act orchestrator. Prefer the {@link act} builder over
+   * direct construction — `act()...build()` wires the registry, merges
+   * partial states, and collects batch handlers from registered slices
+   * and projections in one pass.
+   *
+   * @param registry  Schemas for every event and action across registered states
+   * @param _states   Merged map of state name → state definition
+   * @param batchHandlers Static-target projection batch handlers (target → handler)
+   * @param options   Tuning knobs — see {@link ActOptions}
+   */
   constructor(registry, _states = /* @__PURE__ */ new Map(), batchHandlers = /* @__PURE__ */ new Map(), options = {}) {
     this.registry = registry;
     this._states = _states;
@@ -1968,12 +1987,6 @@ var Act = class {
     this._emitter.off(event, listener);
     return this;
   }
-  /**
-   * Create a new Act orchestrator.
-   *
-   * @param registry The registry of state, event, and action schemas
-   * @param states Map of state names to their (potentially merged) state definitions
-   */
   /** Batch handlers for static-target projections (target → handler) */
   _batch_handlers;
   /** Event-sourcing handlers, optionally wrapped with trace decorators */
@@ -2119,14 +2132,9 @@ var Act = class {
    *
    * For small result sets, consider using {@link query_array} instead.
    *
-   * @param query - The query filter
-   * @param query.stream - Filter by stream ID
-   * @param query.name - Filter by event name
-   * @param query.after - Filter events after this event ID
-   * @param query.before - Filter events before this event ID
-   * @param query.created_after - Filter events after this timestamp
-   * @param query.created_before - Filter events before this timestamp
-   * @param query.limit - Maximum number of events to return
+   * @param query - Filter criteria — see {@link Query} for available fields
+   *   (`stream`, `name`, `after`, `before`, `created_after`, `created_before`,
+   *   `limit`, `with_snaps`, `stream_exact`)
    * @param callback - Optional callback invoked for each matching event
    * @returns Object with first event, last event, and total count
    *
@@ -2162,11 +2170,12 @@ var Act = class {
    * @see {@link query_array} for loading events into memory
    */
   async query(query, callback) {
-    let first = void 0, last = void 0;
+    let first;
+    let last;
     const count = await store().query((e) => {
-      !first && (first = e);
+      if (!first) first = e;
       last = e;
-      callback && callback(e);
+      callback?.(e);
     }, query);
     return { first, last, count };
   }
@@ -2217,10 +2226,8 @@ var Act = class {
    * 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)
-   * @param options.eventLimit - Maximum events to fetch per stream (default: 10)
-   * @param options.leaseMillis - Lease duration in milliseconds (default: 10000)
+   * @param options - Drain configuration — see {@link DrainOptions} for fields
+   *   (`streamLimit`, `eventLimit`, `leaseMillis`).
    * @returns Drain statistics with fetched, leased, acked, and blocked counts
    *
    * @example In tests and scripts
@@ -2255,8 +2262,8 @@ var Act = class {
    * the next drain cycle.
    *
    * @param query - Query filter to scan for new correlations
-   * @param query.after - Start scanning after this event ID (default: -1)
-   * @param query.limit - Maximum events to scan (default: 10)
+   * @param query - Scan filter — see {@link Query} for fields (typically
+   *   `{ after: <event-id>, limit: <count> }`)
    * @returns Object with newly leased streams and last scanned event ID
    *
    * @example Manual correlation
@@ -2303,9 +2310,8 @@ var Act = class {
    *
    * **Note:** Only one correlation worker can run at a time per Act instance.
    *
-   * @param query - Query filter for correlation scans
-   * @param query.after - Initial starting point (default: -1, start from beginning)
-   * @param query.limit - Events to scan per cycle (default: 100)
+   * @param query - Query filter for correlation scans — see {@link Query}
+   *   (typically `{ after: -1, limit: 100 }`)
    * @param frequency - Correlation frequency in milliseconds (default: 10000)
    * @param callback - Optional callback invoked with newly discovered streams
    * @returns `true` if worker started, `false` if already running
@@ -2472,14 +2478,11 @@ var Act = class {
    * 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 - 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)
+   * @param options - Settle configuration — see {@link SettleOptions} for fields:
+   *   `debounceMs` (default 10), `correlate` (default `{ after: -1, limit: 100 }`),
+   *   `maxPasses` (default `Infinity` — kill-switch for runaway loops),
+   *   `streamLimit` (default 10), `eventLimit` (default 10),
+   *   `leaseMillis` (default 10000).
    *
    * @example API mutations
    * ```typescript
@@ -2742,7 +2745,8 @@ function action_builder(state2) {
         throw new Error(`Duplicate action "${action2}"`);
       internal.actions[action2] = schema;
       function given(rules) {
-        (internal.given ??= {})[action2] = rules;
+        internal.given ??= {};
+        internal.given[action2] = rules;
         return { emit };
       }
       function emit(handler) {