node-cqrs 0.16.3 → 0.17.0

package/src/AbstractSaga.ts

@@ -0,0 +1,118 @@
+import { ICommand, Identifier, IEvent, ISaga, ISagaConstructorParams } from "./interfaces";
+
+import { getClassName, validateHandlers, getHandler } from './utils';
+
+/**
+ * Base class for Saga definition
+ */
+export abstract class AbstractSaga implements ISaga {
+
+	/** List of events that start new saga, must be overridden in Saga implementation */
+	static get startsWith(): string[] {
+		throw new Error('startsWith must be overridden to return a list of event types that start saga');
+	}
+
+	/** List of event types being handled by Saga, must be overridden in Saga implementation */
+	static get handles(): string[] {
+		return [];
+	}
+
+	/** Saga ID */
+	get id(): Identifier {
+		return this.#id;
+	}
+
+	/** Saga version */
+	get version(): number {
+		return this.#version;
+	}
+
+	/** Command execution queue */
+	get uncommittedMessages(): ICommand[] {
+		return Array.from(this.#messages);
+	}
+
+	#id: Identifier;
+	#version = 0;
+	#messages: ICommand[] = [];
+
+	/**
+	 * Creates an instance of AbstractSaga
+	 */
+	constructor(options: ISagaConstructorParams) {
+		if (!options)
+			throw new TypeError('options argument required');
+		if (!options.id)
+			throw new TypeError('options.id argument required');
+
+		this.#id = options.id;
+
+		validateHandlers(this, 'startsWith');
+		validateHandlers(this, 'handles');
+
+		if (options.events) {
+			options.events.forEach(e => this.apply(e));
+			this.resetUncommittedMessages();
+		}
+
+		Object.defineProperty(this, 'restored', { value: true });
+	}
+
+	/** Modify saga state by applying an event */
+	apply(event: IEvent): Promise<void> | void {
+		if (!event)
+			throw new TypeError('event argument required');
+		if (!event.type)
+			throw new TypeError('event.type argument required');
+
+		const handler = getHandler(this, event.type);
+		if (!handler)
+			throw new Error(`'${event.type}' handler is not defined or not a function`);
+
+		const r = handler.call(this, event);
+		if (r instanceof Promise) {
+			return r.then(() => {
+				this.#version += 1;
+			});
+		}
+
+		this.#version += 1;
+		return undefined;
+	}
+
+	/** Format a command and put it to the execution queue */
+	protected enqueue(commandType: string, aggregateId: Identifier | undefined, payload: object) {
+		if (typeof commandType !== 'string' || !commandType.length)
+			throw new TypeError('commandType argument must be a non-empty String');
+		if (!['string', 'number', 'undefined'].includes(typeof aggregateId))
+			throw new TypeError('aggregateId argument must be either string, number or undefined');
+
+		this.enqueueRaw({
+			aggregateId,
+			sagaId: this.id,
+			sagaVersion: this.version,
+			type: commandType,
+			payload
+		});
+	}
+
+	/** Put a command to the execution queue */
+	 protected enqueueRaw(command: ICommand) {
+		if (typeof command !== 'object' || !command)
+			throw new TypeError('command argument must be an Object');
+		if (typeof command.type !== 'string' || !command.type.length)
+			throw new TypeError('command.type argument must be a non-empty String');
+
+		this.#messages.push(command);
+	}
+
+	/** Clear the execution queue */
+	 resetUncommittedMessages() {
+		this.#messages.length = 0;
+	}
+
+	/** Get human-readable Saga name */
+	toString(): string {
+		return `${getClassName(this)} ${this.id} (v${this.version})`;
+	}
+}

package/src/AggregateCommandHandler.ts

@@ -0,0 +1,129 @@
+import {
+	IAggregate,
+	IAggregateConstructor,
+	IAggregateFactory,
+	ICommand,
+	ICommandBus,
+	ICommandHandler,
+	Identifier,
+	IEventSet,
+	IEventStore,
+	IExtendableLogger,
+	ILogger
+} from "./interfaces";
+
+import {
+	getClassName,
+	getHandledMessageTypes,
+	subscribe
+} from './utils';
+
+/**
+ * Aggregate command handler.
+ *
+ * Subscribes to event store and awaits aggregate commands.
+ * Upon command receiving creates an instance of aggregate,
+ * restores its state, passes command and commits emitted events to event store.
+ */
+export class AggregateCommandHandler implements ICommandHandler {
+
+	#eventStore: IEventStore;
+	#logger?: ILogger;
+
+	#aggregateFactory: IAggregateFactory<any>;
+	#handles: string[];
+
+	constructor({
+		eventStore,
+		aggregateType,
+		aggregateFactory,
+		handles,
+		logger
+	}: {
+		eventStore: IEventStore,
+		aggregateType?: IAggregateConstructor<any>,
+		aggregateFactory?: IAggregateFactory<any>,
+		handles?: string[],
+		logger?: ILogger | IExtendableLogger
+	}) {
+		if (!eventStore)
+			throw new TypeError('eventStore argument required');
+
+		this.#eventStore = eventStore;
+		this.#logger = logger && 'child' in logger ?
+			logger.child({ service: getClassName(this) }) :
+			logger;
+
+		if (aggregateType) {
+			const AggregateType = aggregateType;
+			this.#aggregateFactory = params => new AggregateType(params);
+			this.#handles = getHandledMessageTypes(AggregateType);
+		}
+		else if (aggregateFactory) {
+			if (!Array.isArray(handles) || !handles.length)
+				throw new TypeError('handles argument must be an non-empty Array');
+
+			this.#aggregateFactory = aggregateFactory;
+			this.#handles = handles;
+		}
+		else {
+			throw new TypeError('either aggregateType or aggregateFactory is required');
+		}
+	}
+
+	/** Subscribe to all command types handled by aggregateType */
+	subscribe(commandBus: ICommandBus) {
+		subscribe(commandBus, this, {
+			messageTypes: this.#handles,
+			masterHandler: (c: ICommand) => this.execute(c)
+		});
+	}
+
+	/** Restore aggregate from event store events */
+	async #restoreAggregate(id: Identifier): Promise<IAggregate> {
+		if (!id)
+			throw new TypeError('id argument required');
+
+		const events = await this.#eventStore.getAggregateEvents(id);
+		const aggregate = this.#aggregateFactory({ id, events });
+
+		this.#logger?.info(`${aggregate} state restored from ${events.length} event(s)`);
+
+		return aggregate;
+	}
+
+	/** Create new aggregate with new Id generated by event store */
+	async #createAggregate(): Promise<IAggregate> {
+		const id = await this.#eventStore.getNewId();
+		const aggregate = this.#aggregateFactory({ id });
+		this.#logger?.info(`${aggregate} created`);
+
+		return aggregate;
+	}
+
+	/** Pass a command to corresponding aggregate */
+	async execute(cmd: ICommand): Promise<IEventSet> {
+		if (!cmd) throw new TypeError('cmd argument required');
+		if (!cmd.type) throw new TypeError('cmd.type argument required');
+
+		const aggregate = cmd.aggregateId ?
+			await this.#restoreAggregate(cmd.aggregateId) :
+			await this.#createAggregate();
+
+		await aggregate.handle(cmd);
+
+		let events = aggregate.changes;
+		this.#logger?.info(`${aggregate} "${cmd.type}" command processed, ${events.length} event(s) produced`);
+		if (!events.length)
+			return events;
+
+		if (aggregate.shouldTakeSnapshot && this.#eventStore.snapshotsSupported) {
+			aggregate.takeSnapshot();
+			events = aggregate.changes;
+		}
+
+		await this.#eventStore.commit(events);
+
+		return events;
+	}
+}

package/src/CommandBus.ts

@@ -0,0 +1,98 @@
+import { InMemoryMessageBus } from "./infrastructure/InMemoryMessageBus";
+import {
+	ICommand,
+	ICommandBus,
+	IEventSet,
+	IExtendableLogger,
+	ILogger,
+	IMessageBus,
+	IMessageHandler
+} from "./interfaces";
+
+export class CommandBus implements ICommandBus {
+
+	#logger?: ILogger;
+	#bus: IMessageBus;
+
+	/**
+	 * Creates an instance of CommandBus.
+	 */
+	constructor({ messageBus, logger }: {
+		messageBus?: IMessageBus,
+		logger?: ILogger | IExtendableLogger
+	}) {
+		this.#bus = messageBus ?? new InMemoryMessageBus();
+
+		this.#logger = logger && 'child' in logger ?
+			logger.child({ service: 'CommandBus' }) :
+			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

@@ -0,0 +1,120 @@
+import { ContainerBuilder, Container, TypeConfig, TClassOrFactory } from 'di0';
+
+import { AggregateCommandHandler } from './AggregateCommandHandler';
+import { CommandBus } from './CommandBus';
+import { EventStore } from './EventStore';
+import { SagaEventHandler } from './SagaEventHandler';
+import { InMemoryMessageBus } from './infrastructure/InMemoryMessageBus';
+
+import {
+	getHandledMessageTypes,
+	isClass
+} from './utils';
+
+import {
+	IAggregateConstructor,
+	ICommandBus,
+	ICommandHandler,
+	IEventReceptor,
+	IEventStore,
+	IProjection,
+	IProjectionConstructor,
+	ISagaConstructor
+} from './interfaces';
+
+interface CqrsContainer extends Container {
+	eventStore: IEventStore;
+	commandBus: ICommandBus;
+}
+
+export class CqrsContainerBuilder extends ContainerBuilder {
+
+	constructor(options?: {
+		types: Readonly<TypeConfig<any>[]>,
+		singletones: object
+	}) {
+		super(options);
+		super.register(EventStore).as('eventStore');
+		super.register(CommandBus).as('commandBus');
+	}
+
+	/** Register command handler, which will be subscribed to commandBus upon instance creation */
+	registerCommandHandler(typeOrFactory: TClassOrFactory<ICommandHandler>) {
+		return super.register(
+			(container: CqrsContainer) => {
+				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: CqrsContainer) => {
+				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: CqrsContainer): 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: CqrsContainer): ICommandHandler =>
+			container.createInstance(AggregateCommandHandler, {
+				aggregateFactory: (options: any) =>
+					container.createInstance(AggregateType, options),
+				handles: getHandledMessageTypes(AggregateType)
+			});
+
+		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: CqrsContainer): 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

@@ -0,0 +1,43 @@
+import { IEvent } from "./interfaces";
+import * as crypto from 'crypto';
+
+const md5 = (data: object): string => crypto
+	.createHash('md5')
+	.update(JSON.stringify(data))
+	.digest('hex')
+	.replace(/==$/, '');
+
+/**
+ * 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');
+}
+
+export function getId(event: IEvent): string {
+	return event.id ?? md5(event);
+}