@rotorsoft/act 1.17.0 → 1.18.0

package/dist/index.cjs

@@ -43,6 +43,7 @@ __export(index_exports, {
   DEFAULT_LANE: () => DEFAULT_LANE,
   DEFAULT_MAX_SUBSCRIBED_STREAMS: () => DEFAULT_MAX_SUBSCRIBED_STREAMS,
   DEFAULT_SETTLE_DEBOUNCE_MS: () => DEFAULT_SETTLE_DEBOUNCE_MS,
+  DeferSignal: () => DeferSignal,
   Environments: () => Environments,
   Errors: () => Errors,
   EventMetaSchema: () => EventMetaSchema,
@@ -2130,13 +2131,258 @@ function classify_registry(registry, states) {
   };
 }
 
-// src/internal/circuit-breaker.ts
+// src/internal/defer-config.ts
 var import_zod7 = require("zod");
+
+// src/internal/defer-signal.ts
+var DeferSignal = class extends Error {
+  /**
+   * The unresolved schedule. The dispatcher turns this into an absolute
+   * due-time by resolving it against the triggering event.
+   */
+  when;
+  constructor(when) {
+    super("reaction deferred");
+    this.name = "DeferSignal";
+    this.when = when;
+  }
+};
+
+// src/internal/defer-config.ts
+var DeferDurationSchema = import_zod7.z.object({
+  days: import_zod7.z.number().positive().optional(),
+  hours: import_zod7.z.number().positive().optional(),
+  minutes: import_zod7.z.number().positive().optional()
+}).strict().refine((d) => d.days != null || d.hours != null || d.minutes != null, {
+  message: "defer: a duration needs at least one of days, hours, or minutes"
+});
+var DeferWhenSchema = import_zod7.z.object({
+  after: DeferDurationSchema.optional(),
+  at: import_zod7.z.date().optional()
+}).strict().refine((w) => w.after === void 0 !== (w.at === void 0), {
+  message: "defer: specify exactly one of `after` or `at`"
+});
+function duration_ms(d) {
+  return (d.days ?? 0) * 864e5 + (d.hours ?? 0) * 36e5 + (d.minutes ?? 0) * 6e4;
+}
+function resolve_defer_at(when, event) {
+  const parsed = DeferWhenSchema.parse(when);
+  if (parsed.after) return event.created.getTime() + duration_ms(parsed.after);
+  return parsed.at.getTime();
+}
+function assert_defer_when(when) {
+  DeferWhenSchema.parse(when);
+}
+function make_deferred(handler, schedule) {
+  const call = handler;
+  const deferred = async (event, stream, app) => {
+    const when = typeof schedule === "function" ? schedule(event) : schedule;
+    if (Date.now() < resolve_defer_at(when, event)) throw new DeferSignal(when);
+    return call(event, stream, app);
+  };
+  Object.defineProperty(deferred, "name", { value: handler.name });
+  return deferred;
+}
+
+// src/internal/merge.ts
+var import_zod8 = require("zod");
+function base_type_name(zodType) {
+  let t = zodType;
+  while (typeof t.unwrap === "function") {
+    t = t.unwrap();
+  }
+  return t.constructor.name;
+}
+function merge_schemas(existing, incoming, state_name) {
+  if (existing instanceof import_zod8.ZodObject && incoming instanceof import_zod8.ZodObject) {
+    const existing_shape = existing.shape;
+    const incoming_shape = incoming.shape;
+    for (const key of Object.keys(incoming_shape)) {
+      if (key in existing_shape) {
+        const existing_base = base_type_name(existing_shape[key]);
+        const incoming_base = base_type_name(incoming_shape[key]);
+        if (existing_base !== incoming_base) {
+          throw new Error(
+            `Schema conflict in "${state_name}": key "${key}" has type "${existing_base}" but incoming partial declares "${incoming_base}"`
+          );
+        }
+      }
+    }
+    return existing.extend(incoming_shape);
+  }
+  return existing;
+}
+function merge_inits(existing, incoming) {
+  return () => ({ ...existing(), ...incoming() });
+}
+function register_state(state2, states, actions, events) {
+  const existing = states.get(state2.name);
+  if (existing) {
+    merge_into_existing(state2, existing, states, actions, events);
+  } else {
+    register_new_state(state2, states, actions, events);
+  }
+}
+function register_new_state(state2, states, actions, events) {
+  states.set(state2.name, state2);
+  for (const name of Object.keys(state2.actions)) {
+    if (actions[name]) throw new Error(`Duplicate action "${name}"`);
+    actions[name] = state2;
+  }
+  for (const name of Object.keys(state2.events)) {
+    if (events[name]) throw new Error(`Duplicate event "${name}"`);
+    events[name] = { schema: state2.events[name], reactions: /* @__PURE__ */ new Map() };
+  }
+}
+function merge_into_existing(state2, existing, states, actions, events) {
+  for (const name of Object.keys(state2.actions)) {
+    if (existing.actions[name] === state2.actions[name]) continue;
+    if (actions[name]) throw new Error(`Duplicate action "${name}"`);
+  }
+  for (const name of Object.keys(state2.events)) {
+    if (existing.events[name] === state2.events[name]) continue;
+    if (existing.events[name]) {
+      throw new Error(
+        `Event "${name}" in state "${state2.name}" is declared with different Zod schemas across slices. Cross-slice event schemas must reference the same instance \u2014 extract a shared schema (e.g. \`export const ${name} = z.object({ ... })\` in a shared module) and import it in every slice that declares it.`
+      );
+    }
+    if (events[name]) throw new Error(`Duplicate event "${name}"`);
+  }
+  const merged_patch = merge_patches(existing.patch, state2.patch, state2.name);
+  const merged = {
+    ...existing,
+    state: merge_schemas(existing.state, state2.state, state2.name),
+    init: merge_inits(existing.init, state2.init),
+    events: { ...existing.events, ...state2.events },
+    actions: { ...existing.actions, ...state2.actions },
+    patch: merged_patch,
+    on: { ...existing.on, ...state2.on },
+    given: { ...existing.given, ...state2.given },
+    snap: state2.snap && existing.snap && state2.snap !== existing.snap ? (() => {
+      throw new Error(
+        `Duplicate snap strategy for state "${state2.name}"`
+      );
+    })() : state2.snap || existing.snap
+  };
+  states.set(state2.name, merged);
+  for (const name of Object.keys(merged.actions)) {
+    actions[name] = merged;
+  }
+  for (const name of Object.keys(state2.events)) {
+    if (events[name]) continue;
+    events[name] = { schema: state2.events[name], reactions: /* @__PURE__ */ new Map() };
+  }
+}
+function merge_patches(existing, incoming, state_name) {
+  const merged = { ...existing };
+  for (const name of Object.keys(incoming)) {
+    const existing_p = existing[name];
+    const incoming_p = incoming[name];
+    if (!existing_p) {
+      merged[name] = incoming_p;
+      continue;
+    }
+    const existing_is_default = existing_p._passthrough;
+    const incoming_is_default = incoming_p._passthrough;
+    if (!existing_is_default && !incoming_is_default && existing_p !== incoming_p) {
+      throw new Error(
+        `Duplicate custom patch for event "${name}" in state "${state_name}"`
+      );
+    }
+    if (existing_is_default && !incoming_is_default) {
+      merged[name] = incoming_p;
+    }
+  }
+  return merged;
+}
+function merge_event_register(target, source) {
+  for (const [event_name, source_reg] of Object.entries(source)) {
+    const target_reg = target[event_name];
+    if (!target_reg) continue;
+    for (const [name, reaction] of source_reg.reactions) {
+      const existing = target_reg.reactions.get(name);
+      if (existing !== void 0 && existing !== reaction)
+        throw new Error(
+          `Duplicate reaction "${name}" for event "${event_name}". Reaction handlers are keyed by function name; rename one of them.`
+        );
+      target_reg.reactions.set(name, reaction);
+    }
+  }
+}
+function merge_projection(proj, events) {
+  for (const event_name of Object.keys(proj.events)) {
+    const proj_register = proj.events[event_name];
+    const existing = events[event_name];
+    if (!existing) {
+      events[event_name] = {
+        schema: proj_register.schema,
+        reactions: new Map(proj_register.reactions)
+      };
+    } else {
+      for (const [name, reaction] of proj_register.reactions) {
+        let key = name;
+        while (existing.reactions.has(key)) key = `${key}_p`;
+        existing.reactions.set(key, reaction);
+      }
+    }
+  }
+}
+var _this_ = ({ stream }) => ({
+  source: stream,
+  target: stream
+});
+
+// src/internal/builder-utils.ts
+function register_lane(config2, lanes) {
+  if (config2.name === DEFAULT_LANE)
+    throw new Error(`Lane "${DEFAULT_LANE}" is reserved`);
+  if (lanes.some((l) => l.name === config2.name))
+    throw new Error(`Lane "${config2.name}" was already declared`);
+  lanes.push(config2);
+}
+function reaction_on(event, events, builder) {
+  const register = (handler, options, schedule) => {
+    if (!handler.name)
+      throw new Error(
+        `Reaction handler for "${String(event)}" must be a named function`
+      );
+    if (events[event].reactions.has(handler.name))
+      throw new Error(
+        `Duplicate reaction "${handler.name}" for event "${String(event)}". Reaction handlers are keyed by function name; rename one of them.`
+      );
+    if (schedule && typeof schedule !== "function") assert_defer_when(schedule);
+    const reaction = {
+      handler: schedule ? make_deferred(handler, schedule) : handler,
+      resolver: _this_,
+      options: {
+        blockOnError: options?.blockOnError ?? true,
+        maxRetries: options?.maxRetries ?? 3,
+        backoff: options?.backoff
+      }
+    };
+    events[event].reactions.set(handler.name, reaction);
+    return Object.assign(builder, {
+      to(resolver) {
+        reaction.resolver = typeof resolver === "string" ? { target: resolver } : resolver;
+        return builder;
+      }
+    });
+  };
+  return {
+    do: (handler, options) => register(handler, options),
+    defer: (schedule) => ({
+      do: (handler, options) => register(handler, options, schedule)
+    })
+  };
+}
+
+// src/internal/circuit-breaker.ts
+var import_zod9 = require("zod");
 var DEFAULT_CIRCUIT_FAILURE_THRESHOLD = 5;
 var DEFAULT_CIRCUIT_COOLDOWN_MS = 3e4;
-var CircuitBreakerOptionsSchema = import_zod7.z.object({
-  failureThreshold: import_zod7.z.number().int().min(1).default(DEFAULT_CIRCUIT_FAILURE_THRESHOLD),
-  cooldownMs: import_zod7.z.number().int().min(100).max(36e5).default(DEFAULT_CIRCUIT_COOLDOWN_MS)
+var CircuitBreakerOptionsSchema = import_zod9.z.object({
+  failureThreshold: import_zod9.z.number().int().min(1).default(DEFAULT_CIRCUIT_FAILURE_THRESHOLD),
+  cooldownMs: import_zod9.z.number().int().min(100).max(36e5).default(DEFAULT_CIRCUIT_COOLDOWN_MS)
 });
 var resolveCircuitBreakerConfig = (options) => CircuitBreakerOptionsSchema.parse(options ?? {});
 var CircuitBreaker = class {
@@ -2566,17 +2812,6 @@ function close_correlation(correlator, actor) {
   });
 }
 
-// src/internal/defer-signal.ts
-var DeferSignal = class extends Error {
-  /** Wall-clock time (ms since epoch) to re-visit the stream. */
-  defer_at;
-  constructor(defer_at) {
-    super("reaction deferred");
-    this.name = "DeferSignal";
-    this.defer_at = defer_at;
-  }
-};
-
 // src/internal/drain-cycle.ts
 var import_node_crypto2 = require("crypto");
 
@@ -3423,154 +3658,6 @@ var DrainController = class {
   }
 };
 
-// src/internal/merge.ts
-var import_zod8 = require("zod");
-function base_type_name(zodType) {
-  let t = zodType;
-  while (typeof t.unwrap === "function") {
-    t = t.unwrap();
-  }
-  return t.constructor.name;
-}
-function merge_schemas(existing, incoming, state_name) {
-  if (existing instanceof import_zod8.ZodObject && incoming instanceof import_zod8.ZodObject) {
-    const existing_shape = existing.shape;
-    const incoming_shape = incoming.shape;
-    for (const key of Object.keys(incoming_shape)) {
-      if (key in existing_shape) {
-        const existing_base = base_type_name(existing_shape[key]);
-        const incoming_base = base_type_name(incoming_shape[key]);
-        if (existing_base !== incoming_base) {
-          throw new Error(
-            `Schema conflict in "${state_name}": key "${key}" has type "${existing_base}" but incoming partial declares "${incoming_base}"`
-          );
-        }
-      }
-    }
-    return existing.extend(incoming_shape);
-  }
-  return existing;
-}
-function merge_inits(existing, incoming) {
-  return () => ({ ...existing(), ...incoming() });
-}
-function register_state(state2, states, actions, events) {
-  const existing = states.get(state2.name);
-  if (existing) {
-    merge_into_existing(state2, existing, states, actions, events);
-  } else {
-    register_new_state(state2, states, actions, events);
-  }
-}
-function register_new_state(state2, states, actions, events) {
-  states.set(state2.name, state2);
-  for (const name of Object.keys(state2.actions)) {
-    if (actions[name]) throw new Error(`Duplicate action "${name}"`);
-    actions[name] = state2;
-  }
-  for (const name of Object.keys(state2.events)) {
-    if (events[name]) throw new Error(`Duplicate event "${name}"`);
-    events[name] = { schema: state2.events[name], reactions: /* @__PURE__ */ new Map() };
-  }
-}
-function merge_into_existing(state2, existing, states, actions, events) {
-  for (const name of Object.keys(state2.actions)) {
-    if (existing.actions[name] === state2.actions[name]) continue;
-    if (actions[name]) throw new Error(`Duplicate action "${name}"`);
-  }
-  for (const name of Object.keys(state2.events)) {
-    if (existing.events[name] === state2.events[name]) continue;
-    if (existing.events[name]) {
-      throw new Error(
-        `Event "${name}" in state "${state2.name}" is declared with different Zod schemas across slices. Cross-slice event schemas must reference the same instance \u2014 extract a shared schema (e.g. \`export const ${name} = z.object({ ... })\` in a shared module) and import it in every slice that declares it.`
-      );
-    }
-    if (events[name]) throw new Error(`Duplicate event "${name}"`);
-  }
-  const merged_patch = merge_patches(existing.patch, state2.patch, state2.name);
-  const merged = {
-    ...existing,
-    state: merge_schemas(existing.state, state2.state, state2.name),
-    init: merge_inits(existing.init, state2.init),
-    events: { ...existing.events, ...state2.events },
-    actions: { ...existing.actions, ...state2.actions },
-    patch: merged_patch,
-    on: { ...existing.on, ...state2.on },
-    given: { ...existing.given, ...state2.given },
-    snap: state2.snap && existing.snap && state2.snap !== existing.snap ? (() => {
-      throw new Error(
-        `Duplicate snap strategy for state "${state2.name}"`
-      );
-    })() : state2.snap || existing.snap
-  };
-  states.set(state2.name, merged);
-  for (const name of Object.keys(merged.actions)) {
-    actions[name] = merged;
-  }
-  for (const name of Object.keys(state2.events)) {
-    if (events[name]) continue;
-    events[name] = { schema: state2.events[name], reactions: /* @__PURE__ */ new Map() };
-  }
-}
-function merge_patches(existing, incoming, state_name) {
-  const merged = { ...existing };
-  for (const name of Object.keys(incoming)) {
-    const existing_p = existing[name];
-    const incoming_p = incoming[name];
-    if (!existing_p) {
-      merged[name] = incoming_p;
-      continue;
-    }
-    const existing_is_default = existing_p._passthrough;
-    const incoming_is_default = incoming_p._passthrough;
-    if (!existing_is_default && !incoming_is_default && existing_p !== incoming_p) {
-      throw new Error(
-        `Duplicate custom patch for event "${name}" in state "${state_name}"`
-      );
-    }
-    if (existing_is_default && !incoming_is_default) {
-      merged[name] = incoming_p;
-    }
-  }
-  return merged;
-}
-function merge_event_register(target, source) {
-  for (const [event_name, source_reg] of Object.entries(source)) {
-    const target_reg = target[event_name];
-    if (!target_reg) continue;
-    for (const [name, reaction] of source_reg.reactions) {
-      const existing = target_reg.reactions.get(name);
-      if (existing !== void 0 && existing !== reaction)
-        throw new Error(
-          `Duplicate reaction "${name}" for event "${event_name}". Reaction handlers are keyed by function name; rename one of them.`
-        );
-      target_reg.reactions.set(name, reaction);
-    }
-  }
-}
-function merge_projection(proj, events) {
-  for (const event_name of Object.keys(proj.events)) {
-    const proj_register = proj.events[event_name];
-    const existing = events[event_name];
-    if (!existing) {
-      events[event_name] = {
-        schema: proj_register.schema,
-        reactions: new Map(proj_register.reactions)
-      };
-    } else {
-      for (const [name, reaction] of proj_register.reactions) {
-        let key = name;
-        while (existing.reactions.has(key)) key = `${key}_p`;
-        existing.reactions.set(key, reaction);
-      }
-    }
-  }
-}
-var _this_ = ({ stream }) => ({
-  source: stream,
-  target: stream
-});
-
 // src/internal/reactions.ts
 function finalize(lease, handled, at, error, options, logger, failed_at) {
   if (!error) return { lease, handled, acked_at: at };
@@ -3627,7 +3714,12 @@ function build_handle(deps) {
         handled++;
       } catch (error) {
         if (error instanceof DeferSignal)
-          return { lease, handled, acked_at: at, defer: error.defer_at };
+          return {
+            lease,
+            handled,
+            acked_at: at,
+            defer: resolve_defer_at(error.when, event)
+          };
         if (error instanceof CloseSignal)
           return {
             lease,
@@ -3947,9 +4039,9 @@ var Act = class {
           const aggregate = event.stream;
           const config2 = this._autoclose_config;
           if (!in_autoclose_window(config2.autocloseWindow, /* @__PURE__ */ new Date()))
-            throw new DeferSignal(
-              Date.now() + config2.autocloseCycleMinutes * 6e4
-            );
+            throw new DeferSignal({
+              at: new Date(Date.now() + config2.autocloseCycleMinutes * 6e4)
+            });
           const stats = await store2().query_stats([aggregate], {
             count: true,
             exclude: [TOMBSTONE_EVENT]
@@ -3967,7 +4059,9 @@ var Act = class {
               at: head.id
             });
           if (after_ms !== void 0)
-            throw new DeferSignal(head.created.getTime() + after_ms);
+            throw new DeferSignal({
+              at: new Date(head.created.getTime() + after_ms)
+            });
         }
       };
       const key = `__autoclose_${st.name}`;
@@ -5068,41 +5162,10 @@ function act() {
     },
     withActor: () => builder,
     withLane: (config2) => {
-      if (config2.name === DEFAULT_LANE)
-        throw new Error(`Lane "${DEFAULT_LANE}" is reserved`);
-      if (lanes.some((l) => l.name === config2.name))
-        throw new Error(`Lane "${config2.name}" was already declared`);
-      lanes.push(config2);
+      register_lane(config2, lanes);
       return builder;
     },
-    on: (event) => ({
-      do: (handler, options) => {
-        const reaction = {
-          handler,
-          resolver: _this_,
-          options: {
-            blockOnError: options?.blockOnError ?? true,
-            maxRetries: options?.maxRetries ?? 3,
-            backoff: options?.backoff
-          }
-        };
-        if (!handler.name)
-          throw new Error(
-            `Reaction handler for "${String(event)}" must be a named function`
-          );
-        if (registry.events[event].reactions.has(handler.name))
-          throw new Error(
-            `Duplicate reaction "${handler.name}" for event "${String(event)}". Reaction handlers are keyed by function name; rename one of them.`
-          );
-        registry.events[event].reactions.set(handler.name, reaction);
-        return Object.assign(builder, {
-          to(resolver) {
-            reaction.resolver = typeof resolver === "string" ? { target: resolver } : resolver;
-            return builder;
-          }
-        });
-      }
-    }),
+    on: (event) => reaction_on(event, registry.events, builder),
     build: (options) => {
       if (!_built) {
         for (const proj of pending_projections) {
@@ -5267,41 +5330,10 @@ function slice() {
       return builder;
     },
     withLane: (config2) => {
-      if (config2.name === DEFAULT_LANE)
-        throw new Error(`Lane "${DEFAULT_LANE}" is reserved`);
-      if (lanes.some((l) => l.name === config2.name))
-        throw new Error(`Lane "${config2.name}" was already declared`);
-      lanes.push(config2);
+      register_lane(config2, lanes);
       return builder;
     },
-    on: (event) => ({
-      do: (handler, options) => {
-        const reaction = {
-          handler,
-          resolver: _this_,
-          options: {
-            blockOnError: options?.blockOnError ?? true,
-            maxRetries: options?.maxRetries ?? 3,
-            backoff: options?.backoff
-          }
-        };
-        if (!handler.name)
-          throw new Error(
-            `Reaction handler for "${String(event)}" must be a named function`
-          );
-        if (events[event].reactions.has(handler.name))
-          throw new Error(
-            `Duplicate reaction "${handler.name}" for event "${String(event)}". Reaction handlers are keyed by function name; rename one of them.`
-          );
-        events[event].reactions.set(handler.name, reaction);
-        return Object.assign(builder, {
-          to(resolver) {
-            reaction.resolver = typeof resolver === "string" ? { target: resolver } : resolver;
-            return builder;
-          }
-        });
-      }
-    }),
+    on: (event) => reaction_on(event, events, builder),
     build: () => ({
       _tag: "Slice",
       states,
@@ -5612,6 +5644,7 @@ function write_line(writer, line) {
   DEFAULT_LANE,
   DEFAULT_MAX_SUBSCRIBED_STREAMS,
   DEFAULT_SETTLE_DEBOUNCE_MS,
+  DeferSignal,
   Environments,
   Errors,
   EventMetaSchema,