@arki/event-sourcing 0.1.0

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

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

package/dist/builders/projection.d.ts

@@ -0,0 +1,92 @@
+import type { z } from '@arki/contracts';
+import type { AnyEvent } from '../event.js';
+/**
+ * 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/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,aAAa,CAAC;AAG5C;;;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/builders/projection.js

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

package/dist/builders/projection.js.map

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

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

@@ -0,0 +1,181 @@
+import type { z } from '@arki/contracts';
+import type { Event } from '../event.js';
+/**
+ * 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/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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"}