@rotorsoft/act 0.35.1 → 0.36.0

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

@@ -0,0 +1,314 @@
+/**
+ * @packageDocumentation
+ * @module act/types
+ * @category Types
+ * Types for reactions, leases, and fetch results in the Act Framework.
+ */
+import type { Actor, Committed, IAct, Query, Schema, Schemas, Snapshot } from "./action.js";
+/**
+ * Reaction handler function that processes committed events.
+ *
+ * Reaction handlers respond to events asynchronously. They can:
+ * - Perform side effects (send emails, call APIs, log, etc.)
+ * - Return an action tuple to trigger another action
+ * - Return `void` or `undefined` for side-effect-only reactions
+ *
+ * Handlers are called during drain cycles and support automatic retries
+ * with configurable error handling.
+ *
+ * @template TEvents - Event schemas
+ * @template TKey - Event name
+ * @template TActions - Action schemas (defaults to Schemas for stored reactions)
+ * @template TActor - Actor type extending base Actor
+ * @param event - The committed event that triggered this reaction
+ * @param stream - The target stream name for this reaction
+ * @returns Promise resolving to an action tuple or void
+ *
+ * @example Side effect only
+ * ```typescript
+ * const sendEmail: ReactionHandler<Events, "UserCreated"> = async (event) => {
+ *   await emailService.send(event.data.email, "Welcome!");
+ * };
+ * ```
+ *
+ * @example Triggering another action
+ * ```typescript
+ * const reduceInventory: ReactionHandler<Events, "OrderPlaced"> = async (event) => {
+ *   return ["reduceStock", { amount: event.data.items.length }];
+ * };
+ * ```
+ *
+ * @see {@link Reaction} for complete reaction configuration
+ */
+export type ReactionHandler<TEvents extends Schemas, TKey extends keyof TEvents, TActions extends Schemas = Schemas, TActor extends Actor = Actor> = (event: Committed<TEvents, TKey>, stream: string, app: IAct<TEvents, TActions, TActor>) => Promise<Snapshot<Schema, TEvents> | void>;
+/**
+ * Resolver for determining which stream a reaction should target.
+ *
+ * Resolvers enable dynamic reaction routing based on event content. They can be:
+ * - **Static**: Always route to the same target stream
+ * - **Dynamic**: Determine target based on event data at runtime
+ *
+ * Resolvers can also specify source streams for optimization, allowing the drain
+ * process to efficiently fetch only relevant events. An optional `priority`
+ * biases the lagging-frontier `claim()` ordering — see {@link Resolved.priority}.
+ *
+ * @template TEvents - Event schemas
+ * @template TKey - Event name
+ * @param event - The committed event (for dynamic resolvers)
+ * @returns Target stream configuration or undefined to skip
+ *
+ * @example Static target
+ * ```typescript
+ * .on("UserCreated")
+ *   .do(sendWelcomeEmail)
+ *   .to("email-queue") // Static target
+ * ```
+ *
+ * @example Dynamic target per user
+ * ```typescript
+ * .on("UserLoggedIn")
+ *   .do(incrementLoginCount)
+ *   .to((event) => ({
+ *     target: `stats-${event.stream}` // Dynamic per user
+ *   }))
+ * ```
+ *
+ * @example With source optimization
+ * ```typescript
+ * .on("UserUpdated")
+ *   .do(updateReadModel)
+ *   .to(({ stream }) => ({
+ *     source: stream,           // Only fetch from this user's stream
+ *     target: `cache-${stream}` // Update corresponding cache
+ *   }))
+ * ```
+ *
+ * @example With priority (saturated worker scheduling)
+ * ```typescript
+ * .on("OrderConfirmed")
+ *   .do(sendCriticalNotification)
+ *   .to({ target: "notifications-out", priority: 10 })
+ * ```
+ *
+ * @see {@link Reaction} for complete reaction configuration
+ * @see {@link Resolved} for the resolved-target shape
+ */
+export type ReactionResolver<TEvents extends Schemas, TKey extends keyof TEvents> = Resolved | ((event: Committed<TEvents, TKey>) => Resolved | undefined);
+/**
+ * Resolver output shape — what `.to(...)` returns for a static or dynamic
+ * resolver.
+ *
+ * @property target - Stream name that processes this reaction
+ * @property source - Optional source-stream filter for fetch optimization
+ * @property priority - Optional scheduling hint. The lagging-frontier
+ *   `claim()` orders streams by `priority DESC, at ASC`, so a higher value
+ *   makes the stream win lease slots ahead of equal-watermark peers under
+ *   saturation. Default `0` — behavior identical to current dual-frontier.
+ *   Only meaningful when `streamLimit` is binding (more candidate streams
+ *   than the worker can claim per cycle); idle systems are unaffected.
+ *   See `libs/act-pg/PERFORMANCE.md` for the benchmark that motivated this
+ *   knob.
+ */
+export type Resolved = {
+    readonly target: string;
+    readonly source?: string;
+    readonly priority?: number;
+};
+/**
+ * Options for reaction processing.
+ * @property blockOnError - Whether to block on error.
+ * @property maxRetries - Maximum number of retries.
+ */
+export type ReactionOptions = {
+    readonly blockOnError: boolean;
+    readonly maxRetries: number;
+};
+/**
+ * Distributive mapped type that produces a proper discriminated union of
+ * committed events. Unlike `Committed<TEvents, keyof TEvents>` (where
+ * `name` and `data` are independent unions), each variant correlates
+ * `name` with its corresponding `data` — enabling `switch (event.name)`
+ * to narrow both fields correctly.
+ *
+ * @template TEvents - Event schemas
+ *
+ * @example Exhaustive switch
+ * ```typescript
+ * for (const event of events) {
+ *   switch (event.name) {
+ *     case "TicketOpened":
+ *       event.data; // typed as TicketOpened's schema
+ *       break;
+ *     case "TicketClosed":
+ *       event.data; // typed as TicketClosed's schema
+ *       break;
+ *     default:
+ *       const _: never = event; // compile error if a case is missing
+ *   }
+ * }
+ * ```
+ */
+export type BatchEvent<TEvents extends Schemas> = {
+    [K in keyof TEvents]: Committed<TEvents, K>;
+}[keyof TEvents];
+/**
+ * Batch handler for projections that processes multiple events in a single call.
+ *
+ * Receives the full ordered array of all event types declared on the projection,
+ * enabling bulk DB operations (batch INSERT/UPDATE) in a single transaction.
+ * The handler is always called when defined — even for a single event.
+ *
+ * @template TEvents - Event schemas (all events declared on the projection)
+ * @param events - Ordered array of committed events (discriminated union)
+ * @param stream - The target stream name
+ *
+ * @see {@link BatchEvent} for the discriminated union type
+ */
+export type BatchHandler<TEvents extends Schemas> = (events: ReadonlyArray<BatchEvent<TEvents>>, stream: string) => Promise<void>;
+/**
+ * Defines a reaction to an event.
+ * @template TEvents - Event schemas.
+ * @template TKey - Event name.
+ * @template TActions - Action schemas.
+ * @template TActor - Actor type extending base Actor.
+ * @property handler - The reaction handler.
+ * @property resolver - The reaction resolver.
+ * @property options - The reaction options.
+ */
+export type Reaction<TEvents extends Schemas, TKey extends keyof TEvents = keyof TEvents, TActions extends Schemas = Schemas, TActor extends Actor = Actor> = {
+    readonly handler: ReactionHandler<TEvents, TKey, TActions, TActor>;
+    /**
+     * Mutable so the builder's `.do()` → `.to()` chain can patch the resolver
+     * in place (registered once with the default `_this_` resolver in `.do()`,
+     * overwritten in `.to()` if present). After build-time the field is
+     * effectively immutable; runtime consumers only read it.
+     */
+    resolver: ReactionResolver<TEvents, TKey>;
+    readonly options: ReactionOptions;
+};
+/**
+ * Payload for a reaction.
+ * @template TEvents - Event schemas.
+ * @property handler - The reaction handler.
+ * @property resolver - The reaction resolver.
+ * @property options - The reaction options.
+ * @property event - The committed event triggering the reaction.
+ * @property source - The source stream.
+ */
+export type ReactionPayload<TEvents extends Schemas> = Reaction<TEvents> & {
+    readonly event: Committed<TEvents, keyof TEvents>;
+    readonly source?: string;
+};
+/**
+ * Result of fetching events from the store for processing.
+ * @template TEvents - Event schemas.
+ * @property stream - The stream name
+ * @property source - The source stream(s) (name or RegExp), or undefined when sourcing from all streams.
+ * @property at - The last event sequence number processed by the stream.
+ * @property lagging - Whether the stream is lagging behind.
+ * @property events - The list of next committed events to be processed by the stream.
+ */
+export type Fetch<TEvents extends Schemas> = Array<{
+    readonly stream: string;
+    readonly source?: string;
+    readonly at: number;
+    readonly lagging: boolean;
+    readonly events: Committed<TEvents, keyof TEvents>[];
+}>;
+/**
+ * Lease information for distributed stream processing.
+ *
+ * Leases prevent concurrent processing of the same stream by multiple workers.
+ * When a worker acquires a lease, it has exclusive rights to process events
+ * for that stream until the lease expires or is acknowledged.
+ *
+ * The drain process uses leases to:
+ * - Prevent race conditions in distributed setups
+ * - Track processing progress (watermark)
+ * - Manage retries on failures
+ * - Balance load between lagging and leading streams
+ *
+ * @property stream - The target stream name being processed
+ * @property source - Optional source stream for filtering
+ * @property at - Watermark: last successfully processed event ID
+ * @property by - Unique identifier of the lease holder (UUID)
+ * @property retry - Number of retry attempts (0 = first attempt)
+ * @property lagging - Whether this stream is behind (lagging frontier)
+ *
+ * @example
+ * ```typescript
+ * app.on("acked", (leases) => {
+ *   leases.forEach(lease => {
+ *     console.log(`Processed ${lease.stream} up to event ${lease.at}`);
+ *   });
+ * });
+ *
+ * app.on("blocked", (blocked) => {
+ *   blocked.forEach(({ stream, retry, error }) => {
+ *     console.error(`Stream ${stream} blocked after ${retry} retries: ${error}`);
+ *   });
+ * });
+ * ```
+ *
+ * @see {@link Drain} for drain cycle results
+ */
+export type Lease = {
+    readonly stream: string;
+    readonly source?: string;
+    readonly at: number;
+    readonly by: string;
+    readonly retry: number;
+    readonly lagging: boolean;
+};
+/**
+ * A {@link Lease} augmented with the failure reason that pushed it past
+ * its retry budget. Yielded by {@link Drain.blocked}, emitted on the
+ * `"blocked"` lifecycle event, and accepted by {@link Store.block}.
+ */
+export type BlockedLease = Lease & {
+    readonly error: string;
+};
+/**
+ * Options for draining events from the store.
+ * @property streamLimit - Maximum number of streams to fetch.
+ * @property eventLimit - Maximum number of events to fetch per stream.
+ * @property leaseMillis - Maximum lease duration (in milliseconds).
+ */
+export type DrainOptions = {
+    readonly streamLimit?: number;
+    readonly eventLimit?: number;
+    readonly leaseMillis?: number;
+};
+/**
+ * Drain results
+ * @property fetched - The fetched events.
+ * @property leased - The leased events.
+ * @property acked - The acked events.
+ * @property blocked - The blocked events (with error).
+ */
+export type Drain<TEvents extends Schemas> = {
+    readonly fetched: Fetch<TEvents>;
+    readonly leased: Lease[];
+    readonly acked: Lease[];
+    readonly blocked: BlockedLease[];
+};
+/**
+ * Options for the debounced settle cycle.
+ *
+ * Extends {@link DrainOptions} with parameters that control the debounce
+ * window, the correlation query, and the maximum number of correlate→drain
+ * passes.
+ *
+ * @property debounceMs - Debounce window in milliseconds (default: 10)
+ * @property correlate - Query filter for correlation scans (default: `{ after: -1, limit: 100 }`)
+ * @property maxPasses - Cap on correlate→drain loops (default: `Infinity`).
+ *   Settle exits early as soon as a pass makes no progress (no new
+ *   subscriptions, no acks, no blocks), so the cap only matters in
+ *   pathological cases.
+ */
+export type SettleOptions = DrainOptions & {
+    readonly debounceMs?: number;
+    readonly correlate?: Query;
+    readonly maxPasses?: number;
+};
+//# sourceMappingURL=reaction.d.ts.map

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

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

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

@@ -0,0 +1,74 @@
+import type { ZodType, z } from "zod";
+import type { CommittedMeta, Schema, Schemas, State } from "./action.js";
+import type { Reaction } from "./reaction.js";
+/**
+ * @packageDocumentation
+ * @module act/types
+ * @category Types
+ * Types for event and action registries in the Act Framework.
+ */
+/**
+ * Per-event registration: the event's schema plus every reaction
+ * registered against it. Keyed by reaction name within the inner map so
+ * a single event can fan out to multiple handlers (one per slice or
+ * top-level `act().on(...)` call).
+ *
+ * @template TEvents - Event schemas in the domain
+ * @template TKey    - Specific event name within `TEvents`
+ */
+export type ReactionsRegister<TEvents extends Schemas, TKey extends keyof TEvents> = {
+    schema: ZodType<TEvents[TKey]>;
+    reactions: Map<string, Reaction<TEvents, TKey>>;
+};
+/**
+ * Maps event names to their schema and registered reactions.
+ * @template TEvents - Event schemas.
+ */
+export type EventRegister<TEvents extends Schemas> = {
+    [TKey in keyof TEvents]: ReactionsRegister<TEvents, TKey>;
+};
+/**
+ * Type-level constraint: every key in the action map must point at a
+ * Zod schema. Used as a constraint on the registry's action half so
+ * downstream types can `infer` payloads safely.
+ *
+ * @template TSchemaReg - Schema register for actions
+ */
+export type SchemaRegister<TSchemaReg> = {
+    [TKey in keyof TSchemaReg]: Schema;
+};
+/**
+ * Registry of all actions and events for a domain.
+ * @template TSchemaReg - State schemas.
+ * @template TEvents - Event schemas.
+ * @template TActions - Action schemas.
+ * @property actions - Map of action names to state definitions.
+ * @property events - Map of event names to event registration info.
+ */
+export type Registry<TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas> = {
+    readonly actions: {
+        [TKey in keyof TActions]: State<TSchemaReg[TKey], TEvents, TActions>;
+    };
+    readonly events: EventRegister<TEvents>;
+};
+/**
+ * Utility type to convert a registry entry to a committed event type.
+ * @template R - Registry map.
+ * @template K - Event name.
+ */
+export type AsCommitted<R, K extends keyof R> = R[K] extends {
+    schema: infer S;
+} ? {
+    readonly name: K;
+    readonly data: z.infer<S>;
+} & CommittedMeta : never;
+/**
+ * Utility type to map commited events from zod schema maps.
+ * @template E - Event map.
+ * @template K - Event name.
+ */
+export type CommittedOf<E, K extends keyof E> = E[K] extends z.ZodType ? {
+    readonly name: K;
+    readonly data: z.infer<E[K]>;
+} & CommittedMeta : never;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/types/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,CAC3B,OAAO,SAAS,OAAO,EACvB,IAAI,SAAS,MAAM,OAAO,IACxB;IACF,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;CACjD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,OAAO,IAAI;KAClD,IAAI,IAAI,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC;CAC1D,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,UAAU,IAAI;KACtC,IAAI,IAAI,MAAM,UAAU,GAAG,MAAM;CACnC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAClB,UAAU,SAAS,cAAc,CAAC,QAAQ,CAAC,EAC3C,OAAO,SAAS,OAAO,EACvB,QAAQ,SAAS,OAAO,IACtB;IACF,QAAQ,CAAC,OAAO,EAAE;SACf,IAAI,IAAI,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC;KACrE,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACzC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC5E;IACE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;CAC3B,GAAG,aAAa,GACjB,KAAK,CAAC;AAEV;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,GAClE;IACE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC9B,GAAG,aAAa,GACjB,KAAK,CAAC"}

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

@@ -0,0 +1,117 @@
+import { type ZodObject, type ZodRawShape, z } from "zod";
+/**
+ * @packageDocumentation
+ * @module act/types
+ * @category Types
+ * Zod schemas and helpers for the Act Framework.
+ */
+/**
+ * An empty Zod schema (no properties).
+ */
+export declare const ZodEmpty: z.ZodRecord<z.ZodString, z.ZodNever>;
+/**
+ * Zod schema for an actor (user, system, etc.).
+ */
+export declare const ActorSchema: z.ZodReadonly<ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$loose>>;
+/**
+ * Zod schema for a target (stream and actor info).
+ */
+export declare const TargetSchema: z.ZodReadonly<ZodObject<{
+    stream: z.ZodString;
+    actor: z.ZodReadonly<ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$loose>>;
+    expectedVersion: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>>;
+/**
+ * Zod schema for causation event metadata.
+ */
+export declare const CausationEventSchema: ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    stream: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Zod schema for event metadata (correlation and causation).
+ */
+export declare const EventMetaSchema: z.ZodReadonly<ZodObject<{
+    correlation: z.ZodString;
+    causation: ZodObject<{
+        action: z.ZodOptional<z.ZodIntersection<z.ZodReadonly<ZodObject<{
+            stream: z.ZodString;
+            actor: z.ZodReadonly<ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$loose>>;
+            expectedVersion: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>, ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>>>;
+        event: z.ZodOptional<ZodObject<{
+            id: z.ZodNumber;
+            name: z.ZodString;
+            stream: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+/**
+ * Zod schema for committed event metadata (id, stream, version, created, meta).
+ */
+export declare const CommittedMetaSchema: z.ZodReadonly<ZodObject<{
+    id: z.ZodNumber;
+    stream: z.ZodString;
+    version: z.ZodNumber;
+    created: z.ZodDate;
+    meta: z.ZodReadonly<ZodObject<{
+        correlation: z.ZodString;
+        causation: ZodObject<{
+            action: z.ZodOptional<z.ZodIntersection<z.ZodReadonly<ZodObject<{
+                stream: z.ZodString;
+                actor: z.ZodReadonly<ZodObject<{
+                    id: z.ZodString;
+                    name: z.ZodString;
+                }, z.core.$loose>>;
+                expectedVersion: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>, ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strip>>>;
+            event: z.ZodOptional<ZodObject<{
+                id: z.ZodNumber;
+                name: z.ZodString;
+                stream: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+/**
+ * Type representing the full state schema for a domain.
+ * @property events - Map of event names to Zod schemas.
+ * @property actions - Map of action names to Zod schemas.
+ * @property state - Zod schema for the state object.
+ */
+export type StateSchema = Readonly<{
+    events: Record<string, ZodObject<ZodRawShape> | typeof ZodEmpty>;
+    actions: Record<string, ZodObject<ZodRawShape> | typeof ZodEmpty>;
+    state: ZodObject<ZodRawShape>;
+}>;
+/**
+ * Query options for event store queries.
+ */
+export declare const QuerySchema: z.ZodReadonly<ZodObject<{
+    stream: z.ZodOptional<z.ZodString>;
+    names: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    before: z.ZodOptional<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    created_before: z.ZodOptional<z.ZodDate>;
+    created_after: z.ZodOptional<z.ZodDate>;
+    backward: z.ZodOptional<z.ZodBoolean>;
+    correlation: z.ZodOptional<z.ZodString>;
+    with_snaps: z.ZodOptional<z.ZodBoolean>;
+    stream_exact: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>;
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/types/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE1D;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ,sCAAkC,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,WAAW;;;kBAMX,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;kBAOZ,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;iBAI/B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;kBAQf,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;kBAQnB,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC;IACjE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC;IAClE,KAAK,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;CAC/B,CAAC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;kBAcX,CAAC"}

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

@@ -0,0 +1,54 @@
+import { type ZodType } from "zod";
+/**
+ * @module utils
+ * @category Utilities
+ *
+ * Small utilities used across the framework:
+ * - {@link validate} — parse a payload against a Zod schema, throwing
+ *   {@link ValidationError} on failure.
+ * - {@link extend} — validate a source object and merge into defaults.
+ * - {@link sleep} — async delay (default duration from `config().sleepMs`).
+ */
+/**
+ * Parse `payload` against `schema`, returning the validated value or throwing
+ * a {@link ValidationError} with prettified Zod details. When `schema` is
+ * omitted, returns `payload` unchanged. The framework calls this for every
+ * `app.do()` action, every emitted event, and every state init.
+ *
+ * @example
+ * ```typescript
+ * const UserSchema = z.object({ email: z.string().email() });
+ * const user = validate("User", { email: "alice@example.com" }, UserSchema);
+ * ```
+ *
+ * @see {@link ValidationError}
+ */
+export declare const validate: <S>(target: string, payload: Readonly<S>, schema?: ZodType<S>) => Readonly<S>;
+/**
+ * Validate `source` against `schema` and return a new object that merges
+ * `source` over the optional `target` defaults. Used by {@link config} for
+ * env-var-overrides-defaults patterns; safe to call elsewhere — it never
+ * mutates `target`.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ host: z.string(), port: z.number() });
+ * const cfg = extend({ port: 8080 }, schema, { host: "localhost", port: 80 });
+ * // → { host: "localhost", port: 8080 }
+ * ```
+ *
+ * @throws {@link ValidationError} if `source` fails the schema.
+ */
+export declare const extend: <S extends Record<string, unknown>, T extends Record<string, unknown>>(source: Readonly<S>, schema: ZodType<S>, target?: Readonly<T>) => Readonly<S & T>;
+/**
+ * Pause for `ms` milliseconds (or `config().sleepMs` when omitted — `100ms`
+ * in dev, `0ms` in tests). Used by adapters to simulate async I/O.
+ *
+ * @example
+ * ```typescript
+ * await sleep();      // default delay from config
+ * await sleep(500);   // explicit 500ms
+ * ```
+ */
+export declare function sleep(ms?: number): Promise<unknown>;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAI5D;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EACxB,QAAQ,MAAM,EACd,SAAS,QAAQ,CAAC,CAAC,CAAC,EACpB,SAAS,OAAO,CAAC,CAAC,CAAC,KAClB,QAAQ,CAAC,CAAC,CASZ,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,GACjB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjC,QAAQ,QAAQ,CAAC,CAAC,CAAC,EACnB,QAAQ,OAAO,CAAC,CAAC,CAAC,EAClB,SAAS,QAAQ,CAAC,CAAC,CAAC,KACnB,QAAQ,CAAC,CAAC,GAAG,CAAC,CAGhB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,oBAEtC"}