node-cqrs 1.0.0-rc.8 → 1.0.0

package/dist/esm/AbstractAggregate.js

@@ -0,0 +1,189 @@
+import { AggregateCommandHandler } from "./AggregateCommandHandler.js";
+import { SNAPSHOT_EVENT_TYPE } from "./interfaces/index.js";
+import { getClassName, validateHandlers, getHandler, getMessageHandlerNames, clone, assertDefined, assertString, assertMessage, assertSnapshotEvent, assertNumber, assertObject, assertOptionalArray } from "./utils/index.js";
+/**
+ * Base class for Aggregate definition
+ */
+export class AbstractAggregate {
+    /**
+     * 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() {
+        return getMessageHandlerNames(this);
+    }
+    /**
+     * Optional list of event types that are required to restore the aggregate state.
+     *
+     * @see IAggregateConstructor
+     */
+    static get restoresFrom() {
+        return undefined;
+    }
+    /**
+     * Defines retry behavior when a ConcurrencyError is thrown during event dispatch.
+     *
+     * @see IAggregateConstructor
+     */
+    static get retryOnConcurrencyError() {
+        return undefined;
+    }
+    /**
+     * Convenience helper to create an `AggregateCommandHandler` for this aggregate type and
+     * subscribe it to the provided `commandBus`.
+     */
+    static register(eventStore, commandBus) {
+        const handler = new AggregateCommandHandler({ aggregateType: this, eventStore });
+        handler.subscribe(commandBus);
+        return handler;
+    }
+    #id;
+    #version = 0;
+    #snapshotVersion;
+    /** List of emitted events */
+    changes = [];
+    /** Internal aggregate state */
+    state;
+    /** Command being handled by aggregate */
+    command;
+    /** Unique aggregate instance identifier */
+    get id() {
+        return this.#id;
+    }
+    /** Aggregate instance version */
+    get version() {
+        return this.#version;
+    }
+    /** Restored snapshot version */
+    get snapshotVersion() {
+        return this.#snapshotVersion;
+    }
+    /**
+     * Override to define whether an aggregate state snapshot should be taken
+     *
+     * @example
+     *   // create snapshot every 50 events if new events were emitted
+     *   return !!this.changes.length
+     *     && this.version - (this.snapshotVersion ?? 0) > 50;
+     */
+    // eslint-disable-next-line class-methods-use-this
+    get shouldTakeSnapshot() {
+        return false;
+    }
+    constructor(options) {
+        const { id, state, events } = options;
+        assertDefined(id, 'id');
+        if (state)
+            assertObject(state, 'state');
+        if (events)
+            assertOptionalArray(events, 'events');
+        this.#id = id;
+        validateHandlers(this);
+        if (state)
+            this.state = state;
+        if (events)
+            events.forEach(event => this.mutate(event));
+    }
+    /** Mutate aggregate state and increment aggregate version */
+    mutate(event) {
+        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;
+    }
+    /** Pass command to command handler */
+    async handle(command) {
+        assertMessage(command, 'command');
+        const handler = getHandler(this, command.type);
+        if (!handler)
+            throw new Error(`'${command.type}' handler is not defined or not a function`);
+        if (this.command)
+            throw new Error('Another command is being processed');
+        this.command = command;
+        const eventsOffset = this.changes.length;
+        try {
+            await handler.call(this, command.payload, command.context);
+            return this.getUncommittedEvents(eventsOffset);
+        }
+        finally {
+            this.command = undefined;
+        }
+    }
+    /**
+     * Get the events emitted during commands processing.
+     * If a snapshot should be taken, the snapshot event is added to the end.
+     */
+    getUncommittedEvents(offset) {
+        if (this.shouldTakeSnapshot)
+            this.takeSnapshot();
+        return this.changes.slice(offset);
+    }
+    emit(type, payload) {
+        assertString(type, 'type');
+        const event = this.makeEvent(type, payload, this.command);
+        this.emitRaw(event);
+        return event;
+    }
+    /** Format event based on a current aggregate state and a command being executed */
+    makeEvent(type, payload, sourceCommand) {
+        const event = {
+            aggregateId: this.id,
+            aggregateVersion: this.version,
+            type,
+            payload
+        };
+        if (sourceCommand) {
+            // augment event with command context
+            const { context, sagaOrigins } = sourceCommand;
+            if (context !== undefined)
+                event.context = context;
+            if (sagaOrigins !== undefined)
+                event.sagaOrigins = { ...sagaOrigins };
+        }
+        return event;
+    }
+    /** Register aggregate event and mutate aggregate state */
+    emitRaw(event) {
+        assertDefined(event?.aggregateId, 'event.aggregateId');
+        assertNumber(event?.aggregateVersion, 'event.aggregateVersion');
+        this.mutate(event);
+        this.changes.push(event);
+    }
+    /** Create an aggregate state snapshot */
+    makeSnapshot() {
+        if (!this.state)
+            throw new Error('state property is empty, either define state or override makeSnapshot method');
+        return clone(this.state);
+    }
+    /** Add snapshot event to the collection of emitted events */
+    takeSnapshot() {
+        const snapshotEvent = this.emit(SNAPSHOT_EVENT_TYPE, this.makeSnapshot());
+        this.#snapshotVersion = snapshotEvent.aggregateVersion;
+    }
+    /** Restore aggregate state from a snapshot */
+    restoreSnapshot(snapshotEvent) {
+        assertSnapshotEvent(snapshotEvent, 'snapshotEvent');
+        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() {
+        return `${getClassName(this)} ${this.id} (v${this.version})`;
+    }
+}
+//# sourceMappingURL=AbstractAggregate.js.map

package/dist/esm/AbstractAggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractAggregate.js","sourceRoot":"","sources":["../../src/AbstractAggregate.ts"],"names":[],"mappings":"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"}

package/dist/esm/AbstractProjection.js

@@ -0,0 +1,161 @@
+import { describe } from "./Event.js";
+import { InMemoryView } from "./in-memory/InMemoryView.js";
+import { isViewLocker, isEventLocker } from "./interfaces/index.js";
+import { getClassName, validateHandlers, getHandler, subscribe, getMessageHandlerNames, assertFunction } from "./utils/index.js";
+/**
+ * Base class for Projection definition
+ */
+export class AbstractProjection {
+    /**
+     * 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() {
+        return getMessageHandlerNames(this);
+    }
+    #view;
+    #viewLocker;
+    #eventLocker;
+    _logger;
+    /**
+     * The default view associated with the projection.
+     * Can optionally implement IViewLocker and/or IEventLocker.
+     */
+    get view() {
+        return this.#view ?? (this.#view = new InMemoryView());
+    }
+    set view(value) {
+        this.#view = value;
+    }
+    /**
+     * Manages view restoration state to prevent early access to an inconsistent view
+     * or conflicts from concurrent restoration by other processes.
+     */
+    get _viewLocker() {
+        if (this.#viewLocker === undefined)
+            this.#viewLocker = isViewLocker(this.view) ? this.view : null;
+        return this.#viewLocker;
+    }
+    set _viewLocker(value) {
+        this.#viewLocker = value;
+    }
+    /**
+     * Tracks event processing state to prevent concurrent handling by multiple processes.
+     */
+    get _eventLocker() {
+        if (this.#eventLocker === undefined)
+            this.#eventLocker = isEventLocker(this.view) ? this.view : null;
+        return this.#eventLocker;
+    }
+    set _eventLocker(value) {
+        this.#eventLocker = value;
+    }
+    constructor({ view, viewLocker, eventLocker, logger } = {}) {
+        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
+     * and restore view state from not yet projected events
+     */
+    subscribe(eventStore) {
+        subscribe(eventStore, this, {
+            masterHandler: this.project
+        });
+    }
+    /** Pass event to projection event handler */
+    async project(event, meta) {
+        if (this._viewLocker && !this._viewLocker.ready) {
+            this._logger?.debug(`view is locked, awaiting until it is ready to process ${describe(event)}`);
+            await this._viewLocker.once('ready');
+            this._logger?.debug(`view is ready, processing ${describe(event)}`);
+        }
+        return this._project(event, meta);
+    }
+    /**
+     * Determines whether an event should be recorded as the last projected event (restore checkpoint).
+     * Override in derived classes to control checkpoint behavior based on event metadata.
+     */
+    // eslint-disable-next-line class-methods-use-this
+    shouldRecordLastEvent(_event, _meta) {
+        return true;
+    }
+    /** Pass event to projection event handler, without awaiting for restore operation to complete */
+    async _project(event, meta) {
+        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);
+            if (this.shouldRecordLastEvent(event, meta))
+                await this._eventLocker.markAsLastEvent(event);
+        }
+    }
+    /**
+     * Restore view state from not-yet-projected events.
+     *
+     * Lock the view to ensure same restoring procedure
+     * won't be performed by another projection instance.
+     * */
+    async restore(eventStore) {
+        if (this._viewLocker)
+            await this._viewLocker.lock();
+        await this._restore(eventStore);
+        if (this._viewLocker)
+            this._viewLocker.unlock();
+    }
+    /** Restore view state from not-yet-projected events */
+    async _restore(eventStore) {
+        assertFunction(eventStore?.getEventsByTypes, 'eventStore.getEventsByTypes');
+        let lastEvent;
+        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.handles;
+        const eventsIterable = eventStore.getEventsByTypes(messageTypes, { afterEvent: lastEvent });
+        let eventsCount = 0;
+        let lastRestoredEvent;
+        const startTs = Date.now();
+        for await (const event of eventsIterable) {
+            try {
+                await this._project(event);
+                lastRestoredEvent = event;
+                eventsCount += 1;
+            }
+            catch (err) {
+                this._onRestoringError(err, event);
+            }
+        }
+        if (this._eventLocker && lastRestoredEvent)
+            await this._eventLocker.markAsLastEvent(lastRestoredEvent);
+        this._logger?.info(`view restored from ${eventsCount} event(s) in ${Date.now() - startTs} ms`);
+    }
+    /**
+     * Handle error on restoring.
+     *
+     * Logs and throws error by default
+     */
+    _onRestoringError(error, event) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this._logger?.error(`view restoring has failed (view remains locked): ${errorMessage}`, {
+            service: getClassName(this),
+            event,
+            error
+        });
+        throw error;
+    }
+}
+//# sourceMappingURL=AbstractProjection.js.map

package/dist/esm/AbstractProjection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractProjection.js","sourceRoot":"","sources":["../../src/AbstractProjection.ts"],"names":[],"mappings":"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"}

package/dist/esm/AbstractSaga.js

@@ -0,0 +1,105 @@
+import { SagaEventHandler } from "./SagaEventHandler.js";
+import { validateHandlers, getHandler, getClassName, getMessageHandlerNames, assertDefined, assertString, assertMessage, assertEvent, assertFunction } from "./utils/index.js";
+/**
+ * Base class for Saga definition
+ */
+export class AbstractSaga {
+    /**
+     * Optional list of events that start new saga.
+     *
+     * When not defined, saga start is inferred by the absence of `message.sagaOrigins[sagaDescriptor]`.
+     */
+    static get startsWith() {
+        return undefined;
+    }
+    /** List of event types being handled by Saga, can be overridden in Saga implementation */
+    static get handles() {
+        return getMessageHandlerNames(this);
+    }
+    /**
+     * Convenience helper to create a `SagaEventHandler` for this saga type and subscribe it to
+     * the provided `eventStore`.
+     */
+    static register(eventStore, commandBus) {
+        const handler = new SagaEventHandler({
+            sagaType: this,
+            eventStore,
+            commandBus
+        });
+        handler.subscribe(eventStore);
+        return handler;
+    }
+    /** Saga ID */
+    get id() {
+        return this.#id;
+    }
+    /** Saga version */
+    get version() {
+        return this.#version;
+    }
+    state;
+    #id;
+    #version = 0;
+    #messages = [];
+    #handling = false;
+    /**
+     * Creates an instance of AbstractSaga
+     */
+    constructor(options) {
+        assertDefined(options, 'options');
+        assertDefined(options.id, 'options.id');
+        if (options.events)
+            throw new TypeError('options.events argument is deprecated');
+        this.#id = options.id;
+        validateHandlers(this, 'startsWith');
+        validateHandlers(this, 'handles');
+    }
+    /** Modify saga state by applying an event */
+    mutate(event) {
+        assertEvent(event, 'event');
+        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;
+    }
+    /** Process saga event and return produced commands */
+    async handle(event) {
+        assertEvent(event, 'event');
+        if (this.#handling)
+            throw new Error('Another event is being processed, concurrent handling is not allowed');
+        const handler = getHandler(this, event.type);
+        assertFunction(handler, `${event.type} handler`);
+        this.#handling = true;
+        this.#messages.length = 0;
+        try {
+            await handler.call(this, event);
+            this.mutate(event);
+            return this.#messages.splice(0);
+        }
+        finally {
+            this.#handling = false;
+        }
+    }
+    enqueue(commandType, aggregateId, payload) {
+        assertString(commandType, 'commandType');
+        this.enqueueRaw({
+            aggregateId,
+            type: commandType,
+            payload
+        });
+    }
+    /** Put a command to the execution queue */
+    enqueueRaw(command) {
+        assertMessage(command, 'command');
+        this.#messages.push(command);
+    }
+    /** Get human-readable Saga name */
+    toString() {
+        return `${getClassName(this)} ${this.id} (v${this.version})`;
+    }
+}
+//# sourceMappingURL=AbstractSaga.js.map

package/dist/esm/AbstractSaga.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractSaga.js","sourceRoot":"","sources":["../../src/AbstractSaga.ts"],"names":[],"mappings":"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"}

package/dist/esm/AggregateCommandHandler.js

@@ -0,0 +1,178 @@
+import { assertBoolean, assertDefined, assertMessage, assertNonNegativeInteger, assertObservable, assertStringArray, Lock, MapAssertable } from "./utils/index.js";
+import { ConcurrencyError } from "./errors/index.js";
+import { isObject } from "./interfaces/isObject.js";
+const DEFAULT_MAX_RETRY_ATTEMPTS = 5;
+function normalizeRetryResolver(value) {
+    if (typeof value === 'function')
+        return value;
+    if (value === false)
+        return () => false;
+    if (value === 'ignore')
+        return err => (err instanceof ConcurrencyError ? 'ignore' : false);
+    if (typeof value === 'number')
+        return (err, events, attempt) => err instanceof ConcurrencyError && attempt < value;
+    if (isObject(value)) {
+        const { maxRetries = DEFAULT_MAX_RETRY_ATTEMPTS, ignoreAfterMaxRetries = false } = value;
+        assertNonNegativeInteger(maxRetries, 'retryOnConcurrencyError.maxRetries');
+        assertBoolean(ignoreAfterMaxRetries, 'retryOnConcurrencyError.ignoreAfterMaxRetries');
+        return (err, events, attempt) => {
+            if (!(err instanceof ConcurrencyError))
+                return false;
+            if (attempt < maxRetries)
+                return true;
+            return ignoreAfterMaxRetries ? 'ignore' : false;
+        };
+    }
+    // undefined or true — default behavior
+    return (err, events, attempt) => err instanceof ConcurrencyError && attempt < DEFAULT_MAX_RETRY_ATTEMPTS;
+}
+/**
+ * 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 {
+    #eventStore;
+    #logger;
+    #aggregateFactory;
+    #handles;
+    #restoresFrom;
+    #shouldRetry;
+    /** Aggregate instances cache for concurrent command handling */
+    #aggregatesCache = new MapAssertable();
+    /** Lock for sequential aggregate command execution */
+    #executionLock;
+    constructor({ eventStore, aggregateType, aggregateFactory, handles, executionLocker = new Lock(), restoresFrom, retryOnConcurrencyError, logger }) {
+        assertDefined(eventStore, 'eventStore');
+        this.#eventStore = eventStore;
+        this.#executionLock = executionLocker;
+        this.#logger = logger && 'child' in logger ?
+            logger.child({ service: new.target.name }) :
+            logger;
+        if (aggregateType) {
+            const AggregateType = aggregateType;
+            this.#aggregateFactory = params => new AggregateType(params);
+            this.#handles = AggregateType.handles;
+            this.#restoresFrom = AggregateType.restoresFrom;
+            this.#shouldRetry = normalizeRetryResolver(retryOnConcurrencyError ??
+                AggregateType.retryOnConcurrencyError);
+        }
+        else if (aggregateFactory) {
+            assertStringArray(handles, 'handles');
+            this.#aggregateFactory = aggregateFactory;
+            this.#handles = handles;
+            this.#restoresFrom = restoresFrom;
+            this.#shouldRetry = normalizeRetryResolver(retryOnConcurrencyError);
+        }
+        else {
+            throw new TypeError('either aggregateType or aggregateFactory is required');
+        }
+    }
+    /** Subscribe to all command types handled by aggregateType */
+    subscribe(commandBus) {
+        assertObservable(commandBus, 'commandBus');
+        for (const commandType of this.#handles)
+            commandBus.on(commandType, (cmd) => this.execute(cmd));
+    }
+    /** Restore aggregate from event store events */
+    async #restoreAggregate(id) {
+        assertDefined(id, 'id');
+        const aggregate = this.#aggregateFactory({ id });
+        const queryOptions = this.#restoresFrom?.length ?
+            { eventTypes: this.#restoresFrom, tail: 'last' } :
+            undefined;
+        const eventsIterable = this.#eventStore.getAggregateEvents(id, queryOptions);
+        let eventCount = 0;
+        for await (const event of eventsIterable) {
+            aggregate.mutate(event);
+            eventCount += 1;
+        }
+        this.#logger?.info(`${aggregate} state restored from ${eventCount} event(s)`);
+        return aggregate;
+    }
+    /** Create new aggregate with new Id generated by event store */
+    async #createAggregate() {
+        const id = await this.#eventStore.getNewId();
+        const aggregate = this.#aggregateFactory({ id });
+        this.#logger?.info(`${aggregate} created`);
+        return aggregate;
+    }
+    /**
+     * Register interest in the cache entry before acquiring the lock, so concurrent callers for the same aggregateId
+     * share one restoration promise instead of each triggering a separate event-store read
+     */
+    #allocateCacheEntry(aggregateId) {
+        if (aggregateId)
+            this.#aggregatesCache.assert(aggregateId, () => this.#restoreAggregate(aggregateId));
+    }
+    /**
+     * Replace the dirty cache entry with a fresh restoration promise
+     * so both the retry and any commands queued on the lock start from a clean state.
+     */
+    #resetCacheEntry(aggregateId) {
+        if (aggregateId)
+            this.#aggregatesCache.set(aggregateId, this.#restoreAggregate(aggregateId));
+    }
+    /**
+     * Decrement the usage counter registered above;
+     * deletes the entry when the last concurrent caller for this aggregateId is done.
+     */
+    #releaseCacheEntry(aggregateId) {
+        if (aggregateId)
+            this.#aggregatesCache.release(aggregateId);
+    }
+    /** Pass a command to corresponding aggregate */
+    async execute(cmd) {
+        assertMessage(cmd, 'cmd');
+        const { aggregateId } = cmd;
+        this.#allocateCacheEntry(aggregateId);
+        // Serialize execution per aggregate — commands for the same id queue here.
+        const lease = aggregateId ?
+            await this.#executionLock.acquire(String(aggregateId)) :
+            undefined;
+        try {
+            for (let attempt = 0;; attempt++) {
+                // Read the current cache entry after acquiring the lock. On the first attempt
+                // this is the pre-warmed (possibly shared) instance; on retries it is the
+                // fresh instance placed into the cache by the error handler below.
+                const aggregate = aggregateId ?
+                    await this.#aggregatesCache.get(aggregateId) :
+                    await this.#createAggregate();
+                let events;
+                try {
+                    events = await aggregate.handle(cmd);
+                    this.#logger?.info(`${aggregate} "${cmd.type}" command processed, ${events.length} event(s) produced`);
+                }
+                catch (error) {
+                    this.#resetCacheEntry(aggregateId);
+                    throw error;
+                }
+                try {
+                    if (events.length)
+                        await this.#eventStore.dispatch(events);
+                    return events;
+                }
+                catch (error) {
+                    this.#resetCacheEntry(aggregateId);
+                    const retryDecision = this.#shouldRetry(error, events, attempt);
+                    if (!retryDecision)
+                        throw error;
+                    if (retryDecision === 'ignore') {
+                        this.#logger?.warn(`"${cmd.type}" command error ignored after ${attempt + 1} attempt(s), force-dispatching`, { error });
+                        if (events.length)
+                            await this.#eventStore.dispatch(events, { ignoreConcurrencyError: true });
+                        return events;
+                    }
+                    this.#logger?.warn(`"${cmd.type}" command failed on attempt ${attempt + 1}, will retry`, { error });
+                }
+            }
+        }
+        finally {
+            lease?.release();
+            this.#releaseCacheEntry(aggregateId);
+        }
+    }
+}
+//# sourceMappingURL=AggregateCommandHandler.js.map

package/dist/esm/AggregateCommandHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AggregateCommandHandler.js","sourceRoot":"","sources":["../../src/AggregateCommandHandler.ts"],"names":[],"mappings":"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"}