@rotorsoft/act 0.13.0 → 0.14.0

package/dist/@types/state-builder.d.ts

@@ -46,7 +46,7 @@ export type StateBuilder<S extends Schema, N extends string = string> = {
          *
          * @template E - Event schemas type
          * @param events - Object mapping event names to Zod schemas
-         * @returns A builder with `.patch()` to define event handlers
+         * @returns An ActionBuilder (with optional `.patch()` to override specific reducers)
          *
          * @example
          * ```typescript
@@ -57,27 +57,28 @@ export type StateBuilder<S extends Schema, N extends string = string> = {
          * })
          * ```
          */
-        emits: <E extends Schemas>(events: ZodTypes<E>) => {
+        emits: <E extends Schemas>(events: ZodTypes<E>) => ActionBuilder<S, E, {}, N> & {
             /**
-             * Defines how each event updates (patches) the state.
+             * Overrides specific event reducers. Events without a custom patch
+             * default to passthrough: `({ data }) => data` (event data merges
+             * into state).
              *
-             * Patch handlers are reducers - pure functions that take an event and current state,
-             * and return the changes to apply. Return partial state objects; unchanged fields
-             * are preserved automatically.
-             *
-             * @param patch - Object mapping event names to patch handler functions
+             * @param patch - Partial map of event names to patch handler functions
              * @returns An ActionBuilder for defining actions
              *
-             * @example
+             * @example Only override the events that need custom logic
              * ```typescript
+             * .emits({ TicketOpened, TicketClosed, TicketResolved })
              * .patch({
-             *   Incremented: (event, state) => ({ count: state.count + event.data.amount }),
-             *   Decremented: (event, state) => ({ count: state.count - event.data.amount }),
-             *   Reset: () => ({ count: 0 })
+             *   TicketOpened: ({ data }) => {
+             *     const { message, messageId, userId, ...other } = data;
+             *     return { ...other, userId, messages: { [messageId]: { ... } } };
+             *   },
              * })
+             * // TicketClosed and TicketResolved use passthrough
              * ```
              */
-            patch: (patch: PatchHandlers<S, E>) => ActionBuilder<S, E, {}, N>;
+            patch: (patch: Partial<PatchHandlers<S, E>>) => ActionBuilder<S, E, {}, N>;
         };
     };
 };
@@ -168,20 +169,28 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
              * and must return one or more events to emit. Events are applied to state
              * via the patch handlers defined earlier.
              *
-             * @param handler - Function that returns events to emit
+             * Pass a string event name for passthrough: the action payload becomes
+             * the event data directly.
+             *
+             * @param handler - Function that returns events to emit, or event name string for passthrough
              * @returns The ActionBuilder for chaining more actions
              *
-             * @example
+             * @example Custom handler
              * ```typescript
              * .emit((action, snapshot) => {
              *   const newBalance = snapshot.state.balance + action.amount;
              *   return ["Deposited", { amount: action.amount, newBalance }];
              * })
              * ```
+             *
+             * @example Passthrough (action payload = event data)
+             * ```typescript
+             * .emit("TicketAssigned")
+             * ```
              */
             emit: (handler: ActionHandler<S, E, {
                 [P in K]: AX;
-            }, K>) => ActionBuilder<S, E, A & {
+            }, K> | (keyof E & string)) => ActionBuilder<S, E, A & {
                 [P in K]: AX;
             }, N>;
         };
@@ -192,9 +201,17 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
          * and must return one or more events to emit. Return a single event as
          * `["EventName", data]` or multiple events as an array of event tuples.
          *
-         * @param handler - Function that returns events to emit
+         * Pass a string event name for passthrough: the action payload becomes
+         * the event data directly.
+         *
+         * @param handler - Function that returns events to emit, or event name string for passthrough
          * @returns The ActionBuilder for chaining more actions
          *
+         * @example Passthrough (action payload = event data)
+         * ```typescript
+         * .emit("Incremented")
+         * ```
+         *
          * @example Single event
          * ```typescript
          * .emit((action) => ["Incremented", { amount: action.by }])
@@ -207,23 +224,10 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
          *   ["LogUpdated", { message: `Incremented by ${action.by}` }]
          * ])
          * ```
-         *
-         * @example Conditional events
-         * ```typescript
-         * .emit((action, snapshot) => {
-         *   if (snapshot.state.count + action.by >= 100) {
-         *     return [
-         *       ["Incremented", { amount: action.by }],
-         *       ["MilestoneReached", { milestone: 100 }]
-         *     ];
-         *   }
-         *   return ["Incremented", { amount: action.by }];
-         * })
-         * ```
          */
         emit: (handler: ActionHandler<S, E, {
             [P in K]: AX;
-        }, K>) => ActionBuilder<S, E, A & {
+        }, K> | (keyof E & string)) => ActionBuilder<S, E, A & {
             [P in K]: AX;
         }, N>;
     };
@@ -272,7 +276,7 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
      * const Counter = state({ Counter: schema })
      *   .init(() => ({ count: 0 }))
      *   .emits({ Incremented: z.object({ amount: z.number() }) })
-     *   .patch({ Incremented: (event, state) => ({ count: state.count + event.data.amount }) })
+     *   .patch({ Incremented: ({ data }, state) => ({ count: state.count + data.amount }) })
      *   .on({ increment: z.object({ by: z.number() }) })
      *     .emit((action) => ["Incremented", { amount: action.by }])
      *   .build(); // Returns State<S, E, A, N>
@@ -290,9 +294,9 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
  *
  * The state builder provides a fluent API for defining:
  * 1. Initial state via `.init()`
- * 2. Event types via `.emits()`
- * 3. Event handlers (reducers) via `.patch()`
- * 4. Actions (commands) via `.on()` → `.emit()`
+ * 2. Event types via `.emits()` — all events default to passthrough (`({ data }) => data`)
+ * 3. Custom event reducers via `.patch()` (optional — only for events that need custom logic)
+ * 4. Actions (commands) via `.on()` → `.emit()` — pass an event name string for passthrough
  * 5. Business rules (invariants) via `.given()`
  * 6. Snapshotting strategy via `.snap()`
  *
@@ -300,7 +304,7 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
  * @param entry - Single-key record mapping state name to Zod schema (e.g., `{ Counter: z.object({ count: z.number() }) }`)
  * @returns A StateBuilder instance for fluent API configuration
  *
- * @example Basic counter state
+ * @example Basic counter state (with custom patch)
  * ```typescript
  * import { state } from "@rotorsoft/act";
  * import { z } from "zod";
@@ -310,14 +314,25 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
  *   .emits({
  *     Incremented: z.object({ amount: z.number() })
  *   })
- *   .patch({
- *     Incremented: (event, state) => ({ count: state.count + event.data.amount })
+ *   .patch({  // optional — only for events needing custom reducers
+ *     Incremented: ({ data }, state) => ({ count: state.count + data.amount })
  *   })
  *   .on({ increment: z.object({ by: z.number() }) })
  *     .emit((action) => ["Incremented", { amount: action.by }])
  *   .build();
  * ```
  *
+ * @example Passthrough state (no custom patch or emit needed)
+ * ```typescript
+ * const DigitBoard = state({ DigitBoard: z.object({ digit: z.string() }) })
+ *   .init(() => ({ digit: "" }))
+ *   .emits({ DigitCounted: z.object({ digit: z.string() }) })
+ *   // no .patch() — passthrough is the default (event data merges into state)
+ *   .on({ CountDigit: z.object({ digit: z.string() }) })
+ *     .emit("DigitCounted")  // string passthrough — action payload becomes event data
+ *   .build();
+ * ```
+ *
  * @example State with multiple events and invariants
  * ```typescript
  * const BankAccount = state({ BankAccount: z.object({
@@ -331,29 +346,29 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
  *     Withdrawn: z.object({ amount: z.number() }),
  *     Closed: z.object({})
  *   })
- *   .patch({
- *     Deposited: (event, state) => ({ balance: state.balance + event.data.amount }),
- *     Withdrawn: (event, state) => ({ balance: state.balance - event.data.amount }),
+ *   .patch({  // only override events needing custom logic
+ *     Deposited: ({ data }, state) => ({ balance: state.balance + data.amount }),
+ *     Withdrawn: ({ data }, state) => ({ balance: state.balance - data.amount }),
  *     Closed: () => ({ status: "closed", balance: 0 })
  *   })
  *   .on({ deposit: z.object({ amount: z.number() }) })
  *     .given([
  *       (_, snap) => snap.state.status === "open" || "Account must be open"
  *     ])
- *     .emit((action) => ["Deposited", { amount: action.amount }])
+ *     .emit("Deposited")  // passthrough — action payload { amount } becomes event data
  *   .on({ withdraw: z.object({ amount: z.number() }) })
  *     .given([
  *       (_, snap) => snap.state.status === "open" || "Account must be open",
  *       (_, snap, action) =>
  *         snap.state.balance >= action.amount || "Insufficient funds"
  *     ])
- *     .emit((action) => ["Withdrawn", { amount: action.amount }])
+ *     .emit("Withdrawn")
  *   .on({ close: z.object({}) })
  *     .given([
  *       (_, snap) => snap.state.status === "open" || "Already closed",
  *       (_, snap) => snap.state.balance === 0 || "Balance must be zero"
  *     ])
- *     .emit(() => ["Closed", {}])
+ *     .emit("Closed")
  *   .build();
  * ```
  *
@@ -369,14 +384,14 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
  *     UserCreated: z.object({ name: z.string(), email: z.string() }),
  *     UserLoggedIn: z.object({})
  *   })
- *   .patch({
- *     UserCreated: (event) => event.data,
+ *   .patch({  // only override events needing custom logic
  *     UserLoggedIn: (_, state) => ({ loginCount: state.loginCount + 1 })
  *   })
+ *   // UserCreated uses passthrough — event data merges into state
  *   .on({ createUser: z.object({ name: z.string(), email: z.string() }) })
- *     .emit((action) => ["UserCreated", action])
+ *     .emit("UserCreated")  // passthrough
  *   .on({ login: z.object({}) })
- *     .emit(() => ["UserLoggedIn", {}])
+ *     .emit("UserLoggedIn")
  *   .snap((snap) => snap.patches >= 10) // Snapshot every 10 events
  *   .build();
  * ```

package/dist/@types/state-builder.d.ts.map

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

package/dist/index.cjs

@@ -1652,19 +1652,34 @@ function state(entry) {
     init(init) {
       return {
         emits(events) {
-          return {
-            patch(patch2) {
+          const defaultPatch = Object.fromEntries(
+            Object.keys(events).map((k) => [
+              k,
+              ({ data }) => data
+            ])
+          );
+          const builder = action_builder({
+            events,
+            actions: {},
+            state: stateSchema,
+            name,
+            init,
+            patch: defaultPatch,
+            on: {}
+          });
+          return Object.assign(builder, {
+            patch(customPatch) {
               return action_builder({
                 events,
                 actions: {},
                 state: stateSchema,
                 name,
                 init,
-                patch: patch2,
+                patch: { ...defaultPatch, ...customPatch },
                 on: {}
               });
             }
-          };
+          });
         }
       };
     }
@@ -1687,7 +1702,12 @@ function action_builder(state2) {
         return { emit };
       }
       function emit(handler) {
-        on[action2] = handler;
+        if (typeof handler === "string") {
+          const eventName = handler;
+          on[action2] = ((payload) => [eventName, payload]);
+        } else {
+          on[action2] = handler;
+        }
         return action_builder({
           ...state2,
           actions,