arvo-core 0.0.1

package/dist/ArvoEvent/index.js

@@ -0,0 +1,126 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var schema_1 = require("./schema");
+var OpenTelemetry_1 = require("../OpenTelemetry");
+/**
+ * Represents an ArvoEvent, which extends the CloudEvent specification.
+ * @template TData - The type of the event data, extending ArvoEventData.
+ * @template TExtension - The type of additional extensions, extending CloudEventExtension.
+ */
+var ArvoEvent = /** @class */ (function () {
+    /**
+     * Creates an instance of ArvoEvent.
+     * @param context - The CloudEvent context along with Arvo and OpenTelemetry extensions.
+     * @param data - The event data.
+     * @param extensions - Optional additional extensions.
+     */
+    function ArvoEvent(context, data, extensions) {
+        var cloudEventContext = schema_1.CloudEventContextSchema.parse(context);
+        this.id = cloudEventContext.id;
+        this.time = cloudEventContext.time;
+        this.type = cloudEventContext.type;
+        this.subject = cloudEventContext.subject;
+        this.source = cloudEventContext.source;
+        this.datacontenttype = cloudEventContext.datacontenttype;
+        this.specversion = cloudEventContext.specversion;
+        this.dataschema = cloudEventContext.dataschema;
+        this.data = schema_1.ArvoDataSchema.parse(data);
+        var arvoExtension = schema_1.ArvoExtensionSchema.parse(context);
+        var otelExtension = schema_1.OpenTelemetryExtensionSchema.parse(context);
+        this.extensions = __assign(__assign({}, (extensions
+            ? schema_1.CloudEventExtensionSchema.parse(extensions)
+            : {})), { to: arvoExtension.to, accesscontrol: arvoExtension.accesscontrol, redirectto: arvoExtension.redirectto, executionunits: arvoExtension.executionunits, traceparent: otelExtension.traceparent, tracestate: otelExtension.tracestate });
+        if (this.datacontenttype === schema_1.ArvoDataContentType) {
+            if (!this.extensions.to) {
+                throw new Error("The ArvoEvent must have a non-empty 'to' field");
+            }
+        }
+        Object.freeze(this);
+        Object.freeze(this.extensions);
+    }
+    Object.defineProperty(ArvoEvent.prototype, "cloudevent", {
+        /**
+         * Gets the CloudEvent-specified default fields and extensions.
+         * @returns An object containing the base CloudEvent default fields and extensions.
+         * `default` fields are the standard CloudEvents attributes, which include:
+         * `extension` fields are additional attributes that provide extra context or functionality:
+         * - ArvoExtension: Arvo-specific extensions (to, accesscontrol, redirectto, executionunits)
+         * - OpenTelemetryExtension: OpenTelemetry-specific extensions (traceparent, tracestate)
+         * - TExtension: Any additional custom extensions
+         */
+        get: function () {
+            return {
+                default: {
+                    id: this.id,
+                    source: this.source,
+                    specversion: this.specversion,
+                    type: this.type,
+                    subject: this.subject,
+                    datacontenttype: this.datacontenttype,
+                    dataschema: this.dataschema,
+                    data: this.data,
+                    time: this.time,
+                },
+                extensions: this.extensions,
+            };
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * Converts the ArvoEvent to a JSON-serializable object.
+     * @returns A plain object representation of the ArvoEvent.
+     */
+    ArvoEvent.prototype.toJSON = function () {
+        return __assign(__assign({}, this.cloudevent.default), this.extensions);
+    };
+    /**
+     * Converts the ArvoEvent to a JSON string.
+     * @param [spacing=0] - The number of spaces to use for indentation in the resulting JSON string.
+     * @returns A JSON string representation of the ArvoEvent.
+     */
+    ArvoEvent.prototype.toString = function (spacing) {
+        if (spacing === void 0) { spacing = 0; }
+        return JSON.stringify(this.toJSON(), null, spacing);
+    };
+    Object.defineProperty(ArvoEvent.prototype, "otelAttributes", {
+        /**
+         * Gets OpenTelemetry attributes derived from the ArvoEvent.
+         * @returns An object containing OpenTelemetry attributes.
+         * The OpenTelemetry attributes for CloudEvents is as per
+         * the spec provided [here](https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloudevents/)
+         * Additionally, the Arvo extension attributed are also returned
+         * as `cloudevents.arvo.event_*` fields
+         */
+        get: function () {
+            return {
+                'cloudevents.event_id': this.id || OpenTelemetry_1.OTelNull,
+                'cloudevents.event_source': this.source || OpenTelemetry_1.OTelNull,
+                'cloudevents.event_spec_version': this.specversion || OpenTelemetry_1.OTelNull,
+                'cloudevents.event_subject': this.subject || OpenTelemetry_1.OTelNull,
+                'cloudevents.event_type': this.type || OpenTelemetry_1.OTelNull,
+                'cloudevents.event_time': this.time || OpenTelemetry_1.OTelNull,
+                'cloudevents.event_datacontenttype': this.datacontenttype || OpenTelemetry_1.OTelNull,
+                'cloudevents.event_dataschema': this.dataschema || OpenTelemetry_1.OTelNull,
+                'cloudevents.arvo.event_redirectto': this.extensions.redirectto || OpenTelemetry_1.OTelNull,
+                'cloudevents.arvo.event_to': this.extensions.to || OpenTelemetry_1.OTelNull,
+                'cloudevents.arvo.event_executionunits': this.extensions.executionunits || OpenTelemetry_1.OTelNull,
+            };
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return ArvoEvent;
+}());
+exports.default = ArvoEvent;

package/dist/ArvoEvent/schema.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * The content type for Arvo data in CloudEvents.
+ * This is the recommended content type for Arvo events.
+ */
+export declare const ArvoDataContentType = "application/cloudevents+json;charset=UTF-8;profile=arvo";
+/**
+ * Zod schema for validating the core properties of a CloudEvent.
+ * This schema defines the structure and validation rules for the mandatory
+ * and optional attributes of a CloudEvent as per the CloudEvents specification.
+ */
+export declare const CloudEventContextSchema: z.ZodObject<{
+    id: z.ZodString;
+    time: z.ZodString;
+    source: z.ZodEffects<z.ZodString, string, string>;
+    specversion: z.ZodEffects<z.ZodString, "1.0", string>;
+    type: z.ZodString;
+    subject: z.ZodEffects<z.ZodString, string, string>;
+    datacontenttype: z.ZodDefault<z.ZodEffects<z.ZodString, string, string>>;
+    dataschema: z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>;
+}, "strip", z.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;
+}>;
+/**
+ * Zod schema for validating custom CloudEvent extensions.
+ * This schema allows for additional custom fields in the CloudEvent,
+ * following the CloudEvents specification for extension attributes.
+ */
+export declare const CloudEventExtensionSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>;
+/**
+ * Zod schema for validating the data payload of an Arvo event.
+ * The data must be a JSON serializable object.
+ */
+export declare const ArvoDataSchema: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodAny>, Record<string, any>, Record<string, any>>;
+/**
+ * Zod schema for validating Arvo-specific extensions to the CloudEvent.
+ * This schema defines additional fields used by Arvo for event routing,
+ * access control, and execution metrics.
+ */
+export declare const ArvoExtensionSchema: z.ZodObject<{
+    to: z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>;
+    accesscontrol: z.ZodNullable<z.ZodString>;
+    redirectto: z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>;
+    executionunits: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.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;
+}>;
+/**
+ * Zod schema for validating OpenTelemetry extensions to the CloudEvent.
+ * This schema includes fields for distributed tracing as per the
+ * OpenTelemetry specification.
+ */
+export declare const OpenTelemetryExtensionSchema: z.ZodObject<{
+    traceparent: z.ZodNullable<z.ZodString>;
+    tracestate: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    traceparent: string | null;
+    tracestate: string | null;
+}, {
+    traceparent: string | null;
+    tracestate: string | null;
+}>;

package/dist/ArvoEvent/schema.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenTelemetryExtensionSchema = exports.ArvoExtensionSchema = exports.ArvoDataSchema = exports.CloudEventExtensionSchema = exports.CloudEventContextSchema = exports.ArvoDataContentType = void 0;
+var zod_1 = require("zod");
+var utils_1 = require("../utils");
+var utils_2 = require("./utils");
+/**
+ * The content type for Arvo data in CloudEvents.
+ * This is the recommended content type for Arvo events.
+ */
+exports.ArvoDataContentType = 'application/cloudevents+json;charset=UTF-8;profile=arvo';
+/**
+ * Zod schema for validating the core properties of a CloudEvent.
+ * This schema defines the structure and validation rules for the mandatory
+ * and optional attributes of a CloudEvent as per the CloudEvents specification.
+ */
+exports.CloudEventContextSchema = zod_1.z
+    .object({
+    id: zod_1.z
+        .string()
+        .min(1, 'ID must be a non-empty string')
+        .describe('Unique identifier of the event.'),
+    time: zod_1.z
+        .string()
+        .datetime({ offset: true })
+        .describe('Timestamp of when the occurrence happened. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same source MUST be consistent in this respect. In other words, either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used.'),
+    source: zod_1.z
+        .string()
+        .min(1, 'Source must be a non-empty reference of the producer of the event')
+        .refine(utils_1.validateURI, 'The source must be a properly encoded URI')
+        .describe((0, utils_1.cleanString)("\n      Identifies the context in which an event happened.\n      It must be a valid URI that represents the event producer.\n    ")),
+    specversion: zod_1.z
+        .string()
+        .min(1, 'Spec version must be a non-empty string')
+        .refine(function (val) { return val === '1.0'; }, "Spec version must be '1.0' for this version of the specification")
+        .describe((0, utils_1.cleanString)("\n      The version of the CloudEvents specification which the event uses.\n      Must be '1.0' for this version of the specification.\n    ")),
+    type: zod_1.z
+        .string()
+        .min(1, 'Type must be a non-empty string')
+        .regex(/^[a-z0-9]+(\.[a-z0-9]+)+\.[a-z0-9]+$/, 'Type should be prefixed with a reverse-DNS name')
+        .describe((0, utils_1.cleanString)("\n      Describes the type of event related to the originating occurrence.\n      Should be prefixed with a reverse-DNS name.\n    ")),
+    subject: zod_1.z
+        .string()
+        .min(1)
+        .describe((0, utils_1.cleanString)("\n      Identifies the subject of the event in the context of the event producer. \n      In case of Arvo, this MUST be Process Id.\n    "))
+        .refine(utils_1.validateURI, 'The subject must be a properly encoded URI'),
+    datacontenttype: zod_1.z
+        .string()
+        .min(1, 'Data content type must be a non-empty string')
+        .refine(function (val) {
+        return Boolean(val === null || val === void 0 ? void 0 : val.includes('application/cloudevents+json')) ||
+            Boolean(val === null || val === void 0 ? void 0 : val.includes('application/json'));
+    }, (0, utils_1.cleanString)("\n          The content type must be a valid JSON e.g. it must contain \n          'application/cloudevents+json' or 'application/json'. \n          Arvo recommends using '".concat(exports.ArvoDataContentType, "'\n        ")))
+        .default(exports.ArvoDataContentType)
+        .describe('Content type of the data value. Must adhere to RFC 2046 format if present.'),
+    dataschema: zod_1.z
+        .string()
+        .min(1, 'Must be a non-empty string if present.')
+        .refine(utils_1.validateURI, 'The dataschema must be a properly encoded URI')
+        .nullable()
+        .describe('Identifies the schema that data adheres to'),
+})
+    .describe((0, utils_1.cleanString)("\n    Defines the structure and validation rules \n    for the core properties of a CloudEvent.\n  "));
+/**
+ * Zod schema for validating custom CloudEvent extensions.
+ * This schema allows for additional custom fields in the CloudEvent,
+ * following the CloudEvents specification for extension attributes.
+ */
+exports.CloudEventExtensionSchema = zod_1.z
+    .record(zod_1.z.string().regex(/^[a-z0-9]+$/, (0, utils_1.cleanString)("\n          In compliance with CloudEvent specs, the extension keys must contain only \n          lowercase letters and numbers, with no spaces or other characters  \n        ")), zod_1.z
+    .union([zod_1.z.string(), zod_1.z.boolean(), zod_1.z.number(), zod_1.z.null()])
+    .describe('The CloudEvent extension can only contain a number, boolean, string or null'))
+    .describe('Schema for custom CloudEvent extensions. Allows for additional custom fields in the CloudEvent.');
+/**
+ * Zod schema for validating the data payload of an Arvo event.
+ * The data must be a JSON serializable object.
+ */
+exports.ArvoDataSchema = zod_1.z
+    .record(zod_1.z.string(), zod_1.z.any())
+    .refine(utils_2.isJSONSerializable, 'The Arvo data object must be a JSON serializable object')
+    .describe('A JSON serialisable object as ArvoEvent payload data');
+/**
+ * Zod schema for validating Arvo-specific extensions to the CloudEvent.
+ * This schema defines additional fields used by Arvo for event routing,
+ * access control, and execution metrics.
+ */
+exports.ArvoExtensionSchema = zod_1.z
+    .object({
+    to: zod_1.z
+        .string()
+        .min(1, 'Must be a non empty string')
+        .refine(utils_1.validateURI, "The 'to' must be a properly encoded URI")
+        .nullable()
+        .describe((0, utils_1.cleanString)("\n      This field defined the consumer machine of the event. It's value can\n      be the same as the type field or can be different. This is a metadata \n      field in event routing specifies initial recipients or topics. \n\n      For successful events, it should be determined \n      by handler definition, redirectto, or source. For errors, it should be \n      set to the error destination or event's source.\n    ")),
+    accesscontrol: zod_1.z
+        .string()
+        .min(1, 'Must be a non empty string, if defined')
+        .nullable()
+        .describe((0, utils_1.cleanString)("\n      Defines the access controls for the event. This field may contain one of the following:\n      1. A UserID: A valid UUID representing a user who has access to the event.\n      2. An encrypted string: A base64-encoded encrypted string containing access control information.\n      3. Key-value pairs: A semicolon-separated list of key-value pairs, where each pair is separated by a colon.\n        Example: \"role:admin;department:finance;clearance:top-secret\"\n\n      This field is used to determine who or what can perform actions on or read the event.\n      It can be used for fine-grained access control, allowing different levels of access\n      based on user roles, departments, or other custom criteria.\n\n      If no access controls are needed, this field can be set to null.\n\n      Examples:\n      - \"123e4567-e89b-12d3-a456-426614174000\" (UserID)\n      - \"ZW5jcnlwdGVkX2FjY2Vzc19jb250cm9sX2RhdGE=\" (Encrypted string)\n      - \"role:editor;project:alpha;team:backend\" (Key-value pairs)\n    ")),
+    redirectto: zod_1.z
+        .string()
+        .min(1, 'Must be a non empty string, if defined')
+        .refine(utils_1.validateURI, "The 'redirectto' must be a properly encoded URI")
+        .nullable()
+        .describe((0, utils_1.cleanString)("\n      This is a metadata field for events, indicating alternative recipients \n      or destinations. It enables dynamic routing and complex workflows. \n\n      For successful events, it's set by handlers; for errors, it's \n      null to prevent automatic redirection.\n    ")),
+    executionunits: zod_1.z
+        .number()
+        .nullable()
+        .describe((0, utils_1.cleanString)("\n      This data field represents the cost associated with \n      generating this specific cloudevent. It serves as a metric \n      to track and measure the financial impact of event generation\n      within cloud-based systems or applications.\n    ")),
+})
+    .describe('Schema for Arvo-specific extensions to the CloudEvent.');
+/**
+ * Zod schema for validating OpenTelemetry extensions to the CloudEvent.
+ * This schema includes fields for distributed tracing as per the
+ * OpenTelemetry specification.
+ */
+exports.OpenTelemetryExtensionSchema = zod_1.z
+    .object({
+    traceparent: zod_1.z
+        .string()
+        .min(1, 'Must be a non empty string, if defined')
+        .nullable()
+        .describe((0, utils_1.cleanString)("\n      The traceparent header is part of the OpenTelemetry specification. \n      It contains trace context information, including trace ID, parent \n      span ID, and trace flags, enabling distributed tracing across \n      services and systems.  \n    ")),
+    tracestate: zod_1.z
+        .string()
+        .min(1, 'Must be a non empty string, if defined')
+        .nullable()
+        .describe((0, utils_1.cleanString)("\n      The tracestate header in OpenTelemetry is used to convey vendor-specific \n      trace information across service boundaries. It allows for custom \n      key-value pairs to be propagated alongside the traceparent header in \n      distributed tracing scenarios.  \n    ")),
+})
+    .describe((0, utils_1.cleanString)("\n    Distributed tracing extension as per\n    https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/distributed-tracing.md  \n  "));

package/dist/ArvoEvent/types.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { CloudEventContextSchema, ArvoExtensionSchema, CloudEventExtensionSchema, ArvoDataSchema, OpenTelemetryExtensionSchema } from './schema';
+/**
+ * Represents the core properties of a CloudEvent.
+ */
+export type CloudEventContext = z.infer<typeof CloudEventContextSchema>;
+/**
+ * Represents custom CloudEvent extensions.
+ */
+export type CloudEventExtension = z.infer<typeof CloudEventExtensionSchema>;
+/**
+ * Represents the data payload of an ArvoEvent.
+ */
+export type ArvoEventData = z.infer<typeof ArvoDataSchema>;
+/**
+ * Represents Arvo-specific extensions to the CloudEvent.
+ */
+export type ArvoExtension = z.infer<typeof ArvoExtensionSchema>;
+/**
+ * Represents OpenTelemetry-specific extensions to the CloudEvent.
+ */
+export type OpenTelemetryExtension = z.infer<typeof OpenTelemetryExtensionSchema>;
+/**
+ * Represents the input parameters for creating an ArvoEvent.
+ * @template TData - The type of the event data, extending ArvoEventData.
+ */
+export type CreateArvoEvent<TData extends ArvoEventData> = {
+    /** Unique identifier of the event. Must be a non-empty string. If not provided, a UUID will be generated. */
+    id?: string;
+    /** Timestamp of when the occurrence happened. Must be in ISO 8601 format with timezone offset. */
+    time?: string;
+    /** Identifies the context in which an event happened. Must be a valid URI representing the event producer. */
+    source: string;
+    /** The version of the CloudEvents specification used. Must be '1.0' for this version. */
+    specversion?: '1.0';
+    /** Describes the type of event. Should be prefixed with a reverse-DNS name. */
+    type: string;
+    /** Identifies the subject of the event. For Arvo, this must be the Process Id. */
+    subject: string;
+    /** Content type of the data value. Must include 'application/cloudevents+json' or
+     * 'application/json'. For an ArvoEvent, it is set automatically to
+     * 'application/cloudevents+json;charset=UTF-8;profile=arvo'
+     */
+    datacontenttype?: string;
+    /** Identifies the schema that data adheres to. Must be a valid URI if present. */
+    dataschema?: string;
+    /** The event payload. This payload must be JSON serializable. */
+    data: TData;
+    /** Defines the consumer machine of the event. Used for event routing. Must be a valid URI if present. */
+    to?: string;
+    /** Defines access controls for the event. Can be a UserID, encrypted string, or key-value pairs. */
+    accesscontrol?: string;
+    /** Indicates alternative recipients or destinations for events. Must be a valid URI if present. */
+    redirectto?: string;
+    /** Represents the cost associated with generating the cloudevent. */
+    executionunits?: number;
+    /** Contains trace context information for distributed tracing (OpenTelemetry). */
+    traceparent?: string;
+    /** Conveys vendor-specific trace information across service boundaries (OpenTelemetry). */
+    tracestate?: string;
+};

package/dist/ArvoEvent/types.js

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

package/dist/ArvoEvent/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Checks if an object is JSON serializable.
+ *
+ * @param obj - The object to check for JSON serializability.
+ * @returns A boolean indicating whether the object is JSON serializable.
+ * @throws {Error} If the object is not JSON serializable.
+ */
+export declare const isJSONSerializable: (obj: unknown) => boolean;

package/dist/ArvoEvent/utils.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isJSONSerializable = void 0;
+/**
+ * Checks if an object is JSON serializable.
+ *
+ * @param obj - The object to check for JSON serializability.
+ * @returns A boolean indicating whether the object is JSON serializable.
+ * @throws {Error} If the object is not JSON serializable.
+ */
+var isJSONSerializable = function (obj) {
+    try {
+        var serialized = JSON.stringify(obj);
+        if (serialized === '{}' && Object.keys(obj).length > 0) {
+            return false;
+        }
+        var parsed = JSON.parse(serialized);
+        return JSON.stringify(obj) === JSON.stringify(parsed);
+    }
+    catch (_a) {
+        return false;
+    }
+};
+exports.isJSONSerializable = isJSONSerializable;

package/dist/OpenTelemetry/index.d.ts

@@ -0,0 +1,93 @@
+import { Context, Span, SpanOptions } from '@opentelemetry/api';
+import { TelemetryCarrier, TelemetryLogLevel, TelemetryContext } from './types';
+/**
+ * Retrieves the active context based on the provided trace header.
+ * @param traceparent - The trace header string.
+ * @returns The active context.
+ */
+export declare const getTelemetryContext: (traceparent?: string | null) => Context;
+/**
+ * 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.
+ */
+export declare const getTelemetryCarrier: (span: Span, activeContext?: Context) => TelemetryCarrier;
+/**
+ * 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.
+ */
+export declare const logToSpan: (span: Span, params: {
+    level: TelemetryLogLevel;
+    message: string;
+}) => void;
+/**
+ * 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.
+ */
+export declare const exceptionToSpan: (span: Span, level: TelemetryLogLevel, error: Error) => void;
+/**
+ * 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'
+ * );
+ */
+export declare const createOtelSpan: <TArgs extends unknown[], TReturn>(telemetryContext: TelemetryContext | string, spanName: string, spanOptions: SpanOptions | undefined, wrappedFunction: (currentSpan: Span, ...args: TArgs) => TReturn, thisArg?: ThisParameterType<typeof wrappedFunction>, ...args: TArgs) => TReturn;
+/**
+ * A constant representing a null or not applicable value in OpenTelemetry context.
+ */
+export declare const OTelNull = "N/A";