arvo-event-handler 2.3.3 → 3.0.1

package/dist/{utils.d.ts → utils/index.d.ts}

@@ -1,8 +1,7 @@
 import { type SpanOptions } from '@opentelemetry/api';
-import { type ArvoEvent, type CreateArvoEvent, type OpenTelemetryHeaders } from 'arvo-core';
-import type { ArvoEventHandlerFunctionOutput } from './ArvoEventHandler/types';
-import type { MultiArvoEventHandlerFunctionOutput } from './MultiArvoEventHandler/types';
-import type { ArvoEventHandlerOpenTelemetryOptions } from './types';
+import type { ArvoEvent } from 'arvo-core';
+import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
+export declare function isError(e: unknown): e is Error;
 /**
  * Checks if the item is null or undefined.
  *
@@ -46,38 +45,6 @@ export declare function coalesce<T>(...values: (T | null | undefined)[]): T | un
  * console.log(result); // Output: 'default'
  */
 export declare function coalesceOrDefault<T>(values: (T | null | undefined)[], _default: NonNullable<T>): NonNullable<T>;
-/**
- * Creates ArvoEvents from event handler output.
- *
- * @param events - An array of event handler function outputs.
- * @param otelSpanHeaders - OpenTelemetry headers for tracing.
- * @param source - The source of the event.
- * @param defaultAccessControl - The default access control string for the events
- * @param originalEvent - The original ArvoEvent that triggered the handler.
- * @param handlerExectionUnits - The number of execution units for the handler.
- * @param factory - A function to create ArvoEvents.
- * @returns An array of ArvoEvents created from the handler output.
- */
-export declare const eventHandlerOutputEventCreator: (events: Array<ArvoEventHandlerFunctionOutput<any> | MultiArvoEventHandlerFunctionOutput>, otelSpanHeaders: OpenTelemetryHeaders, source: string, originalEvent: ArvoEvent, handlerExectionUnits: number, factory: (param: CreateArvoEvent<any, any> & {
-    to: string;
-}, extensions?: Record<string, string | number | boolean>) => ArvoEvent<any, any, any>) => ArvoEvent<any, any, any>[];
-export declare const handleArvoEventHandlerCommonError: (error: Error, otelSpanHeaders: OpenTelemetryHeaders, type: string, source: string, originalEvent: ArvoEvent, handlerExectionUnits: number, factory: (param: CreateArvoEvent<any, any> & {
-    to: string;
-}, extensions?: Record<string, string | number | boolean>) => ArvoEvent<any, any, any>) => ArvoEvent<any, any, any>[];
-/**
- * Validates if a string contains only uppercase or lowercase alphanumeric characters.
- *
- * This function checks if the input string consists solely of:
- * - Lowercase letters (a-z)
- * - Numbers (0-9)
- * - Dot (.)
- *
- * It does not allow any special characters, spaces, or other non-alphanumeric characters.
- *
- * @param input - The string to be validated.
- * @returns True if the string contains only alphanumeric characters, false otherwise.
- */
-export declare function isLowerAlphanumeric(input: string): boolean;
 export declare const createEventHandlerTelemetryConfig: (name: string, options: SpanOptions, contextConfig: ArvoEventHandlerOpenTelemetryOptions, event: ArvoEvent) => {
     name: string;
     disableSpanManagement: boolean;

package/dist/utils/index.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEventHandlerTelemetryConfig = void 0;
+exports.isError = isError;
+exports.isNullOrUndefined = isNullOrUndefined;
+exports.getValueOrDefault = getValueOrDefault;
+exports.coalesce = coalesce;
+exports.coalesceOrDefault = coalesceOrDefault;
+var api_1 = require("@opentelemetry/api");
+function isError(e) {
+    return e instanceof Error || (typeof e === 'object' && e !== null && 'message' in e);
+}
+/**
+ * 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);
+}
+var createEventHandlerTelemetryConfig = function (name, options, contextConfig, event) { return ({
+    name: name,
+    disableSpanManagement: true,
+    spanOptions: options,
+    context: contextConfig.inheritFrom === 'EVENT'
+        ? {
+            inheritFrom: 'TRACE_HEADERS',
+            traceHeaders: {
+                traceparent: event.traceparent,
+                tracestate: event.tracestate,
+            },
+        }
+        : {
+            inheritFrom: 'CONTEXT',
+            context: api_1.context.active(),
+        },
+}); };
+exports.createEventHandlerTelemetryConfig = createEventHandlerTelemetryConfig;

package/dist/utils/object/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Represents a path and its corresponding value in an object.
+ * @property {string[]} path - An array of strings representing the path to the value.
+ * @property {any} value - The value found at the specified path.
+ */
+export type PathValue = {
+    path: string[];
+    value: any;
+};
+/**
+ * Recursively retrieves all paths and their corresponding values from an object.
+ *
+ * @param {Record<string, any>} obj - The object from which paths are extracted.
+ * @returns {PathValue[]} An array of PathValue, each containing a path and its corresponding value.
+ * @throws {Error} Will throw an error if `obj` is not a string or an object.
+ *
+ * @example
+ * const obj = { a: { b: 1 }, c: 2 };
+ * const paths = getAllPaths(obj);
+ * // paths = [
+ * //   { path: ['a', 'b'], value: 1 },
+ * //   { path: ['c'], value: 2 }
+ * // ]
+ */
+export declare function getAllPaths(obj: Record<string, any>): PathValue[];
+/**
+ * Converts a PathValue object to a string representation.
+ *
+ * @param {PathValue} item - The PathValue object to convert.
+ * @returns {string} A string representation of the PathValue.
+ *
+ * @example
+ * const pathValue = { path: ['a', 'b'], value: 1 };
+ * const result = pathValueToString(pathValue);
+ * // result = "#a.#b.1"
+ */
+export declare const pathValueToString: (item: PathValue) => string;

package/dist/utils/object/index.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathValueToString = void 0;
+exports.getAllPaths = getAllPaths;
+/**
+ * Recursively retrieves all paths and their corresponding values from an object.
+ *
+ * @param {Record<string, any>} obj - The object from which paths are extracted.
+ * @returns {PathValue[]} An array of PathValue, each containing a path and its corresponding value.
+ * @throws {Error} Will throw an error if `obj` is not a string or an object.
+ *
+ * @example
+ * const obj = { a: { b: 1 }, c: 2 };
+ * const paths = getAllPaths(obj);
+ * // paths = [
+ * //   { path: ['a', 'b'], value: 1 },
+ * //   { path: ['c'], value: 2 }
+ * // ]
+ */
+function getAllPaths(obj) {
+    if (!obj || !(typeof obj === 'string' || typeof obj === 'object')) {
+        throw new Error("[getAllPaths] the 'obj' type must be 'string' or 'object'. The given obj is '".concat(obj, "' of type '").concat(typeof obj, "'"));
+    }
+    var result = [];
+    var stack = [{ obj: obj, path: [] }];
+    while (stack.length > 0) {
+        var stack_item = stack.pop();
+        if (!stack_item)
+            continue;
+        var currentObj = stack_item.obj, currentPath = stack_item.path;
+        if (typeof currentObj !== 'object' || currentObj === null) {
+            result.push({ path: currentPath, value: currentObj });
+        }
+        else {
+            for (var key in currentObj) {
+                // biome-ignore lint/suspicious/noPrototypeBuiltins: no reason to entertain this lint issue
+                if (currentObj.hasOwnProperty(key)) {
+                    stack.push({ obj: currentObj[key], path: currentPath.concat(key) });
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Converts a PathValue object to a string representation.
+ *
+ * @param {PathValue} item - The PathValue object to convert.
+ * @returns {string} A string representation of the PathValue.
+ *
+ * @example
+ * const pathValue = { path: ['a', 'b'], value: 1 };
+ * const result = pathValueToString(pathValue);
+ * // result = "#a.#b.1"
+ */
+var pathValueToString = function (item) {
+    if (!(item.path || []).length) {
+        return item.value.toString();
+    }
+    var pathString = item.path.map(function (i) { return "#".concat(i); }).join('.');
+    return "".concat(pathString, ".").concat(item.value);
+};
+exports.pathValueToString = pathValueToString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-event-handler",
-  "version": "2.3.3",
+  "version": "3.0.1",
   "description": "Type-safe event handler system with versioning, telemetry, and contract validation for distributed Arvo event-driven architectures, featuring routing and multi-handler support.",
   "main": "dist/index.js",
   "scripts": {
@@ -10,7 +10,8 @@
     "test": "jest --passWithNoTests --runInBand --detectOpenHandles --forceExit",
     "lint": "biome check --fix",
     "format": "biome format --fix",
-    "doc": "npx typedoc"
+    "doc": "npx typedoc",
+    "otel": "docker run --rm -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 -p 16686:16686 -p 4317:4317 -p 4318:4318 -p 9411:9411 jaegertracing/all-in-one:latest"
   },
   "keywords": ["arvo", "event-driven architecture", "xorca", "core", "cloudevent", "opentelemetry", "orchestrator"],
   "author": "Saad Ahmad <saadkwi12@hotmail.com>",
@@ -45,8 +46,9 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^1.30.1",
-    "arvo-core": "^2.3.3",
+    "arvo-core": "^3.0.1",
     "uuid": "^11.1.0",
+    "xstate": "^5.20.1",
     "zod": "^3.25.67"
   },
   "engines": {

package/dist/ArvoEventRouter/helpers.d.ts

@@ -1,19 +0,0 @@
-import { ArvoEventRouter } from '.';
-import type { IArvoEventRouter } from './types';
-/**
- * Creates a new ArvoEventRouter instance with the provided configuration.
- * Validates source format and ensures unique handlers per event type.
- *
- * @param param Configuration for router initialization including source,
- * handlers, and execution metrics
- * @returns Configured ArvoEventRouter instance
- * @throws When handlers have duplicate event types or source format is invalid
- *
- * @example
- * const router = createArvoEventRouter({
- *   source: 'payment.service',
- *   handlers: [paymentHandler, notificationHandler],
- *   executionunits: 10
- * });
- */
-export declare const createArvoEventRouter: (param: IArvoEventRouter) => ArvoEventRouter;

package/dist/ArvoEventRouter/helpers.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createArvoEventRouter = void 0;
-var _1 = require(".");
-/**
- * Creates a new ArvoEventRouter instance with the provided configuration.
- * Validates source format and ensures unique handlers per event type.
- *
- * @param param Configuration for router initialization including source,
- * handlers, and execution metrics
- * @returns Configured ArvoEventRouter instance
- * @throws When handlers have duplicate event types or source format is invalid
- *
- * @example
- * const router = createArvoEventRouter({
- *   source: 'payment.service',
- *   handlers: [paymentHandler, notificationHandler],
- *   executionunits: 10
- * });
- */
-var createArvoEventRouter = function (param) { return new _1.ArvoEventRouter(param); };
-exports.createArvoEventRouter = createArvoEventRouter;

package/dist/ArvoEventRouter/index.d.ts

@@ -1,89 +0,0 @@
-import { type SpanOptions } from '@opentelemetry/api';
-import { type ArvoContract, ArvoEvent } from 'arvo-core';
-import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
-import type ArvoEventHandler from '../ArvoEventHandler';
-import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
-import type { IArvoEventRouter } from './types';
-/**
- * ArvoEventRouter manages event routing and execution within the Arvo event system. It directs
- * incoming events to appropriate handlers based on event type while maintaining telemetry
- * and error handling.
- *
- * The router enforces contract validation, manages execution costs, and provides comprehensive
- * telemetry via OpenTelemetry integration. It handles event lifecycle management from initial
- * receipt through processing and response generation.
- *
- * @example
- * ```typescript
- * const router = createArvoEventRouter({
- *   source: "payment.service",
- *   executionunits: 1,
- *   handlers: [paymentProcessedHandler, paymentFailedHandler]
- * });
- *
- * // Route an incoming event
- * const results = await router.execute(incomingEvent);
- * ```
- */
-export declare class ArvoEventRouter extends AbstractArvoEventHandler {
-    /** Source identifier for the router used in event routing */
-    readonly source: string;
-    /** Registry mapping event types to their handlers */
-    readonly handlersMap: Record<string, ArvoEventHandler<ArvoContract>>;
-    /**
-     * Computational cost metric for router operations.
-     * Used for resource tracking and billing calculations.
-     */
-    readonly executionunits: number;
-    /**
-     * The OpenTelemetry span options
-     */
-    readonly spanOptions: SpanOptions;
-    /**
-     * Creates an ArvoEventRouter instance with specified configuration.
-     *
-     * @param param - Router configuration containing source, handlers, and execution parameters
-     *
-     * @throws {Error} When source contains invalid characters (non-alphanumeric)
-     * @throws {Error} When multiple handlers are registered for the same event type
-     */
-    constructor(param: IArvoEventRouter);
-    /**
-     * Routes and executes an event through its appropriate handler. Creates a telemetry span,
-     * validates the event destination, finds a matching handler, and processes the event.
-     * Handles routing errors, missing handlers, and execution failures by returning error
-     * events with telemetry context. Tracks performance through execution units and span
-     * propagation.
-     *
-     * @param event The event to be routed and processed
-     * @param opentelemetry Configuration for telemetry context inheritance
-     * @returns Promise resolving to resulting events or error events
-     *
-     * @throws {ConfigViolation} When event destination does not match router's source
-     * @throws {ConfigViolation} When no registered handler exists for the event type
-     * @throws Other Violation error which are thrown by the registered event handlers
-     */
-    execute(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): Promise<{
-        events: ArvoEvent[];
-    }>;
-    /**
-     * System error schema configuration.
-     * Error events follow format: sys.<handler-source>.error
-     */
-    get systemErrorSchema(): {
-        type: string;
-        schema: import("zod").ZodObject<{
-            errorName: import("zod").ZodString;
-            errorMessage: import("zod").ZodString;
-            errorStack: import("zod").ZodNullable<import("zod").ZodString>;
-        }, "strip", import("zod").ZodTypeAny, {
-            errorName: string;
-            errorMessage: string;
-            errorStack: string | null;
-        }, {
-            errorName: string;
-            errorMessage: string;
-            errorStack: string | null;
-        }>;
-    };
-}