@rotorsoft/act 1.37.8 → 2.0.1

package/dist/index.js

@@ -13,6 +13,8 @@ import {
   MAX_SHUTDOWN_GRACE_MS,
   PackageSchema,
   cache,
+  check_appends,
+  check_store,
   config,
   current_autoclose_window,
   current_reacting,
@@ -42,7 +44,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-TSDQDT4S.js";
+} from "./chunk-33D5NQNQ.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -56,7 +58,6 @@ import {
   Errors,
   EventMetaSchema,
   ExitCodes,
-  InvariantError,
   LogLevels,
   NonRetryableError,
   PreconditionError,
@@ -76,7 +77,7 @@ import {
   pii_fields,
   pii_schemas,
   sensitive
-} from "./chunk-I5RF2NFR.js";
+} from "./chunk-UO7HNLSH.js";
 
 // src/signals.ts
 process.once("SIGINT", async (arg) => {
@@ -752,6 +753,7 @@ var CircuitBreaker = class {
 
 // src/internal/classify.ts
 var ALL_LANES = /* @__PURE__ */ Symbol("act/all-lanes");
+var describe_source = (source) => source === void 0 ? "no source (every stream)" : `"${source}"`;
 function classify_registry(registry, states) {
   const statics = /* @__PURE__ */ new Map();
   const target_lanes = /* @__PURE__ */ new Map();
@@ -778,6 +780,10 @@ function classify_registry(registry, states) {
           );
         }
         const existing = statics.get(target);
+        if (existing && existing.source !== source)
+          throw new Error(
+            `Target "${target}" has reactions on two sources, ${describe_source(existing.source)} and ${describe_source(source)}. A target reads one source, so the second would miss events or read too many. Give it its own target.`
+          );
         if (!existing) {
           statics.set(target, { stream: target, source, priority, lane });
         } else if (priority > existing.priority) {
@@ -1197,14 +1203,18 @@ async function snap(snapshot) {
   const { id, stream, name, meta, version } = snapshot.event;
   try {
     const [committed] = await store().commit(
-      stream,
-      [{ name: SNAP_EVENT, data: snapshot.state }],
+      [
+        {
+          stream,
+          msgs: [{ name: SNAP_EVENT, data: snapshot.state }],
+          // IMPORTANT! - state events are committed right after the snapshot event
+          expectedVersion: version
+        }
+      ],
       {
         correlation: meta.correlation,
         causation: { event: { id, name, stream } }
-      },
-      version
-      // IMPORTANT! - state events are committed right after the snapshot event
+      }
     );
     return committed;
   } catch (error) {
@@ -1217,10 +1227,14 @@ async function snap(snapshot) {
 async function tombstone(stream, expectedVersion, correlation) {
   try {
     const [committed] = await store().commit(
-      stream,
-      [{ name: TOMBSTONE_EVENT, data: {} }],
-      { correlation, causation: {} },
-      expectedVersion
+      [
+        {
+          stream,
+          msgs: [{ name: TOMBSTONE_EVENT, data: {} }],
+          expectedVersion
+        }
+      ],
+      { correlation, causation: {} }
     );
     return committed;
   } catch (error) {
@@ -1422,6 +1436,38 @@ async function load(me, target, callback, patch_fn = bare_patch) {
     replayed
   };
 }
+async function load_others(loads, payload, own, actor, patch_fn, refuse) {
+  const streams = loads.map((l) => l.target(payload, own.state));
+  streams.forEach((stream, i) => {
+    if (stream === void 0) return;
+    if (typeof stream !== "string" || !stream)
+      throw refuse(`loads "${loads[i].name}" from an empty stream name`);
+    if (stream === own.stream) throw refuse(`loads its own stream "${stream}"`);
+    if (streams.indexOf(stream) !== i)
+      throw refuse(`loads stream "${stream}" twice`);
+  });
+  return Promise.all(
+    loads.map(async (l, i) => {
+      const stream = streams[i];
+      if (stream === void 0) return void 0;
+      const snapshot = await load(
+        l.state,
+        { stream, actor },
+        void 0,
+        patch_fn
+      );
+      if (snapshot.event?.name === TOMBSTONE_EVENT)
+        throw new StreamClosedError(stream);
+      return {
+        state: l.state,
+        stream,
+        snapshot,
+        expected: snapshot.version,
+        events: []
+      };
+    })
+  );
+}
 async function action(me, action2, target, payload, options, patch_fn = bare_patch) {
   const { stream, expectedVersion, actor } = target;
   if (!stream) throw new Error("Missing target stream");
@@ -1430,6 +1476,7 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
   const validated = validate(action2, payload, me.actions[action2]);
   const opts = me.options?.[action2];
   const max_retries = opts?.maxRetries ?? 0;
+  const loads = me.loads?.[action2] ?? [];
   for (let attempt = 0; ; attempt++) {
     try {
       const snapshot = await load(
@@ -1440,18 +1487,32 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
       );
       if (snapshot.event?.name === TOMBSTONE_EVENT)
         throw new StreamClosedError(stream);
-      const expected = expectedVersion ?? snapshot.version;
-      for (const { valid, description } of me.given?.[action2] ?? [])
-        if (!valid(snapshot.state, actor))
-          throw new InvariantError(
-            action2,
-            validated,
-            target,
-            snapshot,
-            description
-          );
+      const own = {
+        state: me,
+        stream,
+        snapshot,
+        expected: expectedVersion ?? snapshot.version,
+        events: []
+      };
+      const others = loads.length ? await load_others(
+        loads,
+        validated,
+        { stream, state: snapshot.state },
+        target.actor,
+        patch_fn,
+        (description) => new PreconditionError(
+          action2,
+          validated,
+          target,
+          snapshot,
+          description
+        )
+      ) : [];
+      const loaded = Object.fromEntries(
+        others.map((p, i) => [loads[i].name, p?.snapshot.state])
+      );
       for (const { holds, description } of me.requires?.[action2] ?? [])
-        if (!holds(validated, snapshot.state, actor))
+        if (!holds(validated, snapshot.state, actor, loaded))
           throw new PreconditionError(
             action2,
             validated,
@@ -1459,15 +1520,31 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
             snapshot,
             description
           );
-      const result = me.on[action2](validated, snapshot, target);
+      const result = me.on[action2](validated, snapshot, target, loaded);
       if (!result || Array.isArray(result) && !result.length)
         return [snapshot];
       const tuples = Array.isArray(result[0]) ? result : [result];
-      const events = tuples.map(([name, data]) => ({
-        name,
-        data: validate(name, data, me.events[name])
-      }));
-      const emitted = events.map((e) => me.message(e));
+      for (const [name, data] of tuples) {
+        const event = name;
+        const i = loads.findIndex((l) => l.events.includes(event));
+        if (i >= 0 && !others[i]) continue;
+        const to = i >= 0 ? others[i] : name in me.events ? own : void 0;
+        if (!to)
+          throw new Error(
+            `Action "${action2}" emitted "${event}", which isn't an event of "${me.name}" and isn't listed on any of its loads`
+          );
+        to.events.push({
+          name: event,
+          data: validate(event, data, to.state.events[event])
+        });
+      }
+      if (!own.events.length)
+        throw new Error(
+          `Action "${action2}" appends only to the streams it loads; it must append an event to its own stream too`
+        );
+      const appends = [own, ...others].filter(
+        (p) => !!p?.events.length
+      );
       const meta = {
         correlation: reactingTo?.meta.correlation || correlator({
           action: action2,
@@ -1488,61 +1565,86 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
           } : void 0
         }
       };
-      let { state: state2, patches } = snapshot;
       const created = /* @__PURE__ */ new Date();
-      const folded = events.map((e, i) => {
-        const event = {
-          ...e,
-          id: -1,
-          stream,
-          version: snapshot.version + i + 1,
-          created,
-          meta
-        };
-        const patch2 = me.patch[event.name](event, state2);
-        state2 = patch_fn(me, state2, patch2, event);
-        patches++;
-        return { state: state2, patch: patch2, patches };
+      const folds = appends.map((p) => {
+        let { state: state2, patches } = p.snapshot;
+        const folded = p.events.map((e, i) => {
+          const event = {
+            ...e,
+            id: -1,
+            stream: p.stream,
+            version: p.snapshot.version + i + 1,
+            created,
+            meta
+          };
+          const patch2 = p.state.patch[event.name](event, state2);
+          state2 = patch_fn(p.state, state2, patch2, event);
+          patches++;
+          return { state: state2, patch: patch2, patches };
+        });
+        check_invariants(
+          `${p.state.name}.${action2}`,
+          state2,
+          p.state.state,
+          p.state.pii_aware
+        );
+        return folded;
       });
-      check_invariants(
-        `${me.name}.${action2}`,
-        state2,
-        me.state,
-        me.pii_aware
-      );
       let committed;
       try {
-        committed = await store().commit(stream, emitted, meta, expected);
+        committed = await store().commit(
+          appends.map((p) => ({
+            stream: p.stream,
+            msgs: p.events.map((e) => p.state.message(e)),
+            expectedVersion: p.expected
+          })),
+          meta
+        );
       } catch (error) {
-        if (error instanceof ConcurrencyError) void cache_drop(stream);
+        if (error instanceof ConcurrencyError) void cache_drop(error.stream);
         throw error;
       }
-      const snapshots = committed.map((row, i) => ({
-        event: { ...row, data: events[i].data },
-        state: folded[i].state,
-        version: row.version,
-        id: row.id,
-        patches: folded[i].patches,
-        snaps: snapshot.snaps,
-        patch: folded[i].patch,
-        cache_hit: snapshot.cache_hit,
-        replayed: snapshot.replayed
-      }));
-      const last = snapshots.at(-1);
-      const snap_event = me.snap?.(last) ? await snap(last) : void 0;
-      if (!me.pii_aware)
-        void cache_put(stream, {
-          stream,
-          state: last.state,
-          version: snap_event?.version ?? last.event.version,
-          event_id: snap_event?.id ?? last.event.id,
-          patches: snap_event ? 0 : last.patches,
-          snaps: snap_event ? last.snaps + 1 : last.snaps
+      let row = 0;
+      const snapshots = [];
+      for (const [a, append] of appends.entries()) {
+        const { snapshot: base, state: owner } = append;
+        const appended = append.events.map((e, i) => {
+          const stored = committed[row++];
+          const fold = folds[a][i];
+          return {
+            event: { ...stored, data: e.data },
+            state: fold.state,
+            version: stored.version,
+            id: stored.id,
+            patches: fold.patches,
+            snaps: base.snaps,
+            patch: fold.patch,
+            cache_hit: base.cache_hit,
+            replayed: base.replayed
+          };
         });
+        const last = appended.at(-1);
+        const snap_event = owner.snap?.(last) ? await snap(last) : void 0;
+        if (!owner.pii_aware)
+          void cache_put(append.stream, {
+            stream: append.stream,
+            state: last.state,
+            version: snap_event?.version ?? last.event.version,
+            event_id: snap_event?.id ?? last.event.id,
+            patches: snap_event ? 0 : last.patches,
+            snaps: snap_event ? last.snaps + 1 : last.snaps
+          });
+        if (snap_event)
+          appended[appended.length - 1] = {
+            ...last,
+            version: snap_event.version
+          };
+        snapshots.push(...appended);
+      }
       return snapshots;
     } catch (error) {
       if (!(error instanceof ConcurrencyError)) throw error;
-      if (expectedVersion !== void 0) throw error;
+      if (expectedVersion !== void 0 && error.stream === stream) throw error;
       if (attempt >= max_retries) throw error;
       if (opts?.backoff) {
         const delay_ms = compute_backoff_delay(attempt, opts.backoff);
@@ -1649,14 +1751,14 @@ function build_es(logger, correlator = default_correlator, patch_fn = bare_patch
     }),
     action: traced(
       bound_action,
-      (snapshots, _me, _action, target) => {
+      (snapshots) => {
         if (snapshots[0].patch)
           logger.trace(
             snapshots.map((s) => s.event.data),
             es_caption(
               "committed",
               C_ORANGE,
-              `${target.stream}.${snapshots.map((s) => s.event.name).join(", ")}`
+              snapshots.map((s) => `${s.event.stream}.${s.event.name}`).join(", ")
             )
           );
       },
@@ -2205,9 +2307,9 @@ function synthesize_autoclose_reactions(registry, states, read_window) {
       // watermark would let autoclose's defer short-circuit the aggregate's
       // other reactions (the "a defer affects all reactions on a stream"
       // hazard). The close still targets the aggregate (`source`).
-      // A stream name with a regex metacharacter would read as a pattern, and a
-      // store may refuse it at subscribe, stopping every reaction. Such a stream
-      // has no autoclose: `app.close` still closes it.
+      // An anchored stream name would read as a pattern, and a store may refuse
+      // it at subscribe, stopping every reaction. Such a stream has no
+      // autoclose: `app.close` still closes it.
       resolver: (e) => is_literal_source(e.stream) ? {
         target: `${AUTOCLOSE_TARGET_PREFIX}${e.stream}`,
         source: e.stream
@@ -3285,6 +3387,7 @@ var Act = class {
     this._lanes = lanes;
     this._declared_lanes = ["default", ...lanes.map((l) => l.name)];
     validate_only_lanes(options.onlyLanes, this._declared_lanes);
+    if (options.scoped) check_store(options.scoped.store);
     this._ports = options.scoped ?? default_scope();
     const ports = this._ports;
     this._scoped = make_run_scoped({
@@ -3540,7 +3643,7 @@ var Act = class {
    * Executes an action: validates the payload, loads the state, checks its
    * preconditions, runs the handler, folds the events it emits, checks the
    * state's invariants (its schema) on the result, and commits them with
-   * optimistic concurrency on the stream. The reactions to those events
+   * optimistic concurrency on every stream it appends to. The reactions to those events
    * settle on their own (unless `autoSettle: false`).
    *
    * @template TKey - Action name from registered actions
@@ -3550,7 +3653,8 @@ var Act = class {
    * @param options - Per-call dispatch options ({@link DoOptions}) —
    *   `reactingTo` to thread correlation, `correlator` to override the
    *   framework or orchestrator-level correlator for this call only.
-   * @returns Array of snapshots for all affected states (usually one)
+   * @returns The snapshots of the action's own stream, one per event appended
+   *   to it; the loaded snapshot alone when the action commits nothing
    *
    * @throws {ValidationError} If the payload doesn't match the action schema,
    *   or the state the action leaves breaks the state schema
@@ -3587,13 +3691,22 @@ var Act = class {
         do_options
       );
       if (!snapshots[0].patch) return snapshots;
+      const me = this.registry.actions[action2];
       this._wake(snapshots.map((s) => s.event.name));
-      this.emit("committed", snapshots);
-      this._notify(
-        `committed:${this.registry.actions[action2].name}`,
-        snapshots
-      );
-      return snapshots;
+      const by_stream = /* @__PURE__ */ new Map();
+      for (const s of snapshots) {
+        const of_stream = by_stream.get(s.event.stream);
+        if (of_stream) of_stream.push(s);
+        else by_stream.set(s.event.stream, [s]);
+      }
+      for (const [stream, of_stream] of by_stream) {
+        const owner = stream === target.stream ? me : me.loads[action2].find(
+          (l) => l.events.includes(of_stream[0].event.name)
+        ).state;
+        this.emit("committed", of_stream);
+        this._notify(`committed:${owner.name}`, of_stream);
+      }
+      return snapshots.filter((s) => s.event.stream === target.stream);
     });
   }
   async load(stateOrName, streamOrTarget, callback, asOf) {
@@ -4189,12 +4302,11 @@ var Act = class {
 
 // src/builders/merge.ts
 import { ZodObject } from "zod";
-function base_type_name(zodType) {
-  let t = zodType;
-  while (typeof t.unwrap === "function") {
-    t = t.unwrap();
-  }
-  return t.constructor.name;
+function base_type_name(schema) {
+  let def = def_of(schema);
+  for (let inner = inner_of(def); inner; inner = inner_of(def))
+    def = def_of(inner);
+  return def.type === "array" ? `array of ${base_type_name(def.element)}` : def.type;
 }
 function merge_schemas(existing, incoming, state_name) {
   if (existing === incoming) return existing;
@@ -4286,8 +4398,8 @@ function merge_into_existing(state2, existing, states, actions, events) {
     actions: { ...existing.actions, ...state2.actions },
     patch: merged_patch,
     on: { ...existing.on, ...state2.on },
-    given: { ...existing.given, ...state2.given },
     requires: { ...existing.requires, ...state2.requires },
+    loads: existing.loads || state2.loads ? { ...existing.loads, ...state2.loads } : void 0,
     snap: pick_declared(existing.snap, state2.snap, "snap strategy", state2.name),
     // Per-action retry policy is keyed by action name, so the two partials'
     // maps combine. Left `undefined` when neither declared one, so the
@@ -4852,6 +4964,38 @@ function act() {
         for (const [name, gate] of built.handler_readers) _hr.set(name, gate);
         finalize_deprecations();
         if (built.advisory) log().warn(built.advisory);
+        for (const [name, state2] of states) {
+          if (!state2.loads) continue;
+          const resolved = {};
+          for (const [action2, loads] of Object.entries(state2.loads)) {
+            resolved[action2] = loads.map((l) => {
+              const registered = states.get(l.state.name);
+              if (!registered)
+                throw new Error(
+                  `Action "${action2}" loads "${l.state.name}", which is not registered \u2014 add it via withState/withSlice before build()`
+                );
+              const deprecated = l.events.find(
+                (e) => _de.get(registered.name)?.has(e)
+              );
+              if (deprecated)
+                throw new Error(
+                  `Action "${action2}" lists deprecated event "${deprecated}" on its load of "${registered.name}". A newer version exists: "${current_version_of(deprecated, Object.keys(registered.events))}". List the current version instead.`
+                );
+              return { ...l, state: registered };
+            });
+          }
+          for (const [action2, loads] of Object.entries(resolved)) {
+            const static_target = state2.on[action2]._static_emit;
+            if (static_target && loads.some((l) => l.events.includes(static_target)))
+              throw new Error(
+                `Action "${action2}" statically emits "${static_target}", which its load lists, so nothing goes to its own stream; emit one of its own events too`
+              );
+          }
+          const own = { ...state2, loads: resolved };
+          states.set(name, own);
+          for (const action2 of Object.keys(own.actions))
+            registry.actions[action2] = own;
+        }
         for (const state2 of states.values()) {
           if (state2.disclose) _dp.set(state2.name, state2.disclose);
           if (state2.autoclose) _ac.set(state2.name, state2.autoclose);
@@ -5092,9 +5236,25 @@ function action_builder(state2) {
         internal.options ??= {};
         internal.options[action2] = options;
       }
-      function given(rules) {
-        (internal.given ??= {})[action2] = rules;
-        return { requires, emit };
+      const loads = [];
+      function load2(state3, target, events = [], name = state3.name) {
+        if (loads.some((l) => l.name === name))
+          throw new Error(
+            `Action "${action2}" loads "${name}" twice; name each load of the same state`
+          );
+        for (const event of events) {
+          if (!(event in state3.events))
+            throw new Error(
+              `Action "${action2}" lists "${event}" on its load of "${state3.name}", which doesn't emit it`
+            );
+          if (loads.some((l) => l.events.includes(event)))
+            throw new Error(
+              `Action "${action2}" lists "${event}" on two loads; an event goes to one stream`
+            );
+        }
+        loads.push({ state: state3, target, events, name });
+        (internal.loads ??= {})[action2] = loads;
+        return { loads: load2, requires, emit };
       }
       function requires(rules) {
         (internal.requires ??= {})[action2] = rules;
@@ -5115,7 +5275,7 @@ function action_builder(state2) {
         }
         return builder;
       }
-      return { given, requires, emit };
+      return { loads: load2, requires, emit };
     },
     snap(snap2) {
       internal.snap = snap2;
@@ -5348,7 +5508,6 @@ export {
   ExitCodes,
   InMemoryCache,
   InMemoryStore,
-  InvariantError,
   LogLevels,
   NonRetryableError,
   PackageSchema,
@@ -5365,6 +5524,7 @@ export {
   ZodEmpty,
   act,
   cache,
+  check_appends,
   config,
   dateReviver,
   default_scope,