arvo-core 1.1.20 → 1.1.22

package/dist/ArvoEvent/helpers.d.ts

@@ -1,6 +1,6 @@
 import ArvoEvent from '.';
 import { ArvoEventData, CloudEventExtension, CreateArvoEvent } from './types';
-import { ExecutionOpenTelemetryConfiguration } from '../types';
+import { ExecutionOpenTelemetryConfiguration } from '../OpenTelemetry/types';
 /**
  * Creates an ArvoEvent with the provided data and extensions.
  *
@@ -12,6 +12,7 @@ import { ExecutionOpenTelemetryConfiguration } from '../types';
  *
  * @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<TData, TExtension>} The created ArvoEvent instance.
  *

package/dist/ArvoEvent/helpers.js

@@ -21,6 +21,7 @@ var uuid_1 = require("uuid");
  *
  * @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<TData, TExtension>} The created ArvoEvent instance.
  *
@@ -46,9 +47,9 @@ var uuid_1 = require("uuid");
  * );
  */
 var createArvoEvent = function (event, extensions, opentelemetry) {
-    if (opentelemetry === void 0) { opentelemetry = {
+    opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
         tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
-    }; }
+    };
     var span = opentelemetry.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;

package/dist/ArvoEventFactory/index.d.ts

@@ -1,7 +1,7 @@
 import ArvoContract from '../ArvoContract';
 import { z } from 'zod';
 import { CreateArvoEvent } from '../ArvoEvent/types';
-import { ExecutionOpenTelemetryConfiguration } from '../types';
+import { ExecutionOpenTelemetryConfiguration } from '../OpenTelemetry/types';
 /**
  * A factory class for creating contractual ArvoEvents based on a given ArvoContract.
  *
@@ -24,6 +24,7 @@ export default class ArvoEventFactory<TUri extends string = string, TType extend
      * @template TExtension - The type of extensions to add to the event.
      * @param event - The event to create. The field 'type' is automatically infered
      * @param [extensions] - Optional extensions to add to the event.
+     * @param [opentelemetry] - Optional opentelemetry configuration object
      * @returns The created ArvoEvent as per the accept record of the contract.
      * @throws If the event data fails validation against the contract.
      */
@@ -35,6 +36,7 @@ export default class ArvoEventFactory<TUri extends string = string, TType extend
      * @template TExtension - The type of extensions to add to the event.
      * @param event - The event to create.
      * @param [extensions] - Optional extensions to add to the event.
+     * @param [opentelemetry] - Optional opentelemetry configuration object
      * @returns The created ArvoEvent as per one of the emits records of the contract.
      * @throws If the event data fails validation against the contract.
      */
@@ -45,6 +47,7 @@ export default class ArvoEventFactory<TUri extends string = string, TType extend
      * @template TExtension - The type of extensions to add to the event.
      * @param event - The event to create, including the error.
      * @param [extensions] - Optional extensions to add to the event.
+     * @param [opentelemetry] - Optional opentelemtry configuration object
      * @returns The created system error ArvoEvent.
      */
     systemError<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<any, any>, 'data' | 'type' | 'datacontenttype' | 'dataschema'> & {

package/dist/ArvoEventFactory/index.js

@@ -49,14 +49,15 @@ var ArvoEventFactory = /** @class */ (function () {
      * @template TExtension - The type of extensions to add to the event.
      * @param event - The event to create. The field 'type' is automatically infered
      * @param [extensions] - Optional extensions to add to the event.
+     * @param [opentelemetry] - Optional opentelemetry configuration object
      * @returns The created ArvoEvent as per the accept record of the contract.
      * @throws If the event data fails validation against the contract.
      */
     ArvoEventFactory.prototype.accepts = function (event, extensions, opentelemetry) {
         var _this = this;
-        if (opentelemetry === void 0) { opentelemetry = {
+        opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
             tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
-        }; }
+        };
         var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, ">.accepts<").concat(this.contract.accepts.type, ">.create"));
         return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
             var _a, _b, _c, _d;
@@ -89,14 +90,15 @@ var ArvoEventFactory = /** @class */ (function () {
      * @template TExtension - The type of extensions to add to the event.
      * @param event - The event to create.
      * @param [extensions] - Optional extensions to add to the event.
+     * @param [opentelemetry] - Optional opentelemetry configuration object
      * @returns The created ArvoEvent as per one of the emits records of the contract.
      * @throws If the event data fails validation against the contract.
      */
     ArvoEventFactory.prototype.emits = function (event, extensions, opentelemetry) {
         var _this = this;
-        if (opentelemetry === void 0) { opentelemetry = {
-            tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
-        }; }
+        opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
+            tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)()
+        };
         var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, ">.emits<").concat(event.type, ">.create"));
         return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
             var _a, _b, _c, _d;
@@ -128,13 +130,14 @@ var ArvoEventFactory = /** @class */ (function () {
      * @template TExtension - The type of extensions to add to the event.
      * @param event - The event to create, including the error.
      * @param [extensions] - Optional extensions to add to the event.
+     * @param [opentelemetry] - Optional opentelemtry configuration object
      * @returns The created system error ArvoEvent.
      */
     ArvoEventFactory.prototype.systemError = function (event, extensions, opentelemetry) {
         var _this = this;
-        if (opentelemetry === void 0) { opentelemetry = {
+        opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
             tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
-        }; }
+        };
         var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, ">.systemError<sys.").concat(this.contract.accepts.type, ".error>.create"));
         return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
             var _a, _b, _c, _d, _e;

package/dist/ArvoOrchestrationSubject/index.d.ts

@@ -4,33 +4,72 @@ import { ArvoOrchestratorVersion, ArvoOrchestrationSubjectContent } from './type
  */
 export default class ArvoOrchestrationSubject {
     /**
-     * Creates a new Arvo orchestration subject.
+     * Represents a wildcard version number used when version matching is not required.
+     * Format follows semantic versioning pattern.
+     */
+    static readonly WildCardMachineVersion: ArvoOrchestratorVersion;
+    /**
+     * Creates a new Arvo orchestration subject with basic required parameters.
+     * This is a convenience method that wraps the more detailed {@link create} method.
+     *
+     * @param param - Configuration object for the orchestration subject
+     * @param param.orchestator - Name identifier of the orchestrator
+     * @param param.version - Version of the orchestrator. If null, defaults to {@link WildCardMachineVersion}
+     * @param param.initiator - Identifier of the entity initiating the orchestration
+     * @returns A base64 encoded string containing the compressed orchestration subject data
+     * @throws Error if the provided parameters result in invalid subject content
      *
-     * @param param - Parameters for creating the subject
-     * @param param.orchestrator - Name of the orchestrator
-     * @param param.version - Version of the orchestrator
-     * @param param.initiator - Initiator of the orchestration
-     * @returns A base64 encoded string representing the orchestration subject
+     * @example
+     * ```typescript
+     * const subject = ArvoOrchestrationSubject.new({
+     *   orchestator: "mainProcess",
+     *   version: "1.0.0",
+     *   initiator: "systemA"
+     * });
+     * ```
      */
     static new(param: {
         orchestator: string;
-        version: ArvoOrchestratorVersion;
+        version: ArvoOrchestratorVersion | null;
         initiator: string;
     }): string;
     /**
-     * Creates an Arvo orchestration subject from the provided content.
+     * Creates an Arvo orchestration subject from detailed content parameters.
+     * The content is validated, compressed using zlib, and encoded in base64 format.
      *
-     * @param param - The orchestration subject content
-     * @returns A base64 encoded string representing the orchestration subject
-     * @throws Error if the provided content is invalid or if compression fails
+     * @param param - Detailed orchestration subject content following the {@link ArvoOrchestrationSubjectContent} structure
+     * @returns A base64 encoded string containing the compressed orchestration subject data
+     * @throws Error if validation fails or compression encounters an error
+     *
+     * @example
+     * ```typescript
+     * const subject = ArvoOrchestrationSubject.create({
+     *   orchestrator: {
+     *     name: "mainProcess",
+     *     version: "1.0.0"
+     *   },
+     *   execution: {
+     *     id: "550e8400-e29b-41d4-a716-446655440000",
+     *     initiator: "systemA"
+     *   }
+     * });
+     * ```
      */
     static create(param: ArvoOrchestrationSubjectContent): string;
     /**
-     * Parses a base64 encoded Arvo orchestration subject string.
+     * Parses a base64 encoded orchestration subject string back into its structured content form.
+     * Performs decompression, JSON parsing, and validation of the subject content.
+     *
+     * @param subject - Base64 encoded string representing the compressed orchestration subject
+     * @returns The decoded and validated {@link ArvoOrchestrationSubjectContent}
+     * @throws Error if decompression, parsing, or validation fails
      *
-     * @param subject - The base64 encoded subject string to parse
-     * @returns The parsed ArvoOrchestrationSubjectContent
-     * @throws Error if parsing or validation fails
+     * @example
+     * ```typescript
+     * const content = ArvoOrchestrationSubject.parse(encodedSubject);
+     * console.log(content.orchestrator.name);
+     * console.log(content.execution.id);
+     * ```
      */
     static parse(subject: string): ArvoOrchestrationSubjectContent;
 }

package/dist/ArvoOrchestrationSubject/index.js

@@ -34,19 +34,31 @@ var ArvoOrchestrationSubject = /** @class */ (function () {
     function ArvoOrchestrationSubject() {
     }
     /**
-     * Creates a new Arvo orchestration subject.
+     * Creates a new Arvo orchestration subject with basic required parameters.
+     * This is a convenience method that wraps the more detailed {@link create} method.
      *
-     * @param param - Parameters for creating the subject
-     * @param param.orchestrator - Name of the orchestrator
-     * @param param.version - Version of the orchestrator
-     * @param param.initiator - Initiator of the orchestration
-     * @returns A base64 encoded string representing the orchestration subject
+     * @param param - Configuration object for the orchestration subject
+     * @param param.orchestator - Name identifier of the orchestrator
+     * @param param.version - Version of the orchestrator. If null, defaults to {@link WildCardMachineVersion}
+     * @param param.initiator - Identifier of the entity initiating the orchestration
+     * @returns A base64 encoded string containing the compressed orchestration subject data
+     * @throws Error if the provided parameters result in invalid subject content
+     *
+     * @example
+     * ```typescript
+     * const subject = ArvoOrchestrationSubject.new({
+     *   orchestator: "mainProcess",
+     *   version: "1.0.0",
+     *   initiator: "systemA"
+     * });
+     * ```
      */
     ArvoOrchestrationSubject.new = function (param) {
+        var _a;
         return ArvoOrchestrationSubject.create({
             orchestrator: {
                 name: param.orchestator,
-                version: param.version,
+                version: (_a = param.version) !== null && _a !== void 0 ? _a : ArvoOrchestrationSubject.WildCardMachineVersion,
             },
             execution: {
                 id: (0, uuid_1.v4)(),
@@ -55,11 +67,26 @@ var ArvoOrchestrationSubject = /** @class */ (function () {
         });
     };
     /**
-     * Creates an Arvo orchestration subject from the provided content.
+     * Creates an Arvo orchestration subject from detailed content parameters.
+     * The content is validated, compressed using zlib, and encoded in base64 format.
+     *
+     * @param param - Detailed orchestration subject content following the {@link ArvoOrchestrationSubjectContent} structure
+     * @returns A base64 encoded string containing the compressed orchestration subject data
+     * @throws Error if validation fails or compression encounters an error
      *
-     * @param param - The orchestration subject content
-     * @returns A base64 encoded string representing the orchestration subject
-     * @throws Error if the provided content is invalid or if compression fails
+     * @example
+     * ```typescript
+     * const subject = ArvoOrchestrationSubject.create({
+     *   orchestrator: {
+     *     name: "mainProcess",
+     *     version: "1.0.0"
+     *   },
+     *   execution: {
+     *     id: "550e8400-e29b-41d4-a716-446655440000",
+     *     initiator: "systemA"
+     *   }
+     * });
+     * ```
      */
     ArvoOrchestrationSubject.create = function (param) {
         try {
@@ -76,11 +103,19 @@ var ArvoOrchestrationSubject = /** @class */ (function () {
         }
     };
     /**
-     * Parses a base64 encoded Arvo orchestration subject string.
+     * Parses a base64 encoded orchestration subject string back into its structured content form.
+     * Performs decompression, JSON parsing, and validation of the subject content.
+     *
+     * @param subject - Base64 encoded string representing the compressed orchestration subject
+     * @returns The decoded and validated {@link ArvoOrchestrationSubjectContent}
+     * @throws Error if decompression, parsing, or validation fails
      *
-     * @param subject - The base64 encoded subject string to parse
-     * @returns The parsed ArvoOrchestrationSubjectContent
-     * @throws Error if parsing or validation fails
+     * @example
+     * ```typescript
+     * const content = ArvoOrchestrationSubject.parse(encodedSubject);
+     * console.log(content.orchestrator.name);
+     * console.log(content.execution.id);
+     * ```
      */
     ArvoOrchestrationSubject.parse = function (subject) {
         try {
@@ -97,6 +132,11 @@ var ArvoOrchestrationSubject = /** @class */ (function () {
             throw new Error((0, utils_1.cleanString)("\n        Error parsing orchestration subject string to the context. \n        Error -> ".concat(e.message, "  \n        subject -> ").concat(subject, "\n      ")));
         }
     };
+    /**
+     * Represents a wildcard version number used when version matching is not required.
+     * Format follows semantic versioning pattern.
+     */
+    ArvoOrchestrationSubject.WildCardMachineVersion = '0.0.0';
     return ArvoOrchestrationSubject;
 }());
 exports.default = ArvoOrchestrationSubject;

package/dist/OpenTelemetry/types.d.ts

@@ -1,3 +1,4 @@
+import { Tracer } from '@opentelemetry/api';
 /**
  * Represents the available log levels for telemetry.
  * - DEBUG: Used for detailed information, typically of interest only when diagnosing problems.
@@ -17,3 +18,16 @@ export type OpenTelemetryHeaders = {
     /** The tracestate header value */
     tracestate: string | null;
 };
+/**
+ * Configuration options for OpenTelemetry integration in execution context.
+ *
+ * This type defines how tracing should be configured and inherited within
+ * the execution pipeline.
+ */
+export type ExecutionOpenTelemetryConfiguration = {
+    /**
+     * OpenTelemetry tracer instance to use for creating spans.
+     * If not provided, a default tracer may be used depending on the implementation.
+     */
+    tracer: Tracer;
+};

package/dist/index.d.ts

@@ -23,11 +23,12 @@ import { ArvoOrchestrationSubjectContentSchema, ArvoOrchestratorVersionSchema }
 import { ArvoOrchestrationSubjectContent, ArvoOrchestratorVersion } from './ArvoOrchestrationSubject/type';
 import ArvoEventHttp from './ArvoEventHttp';
 import { ArvoEventHttpConfig } from './ArvoEventHttp/types';
-import { InferArvoContract, InferArvoEvent, InferArvoOrchestratorContract, ExecutionOpenTelemetryConfiguration } from './types';
+import { InferArvoContract, InferArvoEvent, InferArvoOrchestratorContract } from './types';
 import { createArvoOrchestratorContract } from './ArvoOrchestratorContract/helpers';
 import ArvoOrchestratorContract from './ArvoOrchestratorContract';
 import { ICreateArvoOrchestratorContract, IArvoOrchestratorContract } from './ArvoOrchestratorContract/types';
 import { ArvoOrchestratorEventTypeGen } from './ArvoOrchestratorContract/typegen';
+import { ExecutionOpenTelemetryConfiguration } from './OpenTelemetry/types';
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.

package/dist/types.d.ts

@@ -3,20 +3,6 @@ import ArvoContract from './ArvoContract';
 import ArvoEvent from './ArvoEvent';
 import { ArvoExtension, OpenTelemetryExtension } from './ArvoEvent/types';
 import ArvoOrchestratorContract from './ArvoOrchestratorContract';
-import { Tracer } from '@opentelemetry/api';
-/**
- * Configuration options for OpenTelemetry integration in execution context.
- *
- * This type defines how tracing should be configured and inherited within
- * the execution pipeline.
- */
-export type ExecutionOpenTelemetryConfiguration = {
-    /**
-     * OpenTelemetry tracer instance to use for creating spans.
-     * If not provided, a default tracer may be used depending on the implementation.
-     */
-    tracer: Tracer;
-};
 /**
  * A type utility that infers the structure of an ArvoEvent.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-core",
-  "version": "1.1.20",
+  "version": "1.1.22",
   "description": "This core package contains all the core classes and components of the Arvo Event Driven System",
   "main": "dist/index.js",
   "scripts": {
@@ -50,6 +50,6 @@
     "@opentelemetry/core": "^1.27.0",
     "uuid": "^10.0.0",
     "zod": "^3.23.8",
-    "zod-to-json-schema": "^3.23.2"
+    "zod-to-json-schema": "^3.23.5"
   }
 }