node-cqrs 1.0.0-rc.9 → 1.0.0

package/src/AbstractAggregate.ts

@@ -1,223 +0,0 @@
-import {
-	IAggregate,
-	IMutableAggregateState,
-	ICommand,
-	Identifier,
-	IEvent,
-	IEventSet,
-	IAggregateConstructorParams
-} from './interfaces';
-
-import { getClassName, validateHandlers, getHandler, getMessageHandlerNames } from './utils';
-
-/**
- * Deep-clone simple JS object
- */
-function clone<T>(obj: T): T {
-	return JSON.parse(JSON.stringify(obj));
-}
-
-const SNAPSHOT_EVENT_TYPE = 'snapshot';
-
-/**
- * Base class for Aggregate definition
- */
-export abstract class AbstractAggregate<TState extends IMutableAggregateState | object | void> implements IAggregate {
-
-	/**
-	 * List of command names handled by the Aggregate.
-	 *
-	 * Can be overridden in the Aggregate implementation to explicitly define supported commands.
-	 * If not overridden, all public methods will be treated as command handlers by default.
-	 *
-	 * @example ['createUser', 'changePassword'];
-	 */
-	static get handles(): string[] {
-		return getMessageHandlerNames(this);
-	}
-
-	#id: Identifier;
-	#changes: IEvent[] = [];
-	#version: number = 0;
-	#snapshotVersion: number | undefined;
-
-	/** Internal aggregate state */
-	protected state: TState | undefined;
-
-	/** Command being handled by aggregate */
-	protected command?: ICommand;
-
-	/** Unique aggregate instance identifier */
-	get id(): Identifier {
-		return this.#id;
-	}
-
-	/** Aggregate instance version */
-	get version(): number {
-		return this.#version;
-	}
-
-	/** Restored snapshot version */
-	get snapshotVersion(): number | undefined {
-		return this.#snapshotVersion;
-	}
-
-	/** Events emitted by Aggregate */
-	get changes(): IEventSet {
-		return [...this.#changes];
-	}
-
-	/**
-	 * Override to define whether an aggregate state snapshot should be taken
-	 *
-	 * @example
-	 * 	// create snapshot every 50 events
-	 * 	return this.version % 50 === 0;
-	 */
-	// eslint-disable-next-line class-methods-use-this
-	get shouldTakeSnapshot(): boolean {
-		return false;
-	}
-
-	constructor(options: IAggregateConstructorParams<TState>) {
-		const { id, state, events } = options;
-		if (!id)
-			throw new TypeError('id argument required');
-		if (state && typeof state !== 'object')
-			throw new TypeError('state argument, when provided, must be an Object');
-		if (events && !Array.isArray(events))
-			throw new TypeError('events argument, when provided, must be an Array');
-
-		this.#id = id;
-
-		validateHandlers(this);
-
-		if (state)
-			this.state = state;
-
-		if (events)
-			events.forEach(event => this.mutate(event));
-	}
-
-	/** Pass command to command handler */
-	handle(command: ICommand) {
-		if (!command)
-			throw new TypeError('command argument required');
-		if (!command.type)
-			throw new TypeError('command.type argument required');
-
-		const handler = getHandler(this, command.type);
-		if (!handler)
-			throw new Error(`'${command.type}' handler is not defined or not a function`);
-
-		this.command = command;
-
-		return handler.call(this, command.payload, command.context);
-	}
-
-	/** Mutate aggregate state and increment aggregate version */
-	mutate(event: IEvent) {
-		if (event.aggregateVersion !== undefined)
-			this.#version = event.aggregateVersion;
-
-		if (event.type === SNAPSHOT_EVENT_TYPE) {
-			this.#snapshotVersion = event.aggregateVersion;
-			this.restoreSnapshot(event);
-		}
-		else if (this.state) {
-			const handler = 'mutate' in this.state ?
-				this.state.mutate :
-				getHandler(this.state, event.type);
-			if (handler)
-				handler.call(this.state, event);
-		}
-
-		this.#version += 1;
-	}
-
-	/** Format and register aggregate event and mutate aggregate state */
-	protected emit<TPayload>(type: string, payload?: TPayload) {
-		if (typeof type !== 'string' || !type.length)
-			throw new TypeError('type argument must be a non-empty string');
-
-		const event = this.makeEvent<TPayload>(type, payload, this.command);
-
-		this.emitRaw(event);
-	}
-
-	/** Format event based on a current aggregate state and a command being executed */
-	protected makeEvent<TPayload>(type: string, payload?: TPayload, sourceCommand?: ICommand): IEvent<TPayload> {
-		const event: IEvent<TPayload> = {
-			aggregateId: this.id,
-			aggregateVersion: this.version,
-			type,
-			payload
-		};
-
-		if (sourceCommand) {
-			// augment event with command context
-			const { context, sagaId, sagaVersion } = sourceCommand;
-			if (context !== undefined)
-				event.context = context;
-			if (sagaId !== undefined)
-				event.sagaId = sagaId;
-			if (sagaVersion !== undefined)
-				event.sagaVersion = sagaVersion;
-		}
-
-		return event;
-	}
-
-	/** Register aggregate event and mutate aggregate state */
-	protected emitRaw<TPayload>(event: IEvent<TPayload>): void {
-		if (!event)
-			throw new TypeError('event argument required');
-		if (!event.aggregateId)
-			throw new TypeError('event.aggregateId argument required');
-		if (typeof event.aggregateVersion !== 'number')
-			throw new TypeError('event.aggregateVersion argument must be a Number');
-		if (typeof event.type !== 'string' || !event.type.length)
-			throw new TypeError('event.type argument must be a non-empty String');
-
-		this.mutate(event);
-
-		this.#changes.push(event);
-	}
-
-	/**
-	 * Take an aggregate state snapshot and add it to the changes queue
-	 */
-	takeSnapshot() {
-		this.emit(SNAPSHOT_EVENT_TYPE, this.makeSnapshot());
-	}
-
-	/** Create an aggregate state snapshot */
-	makeSnapshot(): TState {
-		if (!this.state)
-			throw new Error('state property is empty, either define state or override makeSnapshot method');
-
-		return clone(this.state);
-	}
-
-	/** Restore aggregate state from a snapshot */
-	protected restoreSnapshot(snapshotEvent: IEvent<TState>) {
-		if (!snapshotEvent)
-			throw new TypeError('snapshotEvent argument required');
-		if (!snapshotEvent.type)
-			throw new TypeError('snapshotEvent.type argument required');
-		if (!snapshotEvent.payload)
-			throw new TypeError('snapshotEvent.payload argument required');
-
-		if (snapshotEvent.type !== SNAPSHOT_EVENT_TYPE)
-			throw new Error(`${SNAPSHOT_EVENT_TYPE} event type expected`);
-		if (!this.state)
-			throw new Error('state property is empty, either defined state or override restoreSnapshot method');
-
-		Object.assign(this.state, clone(snapshotEvent.payload));
-	}
-
-	/** Get human-readable aggregate identifier */
-	toString(): string {
-		return `${getClassName(this)} ${this.id} (v${this.version})`;
-	}
-}

package/src/AbstractProjection.ts

@@ -1,209 +0,0 @@
-import { describe } from './Event';
-import { InMemoryView } from './in-memory/InMemoryView';
-import {
-	IViewLocker,
-	IEventLocker,
-	IProjection,
-	ILogger,
-	IExtendableLogger,
-	IEventStore,
-	IEvent,
-	isViewLocker,
-	isEventLocker
-} from './interfaces';
-
-import {
-	getClassName,
-	validateHandlers,
-	getHandler,
-	subscribe,
-	getMessageHandlerNames
-} from './utils';
-
-export type AbstractProjectionParams<T> = {
-
-	/**
-	 * The default view associated with the projection.
-	 * Can optionally implement IViewLocker and/or IEventLocker.
-	 */
-	view?: T,
-
-	/**
-	 * Manages view restoration state to prevent early access to an inconsistent view
-	 * or conflicts from concurrent restoration by other processes.
-	 */
-	viewLocker?: IViewLocker,
-
-	/**
-	 * Tracks event processing state to prevent concurrent handling by multiple processes.
-	 */
-	eventLocker?: IEventLocker,
-
-	logger?: ILogger | IExtendableLogger
-}
-
-/**
- * Base class for Projection definition
- */
-export abstract class AbstractProjection<TView = any> implements IProjection<TView> {
-
-	/**
-	 * List of event types handled by the projection. Can be overridden in the projection implementation.
-	 * If not overridden, event types will be inferred from handler methods defined on the Projection class.
-	 */
-	static get handles(): string[] {
-		return getMessageHandlerNames(this);
-	}
-
-	#view?: TView;
-	#viewLocker?: IViewLocker;
-	#eventLocker?: IEventLocker;
-	protected _logger?: ILogger;
-
-	/**
-	 * The default view associated with the projection.
-	 * Can optionally implement IViewLocker and/or IEventLocker.
-	 */
-	public get view(): TView {
-		return this.#view ?? (this.#view = new InMemoryView() as TView);
-	}
-
-	protected set view(value: TView) {
-		this.#view = value;
-	}
-
-	/**
-	 * Manages view restoration state to prevent early access to an inconsistent view
-	 * or conflicts from concurrent restoration by other processes.
-	 */
-	protected get _viewLocker(): IViewLocker | undefined {
-		return this.#viewLocker ?? (isViewLocker(this.view) ? this.view : undefined);
-	}
-
-	protected set _viewLocker(value: IViewLocker | undefined) {
-		this.#viewLocker = value;
-	}
-
-	/**
-	 * Tracks event processing state to prevent concurrent handling by multiple processes.
-	 */
-	protected get _eventLocker(): IEventLocker | undefined {
-		return this.#eventLocker ?? (isEventLocker(this.view) ? this.view : undefined);
-	}
-
-	protected set _eventLocker(value: IEventLocker | undefined) {
-		this.#eventLocker = value;
-	}
-
-	constructor({
-		view,
-		viewLocker,
-		eventLocker,
-		logger
-	}: AbstractProjectionParams<TView> = {}) {
-		validateHandlers(this);
-
-		this.#view = view;
-		this.#viewLocker = viewLocker;
-		this.#eventLocker = eventLocker;
-
-		this._logger = logger && 'child' in logger ?
-			logger.child({ service: getClassName(this) }) :
-			logger;
-	}
-
-	/** Subscribe to event store */
-	async subscribe(eventStore: IEventStore): Promise<void> {
-		subscribe(eventStore, this, {
-			masterHandler: (e: IEvent) => this.project(e)
-		});
-
-		await this.restore(eventStore);
-	}
-
-	/** Pass event to projection event handler */
-	async project(event: IEvent): Promise<void> {
-		if (this._viewLocker && !this._viewLocker?.ready) {
-			this._logger?.debug('view is locked, awaiting until it is ready');
-			await this._viewLocker.once('ready');
-		}
-
-		return this._project(event);
-	}
-
-	/** Pass event to projection event handler, without awaiting for restore operation to complete */
-	protected async _project(event: IEvent): Promise<void> {
-		const handler = getHandler(this, event.type);
-		if (!handler)
-			throw new Error(`'${event.type}' handler is not defined or not a function`);
-
-		if (this._eventLocker) {
-			const eventLockObtained = await this._eventLocker.tryMarkAsProjecting(event);
-			if (!eventLockObtained)
-				return;
-		}
-
-		await handler.call(this, event);
-
-		if (this._eventLocker)
-			await this._eventLocker.markAsProjected(event);
-	}
-
-	/** Restore projection view from event store */
-	async restore(eventStore: IEventStore): Promise<void> {
-		// lock the view to ensure same restoring procedure
-		// won't be performed by another projection instance
-		if (this._viewLocker)
-			await this._viewLocker.lock();
-
-		await this._restore(eventStore);
-
-		if (this._viewLocker)
-			this._viewLocker.unlock();
-	}
-
-	/** Restore projection view from event store */
-	protected async _restore(eventStore: IEventStore): Promise<void> {
-		if (!eventStore)
-			throw new TypeError('eventStore argument required');
-		if (typeof eventStore.getEventsByTypes !== 'function')
-			throw new TypeError('eventStore.getEventsByTypes must be a Function');
-
-		let lastEvent: IEvent | undefined;
-
-		if (this._eventLocker) {
-			this._logger?.debug('retrieving last event projected');
-			lastEvent = await this._eventLocker.getLastEvent();
-		}
-
-		this._logger?.debug(`retrieving ${lastEvent ? `events after ${describe(lastEvent)}` : 'all events'}...`);
-
-		const messageTypes = (this.constructor as typeof AbstractProjection).handles;
-		const eventsIterable = eventStore.getEventsByTypes(messageTypes, { afterEvent: lastEvent });
-
-		let eventsCount = 0;
-		const startTs = Date.now();
-
-		for await (const event of eventsIterable) {
-			try {
-				await this._project(event);
-				eventsCount += 1;
-			}
-			catch (err: any) {
-				this._onRestoringError(err, event);
-			}
-		}
-
-		this._logger?.info(`view restored from ${eventsCount} event(s) in ${Date.now() - startTs} ms`);
-	}
-
-	/** Handle error on restoring. Logs and throws error by default */
-	protected _onRestoringError(error: Error, event: IEvent) {
-		this._logger?.error(`view restoring has failed (view will remain locked): ${error.message}`, {
-			service: getClassName(this),
-			event,
-			stack: error.stack
-		});
-		throw error;
-	}
-}

package/src/AbstractSaga.ts

@@ -1,118 +0,0 @@
-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

@@ -1,131 +0,0 @@
-import {
-	IAggregate,
-	IAggregateConstructor,
-	IAggregateFactory,
-	ICommand,
-	ICommandBus,
-	ICommandHandler,
-	IContainer,
-	Identifier,
-	IEventSet,
-	IEventStore,
-	ILogger
-} from './interfaces';
-
-import {
-	iteratorToArray,
-	getClassName,
-	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
-	}: Pick<IContainer, 'eventStore' | 'logger'> & {
-		aggregateType?: IAggregateConstructor<any>,
-		aggregateFactory?: IAggregateFactory<any>,
-		handles?: string[]
-	}) {
-		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 = AggregateType.handles;
-		}
-		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 eventsIterable = this.#eventStore.getAggregateEvents(id);
-		const events = await iteratorToArray(eventsIterable);
-
-		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) {
-			aggregate.takeSnapshot();
-			events = aggregate.changes;
-		}
-
-		await this.#eventStore.dispatch(events);
-
-		return events;
-	}
-}