arvo-core 0.0.1

package/dist/OpenTelemetry/index.js

@@ -0,0 +1,179 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OTelNull = exports.createOtelSpan = exports.exceptionToSpan = exports.logToSpan = exports.getTelemetryCarrier = exports.getTelemetryContext = void 0;
+var api_1 = require("@opentelemetry/api");
+/**
+ * Retrieves the active context based on the provided trace header.
+ * @param traceparent - The trace header string.
+ * @returns The active context.
+ */
+var getTelemetryContext = function (traceparent) {
+    if (traceparent) {
+        return api_1.propagation.extract(api_1.context.active(), { traceparent: traceparent });
+    }
+    return api_1.context.active();
+};
+exports.getTelemetryContext = getTelemetryContext;
+/**
+ * Parses the context from a span and active context.
+ * @param span - The span to parse the context from.
+ * @param activeContext - The active context (optional, defaults to the current active context).
+ * @returns The parsed telemetry context.
+ */
+var getTelemetryCarrier = function (span, activeContext) {
+    if (activeContext === void 0) { activeContext = api_1.context.active(); }
+    var carrier = {
+        traceparent: null,
+        tracestate: null,
+    };
+    api_1.propagation.inject(activeContext, carrier);
+    if (!carrier.traceparent) {
+        carrier.traceparent = "00-".concat(span.spanContext().traceId, "-").concat(span.spanContext().spanId, "-0").concat(span.spanContext().traceFlags);
+    }
+    return carrier;
+};
+exports.getTelemetryCarrier = getTelemetryCarrier;
+/**
+ * Logs a message to a span with additional parameters.
+ * @param span - The span to log the message to.
+ * @param params - The parameters for the log message.
+ * @param params.level - The log level.
+ * @param params.message - The log message.
+ */
+var logToSpan = function (span, params) {
+    span.addEvent('log_message', __assign(__assign({}, params), { timestamp: performance.now() }));
+};
+exports.logToSpan = logToSpan;
+/**
+ * Logs an exception to a span and sets exception-related attributes.
+ * @param span - The span to log the exception to.
+ * @param level - The log level for the exception.
+ * @param error - The error object to be logged.
+ */
+var exceptionToSpan = function (span, level, error) {
+    (0, exports.logToSpan)(span, {
+        level: level,
+        message: error.message,
+    });
+    span.setAttributes({
+        'exception.type': "[".concat(level, "] ").concat(error.name),
+        'exception.message': error.message,
+        'exception.stacktrace': error.stack || exports.OTelNull,
+    });
+};
+exports.exceptionToSpan = exceptionToSpan;
+/**
+ * Creates a new OpenTelemetry span and executes the provided function within its context.
+ *
+ * This function enhances tracing by creating a new span, executing the given function within
+ * that span's context, and properly handling any errors that may occur. It also ensures that
+ * the wrapped function has access to the current span.
+ *
+ * @template TArgs - The type of the arguments array for the wrapped function.
+ * @template TReturn - The return type of the wrapped function.
+ *
+ * @param {TelemetryContext | string} telemetryContext - The OpenTelemetry context object or a tracer name.
+ * @param {string} spanName - The name of the span to be created.
+ * @param {SpanOptions} [spanOptions] - Optional configuration for the span.
+ * @param {(currentSpan: Span, ...args: TArgs) => TReturn} wrappedFunction - The function to be executed within the new span.
+ *   This function will receive the current span as its first argument.
+ * @param {ThisParameterType<TFunction>} [thisArg] - The 'this' context to be used when calling the wrapped function.
+ * @param {...TArgs} args - The arguments to be passed to the wrapped function.
+ *
+ * @returns {TReturn} The result of the wrapped function execution.
+ *
+ * @throws {Error} Rethrows any error that occurs during the execution of the wrapped function.
+ *
+ * @example
+ * // Using with TelemetryContext
+ * const telemetryContext: TelemetryContext = {
+ *   span: currentSpan,
+ *   tracer: currentTracer,
+ *   context: { traceparent: 'traceparent-value', tracestate: 'tracestate-value' }
+ * };
+ * const result = createOtelSpan(
+ *   telemetryContext,
+ *   'ProcessOrder',
+ *   { attributes: { orderId: '12345' } },
+ *   (span, orderId) => {
+ *     span.addEvent('Processing order');
+ *     return processOrder(orderId);
+ *   },
+ *   null,
+ *   '12345'
+ * );
+ *
+ * @example
+ * // Using with tracer name
+ * const result = createOtelSpan(
+ *   'OrderService',
+ *   'FetchOrderDetails',
+ *   undefined,
+ *   (span, orderId) => {
+ *     span.setAttribute('orderId', orderId);
+ *     return fetchOrderDetails(orderId);
+ *   },
+ *   null,
+ *   '12345'
+ * );
+ */
+var createOtelSpan = function (telemetryContext, spanName, spanOptions, wrappedFunction, thisArg) {
+    var args = [];
+    for (var _i = 5; _i < arguments.length; _i++) {
+        args[_i - 5] = arguments[_i];
+    }
+    var activeContext = api_1.context.active();
+    var activeTracer;
+    if (typeof telemetryContext === 'string') {
+        activeTracer = api_1.trace.getTracer(telemetryContext);
+    }
+    else {
+        activeContext = (0, exports.getTelemetryContext)(telemetryContext.context.traceparent);
+        activeTracer = telemetryContext.tracer;
+    }
+    var newSpan = activeTracer.startSpan(spanName, spanOptions, activeContext);
+    try {
+        var result = api_1.context.with(api_1.trace.setSpan(activeContext, newSpan), function () {
+            return wrappedFunction.call.apply(wrappedFunction, __spreadArray([thisArg, newSpan], args, false));
+        });
+        newSpan.setStatus({
+            code: api_1.SpanStatusCode.OK,
+        });
+        newSpan.end();
+        return result;
+    }
+    catch (error) {
+        (0, exports.exceptionToSpan)(newSpan, 'ERROR', error);
+        newSpan.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: error.message,
+        });
+        newSpan.end();
+        throw error;
+    }
+};
+exports.createOtelSpan = createOtelSpan;
+/**
+ * A constant representing a null or not applicable value in OpenTelemetry context.
+ */
+exports.OTelNull = 'N/A';

package/dist/OpenTelemetry/types.d.ts

@@ -0,0 +1,40 @@
+import { Span, Tracer } from '@opentelemetry/api';
+/**
+ * Represents the available log levels for telemetry.
+ * - DEBUG: Used for detailed information, typically of interest only when diagnosing problems.
+ * - INFO: Used for general information about program execution.
+ * - WARNING: Indicates an unexpected event or a potential problem that doesn't prevent the program from working.
+ * - ERROR: Used for more serious problems that prevent a specific function or feature from working correctly.
+ * - CRITICAL: Used for very serious errors that might prevent the entire program from running.
+ */
+export type TelemetryLogLevel = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL';
+/**
+ * Represents the context for telemetry.
+ * See reference standard documentation [here](https://www.w3.org/TR/trace-context/#design-overview)
+ */
+export type TelemetryCarrier = {
+    /** The traceparent header value */
+    traceparent: string | null;
+    /** The tracestate header value */
+    tracestate: string | null;
+};
+/**
+ * Represents the OpenTelemetry context for a handler.
+ * See reference documentation [here](https://opentelemetry.io/docs/languages/js/instrumentation/#traces)
+ */
+export type TelemetryContext = {
+    /**
+     * The current OpenTelemetry Span. If passed to a function,
+     * then for that function, this is the parent span object
+     */
+    span: Span;
+    /**
+     * The current OpenTelemetry tracer object being
+     * used.
+     */
+    tracer: Tracer;
+    /**
+     * The telemetry headers
+     */
+    context: TelemetryCarrier;
+};

package/dist/OpenTelemetry/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import ArvoEvent from './ArvoEvent';
+import { ArvoDataContentType } from './ArvoEvent/schema';
+import { createArvoEvent } from './ArvoEvent/helpers';
+import { CloudEventContext, CloudEventExtension, ArvoEventData, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent } from './ArvoEvent/types';
+import { exceptionToSpan, logToSpan, getTelemetryContext, getTelemetryCarrier, createOtelSpan, OTelNull } from './OpenTelemetry';
+import { TelemetryCarrier, TelemetryContext, TelemetryLogLevel } from './OpenTelemetry/types';
+import { validateURI, cleanString } from './utils';
+/**
+ * Collection of Zod schemas for validating various aspects of Arvo events.
+ * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.
+ * @property {z.ZodRecord} CloudEventExtensionSchema - Schema for custom CloudEvent extensions.
+ * @property {z.ZodRecord} ArvoDataSchema - Schema for Arvo event data payload.
+ * @property {z.ZodObject} ArvoExtensionSchema - Schema for Arvo-specific CloudEvent extensions.
+ * @property {z.ZodObject} OpenTelemetryExtensionSchema - Schema for OpenTelemetry extensions.
+ */
+declare const ArvoEventSchemas: {
+    CloudEventContextSchema: import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        time: import("zod").ZodString;
+        source: import("zod").ZodEffects<import("zod").ZodString, string, string>;
+        specversion: import("zod").ZodEffects<import("zod").ZodString, "1.0", string>;
+        type: import("zod").ZodString;
+        subject: import("zod").ZodEffects<import("zod").ZodString, string, string>;
+        datacontenttype: import("zod").ZodDefault<import("zod").ZodEffects<import("zod").ZodString, string, string>>;
+        dataschema: import("zod").ZodNullable<import("zod").ZodEffects<import("zod").ZodString, string, string>>;
+    }, "strip", import("zod").ZodTypeAny, {
+        id: string;
+        time: string;
+        source: string;
+        specversion: "1.0";
+        type: string;
+        subject: string;
+        datacontenttype: string;
+        dataschema: string | null;
+    }, {
+        id: string;
+        time: string;
+        source: string;
+        specversion: string;
+        type: string;
+        subject: string;
+        dataschema: string | null;
+        datacontenttype?: string | undefined;
+    }>;
+    CloudEventExtensionSchema: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodBoolean, import("zod").ZodNumber, import("zod").ZodNull]>>;
+    ArvoDataSchema: import("zod").ZodEffects<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodAny>, Record<string, any>, Record<string, any>>;
+    ArvoExtensionSchema: import("zod").ZodObject<{
+        to: import("zod").ZodNullable<import("zod").ZodEffects<import("zod").ZodString, string, string>>;
+        accesscontrol: import("zod").ZodNullable<import("zod").ZodString>;
+        redirectto: import("zod").ZodNullable<import("zod").ZodEffects<import("zod").ZodString, string, string>>;
+        executionunits: import("zod").ZodNullable<import("zod").ZodNumber>;
+    }, "strip", import("zod").ZodTypeAny, {
+        to: string | null;
+        accesscontrol: string | null;
+        redirectto: string | null;
+        executionunits: number | null;
+    }, {
+        to: string | null;
+        accesscontrol: string | null;
+        redirectto: string | null;
+        executionunits: number | null;
+    }>;
+    OpenTelemetryExtensionSchema: import("zod").ZodObject<{
+        traceparent: import("zod").ZodNullable<import("zod").ZodString>;
+        tracestate: import("zod").ZodNullable<import("zod").ZodString>;
+    }, "strip", import("zod").ZodTypeAny, {
+        traceparent: string | null;
+        tracestate: string | null;
+    }, {
+        traceparent: string | null;
+        tracestate: string | null;
+    }>;
+};
+export { ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchemas, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, getTelemetryCarrier, getTelemetryContext, createOtelSpan, TelemetryCarrier, TelemetryContext, TelemetryLogLevel, OTelNull, validateURI, cleanString, };

package/dist/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanString = exports.validateURI = exports.OTelNull = exports.createOtelSpan = exports.getTelemetryContext = exports.getTelemetryCarrier = exports.logToSpan = exports.exceptionToSpan = exports.ArvoEventSchemas = exports.ArvoDataContentType = exports.createArvoEvent = exports.ArvoEvent = void 0;
+var ArvoEvent_1 = __importDefault(require("./ArvoEvent"));
+exports.ArvoEvent = ArvoEvent_1.default;
+var schema_1 = require("./ArvoEvent/schema");
+Object.defineProperty(exports, "ArvoDataContentType", { enumerable: true, get: function () { return schema_1.ArvoDataContentType; } });
+var helpers_1 = require("./ArvoEvent/helpers");
+Object.defineProperty(exports, "createArvoEvent", { enumerable: true, get: function () { return helpers_1.createArvoEvent; } });
+var OpenTelemetry_1 = require("./OpenTelemetry");
+Object.defineProperty(exports, "exceptionToSpan", { enumerable: true, get: function () { return OpenTelemetry_1.exceptionToSpan; } });
+Object.defineProperty(exports, "logToSpan", { enumerable: true, get: function () { return OpenTelemetry_1.logToSpan; } });
+Object.defineProperty(exports, "getTelemetryContext", { enumerable: true, get: function () { return OpenTelemetry_1.getTelemetryContext; } });
+Object.defineProperty(exports, "getTelemetryCarrier", { enumerable: true, get: function () { return OpenTelemetry_1.getTelemetryCarrier; } });
+Object.defineProperty(exports, "createOtelSpan", { enumerable: true, get: function () { return OpenTelemetry_1.createOtelSpan; } });
+Object.defineProperty(exports, "OTelNull", { enumerable: true, get: function () { return OpenTelemetry_1.OTelNull; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "validateURI", { enumerable: true, get: function () { return utils_1.validateURI; } });
+Object.defineProperty(exports, "cleanString", { enumerable: true, get: function () { return utils_1.cleanString; } });
+/**
+ * Collection of Zod schemas for validating various aspects of Arvo events.
+ * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.
+ * @property {z.ZodRecord} CloudEventExtensionSchema - Schema for custom CloudEvent extensions.
+ * @property {z.ZodRecord} ArvoDataSchema - Schema for Arvo event data payload.
+ * @property {z.ZodObject} ArvoExtensionSchema - Schema for Arvo-specific CloudEvent extensions.
+ * @property {z.ZodObject} OpenTelemetryExtensionSchema - Schema for OpenTelemetry extensions.
+ */
+var ArvoEventSchemas = {
+    CloudEventContextSchema: schema_1.CloudEventContextSchema,
+    CloudEventExtensionSchema: schema_1.CloudEventExtensionSchema,
+    ArvoDataSchema: schema_1.ArvoDataSchema,
+    ArvoExtensionSchema: schema_1.ArvoExtensionSchema,
+    OpenTelemetryExtensionSchema: schema_1.OpenTelemetryExtensionSchema,
+};
+exports.ArvoEventSchemas = ArvoEventSchemas;

package/dist/utils.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Cleans a string by removing leading/trailing whitespace from each line,
+ * removing empty lines, and joining the remaining lines with newline characters.
+ *
+ * @param s - The input string to be cleaned.
+ * @returns A new string with cleaned content.
+ *
+ * @example
+ * const input = "  Hello  \n  World  \n\n  ";
+ * const cleaned = cleanString(input);
+ * console.log(cleaned); // Output: "Hello\nWorld"
+ */
+export declare function cleanString(s: string): string;
+/**
+ * Validates if a given string is a properly encoded URI.
+ *
+ * This function checks if the input string remains unchanged after being
+ * decoded and then re-encoded, which indicates that it's a valid URI.
+ *
+ * @param value - The string to be validated as a URI.
+ * @returns A boolean indicating whether the input is a valid URI (true) or not (false).
+ *
+ * @example
+ * validateURI("https://example.com"); // Returns true
+ * validateURI("https://example.com/path with spaces"); // Returns false
+ * validateURI("https://example.com/path%20with%20spaces"); // Returns true
+ */
+export declare const validateURI: (value: string) => boolean;
+/**
+ * Creates an RFC 3339 compliant timestamp string with an optional UTC offset.
+ *
+ * @param offsetHours - The number of hours to offset from UTC. Positive values
+ *                      represent hours ahead of UTC, negative values represent
+ *                      hours behind UTC. Defaults to 0 (UTC).
+ * @returns A string representing the current date and time in RFC 3339 format
+ *          with the specified UTC offset.
+ *
+ * @example
+ * // Returns current time in UTC
+ * createTimestamp();
+ *
+ * @example
+ * // Returns current time with +2 hours offset
+ * createTimestamp(2);
+ *
+ * @example
+ * // Returns current time with -5 hours offset
+ * createTimestamp(-5);
+ */
+export declare const createTimestamp: (offsetHours?: number) => string;

package/dist/utils.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTimestamp = exports.validateURI = void 0;
+exports.cleanString = cleanString;
+/**
+ * Cleans a string by removing leading/trailing whitespace from each line,
+ * removing empty lines, and joining the remaining lines with newline characters.
+ *
+ * @param s - The input string to be cleaned.
+ * @returns A new string with cleaned content.
+ *
+ * @example
+ * const input = "  Hello  \n  World  \n\n  ";
+ * const cleaned = cleanString(input);
+ * console.log(cleaned); // Output: "Hello\nWorld"
+ */
+function cleanString(s) {
+    return s
+        .split('\n')
+        .map(function (item) { return item.trim(); })
+        .filter(function (item) { return Boolean(item); })
+        .join('\n');
+}
+/**
+ * Validates if a given string is a properly encoded URI.
+ *
+ * This function checks if the input string remains unchanged after being
+ * decoded and then re-encoded, which indicates that it's a valid URI.
+ *
+ * @param value - The string to be validated as a URI.
+ * @returns A boolean indicating whether the input is a valid URI (true) or not (false).
+ *
+ * @example
+ * validateURI("https://example.com"); // Returns true
+ * validateURI("https://example.com/path with spaces"); // Returns false
+ * validateURI("https://example.com/path%20with%20spaces"); // Returns true
+ */
+var validateURI = function (value) {
+    try {
+        return value === encodeURI(decodeURI(value));
+    }
+    catch (_a) {
+        return false;
+    }
+};
+exports.validateURI = validateURI;
+/**
+ * Creates an RFC 3339 compliant timestamp string with an optional UTC offset.
+ *
+ * @param offsetHours - The number of hours to offset from UTC. Positive values
+ *                      represent hours ahead of UTC, negative values represent
+ *                      hours behind UTC. Defaults to 0 (UTC).
+ * @returns A string representing the current date and time in RFC 3339 format
+ *          with the specified UTC offset.
+ *
+ * @example
+ * // Returns current time in UTC
+ * createTimestamp();
+ *
+ * @example
+ * // Returns current time with +2 hours offset
+ * createTimestamp(2);
+ *
+ * @example
+ * // Returns current time with -5 hours offset
+ * createTimestamp(-5);
+ */
+var createTimestamp = function (offsetHours) {
+    if (offsetHours === void 0) { offsetHours = 0; }
+    var now = new Date();
+    var offsetMinutes = offsetHours * 60;
+    now.setMinutes(now.getMinutes() - now.getTimezoneOffset() + offsetMinutes);
+    return now
+        .toISOString()
+        .replace('Z', offsetHours >= 0
+        ? "+".concat(String(offsetHours).padStart(2, '0'), ":00")
+        : "-".concat(String(Math.abs(offsetHours)).padStart(2, '0'), ":00"));
+};
+exports.createTimestamp = createTimestamp;

package/generate-changelog.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# File name
+CHANGELOG_FILE="CHANGELOG.md"
+
+# Get current date
+CURRENT_DATE=$(date +"%Y-%m-%d")
+
+# Prompt for version
+read -p "Enter version number: " VERSION
+
+# Prompt for description
+read -p "Enter change description: " DESCRIPTION
+
+# Create or append to CHANGELOG.md
+if [ ! -f "$CHANGELOG_FILE" ]; then
+    echo "# Changelog" > "$CHANGELOG_FILE"
+    echo "" >> "$CHANGELOG_FILE"
+fi
+
+# Add new entry
+{
+    echo "## [$VERSION] - $CURRENT_DATE"
+    echo ""
+    echo "- $DESCRIPTION"
+    echo ""
+} >> "$CHANGELOG_FILE"
+
+echo "Changelog updated successfully!"

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "arvo-core",
+  "version": "0.0.1",
+  "description": "This core package contains all the core classes and components of the Arvo Event Driven System",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node ./dist/index.js",
+    "dev": "ts-node ./src/index.ts",
+    "test": "jest --passWithNoTests --runInBand --detectOpenHandles --forceExit",
+    "format": "npx prettier --write .",
+    "doc": "npx typedoc"
+  },
+  "keywords": [
+    "arvo",
+    "event-driven architecture",
+    "xorca",
+    "core",
+    "cloudevent",
+    "opentelemetry",
+    "orchestrator"
+  ],
+  "author": "Saad Ahmad <saadkwi12@hotmail.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.49.1",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.52.1",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.52.1",
+    "@opentelemetry/resources": "^1.25.1",
+    "@opentelemetry/sdk-metrics": "^1.25.1",
+    "@opentelemetry/sdk-node": "^0.52.1",
+    "@opentelemetry/sdk-trace-node": "^1.25.1",
+    "@opentelemetry/semantic-conventions": "^1.25.1",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.5.0",
+    "@types/uuid": "^10.0.0",
+    "dotenv": "^16.4.5",
+    "jest": "^29.7.0",
+    "prettier": "^3.3.3",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.26.6",
+    "typedoc-plugin-zod": "^1.2.1",
+    "typescript": "^5.5.4"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "uuid": "^10.0.0",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.2"
+  }
+}