arvo-core 1.1.15 → 1.1.16

package/CHANGELOG.md

@@ -64,3 +64,7 @@
 
 - Added Arvo Orchestrator Contract primitive
 
+## [1.1.16] - 2024-10-21
+
+- Added mandatory parent chaining in orchestration events so the process chaining and orchestration chaining can be traced
+

package/dist/ArvoContract/helpers.js

@@ -34,8 +34,12 @@ var utils_1 = require("../utils");
  * });
  */
 var createArvoContract = function (contract) {
-    var createErrorMessage = function (source, type) { return (0, utils_1.cleanString)("\n    In contract (uri=".concat(contract.uri, "), the '").concat(source, "' event (type=").concat(type, ") must not start \n    with '").concat(typegen_1.ArvoOrchestratorEventTypeGen.__prefix, "' becuase this a reserved pattern \n    for Arvo orchestrators.\n  ")); };
-    var validator = function (value) { return value.startsWith(typegen_1.ArvoOrchestratorEventTypeGen.__prefix); };
+    var createErrorMessage = function (source, type) {
+        return (0, utils_1.cleanString)("\n    In contract (uri=".concat(contract.uri, "), the '").concat(source, "' event (type=").concat(type, ") must not start \n    with '").concat(typegen_1.ArvoOrchestratorEventTypeGen.__prefix, "' becuase this a reserved pattern \n    for Arvo orchestrators.\n  "));
+    };
+    var validator = function (value) {
+        return value.startsWith(typegen_1.ArvoOrchestratorEventTypeGen.__prefix);
+    };
     if (validator(contract.accepts.type)) {
         throw new Error(createErrorMessage('accepts', contract.accepts.type));
     }

package/dist/ArvoOrchestratorContract/helpers.d.ts

@@ -1,6 +1,6 @@
-import { z } from "zod";
-import { ICreateArvoOrchestratorContract } from "./types";
-import ArvoOrchestratorContract from ".";
+import { z } from 'zod';
+import { ICreateArvoOrchestratorContract } from './types';
+import ArvoOrchestratorContract from '.';
 /**
  * Creates an ArvoOrchestratorContract with specified parameters.
  *
@@ -10,22 +10,58 @@ import ArvoOrchestratorContract from ".";
  *
  * Key features:
  * 1. Initialization: Defines the structure and validation for the initial event that starts the orchestration.
+ *    The init schema is automatically intersected with OrchestrationInitEventBaseSchema.
  * 2. Completion: Specifies the event type and data emitted when the orchestration process concludes.
  * 3. Type Safety: Utilizes TypeScript generics to ensure type consistency across the contract definition.
  * 4. Runtime Validation: Employs Zod schemas for robust runtime type checking and data validation.
  *
+ * Base Schema:
+ * The OrchestrationInitEventBaseSchema is automatically intersected with the user-provided init schema.
+ * This base schema includes essential fields for orchestration, such as:
+ * - parentSubject$$: Identifies the subject of the parent process or event in the ArvoEvent system.
+ *
  * This contract serves as a crucial component in maintaining consistency and type safety
  * throughout the orchestration process, from initiation to completion.
  *
  * @param param - The configuration object for creating the contract.
  * @param param.uri - The URI for the contract.
- * @param param.name - The name of the contract (must be alphanumeric).
+ * @param param.name - The name of the contract (must be lowercase alphanumeric with dots).
  * @param param.schema - The schema object containing init and complete Zod schemas.
- * @param param.schema.init - The Zod schema for initialization.
+ * @param param.schema.init - The Zod schema for initialization (will be intersected with OrchestrationInitEventBaseSchema).
  * @param param.schema.complete - The Zod schema for completion.
  *
- * @throws {Error} Throws an error if the name is not alphanumeric.
+ * @throws {Error} Throws an error if the name is not lowercase alphanumeric with dots.
  *
  * @returns Returns a new ArvoOrchestratorContract instance with the specified parameters.
+ *
+ * @example
+ * ```typescript
+ * import { createArvoOrchestratorContract } from 'arvo-core'
+ * import { z } from 'zod'
+ *
+ * const contract = createArvoOrchestratorContract({
+ *   uri: '#/example/contract',
+ *   name: 'rag.orchestrator',
+ *   schema: {
+ *     init: z.object({
+ *       request: z.string(),
+ *       vectorStore: z.string(),
+ *       llm: z.string()
+ *     }),
+ *     complete: z.object({
+ *       response: z.string()
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * In this example, the actual init schema will be an intersection of the provided schema
+ * and the OrchestrationInitEventBaseSchema, ensuring all necessary fields are included.
  */
-export declare const createArvoOrchestratorContract: <TUri extends string, TName extends string, TInit extends z.ZodTypeAny, TComplete extends z.ZodTypeAny>(param: ICreateArvoOrchestratorContract<TUri, TName, TInit, TComplete>) => ArvoOrchestratorContract<TUri, `arvo.orc.${TName}`, TInit, `arvo.orc.${TName}.done`, TComplete>;
+export declare const createArvoOrchestratorContract: <TUri extends string, TName extends string, TInit extends z.ZodTypeAny, TComplete extends z.ZodTypeAny>(param: ICreateArvoOrchestratorContract<TUri, TName, TInit, TComplete>) => ArvoOrchestratorContract<TUri, `arvo.orc.${TName}`, z.ZodIntersection<z.ZodObject<{
+    parentSubject$$: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    parentSubject$$: string | null;
+}, {
+    parentSubject$$: string | null;
+}>, TInit>, `arvo.orc.${TName}.done`, TComplete>;

package/dist/ArvoOrchestratorContract/helpers.js

@@ -4,8 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createArvoOrchestratorContract = void 0;
+var zod_1 = require("zod");
 var _1 = __importDefault(require("."));
 var typegen_1 = require("./typegen");
+var schema_1 = require("./schema");
 /**
  * Validates if a string contains only uppercase or lowercase alphanumeric characters.
  *
@@ -32,23 +34,53 @@ function isLowerAlphanumeric(input) {
  *
  * Key features:
  * 1. Initialization: Defines the structure and validation for the initial event that starts the orchestration.
+ *    The init schema is automatically intersected with OrchestrationInitEventBaseSchema.
  * 2. Completion: Specifies the event type and data emitted when the orchestration process concludes.
  * 3. Type Safety: Utilizes TypeScript generics to ensure type consistency across the contract definition.
  * 4. Runtime Validation: Employs Zod schemas for robust runtime type checking and data validation.
  *
+ * Base Schema:
+ * The OrchestrationInitEventBaseSchema is automatically intersected with the user-provided init schema.
+ * This base schema includes essential fields for orchestration, such as:
+ * - parentSubject$$: Identifies the subject of the parent process or event in the ArvoEvent system.
+ *
  * This contract serves as a crucial component in maintaining consistency and type safety
  * throughout the orchestration process, from initiation to completion.
  *
  * @param param - The configuration object for creating the contract.
  * @param param.uri - The URI for the contract.
- * @param param.name - The name of the contract (must be alphanumeric).
+ * @param param.name - The name of the contract (must be lowercase alphanumeric with dots).
  * @param param.schema - The schema object containing init and complete Zod schemas.
- * @param param.schema.init - The Zod schema for initialization.
+ * @param param.schema.init - The Zod schema for initialization (will be intersected with OrchestrationInitEventBaseSchema).
  * @param param.schema.complete - The Zod schema for completion.
  *
- * @throws {Error} Throws an error if the name is not alphanumeric.
+ * @throws {Error} Throws an error if the name is not lowercase alphanumeric with dots.
  *
  * @returns Returns a new ArvoOrchestratorContract instance with the specified parameters.
+ *
+ * @example
+ * ```typescript
+ * import { createArvoOrchestratorContract } from 'arvo-core'
+ * import { z } from 'zod'
+ *
+ * const contract = createArvoOrchestratorContract({
+ *   uri: '#/example/contract',
+ *   name: 'rag.orchestrator',
+ *   schema: {
+ *     init: z.object({
+ *       request: z.string(),
+ *       vectorStore: z.string(),
+ *       llm: z.string()
+ *     }),
+ *     complete: z.object({
+ *       response: z.string()
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * In this example, the actual init schema will be an intersection of the provided schema
+ * and the OrchestrationInitEventBaseSchema, ensuring all necessary fields are included.
  */
 var createArvoOrchestratorContract = function (param) {
     if (!isLowerAlphanumeric(param.name)) {
@@ -58,12 +90,12 @@ var createArvoOrchestratorContract = function (param) {
         uri: param.uri,
         init: {
             type: typegen_1.ArvoOrchestratorEventTypeGen.init(param.name),
-            schema: param.schema.init,
+            schema: zod_1.z.intersection(schema_1.OrchestrationInitEventBaseSchema, param.schema.init),
         },
         complete: {
             type: typegen_1.ArvoOrchestratorEventTypeGen.complete(param.name),
             schema: param.schema.complete,
-        }
+        },
     });
 };
 exports.createArvoOrchestratorContract = createArvoOrchestratorContract;

package/dist/ArvoOrchestratorContract/schema.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+/**
+ * Defines the base schema for orchestrator acceptance in the context of ArvoEvents.
+ * This schema is used to validate and type-check the minimal required fields
+ * for an orchestrator to accept a task or event.
+ */
+export declare const OrchestrationInitEventBaseSchema: z.ZodObject<{
+    parentSubject$$: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    parentSubject$$: string | null;
+}, {
+    parentSubject$$: string | null;
+}>;

package/dist/ArvoOrchestratorContract/schema.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrchestrationInitEventBaseSchema = void 0;
+var zod_1 = require("zod");
+var utils_1 = require("../utils");
+/**
+ * Defines the base schema for orchestrator acceptance in the context of ArvoEvents.
+ * This schema is used to validate and type-check the minimal required fields
+ * for an orchestrator to accept a task or event.
+ */
+exports.OrchestrationInitEventBaseSchema = zod_1.z
+    .object({
+    parentSubject$$: zod_1.z
+        .string()
+        .min(1, 'The parent subject must not be an empty string')
+        .nullable()
+        .describe((0, utils_1.cleanString)("\n    Identifies the subject of the parent process or event in the ArvoEvent system.\n    \n    Purpose:\n    1. Enables the orchestrator to return its final output to the initiating process or orchestrator.\n    2. Maintains the event chain and process hierarchy in a distributed system.\n    3. Facilitates proper event routing and traceability.\n    \n    Usage:\n    - For non-root processes: Set to the subject of the parent process/orchestrator.\n    - For root processes/orchestrations: Must be set to null.\n    \n    This field aligns with the ArvoEvent 'subject' field, which is a URI identifying the event's subject.\n    It plays a crucial role in distributed tracing, debugging, and maintaining system coherence.\n    \n    Example:\n    - Parent process subject: \"process/parent-id-123\"\n    - Child process parentSubject$$: \"process/parent-id-123\"\n    \n    Note: Ensure this value is a valid URI as per ArvoEvent specifications.\n  ")),
+});

package/dist/ArvoOrchestratorContract/typegen.js

@@ -3,7 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArvoOrchestratorEventTypeGen = void 0;
 exports.ArvoOrchestratorEventTypeGen = {
     __prefix: "arvo.orc",
-    init: function (name) { return "".concat(exports.ArvoOrchestratorEventTypeGen.__prefix, ".").concat(name); },
-    complete: function (name) { return "".concat(exports.ArvoOrchestratorEventTypeGen.init(name), ".done"); },
-    systemError: function (name) { return "sys.".concat(exports.ArvoOrchestratorEventTypeGen.init(name), ".error"); }
+    init: function (name) {
+        return "".concat(exports.ArvoOrchestratorEventTypeGen.__prefix, ".").concat(name);
+    },
+    complete: function (name) {
+        return "".concat(exports.ArvoOrchestratorEventTypeGen.init(name), ".done");
+    },
+    systemError: function (name) {
+        return "sys.".concat(exports.ArvoOrchestratorEventTypeGen.init(name), ".error");
+    },
 };

package/dist/index.d.ts

@@ -35,6 +35,7 @@ import { ArvoOrchestratorEventTypeGen } from './ArvoOrchestratorContract/typegen
  * @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.
+ * @property {z.ZodObject} OrchestrationInitEventBaseSchema - The base schema for the orchestrator init events.
  */
 declare const ArvoEventSchemas: {
     CloudEventContextSchema: import("zod").ZodObject<{
@@ -93,5 +94,12 @@ declare const ArvoEventSchemas: {
         traceparent: string | null;
         tracestate: string | null;
     }>;
+    OrchestrationInitEventBaseSchema: import("zod").ZodObject<{
+        parentSubject$$: import("zod").ZodNullable<import("zod").ZodString>;
+    }, "strip", import("zod").ZodTypeAny, {
+        parentSubject$$: string | null;
+    }, {
+        parentSubject$$: string | null;
+    }>;
 };
-export { ArvoEventHttpConfig, ArvoEventHttp, ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchemas, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, OpenTelemetryHeaders, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, createArvoContract, ArvoContractValidators, ArvoContractRecord, IArvoContract, ResolveArvoContractRecord, ArvoContractLibrary, createArvoContractLibrary, ArvoEventFactory, createArvoEventFactory, ArvoErrorSchema, currentOpenTelemetryHeaders, OpenInference, OpenInferenceSpanKind, ArvoExecution, ArvoExecutionSpanKind, ArvoContractJSONSchema, ArvoOrchestrationSubject, ArvoOrchestrationSubjectContentSchema, ArvoOrchestratorVersionSchema, ArvoOrchestrationSubjectContent, ArvoOrchestratorVersion, InferArvoEvent, InferArvoContract, InferArvoContractType, createArvoOrchestratorContract, ArvoOrchestratorContract, ICreateArvoOrchestratorContract, IArvoOrchestratorContract, InferArvoOrchestratorContract, ArvoOrchestratorEventTypeGen };
+export { ArvoEventHttpConfig, ArvoEventHttp, ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchemas, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, OpenTelemetryHeaders, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, createArvoContract, ArvoContractValidators, ArvoContractRecord, IArvoContract, ResolveArvoContractRecord, ArvoContractLibrary, createArvoContractLibrary, ArvoEventFactory, createArvoEventFactory, ArvoErrorSchema, currentOpenTelemetryHeaders, OpenInference, OpenInferenceSpanKind, ArvoExecution, ArvoExecutionSpanKind, ArvoContractJSONSchema, ArvoOrchestrationSubject, ArvoOrchestrationSubjectContentSchema, ArvoOrchestratorVersionSchema, ArvoOrchestrationSubjectContent, ArvoOrchestratorVersion, InferArvoEvent, InferArvoContract, InferArvoContractType, createArvoOrchestratorContract, ArvoOrchestratorContract, ICreateArvoOrchestratorContract, IArvoOrchestratorContract, InferArvoOrchestratorContract, ArvoOrchestratorEventTypeGen, };

package/dist/index.js

@@ -55,6 +55,7 @@ var ArvoOrchestratorContract_1 = __importDefault(require("./ArvoOrchestratorCont
 exports.ArvoOrchestratorContract = ArvoOrchestratorContract_1.default;
 var typegen_1 = require("./ArvoOrchestratorContract/typegen");
 Object.defineProperty(exports, "ArvoOrchestratorEventTypeGen", { enumerable: true, get: function () { return typegen_1.ArvoOrchestratorEventTypeGen; } });
+var schema_4 = require("./ArvoOrchestratorContract/schema");
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.
@@ -62,6 +63,7 @@ Object.defineProperty(exports, "ArvoOrchestratorEventTypeGen", { enumerable: tru
  * @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.
+ * @property {z.ZodObject} OrchestrationInitEventBaseSchema - The base schema for the orchestrator init events.
  */
 var ArvoEventSchemas = {
     CloudEventContextSchema: schema_1.CloudEventContextSchema,
@@ -69,5 +71,6 @@ var ArvoEventSchemas = {
     ArvoDataSchema: schema_1.ArvoDataSchema,
     ArvoExtensionSchema: schema_1.ArvoExtensionSchema,
     OpenTelemetryExtensionSchema: schema_1.OpenTelemetryExtensionSchema,
+    OrchestrationInitEventBaseSchema: schema_4.OrchestrationInitEventBaseSchema,
 };
 exports.ArvoEventSchemas = ArvoEventSchemas;

package/package.json

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