@arki/event-sourcing 0.1.0

package/dist/builders/decider.js

@@ -0,0 +1,252 @@
+import { debugBuilder } from '../debug.js';
+import { defineCommandHandler } from './command-handler.js';
+/**
+ * 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]);
+ * ```
+ */
+class DeciderBuilder {
+    _stateSchema;
+    _initialStateFn;
+    _evolveFn;
+    _decideFn;
+    /**
+     * Creates a deep copy of the builder to ensure immutability
+     * @private
+     */
+    clone() {
+        const builder = new DeciderBuilder();
+        builder._stateSchema = this._stateSchema;
+        builder._initialStateFn = this._initialStateFn;
+        builder._evolveFn = this._evolveFn;
+        builder._decideFn = this._decideFn;
+        return builder;
+    }
+    /**
+     * 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(schema) {
+        const builder = new DeciderBuilder();
+        builder._stateSchema = schema;
+        builder._initialStateFn = this._initialStateFn;
+        builder._evolveFn = this._evolveFn;
+        builder._decideFn = this._decideFn;
+        debugBuilder('[decider] Set state schema');
+        return builder;
+    }
+    /**
+     * 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) {
+        const builder = this.clone();
+        builder._initialStateFn = fn;
+        debugBuilder('[decider] Set initial state function');
+        return builder;
+    }
+    /**
+     * 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(fn) {
+        const builder = new DeciderBuilder();
+        builder._stateSchema = this._stateSchema;
+        builder._initialStateFn = this._initialStateFn;
+        builder._evolveFn = fn;
+        builder._decideFn = this._decideFn;
+        debugBuilder('[decider] Set evolve function');
+        return builder;
+    }
+    /**
+     * 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(fn) {
+        const builder = new DeciderBuilder();
+        builder._stateSchema = this._stateSchema;
+        builder._initialStateFn = this._initialStateFn;
+        builder._evolveFn = this._evolveFn;
+        builder._decideFn = fn;
+        debugBuilder('[decider] Set decide function');
+        return builder;
+    }
+    /**
+     * 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() {
+        if (!this._stateSchema || !this._initialStateFn || !this._evolveFn || !this._decideFn) {
+            debugBuilder('[decider] ERROR: Missing required properties');
+            throw new Error('Decider must have state schema, initial state function, evolve function, and decide function defined');
+        }
+        const stateSchema = this._stateSchema;
+        const initialStateFn = this._initialStateFn;
+        const evolveFn = this._evolveFn;
+        const decideFn = this._decideFn;
+        debugBuilder('[decider] Building decider handler');
+        return {
+            initialState: () => {
+                debugBuilder('[decider] Getting initial state');
+                const state = initialStateFn();
+                return stateSchema.parse(state);
+            },
+            evolve: (state, event) => {
+                debugBuilder('[decider] Evolving state with event: %s', event.type);
+                const validatedState = stateSchema.parse(state);
+                const nextState = evolveFn(validatedState, event);
+                return stateSchema.parse(nextState);
+            },
+            decide: (command, state) => {
+                debugBuilder('[decider] Deciding events for command: %s', command.type);
+                const validatedState = stateSchema.parse(state);
+                const events = decideFn(command, validatedState);
+                debugBuilder('[decider] Generated %d event(s)', events.length);
+                return events;
+            },
+        };
+    }
+    /**
+     * 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() {
+        if (!this._initialStateFn || !this._evolveFn || !this._decideFn) {
+            debugBuilder('[decider] ERROR: Missing required properties for command handler');
+            throw new Error('Decider must have initial state function, evolve function, and decide function defined to create a command handler');
+        }
+        debugBuilder('[decider] Building store-connected command handler');
+        return defineCommandHandler({
+            initialState: this._initialStateFn,
+            evolve: this._evolveFn,
+            decide: this._decideFn,
+        });
+    }
+}
+/**
+ * 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 function defineDecider() {
+    debugBuilder('[decider] Creating new decider builder');
+    return new DeciderBuilder();
+}
+//# sourceMappingURL=decider.js.map

package/dist/builders/decider.js.map

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

package/dist/builders/event.d.ts

@@ -0,0 +1,39 @@
+import type { z } from '@arki/contracts';
+import type { Event } from '../event.js';
+import type { DefaultRecord } from '../types.js';
+/**
+ * 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/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,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;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/builders/event.js

@@ -0,0 +1,42 @@
+/**
+ * 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 function defineEvent(config) {
+    const { type, dataSchema, metadataSchema } = config;
+    return (data, metadata) => {
+        const validatedData = dataSchema.parse(data);
+        const validatedMetadata = metadataSchema ? metadataSchema.parse(metadata) : metadata;
+        // Conditionally construct the event object based on whether metadata is provided
+        return (validatedMetadata === undefined
+            ? {
+                type,
+                data: validatedData,
+            }
+            : {
+                type,
+                data: validatedData,
+                metadata: validatedMetadata,
+            });
+    };
+}
+//# sourceMappingURL=event.js.map

package/dist/builders/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../src/builders/event.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,WAAW,CAIzB,MAA4C;IAC5C,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC;IAEpD,OAAO,CAAC,IAAW,EAAE,QAAoB,EAAE,EAAE;QAC3C,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,iBAAiB,GAAG,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAErF,iFAAiF;QACjF,OAAO,CAAC,iBAAiB,KAAK,SAAS;YACrC,CAAC,CAAC;gBACE,IAAI;gBACJ,IAAI,EAAE,aAAa;aACpB;YACH,CAAC,CAAC;gBACE,IAAI;gBACJ,IAAI,EAAE,aAAa;gBACnB,QAAQ,EAAE,iBAAiB;aAC5B,CAA8C,CAAC;IACtD,CAAC,CAAC;AACJ,CAAC"}

package/dist/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.js';
+export { defineCommandHandler, type CommandHandler } from './command-handler.js';
+export { defineEvent } from './event.js';
+export { defineDecider } from './decider.js';
+export { defineProjection } from './projection.js';
+export { defineProcessManager } from './process-manager.js';
+export { defineStatefulProcessManager } from './stateful-process-manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/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,cAAc,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/builders/index.js

@@ -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.js';
+export { defineCommandHandler } from './command-handler.js';
+export { defineEvent } from './event.js';
+export { defineDecider } from './decider.js';
+export { defineProjection } from './projection.js';
+export { defineProcessManager } from './process-manager.js';
+export { defineStatefulProcessManager } from './stateful-process-manager.js';
+//# sourceMappingURL=index.js.map

package/dist/builders/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC"}

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

@@ -0,0 +1,94 @@
+import type { z } from '@arki/contracts';
+import type { Event } from '../event.js';
+/**
+ * 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/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,aAAa,CAAC;AAGzC;;;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/builders/process-manager.js

@@ -0,0 +1,131 @@
+import { debugBuilder } from '../debug.js';
+/**
+ * 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 });
+ *       }
+ *     }
+ *   });
+ * ```
+ */
+class ProcessManagerBuilder {
+    _name;
+    _eventTypes;
+    _contextSchema;
+    _handlerFn;
+    /**
+     * Creates a deep copy of the builder to ensure immutability
+     * @private
+     */
+    clone() {
+        const builder = new ProcessManagerBuilder();
+        builder._name = this._name;
+        builder._eventTypes = this._eventTypes;
+        builder._contextSchema = this._contextSchema;
+        builder._handlerFn = this._handlerFn;
+        return builder;
+    }
+    /**
+     * Sets the process manager name
+     * @param name - Unique identifier for the process manager
+     * @returns A new ProcessManagerBuilder instance with the name set
+     */
+    name(name) {
+        const builder = this.clone();
+        builder._name = name;
+        debugBuilder('[process-manager] Set name: %s', name);
+        return builder;
+    }
+    /**
+     * 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) {
+        const builder = this.clone();
+        builder._eventTypes = types;
+        debugBuilder('[process-manager:%s] Set event types: %o', this._name ?? 'unnamed', types);
+        return builder;
+    }
+    /**
+     * 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(schema) {
+        const builder = new ProcessManagerBuilder();
+        builder._name = this._name;
+        builder._eventTypes = this._eventTypes;
+        builder._contextSchema = schema;
+        builder._handlerFn = this._handlerFn;
+        debugBuilder('[process-manager:%s] Set context schema', this._name ?? 'unnamed');
+        return builder;
+    }
+    /**
+     * 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) {
+        if (!this._name || !this._eventTypes || !this._contextSchema) {
+            debugBuilder('[process-manager] ERROR: Missing required properties');
+            throw new Error('Process manager must have name, eventTypes, and contextSchema defined');
+        }
+        const name = this._name;
+        const eventTypes = this._eventTypes;
+        const contextSchema = this._contextSchema;
+        debugBuilder('[process-manager:%s] Building handler for event types: %o', name, eventTypes);
+        return {
+            processorId: name,
+            canHandle: eventTypes,
+            eachBatch: async (events, context) => {
+                debugBuilder('[process-manager:%s] Validating context', name);
+                const validatedContext = contextSchema.parse(context);
+                debugBuilder('[process-manager:%s] Processing batch of %d events', name, events.length);
+                await fn(events, validatedContext);
+                debugBuilder('[process-manager:%s] Batch processed successfully', name);
+            },
+        };
+    }
+}
+/**
+ * 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 function defineProcessManager() {
+    debugBuilder('[process-manager] Creating new process manager builder');
+    return new ProcessManagerBuilder();
+}
+//# sourceMappingURL=process-manager.js.map