node-cqrs 0.17.0 → 1.0.0-beta.0

package/src/EventStore.ts

@@ -1,315 +0,0 @@
-import {
-	IAggregateSnapshotStorage,
-	Identifier,
-	IEvent,
-	IEventQueryFilter,
-	IEventStorage,
-	IEventSet,
-	IExtendableLogger,
-	ILogger,
-	IMessageBus,
-	IMessageHandler,
-	IObservable,
-	IEventStream,
-	IEventStore
-} from "./interfaces";
-import { getClassName, setupOneTimeEmitterSubscription } from "./utils";
-import * as Event from './Event';
-
-const isIEventStorage = (storage: IEventStorage): storage is IEventStorage =>
-	storage
-	&& typeof storage.getNewId === 'function'
-	&& typeof storage.commitEvents === 'function'
-	&& typeof storage.getEvents === 'function'
-	&& typeof storage.getAggregateEvents === 'function'
-	&& typeof storage.getSagaEvents === 'function';
-
-const isIObservable = (obj: IObservable | any): obj is IObservable =>
-	obj
-	&& 'on' in obj
-	&& typeof obj.on === 'function'
-	&& 'off' in obj
-	&& typeof obj.off === 'function';
-
-const isIMessageBus = (bus: IMessageBus | any): bus is IMessageBus =>
-	bus
-	&& isIObservable(bus)
-	&& 'send' in bus
-	&& typeof bus.send === 'function'
-	&& 'publish' in bus
-	&& typeof bus.publish === 'function';
-
-const SNAPSHOT_EVENT_TYPE = 'snapshot';
-
-export class EventStore implements IEventStore {
-
-	#publishAsync: boolean;
-	#validator: (event: IEvent<any>) => void;
-	#logger?: ILogger;
-	#storage: IEventStorage;
-	#messageBus?: IMessageBus;
-	#snapshotStorage: IAggregateSnapshotStorage | undefined;
-	#sagaStarters: string[] = [];
-	#defaultEventEmitter: IObservable;
-
-	/** Whether storage supports aggregate snapshots */
-	get snapshotsSupported(): boolean {
-		return Boolean(this.#snapshotStorage);
-	}
-
-	constructor({
-		storage,
-		messageBus,
-		snapshotStorage,
-		eventValidator = Event.validate,
-		eventStoreConfig,
-		logger
-	}: {
-		storage: IEventStorage,
-		messageBus?: IMessageBus,
-		snapshotStorage?: IAggregateSnapshotStorage,
-		eventValidator?: IMessageHandler,
-		eventStoreConfig?: {
-			publishAsync?: boolean
-		},
-		logger?: ILogger | IExtendableLogger
-	}) {
-		if (!storage)
-			throw new TypeError('storage argument required');
-		if (!isIEventStorage(storage))
-			throw new TypeError('storage does not implement IEventStorage interface');
-		if (messageBus && !isIMessageBus(messageBus))
-			throw new TypeError('messageBus does not implement IMessageBus interface');
-		if (messageBus && isIObservable(storage))
-			throw new TypeError('both storage and messageBus implement IObservable interface, it is not yet supported');
-
-		const defaultEventEmitter = isIObservable(storage) ? storage : messageBus;
-		if (!defaultEventEmitter)
-			throw new TypeError('storage must implement IObservable if messageBus is not injected');
-
-		this.#publishAsync = eventStoreConfig?.publishAsync ?? true;
-		this.#validator = eventValidator;
-		this.#logger = logger && 'child' in logger ?
-			logger.child({ service: getClassName(this) }) :
-			logger;
-		this.#storage = storage;
-		this.#snapshotStorage = snapshotStorage;
-		this.#messageBus = messageBus;
-		this.#defaultEventEmitter = defaultEventEmitter;
-	}
-
-	/** Retrieve new ID from the storage */
-	async getNewId(): Promise<Identifier> {
-		return this.#storage.getNewId();
-	}
-
-	/** Retrieve all events of specific types */
-	async* getAllEvents(eventTypes?: string[]): IEventStream {
-		if (eventTypes && !Array.isArray(eventTypes))
-			throw new TypeError('eventTypes, if specified, must be an Array');
-
-		this.#logger?.debug(`retrieving ${eventTypes ? eventTypes.join(', ') : 'all'} events...`);
-
-		const eventsIterable = await this.#storage.getEvents(eventTypes);
-
-		yield* eventsIterable;
-
-		this.#logger?.debug(`${eventTypes ? eventTypes.join(', ') : 'all'} events retrieved`);
-	}
-
-	/** Retrieve all events of specific Aggregate */
-	async getAggregateEvents(aggregateId: Identifier): Promise<IEventSet> {
-		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;
-
-		const events: IEvent[] = [];
-		if (snapshot)
-			events.push(snapshot);
-
-		const eventsIterable = await this.#storage.getAggregateEvents(aggregateId, { snapshot });
-		for await (const event of eventsIterable)
-			events.push(event);
-
-		this.#logger?.debug(`${Event.describeMultiple(events)} retrieved`);
-
-		return events;
-	}
-
-	/** Retrieve events of specific Saga */
-	async getSagaEvents(sagaId: Identifier, filter: Pick<IEventQueryFilter, "beforeEvent">) {
-		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 events: IEvent[] = [];
-		const eventsIterable = await this.#storage.getSagaEvents(sagaId, filter);
-		for await (const event of eventsIterable)
-			events.push(event);
-
-		this.#logger?.debug(`${Event.describeMultiple(events)} retrieved`);
-
-		return events;
-	}
-
-	/**
-	 * Register event types that start sagas.
-	 * Upon such event commit a new sagaId will be assigned
-	 */
-	registerSagaStarters(eventTypes: string[] = []) {
-		const uniqueEventTypes = eventTypes.filter(e => !this.#sagaStarters.includes(e));
-		this.#sagaStarters.push(...uniqueEventTypes);
-	}
-
-	/**
-	 * Validate events, commit to storage and publish to messageBus, if needed
-	 *
-	 * @param {IEventSet} events - a set of events to commit
-	 * @returns {Promise<IEventSet>} - resolves to signed and committed events
-	 */
-	async commit(events) {
-		if (!Array.isArray(events))
-			throw new TypeError('events argument must be an Array');
-
-		const containsSagaStarters = this.#sagaStarters.length && events.some(e => this.#sagaStarters.includes(e.type));
-		const augmentedEvents = containsSagaStarters ?
-			await this.#attachSagaIdToSagaStarterEvents(events) :
-			events;
-
-		const eventStreamWithoutSnapshots = await this.save(augmentedEvents);
-
-		// after events are saved to the persistent storage,
-		// publish them to the event bus (i.e. RabbitMq)
-		if (this.#messageBus)
-			await this.#publish(eventStreamWithoutSnapshots);
-
-		return eventStreamWithoutSnapshots;
-	}
-
-	/** Generate and attach sagaId to events that start new sagas */
-	async #attachSagaIdToSagaStarterEvents(events: IEventSet): Promise<IEventSet> {
-		const augmentedEvents: IEvent[] = [];
-		for (const event of events) {
-			if (this.#sagaStarters.includes(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;
-	}
-
-	/** Save events to the persistent storage(s) */
-	async save(events: IEventSet): Promise<IEventSet> {
-		if (!Array.isArray(events))
-			throw new TypeError('events argument must be an Array');
-
-		const snapshotEvents = events.filter(e => e.type === SNAPSHOT_EVENT_TYPE);
-		if (snapshotEvents.length > 1)
-			throw new Error(`cannot commit a stream with more than 1 ${SNAPSHOT_EVENT_TYPE} event`);
-		if (snapshotEvents.length && !this.snapshotsSupported)
-			throw new Error(`${SNAPSHOT_EVENT_TYPE} event type is not supported by the storage`);
-
-		const snapshot = snapshotEvents[0];
-		const eventsWithoutSnapshot = events.filter(e => e !== snapshot);
-
-		this.#logger?.debug(`validating ${Event.describeMultiple(eventsWithoutSnapshot)}...`);
-		eventsWithoutSnapshot.forEach(this.#validator);
-
-		this.#logger?.debug(`saving ${Event.describeMultiple(eventsWithoutSnapshot)}...`);
-		await Promise.all([
-			this.#storage.commitEvents(eventsWithoutSnapshot),
-			snapshot ?
-				this.#snapshotStorage?.saveAggregateSnapshot(snapshot) :
-				undefined
-		]);
-
-		return eventsWithoutSnapshot;
-	}
-
-	async #publish(events: IEventSet) {
-		if (this.#publishAsync) {
-			this.#logger?.debug(`publishing ${Event.describeMultiple(events)} asynchronously...`);
-			setImmediate(() => this.#publishEvents(events));
-		}
-		else {
-			this.#logger?.debug(`publishing ${Event.describeMultiple(events)} synchronously...`);
-			await this.#publishEvents(events);
-		}
-	}
-
-	async #publishEvents(events: IEventSet) {
-		if (!this.#messageBus)
-			return;
-
-		try {
-			await Promise.all(events.map(event =>
-				this.#messageBus?.publish(event)));
-
-			this.#logger?.debug(`${Event.describeMultiple(events)} published`);
-		}
-		catch (error: any) {
-			this.#logger?.error(`${Event.describeMultiple(events)} publishing failed: ${error.message}`, {
-				stack: error.stack
-			});
-			throw error;
-		}
-	}
-
-	/** Setup a listener for a specific event type */
-	on(messageType: string, handler: IMessageHandler) {
-		if (typeof messageType !== 'string' || !messageType.length)
-			throw new TypeError('messageType argument must be a non-empty String');
-		if (typeof handler !== 'function')
-			throw new TypeError('handler argument must be a Function');
-		if (arguments.length !== 2)
-			throw new TypeError(`2 arguments are expected, but ${arguments.length} received`);
-
-		if (isIObservable(this.#storage))
-			this.#storage.on(messageType, handler);
-
-		this.#messageBus?.on(messageType, handler);
-	}
-
-	/** Remove previously installed listener */
-	off(messageType: string, handler: IMessageHandler) {
-		if (isIObservable(this.#storage))
-			this.#storage.off(messageType, handler);
-
-		this.#messageBus?.off(messageType, handler);
-	}
-
-	/** Get or create a named queue, which delivers events to a single handler only */
-	queue(name: string): IObservable {
-		if (!this.#defaultEventEmitter.queue)
-			throw new Error('Named queues are not supported by the underlying message bus');
-
-		return this.#defaultEventEmitter.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.#defaultEventEmitter, subscribeTo, filter, handler, this.#logger);
-	}
-}

package/src/SagaEventHandler.ts

@@ -1,161 +0,0 @@
-import * as Event from './Event';
-import {
-	ICommandBus,
-	IEvent,
-	IEventReceptor,
-	IEventStore,
-	IExtendableLogger,
-	ILogger,
-	IObservable,
-	ISaga,
-	ISagaConstructor,
-	ISagaFactory
-} from './interfaces';
-
-import {
-	subscribe,
-	getClassName
-} from './utils';
-
-/**
- * Listens to Saga events,
- * creates new saga or restores it from event store,
- * applies new events
- * and passes command(s) to command bus
- */
-export class SagaEventHandler implements IEventReceptor {
-
-	#eventStore: IEventStore;
-	#commandBus: ICommandBus;
-	#queueName?: string;
-	#logger?: ILogger;
-	#sagaFactory: (params: any) => ISaga;
-	#startsWith: string[];
-	#handles: string[];
-
-	constructor(options: {
-		sagaType?: ISagaConstructor,
-		sagaFactory?: ISagaFactory,
-		eventStore: IEventStore,
-		commandBus: ICommandBus,
-		logger?: ILogger | IExtendableLogger,
-		queueName?: string,
-		startsWith?: string[],
-		handles?: string[]
-	}) {
-		if (!options)
-			throw new TypeError('options argument required');
-		if (!options.eventStore)
-			throw new TypeError('options.eventStore argument required');
-		if (!options.commandBus)
-			throw new TypeError('options.commandBus argument required');
-
-		this.#eventStore = options.eventStore;
-		this.#commandBus = options.commandBus;
-		this.#queueName = options.queueName;
-		this.#logger = options.logger && 'child' in options.logger ?
-			options.logger.child({ service: getClassName(this) }) :
-			options.logger;
-
-		if (options.sagaType) {
-			const SagaType = options.sagaType as ISagaConstructor;
-
-			this.#sagaFactory = params => new SagaType(params);
-			this.#startsWith = SagaType.startsWith;
-			this.#handles = SagaType.handles;
-		}
-		else if (options.sagaFactory) {
-			if (!Array.isArray(options.startsWith))
-				throw new TypeError('options.startsWith argument must be an Array');
-			if (!Array.isArray(options.handles))
-				throw new TypeError('options.handles argument must be an Array');
-
-			this.#sagaFactory = options.sagaFactory;
-			this.#startsWith = options.startsWith;
-			this.#handles = options.handles;
-		}
-		else {
-			throw new Error('Either sagaType or sagaFactory is required');
-		}
-
-		this.#eventStore.registerSagaStarters(options.startsWith);
-	}
-
-	/** Overrides observer subscribe method */
-	subscribe(eventStore: IObservable) {
-		subscribe(eventStore, this, {
-			messageTypes: [...this.#startsWith, ...this.#handles],
-			masterHandler: e => this.handle(e),
-			queueName: this.#queueName
-		});
-	}
-
-	/** Handle saga event */
-	async handle(event: IEvent): Promise<void> {
-		if (!event)
-			throw new TypeError('event argument required');
-		if (!event.type)
-			throw new TypeError('event.type argument required');
-
-		const isSagaStarterEvent = this.#startsWith.includes(event.type);
-		const saga = isSagaStarterEvent ?
-			await this.#createSaga() :
-			await this.#restoreSaga(event);
-
-		const r = saga.apply(event);
-		if (r instanceof Promise)
-			await r;
-
-		await this.#sendCommands(saga, event);
-
-		// additional commands can be added by the saga.onError handler
-		if (saga.uncommittedMessages.length)
-			await this.#sendCommands(saga, event);
-	}
-
-	async #sendCommands(saga: ISaga, event: IEvent<any>) {
-		const commands = saga.uncommittedMessages;
-		saga.resetUncommittedMessages();
-
-		this.#logger?.debug(`"${Event.describe(event)}" processed, ${commands.map(c => c.type).join(',') || 'no commands'} produced`);
-
-		for (const command of commands) {
-
-			// attach event context to produced command
-			if (command.context === undefined && event.context !== undefined)
-				command.context = event.context;
-
-			try {
-				await this.#commandBus.sendRaw(command);
-			}
-			catch (err: any) {
-				if (typeof saga.onError === 'function') {
-					// let saga to handle the error
-					saga.onError(err, { event, command });
-				}
-				else {
-					throw err;
-				}
-			}
-		}
-	}
-
-	/** Start new saga */
-	async #createSaga(): Promise<ISaga> {
-		const id = await this.#eventStore.getNewId();
-		return this.#sagaFactory.call(null, { id });
-	}
-
-	/** Restore saga from event store */
-	async #restoreSaga(event: IEvent): Promise<ISaga> {
-		if (!event.sagaId)
-			throw new TypeError(`${Event.describe(event)} does not contain sagaId`);
-
-		const events = await this.#eventStore.getSagaEvents(event.sagaId, { beforeEvent: event });
-
-		const saga = this.#sagaFactory.call(null, { id: event.sagaId, events });
-		this.#logger?.info(`Saga state restored from ${events.length} event(s)`);
-
-		return saga;
-	}
-}

package/src/index.ts

@@ -1,26 +0,0 @@
-export { CqrsContainerBuilder as ContainerBuilder } from './CqrsContainerBuilder';
-
-export * from './CommandBus';
-export * from './EventStore';
-
-export * from './AbstractAggregate';
-export * from './AggregateCommandHandler';
-export * from './AbstractSaga';
-export * from './SagaEventHandler';
-export * from './AbstractProjection';
-
-export * from './infrastructure/InMemoryMessageBus';
-export * from './infrastructure/InMemoryEventStorage';
-export * from './infrastructure/InMemorySnapshotStorage';
-export * from './infrastructure/InMemoryView';
-export * from './infrastructure/InMemoryLock';
-export * from './infrastructure/utils/Deferred';
-
-export * as Event from './Event';
-export {
-	getMessageHandlerNames,
-	getHandledMessageTypes,
-	subscribe
-} from './utils';
-
-export * from './interfaces';

package/src/infrastructure/InMemoryEventStorage.ts

@@ -1,68 +0,0 @@
-import { IEvent, IEventStorage, IEventSet, IEventStream } from "../interfaces";
-import { nextCycle } from "./utils";
-
-/**
- * A simple event storage implementation intended to use for tests only.
- * Storage content resets on each app restart.
- *
- * @class InMemoryEventStorage
- * @implements {IEventStorage}
- */
-export class InMemoryEventStorage implements IEventStorage {
-
-	#nextId: number = 0;
-	#events: IEventSet = [];
-
-	async commitEvents(events: IEventSet): Promise<IEventSet> {
-		await nextCycle();
-
-		this.#events = this.#events.concat(events);
-
-		await nextCycle();
-
-		return events;
-	}
-
-	async getAggregateEvents(aggregateId, options?: { snapshot: IEvent }): Promise<IEventSet> {
-		await nextCycle();
-
-		const afterVersion = options?.snapshot?.aggregateVersion;
-		const result = !afterVersion ?
-			this.#events.filter(e => e.aggregateId == aggregateId) :
-			this.#events.filter(e =>
-				e.aggregateId == aggregateId &&
-				e.aggregateVersion !== undefined &&
-				e.aggregateVersion > afterVersion);
-
-		await nextCycle();
-
-		return result;
-	}
-
-	async getSagaEvents(sagaId, { beforeEvent }): Promise<IEventSet> {
-		await nextCycle();
-
-		const results = this.#events.filter(e =>
-			e.sagaId == sagaId &&
-			e.sagaVersion !== undefined &&
-			e.sagaVersion < beforeEvent.sagaVersion);
-
-		await nextCycle();
-
-		return results;
-	}
-
-	async* getEvents(eventTypes): IEventStream {
-		await nextCycle();
-
-		for await (const event of this.#events) {
-			if (!eventTypes || eventTypes.includes(event.type))
-				yield event;
-		}
-	}
-
-	getNewId(): number {
-		this.#nextId += 1;
-		return this.#nextId;
-	}
-}

package/src/infrastructure/InMemoryLock.ts

@@ -1,73 +0,0 @@
-import { ILockable, ILockableWithIndication } from "../interfaces";
-import { Deferred } from "./utils";
-
-export class InMemoryLock implements ILockableWithIndication {
-
-	#lockMarker: Deferred<void> | undefined;
-	#innerLock: ILockable | undefined;
-
-	/**
-	 * Indicates if lock is acquired
-	 */
-	get locked(): boolean {
-		return !!this.#lockMarker;
-	}
-
-	/**
-	 * Creates an instance of InMemoryLock
-	 *
-	 * @param innerLock ILockable instance that can persist lock state outside of the current process
-	 */
-	constructor(innerLock?: ILockable) {
-		this.#innerLock = innerLock;
-	}
-
-	/**
-	 * Acquire the lock on the current instance.
-	 * Resolves when the lock is successfully acquired
-	 */
-	async lock(): Promise<void> {
-		while (this.locked)
-			await this.once('unlocked');
-
-		try {
-			this.#lockMarker = new Deferred();
-			if (this.#innerLock)
-				await this.#innerLock.lock();
-		}
-		catch (err: any) {
-			try {
-				await this.unlock();
-			}
-			catch (unlockErr: any) {
-				// unlocking errors are ignored
-			}
-			throw err;
-		}
-	}
-
-	/**
-	 * Release the lock acquired earlier
-	 */
-	async unlock(): Promise<void> {
-		try {
-			if (this.#innerLock)
-				await this.#innerLock.unlock();
-		}
-		finally {
-			this.#lockMarker?.resolve();
-			this.#lockMarker = undefined;
-		}
-	}
-
-	/**
-	 * Wait until the lock is released.
-	 * Resolves immediately if the lock is not acquired
-	 */
-	once(event: 'unlocked'): Promise<void> {
-		if (event !== 'unlocked')
-			throw new TypeError(`Unexpected event type: ${event}`);
-
-		return this.#lockMarker?.promise ?? Promise.resolve();
-	}
-}