arvo-core 1.1.21 → 1.2.0

package/dist/ArvoOrchestrationSubject/index.d.ts

@@ -4,33 +4,85 @@ 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
+     * @param param.meta - Optional metadata key-value pairs for additional orchestration context
+     * @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"
+     * });
+     *
+     * // With metadata
+     * const subjectWithMeta = ArvoOrchestrationSubject.new({
+     *   orchestator: "com.company.mainProcess",
+     *   version: "1.0.0",
+     *   initiator: "com.company.systemA",
+     *   meta: {
+     *     priority: "high",
+     *     environment: "production"
+     *   }
+     * });
+     * ```
      */
     static new(param: {
         orchestator: string;
-        version: ArvoOrchestratorVersion;
+        version: ArvoOrchestratorVersion | null;
         initiator: string;
+        meta?: Record<string, 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 - 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"
+     *   }
+     * });
+     * ```
      */
     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,32 +34,72 @@ 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
+     * @param param.meta - Optional metadata key-value pairs for additional orchestration context
+     * @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"
+     * });
+     *
+     * // With metadata
+     * const subjectWithMeta = ArvoOrchestrationSubject.new({
+     *   orchestator: "com.company.mainProcess",
+     *   version: "1.0.0",
+     *   initiator: "com.company.systemA",
+     *   meta: {
+     *     priority: "high",
+     *     environment: "production"
+     *   }
+     * });
+     * ```
      */
     ArvoOrchestrationSubject.new = function (param) {
+        var _a, _b;
         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)(),
                 initiator: param.initiator,
             },
+            meta: (_b = param.meta) !== null && _b !== void 0 ? _b : {}
         });
     };
     /**
-     * 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 +116,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 - The base64 encoded subject string to parse
-     * @returns The parsed ArvoOrchestrationSubjectContent
-     * @throws Error if parsing or validation fails
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const content = ArvoOrchestrationSubject.parse(encodedSubject);
+     * console.log(content.orchestrator.name);
+     * console.log(content.execution.id);
+     * ```
      */
     ArvoOrchestrationSubject.parse = function (subject) {
         try {
@@ -97,6 +145,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/ArvoOrchestrationSubject/schema.d.ts

@@ -21,6 +21,7 @@ export declare const ArvoOrchestrationSubjectContentSchema: z.ZodObject<{
         id: string;
         initiator: string;
     }>;
+    meta: z.ZodRecord<z.ZodString, z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     orchestrator: {
         name: string;
@@ -30,6 +31,7 @@ export declare const ArvoOrchestrationSubjectContentSchema: z.ZodObject<{
         id: string;
         initiator: string;
     };
+    meta: Record<string, string>;
 }, {
     orchestrator: {
         name: string;
@@ -39,4 +41,5 @@ export declare const ArvoOrchestrationSubjectContentSchema: z.ZodObject<{
         id: string;
         initiator: string;
     };
+    meta: Record<string, string>;
 }>;

package/dist/ArvoOrchestrationSubject/schema.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArvoOrchestrationSubjectContentSchema = exports.ArvoOrchestratorVersionSchema = void 0;
 var zod_1 = require("zod");
+var utils_1 = require("../utils");
 // Zod schema for ArvoOchestratorVersion
 exports.ArvoOrchestratorVersionSchema = zod_1.z
     .string()
@@ -35,5 +36,8 @@ exports.ArvoOrchestrationSubjectContentSchema = zod_1.z
             .describe('Entity or process that initiated the execution'),
     })
         .describe('Details about the current execution'),
+    meta: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.string())
+        .describe((0, utils_1.cleanString)("\n        Additional metadata for the orchestration process. Store essential key-value pairs \n        that provide context or configuration details necessary for the orchestration. \n        Use selectively to maintain clarity and avoid storing unnecessary information.  \n      "))
 })
     .describe('Context information for Arvo orchestration');

package/dist/ArvoOrchestrationSubject/type.d.ts

@@ -62,4 +62,10 @@ export type ArvoOrchestrationSubjectContent = {
          */
         initiator: string;
     };
+    /**
+     * Additional metadata for the orchestration process. Store essential key-value pairs
+     * that provide context or configuration details necessary for the orchestration.
+     * Use selectively to maintain clarity and avoid storing unnecessary information.
+     */
+    meta: Record<string, string>;
 };

package/package.json

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