arvo-event-handler 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -7,3 +7,7 @@
 
 - Finalised Event Handler implementation
 
+## [0.0.5] - 2024-09-10
+
+- Updated routing
+

package/dist/ArvoEventHandler/index.d.ts

@@ -44,17 +44,46 @@ export default class ArvoEventHandler<TContract extends ArvoContract> {
      * Executes the event handler for a given event.
      *
      * @param event - The event to handle.
-     * @returns A promise that resolves to the resulting ArvoEvents.
+     * @returns A promise that resolves to an array of resulting ArvoEvents.
      *
      * @remarks
      * This method performs the following steps:
      * 1. Creates an OpenTelemetry span for the execution.
      * 2. Validates the input event against the contract.
      * 3. Executes the handler function.
-     * 4. Creates and returns the result event.
+     * 4. Creates and returns the result event(s).
      * 5. Handles any errors and creates an error event if necessary.
      *
      * All telemetry data is properly set and propagated throughout the execution.
+     *
+     * @example
+     * ```typescript
+     * const contract = createArvoContract({ ... })
+     * const handler = createArvoEventHandler({
+     *    contract: contract,
+     *    ...
+     * });
+     * const inputEvent: ArvoEvent<...> = createArvoEvent({ ... });
+     * const resultEvents = await handler.execute(inputEvent);
+     * ```
+     *
+     * @throws All error throw during the execution are returned as a system error event
+     *
+     * **Routing**
+     * The routing of the resulting events is determined as follows:
+     * - The `to` field of the output event is set in this priority:
+     *   1. The `to` field provided by the handler result
+     *   2. The `redirectto` field from the input event
+     *   3. The `source` field from the input event (as a form of reply)
+     * - For system error events, the `to` field is always set to the `source` of the input event.
+     *
+     * **Telemetry**
+     * - Creates a new span for each execution as per the traceparent and tracestate field
+     *   of the event. If those are not present, then a brand new span is created and distributed
+     *   tracing is disabled
+     * - Sets span attributes for input and output events
+     * - Propagates trace context to output events
+     * - Handles error cases and sets appropriate span status
      */
     execute(event: ArvoEvent<ResolveArvoContractRecord<TContract['accepts']>, Record<string, any>, TContract['accepts']['type']>): Promise<ArvoEvent[]>;
     /**

package/dist/ArvoEventHandler/index.js

@@ -62,6 +62,7 @@ var arvo_core_1 = require("arvo-core");
 var schema_1 = require("arvo-core/dist/ArvoEvent/schema");
 var OpenTelemetry_1 = require("../OpenTelemetry");
 var api_1 = require("@opentelemetry/api");
+var utils_1 = require("../utils");
 /**
  * Represents an event handler for Arvo contracts.
  *
@@ -109,17 +110,46 @@ var ArvoEventHandler = /** @class */ (function () {
      * Executes the event handler for a given event.
      *
      * @param event - The event to handle.
-     * @returns A promise that resolves to the resulting ArvoEvents.
+     * @returns A promise that resolves to an array of resulting ArvoEvents.
      *
      * @remarks
      * This method performs the following steps:
      * 1. Creates an OpenTelemetry span for the execution.
      * 2. Validates the input event against the contract.
      * 3. Executes the handler function.
-     * 4. Creates and returns the result event.
+     * 4. Creates and returns the result event(s).
      * 5. Handles any errors and creates an error event if necessary.
      *
      * All telemetry data is properly set and propagated throughout the execution.
+     *
+     * @example
+     * ```typescript
+     * const contract = createArvoContract({ ... })
+     * const handler = createArvoEventHandler({
+     *    contract: contract,
+     *    ...
+     * });
+     * const inputEvent: ArvoEvent<...> = createArvoEvent({ ... });
+     * const resultEvents = await handler.execute(inputEvent);
+     * ```
+     *
+     * @throws All error throw during the execution are returned as a system error event
+     *
+     * **Routing**
+     * The routing of the resulting events is determined as follows:
+     * - The `to` field of the output event is set in this priority:
+     *   1. The `to` field provided by the handler result
+     *   2. The `redirectto` field from the input event
+     *   3. The `source` field from the input event (as a form of reply)
+     * - For system error events, the `to` field is always set to the `source` of the input event.
+     *
+     * **Telemetry**
+     * - Creates a new span for each execution as per the traceparent and tracestate field
+     *   of the event. If those are not present, then a brand new span is created and distributed
+     *   tracing is disabled
+     * - Sets span attributes for input and output events
+     * - Propagates trace context to output events
+     * - Handles error cases and sets appropriate span status
      */
     ArvoEventHandler.prototype.execute = function (event) {
         return __awaiter(this, void 0, void 0, function () {
@@ -178,7 +208,12 @@ var ArvoEventHandler = /** @class */ (function () {
                                             }
                                             return [2 /*return*/, outputs.map(function (output, index) {
                                                     var __extensions = output.__extensions, handlerResult = __rest(output, ["__extensions"]);
-                                                    var result = eventFactory.emits(__assign(__assign({}, handlerResult), { traceparent: otelSpanHeaders.traceparent || undefined, tracestate: otelSpanHeaders.tracestate || undefined, source: _this.source, subject: event.subject, to: handlerResult.to || event.source, executionunits: handlerResult.executionunits || _this.executionunits }), __extensions);
+                                                    var result = eventFactory.emits(__assign(__assign({}, handlerResult), { traceparent: otelSpanHeaders.traceparent || undefined, tracestate: otelSpanHeaders.tracestate || undefined, source: _this.source, subject: event.subject, 
+                                                        // The user should be able to override the `to` field
+                                                        // If that is not present then the 'redirectto' field 
+                                                        // is referred to. Then, after all else, 'source' field
+                                                        // is used as a form of reply. 
+                                                        to: (0, utils_1.coalesceOrDefault)([handlerResult.to, event.redirectto], event.source), executionunits: (0, utils_1.coalesce)(handlerResult.executionunits, _this.executionunits) }), __extensions);
                                                     Object.entries(result.otelAttributes).forEach(function (_a) {
                                                         var key = _a[0], value = _a[1];
                                                         return span.setAttribute("to_emit.".concat(index, ".").concat(key), value);
@@ -195,6 +230,8 @@ var ArvoEventHandler = /** @class */ (function () {
                                             result = eventFactory.systemError({
                                                 source: this.source,
                                                 subject: event.subject,
+                                                // The system error must always got back to 
+                                                // the source
                                                 to: event.source,
                                                 error: error_1,
                                                 executionunits: this.executionunits,

package/dist/MultiArvoEventHandler/index.d.ts

@@ -36,18 +36,43 @@ export default class MultiArvoEventHandler {
      * Executes the event handler for a given event.
      *
      * @param event - The event to handle.
-     * @returns A promise that resolves to the resulting ArvoEvents.
+     * @returns A promise that resolves to an array of resulting ArvoEvents.
      *
      * @remarks
      * This method performs the following steps:
      * 1. Creates an OpenTelemetry span for the execution.
      * 2. Executes the handler function.
-     * 3. Creates and returns the result event.
+     * 3. Creates and returns the result event(s).
      * 4. Handles any errors and creates an error event if necessary.
      *
      * All telemetry data is properly set and propagated throughout the execution.
-     * The method ensures that the resulting event has the correct source, subject,
-     * and execution units, and includes any necessary tracing information.
+     *
+     * @example
+     * ```typescript
+     * const handler = new MultiArvoEventHandler({
+     *    source: 'com.multi.handler',
+     *    ...
+     * });
+     * const inputEvent: ArvoEvent = createArvoEvent({ ... });
+     * const resultEvents = await handler.execute(inputEvent);
+     * ```
+     *
+     * @throws All errors thrown during the execution are returned as a system error event
+     *
+     * **Routing**
+     * The routing of the resulting events is determined as follows:
+     * - The `to` field of the output event is set in this priority:
+     *   1. The `to` field provided by the handler result
+     *   2. The `source` field from the input event (as a form of reply)
+     * - For system error events, the `to` field is always set to the `source` of the input event.
+     *
+     * **Telemetry**
+     * - Creates a new span for each execution as per the traceparent and tracestate field
+     *   of the event. If those are not present, then a brand new span is created and distributed
+     *   tracing is disabled
+     * - Sets span attributes for input and output events
+     * - Propagates trace context to output events
+     * - Handles error cases and sets appropriate span status
      */
     execute(event: ArvoEvent): Promise<ArvoEvent[]>;
     /**

package/dist/MultiArvoEventHandler/index.js

@@ -62,6 +62,7 @@ var api_1 = require("@opentelemetry/api");
 var arvo_core_1 = require("arvo-core");
 var schema_1 = require("arvo-core/dist/ArvoEvent/schema");
 var OpenTelemetry_1 = require("../OpenTelemetry");
+var utils_1 = require("../utils");
 /**
  * Represents a Multi ArvoEvent handler that can process multiple event types.
  *
@@ -100,18 +101,43 @@ var MultiArvoEventHandler = /** @class */ (function () {
      * Executes the event handler for a given event.
      *
      * @param event - The event to handle.
-     * @returns A promise that resolves to the resulting ArvoEvents.
+     * @returns A promise that resolves to an array of resulting ArvoEvents.
      *
      * @remarks
      * This method performs the following steps:
      * 1. Creates an OpenTelemetry span for the execution.
      * 2. Executes the handler function.
-     * 3. Creates and returns the result event.
+     * 3. Creates and returns the result event(s).
      * 4. Handles any errors and creates an error event if necessary.
      *
      * All telemetry data is properly set and propagated throughout the execution.
-     * The method ensures that the resulting event has the correct source, subject,
-     * and execution units, and includes any necessary tracing information.
+     *
+     * @example
+     * ```typescript
+     * const handler = new MultiArvoEventHandler({
+     *    source: 'com.multi.handler',
+     *    ...
+     * });
+     * const inputEvent: ArvoEvent = createArvoEvent({ ... });
+     * const resultEvents = await handler.execute(inputEvent);
+     * ```
+     *
+     * @throws All errors thrown during the execution are returned as a system error event
+     *
+     * **Routing**
+     * The routing of the resulting events is determined as follows:
+     * - The `to` field of the output event is set in this priority:
+     *   1. The `to` field provided by the handler result
+     *   2. The `source` field from the input event (as a form of reply)
+     * - For system error events, the `to` field is always set to the `source` of the input event.
+     *
+     * **Telemetry**
+     * - Creates a new span for each execution as per the traceparent and tracestate field
+     *   of the event. If those are not present, then a brand new span is created and distributed
+     *   tracing is disabled
+     * - Sets span attributes for input and output events
+     * - Propagates trace context to output events
+     * - Handles error cases and sets appropriate span status
      */
     MultiArvoEventHandler.prototype.execute = function (event) {
         return __awaiter(this, void 0, void 0, function () {
@@ -165,7 +191,12 @@ var MultiArvoEventHandler = /** @class */ (function () {
                                             }
                                             return [2 /*return*/, outputs.map(function (output, index) {
                                                     var __extensions = output.__extensions, handlerResult = __rest(output, ["__extensions"]);
-                                                    var result = (0, arvo_core_1.createArvoEvent)(__assign(__assign({}, handlerResult), { traceparent: otelSpanHeaders.traceparent || undefined, tracestate: otelSpanHeaders.tracestate || undefined, source: _this.source, subject: event.subject, to: handlerResult.to || event.source, executionunits: handlerResult.executionunits || _this.executionunits }), __extensions);
+                                                    var result = (0, arvo_core_1.createArvoEvent)(__assign(__assign({}, handlerResult), { traceparent: otelSpanHeaders.traceparent || undefined, tracestate: otelSpanHeaders.tracestate || undefined, source: _this.source, subject: event.subject, 
+                                                        // The user should be able to override the `to` field
+                                                        // If that is not present then the 'redirectto' field 
+                                                        // is referred to. Then, after all else, 'source' field
+                                                        // is used as a form of reply. 
+                                                        to: (0, utils_1.coalesceOrDefault)([handlerResult.to, event.redirectto], event.source), executionunits: (0, utils_1.coalesce)(handlerResult.executionunits, _this.executionunits) }), __extensions);
                                                     Object.entries(result.otelAttributes).forEach(function (_a) {
                                                         var key = _a[0], value = _a[1];
                                                         return span.setAttribute("to_emit.".concat(index, ".").concat(key), value);
@@ -183,6 +214,8 @@ var MultiArvoEventHandler = /** @class */ (function () {
                                                 type: "sys.".concat(this.source, ".error"),
                                                 source: this.source,
                                                 subject: event.subject,
+                                                // The system error must always got back to 
+                                                // the source
                                                 to: event.source,
                                                 executionunits: this.executionunits,
                                                 traceparent: otelSpanHeaders.traceparent || undefined,

package/dist/index.d.ts

@@ -5,4 +5,5 @@ import { PartialExcept } from './types';
 import MultiArvoEventHandler from './MultiArvoEventHandler';
 import { MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler } from './MultiArvoEventHandler/types';
 import { createMultiArvoEventHandler } from './MultiArvoEventHandler/helpers';
-export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, };
+import { isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault } from './utils';
+export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, };

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
+exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
 var ArvoEventHandler_1 = __importDefault(require("./ArvoEventHandler"));
 exports.ArvoEventHandler = ArvoEventHandler_1.default;
 var helpers_1 = require("./ArvoEventHandler/helpers");
@@ -12,3 +12,8 @@ var MultiArvoEventHandler_1 = __importDefault(require("./MultiArvoEventHandler")
 exports.MultiArvoEventHandler = MultiArvoEventHandler_1.default;
 var helpers_2 = require("./MultiArvoEventHandler/helpers");
 Object.defineProperty(exports, "createMultiArvoEventHandler", { enumerable: true, get: function () { return helpers_2.createMultiArvoEventHandler; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "isNullOrUndefined", { enumerable: true, get: function () { return utils_1.isNullOrUndefined; } });
+Object.defineProperty(exports, "getValueOrDefault", { enumerable: true, get: function () { return utils_1.getValueOrDefault; } });
+Object.defineProperty(exports, "coalesce", { enumerable: true, get: function () { return utils_1.coalesce; } });
+Object.defineProperty(exports, "coalesceOrDefault", { enumerable: true, get: function () { return utils_1.coalesceOrDefault; } });

package/dist/utils.d.ts

@@ -1 +1,43 @@
-export declare function isArray(input: unknown): boolean;
+/**
+ * Checks if the item is null or undefined.
+ *
+ * @param item - The value to check.
+ * @returns True if the item is null or undefined, false otherwise.
+ */
+export declare function isNullOrUndefined(item: unknown): item is null | undefined;
+/**
+ * Returns the provided value if it's not null or undefined; otherwise, returns the default value.
+ *
+ * @template T - The type of the value and default value.
+ * @param value - The value to check.
+ * @param defaultValue - The default value to return if the provided value is null or undefined.
+ * @returns The provided value if it's not null or undefined; otherwise, the default value.
+ */
+export declare function getValueOrDefault<T>(value: T | null | undefined, defaultValue: NonNullable<T>): NonNullable<T>;
+/**
+ * Returns the first non-null and non-undefined value from the provided arguments.
+ * If all arguments are null or undefined, returns undefined.
+ *
+ * @template T - The type of the values.
+ * @param values - The values to coalesce.
+ * @returns The first non-null and non-undefined value, or undefined if all are null or undefined.
+ */
+export declare function coalesce<T>(...values: (T | null | undefined)[]): T | undefined;
+/**
+ * Returns the first non-null and non-undefined value from the provided array of values.
+ * If all values in the array are null or undefined, returns the specified default value.
+ *
+ * @template T - The type of the values and the default value.
+ * @param values - An array of values to coalesce.
+ * @param _default - The default value to return if all values in the array are null or undefined.
+ * @returns The first non-null and non-undefined value from the array, or the default value if all are null or undefined.
+ *
+ * @example
+ * const result = coalesceOrDefault([null, undefined, 'hello', 'world'], 'default');
+ * console.log(result); // Output: 'hello'
+ *
+ * @example
+ * const result = coalesceOrDefault([null, undefined], 'default');
+ * console.log(result); // Output: 'default'
+ */
+export declare function coalesceOrDefault<T>(values: (T | null | undefined)[], _default: NonNullable<T>): NonNullable<T>;

package/dist/utils.js

@@ -1,6 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isArray = isArray;
-function isArray(input) {
-    return Array.isArray(input);
+exports.isNullOrUndefined = isNullOrUndefined;
+exports.getValueOrDefault = getValueOrDefault;
+exports.coalesce = coalesce;
+exports.coalesceOrDefault = coalesceOrDefault;
+/**
+ * Checks if the item is null or undefined.
+ *
+ * @param item - The value to check.
+ * @returns True if the item is null or undefined, false otherwise.
+ */
+function isNullOrUndefined(item) {
+    return item === null || item === undefined;
+}
+/**
+ * Returns the provided value if it's not null or undefined; otherwise, returns the default value.
+ *
+ * @template T - The type of the value and default value.
+ * @param value - The value to check.
+ * @param defaultValue - The default value to return if the provided value is null or undefined.
+ * @returns The provided value if it's not null or undefined; otherwise, the default value.
+ */
+function getValueOrDefault(value, defaultValue) {
+    return isNullOrUndefined(value) ? defaultValue : value;
+}
+/**
+ * Returns the first non-null and non-undefined value from the provided arguments.
+ * If all arguments are null or undefined, returns undefined.
+ *
+ * @template T - The type of the values.
+ * @param values - The values to coalesce.
+ * @returns The first non-null and non-undefined value, or undefined if all are null or undefined.
+ */
+function coalesce() {
+    var values = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        values[_i] = arguments[_i];
+    }
+    for (var _a = 0, values_1 = values; _a < values_1.length; _a++) {
+        var value = values_1[_a];
+        if (!isNullOrUndefined(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns the first non-null and non-undefined value from the provided array of values.
+ * If all values in the array are null or undefined, returns the specified default value.
+ *
+ * @template T - The type of the values and the default value.
+ * @param values - An array of values to coalesce.
+ * @param _default - The default value to return if all values in the array are null or undefined.
+ * @returns The first non-null and non-undefined value from the array, or the default value if all are null or undefined.
+ *
+ * @example
+ * const result = coalesceOrDefault([null, undefined, 'hello', 'world'], 'default');
+ * console.log(result); // Output: 'hello'
+ *
+ * @example
+ * const result = coalesceOrDefault([null, undefined], 'default');
+ * console.log(result); // Output: 'default'
+ */
+function coalesceOrDefault(values, _default) {
+    return getValueOrDefault(coalesce.apply(void 0, values), _default);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-event-handler",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "This package contains class and function for event handlers in an Arvo Event Driven system",
   "main": "dist/index.js",
   "scripts": {
@@ -43,7 +43,8 @@
     "ts-node": "^10.9.2",
     "typedoc": "^0.26.6",
     "typedoc-plugin-zod": "^1.2.1",
-    "typescript": "^5.5.4"
+    "typescript": "^5.5.4",
+    "typedoc-plugin-mermaid": "^1.12.0"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",