@rotorsoft/act 0.35.1 → 0.36.0

package/dist/@types/adapters/console-logger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module adapters/console-logger
+ *
+ * High-performance console logger inspired by pino's design:
+ * - Numeric level comparison for O(1) gating
+ * - stdout.write() in production for raw JSON lines (no console overhead)
+ * - Colorized single-line output in development
+ * - No-op method replacement when level is above threshold
+ * - Child logger support with merged bindings
+ */
+import type { Logger } from "../types/index.js";
+/**
+ * Default console logger for the Act framework.
+ *
+ * Production mode emits newline-delimited JSON (compatible with GCP, AWS
+ * CloudWatch, Datadog, and other structured log ingestion systems).
+ *
+ * Development mode emits colorized, human-readable output.
+ */
+export declare class ConsoleLogger implements Logger {
+    level: string;
+    private readonly _pretty;
+    readonly fatal: Logger["fatal"];
+    readonly error: Logger["error"];
+    readonly warn: Logger["warn"];
+    readonly info: Logger["info"];
+    readonly debug: Logger["debug"];
+    readonly trace: Logger["trace"];
+    constructor(options?: {
+        level?: string;
+        pretty?: boolean;
+        bindings?: Record<string, unknown>;
+    });
+    /** No-op — `console.log` has no resources to release. */
+    dispose(): Promise<void>;
+    /** @inheritDoc */
+    child(bindings: Record<string, unknown>): Logger;
+    private _jsonWrite;
+    private _prettyWrite;
+}
+//# sourceMappingURL=console-logger.d.ts.map

package/dist/@types/adapters/console-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-logger.d.ts","sourceRoot":"","sources":["../../../src/adapters/console-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAwBhD;;;;;;;GAOG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;gBAG9B,OAAO,GAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B;IAwBR,yDAAyD;IACnD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAE9B,kBAAkB;IAClB,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAQhD,OAAO,CAAC,UAAU;IAwClB,OAAO,CAAC,YAAY;CAmCrB"}

package/dist/@types/adapters/in-memory-cache.d.ts

@@ -0,0 +1,34 @@
+import type { Cache, CacheEntry, Schema } from "../types/index.js";
+/**
+ * In-memory LRU cache for stream snapshots.
+ *
+ * Backed by an internal `LruMap` for O(1) get/set with LRU eviction.
+ * Configurable `maxSize` bounds memory usage.
+ *
+ * @example
+ * ```typescript
+ * import { cache } from "@rotorsoft/act";
+ * import { InMemoryCache } from "@rotorsoft/act";
+ *
+ * cache(new InMemoryCache({ maxSize: 500 }));
+ * ```
+ */
+export declare class InMemoryCache implements Cache {
+    private readonly _entries;
+    constructor(options?: {
+        maxSize?: number;
+    });
+    /** @inheritDoc */
+    get<TState extends Schema>(stream: string): Promise<CacheEntry<TState> | undefined>;
+    /** @inheritDoc */
+    set<TState extends Schema>(stream: string, entry: CacheEntry<TState>): Promise<void>;
+    /** @inheritDoc */
+    invalidate(stream: string): Promise<void>;
+    /** @inheritDoc */
+    clear(): Promise<void>;
+    /** @inheritDoc */
+    dispose(): Promise<void>;
+    /** Current number of entries held by the LRU. */
+    get size(): number;
+}
+//# sourceMappingURL=in-memory-cache.d.ts.map

package/dist/@types/adapters/in-memory-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-cache.d.ts","sourceRoot":"","sources":["../../../src/adapters/in-memory-cache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEnE;;;;;;;;;;;;;GAaG;AAEH,qBAAa,aAAc,YAAW,KAAK;IAIzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;gBAE/C,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAI1C,kBAAkB;IACZ,GAAG,CAAC,MAAM,SAAS,MAAM,EAC7B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAI1C,kBAAkB;IACZ,GAAG,CAAC,MAAM,SAAS,MAAM,EAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC,IAAI,CAAC;IAIhB,kBAAkB;IACZ,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,kBAAkB;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,kBAAkB;IACZ,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/@types/adapters/in-memory-store.d.ts

@@ -0,0 +1,202 @@
+import type { BlockedLease, Committed, EventMeta, Lease, Message, PrioritizeFilter, Query, QueryStreams, QueryStreamsResult, Schema, Schemas, Store, StreamPosition } from "../types/index.js";
+/**
+ * In-memory event store implementation.
+ *
+ * This is the default store used by Act when no other store is injected.
+ * It stores all events in memory and is suitable for:
+ * - Development and prototyping
+ * - Unit and integration testing
+ * - Demonstrations and examples
+ *
+ * **Not suitable for production** - all data is lost when the process exits.
+ * Use {@link PostgresStore} for production deployments.
+ *
+ * The in-memory store provides:
+ * - Full {@link Store} interface implementation
+ * - Optimistic concurrency control
+ * - Stream leasing for distributed processing simulation
+ * - Snapshot support
+ * - Fast performance (no I/O overhead)
+ *
+ * **`Store.notify` is intentionally not implemented.** The notify hook is a
+ * cross-process wake-up signal — local commits already arm the drain via
+ * `do()`. An in-memory store is single-process by definition, so there is
+ * no remote writer to be notified of. The {@link Act} orchestrator
+ * detects the absence and falls back to the existing debounce/poll path.
+ *
+ * @example Using in tests
+ * ```typescript
+ * import { store } from "@rotorsoft/act";
+ *
+ * describe("Counter", () => {
+ *   beforeEach(async () => {
+ *     // Reset store between tests
+ *     await store().seed();
+ *   });
+ *
+ *   it("increments", async () => {
+ *     await app.do("increment", target, { by: 5 });
+ *     const snapshot = await app.load(Counter, "counter-1");
+ *     expect(snapshot.state.count).toBe(5);
+ *   });
+ * });
+ * ```
+ *
+ * @example Explicit instantiation
+ * ```typescript
+ * import { InMemoryStore } from "@rotorsoft/act";
+ *
+ * const testStore = new InMemoryStore();
+ * await testStore.seed();
+ *
+ * // Use for specific test scenarios
+ * await testStore.commit("test-stream", events, meta);
+ * ```
+ *
+ * @example Querying events
+ * ```typescript
+ * const events: any[] = [];
+ * await store().query(
+ *   (event) => events.push(event),
+ *   { stream: "test-stream" }
+ * );
+ * console.log(`Found ${events.length} events`);
+ * ```
+ *
+ * @see {@link Store} for the interface definition
+ * @see {@link PostgresStore} for production use
+ * @see {@link store} for injecting stores
+ *
+ * @category Adapters
+ */
+export declare class InMemoryStore implements Store {
+    private _events;
+    private _streams;
+    private _streamVersions;
+    private _maxEventIdByStream;
+    private _maxNonSnapEventId;
+    private _resetIndexes;
+    /**
+     * 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>;
+    private in_query;
+    /**
+     * 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>[]>;
+    /**
+     * Atomically discovers and leases streams for processing.
+     * Fuses poll + lease into a single operation.
+     * @param lagging - Max streams from lagging frontier.
+     * @param leading - Max streams from leading frontier.
+     * @param by - Lease holder identifier.
+     * @param millis - Lease duration in milliseconds.
+     * @returns Granted leases.
+     */
+    claim(lagging: number, leading: number, by: string, millis: number): Promise<Lease[]>;
+    /**
+     * Registers streams for event processing. When the same stream is
+     * resubscribed with a different priority, the **maximum** wins — so
+     * the highest-priority registered reaction sets the scheduling lane.
+     * Use {@link prioritize} for operator runtime overrides.
+     *
+     * @param streams - Streams to register with optional source + priority.
+     * @returns subscribed count and current max watermark.
+     */
+    subscribe(streams: Array<{
+        stream: string;
+        source?: string;
+        priority?: number;
+    }>): Promise<{
+        subscribed: number;
+        watermark: number;
+    }>;
+    /**
+     * Acknowledge completion of processing for leased streams.
+     * @param leases - Leases to acknowledge, including last processed watermark and lease holder.
+     */
+    ack(leases: Lease[]): Promise<{
+        stream: string;
+        source: string | undefined;
+        at: number;
+        by: string;
+        retry: number;
+        lagging: boolean;
+    }[]>;
+    /**
+     * Block a stream for processing after failing to process and reaching max retries with blocking enabled.
+     * @param leases - Leases to block, including lease holder and last error message.
+     * @returns Blocked leases.
+     */
+    block(leases: BlockedLease[]): Promise<{
+        stream: string;
+        source: string | undefined;
+        at: number;
+        by: string;
+        retry: number;
+        error: string;
+        lagging: boolean;
+    }[]>;
+    /**
+     * Reset watermarks for the given streams to -1, clearing retry, blocked,
+     * error, and lease state so they can be replayed from the beginning.
+     * @param streams - Stream names to reset.
+     * @returns Count of streams that were actually reset.
+     */
+    reset(streams: string[]): Promise<number>;
+    /**
+     * Bulk-update priority of streams matching `filter`. Mirrors
+     * {@link query_streams}'s filter semantics — see {@link Store.prioritize}.
+     * Unlike {@link subscribe} (which keeps `max()` of registered
+     * priorities), this sets the priority outright — operator override
+     * for the build-time scheduling policy.
+     *
+     * @returns Count of streams whose priority changed.
+     */
+    prioritize(filter: PrioritizeFilter, priority: number): Promise<number>;
+    /**
+     * Streams registered subscription positions to the callback, ordered by
+     * stream name. Returns the highest event id in the store and the count
+     * of positions emitted.
+     */
+    query_streams(callback: (position: StreamPosition) => void, query?: QueryStreams): Promise<QueryStreamsResult>;
+    /**
+     * Atomically truncates streams and seeds each with a snapshot or tombstone.
+     * @param targets - Streams to truncate with optional snapshot state and meta.
+     * @returns Map keyed by stream name, each entry with `deleted` count and `committed` event.
+     */
+    truncate(targets: Array<{
+        stream: string;
+        snapshot?: Schema;
+        meta?: EventMeta;
+    }>): Promise<Map<string, {
+        deleted: number;
+        committed: Committed<Schemas, keyof Schemas>;
+    }>>;
+}
+//# sourceMappingURL=in-memory-store.d.ts.map

package/dist/@types/adapters/in-memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-store.d.ts","sourceRoot":"","sources":["../../../src/adapters/in-memory-store.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,KAAK,EACL,OAAO,EACP,gBAAgB,EAChB,KAAK,EACL,YAAY,EACZ,kBAAkB,EAClB,MAAM,EACN,OAAO,EACP,KAAK,EACL,cAAc,EACf,MAAM,mBAAmB,CAAC;AA0J3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,qBAAa,aAAc,YAAW,KAAK;IAEzC,OAAO,CAAC,OAAO,CAA2C;IAE1D,OAAO,CAAC,QAAQ,CAA0C;IAE1D,OAAO,CAAC,eAAe,CAAkC;IAGzD,OAAO,CAAC,mBAAmB,CAAkC;IAE7D,OAAO,CAAC,kBAAkB,CAAM;IAEhC,OAAO,CAAC,aAAa;IAOrB;;;OAGG;IACG,OAAO;IAKb;;;OAGG;IACG,IAAI;IAIV;;;OAGG;IACG,IAAI;IAMV,OAAO,CAAC,QAAQ;IAahB;;;;;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;IAiCf;;;;;;;;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;IA2C1B;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IA8DxE;;;;;;;;OAQG;IACG,SAAS,CACb,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;;;;IAoBxE;;;OAGG;IACG,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE;;;;;;;;IAOzB;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE;;;;;;;;;IAOlC;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE;IAa7B;;;;;;;;OAQG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM;IAuC3D;;;;OAIG;IACG,aAAa,CACjB,QAAQ,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,EAC5C,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,kBAAkB,CAAC;IAwD9B;;;;OAIG;IACG,QAAQ,CACZ,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,SAAS,CAAC;KAClB,CAAC;iBAmBW,MAAM;mBAAa,SAAS,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;;CA6BpE"}

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

@@ -0,0 +1,4 @@
+export { ConsoleLogger } from "./console-logger.js";
+export { InMemoryCache } from "./in-memory-cache.js";
+export { InMemoryStore } from "./in-memory-store.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

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

@@ -0,0 +1,160 @@
+/**
+ * @module act-builder
+ * @category Builders
+ *
+ * Fluent builder for composing event-sourced applications.
+ */
+import { Act, type ActOptions } from "../act.js";
+import type { Actor, Committed, EventRegister, IAct, ReactionOptions, ReactionResolver, Schema, SchemaRegister, Schemas, Snapshot, State } from "../types/index.js";
+import type { Projection } from "./projection-builder.js";
+import type { Slice } from "./slice-builder.js";
+/**
+ * Fluent builder interface for composing event-sourced applications.
+ *
+ * Provides a chainable API for:
+ * - Registering states via `.withState()`
+ * - Registering slices via `.withSlice()`
+ * - Registering projections via `.withProjection()`
+ * - Locking a custom actor type via `.withActor<TActor>()`
+ * - Defining event reactions via `.on()` → `.do()` → `.to()`
+ * - Building the orchestrator via `.build()`
+ *
+ * @template TSchemaReg - Schema register for states (maps action names to state schemas)
+ * @template TEvents - Event schemas (maps event names to event data schemas)
+ * @template TActions - Action schemas (maps action names to action payload schemas)
+ * @template TStateMap - Map of state names to state schemas
+ * @template TActor - Actor type extending base Actor
+ *
+ * @see {@link act} for usage examples
+ * @see {@link Act} for the built orchestrator API
+ */
+export type ActBuilder<TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas, TStateMap extends Record<string, Schema> = {}, TActor extends Actor = Actor> = {
+    /**
+     * Registers a state definition with the builder.
+     *
+     * State names, action names, and event names must be unique across the
+     * application (partial states with the same name are merged automatically).
+     *
+     * @throws {Error} If duplicate action or event names are detected
+     */
+    withState: <TNewState extends Schema, TNewEvents extends Schemas, TNewActions extends Schemas, TNewName extends string = string>(state: State<TNewState, TNewEvents, TNewActions, TNewName>) => ActBuilder<TSchemaReg & {
+        [K in keyof TNewActions]: TNewState;
+    }, TEvents & TNewEvents, TActions & TNewActions, TStateMap & {
+        [K in TNewName]: TNewState;
+    }, TActor>;
+    /**
+     * Registers a slice with the builder.
+     *
+     * Merges all the slice's states and reactions into the application.
+     * State names, action names, and event names must be unique across the
+     * application (partial states with the same name are merged automatically).
+     *
+     * @throws {Error} If duplicate action or event names are detected
+     */
+    withSlice: <TNewSchemaReg extends SchemaRegister<TNewActions>, TNewEvents extends Schemas, TNewActions extends Schemas, TNewMap extends Record<string, Schema>>(slice: Slice<TNewSchemaReg, TNewEvents, TNewActions, TNewMap>) => ActBuilder<TSchemaReg & TNewSchemaReg, TEvents & TNewEvents, TActions & TNewActions, TStateMap & TNewMap, TActor>;
+    /**
+     * Registers a standalone projection with the builder.
+     *
+     * The projection's events must be a subset of events already registered
+     * via `.withState()` or `.withSlice()`.
+     */
+    withProjection: <TNewEvents extends Schemas>(projection: [Exclude<keyof TNewEvents, keyof TEvents>] extends [never] ? Projection<TNewEvents> : never) => ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor>;
+    /**
+     * Locks a custom actor type for this application.
+     *
+     * This is a pure type-level method — it returns the same builder at
+     * runtime but narrows the `TActor` generic so that `app.do()` and
+     * reaction dispatchers require the richer actor shape.
+     *
+     * @template TNewActor - Custom actor type extending base Actor
+     * @returns The same builder with `TActor` locked to `TNewActor`
+     *
+     * @example
+     * ```typescript
+     * type MyActor = { id: string; name: string; role: string; tenantId: string };
+     *
+     * const app = act()
+     *   .withActor<MyActor>()
+     *   .withState(Counter)
+     *   .build();
+     *
+     * // Now app.do() requires MyActor in the target
+     * await app.do("increment", {
+     *   stream: "counter-1",
+     *   actor: { id: "1", name: "Alice", role: "admin", tenantId: "t1" }
+     * }, { by: 5 });
+     * ```
+     */
+    withActor: <TNewActor extends Actor>() => ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TNewActor>;
+    /**
+     * 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 TKey - 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
+     */
+    on: <TKey extends keyof TEvents>(event: TKey) => {
+        do: (handler: (event: Committed<TEvents, TKey>, stream: string, app: IAct<TEvents, TActions, TActor>) => Promise<Snapshot<Schema, TEvents> | void>, options?: Partial<ReactionOptions>) => ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor> & {
+            to: (resolver: ReactionResolver<TEvents, TKey> | string) => ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor>;
+        };
+    };
+    /**
+     * Builds and returns the Act orchestrator instance.
+     *
+     * @param options - Optional runtime overrides (see {@link ActOptions}).
+     * @returns The Act orchestrator instance
+     *
+     * @see {@link Act} for available orchestrator methods
+     */
+    build: (options?: ActOptions) => Act<TSchemaReg, TEvents, TActions, TStateMap, TActor>;
+    /**
+     * The registered event schemas and their reaction maps.
+     */
+    readonly events: EventRegister<TEvents>;
+};
+/**
+ * Creates a new Act orchestrator builder for composing event-sourced applications.
+ *
+ * @example Basic application with single state
+ * ```typescript
+ * const app = act()
+ *   .withState(Counter)
+ *   .build();
+ * ```
+ *
+ * @example Application with custom actor type
+ * ```typescript
+ * type MyActor = { id: string; name: string; role: string };
+ *
+ * const app = act()
+ *   .withActor<MyActor>()
+ *   .withState(Counter)
+ *   .build();
+ * ```
+ *
+ * @example Application with slices (vertical slice architecture)
+ * ```typescript
+ * const CounterSlice = slice()
+ *   .withState(Counter)
+ *   .on("Incremented")
+ *     .do(async (event) => { console.log("incremented!"); })
+ *     .to("counter-target")
+ *   .build();
+ *
+ * const app = act()
+ *   .withSlice(CounterSlice)
+ *   .build();
+ * ```
+ *
+ *
+ * @see {@link ActBuilder} for available builder methods
+ * @see {@link Act} for orchestrator API methods
+ * @see {@link state} for defining states
+ * @see {@link slice} for defining slices
+ */
+export declare function act<TSchemaReg extends SchemaRegister<TActions> = {}, TEvents extends Schemas = {}, TActions extends Schemas = {}, TStateMap extends Record<string, Schema> = {}, TActor extends Actor = Actor>(): ActBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor>;
+//# sourceMappingURL=act-builder.d.ts.map

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

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

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

@@ -0,0 +1,13 @@
+/**
+ * @module builders
+ * @category Builders
+ *
+ * Public-facing fluent builders for composing event-sourced applications:
+ * `state` (aggregates), `slice` (vertical-slice modules), `projection`
+ * (read-model updaters), and `act` (the orchestrator builder).
+ */
+export * from "./act-builder.js";
+export * from "./projection-builder.js";
+export * from "./slice-builder.js";
+export * from "./state-builder.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}

package/dist/@types/builders/projection-builder.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @module projection-builder
+ * @category Builders
+ *
+ * Fluent builder for composing projection handlers — read-model updaters
+ * that react to events and update external state (databases, caches, etc.).
+ *
+ * Projections differ from slices: they don't contain states, don't dispatch
+ * actions, and are pure side-effect handlers routed to a named stream.
+ */
+import type { ZodType } from "zod";
+import type { BatchHandler, Committed, EventRegister, ReactionResolver, Schema, Schemas } from "../types/index.js";
+/**
+ * A self-contained projection grouping read-model update handlers.
+ * Projections are composed into an Act orchestrator via `act().withProjection(projection)`.
+ *
+ * @template TEvents - Event schemas handled by this projection
+ */
+export type Projection<TEvents extends Schemas> = {
+    readonly _tag: "Projection";
+    readonly events: EventRegister<TEvents>;
+    readonly target?: string;
+    readonly batchHandler?: BatchHandler<TEvents>;
+};
+/** Helper: a single-key record mapping an event name to its Zod schema. */
+type EventEntry<TKey extends string = string, TData extends Schema = Schema> = {
+    [P in TKey]: ZodType<TData>;
+};
+/** Infer the handler-result type after registering one event. */
+type DoResult<TEvents extends Schemas, TKey extends string, TData extends Schema, TTarget extends string | undefined = undefined> = ProjectionBuilder<TEvents & {
+    [P in TKey]: TData;
+}, TTarget> & {
+    to: (resolver: ReactionResolver<TEvents & {
+        [P in TKey]: TData;
+    }, TKey> | string) => ProjectionBuilder<TEvents & {
+        [P in TKey]: TData;
+    }, TTarget>;
+};
+/**
+ * Fluent builder interface for composing projections.
+ *
+ * When a static target is provided via `projection("target")`, the builder
+ * exposes a `.batch()` method for registering a batch handler that processes
+ * all events in a single call.
+ *
+ * @template TEvents - Event schemas
+ * @template TTarget - Static target string or undefined
+ */
+export type ProjectionBuilder<TEvents extends Schemas, TTarget extends string | undefined = undefined> = {
+    /**
+     * Begins defining a projection handler for a specific event.
+     *
+     * Pass a `{ EventName: schema }` record — use shorthand `{ EventName }`
+     * when the variable name matches the event name. The key becomes the
+     * event name, the value the Zod schema.
+     */
+    on: <TKey extends string, TData extends Schema>(entry: EventEntry<TKey, TData>) => {
+        do: (handler: (event: Committed<TEvents & {
+            [P in TKey]: TData;
+        }, TKey>, stream: string) => Promise<void>) => DoResult<TEvents, TKey, TData, TTarget>;
+    };
+    /**
+     * Builds and returns the Projection data structure.
+     */
+    build: () => Projection<TEvents>;
+    /**
+     * The registered event schemas and their reaction maps.
+     */
+    readonly events: EventRegister<TEvents>;
+} & (TTarget extends string ? {
+    /**
+     * Registers a batch handler that processes all events in a single call.
+     *
+     * Only available on projections with a static target (`projection("target")`).
+     * The handler receives a discriminated union of all declared events,
+     * enabling bulk DB operations in a single transaction.
+     *
+     * When defined, the batch handler is always called — even for a single event.
+     * Individual `.do()` handlers serve as fallback for projections without `.batch()`.
+     */
+    batch: (handler: BatchHandler<TEvents>) => {
+        build: () => Projection<TEvents>;
+    };
+} : {});
+/**
+ * Creates a new projection builder with a static target stream.
+ *
+ * All handlers inherit the target resolver automatically. Enables `.batch()`
+ * for bulk event processing in a single transaction.
+ *
+ * @param target - Static target stream for all handlers
+ */
+export declare function projection<TEvents extends Schemas = {}>(target: string): ProjectionBuilder<TEvents, string>;
+/**
+ * Creates a new projection builder without a default target.
+ *
+ * Use per-handler `.to()` to route events to different streams.
+ */
+export declare function projection<TEvents extends Schemas = {}>(target?: undefined): ProjectionBuilder<TEvents, undefined>;
+export {};
+//# sourceMappingURL=projection-builder.d.ts.map

package/dist/@types/builders/projection-builder.d.ts.map

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