@arki/event-sourcing 0.1.0

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './command.js';
+export * from './decide.js';
+export * from './event.js';
+export { createSimpleProcessManager } from './simple-process-manager.js';
+export { EVENT_STORE_URL_VARIANTS, eventSourcingFeatures, } from './event-sourcing-features.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EACL,wBAAwB,EACxB,qBAAqB,GAEtB,MAAM,8BAA8B,CAAC"}

package/dist/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "dist",
+  "version": "0.0.0",
+  "private": true
+}

package/dist/process-manager.d.ts

@@ -0,0 +1,113 @@
+import type { AnyEvent, DefaultRecord, Event, EventTypeOf, GlobalPositionTypeOfRecordedMessageMetadata, MessageBus, MessageProcessorStartFrom, ReadEventMetadataWithGlobalPosition } from '@event-driven-io/emmett';
+/**
+ * Process Manager (Saga) handler context
+ * This context is passed to the process manager handler function
+ */
+export type ProcessManagerContext = DefaultRecord & {
+    /** Message bus for sending commands in response to events */
+    messageBus: MessageBus;
+};
+/**
+ * Process Manager handler function
+ */
+export type ProcessManagerHandler<EventType extends Event = AnyEvent, Context extends ProcessManagerContext = ProcessManagerContext> = (events: EventType[], context: Context) => Promise<void>;
+/**
+ * Process Manager configuration options
+ */
+export type ProcessManagerOptions<EventType extends Event = AnyEvent, Context extends ProcessManagerContext = ProcessManagerContext, CheckpointType = GlobalPositionTypeOfRecordedMessageMetadata<ReadEventMetadataWithGlobalPosition>> = {
+    /** Unique identifier for the process manager */
+    name: string;
+    /** Event types the process manager will handle */
+    eventTypes: EventTypeOf<EventType>[];
+    /** Handler function that processes events */
+    handler: ProcessManagerHandler<EventType, Context>;
+    /**
+     * Optional hooks for process manager lifecycle
+     */
+    hooks?: {
+        /** Called when the process manager starts */
+        onStart?: (context: Context) => Promise<void>;
+        /** Called when the process manager closes */
+        onClose?: () => Promise<void>;
+    };
+    /**
+     * Optional configuration for resuming from specific checkpoint
+     * Useful for long-running process managers
+     */
+    startFrom?: MessageProcessorStartFrom<CheckpointType>;
+};
+/**
+ * Creates a process manager (saga) that subscribes to events and orchestrates responses
+ * This is built on top of Emmett's reactor functionality
+ */
+export declare function createProcessManager<EventType extends Event = AnyEvent, Context extends ProcessManagerContext = ProcessManagerContext, CheckpointType = GlobalPositionTypeOfRecordedMessageMetadata<ReadEventMetadataWithGlobalPosition>>(options: ProcessManagerOptions<EventType, Context, CheckpointType>): import("@event-driven-io/emmett").MessageProcessor<EventType, ReadEventMetadataWithGlobalPosition, Context, CheckpointType>;
+/**
+ * State that can be maintained by a stateful process manager
+ */
+export type ProcessManagerState = DefaultRecord;
+/**
+ * Handler function for a stateful process manager
+ */
+export type StatefulProcessManagerHandler<EventType extends Event = AnyEvent, StateType extends ProcessManagerState = ProcessManagerState, Context extends ProcessManagerContext = ProcessManagerContext> = (events: EventType[], state: StateType, context: Context) => Promise<StateType>;
+/**
+ * Options for creating a stateful process manager
+ */
+export type StatefulProcessManagerOptions<EventType extends Event = AnyEvent, StateType extends ProcessManagerState = ProcessManagerState, Context extends ProcessManagerContext = ProcessManagerContext, CheckpointType = GlobalPositionTypeOfRecordedMessageMetadata<ReadEventMetadataWithGlobalPosition>> = Omit<ProcessManagerOptions<EventType, Context, CheckpointType>, 'handler'> & {
+    /** Initial state for the process manager */
+    initialState: StateType;
+    /** Handler function that processes events and updates state */
+    handler: StatefulProcessManagerHandler<EventType, StateType, Context>;
+    /**
+     * Store function that persists process manager state
+     * Called after each successful event processing
+     */
+    storeState?: (state: StateType, processorId: string) => Promise<void>;
+    /**
+     * Load function that retrieves process manager state
+     * Called during initialization
+     */
+    loadState?: (processorId: string) => Promise<StateType | null>;
+};
+/**
+ * Creates a stateful process manager that maintains its own state
+ * This is useful for tracking saga state across event processing
+ */
+export declare function createStatefulProcessManager<EventType extends Event = AnyEvent, StateType extends ProcessManagerState = ProcessManagerState, Context extends ProcessManagerContext = ProcessManagerContext, CheckpointType = GlobalPositionTypeOfRecordedMessageMetadata<ReadEventMetadataWithGlobalPosition>>(options: StatefulProcessManagerOptions<EventType, StateType, Context, CheckpointType>): import("@event-driven-io/emmett").MessageProcessor<EventType, ReadEventMetadataWithGlobalPosition, Context, CheckpointType>;
+/**
+ * Function to generate a unique idempotency key for an event
+ * Used to ensure that a process manager only processes an event once
+ *
+ * @param event The event to generate an idempotency key for
+ * @param processManagerId Optional identifier for the process manager
+ * @returns A string that can be used as an idempotency key
+ */
+export declare function generateIdempotencyKey(event: Event<any, any, ReadEventMetadataWithGlobalPosition>, processManagerId?: string): string;
+/**
+ * Interface for a function to check if an event has already been processed
+ */
+export type IdempotencyCheck = (key: string) => Promise<boolean>;
+/**
+ * Interface for a function to mark an event as processed
+ */
+export type MarkProcessed = (key: string) => Promise<void>;
+/**
+ * Options for idempotent event processing
+ */
+export type IdempotentProcessingOptions = {
+    /** Function to check if an event has already been processed */
+    checkProcessed: IdempotencyCheck;
+    /** Function to mark an event as processed */
+    markProcessed: MarkProcessed;
+    /** Optional process manager ID to include in the idempotency key */
+    processManagerId?: string;
+};
+/**
+ * Higher-order function that wraps a process manager handler to provide idempotent processing
+ * This ensures that each event is only processed once, even if it's received multiple times
+ *
+ * @param handler The original process manager handler
+ * @param options Options for idempotent processing
+ * @returns A wrapped handler that implements idempotent processing
+ */
+export declare function withIdempotentProcessing<EventType extends Event<any, any, ReadEventMetadataWithGlobalPosition> = Event<any, any, ReadEventMetadataWithGlobalPosition>, Context extends ProcessManagerContext = ProcessManagerContext>(handler: ProcessManagerHandler<EventType, Context>, options: IdempotentProcessingOptions): ProcessManagerHandler<EventType, Context>;
+//# sourceMappingURL=process-manager.d.ts.map

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

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

package/dist/process-manager.js

@@ -0,0 +1,155 @@
+import { reactor } from '@event-driven-io/emmett';
+import { debugProcess } from './debug.js';
+/**
+ * Creates a process manager (saga) that subscribes to events and orchestrates responses
+ * This is built on top of Emmett's reactor functionality
+ */
+export function createProcessManager(options) {
+    const { name, eventTypes, handler, hooks, startFrom } = options;
+    debugProcess('[%s] Creating process manager for event types: %o', name, eventTypes);
+    return reactor({
+        processorId: name,
+        canHandle: eventTypes,
+        startFrom,
+        // Process events in batch mode
+        eachBatch: async (events, context) => {
+            debugProcess('[%s] Processing batch of %d events', name, events.length);
+            await handler(events, context);
+            debugProcess('[%s] Batch processed successfully', name);
+        },
+        // Pass through lifecycle hooks
+        hooks: {
+            onStart: async (context) => {
+                debugProcess('[%s] Process manager starting', name);
+                if (hooks?.onStart) {
+                    await hooks.onStart(context);
+                }
+                debugProcess('[%s] Process manager started', name);
+            },
+            onClose: async () => {
+                debugProcess('[%s] Process manager closing', name);
+                if (hooks?.onClose) {
+                    await hooks.onClose();
+                }
+                debugProcess('[%s] Process manager closed', name);
+            },
+        },
+    });
+}
+/**
+ * Creates a stateful process manager that maintains its own state
+ * This is useful for tracking saga state across event processing
+ */
+export function createStatefulProcessManager(options) {
+    const { name, eventTypes, initialState, handler, hooks, startFrom, storeState, loadState } = options;
+    debugProcess('[%s] Creating stateful process manager for event types: %o', name, eventTypes);
+    // Initialize state (will be updated during processing)
+    let state = initialState;
+    return reactor({
+        processorId: name,
+        canHandle: eventTypes,
+        startFrom,
+        hooks: {
+            // Load state during startup
+            onStart: async (context) => {
+                debugProcess('[%s] Stateful process manager starting', name);
+                if (loadState) {
+                    debugProcess('[%s] Loading state from storage', name);
+                    const loadedState = await loadState(name);
+                    if (loadedState) {
+                        state = loadedState;
+                        debugProcess('[%s] State loaded successfully', name);
+                    }
+                    else {
+                        debugProcess('[%s] No stored state found, using initial state', name);
+                    }
+                }
+                // Call user-provided onStart hook if specified
+                if (hooks?.onStart) {
+                    await hooks.onStart(context);
+                }
+                debugProcess('[%s] Stateful process manager started', name);
+            },
+            // Call user-provided onClose hook if specified
+            onClose: async () => {
+                debugProcess('[%s] Stateful process manager closing', name);
+                if (hooks?.onClose) {
+                    await hooks.onClose();
+                }
+                debugProcess('[%s] Stateful process manager closed', name);
+            },
+        },
+        // Process events and update state
+        eachBatch: async (events, context) => {
+            debugProcess('[%s] Processing batch of %d events (stateful)', name, events.length);
+            // Update state based on events
+            state = await handler(events, state, context);
+            debugProcess('[%s] State updated after processing events', name);
+            // Persist updated state if storage function provided
+            if (storeState) {
+                debugProcess('[%s] Storing updated state', name);
+                await storeState(state, name);
+                debugProcess('[%s] State stored successfully', name);
+            }
+        },
+    });
+}
+/**
+ * Function to generate a unique idempotency key for an event
+ * Used to ensure that a process manager only processes an event once
+ *
+ * @param event The event to generate an idempotency key for
+ * @param processManagerId Optional identifier for the process manager
+ * @returns A string that can be used as an idempotency key
+ */
+export function generateIdempotencyKey(event, processManagerId) {
+    // Get the event metadata
+    const metadata = event.metadata;
+    // Create an idempotency key using stream name, position, and optionally process manager ID
+    const baseKey = `${metadata.streamName}:${metadata.streamPosition}:${event.type}`;
+    // Add process manager ID if provided
+    return processManagerId ? `${processManagerId}:${baseKey}` : baseKey;
+}
+/**
+ * Higher-order function that wraps a process manager handler to provide idempotent processing
+ * This ensures that each event is only processed once, even if it's received multiple times
+ *
+ * @param handler The original process manager handler
+ * @param options Options for idempotent processing
+ * @returns A wrapped handler that implements idempotent processing
+ */
+export function withIdempotentProcessing(handler, options) {
+    const { checkProcessed, markProcessed, processManagerId } = options;
+    debugProcess('[%s] Wrapping handler with idempotent processing', processManagerId ?? 'unknown');
+    return async (events, context) => {
+        debugProcess('[%s] Checking idempotency for %d events', processManagerId ?? 'unknown', events.length);
+        // Filter out events that have already been processed
+        const unprocessedEvents = [];
+        const processedKeys = [];
+        // Check each event
+        for (const event of events) {
+            const idempotencyKey = generateIdempotencyKey(event, processManagerId);
+            const alreadyProcessed = await checkProcessed(idempotencyKey);
+            if (alreadyProcessed) {
+                debugProcess('[%s] Event already processed, skipping: %s', processManagerId ?? 'unknown', idempotencyKey);
+            }
+            else {
+                unprocessedEvents.push(event);
+                processedKeys.push(idempotencyKey);
+            }
+        }
+        // If no events need processing, return early
+        if (unprocessedEvents.length === 0) {
+            debugProcess('[%s] All events already processed, skipping batch', processManagerId ?? 'unknown');
+            return;
+        }
+        debugProcess('[%s] Processing %d unprocessed events', processManagerId ?? 'unknown', unprocessedEvents.length);
+        // Process the unprocessed events
+        await handler(unprocessedEvents, context);
+        // Mark all events as processed
+        debugProcess('[%s] Marking %d events as processed', processManagerId ?? 'unknown', processedKeys.length);
+        await Promise.all(processedKeys.map(key => markProcessed(key)));
+        debugProcess('[%s] Idempotent processing completed', processManagerId ?? 'unknown');
+    };
+}
+//# sourceMappingURL=process-manager.js.map

package/dist/process-manager.js.map

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

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

@@ -0,0 +1,37 @@
+import type { Event } from '@event-driven-io/emmett';
+/**
+ * Creates a simple process manager that reacts to events one at a time,
+ * with a pre-bound context closed over at construction time.
+ *
+ * This is a thin wrapper around Emmett's `reactor` that exposes a positional
+ * API with per-message processing semantics. It is intended for the most
+ * common process manager use case where:
+ *
+ * - The context (repositories, KV, message bus, etc.) is fixed at construction time.
+ * - The handler operates on one event at a time rather than a batch.
+ * - Errors propagate to the consumer so the underlying subscription can
+ *   apply retry/back-off policies.
+ *
+ * For richer use cases (per-batch processing, lifecycle hooks, stateful
+ * sagas, idempotency) prefer {@link createProcessManager} or
+ * {@link createStatefulProcessManager} from this package.
+ *
+ * @example
+ * ```ts
+ * const trackingNotifications = createSimpleProcessManager(
+ *   { repo, kv },
+ *   'tracking-notifications',
+ *   ['MovieWatchLogged', 'TvShowRated'],
+ *   async (event, context) => {
+ *     // ... handle one event using context
+ *   },
+ * );
+ * ```
+ *
+ * @param context Fixed context closed over by the process manager handler.
+ * @param name Unique identifier for the process manager (used as processor id).
+ * @param eventTypes Event types this process manager reacts to.
+ * @param handlerFn Async function invoked once per matching event.
+ */
+export declare function createSimpleProcessManager<TEvent extends Event, TContext extends object>(context: TContext, name: string, eventTypes: TEvent['type'][], handlerFn: (event: TEvent, context: TContext) => Promise<void>): import("@event-driven-io/emmett").MessageProcessor<TEvent, import("@event-driven-io/emmett").AnyRecordedMessageMetadata, import("@event-driven-io/emmett").DefaultRecord, any>;
+//# sourceMappingURL=simple-process-manager.d.ts.map

package/dist/simple-process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-process-manager.d.ts","sourceRoot":"","sources":["../src/simple-process-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAKrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,SAAS,KAAK,EAAE,QAAQ,SAAS,MAAM,EACtF,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAC5B,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,kLA0B/D"}

package/dist/simple-process-manager.js

@@ -0,0 +1,55 @@
+import { reactor } from '@event-driven-io/emmett';
+import { debugProcess } from './debug.js';
+/**
+ * Creates a simple process manager that reacts to events one at a time,
+ * with a pre-bound context closed over at construction time.
+ *
+ * This is a thin wrapper around Emmett's `reactor` that exposes a positional
+ * API with per-message processing semantics. It is intended for the most
+ * common process manager use case where:
+ *
+ * - The context (repositories, KV, message bus, etc.) is fixed at construction time.
+ * - The handler operates on one event at a time rather than a batch.
+ * - Errors propagate to the consumer so the underlying subscription can
+ *   apply retry/back-off policies.
+ *
+ * For richer use cases (per-batch processing, lifecycle hooks, stateful
+ * sagas, idempotency) prefer {@link createProcessManager} or
+ * {@link createStatefulProcessManager} from this package.
+ *
+ * @example
+ * ```ts
+ * const trackingNotifications = createSimpleProcessManager(
+ *   { repo, kv },
+ *   'tracking-notifications',
+ *   ['MovieWatchLogged', 'TvShowRated'],
+ *   async (event, context) => {
+ *     // ... handle one event using context
+ *   },
+ * );
+ * ```
+ *
+ * @param context Fixed context closed over by the process manager handler.
+ * @param name Unique identifier for the process manager (used as processor id).
+ * @param eventTypes Event types this process manager reacts to.
+ * @param handlerFn Async function invoked once per matching event.
+ */
+export function createSimpleProcessManager(context, name, eventTypes, handlerFn) {
+    debugProcess('[createSimpleProcessManager] Creating process manager: %s for event types: %s', name, eventTypes.join(', '));
+    return reactor({
+        canHandle: [...eventTypes],
+        eachMessage: async (message) => {
+            debugProcess('[createSimpleProcessManager:%s] Processing event: %s', name, message.type);
+            try {
+                await handlerFn(message, context);
+                debugProcess('[createSimpleProcessManager:%s] Successfully processed event: %s', name, message.type);
+            }
+            catch (error) {
+                debugProcess('[createSimpleProcessManager:%s] Error processing event %s: %s', name, message.type, error instanceof Error ? error.message : String(error));
+                throw error;
+            }
+        },
+        processorId: `process-manager-${name}`,
+    });
+}
+//# sourceMappingURL=simple-process-manager.js.map

package/dist/simple-process-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-process-manager.js","sourceRoot":"","sources":["../src/simple-process-manager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAElD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAiB,EACjB,IAAY,EACZ,UAA4B,EAC5B,SAA8D;IAE9D,YAAY,CACV,+EAA+E,EAC/E,IAAI,EACJ,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CACtB,CAAC;IACF,OAAO,OAAO,CAAS;QACrB,SAAS,EAAE,CAAC,GAAG,UAAU,CAAC;QAC1B,WAAW,EAAE,KAAK,EAAC,OAAO,EAAC,EAAE;YAC3B,YAAY,CAAC,sDAAsD,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YACzF,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAClC,YAAY,CAAC,kEAAkE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YACvG,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,YAAY,CACV,+DAA+D,EAC/D,IAAI,EACJ,OAAO,CAAC,IAAI,EACZ,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;gBACF,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QACD,WAAW,EAAE,mBAAmB,IAAI,EAAE;KACvC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/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/src/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/src/builders/command.d.ts

@@ -0,0 +1,39 @@
+import type { z } from '@arki/contracts';
+import type { Command, DefaultCommandMetadata } from '../command';
+import type { DefaultRecord } from '../types';
+/**
+ * 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/src/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,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;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"}