node-cqrs 1.0.0-rc.9 → 1.0.0

package/src/in-memory/InMemoryView.ts

@@ -1,208 +0,0 @@
-import { InMemoryLock } from './InMemoryLock';
-import { IViewLocker, Identifier, IObjectStorage } from '../interfaces';
-import { nextCycle } from './utils';
-
-/**
- * Update given value with an update Cb and return updated value.
- * Wrapper is needed for backward compatibility with update methods that were modifying the passed in objects directly
- */
-function applyUpdate<T>(view: T, update: (r: T) => T): T {
-	const valueReturnedByUpdate = update(view);
-	return valueReturnedByUpdate === undefined ?
-		view :
-		valueReturnedByUpdate;
-}
-
-/**
- * In-memory Projection View, which suspends get()'s until it is ready
- */
-export class InMemoryView<TRecord> implements IViewLocker, IObjectStorage<TRecord> {
-
-	static factory<TView>(): TView {
-		return (new InMemoryView() as unknown) as TView;
-	}
-
-	protected _map: Map<Identifier, TRecord> = new Map();
-
-	#lock: InMemoryLock;
-
-	/** Whether the view is restored */
-	get ready(): boolean {
-		return !this.#lock.locked;
-	}
-
-	/** Number of records in the View */
-	get size(): number {
-		return this._map.size;
-	}
-
-	constructor() {
-		this.#lock = new InMemoryLock();
-
-		// explicitly bind the `get` method to this object for easier using in Promises
-		Object.defineProperty(this, this.get.name, {
-			value: this.get.bind(this)
-		});
-	}
-
-	/** Lock the view to prevent concurrent modifications */
-	async lock(): Promise<boolean> {
-		await this.#lock.lock();
-		return this.#lock.locked;
-	}
-
-	/** Release the lock */
-	async unlock(): Promise<void> {
-		return this.#lock.unlock();
-	}
-
-	/** Create a Promise which will resolve to a first emitted event of a given type */
-	once(eventType: 'ready'): Promise<any> {
-		if (eventType !== 'ready')
-			throw new TypeError(`Unexpected event type: ${eventType}`);
-
-		return this.#lock.once('unlocked');
-	}
-
-	/**
-	 * Check if view contains a record with a given key.
-	 * This is the only synchronous method, so make sure to check the `ready` flag, if necessary
-	 *
-	 * @deprecated Use `async get()` instead
-	 */
-	has(key: Identifier): boolean {
-		return this._map.has(key);
-	}
-
-	/** Get record with a given key; await until the view is restored */
-	async get(key: Identifier, options?: { nowait?: boolean }): Promise<TRecord | undefined> {
-		if (!key)
-			throw new TypeError('key argument required');
-
-		if (!this.ready && !options?.nowait)
-			await this.once('ready');
-
-		await nextCycle();
-
-		return this._map.get(key);
-	}
-
-	/**
-	 * Get record with a given key synchronously
-	 */
-	getSync(key: Identifier): TRecord | undefined {
-		if (!key)
-			throw new TypeError('key argument required');
-
-		return this._map.get(key);
-	}
-
-	/** Get all records matching an optional filter */
-	async getAll(filter?: (r: TRecord | undefined, i: Identifier) => boolean):
-		Promise<Array<[Identifier, TRecord | undefined]>> {
-		if (filter && typeof filter !== 'function')
-			throw new TypeError('filter argument, when defined, must be a Function');
-
-		if (!this.ready)
-			await this.once('ready');
-
-		await nextCycle();
-
-		const r: Array<[Identifier, TRecord | undefined]> = [];
-		for (const entry of this._map.entries()) {
-			if (!filter || filter(entry[1], entry[0]))
-				r.push(entry);
-		}
-
-		return r;
-	}
-
-	/** Create record with a given key and value */
-	async create(key: Identifier, value: TRecord = {} as TRecord) {
-		if (!key)
-			throw new TypeError('key argument required');
-		if (typeof value === 'function')
-			throw new TypeError('value argument must be an instance of an Object');
-
-		if (this._map.has(key))
-			throw new Error(`Key '${key}' already exists`);
-
-		this._map.set(key, value);
-	}
-
-	/** Update existing view record */
-	async update(key: Identifier, update: (r: TRecord) => TRecord) {
-		if (!key)
-			throw new TypeError('key argument required');
-		if (typeof update !== 'function')
-			throw new TypeError('update argument must be a Function');
-
-		if (!this._map.has(key))
-			throw new Error(`Key '${key}' does not exist`);
-
-		return this._update(key, update);
-	}
-
-	/** Update existing view record or create new */
-	async updateEnforcingNew(key: Identifier, update: (r?: TRecord) => TRecord) {
-		if (!key)
-			throw new TypeError('key argument required');
-		if (typeof update !== 'function')
-			throw new TypeError('update argument must be a Function');
-
-		if (!this._map.has(key))
-			return this.create(key, applyUpdate(undefined, update));
-
-		return this._update(key, update);
-	}
-
-	/** Update all records that match filter criteria */
-	async updateAll(filter: (r: TRecord) => boolean, update: (r: TRecord) => TRecord) {
-		if (filter && typeof filter !== 'function')
-			throw new TypeError('filter argument, when specified, must be a Function');
-		if (typeof update !== 'function')
-			throw new TypeError('update argument must be a Function');
-
-		for (const [key, value] of this._map) {
-			if (!filter || filter(value))
-				await this._update(key, update);
-		}
-	}
-
-	/** Update existing record */
-	private async _update(key: Identifier, update: (r: TRecord) => TRecord) {
-		const value = this._map.get(key);
-		if (!value)
-			throw new Error(`Key '${key}' does not exist`);
-
-		const updatedValue = applyUpdate(value, update);
-		if (updatedValue === undefined)
-			return;
-
-		this._map.set(key, updatedValue);
-	}
-
-	/** Delete record */
-	async delete(key: Identifier) {
-		if (!key)
-			throw new TypeError('key argument required');
-
-		this._map.delete(key);
-	}
-
-	/** Delete all records that match filter criteria */
-	async deleteAll(filter: (r?: TRecord) => boolean) {
-		if (filter && typeof filter !== 'function')
-			throw new TypeError('filter argument, when specified, must be a Function');
-
-		for (const [key, value] of this._map) {
-			if (!filter || filter(value))
-				await this.delete(key);
-		}
-	}
-
-	/** Get view summary as string */
-	toString(): string {
-		return `${this.size} record${this.size !== 1 ? 's' : ''}`;
-	}
-}

package/src/in-memory/index.ts

@@ -1,5 +0,0 @@
-export * from './InMemoryEventStorage';
-export * from './InMemoryLock';
-export * from './InMemoryMessageBus';
-export * from './InMemorySnapshotStorage';
-export * from './InMemoryView';

package/src/in-memory/utils/index.ts

@@ -1 +0,0 @@
-export * from './nextCycle';

package/src/in-memory/utils/nextCycle.ts

@@ -1,4 +0,0 @@
-/**
- * @returns Promise that resolves on next event loop cycle
- */
-export const nextCycle = (): Promise<void> => new Promise(rs => setImmediate(rs));

package/src/index.ts

@@ -1,22 +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 './EventDispatcher';
-export * from './EventValidationProcessor';
-
-export * from './in-memory';
-
-export * as Event from './Event';
-export {
-	getMessageHandlerNames,
-	subscribe
-} from './utils';
-
-export * from './interfaces';

package/src/interfaces/IAggregate.ts

@@ -1,58 +0,0 @@
-import { ICommand } from './ICommand';
-import { Identifier } from './Identifier';
-import { IEvent } from './IEvent';
-import { IEventSet } from './IEventSet';
-
-/**
- * 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;
-

package/src/interfaces/IAggregateSnapshotStorage.ts

@@ -1,11 +0,0 @@
-import { Identifier } from './Identifier';
-import { IEvent } from './IEvent';
-
-export interface IAggregateSnapshotStorage {
-	getAggregateSnapshot<TState>(aggregateId: Identifier):
-		Promise<IEvent<TState> | undefined> | IEvent<TState> | undefined;
-
-	saveAggregateSnapshot<TState>(snapshotEvent: IEvent<TState>): Promise<void> | void;
-
-	deleteAggregateSnapshot<TState>(snapshotEvent: IEvent<TState>): Promise<void> | void;
-}

package/src/interfaces/ICommand.ts

@@ -1,3 +0,0 @@
-import { IMessage } from './IMessage';
-
-export type ICommand<TPayload = any> = IMessage<TPayload>;

package/src/interfaces/ICommandBus.ts

@@ -1,16 +0,0 @@
-import { ICommand } from './ICommand';
-import { IEventSet } from './IEventSet';
-import { IObservable } from './IObservable';
-import { IObserver } from './IObserver';
-
-export interface ICommandBus extends IObservable {
-	send(commandType: string, aggregateId: string | undefined, options: { payload?: object, context?: object }):
-		Promise<IEventSet>;
-
-	sendRaw(command: ICommand):
-		Promise<IEventSet>;
-}
-
-export interface ICommandHandler extends IObserver {
-	subscribe(commandBus: ICommandBus): void;
-}

package/src/interfaces/IContainer.ts

@@ -1,27 +0,0 @@
-import { Container } from 'di0';
-import { ICommandBus } from './ICommandBus';
-import { IEventDispatcher } from './IEventDispatcher';
-import { IEventStore } from './IEventStore';
-import { IEventBus } from './IEventBus';
-import { IDispatchPipelineProcessor } from './IDispatchPipelineProcessor';
-import { IEventStorageReader, IEventStorageWriter } from './IEventStorage';
-import { IAggregateSnapshotStorage } from './IAggregateSnapshotStorage';
-import { IIdentifierProvider } from './IIdentifierProvider';
-import { IExtendableLogger, ILogger } from './ILogger';
-
-export interface IContainer extends Container {
-	eventBus: IEventBus;
-	eventStore: IEventStore
-	eventStorageReader: IEventStorageReader;
-	eventStorageWriter?: IEventStorageWriter;
-	identifierProvider?: IIdentifierProvider;
-	snapshotStorage?: IAggregateSnapshotStorage;
-
-	commandBus: ICommandBus;
-	eventDispatcher: IEventDispatcher;
-	eventDispatchPipeline?: IDispatchPipelineProcessor[];
-
-	logger?: ILogger | IExtendableLogger;
-
-	process?: NodeJS.Process
-}

package/src/interfaces/IDispatchPipelineProcessor.ts

@@ -1,35 +0,0 @@
-import { IEvent } from './IEvent';
-import { isObject } from './isObject';
-
-/**
- * Represents a wrapper for an event that can optionally contain additional metadata.
- * Used to extend event processing with context-specific data required by processors.
- */
-export type DispatchPipelineEnvelope = {
-
-	/**
-	 * Origin of the event. Can be used to distinguish between events coming from different sources.
-	 */
-	origin?: 'external' | 'internal';
-
-	event?: IEvent;
-}
-
-/**
- * A batch of event envelopes. Can contain custom envelope types extending EventEnvelope.
- */
-export type DispatchPipelineBatch<T extends DispatchPipelineEnvelope = DispatchPipelineEnvelope> = Readonly<Array<T>>;
-
-/**
- * Defines a processor that operates on a batch of event envelopes.
- * Allows transformations, side-effects, or filtering of events during dispatch.
- */
-export interface IDispatchPipelineProcessor<T extends DispatchPipelineEnvelope = {}> {
-	process(batch: DispatchPipelineBatch<T>): Promise<DispatchPipelineBatch<T>>;
-	revert?(batch: DispatchPipelineBatch<T>): Promise<void>;
-}
-
-export const isDispatchPipelineProcessor = (obj: unknown): obj is IDispatchPipelineProcessor =>
-	isObject(obj)
-	&& 'process' in obj
-	&& typeof (obj as IDispatchPipelineProcessor).process === 'function';

package/src/interfaces/IEvent.ts

@@ -1,13 +0,0 @@
-import { IMessage } from './IMessage';
-import { isObject } from './isObject';
-
-export type IEvent<TPayload = any> = IMessage<TPayload> & {
-
-	/** Unique event identifier */
-	id?: string;
-};
-
-export const isEvent = (event: unknown): event is IEvent =>
-	isObject(event)
-	&& 'type' in event
-	&& typeof event.type === 'string';

package/src/interfaces/IEventBus.ts

@@ -1,11 +0,0 @@
-import { IEvent } from './IEvent';
-import { IObservable, isIObservable } from './IObservable';
-
-export interface IEventBus extends IObservable {
-	publish(event: IEvent, meta?: Record<string, any>): Promise<any>;
-}
-
-export const isIEventBus = (obj: unknown) =>
-	isIObservable(obj)
-	&& 'publish' in obj
-	&& typeof obj.publish === 'function';

package/src/interfaces/IEventDispatcher.ts

@@ -1,7 +0,0 @@
-import { IEventSet } from './IEventSet';
-import { IEventBus } from './IEventBus';
-
-export interface IEventDispatcher {
-	readonly eventBus: IEventBus;
-	dispatch(events: IEventSet, meta?: Record<string, any>): Promise<IEventSet>;
-}

package/src/interfaces/IEventLocker.ts

@@ -1,34 +0,0 @@
-import { IEvent } from './IEvent';
-import { isObject } from './isObject';
-
-/**
- * Interface for tracking event processing state to prevent concurrent processing
- * by multiple processes.
- */
-export interface IEventLocker {
-
-	/**
-	 * Retrieves the last projected event,
-	 * allowing the projection state to be restored from subsequent events.
-	 */
-	getLastEvent(): Promise<IEvent | undefined> | IEvent | undefined;
-
-	/**
-	 * Marks an event as projecting to prevent it from being processed
-	 * by another projection instance using the same storage.
-	 *
-	 * @returns `false` if the event is already being processed or has been processed.
-	 */
-	tryMarkAsProjecting(event: IEvent): Promise<boolean> | boolean;
-
-	/**
-	 * Marks an event as projected.
-	 */
-	markAsProjected(event: IEvent): Promise<void> | void;
-}
-
-export const isEventLocker = (view: unknown): view is IEventLocker =>
-	isObject(view)
-	&& 'getLastEvent' in view
-	&& 'tryMarkAsProjecting' in view
-	&& 'markAsProjected' in view;

package/src/interfaces/IEventReceptor.ts

@@ -1,6 +0,0 @@
-import { IEventStore } from './IEventStore';
-import { IObserver } from './IObserver';
-
-export interface IEventReceptor extends IObserver {
-	subscribe(eventStore: IEventStore): void;
-}

package/src/interfaces/IEventSet.ts

@@ -1,7 +0,0 @@
-import { IEvent, isEvent } from './IEvent';
-
-export type IEventSet = ReadonlyArray<Readonly<IEvent>>;
-
-export const isEventSet = (arr: unknown): arr is IEventSet =>
-	Array.isArray(arr)
-	&& arr.every(isEvent);

package/src/interfaces/IEventStorage.ts

@@ -1,53 +0,0 @@
-import { Identifier } from './Identifier';
-import { IEvent } from './IEvent';
-import { IEventSet } from './IEventSet';
-import { IEventStream } from './IEventStream';
-import { isObject } from './isObject';
-
-export type EventQueryAfter = {
-
-	/** Get events emitted after this specific event */
-	afterEvent?: IEvent;
-}
-
-export type EventQueryBefore = {
-
-	/** Get events emitted before this specific event */
-	beforeEvent?: IEvent;
-}
-
-export interface IEventStorageReader {
-
-	/**
-	 * Retrieves events of specified types that were emitted after a given event.
-	 */
-	getEventsByTypes(eventTypes: Readonly<string[]>, options?: EventQueryAfter): IEventStream;
-
-	/**
-	 * Retrieves all events (and optionally a snapshot) associated with a specific aggregate.
-	 */
-	getAggregateEvents(aggregateId: Identifier, options?: { snapshot?: IEvent }): IEventStream;
-
-	/**
-	 * Retrieves events associated with a saga, with optional filtering by version or timestamp.
-	 */
-	getSagaEvents(sagaId: Identifier, options: EventQueryBefore): IEventStream;
-}
-
-export interface IEventStorageWriter {
-
-	/**
-	 * Persists a set of events to the event store.
-	 * Returns the persisted event set (potentially enriched or normalized).
-	 */
-	commitEvents(events: IEventSet): Promise<IEventSet>;
-}
-
-export const isIEventStorageReader = (storage: unknown): storage is IEventStorageReader =>
-	isObject(storage)
-	&& 'getEventsByTypes' in storage
-	&& typeof storage.getEventsByTypes === 'function'
-	&& 'getAggregateEvents' in storage
-	&& typeof storage.getAggregateEvents === 'function'
-	&& 'getSagaEvents' in storage
-	&& typeof storage.getSagaEvents === 'function';

package/src/interfaces/IEventStore.ts

@@ -1,13 +0,0 @@
-import { IEventDispatcher } from './IEventDispatcher';
-import { IEvent } from './IEvent';
-import { IEventStorageReader } from './IEventStorage';
-import { IIdentifierProvider } from './IIdentifierProvider';
-import { IMessageHandler, IObservable } from './IObservable';
-
-export interface IEventStore
-	extends IObservable, IEventDispatcher, IEventStorageReader, IIdentifierProvider {
-
-	registerSagaStarters(startsWith: string[] | undefined): void;
-
-	once(messageTypes: string | string[], handler?: IMessageHandler, filter?: (e: IEvent) => boolean): Promise<IEvent>;
-}

package/src/interfaces/IEventStream.ts

@@ -1,3 +0,0 @@
-import { IEvent } from './IEvent';
-
-export type IEventStream = AsyncIterableIterator<Readonly<IEvent>>;

package/src/interfaces/IIdentifierProvider.ts

@@ -1,17 +0,0 @@
-import { Identifier } from './Identifier';
-import { isObject } from './isObject';
-
-export interface IIdentifierProvider {
-
-	/**
-	 * Generates and returns a new unique identifier suitable for aggregates, sagas, and events.
-	 *
-	 * @returns A promise resolving to an identifier or an identifier itself.
-	 */
-	getNewId(): Identifier | Promise<Identifier>;
-}
-
-export const isIdentifierProvider = (obj: any): obj is IIdentifierProvider =>
-	isObject(obj)
-	&& 'getNewId' in obj
-	&& typeof obj.getNewId === 'function';

package/src/interfaces/ILogger.ts

@@ -1,11 +0,0 @@
-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/interfaces/IMessage.ts

@@ -1,22 +0,0 @@
-import { Identifier } from './Identifier';
-import { isObject } from './isObject';
-
-export interface IMessage<TPayload = any> {
-
-	/** Event or command type */
-	type: string;
-
-	aggregateId?: Identifier;
-	aggregateVersion?: number;
-
-	sagaId?: Identifier;
-	sagaVersion?: number;
-
-	payload?: TPayload;
-	context?: any;
-}
-
-export const isMessage = (obj: unknown): obj is IMessage =>
-	isObject(obj)
-	&& 'type' in obj
-	&& typeof obj.type === 'string';

package/src/interfaces/IMessageBus.ts

@@ -1,8 +0,0 @@
-import { ICommand } from './ICommand';
-import { IEvent } from './IEvent';
-import { IObservable } from './IObservable';
-
-export interface IMessageBus extends IObservable {
-	send(command: ICommand): Promise<any>;
-	publish(event: IEvent, meta?: Record<string, any>): Promise<any>;
-}

package/src/interfaces/IObjectStorage.ts

@@ -1,13 +0,0 @@
-import { Identifier } from './Identifier';
-
-export interface IObjectStorage<TRecord> {
-	get(id: Identifier): Promise<TRecord | undefined> | TRecord | undefined;
-
-	create(id: Identifier, r: TRecord): Promise<any> | any;
-
-	update(id: Identifier, cb: (r: TRecord) => TRecord): Promise<any> | any;
-
-	updateEnforcingNew(id: Identifier, cb: (r?: TRecord) => TRecord): Promise<any> | any;
-
-	delete(id: Identifier): Promise<any> | any;
-}

package/src/interfaces/IObservable.ts

@@ -1,31 +0,0 @@
-import { IMessage } from './IMessage';
-import { isObject } from './isObject';
-
-export interface IMessageHandler {
-	(message: IMessage, meta?: Record<string, any>): any | Promise<any>
-}
-
-export interface IObservable {
-
-	/**
-	 * Setup a listener for a specific event type
-	 */
-	on(type: string, handler: IMessageHandler): void;
-
-	/**
-	 * Remove previously installed listener
-	 */
-	off(type: string, handler: IMessageHandler): void;
-
-	/**
-	 * Get or create a named queue, which delivers events to a single handler only
-	 */
-	queue?(name: string): IObservable;
-}
-
-export const isIObservable = (obj: unknown): obj is IObservable =>
-	isObject(obj)
-	&& 'on' in obj
-	&& typeof obj.on === 'function'
-	&& 'off' in obj
-	&& typeof obj.off === 'function';