@rotorsoft/act 0.6.28 → 0.6.29

package/dist/@types/ports.d.ts

@@ -41,13 +41,83 @@ type Injector<Port extends Disposable> = (adapter?: Port) => Port;
 export declare function port<Port extends Disposable>(injector: Injector<Port>): (adapter?: Port) => Port;
 export declare function disposeAndExit(code?: ExitCode): Promise<void>;
 /**
- * Registers resource disposers that are triggered on process exit.
+ * Registers resource cleanup functions for graceful shutdown.
  *
- * @param disposer The disposer function to register
- * @returns A function that triggers all registered disposers and terminates the process
+ * Disposers are called automatically when the process exits (SIGINT, SIGTERM)
+ * or when manually triggered. They execute in reverse registration order,
+ * allowing proper cleanup of dependent resources.
  *
- * @example
- * dispose(async () => { await myResource.close(); });
+ * Act automatically disposes registered stores and adapters. Use this function
+ * to register additional cleanup for your own resources (database connections,
+ * file handles, timers, etc.).
+ *
+ * @param disposer - Async function to call during cleanup
+ * @returns Function to manually trigger disposal and exit
+ *
+ * @example Register custom resource cleanup
+ * ```typescript
+ * import { dispose } from "@rotorsoft/act";
+ *
+ * const redis = createRedisClient();
+ *
+ * dispose(async () => {
+ *   console.log("Closing Redis connection...");
+ *   await redis.quit();
+ * });
+ *
+ * // On SIGINT/SIGTERM, Redis will be cleaned up automatically
+ * ```
+ *
+ * @example Multiple disposers in order
+ * ```typescript
+ * import { dispose } from "@rotorsoft/act";
+ *
+ * const db = connectDatabase();
+ * dispose(async () => {
+ *   console.log("Closing database...");
+ *   await db.close();
+ * });
+ *
+ * const cache = connectCache();
+ * dispose(async () => {
+ *   console.log("Closing cache...");
+ *   await cache.disconnect();
+ * });
+ *
+ * // On exit: cache closes first, then database
+ * ```
+ *
+ * @example Manual cleanup trigger
+ * ```typescript
+ * import { dispose } from "@rotorsoft/act";
+ *
+ * const shutdown = dispose(async () => {
+ *   await cleanup();
+ * });
+ *
+ * // Manually trigger cleanup and exit
+ * process.on("SIGUSR2", async () => {
+ *   console.log("Manual shutdown requested");
+ *   await shutdown("EXIT");
+ * });
+ * ```
+ *
+ * @example With error handling
+ * ```typescript
+ * import { dispose } from "@rotorsoft/act";
+ *
+ * dispose(async () => {
+ *   try {
+ *     await expensiveCleanup();
+ *   } catch (error) {
+ *     console.error("Cleanup failed:", error);
+ *     // Error doesn't prevent other disposers from running
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link Disposer} for disposer function type
+ * @see {@link Disposable} for disposable interface
  */
 export declare function dispose(disposer?: Disposer): (code?: ExitCode) => Promise<void>;
 /**
@@ -55,13 +125,82 @@ export declare function dispose(disposer?: Disposer): (code?: ExitCode) => Promi
  */
 export declare const SNAP_EVENT = "__snapshot__";
 /**
- * Singleton event store port. By default, uses the in-memory store.
+ * Gets or injects the singleton event store.
  *
- * You can inject a persistent store (e.g., Postgres) by calling `store(myAdapter)`.
+ * By default, Act uses an in-memory store suitable for development and testing.
+ * For production, inject a persistent store like PostgresStore before building
+ * your application.
  *
- * @example
- * const myStore = store();
- * const customStore = store(new MyCustomStore());
+ * **Important:** Store injection must happen before creating any Act instances.
+ * Once set, the store cannot be changed without restarting the application.
+ *
+ * @param adapter - Optional store implementation to inject
+ * @returns The singleton store instance
+ *
+ * @example Using default in-memory store
+ * ```typescript
+ * import { store } from "@rotorsoft/act";
+ *
+ * const currentStore = store(); // Returns InMemoryStore
+ * ```
+ *
+ * @example Injecting PostgreSQL store
+ * ```typescript
+ * import { store } from "@rotorsoft/act";
+ * import { PostgresStore } from "@rotorsoft/act-pg";
+ *
+ * // Inject before building your app
+ * store(new PostgresStore({
+ *   host: "localhost",
+ *   port: 5432,
+ *   database: "myapp",
+ *   user: "postgres",
+ *   password: "secret",
+ *   schema: "public",
+ *   table: "events"
+ * }));
+ *
+ * // Now build your app - it will use PostgreSQL
+ * const app = act()
+ *   .with(Counter)
+ *   .build();
+ * ```
+ *
+ * @example With environment-based configuration
+ * ```typescript
+ * import { store } from "@rotorsoft/act";
+ * import { PostgresStore } from "@rotorsoft/act-pg";
+ *
+ * if (process.env.NODE_ENV === "production") {
+ *   store(new PostgresStore({
+ *     host: process.env.DB_HOST,
+ *     port: parseInt(process.env.DB_PORT || "5432"),
+ *     database: process.env.DB_NAME,
+ *     user: process.env.DB_USER,
+ *     password: process.env.DB_PASSWORD
+ *   }));
+ * }
+ * // Development uses default in-memory store
+ * ```
+ *
+ * @example Testing with fresh store
+ * ```typescript
+ * import { store } from "@rotorsoft/act";
+ *
+ * beforeEach(async () => {
+ *   // Reset store between tests
+ *   await store().seed();
+ * });
+ *
+ * afterAll(async () => {
+ *   // Cleanup
+ *   await store().drop();
+ * });
+ * ```
+ *
+ * @see {@link Store} for the store interface
+ * @see {@link InMemoryStore} for the default implementation
+ * @see {@link PostgresStore} for production use
  */
 export declare const store: (adapter?: Store | undefined) => Store;
 /**

package/dist/@types/ports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/ports.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EACR,KAAK,EACL,KAAK,EACL,QAAQ,EACR,OAAO,EACP,KAAK,EACN,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS,4BAA6B,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,uCAajB,CAAC;AAEH;;;;;;;;;GASG;AACH,KAAK,QAAQ,CAAC,IAAI,SAAS,UAAU,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,KAAK,IAAI,CAAC;AAElE,wBAAgB,IAAI,CAAC,IAAI,SAAS,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,IACnD,UAAU,IAAI,KAAG,IAAI,CAQvC;AAGD,wBAAsB,cAAc,CAAC,IAAI,GAAE,QAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAa3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CACrB,QAAQ,CAAC,EAAE,QAAQ,GAClB,CAAC,IAAI,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAGpC;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,iBAAiB,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,wCAEhB,CAAC;AAEH;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG;IAChD,OAAO,EAAE,CAAC,CAAC,SAAS,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACxD,UAAU,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IACtC,MAAM,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IAClC,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IACjC,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;CAC7D,CAkDA"}
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/ports.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EACR,KAAK,EACL,KAAK,EACL,QAAQ,EACR,OAAO,EACP,KAAK,EACN,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS,4BAA6B,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,uCAajB,CAAC;AAEH;;;;;;;;;GASG;AACH,KAAK,QAAQ,CAAC,IAAI,SAAS,UAAU,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,KAAK,IAAI,CAAC;AAElE,wBAAgB,IAAI,CAAC,IAAI,SAAS,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,IACnD,UAAU,IAAI,KAAG,IAAI,CAQvC;AAGD,wBAAsB,cAAc,CAAC,IAAI,GAAE,QAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAa3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,wBAAgB,OAAO,CACrB,QAAQ,CAAC,EAAE,QAAQ,GAClB,CAAC,IAAI,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAGpC;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,iBAAiB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,eAAO,MAAM,KAAK,wCAEhB,CAAC;AAEH;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG;IAChD,OAAO,EAAE,CAAC,CAAC,SAAS,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACxD,UAAU,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IACtC,MAAM,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IAClC,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;IACjC,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;CAC7D,CAkDA"}

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

@@ -6,46 +6,170 @@
  */
 import { ZodType } from "zod";
 import { ActionHandler, Invariant, PatchHandlers, Schema, Schemas, Snapshot, State, ZodTypes } from "./types/index.js";
+/**
+ * Builder interface for defining a state with event sourcing.
+ *
+ * Provides a fluent API to configure the initial state, event types,
+ * and event handlers (reducers) before moving to action configuration.
+ *
+ * @template S - State schema type
+ *
+ * @see {@link state} for usage examples
+ * @see {@link ActionBuilder} for action configuration
+ */
 export type StateBuilder<S extends Schema> = {
     /**
-     * Define the initial state for the state machine.
-     * @param init Function returning the initial state
-     * @returns An object with .emits() to declare event types
+     * Defines the initial state for new state instances.
+     *
+     * The init function is called when a new stream is created (first event).
+     * It can accept initial data or return a default state.
+     *
+     * @param init - Function returning the initial state
+     * @returns A builder with `.emits()` to declare event types
+     *
+     * @example
+     * ```typescript
+     * .init(() => ({ count: 0, created: new Date() }))
+     * ```
+     *
+     * @example With initial data
+     * ```typescript
+     * .init((data) => ({ ...data, createdAt: new Date() }))
+     * ```
      */
     init: (init: () => Readonly<S>) => {
         /**
-         * Declare the event types the state machine can emit.
-         * @param events Zod schemas for each event
-         * @returns An object with .patch() to define event handlers
+         * Declares the event types that this state can emit.
+         *
+         * Events represent facts that have happened - they should be named in past tense.
+         * Each event is defined with a Zod schema for type safety and runtime validation.
+         *
+         * @template E - Event schemas type
+         * @param events - Object mapping event names to Zod schemas
+         * @returns A builder with `.patch()` to define event handlers
+         *
+         * @example
+         * ```typescript
+         * .emits({
+         *   Incremented: z.object({ amount: z.number() }),
+         *   Decremented: z.object({ amount: z.number() }),
+         *   Reset: z.object({})
+         * })
+         * ```
          */
         emits: <E extends Schemas>(events: ZodTypes<E>) => {
             /**
-             * Define how each event updates state.
-             * @param patch Event handler functions
+             * Defines how each event updates (patches) the 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
              * @returns An ActionBuilder for defining actions
+             *
+             * @example
+             * ```typescript
+             * .patch({
+             *   Incremented: (event, state) => ({ count: state.count + event.data.amount }),
+             *   Decremented: (event, state) => ({ count: state.count - event.data.amount }),
+             *   Reset: () => ({ count: 0 })
+             * })
+             * ```
              */
             patch: (patch: PatchHandlers<S, E>) => ActionBuilder<S, E, {}>;
         };
     };
 };
+/**
+ * Builder interface for defining actions (commands) on a state.
+ *
+ * Actions represent user/system intents to modify state. Each action is validated
+ * against a schema, can have business rule invariants, and must emit one or more events.
+ *
+ * @template S - State schema type
+ * @template E - Event schemas type
+ * @template A - Action schemas type
+ *
+ * @see {@link state} for complete usage examples
+ */
 export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas> = {
     /**
-     * Define an action for the state machine.
-     * @param action The action name
-     * @param schema The Zod schema for the action payload
-     * @returns An object with .given() and .emit() for further configuration
+     * Defines an action (command) that can be executed on this state.
+     *
+     * Actions represent intents to change state - they should be named in imperative form
+     * (e.g., "createUser", "incrementCounter", "placeOrder"). Actions are validated against
+     * their schema and must emit at least one event.
+     *
+     * @template K - Action name (string literal type)
+     * @template AX - Action payload schema type
+     * @param action - The action name (should be unique within this state)
+     * @param schema - Zod schema for the action payload
+     * @returns An object with `.given()` and `.emit()` for further configuration
+     *
+     * @example Simple action without invariants
+     * ```typescript
+     * .on("increment", z.object({ by: z.number() }))
+     *   .emit((action) => ["Incremented", { amount: action.by }])
+     * ```
+     *
+     * @example Action with business rules
+     * ```typescript
+     * .on("withdraw", z.object({ amount: z.number() }))
+     *   .given([
+     *     (_, snap) => snap.state.balance >= 0 || "Account closed",
+     *     (_, snap, action) => snap.state.balance >= action.amount || "Insufficient funds"
+     *   ])
+     *   .emit((action) => ["Withdrawn", { amount: action.amount }])
+     * ```
+     *
+     * @example Action emitting multiple events
+     * ```typescript
+     * .on("completeOrder", z.object({ orderId: z.string() }))
+     *   .emit((action) => [
+     *     ["OrderCompleted", { orderId: action.orderId }],
+     *     ["InventoryReserved", { orderId: action.orderId }],
+     *     ["PaymentProcessed", { orderId: action.orderId }]
+     *   ])
+     * ```
      */
     on: <K extends string, AX extends Schema>(action: K, schema: ZodType<AX>) => {
         /**
-         * Constrain the action with invariants (business rules).
-         * @param rules Array of invariants
-         * @returns An object with .emit() to finalize the action
+         * Adds business rule invariants that must hold before the action can execute.
+         *
+         * Invariants are checked after loading the current state but before emitting events.
+         * Each invariant should return `true` or an error message string. All invariants
+         * must pass for the action to succeed.
+         *
+         * @param rules - Array of invariant functions
+         * @returns An object with `.emit()` to finalize the action
+         *
+         * @example
+         * ```typescript
+         * .given([
+         *   (_, snap) => snap.state.status === "active" || "Must be active",
+         *   (target, snap) => snap.state.ownerId === target.actor.id || "Not authorized"
+         * ])
+         * ```
          */
         given: (rules: Invariant<S>[]) => {
             /**
-             * Finalize the action by providing the event emission handler.
-             * @param handler The action handler function
-             * @returns The ActionBuilder for chaining
+             * Defines the action handler that emits events.
+             *
+             * The handler receives the action payload and current state snapshot,
+             * 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
+             * @returns The ActionBuilder for chaining more actions
+             *
+             * @example
+             * ```typescript
+             * .emit((action, snapshot) => {
+             *   const newBalance = snapshot.state.balance + action.amount;
+             *   return ["Deposited", { amount: action.amount, newBalance }];
+             * })
+             * ```
              */
             emit: (handler: ActionHandler<S, E, {
                 [P in K]: AX;
@@ -54,9 +178,40 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
             }>;
         };
         /**
-         * Finalize the action by providing the event emission handler.
-         * @param handler The action handler function
-         * @returns The ActionBuilder for chaining
+         * Defines the action handler that emits events.
+         *
+         * The handler receives the action payload and current state snapshot,
+         * 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
+         * @returns The ActionBuilder for chaining more actions
+         *
+         * @example Single event
+         * ```typescript
+         * .emit((action) => ["Incremented", { amount: action.by }])
+         * ```
+         *
+         * @example Multiple events
+         * ```typescript
+         * .emit((action) => [
+         *   ["Incremented", { amount: action.by }],
+         *   ["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;
@@ -65,44 +220,164 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
         }>;
     };
     /**
-     * Define a snapshotting strategy to reduce recomputations.
-     * @param snap Function that determines when to snapshot
+     * Defines a snapshotting strategy to optimize state reconstruction.
+     *
+     * Snapshots store the current state at a point in time, allowing faster state loading
+     * by avoiding replaying all events from the beginning. The snap function is called
+     * after each event is applied and should return `true` when a snapshot should be taken.
+     *
+     * @param snap - Predicate function that returns true when a snapshot should be taken
      * @returns The ActionBuilder for chaining
+     *
+     * @example Snapshot every 10 events
+     * ```typescript
+     * .snap((snapshot) => snapshot.patches >= 10)
+     * ```
+     *
+     * @example Snapshot based on state size
+     * ```typescript
+     * .snap((snapshot) => {
+     *   const estimatedSize = JSON.stringify(snapshot.state).length;
+     *   return estimatedSize > 10000 || snapshot.patches >= 50;
+     * })
+     * ```
+     *
+     * @example Time-based snapshotting
+     * ```typescript
+     * .snap((snapshot) => {
+     *   const hoursSinceLastSnapshot = snapshot.patches * 0.1; // Estimate
+     *   return hoursSinceLastSnapshot >= 24;
+     * })
+     * ```
      */
     snap: (snap: (snapshot: Snapshot<S, E>) => boolean) => ActionBuilder<S, E, A>;
     /**
-     * Finalize and build the state machine definition.
-     * @returns The strongly-typed State definition
+     * Finalizes and builds the state definition.
+     *
+     * Call this method after defining all actions, invariants, and patches to create
+     * the complete State object that can be registered with Act.
+     *
+     * @returns The complete strongly-typed State definition
+     *
+     * @example
+     * ```typescript
+     * 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 }) })
+     *   .on("increment", z.object({ by: z.number() }))
+     *     .emit((action) => ["Incremented", { amount: action.by }])
+     *   .build(); // Returns State<S, E, A>
+     * ```
      */
     build: () => State<S, E, A>;
 };
 /**
- * Fluent interface for defining a strongly-typed state machine using Zod schemas.
+ * Creates a new state definition with event sourcing capabilities.
+ *
+ * States are the core building blocks of Act. Each state represents a consistency
+ * boundary (aggregate) that processes actions, emits events, and maintains its own
+ * state through event patches (reducers). States use event sourcing to maintain a
+ * complete audit trail and enable time-travel capabilities.
+ *
+ * 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()`
+ * 5. Business rules (invariants) via `.given()`
+ * 6. Snapshotting strategy via `.snap()`
  *
- * This builder helps you model a system where:
- * - You start by defining the state schema with `state(name, zodSchema)`
- * - Then, provide the initial state using `.init(() => defaultState)`
- * - Declare the event types your system can emit using `.emits({ ... })`
- * - Define how emitted events update state with `.patch({ ... })`
- * - Define actions using `.on("actionName", actionSchema)`
- *     - Optionally constrain the action with `.given([...invariants])`
- *     - Then finalize the action behavior with `.emit(handler)`
- * - (Optional) Define a `.snap(snapshot => boolean)` function to reduce recomputations
- * - Finalize the state machine definition using `.build()`
+ * @template S - Zod schema type defining the shape of the state
+ * @param name - Unique identifier for this state type (e.g., "Counter", "User", "Order")
+ * @param state - Zod schema defining the structure of the state
+ * @returns A StateBuilder instance for fluent API configuration
  *
- * @template S The type of state
+ * @example Basic counter state
+ * ```typescript
+ * import { state } from "@rotorsoft/act";
+ * import { z } from "zod";
  *
- * @example
- * const machine = state("machine", myStateSchema)
+ * const Counter = state("Counter", z.object({ count: z.number() }))
  *   .init(() => ({ count: 0 }))
- *   .emits({ Incremented: z.object({ amount: z.number() }) })
+ *   .emits({
+ *     Incremented: z.object({ amount: z.number() })
+ *   })
  *   .patch({
- *     Incremented: (event, state) => ({ count: state.count + event.amount })
+ *     Incremented: (event, state) => ({ count: state.count + event.data.amount })
  *   })
  *   .on("increment", z.object({ by: z.number() }))
- *   .given([{ description: "must be positive", valid: (s, a) => a?.by > 0 }])
- *   .emit((action, state) => ({ type: "Incremented", amount: action.by }))
+ *     .emit((action) => ["Incremented", { amount: action.by }])
+ *   .build();
+ * ```
+ *
+ * @example State with multiple events and invariants
+ * ```typescript
+ * const BankAccount = state("BankAccount", z.object({
+ *   balance: z.number(),
+ *   currency: z.string(),
+ *   status: z.enum(["open", "closed"])
+ * }))
+ *   .init(() => ({ balance: 0, currency: "USD", status: "open" }))
+ *   .emits({
+ *     Deposited: z.object({ amount: z.number() }),
+ *     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 }),
+ *     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 }])
+ *   .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 }])
+ *   .on("close", z.object({}))
+ *     .given([
+ *       (_, snap) => snap.state.status === "open" || "Already closed",
+ *       (_, snap) => snap.state.balance === 0 || "Balance must be zero"
+ *     ])
+ *     .emit(() => ["Closed", {}])
  *   .build();
+ * ```
+ *
+ * @example State with snapshotting
+ * ```typescript
+ * const User = state("User", z.object({
+ *   name: z.string(),
+ *   email: z.string(),
+ *   loginCount: z.number()
+ * }))
+ *   .init((data) => ({ ...data, loginCount: 0 }))
+ *   .emits({
+ *     UserCreated: z.object({ name: z.string(), email: z.string() }),
+ *     UserLoggedIn: z.object({})
+ *   })
+ *   .patch({
+ *     UserCreated: (event) => event.data,
+ *     UserLoggedIn: (_, state) => ({ loginCount: state.loginCount + 1 })
+ *   })
+ *   .on("createUser", z.object({ name: z.string(), email: z.string() }))
+ *     .emit((action) => ["UserCreated", action])
+ *   .on("login", z.object({}))
+ *     .emit(() => ["UserLoggedIn", {}])
+ *   .snap((snap) => snap.patches >= 10) // Snapshot every 10 events
+ *   .build();
+ * ```
+ *
+ * @see {@link StateBuilder} for available builder methods
+ * @see {@link ActionBuilder} for action configuration methods
+ * @see {@link https://rotorsoft.github.io/act-root/docs/intro | Getting Started Guide}
+ * @see {@link https://rotorsoft.github.io/act-root/docs/examples/calculator | Calculator Example}
  */
 export declare function state<S extends Schema>(name: string, state: ZodType<S>): StateBuilder<S>;
 //# sourceMappingURL=state-builder.d.ts.map

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":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAC9B,OAAO,EACL,aAAa,EAGb,SAAS,EACT,aAAa,EACb,MAAM,EACN,OAAO,EACP,QAAQ,EACR,KAAK,EACL,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI;IAC3C;;;;OAIG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAK;QACjC;;;;WAIG;QACH,KAAK,EAAE,CAAC,CAAC,SAAS,OAAO,EACvB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,KAChB;YACH;;;;eAIG;YACH,KAAK,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;SAChE,CAAC;KACH,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,aAAa,CACvB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,IACf;IACF;;;;;OAKG;IACH,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,EACtC,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,KAChB;QACH;;;;WAIG;QACH,KAAK,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK;YAChC;;;;eAIG;YACH,IAAI,EAAE,CACJ,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE;iBAAG,CAAC,IAAI,CAAC,GAAG,EAAE;aAAE,EAAE,CAAC,CAAC,KAC9C,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG;iBAAG,CAAC,IAAI,CAAC,GAAG,EAAE;aAAE,CAAC,CAAC;SAChD,CAAC;QACF;;;;WAIG;QACH,IAAI,EAAE,CACJ,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE;aAAG,CAAC,IAAI,CAAC,GAAG,EAAE;SAAE,EAAE,CAAC,CAAC,KAC9C,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG;aAAG,CAAC,IAAI,CAAC,GAAG,EAAE;SAAE,CAAC,CAAC;KAChD,CAAC;IACF;;;;OAIG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO,KAAK,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9E;;;OAGG;IACH,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAChB,YAAY,CAAC,CAAC,CAAC,CAsBjB"}
+{"version":3,"file":"state-builder.d.ts","sourceRoot":"","sources":["../../src/state-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAC9B,OAAO,EACL,aAAa,EAGb,SAAS,EACT,aAAa,EACb,MAAM,EACN,OAAO,EACP,QAAQ,EACR,KAAK,EACL,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI;IAC3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAK;QACjC;;;;;;;;;;;;;;;;;;WAkBG;QACH,KAAK,EAAE,CAAC,CAAC,SAAS,OAAO,EACvB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,KAChB;YACH;;;;;;;;;;;;;;;;;;eAkBG;YACH,KAAK,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;SAChE,CAAC;KACH,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,CACvB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,IACf;IACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,EACtC,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,KAChB;QACH;;;;;;;;;;;;;;;;;WAiBG;QACH,KAAK,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK;YAChC;;;;;;;;;;;;;;;;;eAiBG;YACH,IAAI,EAAE,CACJ,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE;iBAAG,CAAC,IAAI,CAAC,GAAG,EAAE;aAAE,EAAE,CAAC,CAAC,KAC9C,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG;iBAAG,CAAC,IAAI,CAAC,GAAG,EAAE;aAAE,CAAC,CAAC;SAChD,CAAC;QACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAmCG;QACH,IAAI,EAAE,CACJ,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE;aAAG,CAAC,IAAI,CAAC,GAAG,EAAE;SAAE,EAAE,CAAC,CAAC,KAC9C,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG;aAAG,CAAC,IAAI,CAAC,GAAG,EAAE;SAAE,CAAC,CAAC;KAChD,CAAC;IACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO,KAAK,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9E;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0GG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAChB,YAAY,CAAC,CAAC,CAAC,CAsBjB"}