@rotorsoft/act 0.6.27 → 0.6.29

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

@@ -7,90 +7,335 @@
 import { Act } from "./act.js";
 import type { EventRegister, ReactionHandler, ReactionOptions, ReactionResolver, Registry, Schema, SchemaRegister, Schemas, State } from "./types/index.js";
 /**
- * Fluent builder for composing event-sourced state machines with actions and reactions.
+ * Fluent builder interface for composing event-sourced applications.
  *
- * Provides a chainable API for registering states, events, and reaction handlers, enabling you to declaratively build complex, reactive applications.
+ * Provides a chainable API for:
+ * - Registering states via `.with()`
+ * - Defining event reactions via `.on()` → `.do()` → `.to()` or `.void()`
+ * - Building the orchestrator via `.build()`
  *
- * @template S SchemaRegister for state
- * @template E Schemas for events
- * @template A Schemas for actions
+ * @template S - Schema register for states (maps action names to state schemas)
+ * @template E - Event schemas (maps event names to event data schemas)
+ * @template A - Action schemas (maps action names to action payload schemas)
  *
- * @example
- * const app = act()
- *   .with(Counter)
- *   .on("Incremented").do(async (event) => { ... })
- *   .to(() => "OtherStream")
- *   .build();
+ * @see {@link act} for usage examples
+ * @see {@link Act} for the built orchestrator API
  */
 export type ActBuilder<S extends SchemaRegister<A>, E extends Schemas, A extends Schemas> = {
     /**
-     * Register a state machine with the builder.
+     * Registers a state definition with the builder.
+     *
+     * States define aggregates that process actions and emit events. Each state
+     * registration adds its actions and events to the orchestrator's registry.
+     * State names, action names, and event names must be unique across the application.
+     *
+     * @template SX - State schema type
+     * @template EX - Event schemas type for this state
+     * @template AX - Action schemas type for this state
+     * @param state - The state definition to register
+     * @returns The builder with updated type information for chaining
+     *
+     * @throws {Error} If a state with duplicate action or event names is registered
      *
-     * @template SX The type of state
-     * @template EX The type of events
-     * @template AX The type of actions
-     * @param state The state machine to add
-     * @returns The builder (for chaining)
+     * @example Register single state
+     * ```typescript
+     * const app = act()
+     *   .with(Counter)
+     *   .build();
+     * ```
+     *
+     * @example Register multiple states
+     * ```typescript
+     * const app = act()
+     *   .with(User)
+     *   .with(Order)
+     *   .with(Inventory)
+     *   .build();
+     * ```
      */
     with: <SX extends Schema, EX extends Schemas, AX extends Schemas>(state: State<SX, EX, AX>) => ActBuilder<S & {
         [K in keyof AX]: SX;
     }, E & EX, A & AX>;
     /**
-     * Register a reaction handler for a given event.
+     * Begins defining a reaction to a specific event.
+     *
+     * Reactions are event handlers that respond to state changes. They can trigger
+     * additional actions, update external systems, or perform side effects. Reactions
+     * are processed asynchronously during drain cycles.
+     *
+     * @template K - Event name (must be a registered event)
+     * @param event - The event name to react to
+     * @returns An object with `.do()` method to define the reaction handler
      *
-     * @template K The event name
-     * @param event The event to react to
-     * @returns An object with .do(handler) to register the handler
+     * @example
+     * ```typescript
+     * const app = act()
+     *   .with(User)
+     *   .on("UserCreated")  // React to UserCreated events
+     *     .do(async (event) => {
+     *       await sendWelcomeEmail(event.data.email);
+     *     })
+     *     .void()
+     *   .build();
+     * ```
      */
     on: <K extends keyof E>(event: K) => {
         /**
-         * Register a reaction handler for the event.
+         * Defines the reaction handler function for the event.
+         *
+         * The handler receives the committed event and can:
+         * - Perform side effects (send emails, call APIs, etc.)
+         * - Return an action tuple `[actionName, payload]` to trigger another action
+         * - Return `void` or `undefined` for side-effect-only reactions
+         *
+         * @param handler - The reaction handler function
+         * @param options - Optional reaction configuration
+         * @param options.blockOnError - Block this stream if handler fails (default: true)
+         * @param options.maxRetries - Maximum retry attempts on failure (default: 3)
+         * @returns The builder with `.to()` and `.void()` methods for routing configuration
          *
-         * @param handler The reaction handler function
-         * @param options (Optional) Reaction options (retries, blocking, etc.)
-         * @returns The builder (for chaining), with .to(resolver) and .void() for advanced routing
+         * @example Side effect only (void)
+         * ```typescript
+         * .on("UserCreated")
+         *   .do(async (event) => {
+         *     await analytics.track("user_created", event.data);
+         *   })
+         *   .void()
+         * ```
+         *
+         * @example Trigger another action
+         * ```typescript
+         * .on("OrderPlaced")
+         *   .do(async (event) => {
+         *     return ["reduceStock", { amount: event.data.items.length }];
+         *   })
+         *   .to("inventory-1")
+         * ```
+         *
+         * @example With retry configuration
+         * ```typescript
+         * .on("PaymentProcessed")
+         *   .do(async (event) => {
+         *     await externalAPI.notify(event.data);
+         *   }, {
+         *     blockOnError: false,  // Don't block on failure
+         *     maxRetries: 5         // Retry up to 5 times
+         *   })
+         *   .void()
+         * ```
          */
         do: (handler: ReactionHandler<E, K>, options?: Partial<ReactionOptions>) => ActBuilder<S, E, A> & {
             /**
-             * Route the reaction to a specific target and optionally source streams (resolver function).
-             * @param resolver The resolver function or target stream name (all sources) as a shorthand
-             * @returns The builder (for chaining)
+             * Routes the reaction to a specific target stream.
+             *
+             * Use this when the reaction triggers an action on a specific state instance.
+             * You can provide either a static stream name (string) or a resolver function
+             * that dynamically determines the target based on the event.
+             *
+             * @param resolver - Target stream name (string) or resolver function
+             * @returns The builder for chaining
+             *
+             * @example Static target stream
+             * ```typescript
+             * .on("OrderPlaced")
+             *   .do(async (event) => ["reduceStock", { amount: 10 }])
+             *   .to("inventory-main")
+             * ```
+             *
+             * @example Dynamic target based on event data
+             * ```typescript
+             * .on("OrderPlaced")
+             *   .do(async (event) => ["reduceStock", { amount: 10 }])
+             *   .to((event) => ({
+             *     target: `inventory-${event.data.warehouseId}`
+             *   }))
+             * ```
+             *
+             * @example Source and target routing
+             * ```typescript
+             * .on("UserLoggedIn")
+             *   .do(async (event) => ["incrementCount", {}])
+             *   .to(({ stream }) => ({
+             *     source: stream,           // React to events from this user stream
+             *     target: `stats-${stream}` // Update corresponding stats stream
+             *   }))
+             * ```
              */
             to: (resolver: ReactionResolver<E, K> | string) => ActBuilder<S, E, A>;
             /**
-             * Mark the reaction as void (no routing).
-             * @returns The builder (for chaining)
+             * Marks the reaction as void (side-effect only, no target stream).
+             *
+             * Use this when the reaction doesn't trigger any actions - it only performs
+             * side effects like logging, sending notifications, or updating external systems.
+             *
+             * @returns The builder for chaining
+             *
+             * @example
+             * ```typescript
+             * .on("UserCreated")
+             *   .do(async (event) => {
+             *     await sendEmail(event.data.email, "Welcome!");
+             *     await logger.info("User created", event.data);
+             *   })
+             *   .void()  // No target stream
+             * ```
              */
             void: () => ActBuilder<S, E, A>;
         };
     };
     /**
-     * Build the application and return an Act orchestrator.
+     * Builds and returns the Act orchestrator instance.
+     *
+     * This finalizes the builder configuration and creates the orchestrator that
+     * can execute actions, load state, and process reactions.
      *
-     * @param drainLimit (Optional) The maximum number of events to drain per cycle (default: 10)
+     * @param drainLimit - Deprecated parameter, no longer used
      * @returns The Act orchestrator instance
+     *
+     * @example
+     * ```typescript
+     * const app = act()
+     *   .with(Counter)
+     *   .with(User)
+     *   .on("UserCreated")
+     *     .do(sendWelcomeEmail)
+     *     .void()
+     *   .build();
+     *
+     * // Now use the app
+     * await app.do("createUser", target, payload);
+     * await app.drain();
+     * ```
+     *
+     * @see {@link Act} for available orchestrator methods
      */
     build: (drainLimit?: number) => Act<S, E, A>;
     /**
-     * The registered event schemas and reaction maps.
+     * The registered event schemas and their reaction maps.
+     *
+     * This is an internal registry maintained by the builder. Generally, you don't
+     * need to access this directly.
      */
     readonly events: EventRegister<E>;
 };
 /**
- * Creates an ActBuilder instance for composing event-sourced applications.
+ * Creates a new Act orchestrator builder for composing event-sourced applications.
+ *
+ * The Act orchestrator is responsible for:
+ * - Managing state instances (aggregates)
+ * - Executing actions and committing events
+ * - Processing reactions (event handlers)
+ * - Coordinating event-driven workflows
  *
- * Use this function to start building your application by chaining `.with()`, `.on()`, and `.build()` calls.
+ * Use the fluent API to register states with `.with()`, define event reactions with `.on()`,
+ * and build the orchestrator with `.build()`.
  *
- * @template S The type of state
- * @template E The type of events
- * @template A The type of actions
- * @returns An ActBuilder instance
+ * @template S - State schema register type
+ * @template E - Event schemas type
+ * @template A - Action schemas type
+ * @returns An ActBuilder instance for fluent API configuration
+ *
+ * @example Basic application with single state
+ * ```typescript
+ * import { act, state } from "@rotorsoft/act";
+ * import { z } from "zod";
+ *
+ * const Counter = state("Counter", z.object({ count: z.number() }))
+ *   .init(() => ({ count: 0 }))
+ *   .emits({ Incremented: z.object({ amount: z.number() }) })
+ *   .patch({ Incremented: (event, state) => ({ count: state.count + event.data.amount }) })
+ *   .on("increment", z.object({ by: z.number() }))
+ *     .emit((action) => ["Incremented", { amount: action.by }])
+ *   .build();
  *
- * @example
  * const app = act()
  *   .with(Counter)
- *   .on("Incremented").do(async (event) => { ... })
  *   .build();
+ *
+ * // Execute action
+ * await app.do("increment",
+ *   { stream: "counter1", actor: { id: "user1", name: "Alice" } },
+ *   { by: 5 }
+ * );
+ *
+ * // Load current state
+ * const snapshot = await app.load(Counter, "counter1");
+ * console.log(snapshot.state.count); // 5
+ * ```
+ *
+ * @example Application with reactions
+ * ```typescript
+ * const User = state("User", z.object({ name: z.string(), email: z.string() }))
+ *   .init((data) => data)
+ *   .emits({ UserCreated: z.object({ name: z.string(), email: z.string() }) })
+ *   .patch({ UserCreated: (event) => event.data })
+ *   .on("createUser", z.object({ name: z.string(), email: z.string() }))
+ *     .emit((action) => ["UserCreated", action])
+ *   .build();
+ *
+ * const app = act()
+ *   .with(User)
+ *   .on("UserCreated")
+ *     .do(async (event) => {
+ *       // Send welcome email
+ *       await sendEmail(event.data.email, "Welcome!");
+ *       logger.info(`Sent welcome email to ${event.data.email}`);
+ *     })
+ *     .void() // No target stream, just side effects
+ *   .build();
+ *
+ * // Create user (triggers email sending via reaction)
+ * await app.do("createUser",
+ *   { stream: "user-123", actor: { id: "admin", name: "Admin" } },
+ *   { name: "Alice", email: "alice@example.com" }
+ * );
+ *
+ * // Process reactions
+ * await app.drain();
+ * ```
+ *
+ * @example Multi-state application with event correlation
+ * ```typescript
+ * const Order = state("Order", z.object({ items: z.array(z.string()), total: z.number() }))
+ *   .init((data) => data)
+ *   .emits({ OrderPlaced: z.object({ items: z.array(z.string()), total: z.number() }) })
+ *   .patch({ OrderPlaced: (event) => event.data })
+ *   .on("placeOrder", z.object({ items: z.array(z.string()), total: z.number() }))
+ *     .emit((action) => ["OrderPlaced", action])
+ *   .build();
+ *
+ * const Inventory = state("Inventory", z.object({ stock: z.number() }))
+ *   .init(() => ({ stock: 100 }))
+ *   .emits({ StockReduced: z.object({ amount: z.number() }) })
+ *   .patch({ StockReduced: (event, state) => ({ stock: state.stock - event.data.amount }) })
+ *   .on("reduceStock", z.object({ amount: z.number() }))
+ *     .emit((action) => ["StockReduced", { amount: action.amount }])
+ *   .build();
+ *
+ * const app = act()
+ *   .with(Order)
+ *   .with(Inventory)
+ *   .on("OrderPlaced")
+ *     .do(async (event) => {
+ *       // Reduce inventory for each item
+ *       return ["reduceStock", { amount: event.data.items.length }];
+ *     })
+ *     .to("inventory-1") // Target specific inventory stream
+ *   .build();
+ *
+ * await app.do("placeOrder",
+ *   { stream: "order-1", actor: { id: "user1", name: "Alice" } },
+ *   { items: ["item1", "item2"], total: 100 }
+ * );
+ *
+ * // Process reaction (reduces inventory)
+ * await app.drain();
+ * ```
+ *
+ * @see {@link ActBuilder} for available builder methods
+ * @see {@link Act} for orchestrator API methods
+ * @see {@link state} for defining states
+ * @see {@link https://rotorsoft.github.io/act-root/docs/intro | Documentation}
  */
 export declare function act<S extends SchemaRegister<A> = {}, E extends Schemas = {}, A extends Schemas = {}>(states?: Set<string>, registry?: Registry<S, E, A>): ActBuilder<S, E, A>;
 //# sourceMappingURL=act-builder.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"act-builder.d.ts","sourceRoot":"","sources":["../../src/act-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,KAAK,EACV,aAAa,EAEb,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,MAAM,EACN,cAAc,EACd,OAAO,EACP,KAAK,EACN,MAAM,kBAAkB,CAAC;AAU1B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,EAC3B,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,IACf;IACF;;;;;;;;OAQG;IACH,IAAI,EAAE,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,OAAO,EAAE,EAAE,SAAS,OAAO,EAC9D,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,KACrB,UAAU,CAAC,CAAC,GAAG;SAAG,CAAC,IAAI,MAAM,EAAE,GAAG,EAAE;KAAE,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7D;;;;;;OAMG;IACH,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EACpB,KAAK,EAAE,CAAC,KACL;QACH;;;;;;WAMG;QACH,EAAE,EAAE,CACF,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAC9B,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,KAC/B,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG;YACzB;;;;eAIG;YACH,EAAE,EAAE,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,KAAK,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACvE;;;eAGG;YACH,IAAI,EAAE,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;SACjC,CAAC;KACH,CAAC;IACF;;;;;OAKG;IACH,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CACnC,CAAC;AAIF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,GAAG,CAEjB,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,GAAG,EAAE,EAChC,CAAC,SAAS,OAAO,GAAG,EAAE,EACtB,CAAC,SAAS,OAAO,GAAG,EAAE,EAEtB,MAAM,GAAE,GAAG,CAAC,MAAM,CAAa,EAC/B,QAAQ,GAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAGzB,GACA,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAsFrB"}
+{"version":3,"file":"act-builder.d.ts","sourceRoot":"","sources":["../../src/act-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,KAAK,EACV,aAAa,EAEb,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,MAAM,EACN,cAAc,EACd,OAAO,EACP,KAAK,EACN,MAAM,kBAAkB,CAAC;AAU1B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,EAC3B,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,IACf;IACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,IAAI,EAAE,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,OAAO,EAAE,EAAE,SAAS,OAAO,EAC9D,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,KACrB,UAAU,CAAC,CAAC,GAAG;SAAG,CAAC,IAAI,MAAM,EAAE,GAAG,EAAE;KAAE,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EACpB,KAAK,EAAE,CAAC,KACL;QACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA2CG;QACH,EAAE,EAAE,CACF,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAC9B,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,KAC/B,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG;YACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAmCG;YACH,EAAE,EAAE,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,KAAK,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACvE;;;;;;;;;;;;;;;;;eAiBG;YACH,IAAI,EAAE,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;SACjC,CAAC;KACH,CAAC;IACF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CACnC,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsHG;AACH,wBAAgB,GAAG,CAEjB,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,GAAG,EAAE,EAChC,CAAC,SAAS,OAAO,GAAG,EAAE,EACtB,CAAC,SAAS,OAAO,GAAG,EAAE,EAEtB,MAAM,GAAE,GAAG,CAAC,MAAM,CAAa,EAC/B,QAAQ,GAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAGzB,GACA,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAsFrB"}