@rotorsoft/act 0.5.1 → 0.5.2

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

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/act.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EACL,KAAK,EAEL,QAAQ,EACR,MAAM,EACN,cAAc,EACd,OAAO,EACP,QAAQ,EACR,KAAK,EACL,MAAM,EACP,MAAM,kBAAkB,CAAC;AAE1B,KAAK,YAAY,GAAG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAE9C;;;;;;;GAOG;AACH,qBAAa,GAAG,CACd,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,EAC3B,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO;aAyBC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;aAC3B,UAAU,EAAE,MAAM;IAxBpC,OAAO,CAAC,QAAQ,CAAsB;IAEtC,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO;IACrD,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO;IAK9C,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IACpE,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI;IAM7D,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IACrE,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI;gBAO5C,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC3B,UAAU,EAAE,MAAM;IAGpC;;;;;;;;;;;;OAYG;IACG,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EACxB,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACvB,UAAU,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAClC,cAAc,UAAQ;IAcxB;;;;;;;;;;OAUG;IACG,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,OAAO,EAAE,EAAE,SAAS,OAAO,EAClE,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACxB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,IAAI,GAC9C,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAI5B;;;;;;OAMG;IACG,KAAK,CACT,KAAK,EAAE,KAAK,EACZ,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,GAChD,OAAO,CAAC;QACT,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9B,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7B,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IAWF;;;;;;OAMG;YACW,MAAM;IA+BpB,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAyG/B"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/act.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EACL,KAAK,EAEL,QAAQ,EACR,MAAM,EACN,cAAc,EACd,OAAO,EACP,QAAQ,EACR,KAAK,EACL,MAAM,EACP,MAAM,kBAAkB,CAAC;AAE1B,KAAK,YAAY,GAAG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,GAAG,CACd,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,EAC3B,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO;aAoDC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;aAC3B,UAAU,EAAE,MAAM;IAnDpC,OAAO,CAAC,QAAQ,CAAsB;IAEtC;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO;IACrD,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO;IAK9C;;;;;;OAMG;IACH,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IACpE,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI;IAM7D;;;;;;OAMG;IACH,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IACrE,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI;IAM9D;;;;;OAKG;gBAEe,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC3B,UAAU,EAAE,MAAM;IAGpC;;;;;;;;;;;;;OAaG;IACG,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EACxB,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACvB,UAAU,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAClC,cAAc,UAAQ;IAcxB;;;;;;;;;;;;;OAaG;IACG,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,OAAO,EAAE,EAAE,SAAS,OAAO,EAClE,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACxB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,IAAI,GAC9C,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAI5B;;;;;;;;;OASG;IACG,KAAK,CACT,KAAK,EAAE,KAAK,EACZ,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,GAChD,OAAO,CAAC;QACT,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9B,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7B,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IAWF;;;;;;;OAOG;YACW,MAAM;IA+BpB,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAyG/B"}

package/dist/@types/adapters/InMemoryStore.d.ts

@@ -1,24 +1,71 @@
 import type { Committed, EventMeta, Lease, Message, Query, Schemas, Store } from "../types/index.js";
 /**
  * @category Adapters
- * @remarks In-memory event store
+ * @see Store
+ *
+ * In-memory implementation of the Store interface.
+ *
+ * Suitable for development, testing, and demonstration. Not for production use.
+ * All events and streams are stored in memory and lost on process exit.
+ *
+ * @example
+ *   const store = new InMemoryStore();
+ *   await store.commit('streamA', [{ name: 'event', data: {} }], meta);
  */
 export declare class InMemoryStore implements Store {
     private _events;
     private _streams;
+    /**
+     * Dispose of the store and clear all events.
+     * @returns Promise that resolves when disposal is complete.
+     */
     dispose(): Promise<void>;
+    /**
+     * Seed the store with initial data (no-op for in-memory).
+     * @returns Promise that resolves when seeding is complete.
+     */
     seed(): Promise<void>;
+    /**
+     * Drop all data from the store.
+     * @returns Promise that resolves when the store is cleared.
+     */
     drop(): Promise<void>;
+    /**
+     * Query events in the store, optionally filtered by query options.
+     * @param callback - Function to call for each event.
+     * @param query - Optional query options.
+     * @returns The number of events processed.
+     */
     query<E extends Schemas>(callback: (event: Committed<E, keyof E>) => void, query?: Query): Promise<number>;
+    /**
+     * Commit one or more events to a stream.
+     * @param stream - The stream name.
+     * @param msgs - The events/messages to commit.
+     * @param meta - Event metadata.
+     * @param expectedVersion - Optional optimistic concurrency check.
+     * @returns The committed events with metadata.
+     * @throws ConcurrencyError if expectedVersion does not match.
+     */
     commit<E extends Schemas>(stream: string, msgs: Message<E, keyof E>[], meta: EventMeta, expectedVersion?: number): Promise<Committed<E, keyof E>[]>;
     /**
-     * Fetches new events from stream watermarks
+     * Fetches new events from stream watermarks for processing.
+     * @param limit - Maximum number of streams to fetch.
+     * @returns Fetched streams and events.
      */
     fetch<E extends Schemas>(limit: number): Promise<{
         streams: string[];
         events: Committed<E, keyof E>[];
     }>;
+    /**
+     * Lease streams for processing (e.g., for distributed consumers).
+     * @param leases - Lease requests.
+     * @returns Granted leases.
+     */
     lease(leases: Lease[]): Promise<Lease[]>;
+    /**
+     * Acknowledge completion of processing for leased streams.
+     * @param leases - Leases to acknowledge.
+     */
     ack(leases: Lease[]): Promise<void>;
 }
 //# sourceMappingURL=InMemoryStore.d.ts.map

package/dist/@types/adapters/InMemoryStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryStore.d.ts","sourceRoot":"","sources":["../../../src/adapters/InMemoryStore.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,KAAK,EACL,OAAO,EACP,KAAK,EACL,OAAO,EACP,KAAK,EACN,MAAM,mBAAmB,CAAC;AA+B3B;;;GAGG;AACH,qBAAa,aAAc,YAAW,KAAK;IAEzC,OAAO,CAAC,OAAO,CAA2C;IAE1D,OAAO,CAAC,QAAQ,CAA0C;IAEpD,OAAO;IAKP,IAAI;IAIJ,IAAI;IAKJ,KAAK,CAAC,CAAC,SAAS,OAAO,EAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,EAChD,KAAK,CAAC,EAAE,KAAK;IA8BT,MAAM,CAAC,CAAC,SAAS,OAAO,EAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,EAC3B,IAAI,EAAE,SAAS,EACf,eAAe,CAAC,EAAE,MAAM;IA4B1B;;OAEG;IACG,KAAK,CAAC,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,MAAM;;;;IAqBtC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE;IAerB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE;CAI1B"}
+{"version":3,"file":"InMemoryStore.d.ts","sourceRoot":"","sources":["../../../src/adapters/InMemoryStore.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,KAAK,EACL,OAAO,EACP,KAAK,EACL,OAAO,EACP,KAAK,EACN,MAAM,mBAAmB,CAAC;AA4C3B;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,KAAK;IAEzC,OAAO,CAAC,OAAO,CAA2C;IAE1D,OAAO,CAAC,QAAQ,CAA0C;IAE1D;;;OAGG;IACG,OAAO;IAKb;;;OAGG;IACG,IAAI;IAIV;;;OAGG;IACG,IAAI;IAKV;;;;;OAKG;IACG,KAAK,CAAC,CAAC,SAAS,OAAO,EAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,EAChD,KAAK,CAAC,EAAE,KAAK;IA8Bf;;;;;;;;OAQG;IACG,MAAM,CAAC,CAAC,SAAS,OAAO,EAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,EAC3B,IAAI,EAAE,SAAS,EACf,eAAe,CAAC,EAAE,MAAM;IA+B1B;;;;OAIG;IACG,KAAK,CAAC,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,MAAM;;;;IAqB5C;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE;IAe3B;;;OAGG;IACG,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE;CAI1B"}

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

@@ -1,29 +1,38 @@
 import { z } from "zod/v4";
 /**
- * Configuration utilities for environment, logging, and package metadata.
+ * Zod schema for validating package.json metadata.
+ * @internal
  */
 export declare const PackageSchema: z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
-    description: z.ZodString;
-    author: z.ZodUnion<[z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         email: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodString]>;
-    license: z.ZodString;
-    dependencies: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>, z.ZodString]>>;
+    license: z.ZodOptional<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
+/**
+ * Type representing the validated package.json metadata.
+ */
 export type Package = z.infer<typeof PackageSchema>;
+/**
+ * Zod schema for the full Act Framework configuration object.
+ * Includes package metadata, environment, logging, and timing options.
+ * @internal
+ */
 declare const BaseSchema: z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
-    description: z.ZodString;
-    author: z.ZodUnion<[z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         email: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodString]>;
-    license: z.ZodString;
-    dependencies: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>, z.ZodString]>>;
+    license: z.ZodOptional<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     env: z.ZodEnum<{
         development: "development";
         test: "test";
@@ -41,7 +50,21 @@ declare const BaseSchema: z.ZodObject<{
     logSingleLine: z.ZodBoolean;
     sleepMs: z.ZodNumber;
 }, z.core.$strip>;
+/**
+ * Type representing the validated Act Framework configuration object.
+ */
 export type Config = z.infer<typeof BaseSchema>;
+/**
+ * Returns the current Act Framework configuration, validated and type-safe.
+ *
+ * Merges package.json metadata with environment, logging, and timing options.
+ * @returns The validated configuration object.
+ * @example
+ * ```ts
+ * const cfg = config();
+ * console.log(cfg.env, cfg.logLevel);
+ * ```
+ */
 export declare const config: () => Config;
 export {};
 //# sourceMappingURL=config.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAS3B;;GAEG;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;iBASxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAOpD,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKd,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAgBhD,eAAO,MAAM,MAAM,QAAO,MAEzB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAS3B;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;iBAWxB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAYpD;;;;GAIG;AACH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKd,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAgBhD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,QAAO,MAEzB,CAAC"}

package/dist/@types/event-sourcing.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @module event-sourcing
+ * @category Event Sourcing
+ *
+ * Utilities for event sourcing, snapshotting, and event store interaction.
+ */
 import type { Committed, Schema, Schemas, Snapshot, State, Target } from "./types/index.js";
 /**
  * Event sourcing utilities for snapshotting, loading, and committing actions/events.
@@ -6,36 +12,51 @@ import type { Committed, Schema, Schemas, Snapshot, State, Target } from "./type
 /**
  * Saves a snapshot of the state to the store.
  *
+ * Snapshots are used to optimize state reconstruction for aggregates with long event streams.
+ *
  * @template S The type of state
  * @template E The type of events
  * @param snapshot The snapshot to save
+ * @returns Promise that resolves when the snapshot is saved
+ *
+ * @example
+ * await snap(snapshot);
  */
 export declare function snap<S extends Schema, E extends Schemas>(snapshot: Snapshot<S, E>): Promise<void>;
 /**
- * Loads a snapshot of the state from the store.
+ * Loads a snapshot of the state from the store by replaying events and applying patches.
  *
  * @template S The type of state
  * @template E The type of events
- * @param me The state machine
- * @param stream The stream to load
- * @param callback The callback to call with the snapshot
+ * @template A The type of actions
+ * @param me The state machine definition
+ * @param stream The stream (instance) to load
+ * @param callback (Optional) Callback to receive the loaded snapshot as it is built
  * @returns The snapshot of the loaded state
+ *
+ * @example
+ * const snapshot = await load(Counter, "counter1");
  */
 export declare function load<S extends Schema, E extends Schemas, A extends Schemas>(me: State<S, E, A>, stream: string, callback?: (snapshot: Snapshot<S, E>) => void): Promise<Snapshot<S, E>>;
 /**
  * Executes an action and emits an event to be committed by the store.
  *
+ * This function validates the action, applies business invariants, emits events, and commits them to the event store.
+ *
  * @template S The type of state
  * @template E The type of events
  * @template A The type of actionSchemas
  * @template K The type of action to execute
- * @param me The state machine
+ * @param me The state machine definition
  * @param action The action to execute
- * @param target The target of the action
+ * @param target The target (stream, actor, etc.)
  * @param payload The payload of the action
- * @param reactingTo The event that the action is reacting to
- * @param skipValidation Whether to skip validation
- * @returns The snapshot of the committed Event
+ * @param reactingTo (Optional) The event that the action is reacting to
+ * @param skipValidation (Optional) Whether to skip validation (not recommended)
+ * @returns The snapshot of the committed event
+ *
+ * @example
+ * const snapshot = await action(Counter, "increment", { stream: "counter1", actor }, { by: 1 });
  */
 export declare function action<S extends Schema, E extends Schemas, A extends Schemas, K extends keyof A>(me: State<S, E, A>, action: K, target: Target, payload: Readonly<A[K]>, reactingTo?: Committed<Schemas, keyof Schemas>, skipValidation?: boolean): Promise<Snapshot<S, E>>;
 //# sourceMappingURL=event-sourcing.d.ts.map

package/dist/@types/event-sourcing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-sourcing.d.ts","sourceRoot":"","sources":["../../src/event-sourcing.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EAGT,MAAM,EACN,OAAO,EACP,QAAQ,EACR,KAAK,EACL,MAAM,EACP,MAAM,kBAAkB,CAAC;AAG1B;;;GAGG;AAEH;;;;;;GAMG;AACH,wBAAsB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,EAC5D,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GACvB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;GASG;AACH,wBAAsB,IAAI,CACxB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,EAEjB,EAAE,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,GAC5C,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAuBzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,MAAM,CAC1B,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,MAAM,CAAC,EAEjB,EAAE,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAClB,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACvB,UAAU,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,EAC9C,cAAc,UAAQ,GACrB,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAoFzB"}
+{"version":3,"file":"event-sourcing.d.ts","sourceRoot":"","sources":["../../src/event-sourcing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EACV,SAAS,EAGT,MAAM,EACN,OAAO,EACP,QAAQ,EACR,KAAK,EACL,MAAM,EACP,MAAM,kBAAkB,CAAC;AAG1B;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,EAC5D,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GACvB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,IAAI,CACxB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,EAEjB,EAAE,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,GAC5C,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAuBzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,MAAM,CAC1B,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,MAAM,CAAC,EAEjB,EAAE,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAClB,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACvB,UAAU,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,EAC9C,cAAc,UAAQ,GACrB,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAoFzB"}

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

@@ -1,13 +1,14 @@
-import { config } from "./config.js";
+import "./signals.js";
 /**
+ * @packageDocumentation
  * @module act
  * Main entry point for the Act framework. Re-exports all core APIs.
  */
 export * from "./act-builder.js";
 export * from "./act.js";
+export * from "./config.js";
 export * from "./ports.js";
 export * from "./state-builder.js";
 export * from "./types/index.js";
 export * from "./utils.js";
-export { config };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC;;;GAGG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,cAAc,CAAC;AAEtB;;;;GAIG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC"}

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

@@ -1,21 +1,68 @@
 import type { Disposable, Disposer, Store } from "./types/index.js";
 /**
  * Port and adapter utilities for logging, store management, and resource disposal.
- * Provides singleton store and logger instances.
+ *
+ * Provides singleton store and logger instances, and helpers for resource lifecycle management.
+ *
+ * - Use `store()` to get or inject the event store (in-memory or persistent).
+ * - Use `logger` for structured logging.
+ * - Use `dispose()` to register resource disposers for graceful shutdown.
+ *
+ * @module ports
+ */
+/**
+ * List of exit codes for process termination.
  */
 export declare const ExitCodes: readonly ["ERROR", "EXIT"];
+/**
+ * Type for allowed exit codes.
+ */
 export type ExitCode = (typeof ExitCodes)[number];
+/**
+ * Singleton logger instance (Pino).
+ *
+ * Use for structured logging throughout your application.
+ *
+ * @example
+ * logger.info("Application started");
+ */
 export declare const logger: import("pino").Logger<never, boolean>;
+/**
+ * Helper to create a singleton port (adapter) with optional injection.
+ *
+ * @param injector The function that creates the port/adapter
+ * @returns A function to get or inject the singleton instance
+ *
+ * @example
+ * const store = port((adapter) => adapter || new InMemoryStore());
+ * const myStore = store();
+ */
 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
- * @param disposer the disposer function
- * @returns a function that triggers all registered disposers and terminates the process
+ * Registers resource disposers that are triggered on process exit.
+ *
+ * @param disposer The disposer function to register
+ * @returns A function that triggers all registered disposers and terminates the process
+ *
+ * @example
+ * dispose(async () => { await myResource.close(); });
  */
 export declare function dispose(disposer?: Disposer): (code?: ExitCode) => Promise<void>;
+/**
+ * Special event name for snapshot events in the event store.
+ */
 export declare const SNAP_EVENT = "__snapshot__";
+/**
+ * Singleton event store port. By default, uses the in-memory store.
+ *
+ * You can inject a persistent store (e.g., Postgres) by calling `store(myAdapter)`.
+ *
+ * @example
+ * const myStore = store();
+ * const customStore = store(new MyCustomStore());
+ */
 export declare const store: (adapter?: Store | undefined) => Store;
 export {};
 //# sourceMappingURL=ports.d.ts.map

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,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEpE;;;GAGG;AAEH,eAAO,MAAM,SAAS,4BAA6B,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD,eAAO,MAAM,MAAM,uCAajB,CAAC;AAEH,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;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,QAAQ,CAAC,EAAE,QAAQ,GAClB,CAAC,IAAI,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAGpC;AAGD,eAAO,MAAM,UAAU,iBAAiB,CAAC;AACzC,eAAO,MAAM,KAAK,wCAEhB,CAAC"}
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/ports.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEpE;;;;;;;;;;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"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=signals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../../src/signals.ts"],"names":[],"mappings":""}

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

@@ -1,28 +1,79 @@
+/**
+ * @module state-builder
+ * @category Builders
+ *
+ * Fluent interface for defining a strongly-typed state machine using Zod schemas.
+ */
 import { ZodType } from "zod/v4";
 import { ActionHandler, Invariant, PatchHandlers, Schema, Schemas, Snapshot, State, ZodTypes } from "./types/index.js";
 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
+     */
     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
+         */
         emits: <E extends Schemas>(events: ZodTypes<E>) => {
+            /**
+             * Define how each event updates state.
+             * @param patch Event handler functions
+             * @returns An ActionBuilder for defining actions
+             */
             patch: (patch: PatchHandlers<S, E>) => ActionBuilder<S, E, {}>;
         };
     };
 };
 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
+     */
     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
+         */
         given: (rules: Invariant<S>[]) => {
+            /**
+             * Finalize the action by providing the event emission handler.
+             * @param handler The action handler function
+             * @returns The ActionBuilder for chaining
+             */
             emit: (handler: ActionHandler<S, E, {
                 [P in K]: AX;
             }, K>) => ActionBuilder<S, E, A & {
                 [P in K]: AX;
             }>;
         };
+        /**
+         * Finalize the action by providing the event emission handler.
+         * @param handler The action handler function
+         * @returns The ActionBuilder for chaining
+         */
         emit: (handler: ActionHandler<S, E, {
             [P in K]: AX;
         }, K>) => ActionBuilder<S, E, A & {
             [P in K]: AX;
         }>;
     };
+    /**
+     * Define a snapshotting strategy to reduce recomputations.
+     * @param snap Function that determines when to snapshot
+     * @returns The ActionBuilder for chaining
+     */
     snap: (snap: (snapshot: Snapshot<S, E>) => boolean) => ActionBuilder<S, E, A>;
+    /**
+     * Finalize and build the state machine definition.
+     * @returns The strongly-typed State definition
+     */
     build: () => State<S, E, A>;
 };
 /**
@@ -39,8 +90,9 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
  * - (Optional) Define a `.snap(snapshot => boolean)` function to reduce recomputations
  * - Finalize the state machine definition using `.build()`
  *
- * Example usage:
- * ```ts
+ * @template S The type of state
+ *
+ * @example
  * const machine = state("machine", myStateSchema)
  *   .init(() => ({ count: 0 }))
  *   .emits({ Incremented: z.object({ amount: z.number() }) })
@@ -51,7 +103,6 @@ export type ActionBuilder<S extends Schema, E extends Schemas, A extends Schemas
  *   .given([{ description: "must be positive", valid: (s, a) => a?.by > 0 }])
  *   .emit((action, state) => ({ type: "Incremented", amount: action.by }))
  *   .build();
- * ```
  */
 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,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,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,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAK;QACjC,KAAK,EAAE,CAAC,CAAC,SAAS,OAAO,EACvB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,KAChB;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,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,EACtC,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,KAChB;QACH,KAAK,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK;YAChC,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,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,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,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,QAAQ,CAAC;AACjC,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"}

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

@@ -1,54 +1,159 @@
 import { z, ZodType } from "zod/v4";
 import { ActorSchema, CausationEventSchema, CommittedMetaSchema, EventMetaSchema, QuerySchema, TargetSchema } from "./schemas.js";
+/**
+ * @packageDocumentation
+ * @module act/types
+ * @category Types
+ * Types for actions, events, schemas, and state in the Act Framework.
+ */
+/**
+ * Represents an actor (user, system, etc.) that initiates actions or events.
+ */
 export type Actor = z.infer<typeof ActorSchema>;
+/**
+ * Represents the target of an action or event, including stream and actor info.
+ */
 export type Target = z.infer<typeof TargetSchema>;
+/**
+ * Metadata describing the causation of an event.
+ */
 export type CausationEvent = z.infer<typeof CausationEventSchema>;
+/**
+ * Metadata attached to an event, including correlation and causation.
+ */
 export type EventMeta = z.infer<typeof EventMetaSchema>;
+/**
+ * Metadata attached to a committed event, including id, stream, version, and creation time.
+ */
 export type CommittedMeta = z.infer<typeof CommittedMetaSchema>;
+/**
+ * Query options for event store queries.
+ */
 export type Query = z.infer<typeof QuerySchema>;
+/**
+ * A generic schema definition (plain object shape).
+ */
 export type Schema = Record<string, any>;
+/**
+ * A map of named schemas.
+ */
 export type Schemas = Record<string, Schema>;
+/**
+ * An empty schema (no properties).
+ */
 export type EmptySchema = Record<string, never>;
+/**
+ * A recursive partial type for patching state objects.
+ * @template T - The base type to patch.
+ */
 export type Patch<T> = {
     [K in keyof T]?: T[K] extends Schema ? Patch<T[K]> : T[K];
 };
+/**
+ * Maps schema names to their Zod type representations.
+ * @template T - The schemas map.
+ */
 export type ZodTypes<T extends Schemas> = {
     [K in keyof T]: ZodType<T[K]>;
 };
+/**
+ * Represents a message (event or action) with a name and data payload.
+ * @template E - Schemas map.
+ * @template K - Event/action name.
+ */
 export type Message<E extends Schemas, K extends keyof E> = {
     readonly name: K;
     readonly data: Readonly<E[K]>;
 };
+/**
+ * A committed event, including metadata.
+ * @template E - Schemas map.
+ * @template K - Event name.
+ */
 export type Committed<E extends Schemas, K extends keyof E> = Message<E, K> & CommittedMeta;
+/**
+ * Represents a snapshot of state at a point in the event stream.
+ * @template S - State schema.
+ * @template E - Event schemas.
+ */
 export type Snapshot<S extends Schema, E extends Schemas> = {
     readonly state: S;
     readonly event?: Committed<E, keyof E>;
     readonly patches: number;
     readonly snaps: number;
 };
+/**
+ * An invariant is a condition that must always hold true for a state.
+ * @template S - State schema.
+ */
 export type Invariant<S extends Schema> = {
     description: string;
     valid: (state: Readonly<S>, actor?: Actor) => boolean;
 };
+/**
+ * Represents an emitted event tuple from an action handler.
+ * @template E - Event schemas.
+ */
 export type Emitted<E extends Schemas> = {
     [K in keyof E]: readonly [K, Readonly<E[K]>];
 }[keyof E];
+/**
+ * Bundles the Zod types for state, events, and actions.
+ * @template S - State schema.
+ * @template E - Event schemas.
+ * @template A - Action schemas.
+ */
 export type StateSchemas<S extends Schema, E extends Schemas, A extends Schemas> = {
     readonly events: ZodTypes<E>;
     readonly actions: ZodTypes<A>;
     readonly state: ZodType<S>;
 };
+/**
+ * Handles patching state in response to a committed event.
+ * @template S - State schema.
+ * @template E - Event schemas.
+ * @template K - Event name.
+ */
 export type PatchHandler<S extends Schema, E extends Schemas, K extends keyof E> = (event: Committed<E, K>, state: Readonly<S>) => Readonly<Patch<S>>;
+/**
+ * Maps event names to their patch handlers.
+ * @template S - State schema.
+ * @template E - Event schemas.
+ */
 export type PatchHandlers<S extends Schema, E extends Schemas> = {
     [K in keyof E]: PatchHandler<S, E, K>;
 };
+/**
+ * Handles an action, producing one or more emitted events.
+ * @template S - State schema.
+ * @template E - Event schemas.
+ * @template A - Action schemas.
+ * @template K - Action name.
+ */
 export type ActionHandler<S extends Schema, E extends Schemas, A extends Schemas, K extends keyof A> = (action: Readonly<A[K]>, state: Readonly<S>, target: Target) => Emitted<E> | Emitted<E>[] | undefined;
+/**
+ * Maps action names to their handlers.
+ * @template S - State schema.
+ * @template E - Event schemas.
+ * @template A - Action schemas.
+ */
 export type ActionHandlers<S extends Schema, E extends Schemas, A extends Schemas> = {
     [K in keyof A]: ActionHandler<S, E, A, K>;
 };
+/**
+ * Maps action names to invariants that must hold after the action.
+ * @template S - State schema.
+ * @template A - Action schemas.
+ */
 export type GivenHandlers<S extends Schema, A extends Schemas> = {
     [K in keyof A]?: Invariant<S>[];
 };
+/**
+ * The full state definition, including schemas, handlers, and optional invariants and snapshot logic.
+ * @template S - State schema.
+ * @template E - Event schemas.
+ * @template A - Action schemas.
+ */
 export type State<S extends Schema, E extends Schemas, A extends Schemas> = StateSchemas<S, E, A> & {
     name: string;
     init: () => Readonly<S>;

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

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