@nimbus-cqrs/core 2.0.0-beta.0

package/esm/lib/message/router.js

@@ -0,0 +1,304 @@
+import { metrics, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
+import { InvalidInputException } from '../exception/invalidInputException.js';
+import { NotFoundException } from '../exception/notFoundException.js';
+import { getLogger } from '../log/logger.js';
+const tracer = trace.getTracer('nimbus');
+const meter = metrics.getMeter('nimbus');
+const messagesRoutedCounter = meter.createCounter('router_messages_routed_total', {
+    description: 'Total number of messages routed',
+});
+const routingDuration = meter.createHistogram('router_routing_duration_seconds', {
+    description: 'Duration of message routing in seconds',
+    unit: 's',
+});
+/**
+ * The MessageRouter routes messages to their handlers based on the type value of the message.
+ *
+ * Messages are validated against their registered Zod schemas before being passed to handlers.
+ * All routing operations are instrumented with OpenTelemetry tracing and metrics for observability.
+ *
+ * @example
+ * ```ts
+ * import { createCommand, MessageRouter } from '@nimbus/core';
+ *
+ * const messageRouter = new MessageRouter({
+ *     name: 'api',
+ *     logInput: (input) => {
+ *         console.log('Received message:', input.type);
+ *     },
+ *     logOutput: (output) => {
+ *         console.log('Handler result:', output);
+ *     },
+ * });
+ *
+ * // Register command handler
+ * messageRouter.register(
+ *     'at.overlap.nimbus.create-order',
+ *     createOrderHandler,
+ *     createOrderCommandSchema,
+ * );
+ *
+ * // Register query handler
+ * messageRouter.register(
+ *     'at.overlap.nimbus.get-order',
+ *     getOrderHandler,
+ *     getOrderQuerySchema,
+ * );
+ *
+ * // Route a command
+ * const command = createCommand({
+ *     type: 'at.overlap.nimbus.create-order',
+ *     source: 'https://api.example.com',
+ *     data: { customerId: '123', items: ['item-1', 'item-2'] },
+ * });
+ *
+ * const result = await messageRouter.route(command);
+ * ```
+ */
+export class MessageRouter {
+    _handlers;
+    _name;
+    _logInput;
+    _logOutput;
+    constructor(options) {
+        this._handlers = new Map();
+        this._name = options?.name ?? 'default';
+        this._logInput = options?.logInput;
+        this._logOutput = options?.logOutput;
+    }
+    /**
+     * Register a handler for a specific message type.
+     *
+     * @param messageType - The message type as defined in the CloudEvents specification
+     *                      (e.g., 'at.overlap.nimbus.create-order').
+     * @param handler - The async handler function that processes the message and returns a result.
+     * @param schema - The Zod schema to validate the incoming message before passing to the handler.
+     *
+     * @example
+     * ```ts
+     * import { commandSchema, type Command, getRouter } from '@nimbus/core';
+     * import { z } from 'zod';
+     *
+     * // Define the command type and schema
+     * const CREATE_ORDER_TYPE = 'at.overlap.nimbus.create-order';
+     *
+     * const createOrderSchema = commandSchema.extend({
+     *     type: z.literal(CREATE_ORDER_TYPE),
+     *     data: z.object({
+     *         customerId: z.string(),
+     *         items: z.array(z.string()),
+     *     }),
+     * });
+     * type CreateOrderCommand = z.infer<typeof createOrderSchema>;
+     *
+     * // Define the handler
+     * const createOrderHandler = async (command: CreateOrderCommand) => {
+     *     // Process the command and return the result
+     *     return { orderId: '12345', status: 'created' };
+     * };
+     *
+     * // Register the handler
+     * const router = getRouter('default');
+     * router.register(CREATE_ORDER_TYPE, createOrderHandler, createOrderSchema);
+     * ```
+     */
+    register(messageType, handler, schema) {
+        this._handlers.set(messageType, {
+            handler,
+            schema,
+        });
+        getLogger().debug({
+            category: 'Nimbus',
+            message: `Registered handler for: ${messageType}`,
+        });
+    }
+    /**
+     * Route a message to its handler.
+     *
+     * The message is validated against the registered schema before being passed to the handler.
+     * The routing operation is instrumented with OpenTelemetry tracing and metrics.
+     *
+     * @param input - The CloudEvents-compliant message to route (command, query, or event).
+     * @returns The result from the handler.
+     *
+     * @throws {NotFoundException} If no handler is registered for the message type.
+     * @throws {InvalidInputException} If the message has no type attribute or fails schema validation.
+     *
+     * @example
+     * ```ts
+     * import { createCommand, getRouter } from '@nimbus/core';
+     *
+     * const router = getRouter('default');
+     *
+     * // Create a command with all CloudEvents properties
+     * const command = createCommand({
+     *     type: 'at.overlap.nimbus.create-order',
+     *     source: 'https://api.example.com',
+     *     correlationid: '550e8400-e29b-41d4-a716-446655440000',
+     *     data: {
+     *         customerId: '123',
+     *         items: ['item-1', 'item-2'],
+     *     },
+     *     datacontenttype: 'application/json',
+     * });
+     *
+     * // Route the command to its registered handler
+     * const result = await router.route(command);
+     * console.log('Order created:', result);
+     * ```
+     */
+    async route(input) {
+        const startTime = performance.now();
+        const messageType = input?.type ?? 'unknown';
+        return await tracer.startActiveSpan('router.route', {
+            kind: SpanKind.INTERNAL,
+            attributes: {
+                'messaging.system': 'nimbusRouter',
+                'messaging.router_name': this._name,
+                'messaging.operation': 'route',
+                'messaging.destination': messageType,
+                ...(input?.correlationid && {
+                    correlation_id: input.correlationid,
+                }),
+            },
+        }, async (span) => {
+            try {
+                if (this._logInput) {
+                    this._logInput(input);
+                }
+                if (!input?.type) {
+                    throw new InvalidInputException('The provided input has no type attribute');
+                }
+                const registration = this._handlers.get(input.type);
+                if (!registration) {
+                    throw new NotFoundException('Message handler not found', {
+                        reason: `Could not find a handler for message type: "${input.type}"`,
+                    });
+                }
+                const { handler, schema } = registration;
+                const validationResult = schema.safeParse(input);
+                if (!validationResult.success) {
+                    throw new InvalidInputException('The provided input is invalid').fromZodError(validationResult.error);
+                }
+                const result = await handler(validationResult.data);
+                if (this._logOutput) {
+                    this._logOutput(result);
+                }
+                messagesRoutedCounter.add(1, {
+                    router_name: this._name,
+                    message_type: input.type,
+                    status: 'success',
+                });
+                routingDuration.record((performance.now() - startTime) / 1000, { router_name: this._name, message_type: input.type });
+                return result;
+            }
+            catch (error) {
+                messagesRoutedCounter.add(1, {
+                    router_name: this._name,
+                    message_type: messageType,
+                    status: 'error',
+                });
+                routingDuration.record((performance.now() - startTime) / 1000, { router_name: this._name, message_type: messageType });
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error
+                        ? error.message
+                        : 'Unknown error',
+                });
+                span.recordException(error instanceof Error
+                    ? error
+                    : new Error('Unknown error'));
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+}
+/**
+ * Registry to store named MessageRouter instances.
+ */
+const routerRegistry = new Map();
+/**
+ * Setup a named MessageRouter instance and register it for later retrieval.
+ *
+ * Use this function to configure a MessageRouter with specific options at application
+ * startup, then retrieve it later using {@link getRouter}.
+ *
+ * @param name - The unique name for this MessageRouter instance.
+ * @param options - Optional configuration options for the MessageRouter.
+ * @param options.logInput - Optional callback invoked when a message is received for routing.
+ * @param options.logOutput - Optional callback invoked after a message has been successfully handled.
+ *
+ * @example
+ * ```ts
+ * import { getLogger, setupRouter } from '@nimbus/core';
+ *
+ * // At application startup, configure the router with all options
+ * setupRouter('default', {
+ *     logInput: (input) => {
+ *         getLogger().debug({
+ *             category: 'Router',
+ *             message: 'Received message',
+ *             data: { type: input.type, correlationId: input.correlationid },
+ *             correlationId: input.correlationid,
+ *         });
+ *     },
+ *     logOutput: (output) => {
+ *         getLogger().debug({
+ *             category: 'Router',
+ *             message: 'Handler completed',
+ *             data: { output },
+ *         });
+ *     },
+ * });
+ * ```
+ */
+export const setupRouter = (name, options) => {
+    routerRegistry.set(name, new MessageRouter({ ...options, name }));
+};
+/**
+ * Get a named MessageRouter instance.
+ *
+ * If a MessageRouter with the given name has been configured via {@link setupRouter},
+ * that instance is returned. Otherwise, a new MessageRouter with default options is created
+ * and registered.
+ *
+ * @param name - The name of the MessageRouter instance to retrieve. Defaults to 'default'.
+ * @returns The MessageRouter instance.
+ *
+ * @example
+ * ```ts
+ * import { createCommand, getRouter } from '@nimbus/core';
+ *
+ * // Get the router configured earlier with setupRouter
+ * const router = getRouter('default');
+ *
+ * // Register handlers
+ * router.register(
+ *     'at.overlap.nimbus.create-order',
+ *     createOrderHandler,
+ *     createOrderSchema,
+ * );
+ *
+ * // Route a message
+ * const command = createCommand({
+ *     type: 'at.overlap.nimbus.create-order',
+ *     source: 'https://api.example.com',
+ *     correlationid: '550e8400-e29b-41d4-a716-446655440000',
+ *     data: { customerId: '123', items: ['item-1'] },
+ *     datacontenttype: 'application/json',
+ * });
+ *
+ * const result = await router.route(command);
+ * ```
+ */
+export const getRouter = (name = 'default') => {
+    let router = routerRegistry.get(name);
+    if (!router) {
+        router = new MessageRouter({ name });
+        routerRegistry.set(name, router);
+    }
+    return router;
+};

package/esm/lib/tracing/withSpan.d.ts

@@ -0,0 +1,67 @@
+import { type Attributes, type Span, SpanKind } from '@opentelemetry/api';
+/**
+ * Options for configuring a span created by withSpan.
+ */
+export type WithSpanOptions = {
+    /**
+     * The name of the span. This will be displayed in your tracing UI.
+     */
+    name: string;
+    /**
+     * The name of the tracer. Defaults to "nimbus".
+     */
+    tracerName?: string;
+    /**
+     * The kind of span. Defaults to SpanKind.INTERNAL.
+     */
+    kind?: SpanKind;
+    /**
+     * Initial attributes to set on the span.
+     */
+    attributes?: Attributes;
+};
+/**
+ * Higher-order function that wraps a function with OpenTelemetry tracing.
+ *
+ * Creates a child span within the current trace context. The span automatically:
+ * - Inherits the parent span from the active context
+ * - Records the function's execution time
+ * - Sets error status and records exceptions on failure
+ * - Ends when the function completes (success or failure)
+ *
+ * @example
+ * ```ts
+ * import { withSpan } from '@nimbus/core';
+ *
+ * const fetchUser = withSpan(
+ *     {
+ *         name: 'fetchUser',
+ *         attributes: {
+ *             'user.source': 'database'
+ *         }
+ *     },
+ *     async (userId: string) => {
+ *         return await db.users.findById(userId);
+ *     }
+ * );
+ *
+ * const user = await fetchUser('123');
+ * ```
+ *
+ * @example
+ * ```ts
+ * const processOrder = withSpan(
+ *     { name: 'processOrder' },
+ *     async (orderId: string, span: Span) => {
+ *         const order = await db.orders.findById(orderId);
+ *
+ *         span.setAttribute('order.total', order.total);
+ *         span.setAttribute('order.items', order.items.length);
+ *
+ *         return await processPayment(order);
+ *     }
+ * );
+ * ```
+ */
+export declare const withSpan: <TArgs extends unknown[], TReturn>(options: WithSpanOptions, fn: (...args: [...TArgs, Span]) => TReturn) => (...args: TArgs) => TReturn;
+//# sourceMappingURL=withSpan.d.ts.map

package/esm/lib/tracing/withSpan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withSpan.d.ts","sourceRoot":"","sources":["../../../src/lib/tracing/withSpan.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,UAAU,EAEf,KAAK,IAAI,EACT,QAAQ,EAGX,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC1B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EACrD,SAAS,eAAe,EACxB,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,KAAK,OAAO,KAC3C,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAkDtB,CAAC"}

package/esm/lib/tracing/withSpan.js

@@ -0,0 +1,87 @@
+import { context, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
+/**
+ * Higher-order function that wraps a function with OpenTelemetry tracing.
+ *
+ * Creates a child span within the current trace context. The span automatically:
+ * - Inherits the parent span from the active context
+ * - Records the function's execution time
+ * - Sets error status and records exceptions on failure
+ * - Ends when the function completes (success or failure)
+ *
+ * @example
+ * ```ts
+ * import { withSpan } from '@nimbus/core';
+ *
+ * const fetchUser = withSpan(
+ *     {
+ *         name: 'fetchUser',
+ *         attributes: {
+ *             'user.source': 'database'
+ *         }
+ *     },
+ *     async (userId: string) => {
+ *         return await db.users.findById(userId);
+ *     }
+ * );
+ *
+ * const user = await fetchUser('123');
+ * ```
+ *
+ * @example
+ * ```ts
+ * const processOrder = withSpan(
+ *     { name: 'processOrder' },
+ *     async (orderId: string, span: Span) => {
+ *         const order = await db.orders.findById(orderId);
+ *
+ *         span.setAttribute('order.total', order.total);
+ *         span.setAttribute('order.items', order.items.length);
+ *
+ *         return await processPayment(order);
+ *     }
+ * );
+ * ```
+ */
+export const withSpan = (options, fn) => {
+    const tracerName = options.tracerName ?? 'nimbus';
+    const tracer = trace.getTracer(tracerName);
+    return (...args) => {
+        const parentContext = context.active();
+        return tracer.startActiveSpan(options.name, {
+            kind: options.kind ?? SpanKind.INTERNAL,
+            attributes: options.attributes,
+        }, parentContext, (span) => {
+            try {
+                const result = fn(...args, span);
+                // Handle promises
+                if (result instanceof Promise) {
+                    return result
+                        .then((value) => {
+                        span.end();
+                        return value;
+                    })
+                        .catch((err) => {
+                        span.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: err.message,
+                        });
+                        span.recordException(err);
+                        span.end();
+                        throw err;
+                    });
+                }
+                span.end();
+                return result;
+            }
+            catch (err) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: err.message,
+                });
+                span.recordException(err);
+                span.end();
+                throw err;
+            }
+        });
+    };
+};

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nimbus-cqrs/core",
+  "version": "2.0.0-beta.0",
+  "description": "Core building blocks of the Nimbus CQRS framework.",
+  "author": "Daniel Gördes <d.goerdes@overlap.at> (https://overlap.at)",
+  "homepage": "https://nimbus.overlap.at",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/overlap-dev/Nimbus"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/overlap-dev/Nimbus/issues"
+  },
+  "module": "./esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./esm/index.js"
+    }
+  },
+  "scripts": {},
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "_generatedBy": "dnt@dev"
+}