@arki/event-sourcing 0.1.0

package/dist/src/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';
+import type { CommandHandler } from './command-handler';
+/**
+ * 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/src/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,UAAU,CAAC;AAGhD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAEtD;;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"}

package/dist/src/builders/event.d.ts

@@ -0,0 +1,39 @@
+import type { z } from '@arki/contracts';
+import type { Event } from '../event';
+import type { DefaultRecord } from '../types';
+/**
+ * Configuration for defining a domain event factory.
+ */
+export type EventConfig<TType extends string, TData extends DefaultRecord, TMetadata extends DefaultRecord | undefined = undefined> = {
+    /** The event type string (e.g., 'UserCreated') */
+    type: TType;
+    /** Zod schema for validating event data */
+    dataSchema: z.ZodType<TData>;
+    /** Optional Zod schema for validating event metadata */
+    metadataSchema?: z.ZodType<TMetadata>;
+};
+/**
+ * Creates a strongly-typed event factory function.
+ *
+ * This factory validates data and metadata using Zod schemas before
+ * creating events that can be appended to Emmett's event store.
+ *
+ * @param config - Configuration object containing type, data schema, and optional metadata schema
+ * @returns A factory function that validates and creates events
+ *
+ * @example
+ * ```ts
+ * const userCreatedEvent = defineEvent({
+ *   type: 'UserCreated',
+ *   dataSchema: z.object({ userId: z.string().uuid(), name: z.string() }),
+ *   metadataSchema: z.object({ now: z.date(), correlationId: z.string().uuid() }),
+ * });
+ *
+ * const event = userCreatedEvent(
+ *   { userId: 'usr_123', name: 'Ada' },
+ *   { now: new Date(), correlationId: 'corr_456' },
+ * );
+ * ```
+ */
+export declare function defineEvent<TType extends string, TData extends DefaultRecord, TMetadata extends DefaultRecord | undefined = undefined>(config: EventConfig<TType, TData, TMetadata>): (data: TData, metadata?: TMetadata) => Event<TType, TData, TMetadata>;
+//# sourceMappingURL=event.d.ts.map

package/dist/src/builders/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../src/builders/event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,WAAW,CACrB,KAAK,SAAS,MAAM,EACpB,KAAK,SAAS,aAAa,EAC3B,SAAS,SAAS,aAAa,GAAG,SAAS,GAAG,SAAS,IACrD;IACF,kDAAkD;IAClD,IAAI,EAAE,KAAK,CAAC;IACZ,2CAA2C;IAC3C,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,wDAAwD;IACxD,cAAc,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CACzB,KAAK,SAAS,MAAM,EACpB,KAAK,SAAS,aAAa,EAC3B,SAAS,SAAS,aAAa,GAAG,SAAS,GAAG,SAAS,EACvD,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,SAAS,KAAK,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAmBrH"}

package/dist/src/builders/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Event Sourcing Builders
+ *
+ * Fluent API builders for constructing event sourcing components with type safety.
+ *
+ * @example
+ * ```typescript
+ * import { defineEvent, defineDecider, defineProjection } from '@arki/event-sourcing/builders';
+ *
+ * // Define an event
+ * const userCreated = defineEvent()
+ *   .type('UserCreated')
+ *   .data(z.object({ userId: z.string(), email: z.string() }))
+ *   .metadata(z.object({ timestamp: z.string() }))
+ *   .handler(({ data, metadata }) => ({ type: 'UserCreated', data, metadata }));
+ *
+ * // Define a decider
+ * const userDecider = defineDecider()
+ *   .stateSchema(userStateSchema)
+ *   .initialState(() => ({ users: [] }))
+ *   .evolve((state, event) => { ... })
+ *   .decide((command, state) => { ... })
+ *   .handler();
+ *
+ * // Define a projection
+ * const userProjection = defineProjection()
+ *   .name('user-projection')
+ *   .eventTypes(['UserCreated', 'UserUpdated'])
+ *   .contextSchema(z.object({ repo: z.any() }))
+ *   .handler(async (events, context) => { ... });
+ * ```
+ */
+export { defineCommand } from './command';
+export { defineCommandHandler, type CommandHandler } from './command-handler';
+export { defineEvent } from './event';
+export { defineDecider } from './decider';
+export { defineProjection } from './projection';
+export { defineProcessManager } from './process-manager';
+export { defineStatefulProcessManager } from './stateful-process-manager';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/builders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/src/builders/process-manager.d.ts

@@ -0,0 +1,94 @@
+import type { z } from '@arki/contracts';
+import type { Event } from '../event';
+/**
+ * Type definition for CanHandle predicate
+ * Used to filter events that a process manager can handle
+ */
+type CanHandle<EventType extends Event> = EventType['type'][];
+/**
+ * Fluent builder for Emmett process managers (sagas).
+ *
+ * Process managers sit outside an aggregate and react to streams of events in order to
+ * coordinate long-running workflows. This builder helps you describe that behaviour with
+ * explicit event filters, a validated execution context, and a terminal `.handler(...)`
+ * that produces the configuration object Emmett expects.
+ *
+ * @example
+ * ```ts
+ * const orderSaga = defineProcessManager<OrderEvent>()
+ *   .name('order-fulfillment')
+ *   .eventTypes(['OrderPlaced', 'PaymentProcessed', 'OrderShipped'])
+ *   .contextSchema(z.object({ messageBus: z.any(), repo: z.any() }))
+ *   .handler(async (events, context) => {
+ *     for (const event of events) {
+ *       if (event.type === 'OrderPlaced') {
+ *         await context.messageBus.send({ type: 'ProcessPayment', data: event.data });
+ *       } else if (event.type === 'PaymentProcessed') {
+ *         await context.messageBus.send({ type: 'ShipOrder', data: event.data });
+ *       }
+ *     }
+ *   });
+ * ```
+ */
+declare class ProcessManagerBuilder<EventType extends Event = never, Context = never> {
+    private _name?;
+    private _eventTypes?;
+    private _contextSchema?;
+    private _handlerFn?;
+    /**
+     * Creates a deep copy of the builder to ensure immutability
+     * @private
+     */
+    private clone;
+    /**
+     * Sets the process manager name
+     * @param name - Unique identifier for the process manager
+     * @returns A new ProcessManagerBuilder instance with the name set
+     */
+    name(name: string): ProcessManagerBuilder<EventType, Context>;
+    /**
+     * Sets the event types this process manager can handle
+     * @param types - Array of event type strings
+     * @returns A new ProcessManagerBuilder instance with the event types set
+     */
+    eventTypes(types: EventType['type'][]): ProcessManagerBuilder<EventType, Context>;
+    /**
+     * Sets the context schema for validation
+     * @param schema - Zod schema for validating the context
+     * @returns A new ProcessManagerBuilder instance with the context schema set
+     */
+    contextSchema<TNewContext>(schema: z.ZodType<TNewContext>): ProcessManagerBuilder<EventType, TNewContext>;
+    /**
+     * Terminal method that creates the process manager
+     *
+     * Validates that all required properties are set and returns an object
+     * with three properties:
+     * - processorId: The process manager identifier
+     * - canHandle: Array of event types to filter events
+     * - eachBatch: Function that validates context and processes event batches
+     *
+     * @param fn - Function that processes event batches to coordinate workflows
+     * @returns An object containing the process manager configuration
+     * @throws Error if name, eventTypes, or contextSchema are not defined
+     */
+    handler(fn: (events: EventType[], context: Context) => Promise<void>): {
+        processorId: string;
+        canHandle: CanHandle<EventType>;
+        eachBatch: (events: EventType[], context: unknown) => Promise<void>;
+    };
+}
+/**
+ * Factory function to create a new ProcessManagerBuilder
+ *
+ * @example
+ * ```typescript
+ * const builder = defineProcessManager<MyEvent>()
+ *   .name('my-process-manager')
+ *   .eventTypes(['EventTypeA', 'EventTypeB'])
+ *   .contextSchema(myContextSchema)
+ *   .handler(async (events, context) => { ... });
+ * ```
+ */
+export declare function defineProcessManager<EventType extends Event = never>(): ProcessManagerBuilder<EventType, never>;
+export {};
+//# sourceMappingURL=process-manager.d.ts.map

package/dist/src/builders/process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../../../src/builders/process-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAGtC;;;GAGG;AACH,KAAK,SAAS,CAAC,SAAS,SAAS,KAAK,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,cAAM,qBAAqB,CAAC,SAAS,SAAS,KAAK,GAAG,KAAK,EAAE,OAAO,GAAG,KAAK;IAC1E,OAAO,CAAC,KAAK,CAAC,CAAS;IACvB,OAAO,CAAC,WAAW,CAAC,CAAsB;IAC1C,OAAO,CAAC,cAAc,CAAC,CAAqB;IAC5C,OAAO,CAAC,UAAU,CAAC,CAA2D;IAE9E;;;OAGG;IACH,OAAO,CAAC,KAAK;IASb;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAAC,SAAS,EAAE,OAAO,CAAC;IAO7D;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,qBAAqB,CAAC,SAAS,EAAE,OAAO,CAAC;IAOjF;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC;IAUzG;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG;QACrE,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;QAChC,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACrE;CAwBF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,SAAS,KAAK,GAAG,KAAK,KAAK,qBAAqB,CAAC,SAAS,EAAE,KAAK,CAAC,CAG/G"}

package/dist/src/builders/projection.d.ts

@@ -0,0 +1,92 @@
+import type { z } from '@arki/contracts';
+import type { AnyEvent } from '../event';
+/**
+ * Type definition for CanHandle predicate
+ * Used to filter events that a projection can handle
+ */
+type CanHandle<EventType extends AnyEvent> = EventType['type'][];
+/**
+ * Fluent builder for read-model projections.
+ *
+ * Projections consume event streams and populate query-side views. This builder captures
+ * the essentials—projection name, handled event types, validated context—and terminates
+ * in a `.handler(...)` call that returns the shape required by Emmett’s projection
+ * registration utilities.
+ *
+ * @example
+ * ```ts
+ * const userProjection = defineProjection<UserEvent>()
+ *   .name('user-projection')
+ *   .eventTypes(['UserCreated', 'UserUpdated'])
+ *   .contextSchema(z.object({ repo: z.any() }))
+ *   .handler(async (events, context) => {
+ *     for (const event of events) {
+ *       if (event.type === 'UserCreated') {
+ *         await context.repo.users.create(event.data);
+ *       }
+ *     }
+ *   });
+ * ```
+ */
+declare class ProjectionBuilder<EventType extends AnyEvent = never, Context = never> {
+    private _name?;
+    private _eventTypes?;
+    private _contextSchema?;
+    private _handlerFn?;
+    /**
+     * Creates a deep copy of the builder to ensure immutability
+     * @private
+     */
+    private clone;
+    /**
+     * Sets the projection name
+     * @param name - Unique identifier for the projection
+     * @returns A new ProjectionBuilder instance with the name set
+     */
+    name(name: string): ProjectionBuilder<EventType, Context>;
+    /**
+     * Sets the event types this projection can handle
+     * @param types - Array of event type strings
+     * @returns A new ProjectionBuilder instance with the event types set
+     */
+    eventTypes(types: EventType['type'][]): ProjectionBuilder<EventType, Context>;
+    /**
+     * Sets the context schema for validation
+     * @param schema - Zod schema for validating the context
+     * @returns A new ProjectionBuilder instance with the context schema set
+     */
+    contextSchema<TNewContext>(schema: z.ZodType<TNewContext>): ProjectionBuilder<EventType, TNewContext>;
+    /**
+     * Terminal method that creates the projection
+     *
+     * Validates that all required properties are set and returns an object
+     * with three properties:
+     * - name: The projection name
+     * - canHandle: Array of event types to filter events
+     * - handle: Function that validates context and processes events
+     *
+     * @param fn - Function that processes events and updates read models
+     * @returns An object containing the projection configuration
+     * @throws Error if name, eventTypes, or contextSchema are not defined
+     */
+    handler(fn: (events: EventType[], context: Context) => Promise<void>): {
+        name: string;
+        canHandle: CanHandle<EventType>;
+        handle: (events: EventType[], context: unknown) => Promise<void>;
+    };
+}
+/**
+ * Factory function to create a new ProjectionBuilder
+ *
+ * @example
+ * ```typescript
+ * const builder = defineProjection<MyEvent>()
+ *   .name('my-projection')
+ *   .eventTypes(['EventTypeA', 'EventTypeB'])
+ *   .contextSchema(myContextSchema)
+ *   .handler(async (events, context) => { ... });
+ * ```
+ */
+export declare function defineProjection<EventType extends AnyEvent = never>(): ProjectionBuilder<EventType, never>;
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/dist/src/builders/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../src/builders/projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGzC;;;GAGG;AACH,KAAK,SAAS,CAAC,SAAS,SAAS,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,cAAM,iBAAiB,CAAC,SAAS,SAAS,QAAQ,GAAG,KAAK,EAAE,OAAO,GAAG,KAAK;IACzE,OAAO,CAAC,KAAK,CAAC,CAAS;IACvB,OAAO,CAAC,WAAW,CAAC,CAAsB;IAC1C,OAAO,CAAC,cAAc,CAAC,CAAqB;IAC5C,OAAO,CAAC,UAAU,CAAC,CAA2D;IAE9E;;;OAGG;IACH,OAAO,CAAC,KAAK;IASb;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC;IAOzD;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC;IAO7E;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,iBAAiB,CAAC,SAAS,EAAE,WAAW,CAAC;IAUrG;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG;QACrE,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;QAChC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAClE;CAwBF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,SAAS,QAAQ,GAAG,KAAK,KAAK,iBAAiB,CAAC,SAAS,EAAE,KAAK,CAAC,CAG1G"}

package/dist/src/builders/stateful-process-manager.d.ts

@@ -0,0 +1,181 @@
+import type { z } from '@arki/contracts';
+import type { Event } from '../event';
+/**
+ * Type definition for CanHandle predicate
+ * Used to filter events that a stateful process manager can handle
+ */
+type CanHandle<EventType extends Event> = EventType['type'][];
+/**
+ * StatefulProcessManagerBuilder - Fluent API for building type-safe stateful process managers (sagas)
+ *
+ * Provides an immutable builder pattern for creating stateful process managers with:
+ * - Type safety through TypeScript generics
+ * - Runtime validation through Zod schemas
+ * - ORPC-style API with .handler() as terminal method
+ * - Persistent state management with load/save operations
+ *
+ * A Stateful Process Manager (Saga) maintains state across events to coordinate complex,
+ * long-running business processes by:
+ * - name: Unique identifier for the stateful process manager
+ * - eventTypes: Array of event types this process manager handles
+ * - stateSchema: Schema for validating process manager state
+ * - contextSchema: Schema for validating execution context
+ * - getStateId: Function to extract state identifier from events
+ * - loadState: Function to load existing state from storage
+ * - saveState: Function to persist state to storage
+ * - handler: Function that processes individual events and returns updated state
+ *
+ * @example
+ * ```typescript
+ * type OrderState = {
+ *   orderId: string;
+ *   status: 'pending' | 'paid' | 'shipped' | 'completed';
+ *   paymentId?: string;
+ *   trackingId?: string;
+ * };
+ *
+ * const orderProcessManager = defineStatefulProcessManager<OrderEvent, OrderState>()
+ *   .name('order-fulfillment')
+ *   .eventTypes(['OrderPlaced', 'PaymentProcessed', 'OrderShipped'])
+ *   .stateSchema(z.object({
+ *     orderId: z.string(),
+ *     status: z.enum(['pending', 'paid', 'shipped', 'completed']),
+ *     paymentId: z.string().optional(),
+ *     trackingId: z.string().optional(),
+ *   }))
+ *   .contextSchema(z.object({ messageBus: z.any(), repo: z.any() }))
+ *   .getStateId(event => `order-${event.data.orderId}`)
+ *   .loadState(async (stateId, context) => {
+ *     return await context.repo.orderSagas.findById(stateId);
+ *   })
+ *   .saveState(async (stateId, state, context) => {
+ *     await context.repo.orderSagas.upsert({ id: stateId, ...state });
+ *   })
+ *   .handler(async (event, state, context) => {
+ *     if (event.type === 'OrderPlaced') {
+ *       // Initialize state for new order
+ *       return {
+ *         orderId: event.data.orderId,
+ *         status: 'pending',
+ *       };
+ *     } else if (event.type === 'PaymentProcessed') {
+ *       // Update state after payment
+ *       return {
+ *         ...state!,
+ *         status: 'paid',
+ *         paymentId: event.data.paymentId,
+ *       };
+ *     } else if (event.type === 'OrderShipped') {
+ *       // Update state after shipping
+ *       return {
+ *         ...state!,
+ *         status: 'shipped',
+ *         trackingId: event.data.trackingId,
+ *       };
+ *     }
+ *     return state!;
+ *   });
+ * ```
+ */
+declare class StatefulProcessManagerBuilder<EventType extends Event = never, State = never, Context = never> {
+    private _name?;
+    private _eventTypes?;
+    private _stateSchema?;
+    private _contextSchema?;
+    private _getStateIdFn?;
+    private _loadStateFn?;
+    private _saveStateFn?;
+    private _handlerFn?;
+    /**
+     * Creates a deep copy of the builder to ensure immutability
+     * @private
+     */
+    private clone;
+    /**
+     * Sets the stateful process manager name
+     * @param name - Unique identifier for the stateful process manager
+     * @returns A new StatefulProcessManagerBuilder instance with the name set
+     */
+    name(name: string): StatefulProcessManagerBuilder<EventType, State, Context>;
+    /**
+     * Sets the event types this stateful process manager can handle
+     * @param types - Array of event type strings
+     * @returns A new StatefulProcessManagerBuilder instance with the event types set
+     */
+    eventTypes(types: EventType['type'][]): StatefulProcessManagerBuilder<EventType, State, Context>;
+    /**
+     * Sets the state schema for validation
+     * @param schema - Zod schema for validating the stateful process manager state
+     * @returns A new StatefulProcessManagerBuilder instance with the state schema set
+     */
+    stateSchema<TNewState>(schema: z.ZodType<TNewState>): StatefulProcessManagerBuilder<EventType, TNewState, Context>;
+    /**
+     * Sets the context schema for validation
+     * @param schema - Zod schema for validating the execution context
+     * @returns A new StatefulProcessManagerBuilder instance with the context schema set
+     */
+    contextSchema<TNewContext>(schema: z.ZodType<TNewContext>): StatefulProcessManagerBuilder<EventType, State, TNewContext>;
+    /**
+     * Sets the function to extract state identifier from events
+     * @param fn - Function that extracts a unique state identifier from an event
+     * @returns A new StatefulProcessManagerBuilder instance with the getStateId function set
+     */
+    getStateId(fn: (event: EventType) => string): StatefulProcessManagerBuilder<EventType, State, Context>;
+    /**
+     * Sets the function to load existing state from storage
+     * @param fn - Function that loads state by identifier, returns null if state doesn't exist
+     * @returns A new StatefulProcessManagerBuilder instance with the loadState function set
+     */
+    loadState(fn: (stateId: string, context: Context) => Promise<State | null>): StatefulProcessManagerBuilder<EventType, State, Context>;
+    /**
+     * Sets the function to persist state to storage
+     * @param fn - Function that saves state by identifier
+     * @returns A new StatefulProcessManagerBuilder instance with the saveState function set
+     */
+    saveState(fn: (stateId: string, state: State, context: Context) => Promise<void>): StatefulProcessManagerBuilder<EventType, State, Context>;
+    /**
+     * Terminal method that creates the stateful process manager
+     *
+     * Validates that all required configuration is set and returns an object
+     * with three properties:
+     * - processorId: The stateful process manager identifier
+     * - canHandle: Array of event types to filter events
+     * - eachBatch: Function that validates context, loads state for each event,
+     *              processes it through the handler, and saves the updated state
+     *
+     * @param fn - Function that processes individual events with their state and returns updated state
+     * @returns An object containing the stateful process manager configuration
+     * @throws Error if name, eventTypes, stateSchema, contextSchema, getStateId, loadState, or saveState are not defined
+     */
+    handler(fn: (event: EventType, state: State | null, context: Context) => Promise<State>): {
+        processorId: string;
+        canHandle: CanHandle<EventType>;
+        eachBatch: (events: EventType[], context: unknown) => Promise<void>;
+    };
+}
+/**
+ * Factory function to create a new StatefulProcessManagerBuilder
+ *
+ * @example
+ * ```typescript
+ * const builder = defineStatefulProcessManager<MyEvent, MyState>()
+ *   .name('my-stateful-process-manager')
+ *   .eventTypes(['EventTypeA', 'EventTypeB'])
+ *   .stateSchema(myStateSchema)
+ *   .contextSchema(myContextSchema)
+ *   .getStateId(event => `state-${event.data.id}`)
+ *   .loadState(async (stateId, context) => {
+ *     return await context.repo.findById(stateId);
+ *   })
+ *   .saveState(async (stateId, state, context) => {
+ *     await context.repo.upsert({ id: stateId, ...state });
+ *   })
+ *   .handler(async (event, state, context) => {
+ *     // Process event and return updated state
+ *     return { ...state, updated: true };
+ *   });
+ * ```
+ */
+export declare function defineStatefulProcessManager<EventType extends Event = never, State = never>(): StatefulProcessManagerBuilder<EventType, State, never>;
+export {};
+//# sourceMappingURL=stateful-process-manager.d.ts.map

package/dist/src/builders/stateful-process-manager.d.ts.map

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

package/dist/src/bus.d.ts

@@ -0,0 +1,3 @@
+export { getInMemoryMessageBus } from '@event-driven-io/emmett';
+export type { CommandBus, EventBus, MessageBus } from '@event-driven-io/emmett';
+//# sourceMappingURL=bus.d.ts.map