@arki/event-sourcing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ARKI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @arki/event-sourcing
+
+Event sourcing primitives for the ARKI package family — event store, message bus, command handlers, projections, and process managers, built on top of [Emmett](https://event-driven-io.github.io/emmett/) with `@event-driven-io/emmett-postgresql`.
+
+## Installation
+
+```sh
+npm install @arki/event-sourcing
+# or
+bun add @arki/event-sourcing
+# or
+pnpm add @arki/event-sourcing
+```
+
+Peer-installs:
+
+- `@event-driven-io/emmett` (re-exported core types)
+- `@event-driven-io/emmett-postgresql` (PostgreSQL event store)
+- `drizzle-orm` (for projections that write through a Drizzle handle)
+
+## What you get
+
+- **Event store** — `getEventStore(connectionString, options)` opens a PostgreSQL event store with a clean `close()` that releases the pool.
+- **Message bus** — `eventSourcingFeatures.initMessageBus(eventStore, handlers)` builds an in-memory message bus, registers command handlers, and wraps each handler with stream-name resolution + logging.
+- **Process managers** — `createProcessManager` (per-batch), `createStatefulProcessManager` (per-batch with state), and `createSimpleProcessManager` (per-message with a pre-bound context).
+- **Builders** — fluent `defineCommand`, `defineEvent`, `defineDecider`, `defineProjection`, `defineCommandHandler`, `defineProcessManager`, `defineStatefulProcessManager` for type-safe authoring.
+- **Drizzle projection helpers** — `drizzleProjection` / `drizzleWithRepoProjection` so projection handlers receive a typed Drizzle database (or repository registry) instead of a raw client.
+
+## Quick start
+
+### 1. Bootstrap an event store and message bus
+
+```ts
+import { eventSourcingFeatures } from '@arki/event-sourcing';
+
+const { eventStore, close } = eventSourcingFeatures.initEventSourcing(
+  [
+    /* projections produced by defineProjection / drizzleProjection / postgreSQLProjection */
+  ],
+  process.env.EVENT_STORE_URL,
+);
+
+const messageBus = eventSourcingFeatures.initMessageBus(eventStore, [
+  /* { commandType, handler, getStreamName } registrations */
+]);
+
+// Later, on shutdown:
+await close();
+```
+
+`initEventSourcing` throws a descriptive error if the connection string is undefined, naming `EVENT_STORE_URL`, `EVENTSTORE_URL`, and `EVENT_DB_URL` as the recognised env var names.
+
+### 2. Define a command, a decider, and a handler
+
+```ts
+import { defineCommand, defineEvent, defineDecider, defineCommandHandler, z } from '@arki/event-sourcing';
+// (or import each builder from '@arki/event-sourcing/builders')
+
+const PlaceOrder = defineCommand({
+  type: 'PlaceOrder',
+  inputSchema: z.object({ orderId: z.string(), total: z.number() }),
+  metadataSchema: z.object({ userId: z.string() }),
+});
+
+const OrderPlaced = defineEvent({
+  type: 'OrderPlaced',
+  inputSchema: z.object({ orderId: z.string(), total: z.number() }),
+  metadataSchema: z.object({ userId: z.string(), at: z.string() }),
+});
+
+const orderDecider = defineDecider()
+  .initialState(() => ({ placed: false }))
+  .evolve((state, event) => (event.type === 'OrderPlaced' ? { placed: true } : state))
+  .decide((command, state) => {
+    if (state.placed) throw new Error('Order already placed');
+    return OrderPlaced({ orderId: command.data.orderId, total: command.data.total }, {
+      userId: command.metadata.userId,
+      at: new Date().toISOString(),
+    });
+  })
+  .build();
+
+export const placeOrderHandler = defineCommandHandler(orderDecider);
+```
+
+### 3. Define a process manager
+
+Use `createProcessManager` for batch processing, or `createSimpleProcessManager` when the handler closes over a fixed context and processes one event at a time:
+
+```ts
+import { createSimpleProcessManager } from '@arki/event-sourcing';
+
+const sendOrderEmails = createSimpleProcessManager(
+  { emailer, repo },
+  'order-emails',
+  ['OrderPlaced', 'OrderCancelled'],
+  async (event, ctx) => {
+    if (event.type === 'OrderPlaced') {
+      await ctx.emailer.send('order-placed', event.data);
+    } else {
+      await ctx.emailer.send('order-cancelled', event.data);
+    }
+  },
+);
+
+await eventSourcingFeatures.setupProcessManagers(eventStore, [sendOrderEmails]);
+```
+
+`setupProcessManagers` starts each process manager as a consumer of the event store and installs a SIGTERM hook that stops and closes the consumers before exiting.
+
+## Subpath exports
+
+- `@arki/event-sourcing` — main surface (commands, events, deciders, process managers, features).
+- `@arki/event-sourcing/builders` — fluent builders only.
+- `@arki/event-sourcing/store` — `getEventStore`, `drizzleProjection`, `postgreSQLProjection`, projection context types.
+- `@arki/event-sourcing/bus` — `getInMemoryMessageBus` and message bus types re-exported from Emmett.
+
+## Documentation
+
+For an overview of the package's design principles, see [`docs/design.md`](./docs/design.md). For command flow patterns, see [`docs/command-flows.md`](./docs/command-flows.md).
+
+## License
+
+MIT © ARKI Contributors

package/dist/builders/command-handler.d.ts

@@ -0,0 +1,48 @@
+import type { CommandHandlerResult, Event, EventStore, HandleOptions } from '@event-driven-io/emmett';
+type DeciderConfig<State, CommandType, StreamEvent> = {
+    initialState: () => State;
+    evolve: (state: State, event: StreamEvent) => State;
+    decide: (command: CommandType, state: State) => StreamEvent | StreamEvent[];
+};
+/**
+ * Store-connected command handler function type.
+ *
+ * Given an event store, stream id, and one or more commands, it loads the
+ * current aggregate state from the stream, applies the decider's `decide`
+ * function, and appends the resulting events.
+ */
+export type CommandHandler<State, CommandType, StreamEvent extends Event> = <Store extends EventStore>(eventStore: Store, id: string, commands: CommandType | CommandType[], handleOptions?: HandleOptions<Store>) => Promise<CommandHandlerResult<State, StreamEvent, Store>>;
+/**
+ * Creates a store-connected command handler from a decider configuration.
+ *
+ * This is the recommended way to create command handlers. It wraps Emmett's
+ * `DeciderCommandHandler` while lifting the `CommandType extends Command`
+ * constraint that prevents commands with custom metadata from type-checking.
+ *
+ * Emmett's `Command` type uses a conditional type for metadata:
+ * - When metadata is `undefined`, the `metadata` property is optional.
+ * - When metadata is defined, it becomes required.
+ *
+ * TypeScript cannot prove that a concrete command (with custom metadata)
+ * satisfies `extends Command` across these conditional branches. This wrapper
+ * bridges that gap with a single, localised type assertion — keeping all
+ * call sites fully type-safe.
+ *
+ * @example
+ * ```typescript
+ * const handler = defineCommandHandler({
+ *   initialState,
+ *   evolve,
+ *   decide,
+ * });
+ *
+ * export const bookCommandHandlers = BookCommands.map(commandType => ({
+ *   commandType,
+ *   handler,
+ *   getStreamName,
+ * }));
+ * ```
+ */
+export declare function defineCommandHandler<State, CommandType, StreamEvent extends Event>(config: DeciderConfig<State, CommandType, StreamEvent>): CommandHandler<State, CommandType, StreamEvent>;
+export {};
+//# sourceMappingURL=command-handler.d.ts.map

package/dist/builders/command-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-handler.d.ts","sourceRoot":"","sources":["../../src/builders/command-handler.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAU,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAC,MAAM,yBAAyB,CAAC;AAI7G,KAAK,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,IAAI;IACpD,YAAY,EAAE,MAAM,KAAK,CAAC;IAC1B,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,KAAK,KAAK,CAAC;IACpD,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,KAAK,WAAW,GAAG,WAAW,EAAE,CAAC;CAC7E,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,SAAS,KAAK,IAAI,CAAC,KAAK,SAAS,UAAU,EACnG,UAAU,EAAE,KAAK,EACjB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,WAAW,GAAG,WAAW,EAAE,EACrC,aAAa,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,KACjC,OAAO,CAAC,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,SAAS,KAAK,EAChF,MAAM,EAAE,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,CAAC,GACrD,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,CAAC,CAWjD"}

package/dist/builders/command-handler.js

@@ -0,0 +1,40 @@
+import { DeciderCommandHandler } from '@event-driven-io/emmett';
+import { debugBuilder } from '../debug.js';
+/**
+ * Creates a store-connected command handler from a decider configuration.
+ *
+ * This is the recommended way to create command handlers. It wraps Emmett's
+ * `DeciderCommandHandler` while lifting the `CommandType extends Command`
+ * constraint that prevents commands with custom metadata from type-checking.
+ *
+ * Emmett's `Command` type uses a conditional type for metadata:
+ * - When metadata is `undefined`, the `metadata` property is optional.
+ * - When metadata is defined, it becomes required.
+ *
+ * TypeScript cannot prove that a concrete command (with custom metadata)
+ * satisfies `extends Command` across these conditional branches. This wrapper
+ * bridges that gap with a single, localised type assertion — keeping all
+ * call sites fully type-safe.
+ *
+ * @example
+ * ```typescript
+ * const handler = defineCommandHandler({
+ *   initialState,
+ *   evolve,
+ *   decide,
+ * });
+ *
+ * export const bookCommandHandlers = BookCommands.map(commandType => ({
+ *   commandType,
+ *   handler,
+ *   getStreamName,
+ * }));
+ * ```
+ */
+export function defineCommandHandler(config) {
+    debugBuilder('[command-handler] Creating command handler');
+    const emmettHandler = DeciderCommandHandler(config);
+    debugBuilder('[command-handler] Command handler created successfully');
+    return emmettHandler;
+}
+//# sourceMappingURL=command-handler.js.map

package/dist/builders/command-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-handler.js","sourceRoot":"","sources":["../../src/builders/command-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EAMtB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsB3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAsD;IAEtD,YAAY,CAAC,4CAA4C,CAAC,CAAC;IAM3D,MAAM,aAAa,GAAG,qBAAqB,CAAC,MAAsB,CAAC,CAAC;IAEpE,YAAY,CAAC,wDAAwD,CAAC,CAAC;IACvE,OAAO,aAAgE,CAAC;AAC1E,CAAC"}

package/dist/builders/command.d.ts

@@ -0,0 +1,39 @@
+import type { z } from '@arki/contracts';
+import type { Command, DefaultCommandMetadata } from '../command.js';
+import type { DefaultRecord } from '../types.js';
+/**
+ * Configuration for defining a domain command factory.
+ */
+export type CommandConfig<TType extends string, TInput extends DefaultRecord, TMetadata extends DefaultCommandMetadata | undefined = undefined> = {
+    /** The command type string (e.g., 'CreateUser') */
+    type: TType;
+    /** Zod schema for validating command input */
+    inputSchema: z.ZodType<TInput>;
+    /** Optional Zod schema for validating command metadata */
+    metadataSchema?: z.ZodType<TMetadata>;
+};
+/**
+ * Creates a strongly-typed command factory function.
+ *
+ * This factory validates input and metadata using Zod schemas before
+ * creating commands that can be dispatched through a command flow or aggregate.
+ *
+ * @param config - Configuration object containing type, input schema, and optional metadata schema
+ * @returns A factory function that validates and creates commands
+ *
+ * @example
+ * ```ts
+ * const createUserCommand = defineCommand({
+ *   type: 'CreateUser',
+ *   inputSchema: z.object({ name: z.string(), email: z.email() }),
+ *   metadataSchema: z.object({ now: z.date(), issuedBy: z.string().uuid() }),
+ * });
+ *
+ * const command = createUserCommand(
+ *   { name: 'Ada', email: 'ada@example.org' },
+ *   { now: new Date(), issuedBy: 'usr_123' },
+ * );
+ * ```
+ */
+export declare function defineCommand<TType extends string, TInput extends DefaultRecord, TMetadata extends DefaultCommandMetadata | undefined = undefined>(config: CommandConfig<TType, TInput, TMetadata>): (input: TInput, metadata?: TMetadata) => Command<TType, TInput, TMetadata>;
+//# sourceMappingURL=command.d.ts.map

package/dist/builders/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/builders/command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,aAAa,CACvB,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,aAAa,EAC5B,SAAS,SAAS,sBAAsB,GAAG,SAAS,GAAG,SAAS,IAC9D;IACF,mDAAmD;IACnD,IAAI,EAAE,KAAK,CAAC;IACZ,8CAA8C;IAC9C,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,0DAA0D;IAC1D,cAAc,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,SAAS,MAAM,EACpB,MAAM,SAAS,aAAa,EAC5B,SAAS,SAAS,sBAAsB,GAAG,SAAS,GAAG,SAAS,EAEhE,MAAM,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,GAC9C,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,CAqB5E"}

package/dist/builders/command.js

@@ -0,0 +1,44 @@
+/**
+ * Creates a strongly-typed command factory function.
+ *
+ * This factory validates input and metadata using Zod schemas before
+ * creating commands that can be dispatched through a command flow or aggregate.
+ *
+ * @param config - Configuration object containing type, input schema, and optional metadata schema
+ * @returns A factory function that validates and creates commands
+ *
+ * @example
+ * ```ts
+ * const createUserCommand = defineCommand({
+ *   type: 'CreateUser',
+ *   inputSchema: z.object({ name: z.string(), email: z.email() }),
+ *   metadataSchema: z.object({ now: z.date(), issuedBy: z.string().uuid() }),
+ * });
+ *
+ * const command = createUserCommand(
+ *   { name: 'Ada', email: 'ada@example.org' },
+ *   { now: new Date(), issuedBy: 'usr_123' },
+ * );
+ * ```
+ */
+export function defineCommand(config) {
+    const { type, inputSchema, metadataSchema } = config;
+    return (input, metadata) => {
+        const validatedInput = inputSchema.parse(input);
+        const validatedMetadata = metadataSchema ? metadataSchema.parse(metadata) : metadata;
+        // Conditionally construct the command object based on whether metadata is provided
+        return (validatedMetadata === undefined
+            ? {
+                type,
+                data: validatedInput,
+                kind: 'Command',
+            }
+            : {
+                type,
+                data: validatedInput,
+                metadata: validatedMetadata,
+                kind: 'Command',
+            });
+    };
+}
+//# sourceMappingURL=command.js.map

package/dist/builders/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/builders/command.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,aAAa,CAK3B,MAA+C;IAE/C,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC;IAErD,OAAO,CAAC,KAAa,EAAE,QAAoB,EAAE,EAAE;QAC7C,MAAM,cAAc,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChD,MAAM,iBAAiB,GAAG,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAErF,mFAAmF;QACnF,OAAO,CAAC,iBAAiB,KAAK,SAAS;YACrC,CAAC,CAAC;gBACE,IAAI;gBACJ,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,SAAkB;aACzB;YACH,CAAC,CAAC;gBACE,IAAI;gBACJ,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,iBAAiB;gBAC3B,IAAI,EAAE,SAAkB;aACzB,CAAiD,CAAC;IACzD,CAAC,CAAC;AACJ,CAAC"}

package/dist/builders/decider.d.ts

@@ -0,0 +1,188 @@
+import type { Event as EmmettEvent } from '@event-driven-io/emmett';
+import type { z } from '@arki/contracts';
+import type { AnyEvent } from '../event.js';
+import type { CommandHandler } from './command-handler.js';
+/**
+ * Applies a domain event to the current aggregate state and produces the next state.
+ */
+type Evolve<State, StreamEvent extends AnyEvent> = (state: State, event: StreamEvent) => State;
+/**
+ * Computes the domain events that should be emitted for an incoming command,
+ * based on the aggregate's current state.
+ */
+type Decide<State, Command, StreamEvent extends AnyEvent> = (command: Command, state: State) => StreamEvent[];
+/**
+ * Fluent builder for aggregate behaviour (aka "decider") definitions.
+ *
+ * In many event-sourcing texts this role is called an *aggregate*: an object that owns
+ * the authoritative state, knows how to rebuild itself from events (`evolve`), and
+ * decides which new events should be recorded when commands arrive (`decide`).
+ *
+ * We keep the historical Emmett name `Decider` to match upstream types, but the builder
+ * intentionally documents the aggregate semantics so domain code can align on that
+ * mental model.
+ *
+ * Capabilities:
+ * - Type safety through TypeScript generics
+ * - Optional Zod schemas to validate state evolution at runtime
+ * - Chainable configuration that terminates with `.handler()`, returning the executed aggregate contract
+ *
+ * @example
+ * ```typescript
+ * const cartAggregate = defineDecider()
+ *   .stateSchema(z.object({ items: z.array(z.string()), total: z.number() }))
+ *   .initialState(() => ({ items: [], total: 0 }))
+ *   .evolve((state, event) => {
+ *     if (event.type === 'ItemAdded') {
+ *       return {
+ *         items: [...state.items, event.data.item],
+ *         total: state.total + event.data.price,
+ *       };
+ *     }
+ *     return state;
+ *   })
+ *   .decide((command, state) => {
+ *     if (command.type === 'AddItem') {
+ *       return [
+ *         {
+ *           type: 'ItemAdded',
+ *           data: { item: command.data.item, price: command.data.price },
+ *         },
+ *       ];
+ *     }
+ *     return [];
+ *   })
+ *   .handler();
+ *
+ * const initial = cartAggregate.initialState();
+ * const events = cartAggregate.decide(addItemCommand, initial);
+ * const next = cartAggregate.evolve(initial, events[0]);
+ * ```
+ */
+declare class DeciderBuilder<State = never, Command = never, StreamEvent extends AnyEvent = never> {
+    private _stateSchema?;
+    private _initialStateFn?;
+    private _evolveFn?;
+    private _decideFn?;
+    /**
+     * Creates a deep copy of the builder to ensure immutability
+     * @private
+     */
+    private clone;
+    /**
+     * Sets the state schema for state validation
+     * @param schema - Zod schema for validating state
+     * @returns A new DeciderBuilder instance with the state schema set
+     */
+    stateSchema<TNewState>(schema: z.ZodType<TNewState>): DeciderBuilder<TNewState, Command, StreamEvent>;
+    /**
+     * Sets the initial state function
+     * @param fn - Function that returns the initial state for a new aggregate
+     * @returns A new DeciderBuilder instance with the initial state function set
+     */
+    initialState(fn: () => State): DeciderBuilder<State, Command, StreamEvent>;
+    /**
+     * Sets the evolve function
+     *
+     * This method is generic and will infer the StreamEvent type from the function parameter,
+     * allowing TypeScript to properly infer complex discriminated union types.
+     *
+     * @template TStreamEvent - The union type of all events (inferred from fn parameter)
+     * @param fn - Function that applies an event to state to compute the next state
+     * @returns A new DeciderBuilder instance with the evolve function and inferred event types set
+     */
+    evolve<TStreamEvent extends AnyEvent>(fn: Evolve<State, TStreamEvent>): DeciderBuilder<State, Command, TStreamEvent>;
+    /**
+     * Sets the decide function
+     *
+     * This method is generic and will infer the Command type from the function parameter,
+     * allowing TypeScript to properly infer complex discriminated union types.
+     *
+     * @template TCommand - The union type of all commands (inferred from fn parameter)
+     * @param fn - Function that determines which events to emit for a given command and state
+     * @returns A new DeciderBuilder instance with the decide function and inferred command types set
+     */
+    decide<TCommand>(fn: Decide<State, TCommand, StreamEvent>): DeciderBuilder<State, TCommand, StreamEvent>;
+    /**
+     * Terminal method that creates the decider
+     *
+     * Validates that all required functions are set and returns an object
+     * with three validated functions:
+     * - initialState: Returns the validated initial state
+     * - evolve: Applies an event to state with validation
+     * - decide: Determines events to emit with validation
+     *
+     * @returns An object containing the three core decider functions
+     * @throws Error if state schema, initial state function, evolve function, or decide function are not defined
+     */
+    handler(): {
+        initialState: () => State;
+        evolve: Evolve<State, StreamEvent>;
+        decide: Decide<State, Command, StreamEvent>;
+    };
+    /**
+     * Terminal method that creates a store-connected command handler.
+     *
+     * Unlike `.handler()`, this does **not** require a state schema — it creates
+     * a handler that can be registered directly with an event store. Internally
+     * it delegates to `defineCommandHandler`, which bridges the Emmett type
+     * constraint on command metadata.
+     *
+     * Use this when you need a handler that reads/writes events from a store
+     * (the common case for aggregates), rather than the raw decider functions.
+     *
+     * @returns A store-connected command handler function
+     * @throws Error if initial state, evolve, or decide functions are not defined
+     *
+     * @example
+     * ```typescript
+     * const handler = defineDecider()
+     *   .initialState(() => null as BookState)
+     *   .evolve(evolve)
+     *   .decide(decide)
+     *   .commandHandler();
+     * ```
+     */
+    commandHandler(): StreamEvent extends EmmettEvent ? CommandHandler<State, Command, StreamEvent> : never;
+}
+/**
+ * Factory function to create a new DeciderBuilder
+ *
+ * **Recommended API**: This builder API supports complex discriminated unions
+ * through parameter-based type inference. The `.evolve()` and `.decide()` methods
+ * are generic and will automatically infer types from your function parameters.
+ *
+ * **Use cases:**
+ * - ✅ All cases (simple and complex)
+ * - ✅ Complex discriminated unions (10+ command/event types)
+ * - ✅ Fluent, chainable API preference
+ * - ✅ Automatic type inference from function parameters
+ *
+ * @example
+ * ```typescript
+ * // Works for both simple and complex union types
+ * const decider = defineDecider()
+ *   .stateSchema(myStateSchema)
+ *   .initialState(() => ({ ... }))
+ *   .evolve((state, event) => {
+ *     // TypeScript infers event type from this function
+ *     switch (event.type) {
+ *       case 'EventA': return { ... };
+ *       case 'EventB': return { ... };
+ *       // ... handles 10+ event types correctly
+ *     }
+ *   })
+ *   .decide((command, state) => {
+ *     // TypeScript infers command type from this function
+ *     switch (command.type) {
+ *       case 'CommandA': return [{ type: 'EventA', ... }];
+ *       case 'CommandB': return [{ type: 'EventB', ... }];
+ *       // ... handles 10+ command types correctly
+ *     }
+ *   })
+ *   .handler();
+ * ```
+ */
+export declare function defineDecider(): DeciderBuilder;
+export {};
+//# sourceMappingURL=decider.d.ts.map

package/dist/builders/decider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decider.d.ts","sourceRoot":"","sources":["../../src/builders/decider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,KAAK,EAAE,QAAQ,EAAS,MAAM,aAAa,CAAC;AAGnD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEzD;;GAEG;AACH,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,SAAS,QAAQ,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,KAAK,KAAK,CAAC;AAE/F;;;GAGG;AACH,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,SAAS,QAAQ,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,WAAW,EAAE,CAAC;AAE9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,cAAM,cAAc,CAAC,KAAK,GAAG,KAAK,EAAE,OAAO,GAAG,KAAK,EAAE,WAAW,SAAS,QAAQ,GAAG,KAAK;IACvF,OAAO,CAAC,YAAY,CAAC,CAAmB;IACxC,OAAO,CAAC,eAAe,CAAC,CAAc;IACtC,OAAO,CAAC,SAAS,CAAC,CAA6B;IAC/C,OAAO,CAAC,SAAS,CAAC,CAAsC;IAExD;;;OAGG;IACH,OAAO,CAAC,KAAK;IASb;;;;OAIG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,WAAW,CAAC;IAUrG;;;;OAIG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC;IAO1E;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAY,SAAS,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC;IAUpH;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,GAAG,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC;IAUxG;;;;;;;;;;;OAWG;IACH,OAAO,IAAI;QACT,YAAY,EAAE,MAAM,KAAK,CAAC;QAC1B,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QACnC,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;KAC7C;IAqCD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAAc,IAAI,WAAW,SAAS,WAAW,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,GAAG,KAAK;CAexG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,aAAa,IAAI,cAAc,CAG9C"}