@rotorsoft/act 0.35.0 → 0.35.2

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

@@ -0,0 +1,109 @@
+import type { Actor, Committed, EventRegister, IAct, ReactionOptions, ReactionResolver, Schema, SchemaRegister, Schemas, Snapshot, State } from "../types/index.js";
+import type { Projection } from "./projection-builder.js";
+/**
+ * A self-contained functional slice grouping partial states with their
+ * scoped reactions. Slices are composed into an Act orchestrator via
+ * `act().withSlice(slice)`.
+ *
+ * @template TSchemaReg - Schema register for states
+ * @template TEvents - Event schemas from this slice's states
+ * @template TActions - Action schemas from this slice's states
+ * @template TStateMap - Map of state names to state schemas
+ * @template TActor - Actor type extending base Actor
+ */
+export type Slice<TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas, TStateMap extends Record<string, Schema> = {}, TActor extends Actor = Actor> = {
+    readonly _tag: "Slice";
+    readonly states: Map<string, State<any, any, any>>;
+    readonly events: EventRegister<TEvents>;
+    readonly projections: ReadonlyArray<Projection<any>>;
+    /** @internal phantom field for type-level state schema tracking */
+    readonly _S?: TSchemaReg;
+    /** @internal phantom field for type-level state name tracking */
+    readonly _M?: TStateMap;
+    /** @internal phantom field for type-level actor tracking */
+    readonly _TActor?: TActor;
+};
+/**
+ * Fluent builder interface for composing functional slices.
+ *
+ * Provides a chainable API for registering states and projections,
+ * and defining reactions scoped to the slice's own events.
+ *
+ * @template TSchemaReg - Schema register for states
+ * @template TEvents - Event schemas
+ * @template TActions - Action schemas
+ * @template TStateMap - Map of state names to state schemas
+ * @template TActor - Actor type extending base Actor
+ */
+export type SliceBuilder<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 slice.
+     *
+     * Include every state whose actions your reaction handlers need to
+     * dispatch. Duplicate registrations (same state in multiple slices)
+     * are handled automatically at composition time.
+     */
+    withState: <TNewState extends Schema, TNewEvents extends Schemas, TNewActions extends Schemas, TNewName extends string = string>(state: State<TNewState, TNewEvents, TNewActions, TNewName>) => SliceBuilder<TSchemaReg & {
+        [K in keyof TNewActions]: TNewState;
+    }, TEvents & TNewEvents, TActions & TNewActions, TStateMap & {
+        [K in TNewName]: TNewState;
+    }, TActor>;
+    /**
+     * Embeds a built Projection within this slice. The projection's events
+     * must be a subset of events from states already registered via
+     * `.withState()`. Projection handlers preserve their `(event, stream)`
+     * signature and do not receive the app interface.
+     */
+    withProjection: <TNewEvents extends Schemas>(projection: [Exclude<keyof TNewEvents, keyof TEvents>] extends [never] ? Projection<TNewEvents> : never) => SliceBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor>;
+    /**
+     * Begins defining a reaction scoped to this slice's events.
+     */
+    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>) => SliceBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor> & {
+            to: (resolver: ReactionResolver<TEvents, TKey> | string) => SliceBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor>;
+        };
+    };
+    /**
+     * Builds and returns the Slice data structure.
+     */
+    build: () => Slice<TSchemaReg, TEvents, TActions, TStateMap, TActor>;
+    /**
+     * The registered event schemas and their reaction maps.
+     */
+    readonly events: EventRegister<TEvents>;
+};
+/**
+ * Creates a new slice builder for composing partial states with scoped reactions.
+ *
+ * Slices enable vertical slice architecture by grouping related states and
+ * reactions into self-contained feature modules. Reactions defined in a slice
+ * are type-scoped to events from that slice's states only.
+ *
+ * @example Single-state slice with typed dispatch
+ * ```typescript
+ * const CounterSlice = slice()
+ *   .withState(Counter)
+ *   .on("Incremented")
+ *     .do(async (event, _stream, app) => {
+ *       await app.do("reset", target, {});
+ *     })
+ *     .to("counter-target")
+ *   .build();
+ * ```
+ *
+ * @example Cross-state dispatch (include both states)
+ * ```typescript
+ * const CreationSlice = slice()
+ *   .withState(TicketCreation)
+ *   .withState(TicketOperations) // handler can dispatch AssignTicket
+ *   .on("TicketOpened").do(async (event, _stream, app) => {
+ *     await app.do("AssignTicket", target, payload, event);
+ *   })
+ *   .build();
+ * ```
+ *
+ * @see {@link SliceBuilder} for builder methods
+ * @see {@link Slice} for the output type
+ */
+export declare function slice<TSchemaReg extends SchemaRegister<TActions> = {}, TEvents extends Schemas = {}, TActions extends Schemas = {}, TStateMap extends Record<string, Schema> = {}, TActor extends Actor = Actor>(): SliceBuilder<TSchemaReg, TEvents, TActions, TStateMap, TActor>;
+//# sourceMappingURL=slice-builder.d.ts.map

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

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

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

@@ -0,0 +1,424 @@
+/**
+ * @module state-builder
+ * @category Builders
+ *
+ * Fluent interface for defining a strongly-typed state machine using Zod schemas.
+ */
+import type { ZodType } from "zod";
+import type { 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 TState - State schema type
+ * @template TName - State name literal type
+ *
+ * @see {@link state} for usage examples
+ * @see {@link ActionBuilder} for action configuration
+ */
+export type StateBuilder<TState extends Schema, TName extends string = string> = {
+    /**
+     * 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<TState>) => {
+        /**
+         * 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 TEvents - Event schemas type
+         * @param events - Object mapping event names to Zod schemas
+         * @returns An ActionBuilder (with optional `.patch()` to override specific reducers)
+         *
+         * @example
+         * ```typescript
+         * .emits({
+         *   Incremented: z.object({ amount: z.number() }),
+         *   Decremented: z.object({ amount: z.number() }),
+         *   Reset: z.object({})
+         * })
+         * ```
+         */
+        emits: <TEvents extends Schemas>(events: ZodTypes<TEvents>) => ActionBuilder<TState, TEvents, {}, TName> & {
+            /**
+             * Overrides specific event reducers. Events without a custom patch
+             * default to passthrough: `({ data }) => data` (event data merges
+             * into state).
+             *
+             * @param patch - Partial map of event names to patch handler functions
+             * @returns An ActionBuilder for defining actions
+             *
+             * @example Only override the events that need custom logic
+             * ```typescript
+             * .emits({ TicketOpened, TicketClosed, TicketResolved })
+             * .patch({
+             *   TicketOpened: ({ data }) => {
+             *     const { message, messageId, userId, ...other } = data;
+             *     return { ...other, userId, messages: { [messageId]: { ... } } };
+             *   },
+             * })
+             * // TicketClosed and TicketResolved use passthrough
+             * ```
+             */
+            patch: (patch: Partial<PatchHandlers<TState, TEvents>>) => ActionBuilder<TState, TEvents, {}, TName>;
+        };
+    };
+};
+/** Helper: a single-key record mapping a state name to its Zod schema. */
+type StateEntry<TKey extends string = string, TState extends Schema = Schema> = {
+    [P in TKey]: ZodType<TState>;
+};
+/** Helper: a single-key record mapping an action name to its Zod schema. */
+type ActionEntry<TKey extends string = string, TNewActions extends Schema = Schema> = {
+    [P in TKey]: ZodType<TNewActions>;
+};
+/**
+ * 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 TState - State schema type
+ * @template TEvents - Event schemas type
+ * @template TActions - Action schemas type
+ * @template TName - State name literal type
+ *
+ * @see {@link state} for complete usage examples
+ */
+export type ActionBuilder<TState extends Schema, TEvents extends Schemas, TActions extends Schemas, TName extends string = string> = {
+    /**
+     * 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.
+     *
+     * Pass a `{ ActionName: schema }` record — use shorthand `{ ActionName }`
+     * when the variable name matches the action name. The key becomes the
+     * action name, the value the Zod schema.
+     *
+     * @template TKey - Action name (string literal type)
+     * @template TNewActions - Action payload schema type
+     * @param entry - Single-key record `{ ActionName: schema }`
+     * @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 with shorthand (variable name matches action name)
+     * ```typescript
+     * const OpenTicket = z.object({ title: z.string() });
+     * .on({ OpenTicket })
+     *   .emit((action) => ["TicketOpened", { title: action.title }])
+     * ```
+     */
+    on: <TKey extends string, TNewActions extends Schema>(entry: ActionEntry<TKey, TNewActions>) => {
+        /**
+         * 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<TState>[]) => {
+            /**
+             * 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.
+             *
+             * Pass a string event name for passthrough: the action payload becomes
+             * the event data directly.
+             *
+             * @param handler - Function that returns events to emit, or event name string for passthrough
+             * @returns The ActionBuilder for chaining more actions
+             *
+             * @example Custom handler
+             * ```typescript
+             * .emit((action, snapshot) => {
+             *   const newBalance = snapshot.state.balance + action.amount;
+             *   return ["Deposited", { amount: action.amount, newBalance }];
+             * })
+             * ```
+             *
+             * @example Passthrough (action payload = event data)
+             * ```typescript
+             * .emit("TicketAssigned")
+             * ```
+             */
+            emit: {
+                /** Custom handler — receives `(action, snapshot)` and returns one
+                 *  or more `[EventName, data]` tuples (or `undefined`). */
+                (handler: ActionHandler<TState, TEvents, {
+                    [P in TKey]: TNewActions;
+                }, TKey>): ActionBuilder<TState, TEvents, TActions & {
+                    [P in TKey]: TNewActions;
+                }, TName>;
+                /** Passthrough — the action payload becomes the event data
+                 *  directly. Must reference an event declared in `.emits()`. */
+                (eventName: keyof TEvents & string): ActionBuilder<TState, TEvents, TActions & {
+                    [P in TKey]: TNewActions;
+                }, TName>;
+            };
+        };
+        /**
+         * Defines the action handler that emits events. Same two overloads as
+         * the post-`.given()` form above:
+         *
+         * - **Function** — receives `(action, snapshot)` and returns one or
+         *   more `[EventName, data]` tuples (or `undefined`).
+         * - **String** — passthrough: the action payload becomes the event
+         *   data directly. Must reference an event declared in `.emits()`.
+         *
+         * The two overloads are kept separate (rather than merged into a
+         * `handler | string` union) so that TS contextual typing of the
+         * function alternative isn't degraded by considering the string
+         * branch — under the union form `TState` could collapse to its
+         * `Schema` constraint inside the callback.
+         *
+         * @example Passthrough (action payload = event data)
+         * ```typescript
+         * .emit("Incremented")
+         * ```
+         *
+         * @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}` }]
+         * ])
+         * ```
+         */
+        emit: {
+            (handler: ActionHandler<TState, TEvents, {
+                [P in TKey]: TNewActions;
+            }, TKey>): ActionBuilder<TState, TEvents, TActions & {
+                [P in TKey]: TNewActions;
+            }, TName>;
+            (eventName: keyof TEvents & string): ActionBuilder<TState, TEvents, TActions & {
+                [P in TKey]: TNewActions;
+            }, TName>;
+        };
+    };
+    /**
+     * 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<TState, TEvents>) => boolean) => ActionBuilder<TState, TEvents, TActions, TName>;
+    /**
+     * 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: ({ data }, state) => ({ count: state.count + data.amount }) })
+     *   .on({ increment: z.object({ by: z.number() }) })
+     *     .emit((action) => ["Incremented", { amount: action.by }])
+     *   .build(); // Returns State<TState, TEvents, TActions, TName>
+     * ```
+     */
+    build: () => State<TState, TEvents, TActions, TName>;
+};
+/**
+ * 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()` — all events default to passthrough (`({ data }) => data`)
+ * 3. Custom event reducers via `.patch()` (optional — only for events that need custom logic)
+ * 4. Actions (commands) via `.on()` → `.emit()` — pass an event name string for passthrough
+ * 5. Business rules (invariants) via `.given()`
+ * 6. Snapshotting strategy via `.snap()`
+ *
+ * @template TState - Zod schema type defining the shape of the state
+ * @param entry - Single-key record mapping state name to Zod schema (e.g., `{ Counter: z.object({ count: z.number() }) }`)
+ * @returns A StateBuilder instance for fluent API configuration
+ *
+ * @example Basic counter state (with custom patch)
+ * ```typescript
+ * import { state } from "@rotorsoft/act";
+ * import { z } from "zod";
+ *
+ * const Counter = state({ Counter: z.object({ count: z.number() }) })
+ *   .init(() => ({ count: 0 }))
+ *   .emits({
+ *     Incremented: z.object({ amount: z.number() })
+ *   })
+ *   .patch({  // optional — only for events needing custom reducers
+ *     Incremented: ({ data }, state) => ({ count: state.count + data.amount })
+ *   })
+ *   .on({ increment: z.object({ by: z.number() }) })
+ *     .emit((action) => ["Incremented", { amount: action.by }])
+ *   .build();
+ * ```
+ *
+ * @example Passthrough state (no custom patch or emit needed)
+ * ```typescript
+ * const DigitBoard = state({ DigitBoard: z.object({ digit: z.string() }) })
+ *   .init(() => ({ digit: "" }))
+ *   .emits({ DigitCounted: z.object({ digit: z.string() }) })
+ *   // no .patch() — passthrough is the default (event data merges into state)
+ *   .on({ CountDigit: z.object({ digit: z.string() }) })
+ *     .emit("DigitCounted")  // string passthrough — action payload becomes event data
+ *   .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({  // only override events needing custom logic
+ *     Deposited: ({ data }, state) => ({ balance: state.balance + data.amount }),
+ *     Withdrawn: ({ data }, state) => ({ balance: state.balance - 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("Deposited")  // passthrough — action payload { amount } becomes event data
+ *   .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("Withdrawn")
+ *   .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({  // only override events needing custom logic
+ *     UserLoggedIn: (_, state) => ({ loginCount: state.loginCount + 1 })
+ *   })
+ *   // UserCreated uses passthrough — event data merges into state
+ *   .on({ createUser: z.object({ name: z.string(), email: z.string() }) })
+ *     .emit("UserCreated")  // passthrough
+ *   .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<TName extends string, TState extends Schema>(entry: StateEntry<TName, TState>): StateBuilder<TState, TName>;
+export {};
+//# sourceMappingURL=state-builder.d.ts.map

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

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

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

@@ -0,0 +1,119 @@
+import { z } from "zod";
+/**
+ * Zod schema for validating package.json metadata.
+ * @internal
+ */
+export declare const PackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    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.ZodOptional<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Type representing the validated package.json metadata.
+ *
+ * @internal
+ */
+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.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.ZodOptional<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    env: z.ZodEnum<{
+        development: "development";
+        test: "test";
+        staging: "staging";
+        production: "production";
+    }>;
+    logLevel: z.ZodEnum<{
+        fatal: "fatal";
+        error: "error";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+        trace: "trace";
+    }>;
+    logSingleLine: z.ZodBoolean;
+    sleepMs: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Type representing the validated Act Framework configuration object.
+ */
+export type Config = z.infer<typeof BaseSchema>;
+/**
+ * Gets the current Act Framework configuration.
+ *
+ * Configuration is loaded from package.json and environment variables, providing
+ * type-safe access to application metadata and runtime settings.
+ *
+ * **Environment Variables:**
+ * - `NODE_ENV`: "development" | "test" | "staging" | "production" (default: "development")
+ * - `LOG_LEVEL`: "fatal" | "error" | "warn" | "info" | "debug" | "trace"
+ * - `LOG_SINGLE_LINE`: "true" | "false" (default: "true")
+ * - `SLEEP_MS`: Milliseconds for sleep utility (default: 100, 0 for tests)
+ *
+ * **Defaults by environment:**
+ * - test: logLevel="error", sleepMs=0
+ * - production: logLevel="info"
+ * - development: logLevel="trace"
+ *
+ * @returns The validated configuration object
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { config } from "@rotorsoft/act";
+ *
+ * const cfg = config();
+ * console.log(`App: ${cfg.name} v${cfg.version}`);
+ * console.log(`Environment: ${cfg.env}`);
+ * console.log(`Log level: ${cfg.logLevel}`);
+ * ```
+ *
+ * @example Environment-specific behavior
+ * ```typescript
+ * import { config } from "@rotorsoft/act";
+ *
+ * const cfg = config();
+ *
+ * if (cfg.env === "production") {
+ *   // Use PostgreSQL in production
+ *   store(new PostgresStore(prodConfig));
+ * } else {
+ *   // Use in-memory store for dev/test
+ *   store(new InMemoryStore());
+ * }
+ * ```
+ *
+ * @example Adjusting log levels
+ * ```typescript
+ * // Set via environment variable:
+ * // LOG_LEVEL=debug npm start
+ *
+ * // Or check in code:
+ * const cfg = config();
+ * if (cfg.logLevel === "trace") {
+ *   logger.trace("Detailed debugging enabled");
+ * }
+ * ```
+ *
+ * @see {@link Config} for configuration type
+ */
+export declare const config: () => Config;
+export {};
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;iBAWxB,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AA0CpD;;;;GAIG;AACH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKd,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAsBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,MAAM,QAAO,MAwBzB,CAAC"}