arvo-core 2.0.8 → 2.0.9

package/dist/ArvoEvent/helpers.d.ts

@@ -2,39 +2,86 @@ import ArvoEvent from '.';
 import { ArvoEventData, CloudEventExtension, CreateArvoEvent } from './types';
 import { ExecutionOpenTelemetryConfiguration } from '../OpenTelemetry/types';
 /**
- * Creates an ArvoEvent with the provided data and extensions.
+ * Creates a strongly-typed ArvoEvent with configurable telemetry options.
  *
- * This function creates a new ArvoEvent instance using the provided event data and optional extensions.
+ * @template TData - Event data type extending ArvoEventData
+ * @template TExtension - Cloud event extension type
+ * @template TType - String literal type for event type
  *
- * @template TData - The type of the event data, extending ArvoEventData.
- * @template TExtension - The type of the cloud event extension, extending CloudEventExtension.
- * @template TType - The type name of the event
+ * @param event - Event configuration and data
+ * @param [extensions] - Optional cloud event extensions
+ * @param [opentelemetry] - OpenTelemetry configuration with options:
+ *   - disable - Completely disables telemetry if true
+ *   - tracer - Custom OpenTelemetry tracer instance
  *
- * @param {CreateArvoEvent<TData>} event - The event data and metadata to create the ArvoEvent.
- * @param {TExtension} [extensions] - Optional cloud event extensions.
- * @param {ExecutionOpenTelemetryConfiguration} [opentelemetry] - Optional opentelemetry configuration object
+ * @returns ArvoEvent instance
  *
- * @returns {ArvoEvent<TData, TExtension>} The created ArvoEvent instance.
- *
- * @throws {Error} If there's an error during the creation process.
+ * @example
+ * ```typescript
+ * // With default telemetry
+ * const event = createArvoEvent({
+ *   type: 'order.created',
+ *   source: '/orders',
+ *   subject: 'order-123',
+ *   data: orderData
+ * });
  *
- * @remarks
- * - If no `id` is provided in the event object, a UUID v4 will be generated.
- * - If no `time` is provided, the current timestamp will be used.
- * - If no `datacontenttype` is provided, it defaults to `application/cloudevents+json;charset=UTF-8;profile=arvo`.
- * - If a non-compatible `datacontenttype` is provided, a warning will be logged to the span.
- * - The `source`, `subject`, `to`, `redirectto`, and `dataschema` fields are URI-encoded.
- * - If no `to` (null, undefined or empty string) is provided, then the `type` value is used by default
+ * // With disabled telemetry
+ * const event = createArvoEvent(
+ *   {
+ *     type: 'order.created',
+ *     source: '/orders',
+ *     subject: 'order-123',
+ *     data: orderData
+ *   },
+ *   undefined,
+ *   { disable: true }
+ * );
  *
- * @example
+ * // With custom tracer
  * const event = createArvoEvent(
  *   {
- *     type: 'com.example.event',
- *     source: '/example/source',
- *     subject: 'example-subject',
- *     data: { key: 'value' }
+ *     type: 'order.created',
+ *     source: '/orders',
+ *     subject: 'order-123',
+ *     data: orderData
  *   },
- *   { customextension: 'value' },
+ *   undefined,
+ *   { tracer: customTracer }
  * );
+ * ```
+ *
+ * @remarks
+ * This function provides several key features:
+ *
+ * 1. **Type Safety**:
+ *    - Ensures event data matches specified type
+ *    - Validates extension structure
+ *    - Provides type-safe event type strings
+ *
+ * 2. **Default Handling**:
+ *    - Generates UUID if no ID provided
+ *    - Sets current timestamp if no time provided
+ *    - Uses default ArvoDataContentType if none specified
+ *
+ * 3. **URI Handling**:
+ *    - Automatically encodes URI components (source, subject, to, redirectto, dataschema)
+ *    - Validates URI format
+ *
+ * 4. **OpenTelemetry Integration**:
+ *    - Creates spans for event creation
+ *    - Tracks errors and warnings
+ *    - Propagates trace context
+ *
+ * 5. **Validation**:
+ *    - Checks data content type compatibility
+ *    - Validates required fields
+ *    - Ensures URI format correctness
+ *
+ * @see {@link ArvoEvent} For the structure of the created event
+ * @see {@link ArvoDataContentType} For supported content types
+ * @see {@link CloudEventExtension} For extension structure
  */
-export declare const createArvoEvent: <TData extends ArvoEventData, TExtension extends CloudEventExtension, TType extends string>(event: CreateArvoEvent<TData, TType>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration) => ArvoEvent<TData, TExtension, TType>;
+export declare const createArvoEvent: <TData extends ArvoEventData, TExtension extends CloudEventExtension, TType extends string>(event: CreateArvoEvent<TData, TType>, extensions?: TExtension, opentelemetry?: Partial<ExecutionOpenTelemetryConfiguration & {
+    disable: boolean;
+}>) => ArvoEvent<TData, TExtension, TType>;

package/dist/ArvoEvent/helpers.js

@@ -11,75 +11,144 @@ var utils_1 = require("../utils");
 var schema_1 = require("./schema");
 var uuid_1 = require("uuid");
 /**
- * Creates an ArvoEvent with the provided data and extensions.
+ * Internal generator function for creating ArvoEvent instances.
  *
- * This function creates a new ArvoEvent instance using the provided event data and optional extensions.
+ * @template TData - Type of the event data
+ * @template TExtension - Type of cloud event extensions
+ * @param {CreateArvoEvent<any, any>} event - The event configuration and data
+ * @param {any} extensions - Cloud event extensions
+ * @param {ReturnType<typeof currentOpenTelemetryHeaders>} otelHeaders - OpenTelemetry headers
+ * @returns {ArvoEvent<any, any, any>} A new ArvoEvent instance
  *
- * @template TData - The type of the event data, extending ArvoEventData.
- * @template TExtension - The type of the cloud event extension, extending CloudEventExtension.
- * @template TType - The type name of the event
- *
- * @param {CreateArvoEvent<TData>} event - The event data and metadata to create the ArvoEvent.
- * @param {TExtension} [extensions] - Optional cloud event extensions.
- * @param {ExecutionOpenTelemetryConfiguration} [opentelemetry] - Optional opentelemetry configuration object
+ * @remarks
+ * This function handles the actual creation of the ArvoEvent instance, including:
+ * - Generation of default values for optional fields
+ * - URI encoding of relevant fields
+ * - Validation of data content type
+ * - Integration with OpenTelemetry headers
+ * ```
+ */
+var generator = function (event, extensions, otelHeaders) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    if (event.datacontenttype && event.datacontenttype !== schema_1.ArvoDataContentType) {
+        var warning = (0, utils_1.cleanString)("\n    Warning! The provided datacontenttype(=".concat(event.datacontenttype, ")\n    is not ArvoEvent compatible (=").concat(schema_1.ArvoDataContentType, "). There may \n    be some limited functionality.\n  "));
+        (0, OpenTelemetry_1.logToSpan)({
+            level: 'WARNING',
+            message: warning,
+        });
+    }
+    return new _1.default({
+        id: (_a = event.id) !== null && _a !== void 0 ? _a : (0, uuid_1.v4)(),
+        type: event.type,
+        accesscontrol: (_b = event.accesscontrol) !== null && _b !== void 0 ? _b : null,
+        executionunits: (_c = event.executionunits) !== null && _c !== void 0 ? _c : null,
+        traceparent: (_e = (_d = event.traceparent) !== null && _d !== void 0 ? _d : otelHeaders.traceparent) !== null && _e !== void 0 ? _e : null,
+        tracestate: (_g = (_f = event.tracestate) !== null && _f !== void 0 ? _f : otelHeaders.tracestate) !== null && _g !== void 0 ? _g : null,
+        datacontenttype: (_h = event.datacontenttype) !== null && _h !== void 0 ? _h : schema_1.ArvoDataContentType,
+        specversion: (_j = event.specversion) !== null && _j !== void 0 ? _j : '1.0',
+        time: (_k = event.time) !== null && _k !== void 0 ? _k : (0, utils_1.createTimestamp)(),
+        source: encodeURI(event.source),
+        subject: encodeURI(event.subject),
+        to: event.to ? encodeURI(event.to) : encodeURI(event.type),
+        redirectto: event.redirectto ? encodeURI(event.redirectto) : null,
+        dataschema: event.dataschema ? encodeURI(event.dataschema) : null,
+    }, event.data, extensions);
+};
+/**
+ * Creates a strongly-typed ArvoEvent with configurable telemetry options.
  *
- * @returns {ArvoEvent<TData, TExtension>} The created ArvoEvent instance.
+ * @template TData - Event data type extending ArvoEventData
+ * @template TExtension - Cloud event extension type
+ * @template TType - String literal type for event type
  *
- * @throws {Error} If there's an error during the creation process.
+ * @param event - Event configuration and data
+ * @param [extensions] - Optional cloud event extensions
+ * @param [opentelemetry] - OpenTelemetry configuration with options:
+ *   - disable - Completely disables telemetry if true
+ *   - tracer - Custom OpenTelemetry tracer instance
  *
- * @remarks
- * - If no `id` is provided in the event object, a UUID v4 will be generated.
- * - If no `time` is provided, the current timestamp will be used.
- * - If no `datacontenttype` is provided, it defaults to `application/cloudevents+json;charset=UTF-8;profile=arvo`.
- * - If a non-compatible `datacontenttype` is provided, a warning will be logged to the span.
- * - The `source`, `subject`, `to`, `redirectto`, and `dataschema` fields are URI-encoded.
- * - If no `to` (null, undefined or empty string) is provided, then the `type` value is used by default
+ * @returns ArvoEvent instance
  *
  * @example
+ * ```typescript
+ * // With default telemetry
+ * const event = createArvoEvent({
+ *   type: 'order.created',
+ *   source: '/orders',
+ *   subject: 'order-123',
+ *   data: orderData
+ * });
+ *
+ * // With disabled telemetry
+ * const event = createArvoEvent(
+ *   {
+ *     type: 'order.created',
+ *     source: '/orders',
+ *     subject: 'order-123',
+ *     data: orderData
+ *   },
+ *   undefined,
+ *   { disable: true }
+ * );
+ *
+ * // With custom tracer
  * const event = createArvoEvent(
  *   {
- *     type: 'com.example.event',
- *     source: '/example/source',
- *     subject: 'example-subject',
- *     data: { key: 'value' }
+ *     type: 'order.created',
+ *     source: '/orders',
+ *     subject: 'order-123',
+ *     data: orderData
  *   },
- *   { customextension: 'value' },
+ *   undefined,
+ *   { tracer: customTracer }
  * );
+ * ```
+ *
+ * @remarks
+ * This function provides several key features:
+ *
+ * 1. **Type Safety**:
+ *    - Ensures event data matches specified type
+ *    - Validates extension structure
+ *    - Provides type-safe event type strings
+ *
+ * 2. **Default Handling**:
+ *    - Generates UUID if no ID provided
+ *    - Sets current timestamp if no time provided
+ *    - Uses default ArvoDataContentType if none specified
+ *
+ * 3. **URI Handling**:
+ *    - Automatically encodes URI components (source, subject, to, redirectto, dataschema)
+ *    - Validates URI format
+ *
+ * 4. **OpenTelemetry Integration**:
+ *    - Creates spans for event creation
+ *    - Tracks errors and warnings
+ *    - Propagates trace context
+ *
+ * 5. **Validation**:
+ *    - Checks data content type compatibility
+ *    - Validates required fields
+ *    - Ensures URI format correctness
+ *
+ * @see {@link ArvoEvent} For the structure of the created event
+ * @see {@link ArvoDataContentType} For supported content types
+ * @see {@link CloudEventExtension} For extension structure
  */
 var createArvoEvent = function (event, extensions, opentelemetry) {
-    opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
-        tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
-    };
-    var span = opentelemetry.tracer.startSpan("createArvoEvent<".concat(event.type, ">"), {});
+    var _a;
+    if (!(opentelemetry === null || opentelemetry === void 0 ? void 0 : opentelemetry.disable)) {
+        return generator(event, extensions, {
+            traceparent: null,
+            tracestate: null,
+        });
+    }
+    var tracer = (_a = opentelemetry === null || opentelemetry === void 0 ? void 0 : opentelemetry.tracer) !== null && _a !== void 0 ? _a : (0, OpenTelemetry_1.fetchOpenTelemetryTracer)();
+    var span = tracer.startSpan("createArvoEvent<".concat(event.type, ">"), {});
     return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         span.setStatus({ code: api_1.SpanStatusCode.OK });
-        var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
         try {
-            if (event.datacontenttype &&
-                event.datacontenttype !== schema_1.ArvoDataContentType) {
-                var warning = (0, utils_1.cleanString)("\n        Warning! The provided datacontenttype(=".concat(event.datacontenttype, ")\n        is not ArvoEvent compatible (=").concat(schema_1.ArvoDataContentType, "). There may \n        be some limited functionality.\n      "));
-                (0, OpenTelemetry_1.logToSpan)({
-                    level: 'WARNING',
-                    message: warning,
-                });
-            }
-            return new _1.default({
-                id: (_a = event.id) !== null && _a !== void 0 ? _a : (0, uuid_1.v4)(),
-                type: event.type,
-                accesscontrol: (_b = event.accesscontrol) !== null && _b !== void 0 ? _b : null,
-                executionunits: (_c = event.executionunits) !== null && _c !== void 0 ? _c : null,
-                traceparent: (_e = (_d = event.traceparent) !== null && _d !== void 0 ? _d : otelHeaders.traceparent) !== null && _e !== void 0 ? _e : null,
-                tracestate: (_g = (_f = event.tracestate) !== null && _f !== void 0 ? _f : otelHeaders.tracestate) !== null && _g !== void 0 ? _g : null,
-                datacontenttype: (_h = event.datacontenttype) !== null && _h !== void 0 ? _h : schema_1.ArvoDataContentType,
-                specversion: (_j = event.specversion) !== null && _j !== void 0 ? _j : '1.0',
-                time: (_k = event.time) !== null && _k !== void 0 ? _k : (0, utils_1.createTimestamp)(),
-                source: encodeURI(event.source),
-                subject: encodeURI(event.subject),
-                to: event.to ? encodeURI(event.to) : encodeURI(event.type),
-                redirectto: event.redirectto ? encodeURI(event.redirectto) : null,
-                dataschema: event.dataschema ? encodeURI(event.dataschema) : null,
-            }, event.data, extensions);
+            return generator(event, extensions, (0, OpenTelemetry_1.currentOpenTelemetryHeaders)());
         }
         catch (error) {
             (0, OpenTelemetry_1.exceptionToSpan)(error);

package/dist/ArvoEventFactory/index.js

@@ -93,7 +93,7 @@ var ArvoEventFactory = /** @class */ (function () {
                 if (!validationResult.success) {
                     throw new Error("Accept Event data validation failed: ".concat(validationResult.error.message));
                 }
-                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { traceparent: (_b = (_a = event.traceparent) !== null && _a !== void 0 ? _a : otelHeaders.traceparent) !== null && _b !== void 0 ? _b : undefined, tracestate: (_d = (_c = event.tracestate) !== null && _c !== void 0 ? _c : otelHeaders.tracestate) !== null && _d !== void 0 ? _d : undefined, type: _this.contract.accepts.type, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(_this.contract.version), data: validationResult.data }), extensions, opentelemetry);
+                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { traceparent: (_b = (_a = event.traceparent) !== null && _a !== void 0 ? _a : otelHeaders.traceparent) !== null && _b !== void 0 ? _b : undefined, tracestate: (_d = (_c = event.tracestate) !== null && _c !== void 0 ? _c : otelHeaders.tracestate) !== null && _d !== void 0 ? _d : undefined, type: _this.contract.accepts.type, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(_this.contract.version), data: validationResult.data }), extensions, { disable: true });
             }
             catch (error) {
                 (0, OpenTelemetry_1.exceptionToSpan)(error);
@@ -147,7 +147,7 @@ var ArvoEventFactory = /** @class */ (function () {
                     var msg = (_d = (_c = validationResult === null || validationResult === void 0 ? void 0 : validationResult.error) === null || _c === void 0 ? void 0 : _c.message) !== null && _d !== void 0 ? _d : "No contract available for ".concat(event.type);
                     throw new Error("Emit Event data validation failed: ".concat(msg));
                 }
-                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { traceparent: (_f = (_e = event.traceparent) !== null && _e !== void 0 ? _e : otelHeaders.traceparent) !== null && _f !== void 0 ? _f : undefined, tracestate: (_h = (_g = event.tracestate) !== null && _g !== void 0 ? _g : otelHeaders.tracestate) !== null && _h !== void 0 ? _h : undefined, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(_this.contract.version), data: validationResult.data }), extensions, opentelemetry);
+                return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { traceparent: (_f = (_e = event.traceparent) !== null && _e !== void 0 ? _e : otelHeaders.traceparent) !== null && _f !== void 0 ? _f : undefined, tracestate: (_h = (_g = event.tracestate) !== null && _g !== void 0 ? _g : otelHeaders.tracestate) !== null && _h !== void 0 ? _h : undefined, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(_this.contract.version), data: validationResult.data }), extensions, { disable: true });
             }
             catch (error) {
                 (0, OpenTelemetry_1.exceptionToSpan)(error);
@@ -200,7 +200,7 @@ var ArvoEventFactory = /** @class */ (function () {
                         errorName: error.name,
                         errorMessage: error.message,
                         errorStack: (_e = error.stack) !== null && _e !== void 0 ? _e : null,
-                    }, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(ArvoOrchestrationSubject_1.default.WildCardMachineVersion) }), extensions, opentelemetry);
+                    }, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(ArvoOrchestrationSubject_1.default.WildCardMachineVersion) }), extensions, { disable: true });
             }
             catch (error) {
                 (0, OpenTelemetry_1.exceptionToSpan)(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-core",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "This core package contains all the core classes and components of the Arvo Event Driven System",
   "main": "dist/index.js",
   "scripts": {