node-cqrs 1.0.0-rc.9 → 1.0.0

package/src/CommandBus.ts

@@ -1,100 +0,0 @@
-import { InMemoryMessageBus } from './in-memory';
-import {
-	ICommand,
-	ICommandBus,
-	IEventSet,
-	IExtendableLogger,
-	ILogger,
-	IMessageBus,
-	IMessageHandler
-} from './interfaces';
-
-export class CommandBus implements ICommandBus {
-
-	#logger?: ILogger;
-	#bus: IMessageBus;
-
-	constructor(o?: {
-		messageBus?: IMessageBus,
-		logger?: ILogger | IExtendableLogger
-	}) {
-		this.#bus = o?.messageBus ?? new InMemoryMessageBus();
-
-		this.#logger = o?.logger && 'child' in o.logger ?
-			o.logger.child({ service: 'CommandBus' }) :
-			o?.logger;
-	}
-
-	/**
-	 * Set up a command handler
-	 */
-	on(commandType: string, handler: IMessageHandler) {
-		if (typeof commandType !== 'string' || !commandType.length)
-			throw new TypeError('commandType argument must be a non-empty String');
-		if (typeof handler !== 'function')
-			throw new TypeError('handler argument must be a Function');
-
-		return this.#bus.on(commandType, handler);
-	}
-
-	/**
-	 * Remove previously installed command handler
-	 */
-	off(commandType: string, handler: IMessageHandler) {
-		if (typeof commandType !== 'string' || !commandType.length)
-			throw new TypeError('commandType argument must be a non-empty String');
-		if (typeof handler !== 'function')
-			throw new TypeError('handler argument must be a Function');
-
-		return this.#bus.off(commandType, handler);
-	}
-
-	/**
-	 * Format and send a command for execution
-	 */
-	send<TPayload>(
-		type: string,
-		aggregateId: string,
-		options: { payload: TPayload, context: object },
-		...otherArgs: object[]
-	): Promise<IEventSet> {
-		if (typeof type !== 'string' || !type.length)
-			throw new TypeError('type argument must be a non-empty String');
-		if (options && typeof options !== 'object')
-			throw new TypeError('options argument, when defined, must be an Object');
-		if (otherArgs.length > 1)
-			throw new TypeError('more than expected arguments supplied');
-
-		// obsolete. left for backward compatibility
-		const optionsContainContext = options && !('context' in options) && !('payload' in options);
-		if (otherArgs.length || optionsContainContext) {
-			const context = options;
-			const payload = otherArgs.length ? otherArgs[0] : undefined;
-			return this.sendRaw({ type, aggregateId, context, payload });
-		}
-
-		return this.sendRaw<TPayload>({ type, aggregateId, ...options });
-	}
-
-	/**
-	 * Send a command for execution
-	 */
-	sendRaw<TPayload>(command: ICommand<TPayload>): Promise<IEventSet> {
-		if (!command)
-			throw new TypeError('command argument required');
-		if (!command.type)
-			throw new TypeError('command.type argument required');
-
-		this.#logger?.debug(`sending '${command.type}' command${command.aggregateId ? ` to ${command.aggregateId}` : ''}...`);
-
-		return this.#bus.send(command).then(r => {
-			this.#logger?.debug(`'${command.type}' ${command.aggregateId ? `on ${command.aggregateId}` : ''} processed`);
-			return r;
-		}, error => {
-			this.#logger?.warn(`'${command.type}' ${command.aggregateId ? `on ${command.aggregateId}` : ''} processing has failed: ${error.message}`, {
-				stack: error.stack
-			});
-			throw error;
-		});
-	}
-}

package/src/CqrsContainerBuilder.ts

@@ -1,124 +0,0 @@
-import { ContainerBuilder, TypeConfig, TClassOrFactory } from 'di0';
-import { AggregateCommandHandler } from './AggregateCommandHandler';
-import { CommandBus } from './CommandBus';
-import { EventStore } from './EventStore';
-import { SagaEventHandler } from './SagaEventHandler';
-import { EventDispatcher } from './EventDispatcher';
-import { InMemoryEventStorage, InMemoryMessageBus, InMemorySnapshotStorage } from './in-memory';
-import { EventValidationProcessor } from './EventValidationProcessor';
-import { isClass } from './utils';
-import {
-	IAggregateConstructor,
-	ICommandHandler,
-	IContainer,
-	IEventReceptor,
-	IProjection,
-	IProjectionConstructor,
-	ISagaConstructor
-} from './interfaces';
-
-export class CqrsContainerBuilder extends ContainerBuilder {
-
-	constructor(options?: {
-		types: Readonly<TypeConfig<any>[]>,
-		singletones: object
-	}) {
-		super(options);
-		super.register(InMemoryMessageBus).as('eventBus');
-		super.register(EventStore).as('eventStore');
-		super.register(CommandBus).as('commandBus');
-		super.register(EventDispatcher).as('eventDispatcher');
-
-		super.register(InMemoryEventStorage).as('eventStorageWriter');
-		super.register(InMemorySnapshotStorage).as('snapshotStorage');
-
-		// Register default event dispatch pipeline:
-		// validate events, write to event storage, write to snapshot storage.
-		// If any of the processors is not defined, it will be skipped.
-		super.register((container: IContainer) => [
-			new EventValidationProcessor(),
-			container.eventStorageWriter,
-			container.snapshotStorage
-		]).as('eventDispatchPipeline');
-	}
-
-	/** Register command handler, which will be subscribed to commandBus upon instance creation */
-	registerCommandHandler(typeOrFactory: TClassOrFactory<ICommandHandler>) {
-		return super.register(
-			(container: IContainer) => {
-				const handler = container.createInstance(typeOrFactory);
-				handler.subscribe(container.commandBus);
-				return handler;
-			})
-			.asSingleInstance();
-	}
-
-	/** Register event receptor, which will be subscribed to eventStore upon instance creation */
-	registerEventReceptor(typeOrFactory: TClassOrFactory<IEventReceptor>) {
-		return super.register(
-			(container: IContainer) => {
-				const receptor = container.createInstance(typeOrFactory);
-				receptor.subscribe(container.eventStore);
-				return receptor;
-			})
-			.asSingleInstance();
-	}
-
-	/**
-	 * Register projection, which will expose view and will be subscribed
-	 * to eventStore and will restore its state upon instance creation
-	 */
-	registerProjection(ProjectionType: IProjectionConstructor, exposedViewAlias?: string) {
-		if (!isClass(ProjectionType))
-			throw new TypeError('ProjectionType argument must be a constructor function');
-
-		const projectionFactory = (container: IContainer): IProjection<any> => {
-			const projection = container.createInstance(ProjectionType);
-			projection.subscribe(container.eventStore);
-
-			if (exposedViewAlias)
-				return projection.view;
-
-			return projection;
-		};
-
-		const t = super.register(projectionFactory).asSingleInstance();
-
-		if (exposedViewAlias)
-			t.as(exposedViewAlias);
-
-		return t;
-	}
-
-	/** Register aggregate type in the container */
-	registerAggregate(AggregateType: IAggregateConstructor<any>) {
-		if (!isClass(AggregateType))
-			throw new TypeError('AggregateType argument must be a constructor function');
-
-		const commandHandlerFactory = (container: IContainer): ICommandHandler =>
-			container.createInstance(AggregateCommandHandler, {
-				aggregateFactory: (options: any) =>
-					container.createInstance(AggregateType, options),
-				handles: AggregateType.handles
-			});
-
-		return this.registerCommandHandler(commandHandlerFactory);
-	}
-
-
-	/** Register saga type in the container */
-	registerSaga(SagaType: ISagaConstructor) {
-		if (!isClass(SagaType))
-			throw new TypeError('SagaType argument must be a constructor function');
-
-		const eventReceptorFactory = (container: IContainer): IEventReceptor =>
-			container.createInstance(SagaEventHandler, {
-				sagaFactory: (options: any) => container.createInstance(SagaType, options),
-				handles: SagaType.handles,
-				startsWith: SagaType.startsWith,
-				queueName: SagaType.name
-			});
-
-		return this.registerEventReceptor(eventReceptorFactory);
-	}
-}

package/src/Event.ts

@@ -1,32 +0,0 @@
-import { IEvent } from './interfaces';
-
-/**
- * Get text description of an event for logging purposes
- */
-export function describe(event: IEvent): string {
-	return `'${event.type}' of ${event.aggregateId} (v${event.aggregateVersion})`;
-}
-
-/**
- * Get text description of a set of events for logging purposes
- */
-export function describeMultiple(events: ReadonlyArray<IEvent>): string {
-	if (events.length === 1)
-		return describe(events[0]);
-
-	return `${events.length} events`;
-}
-
-/**
- * Validate event structure
- */
-export function validate(event: IEvent) {
-	if (typeof event !== 'object' || !event)
-		throw new TypeError('event must be an Object');
-	if (typeof event.type !== 'string' || !event.type.length)
-		throw new TypeError('event.type must be a non-empty String');
-	if (!event.aggregateId && !event.sagaId)
-		throw new TypeError('either event.aggregateId or event.sagaId is required');
-	if (event.sagaId && typeof event.sagaVersion === 'undefined')
-		throw new TypeError('event.sagaVersion is required, when event.sagaId is defined');
-}

package/src/EventDispatcher.ts

@@ -1,173 +0,0 @@
-import {
-	DispatchPipelineBatch,
-	IEvent,
-	IEventDispatcher,
-	IDispatchPipelineProcessor,
-	IEventSet,
-	IEventBus,
-	isEventSet,
-	IContainer,
-	isDispatchPipelineProcessor
-} from './interfaces';
-import { parallelPipe } from 'async-parallel-pipe';
-import { AsyncIterableBuffer } from 'async-iterable-buffer';
-import { getClassName, notEmpty } from './utils';
-import { InMemoryMessageBus } from './in-memory';
-
-type EventBatchEnvelope = {
-	data: DispatchPipelineBatch<{ event?: IEvent }>;
-	error?: Error;
-	resolve: (event: IEvent[]) => void;
-	reject: (error: Error) => void;
-}
-
-export class EventDispatcher implements IEventDispatcher {
-
-	#pipelineInput = new AsyncIterableBuffer<EventBatchEnvelope>();
-	#processors: Array<IDispatchPipelineProcessor> = [];
-	#pipeline: AsyncIterableIterator<EventBatchEnvelope> | IterableIterator<EventBatchEnvelope> = this.#pipelineInput;
-
-	/**
-	 * Event bus where dispatched messages are delivered after processing.
-	 *
-	 * If not provided in the constructor, defaults to an instance of `InMemoryMessageBus`.
-	 */
-	eventBus: IEventBus;
-
-	/**
-	 * Maximum number of event batches that each pipeline processor can handle in parallel.
-	 */
-	concurrentLimit: number;
-
-	constructor(o?: Pick<IContainer, 'eventBus' | 'eventDispatchPipeline'> & {
-		eventDispatcherConfig?: {
-			concurrentLimit?: number
-		}
-	}) {
-		this.eventBus = o?.eventBus ?? new InMemoryMessageBus();
-		this.concurrentLimit = o?.eventDispatcherConfig?.concurrentLimit ?? 100;
-
-		if (o?.eventDispatchPipeline)
-			this.addPipelineProcessors(o.eventDispatchPipeline);
-	}
-
-	addPipelineProcessors(eventDispatchPipeline: IDispatchPipelineProcessor[]) {
-		if (!Array.isArray(eventDispatchPipeline))
-			throw new TypeError('eventDispatchPipeline argument must be an Array');
-
-		for (const processor of eventDispatchPipeline) {
-			if (processor)
-				this.addPipelineProcessor(processor);
-		}
-	}
-
-	/**
-	 * Adds a preprocessor to the event dispatch pipeline.
-	 *
-	 * Preprocessors run in order they are added but process separate batches in parallel, maintaining FIFO order.
-	 */
-	addPipelineProcessor(preprocessor: IDispatchPipelineProcessor) {
-		if (!isDispatchPipelineProcessor(preprocessor))
-			throw new TypeError(`preprocessor ${getClassName(preprocessor)} does not implement IDispatchPipelineProcessor`);
-		if (this.#pipelineProcessing)
-			throw new Error('pipeline processing already started');
-
-		this.#processors.push(preprocessor);
-
-		// Build a processing pipeline that runs preprocessors concurrently, preserving FIFO ordering
-		this.#pipeline = parallelPipe(this.#pipeline, this.concurrentLimit, async envelope => {
-			if (envelope.error)
-				return envelope;
-
-			try {
-				return {
-					...envelope,
-					data: await preprocessor.process(envelope.data)
-				};
-			}
-			catch (error: any) {
-				return {
-					...envelope,
-					error
-				};
-			}
-		});
-	}
-
-	#pipelineProcessing = false;
-
-	/**
-	 * Consume the pipeline, publish events, and resolve/reject each batch
-	 */
-	async #startPipelineProcessing() {
-		if (this.#pipelineProcessing) // should never happen
-			throw new Error('pipeline processing already started');
-
-		this.#pipelineProcessing = true;
-
-		for await (const { error, reject, data, resolve } of this.#pipeline) {
-			if (error) { // some of the preprocessors failed
-				await this.#revert(data);
-				reject(error);
-				continue;
-			}
-
-			const events = data.map(e => e.event).filter(notEmpty);
-
-			try {
-				for (const batch of data) {
-					const { event, ...meta } = batch;
-					if (event)
-						this.eventBus.publish(event, meta);
-				}
-
-				resolve(events);
-			}
-			catch (publishError: any) {
-				reject(publishError);
-			}
-		}
-	}
-
-	/**
-	 * Revert side effects made by pipeline processors in case of a batch processing failure
-	 */
-	async #revert(batch: DispatchPipelineBatch) {
-		for (const processor of this.#processors)
-			await processor.revert?.(batch);
-	}
-
-	/**
-	 * Dispatch a set of events through the processing pipeline.
-	 *
-	 * Returns a promise that resolves after all events are processed and published.
-	 */
-	async dispatch(events: IEventSet, meta?: Record<string, any>) {
-		if (!isEventSet(events) || events.length === 0)
-			throw new Error('dispatch requires a non-empty array of events');
-
-		// const { promise, resolve, reject } = Promise.withResolvers<IEventSet>();
-		let resolve!: (value: IEventSet | PromiseLike<IEventSet>) => void;
-		let reject!: (reason?: any) => void;
-		const promise = new Promise<IEventSet>((res, rej) => {
-			resolve = res;
-			reject = rej;
-		});
-
-		const envelope: EventBatchEnvelope = {
-			data: events.map(event => ({
-				event,
-				...meta
-			})),
-			resolve,
-			reject
-		};
-
-		if (!this.#pipelineProcessing)
-			this.#startPipelineProcessing();
-
-		this.#pipelineInput.push(envelope);
-
-		return promise;
-	}
-}

package/src/EventStore.ts

@@ -1,205 +0,0 @@
-import {
-	IAggregateSnapshotStorage,
-	IEvent,
-	IEventStorageReader,
-	IEventSet,
-	ILogger,
-	IMessageHandler,
-	IObservable,
-	IEventStream,
-	IEventStore,
-	EventQueryAfter,
-	EventQueryBefore,
-	Identifier,
-	IIdentifierProvider,
-	isIdentifierProvider,
-	IEventDispatcher,
-	IEventBus,
-	isIEventBus,
-	isIEventStorageReader,
-	IContainer
-} from './interfaces';
-import {
-	getClassName,
-	setupOneTimeEmitterSubscription
-} from './utils';
-import { EventDispatcher } from './EventDispatcher';
-
-export class EventStore implements IEventStore {
-
-	#identifierProvider: IIdentifierProvider;
-	#eventStorageReader: IEventStorageReader;
-	#snapshotStorage: IAggregateSnapshotStorage | undefined;
-	eventBus: IEventBus;
-	#eventDispatcher: IEventDispatcher;
-	#sagaStarters: Set<string> = new Set();
-	#logger?: ILogger;
-
-	constructor({
-		eventStorageReader,
-		identifierProvider = isIdentifierProvider(eventStorageReader) ? eventStorageReader : undefined,
-		snapshotStorage,
-		eventBus,
-		eventDispatcher,
-		logger
-	}: Pick<IContainer,
-		'identifierProvider' |
-		'eventStorageReader' |
-		'snapshotStorage' |
-		'eventBus' |
-		'eventDispatcher' |
-		'logger'
-	>) {
-		if (!eventStorageReader)
-			throw new TypeError('eventStorageReader argument required');
-		if (!identifierProvider)
-			throw new TypeError('identifierProvider argument required');
-		if (!isIEventStorageReader(eventStorageReader))
-			throw new TypeError('storage does not implement IEventStorage interface');
-		if (eventBus && !isIEventBus(eventBus))
-			throw new TypeError('eventBus does not implement IMessageBus interface');
-
-		this.#eventStorageReader = eventStorageReader;
-		this.#identifierProvider = identifierProvider;
-		this.#snapshotStorage = snapshotStorage;
-		this.#eventDispatcher = eventDispatcher ?? new EventDispatcher({ eventBus });
-		this.eventBus = eventBus ?? this.#eventDispatcher.eventBus;
-		this.#logger = logger && 'child' in logger ?
-			logger.child({ service: getClassName(this) }) :
-			logger;
-	}
-
-	/**
-	 * Generates and returns a new unique identifier using the configured identifier provider.
-	 *
-	 * @returns A promise resolving to a unique identifier suitable for aggregates, sagas, and events.
-	 */
-	async getNewId(): Promise<Identifier> {
-		return this.#identifierProvider.getNewId();
-	}
-
-	async* getEventsByTypes(eventTypes: Readonly<string[]>, options?: EventQueryAfter): IEventStream {
-		if (!Array.isArray(eventTypes))
-			throw new TypeError('eventTypes argument must be an Array');
-
-		this.#logger?.debug(`retrieving ${eventTypes.join(', ')} events...`);
-
-		const eventsIterable = await this.#eventStorageReader.getEventsByTypes(eventTypes, options);
-
-		yield* eventsIterable;
-
-		this.#logger?.debug(`${eventTypes.join(', ')} events retrieved`);
-	}
-
-	/** Retrieve all events of specific Aggregate */
-	async* getAggregateEvents(aggregateId: Identifier): IEventStream {
-		if (!aggregateId)
-			throw new TypeError('aggregateId argument required');
-
-		this.#logger?.debug(`retrieving event stream for aggregate ${aggregateId}...`);
-
-		const snapshot = this.#snapshotStorage ?
-			await this.#snapshotStorage.getAggregateSnapshot(aggregateId) :
-			undefined;
-
-		if (snapshot)
-			yield snapshot;
-
-		const eventsIterable = await this.#eventStorageReader.getAggregateEvents(aggregateId, { snapshot });
-
-		yield* eventsIterable;
-
-		this.#logger?.debug(`all events for aggregate ${aggregateId} retrieved`);
-	}
-
-	/** Retrieve events of specific Saga */
-	async* getSagaEvents(sagaId: Identifier, filter: EventQueryBefore) {
-		if (!sagaId)
-			throw new TypeError('sagaId argument required');
-		if (!filter)
-			throw new TypeError('filter argument required');
-		if (!filter.beforeEvent)
-			throw new TypeError('filter.beforeEvent argument required');
-		if (filter.beforeEvent.sagaVersion === undefined)
-			throw new TypeError('filter.beforeEvent.sagaVersion argument required');
-
-		this.#logger?.debug(`retrieving event stream for saga ${sagaId}, v${filter.beforeEvent.sagaVersion}...`);
-
-		const eventsIterable = await this.#eventStorageReader.getSagaEvents(sagaId, filter);
-
-		yield* eventsIterable;
-
-		this.#logger?.debug(`all events for saga ${sagaId} retrieved`);
-	}
-
-	/**
-	 * Register event types that start sagas.
-	 * Upon such event commit a new sagaId will be assigned
-	 */
-	registerSagaStarters(eventTypes: string[] = []) {
-		for (const eventType of eventTypes)
-			this.#sagaStarters.add(eventType);
-	}
-
-	/**
-	 * Validate events, commit to storage and publish to messageBus, if needed
-	 *
-	 * @param events - a set of events to commit
-	 * @returns Signed and committed events
-	 */
-	async dispatch(events: IEventSet): Promise<IEventSet> {
-		if (!Array.isArray(events))
-			throw new TypeError('events argument must be an Array');
-
-		const augmentedEvents = await this.#attachSagaIdToSagaStarterEvents(events);
-
-		return this.#eventDispatcher.dispatch(augmentedEvents, { origin: 'internal' });
-	}
-
-	/**
-	 * Generate and attach sagaId to events that start new sagas
-	 */
-	async #attachSagaIdToSagaStarterEvents(events: IEventSet): Promise<IEventSet> {
-		if (!this.#sagaStarters.size)
-			return events;
-
-		const augmentedEvents: IEvent[] = [];
-		for (const event of events) {
-			if (this.#sagaStarters.has(event.type)) {
-				if (event.sagaId)
-					throw new Error(`Event "${event.type}" already contains sagaId. Multiple sagas with same event type are not supported`);
-
-				(event as IEvent).sagaId = await this.getNewId();
-				(event as IEvent).sagaVersion = 0;
-
-				augmentedEvents.push(event);
-			}
-			else {
-				augmentedEvents.push(event);
-			}
-		}
-		return augmentedEvents;
-	}
-
-	on(messageType: string, handler: IMessageHandler) {
-		this.eventBus.on(messageType, handler);
-	}
-
-	off(messageType: string, handler: IMessageHandler) {
-		this.eventBus.off(messageType, handler);
-	}
-
-	queue(name: string): IObservable {
-		if (!this.eventBus.queue)
-			throw new Error('Injected eventBus does not support named queues');
-
-		return this.eventBus.queue(name);
-	}
-
-	/** Creates one-time subscription for one or multiple events that match a filter */
-	once(messageTypes: string | string[], handler?: IMessageHandler, filter?: (e: IEvent) => boolean): Promise<IEvent> {
-		const subscribeTo = Array.isArray(messageTypes) ? messageTypes : [messageTypes];
-
-		return setupOneTimeEmitterSubscription(this.eventBus, subscribeTo, filter, handler, this.#logger);
-	}
-}

package/src/EventValidationProcessor.ts

@@ -1,33 +0,0 @@
-import { DispatchPipelineBatch, IEvent, IDispatchPipelineProcessor } from './interfaces';
-import { validate as defaultValidator } from './Event';
-
-export type EventValidator = (event: IEvent) => void;
-
-/**
- * Processor that validates the format of events.
- * Rejects the batch if any event fails validation.
- */
-export class EventValidationProcessor implements IDispatchPipelineProcessor {
-
-	#validate: EventValidator;
-
-	constructor(o?: {
-		eventFormatValidator?: EventValidator
-	}) {
-		this.#validate = o?.eventFormatValidator ?? defaultValidator;
-	}
-
-	/**
-	 * Processes a batch of dispatch pipeline items by validating each event within the batch.
-	 * It iterates through the batch and calls the private `#validate` method for each event found.
-	 *
-	 * This method is part of the `IDispatchPipelineProcessor` interface.
-	 */
-	async process(batch: DispatchPipelineBatch): Promise<DispatchPipelineBatch> {
-		for (const { event } of batch) {
-			if (event)
-				this.#validate(event);
-		}
-		return batch;
-	}
-}