@nimbus-cqrs/core 2.0.0-beta.0

package/esm/lib/eventBus/eventBus.d.ts

@@ -0,0 +1,329 @@
+import type { Event } from '../message/event.js';
+/**
+ * The type for the NimbusEventBus options.
+ */
+export type NimbusEventBusOptions = {
+    /**
+     * The name of the event bus instance for metrics and traces.
+     * Defaults to 'default'.
+     */
+    name?: string;
+    /**
+     * The maximum number of retries for handling the event in case of an error.
+     * Defaults to 2.
+     */
+    maxRetries?: number;
+    /**
+     * The base delay for exponential backoff in milliseconds.
+     * Defaults to 1000ms.
+     */
+    baseDelay?: number;
+    /**
+     * The maximum delay cap for exponential backoff in milliseconds.
+     * Defaults to 30000ms (30 seconds).
+     */
+    maxDelay?: number;
+    /**
+     * Whether to add jitter to the retry delay to prevent thundering herd issues.
+     * Defaults to true.
+     */
+    useJitter?: boolean;
+    /**
+     * Optional callback invoked when an event is published.
+     * Useful for custom logging or debugging.
+     */
+    logPublish?: (event: Event) => void;
+};
+/**
+ * The input type for subscribing to an event.
+ */
+export type SubscribeEventInput<TEvent extends Event> = {
+    /**
+     * The CloudEvents event type to subscribe to (e.g., 'at.overlap.nimbus.order-created').
+     */
+    type: string;
+    /**
+     * The async handler function that processes received events.
+     */
+    handler: (event: TEvent) => Promise<void>;
+    /**
+     * Optional error callback invoked when event handling fails after all retries.
+     * If not provided, errors are logged using the default logger.
+     */
+    onError?: (error: Error, event: TEvent) => void;
+    /**
+     * Optional retry options that override the EventBus defaults for this subscription.
+     */
+    options?: Omit<NimbusEventBusOptions, 'name'>;
+};
+/**
+ * The NimbusEventBus is used to publish and subscribe to events within the application.
+ *
+ * Events are delivered asynchronously to all registered handlers. If a handler fails,
+ * it will be retried using exponential backoff until it succeeds or the maximum retry
+ * count is reached.
+ *
+ * All operations are instrumented with OpenTelemetry tracing and metrics for observability.
+ *
+ * @example
+ * ```ts
+ * import { createEvent, NimbusEventBus } from '@nimbus/core';
+ *
+ * const eventBus = new NimbusEventBus({
+ *     name: 'orders',
+ *     maxRetries: 3,
+ *     baseDelay: 1000,
+ *     maxDelay: 30000,
+ *     useJitter: true,
+ *     logPublish: (event) => {
+ *         console.log('Event published:', event.type, event.correlationid);
+ *     },
+ * });
+ *
+ * // Subscribe to events
+ * eventBus.subscribeEvent({
+ *     type: 'at.overlap.nimbus.order-created',
+ *     handler: async (event) => {
+ *         console.log('Order created:', event.data);
+ *     },
+ *     onError: (error, event) => {
+ *         console.error('Failed to handle event:', event.id, error.message);
+ *     },
+ *     options: {
+ *         maxRetries: 5,
+ *         baseDelay: 500,
+ *         maxDelay: 15000,
+ *         useJitter: true,
+ *     },
+ * });
+ *
+ * // Publish an event
+ * const event = createEvent({
+ *     type: 'at.overlap.nimbus.order-created',
+ *     source: 'https://api.example.com',
+ *     correlationid: '550e8400-e29b-41d4-a716-446655440000',
+ *     subject: '/orders/12345',
+ *     data: { orderId: '12345', customerId: '67890' },
+ *     datacontenttype: 'application/json',
+ * });
+ *
+ * eventBus.putEvent(event);
+ * ```
+ */
+export declare class NimbusEventBus {
+    private readonly _eventEmitter;
+    private readonly _name;
+    private readonly _maxRetries;
+    private readonly _baseDelay;
+    private readonly _maxDelay;
+    private readonly _useJitter;
+    private readonly _logPublish?;
+    /**
+     * Create a new NimbusEventBus instance.
+     *
+     * @param options - The options for the event bus.
+     * @param options.name - The name of the event bus instance for metrics and traces. Defaults to 'default'.
+     * @param options.maxRetries - The maximum number of retries for handling the event in case of an error. Defaults to 2.
+     * @param options.baseDelay - The base delay for exponential backoff in milliseconds. Defaults to 1000ms.
+     * @param options.maxDelay - The maximum delay cap for exponential backoff in milliseconds. Defaults to 30000ms.
+     * @param options.useJitter - Whether to add jitter to the retry delay. Defaults to true.
+     * @param options.logPublish - Optional callback invoked when an event is published.
+     *
+     * @example
+     * ```ts
+     * import { getLogger, NimbusEventBus } from '@nimbus/core';
+     *
+     * const eventBus = new NimbusEventBus({
+     *     name: 'orders',
+     *     maxRetries: 3,
+     *     baseDelay: 1000,
+     *     maxDelay: 30000,
+     *     useJitter: true,
+     *     logPublish: (event) => {
+     *         getLogger().debug({
+     *             category: 'EventBus',
+     *             message: 'Published event',
+     *             data: { type: event.type, id: event.id },
+     *             correlationId: event.correlationid,
+     *         });
+     *     },
+     * });
+     * ```
+     */
+    constructor(options?: NimbusEventBusOptions);
+    /**
+     * Publish an event to the event bus.
+     *
+     * The event is validated against the CloudEvents 64KB size limit before publishing.
+     * All subscribers registered for this event type will receive the event asynchronously.
+     *
+     * @param event - The CloudEvents-compliant event to publish.
+     * @throws {GenericException} If the event size exceeds 64KB.
+     *
+     * @example
+     * ```ts
+     * import { createEvent, getEventBus } from '@nimbus/core';
+     *
+     * const eventBus = getEventBus('default');
+     *
+     * // Create and publish an event with all CloudEvents properties
+     * const event = createEvent({
+     *     type: 'at.overlap.nimbus.order-created',
+     *     source: 'https://api.example.com',
+     *     correlationid: '550e8400-e29b-41d4-a716-446655440000',
+     *     subject: '/orders/12345',
+     *     data: {
+     *         orderId: '12345',
+     *         customerId: '67890',
+     *         items: ['item-1', 'item-2'],
+     *         total: 99.99,
+     *     },
+     *     datacontenttype: 'application/json',
+     *     dataschema: 'https://schemas.example.com/order-created.json',
+     * });
+     *
+     * eventBus.putEvent(event);
+     * ```
+     */
+    putEvent<TEvent extends Event>(event: TEvent): void;
+    /**
+     * Subscribe to an event type with a handler function.
+     *
+     * When an event matching the specified type is published, the handler is invoked.
+     * If the handler throws an error, it will be retried using exponential backoff
+     * (delay doubles with each attempt) until either it succeeds or the maximum retry
+     * count is reached.
+     *
+     * @param input - The subscription configuration.
+     * @param input.type - The CloudEvents event type to subscribe to.
+     * @param input.handler - The async handler function to process events.
+     * @param input.onError - Optional callback invoked when all retries are exhausted.
+     * @param input.options - Optional retry options to override EventBus defaults.
+     * @param input.options.maxRetries - Override maximum retry attempts for this subscription.
+     * @param input.options.baseDelay - Override base delay in milliseconds for this subscription.
+     * @param input.options.maxDelay - Override maximum delay cap in milliseconds for this subscription.
+     * @param input.options.useJitter - Override jitter setting for this subscription.
+     *
+     * @example
+     * ```ts
+     * import { getEventBus, getLogger } from '@nimbus/core';
+     *
+     * const eventBus = getEventBus('default');
+     *
+     * // Subscribe with all available options
+     * eventBus.subscribeEvent({
+     *     type: 'at.overlap.nimbus.order-created',
+     *     handler: async (event) => {
+     *         // Process the event
+     *         console.log('Order created:', event.data.orderId);
+     *         console.log('Correlation ID:', event.correlationid);
+     *     },
+     *     onError: (error, event) => {
+     *         getLogger().error({
+     *             category: 'OrderHandler',
+     *             message: 'Failed to process order after all retries',
+     *             data: { eventId: event.id, orderId: event.data.orderId },
+     *             error,
+     *             correlationId: event.correlationid,
+     *         });
+     *     },
+     *     options: {
+     *         maxRetries: 5,
+     *         baseDelay: 500,
+     *         maxDelay: 15000,
+     *         useJitter: true,
+     *     },
+     * });
+     * ```
+     */
+    subscribeEvent<TEvent extends Event>({ type, handler, onError, options, }: SubscribeEventInput<TEvent>): void;
+    private _processEvent;
+    private _recordDeliveryMetrics;
+    private _handleFinalFailure;
+    private _calculateRetryDelay;
+    /**
+     * Validate the size of the event and return the size in bytes.
+     *
+     * To comply with the CloudEvent spec a transmitted event
+     * can only have a maximum size of 64KB.
+     *
+     * @param event - The event to validate.
+     * @returns The size of the event in bytes.
+     */
+    private _validateEventSize;
+}
+/**
+ * Setup a named EventBus instance and register it for later retrieval.
+ *
+ * Use this function to configure an EventBus with specific options at application
+ * startup, then retrieve it later using {@link getEventBus}.
+ *
+ * @param name - The unique name for this EventBus instance.
+ * @param options - Optional configuration options for the EventBus.
+ * @param options.maxRetries - The maximum number of retries for handling events. Defaults to 2.
+ * @param options.baseDelay - The base delay for exponential backoff in milliseconds. Defaults to 1000ms.
+ * @param options.maxDelay - The maximum delay cap for exponential backoff in milliseconds. Defaults to 30000ms.
+ * @param options.useJitter - Whether to add jitter to the retry delay. Defaults to true.
+ * @param options.logPublish - Optional callback invoked when an event is published.
+ *
+ * @example
+ * ```ts
+ * import { getLogger, setupEventBus } from '@nimbus/core';
+ *
+ * // At application startup, configure the event bus with all options
+ * setupEventBus('default', {
+ *     maxRetries: 3,
+ *     baseDelay: 1000,
+ *     maxDelay: 30000,
+ *     useJitter: true,
+ *     logPublish: (event) => {
+ *         getLogger().debug({
+ *             category: 'EventBus',
+ *             message: 'Published event',
+ *             data: { type: event.type, id: event.id },
+ *             correlationId: event.correlationid,
+ *         });
+ *     },
+ * });
+ * ```
+ */
+export declare const setupEventBus: (name: string, options?: Omit<NimbusEventBusOptions, "name">) => void;
+/**
+ * Get a named EventBus instance.
+ *
+ * If an EventBus with the given name has been configured via {@link setupEventBus},
+ * that instance is returned. Otherwise, a new EventBus with default options is created
+ * and registered.
+ *
+ * @param name - The name of the EventBus instance to retrieve. Defaults to 'default'.
+ * @returns The NimbusEventBus instance.
+ *
+ * @example
+ * ```ts
+ * import { createEvent, getEventBus } from '@nimbus/core';
+ *
+ * // Get the event bus configured earlier with setupEventBus
+ * const eventBus = getEventBus('default');
+ *
+ * // Subscribe to events
+ * eventBus.subscribeEvent({
+ *     type: 'at.overlap.nimbus.order-created',
+ *     handler: async (event) => {
+ *         console.log('Order created:', event.data.orderId);
+ *     },
+ * });
+ *
+ * // Publish an event
+ * const event = createEvent({
+ *     type: 'at.overlap.nimbus.order-created',
+ *     source: 'https://api.example.com',
+ *     correlationid: '550e8400-e29b-41d4-a716-446655440000',
+ *     data: { orderId: '12345', customerId: '67890' },
+ *     datacontenttype: 'application/json',
+ * });
+ *
+ * eventBus.putEvent(event);
+ * ```
+ */
+export declare const getEventBus: (name?: string) => NimbusEventBus;
+//# sourceMappingURL=eventBus.d.ts.map

package/esm/lib/eventBus/eventBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventBus.d.ts","sourceRoot":"","sources":["../../../src/lib/eventBus/eventBus.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AA0CjD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,MAAM,SAAS,KAAK,IAAI;IACpD;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD;;OAEG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;CACjD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAyB;IAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;gBACS,OAAO,CAAC,EAAE,qBAAqB;IAU3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,QAAQ,CAAC,MAAM,SAAS,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAqD1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACI,cAAc,CAAC,MAAM,SAAS,KAAK,EAAE,EACxC,IAAI,EACJ,OAAO,EACP,OAAO,EACP,OAAO,GACV,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,IAAI;IAqCrC,OAAO,CAAC,aAAa;IAmFrB,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,mBAAmB;IAwC3B,OAAO,CAAC,oBAAoB;IAW5B;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;CAmB7B;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,aAAa,GACtB,MAAM,MAAM,EACZ,UAAU,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,KAC9C,IAEF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,WAAW,GAAI,OAAM,MAAkB,KAAG,cAStD,CAAC"}