node-cqrs 0.16.3 → 0.17.0

package/src/interfaces.ts

@@ -0,0 +1,328 @@
+export type Identifier = string | number;
+
+export interface IMessage<TPayload = any> {
+	/** Event or command type */
+	type: string;
+
+	aggregateId?: Identifier;
+	aggregateVersion?: number;
+
+	sagaId?: Identifier;
+	sagaVersion?: number;
+
+	payload?: TPayload;
+	context?: any;
+}
+
+export type ICommand<TPayload = any> = IMessage<TPayload>;
+
+export type IEvent<TPayload = any> = IMessage<TPayload> & {
+	/** Unique event identifier */
+	id?: string;
+};
+
+/**
+ * @deprecated Try to use `IEventStream` instead
+ */
+export type IEventSet = ReadonlyArray<Readonly<IEvent>>;
+
+export type IEventStream = AsyncIterableIterator<Readonly<IEvent>>;
+
+
+/**
+ * Minimum aggregate interface, as it's used by default `AggregateCommandHandler`
+ */
+export interface IAggregate {
+
+	/** Unique aggregate identifier */
+	readonly id: Identifier;
+
+	/** Main entry point for aggregate commands */
+	handle(command: ICommand): void | Promise<void>;
+
+	/** List of events emitted by Aggregate as a result of handling command(s) */
+	readonly changes: IEventSet;
+
+	/** An indicator if aggregate snapshot should be taken */
+	readonly shouldTakeSnapshot?: boolean;
+
+	/** Take an aggregate state snapshot and add it to the changes queue */
+	takeSnapshot(): void;
+}
+
+export interface IMutableAggregateState {
+	// schemaVersion?: number;
+	// constructor: IAggregateStateConstructor;
+	mutate(event: IEvent): void;
+}
+
+// export interface IAggregateStateConstructor extends Function {
+// 	schemaVersion?: number;
+// 	new(): IAggregateState;
+// }
+
+export type IAggregateConstructorParams<TState extends IMutableAggregateState | object | void> = {
+	/** Unique aggregate identifier */
+	id: Identifier,
+
+	/** Aggregate events, logged after latest snapshot */
+	events?: IEventSet,
+
+	/** Aggregate state instance */
+	state?: TState
+};
+
+export interface IAggregateConstructor<TState extends IMutableAggregateState | object | void> {
+	readonly handles?: string[];
+	new(options: IAggregateConstructorParams<TState>): IAggregate;
+}
+
+export type IAggregateFactory<TState extends IMutableAggregateState | object | void> =
+	(options: IAggregateConstructorParams<TState>) => IAggregate;
+
+export interface ISaga {
+	/** Unique Saga ID */
+	readonly id: Identifier;
+
+	/** List of commands emitted by Saga */
+	readonly uncommittedMessages: ICommand[];
+
+	/** Main entry point for Saga events */
+	apply(event: IEvent): void | Promise<void>;
+
+	/** Reset emitted commands when they are not longer needed */
+	resetUncommittedMessages(): void;
+
+	onError?(error: Error, options: { event: IEvent, command: ICommand }): void;
+}
+
+export type ISagaConstructorParams = {
+	id: Identifier,
+	events?: IEventSet
+};
+
+export type ISagaFactory = (options: ISagaConstructorParams) => ISaga;
+
+export interface ISagaConstructor {
+	new(options: ISagaConstructorParams): ISaga;
+
+	/** List of event types that trigger new saga start */
+	readonly startsWith: string[];
+
+	/** List of events being handled by Saga */
+	readonly handles: string[];
+}
+
+export interface IMessageHandler {
+	(...args: any[]): any | Promise<any>
+};
+
+export interface IObservable {
+	on(type: string, handler: IMessageHandler): void;
+
+	off(type: string, handler: IMessageHandler): void;
+
+	queue?(name: string): IObservable;
+}
+
+export interface IObserver {
+	subscribe(observable: IObservable): void;
+}
+
+/** Commands */
+
+export interface ICommandBus extends IObservable {
+	send(commandType: string, aggregateId: Identifier, options: { payload?: object, context?: object }):
+		Promise<IEventSet>;
+
+	sendRaw(command: ICommand):
+		Promise<IEventSet>;
+
+	on(type: string, handler: IMessageHandler): void;
+}
+
+export interface ICommandHandler extends IObserver {
+	subscribe(commandBus: ICommandBus): void;
+}
+
+/** Events */
+
+export type IEventQueryFilter = {
+	/** Get events emitted after this specific event */
+	afterEvent?: IEvent;
+
+	/** Get events emitted before this specific event */
+	beforeEvent?: IEvent;
+}
+
+export interface IEventStorage {
+	/**
+	 * Create unique identifier 
+	 */
+	getNewId(): Identifier | Promise<Identifier>;
+
+	commitEvents(events: IEventSet): Promise<IEventSet>;
+
+	getEvents(eventTypes?: Readonly<string[]>): IEventStream;
+
+	getAggregateEvents(aggregateId: Identifier, options?: { snapshot?: IEvent }): Promise<IEventSet>;
+
+	getSagaEvents(sagaId: Identifier, options: Pick<IEventQueryFilter, "beforeEvent">): Promise<IEventSet>;
+}
+
+export interface IEventStore extends IObservable {
+	readonly snapshotsSupported?: boolean;
+
+	getNewId(): Identifier | Promise<Identifier>;
+
+	commit(events: IEventSet): Promise<IEventSet>;
+
+	getAllEvents(eventTypes?: Readonly<string[]>): IEventStream;
+
+	getAggregateEvents(aggregateId: Identifier, options?: { snapshot?: IEvent }): Promise<IEventSet>;
+
+	getSagaEvents(sagaId: Identifier, options: Pick<IEventQueryFilter, "beforeEvent">): Promise<IEventSet>;
+
+	once(messageTypes: string | string[], handler?: IMessageHandler, filter?: (e: IEvent) => boolean): Promise<IEvent>;
+
+	queue(name: string): IObservable;
+
+	registerSagaStarters(startsWith: string[] | undefined): void;
+}
+
+export interface IEventReceptor extends IObserver {
+	subscribe(eventStore: IEventStore): void;
+}
+
+export interface IMessageBus extends IObservable {
+	send(command: ICommand): Promise<any>;
+	publish(event: IEvent): Promise<any>;
+}
+
+
+/** Projection */
+
+export interface IProjection<TView extends object> extends IObserver {
+	readonly view: TView;
+
+	subscribe(eventStore: IEventStore): Promise<void>;
+
+	project(event: IEvent): Promise<void>;
+}
+
+export interface IProjectionConstructor {
+	new(c?: any): IProjection<any>;
+	readonly handles?: string[];
+}
+
+// export type ProjectionViewFactoryParams = {
+// 	schemaVersion: string,
+// 	collectionName: string
+// }
+
+export interface IViewFactory<TView> {
+	(): TView;
+}
+
+export interface ILockable {
+	lock(): Promise<any>;
+	unlock(): Promise<any>;
+}
+
+export interface ILockableWithIndication extends ILockable {
+	locked: Readonly<boolean>;
+	once(event: 'unlocked'): Promise<void>;
+}
+
+export interface IProjectionView extends ILockable {
+
+	/**
+	 * Indicates if view is ready for new events projecting
+	 */
+	ready: boolean;
+
+	/**
+	 * Lock the view for external reads/writes
+	 */
+	lock(): Promise<boolean>;
+
+	/**
+	 * Unlock external read/write operations
+	 */
+	unlock(): Promise<void>;
+
+	/**
+	 * Wait till the view is ready to accept new events
+	 */
+	once(eventType: "ready"): Promise<void>;
+}
+
+export interface IPersistentView extends IProjectionView {
+
+	/**
+	 * Get last projected event
+	 */
+	getLastEvent(): Promise<IEvent | undefined>;
+
+	/**
+	 * Mark event as projecting to prevent its handling by another
+	 * projection instance working with the same storage.
+	 *
+	 * @returns False value if event is already processing or processed
+	 */
+	tryMarkAsProjecting(event: IEvent<any>): Promise<boolean>;
+
+	/**
+	 * Mark event as projected
+	 */
+	markAsProjected(event: IEvent<any>): Promise<void>;
+}
+
+
+/** Snapshots */
+
+type TSnapshot<TPayload = object> = {
+	/** 
+	 * Schema version of the data stored in `state` property.
+	 * Snapshots with older schema versions must be passed thru a data migration before applying for a newer schema
+	 */
+	schemaVersion: string | number;
+
+	/**
+	 * Last event that was processed before making a snapshot
+	 */
+	lastEvent: IEvent;
+
+	/**
+	 * Snapshot data
+	 */
+	data: TPayload;
+}
+
+interface ISnapshotStorage {
+	getSnapshot(id: Identifier): Promise<TSnapshot>;
+	saveSnapshot(id: Identifier, snapshot: TSnapshot): Promise<void>;
+}
+
+type ISnapshotEvent<TPayload> = IEvent<TSnapshot<TPayload>>;
+
+export interface IAggregateSnapshotStorage {
+	getAggregateSnapshot<TState>(aggregateId: Identifier): Promise<IEvent<TState> | undefined> | IEvent<TState> | undefined;
+
+	saveAggregateSnapshot<TState>(snapshotEvent: IEvent<TState>): Promise<void> | void;
+}
+
+
+/** Interfaces */
+
+export interface ILogger {
+	log(level: 'debug' | 'info' | 'warn' | 'error', message: string, meta?: { [key: string]: any }): void;
+	debug(message: string, meta?: { [key: string]: any }): void;
+	info(message: string, meta?: { [key: string]: any }): void;
+	warn(message: string, meta?: { [key: string]: any }): void;
+	error(message: string, meta?: { [key: string]: any }): void;
+}
+
+export interface IExtendableLogger extends ILogger {
+	child(meta?: { [key: string]: any }): IExtendableLogger;
+}

package/src/utils/getClassName.ts

@@ -0,0 +1,6 @@
+/**
+ * Get instance class name
+ */
+export function getClassName(instance: object): string {
+	return Object.getPrototypeOf(instance).constructor.name;
+}

package/src/utils/{getHandledMessageTypes.js → getHandledMessageTypes.ts}

@@ -1,13 +1,11 @@
-'use strict';
-
-const getMessageHandlerNames = require('./getMessageHandlerNames');
+import { getMessageHandlerNames } from './getMessageHandlerNames';
 
 /**
  * Get a list of message types handled by observer
- * @param {object | function} observerInstanceOrClass
- * @returns {string[]}
  */
-function getHandledMessageTypes(observerInstanceOrClass) {
+export function getHandledMessageTypes(
+	observerInstanceOrClass: (object | Function) & { handles?: string[] }
+): string[] {
 	if (!observerInstanceOrClass)
 		throw new TypeError('observerInstanceOrClass argument required');
 
@@ -20,5 +18,3 @@ function getHandledMessageTypes(observerInstanceOrClass) {
 
 	return getMessageHandlerNames(observerInstanceOrClass);
 }
-
-module.exports = getHandledMessageTypes;

package/src/utils/{getHandler.js → getHandler.ts}

@@ -1,14 +1,13 @@
-'use strict';
+import { IMessageHandler } from "../interfaces";
 
 /**
  * Gets a handler for a specific message type, prefers a public (w\o _ prefix) method, if available
- * @param  {Object} context
- * @param  {String} messageType
- * @return {IMessageHandler}
  */
-module.exports = function getHandler(context, messageType) {
-	if (!context || typeof context !== 'object') throw new TypeError('context argument required');
-	if (typeof messageType !== 'string' || !messageType.length) throw new TypeError('messageType argument must be a non-empty string');
+export function getHandler(context: { [key: string]: any }, messageType: string): IMessageHandler | null {
+	if (!context || typeof context !== 'object')
+		throw new TypeError('context argument required');
+	if (typeof messageType !== 'string' || !messageType.length)
+		throw new TypeError('messageType argument must be a non-empty string');
 
 	if (messageType in context && typeof context[messageType] === 'function')
 		return context[messageType].bind(context);

package/src/utils/{getMessageHandlerNames.js → getMessageHandlerNames.ts}

@@ -1,10 +1,8 @@
-'use strict';
-
 const KNOWN_METHOD_NAMES = new Set([
 	'subscribe'
 ]);
 
-function getInheritedPropertyNames(prototype) {
+function getInheritedPropertyNames(prototype: object): string[] {
 	const parentPrototype = prototype && Object.getPrototypeOf(prototype);
 	if (!parentPrototype)
 		return [];
@@ -21,11 +19,8 @@ function getInheritedPropertyNames(prototype) {
 /**
  * Get message handler names from a command/event handler class.
  * Assumes all private method names start from underscore ("_").
- *
- * @param {any} observerInstanceOrClass Command or event handler class
- * @returns {string[]}
  */
-function getMessageHandlerNames(observerInstanceOrClass) {
+export function getMessageHandlerNames(observerInstanceOrClass: (object | Function)): string[] {
 	if (!observerInstanceOrClass)
 		throw new TypeError('observerInstanceOrClass argument required');
 
@@ -47,5 +42,3 @@ function getMessageHandlerNames(observerInstanceOrClass) {
 		!KNOWN_METHOD_NAMES.has(key) &&
 		typeof propDescriptors[key].value === 'function');
 }
-
-module.exports = getMessageHandlerNames;

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+export * from './getClassName';
+export * from './getHandler';
+export * from './validateHandlers';
+export * from './getMessageHandlerNames';
+export * from './getHandledMessageTypes';
+export * from './setupOneTimeEmitterSubscription';
+export * from './subscribe';
+export * from './isClass';

package/src/utils/{isClass.js → isClass.ts}

@@ -1,6 +1,4 @@
-'use strict';
-
-module.exports = function isClass(func) {
+export function isClass(func: Function) {
 	return typeof func === 'function'
 		&& Function.prototype.toString.call(func).startsWith('class');
-};
+}

package/src/utils/setupOneTimeEmitterSubscription.ts

@@ -0,0 +1,57 @@
+import { IEvent, ILogger, IObservable } from "../interfaces";
+
+/**
+ * Create one-time eventEmitter subscription for one or multiple events that match a filter
+ *
+ * @param {IObservable} emitter
+ * @param {string[]} messageTypes Array of event type to subscribe to
+ * @param {function(IEvent):any} [handler] Optional handler to execute for a first event received
+ * @param {function(IEvent):boolean} [filter] Optional filter to apply before executing a handler
+ * @param {ILogger} logger
+ * @return {Promise<IEvent>} Resolves to first event that passes filter
+ */
+export function setupOneTimeEmitterSubscription(
+	emitter: IObservable,
+	messageTypes: string[],
+	filter?: (e: IEvent) => boolean,
+	handler?: (e: IEvent) => void,
+	logger?: ILogger
+): Promise<IEvent> {
+	if (typeof emitter !== 'object' || !emitter)
+		throw new TypeError('emitter argument must be an Object');
+	if (!Array.isArray(messageTypes) || messageTypes.some(m => !m || typeof m !== 'string'))
+		throw new TypeError('messageTypes argument must be an Array of non-empty Strings');
+	if (handler && typeof handler !== 'function')
+		throw new TypeError('handler argument, when specified, must be a Function');
+	if (filter && typeof filter !== 'function')
+		throw new TypeError('filter argument, when specified, must be a Function');
+
+	return new Promise(resolve => {
+
+		// handler will be invoked only once,
+		// even if multiple events have been emitted before subscription was destroyed
+		// https://nodejs.org/api/events.html#events_emitter_removelistener_eventname_listener
+		let handled = false;
+
+		function filteredHandler(event: IEvent) {
+			if (filter && !filter(event)) return;
+			if (handled) return;
+			handled = true;
+
+			for (const messageType of messageTypes)
+				emitter.off(messageType, filteredHandler);
+
+			logger?.debug(`'${event.type}' received, one-time subscription to '${messageTypes.join(',')}' removed`);
+
+			if (handler)
+				handler(event);
+
+			resolve(event);
+		}
+
+		for (const messageType of messageTypes)
+			emitter.on(messageType, filteredHandler);
+
+		logger?.debug(`set up one-time ${filter ? 'filtered subscription' : 'subscription'} to '${messageTypes.join(',')}'`);
+	});
+}

package/src/{subscribe.js → utils/subscribe.ts}

@@ -1,21 +1,21 @@
-'use strict';
+import { IMessageHandler, IObservable } from "../interfaces";
+import { getHandler } from './getHandler';
+import { getHandledMessageTypes } from './getHandledMessageTypes';
 
-const { getHandler } = require('./utils');
-const getHandledMessageTypes = require('./utils/getHandledMessageTypes');
-
-const unique = arr => [...new Set(arr)];
+const unique = <T>(arr: T[]): T[] => [...new Set(arr)];
 
 /**
  * Subscribe observer to observable
- *
- * @param {IObservable} observable
- * @param {object} observer
- * @param {object} [options]
- * @param {string[]} [options.messageTypes]
- * @param {IMessageHandler} [options.masterHandler]
- * @param {string} [options.queueName]
  */
-function subscribe(observable, observer, options = {}) {
+export function subscribe(
+	observable: IObservable,
+	observer: object,
+	options: {
+		messageTypes?: string[],
+		masterHandler?: IMessageHandler,
+		queueName?: string
+	} = {}
+) {
 	if (typeof observable !== 'object' || !observable)
 		throw new TypeError('observable argument must be an Object');
 	if (typeof observable.on !== 'function')
@@ -35,14 +35,17 @@ function subscribe(observable, observer, options = {}) {
 
 	for (const messageType of unique(subscribeTo)) {
 		const handler = masterHandler || getHandler(observer, messageType);
-		if (!handler)
+			if (!handler)
 			throw new Error(`'${messageType}' handler is not defined or not a function`);
 
-		if (queueName)
+		if (queueName) {
+			if(!observable.queue)
+				throw new TypeError('Observer does not support named queues');
+
 			observable.queue(queueName).on(messageType, handler);
-		else
+		}
+		else {
 			observable.on(messageType, handler);
+		}
 	}
 }
-
-module.exports = subscribe;

package/src/utils/{validateHandlers.js → validateHandlers.ts}

@@ -1,13 +1,9 @@
-'use strict';
-
-const getHandler = require('./getHandler');
+import { getHandler } from './getHandler';
 
 /**
  * Ensure instance has handlers declared for all handled message types
- *
- * @param {object} instance
  */
-function validateHandlers(instance, handlesFieldName = 'handles') {
+export function validateHandlers(instance: object, handlesFieldName = 'handles') {
 	if (!instance) throw new TypeError('instance argument required');
 
 	const messageTypes = Object.getPrototypeOf(instance).constructor[handlesFieldName];
@@ -21,5 +17,3 @@ function validateHandlers(instance, handlesFieldName = 'handles') {
 			throw new Error(`'${type}' handler is not defined or not a function`);
 	}
 }
-
-module.exports = validateHandlers;

package/index.d.ts

@@ -1,43 +0,0 @@
-export * from "./types/interfaces/IAggregate";
-export * from "./types/interfaces/IAggregateSnapshotStorage";
-export * from "./types/interfaces/ICommandBus";
-export * from "./types/interfaces/ICommandHandler";
-export * from "./types/interfaces/IConcurrentView";
-export * from "./types/interfaces/Identifier";
-export * from "./types/interfaces/IEventReceptor";
-export * from "./types/interfaces/IEventStorage";
-export * from "./types/interfaces/IEventStore";
-export * from "./types/interfaces/IEventStream";
-export * from "./types/interfaces/ILogger";
-export * from "./types/interfaces/IMessageBus";
-export * from "./types/interfaces/IObserver";
-export * from "./types/interfaces/IProjection";
-export * from "./types/interfaces/ISaga";
-export * from "./types/classes/AbstractAggregate";
-export * from "./types/classes/AbstractProjection";
-export * from "./types/classes/AbstractSaga";
-export * from "./types/classes/AggregateCommandHandler";
-export * from "./types/classes/CommandBus";
-export * from "./types/classes/CqrsContainerBuilder";
-export * from "./types/classes/EventStore";
-export * from "./types/classes/EventStream";
-export * from "./types/classes/SagaEventHandler";
-
-export var AbstractAggregate: typeof NodeCqrs.AbstractAggregate;
-export var AbstractProjection: typeof NodeCqrs.AbstractProjection;
-export var AbstractSaga: typeof NodeCqrs.AbstractSaga;
-export var AggregateCommandHandler: typeof NodeCqrs.AggregateCommandHandler;
-export var CommandBus: typeof NodeCqrs.CommandBus;
-export var ContainerBuilder: typeof NodeCqrs.CqrsContainerBuilder;
-export var EventStore: typeof NodeCqrs.EventStore;
-export var EventStream: typeof NodeCqrs.EventStream;
-export var InMemoryEventStorage: typeof NodeCqrs.InMemoryEventStorage;
-export var InMemoryMessageBus: typeof NodeCqrs.InMemoryMessageBus;
-export var InMemorySnapshotStorage: typeof NodeCqrs.InMemorySnapshotStorage;
-export var InMemoryView: typeof NodeCqrs.InMemoryView;
-export var SagaEventHandler: typeof NodeCqrs.SagaEventHandler;
-
-export {
-	getMessageHandlerNames,
-	subscribe
-} from "./src";

package/index.js

@@ -1,3 +0,0 @@
-'use strict';
-
-module.exports = require('./src');

package/jsconfig.json

@@ -1,15 +0,0 @@
-{
-    "compilerOptions": {
-        "target": "es6",
-        "module": "commonjs",
-        "allowSyntheticDefaultImports": true,
-        "checkJs": true,
-        "resolveJsonModule": true,
-        "lib": [
-            "es2018"
-        ]
-    },
-    "exclude": [
-        "node_modules"
-    ]
-}