arvo-core 1.2.2 → 2.0.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (33) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/dist/ArvoContract/helpers.d.ts +119 -20
  3. package/dist/ArvoContract/helpers.js +150 -32
  4. package/dist/ArvoContract/index.d.ts +32 -26
  5. package/dist/ArvoContract/index.js +69 -60
  6. package/dist/ArvoContract/types.d.ts +49 -35
  7. package/dist/ArvoEvent/schema.d.ts +2 -2
  8. package/dist/ArvoEventFactory/helpers.d.ts +39 -9
  9. package/dist/ArvoEventFactory/helpers.js +50 -8
  10. package/dist/ArvoEventFactory/index.d.ts +60 -33
  11. package/dist/ArvoEventFactory/index.js +62 -36
  12. package/dist/ArvoOrchestrationSubject/index.d.ts +5 -4
  13. package/dist/ArvoOrchestrationSubject/index.js +2 -2
  14. package/dist/ArvoOrchestrationSubject/schema.d.ts +1 -2
  15. package/dist/ArvoOrchestrationSubject/schema.js +4 -11
  16. package/dist/ArvoOrchestrationSubject/type.d.ts +2 -12
  17. package/dist/ArvoOrchestratorContract/index.d.ts +62 -56
  18. package/dist/ArvoOrchestratorContract/index.js +99 -93
  19. package/dist/ArvoOrchestratorContract/types.d.ts +64 -71
  20. package/dist/index.d.ts +14 -18
  21. package/dist/index.js +12 -14
  22. package/dist/schema.d.ts +1 -0
  23. package/dist/schema.js +6 -1
  24. package/dist/types.d.ts +107 -81
  25. package/dist/utils.d.ts +21 -0
  26. package/dist/utils.js +33 -0
  27. package/package.json +1 -1
  28. package/dist/ArvoContractLibrary/helpers.d.ts +0 -10
  29. package/dist/ArvoContractLibrary/helpers.js +0 -22
  30. package/dist/ArvoContractLibrary/index.d.ts +0 -61
  31. package/dist/ArvoContractLibrary/index.js +0 -87
  32. package/dist/ArvoOrchestratorContract/helpers.d.ts +0 -67
  33. package/dist/ArvoOrchestratorContract/helpers.js +0 -101
@@ -21,18 +21,20 @@ var __rest = (this && this.__rest) || function (s, e) {
21
21
  }
22
22
  return t;
23
23
  };
24
+ var __importDefault = (this && this.__importDefault) || function (mod) {
25
+ return (mod && mod.__esModule) ? mod : { "default": mod };
26
+ };
24
27
  Object.defineProperty(exports, "__esModule", { value: true });
25
28
  var helpers_1 = require("../ArvoEvent/helpers");
26
29
  var schema_1 = require("../ArvoEvent/schema");
27
30
  var OpenTelemetry_1 = require("../OpenTelemetry");
28
31
  var api_1 = require("@opentelemetry/api");
32
+ var ArvoOrchestrationSubject_1 = __importDefault(require("../ArvoOrchestrationSubject"));
29
33
  /**
30
- * A factory class for creating contractual ArvoEvents based on a given ArvoContract.
34
+ * Factory class for creating contractual ArvoEvents based on a given ArvoContract.
35
+ * This class handles the creation and validation of events according to contract specifications.
31
36
  *
32
- * @template TUri - The URI of the contract
33
- * @template TType - The accept type, defaults to string.
34
- * @template TAcceptSchema - The type of the data which the contract bound can accept
35
- * @template TEmits - The type of records the contract bound handler emits.
37
+ * @template TContract - The type of ArvoContract this factory is bound to
36
38
  */
37
39
  var ArvoEventFactory = /** @class */ (function () {
38
40
  /**
@@ -44,31 +46,39 @@ var ArvoEventFactory = /** @class */ (function () {
44
46
  this.contract = contract;
45
47
  }
46
48
  /**
47
- * Creates an ArvoEvent as per the accept record of the contract.
49
+ * Creates a validated ArvoEvent that matches the contract's accept specifications.
50
+ * This method ensures the created event conforms to the contract's input schema.
51
+ *
52
+ * @template V - The semantic version of the contract to use
53
+ * @template TExtension - Additional custom properties to include in the event
54
+ *
55
+ * @param event - The event configuration object
56
+ * @param event.version - The semantic version of the contract to use
57
+ * @param event.data - The event payload that must conform to the contract's accept schema
58
+ * @param [extensions] - Optional additional properties to include in the event
59
+ * @param [opentelemetry] - Optional OpenTelemetry configuration for tracing
48
60
  *
49
- * @template TExtension - The type of extensions to add to the event.
50
- * @param event - The event to create. The field 'type' is automatically infered
51
- * @param [extensions] - Optional extensions to add to the event.
52
- * @param [opentelemetry] - Optional opentelemetry configuration object
53
- * @returns The created ArvoEvent as per the accept record of the contract.
54
- * @throws If the event data fails validation against the contract.
61
+ * @returns A validated ArvoEvent instance conforming to the contract's accept specifications
62
+ *
63
+ * @throws {Error} If event data validation fails against the contract schema
64
+ * @throws {Error} If OpenTelemetry operations fail
55
65
  */
56
66
  ArvoEventFactory.prototype.accepts = function (event, extensions, opentelemetry) {
57
67
  var _this = this;
58
68
  opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
59
69
  tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
60
70
  };
61
- var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, ">.accepts<").concat(this.contract.accepts.type, ">.create"));
71
+ var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, "/").concat(event.version, ">.accepts"));
62
72
  return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
63
73
  var _a, _b, _c, _d;
64
74
  span.setStatus({ code: api_1.SpanStatusCode.OK });
65
75
  var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
66
76
  try {
67
- var validationResult = _this.contract.validateAccepts(_this.contract.accepts.type, event.data);
77
+ var validationResult = _this.contract.validateAccepts(event.version, _this.contract.type, event.data);
68
78
  if (!validationResult.success) {
69
79
  throw new Error("Accept Event data validation failed: ".concat(validationResult.error.message));
70
80
  }
71
- 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: _this.contract.uri, data: validationResult.data }), extensions, opentelemetry);
81
+ 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.type, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(event.version), data: validationResult.data }), extensions, opentelemetry);
72
82
  }
73
83
  catch (error) {
74
84
  (0, OpenTelemetry_1.exceptionToSpan)(error);
@@ -84,32 +94,42 @@ var ArvoEventFactory = /** @class */ (function () {
84
94
  });
85
95
  };
86
96
  /**
87
- * Creates an ArvoEvent as per one of the emits record in the contract.
97
+ * Creates a validated ArvoEvent that matches one of the contract's emit specifications.
98
+ * This method ensures the created event conforms to the contract's output schema.
99
+ *
100
+ * @template V - The semantic version of the contract to use
101
+ * @template U - The specific emit event type from the contract
102
+ * @template TExtension - Additional custom properties to include in the event
103
+ *
104
+ * @param event - The event configuration object
105
+ * @param event.version - The semantic version of the contract to use
106
+ * @param event.type - The type of emit event to create
107
+ * @param event.data - The event payload that must conform to the contract's emit schema
108
+ * @param [extensions] - Optional additional properties to include in the event
109
+ * @param [opentelemetry] - Optional OpenTelemetry configuration for tracing
88
110
  *
89
- * @template U - The specific event type from TEmits.
90
- * @template TExtension - The type of extensions to add to the event.
91
- * @param event - The event to create.
92
- * @param [extensions] - Optional extensions to add to the event.
93
- * @param [opentelemetry] - Optional opentelemetry configuration object
94
- * @returns The created ArvoEvent as per one of the emits records of the contract.
95
- * @throws If the event data fails validation against the contract.
111
+ * @returns A validated ArvoEvent instance conforming to the contract's emit specifications
112
+ *
113
+ * @throws {Error} If event data validation fails against the contract schema
114
+ * @throws {Error} If the specified emit type doesn't exist in the contract
115
+ * @throws {Error} If OpenTelemetry operations fail
96
116
  */
97
117
  ArvoEventFactory.prototype.emits = function (event, extensions, opentelemetry) {
98
118
  var _this = this;
99
119
  opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
100
- tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)()
120
+ tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
101
121
  };
102
- var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, ">.emits<").concat(event.type, ">.create"));
122
+ var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, "/").concat(event.version, ">.emits<").concat(event.type, ">"));
103
123
  return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
104
124
  var _a, _b, _c, _d;
105
125
  span.setStatus({ code: api_1.SpanStatusCode.OK });
106
126
  var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
107
127
  try {
108
- var validationResult = _this.contract.validateEmits(event.type, event.data);
128
+ var validationResult = _this.contract.validateEmits(event.version, event.type, event.data);
109
129
  if (!validationResult.success) {
110
130
  throw new Error("Emit Event data validation failed: ".concat(validationResult.error.message));
111
131
  }
112
- 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, datacontenttype: schema_1.ArvoDataContentType, dataschema: _this.contract.uri, data: validationResult.data }), extensions, opentelemetry);
132
+ 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, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(event.version), data: validationResult.data }), extensions, opentelemetry);
113
133
  }
114
134
  catch (error) {
115
135
  (0, OpenTelemetry_1.exceptionToSpan)(error);
@@ -125,31 +145,37 @@ var ArvoEventFactory = /** @class */ (function () {
125
145
  });
126
146
  };
127
147
  /**
128
- * Creates a system error ArvoEvent.
148
+ * Creates a system error ArvoEvent for handling and reporting errors within the system.
149
+ *
150
+ * @template TExtension - Additional custom properties to include in the error event
151
+ *
152
+ * @param event - The error event configuration object
153
+ * @param event.error - The Error instance to be converted into an event
154
+ * @param [extensions] - Optional additional properties to include in the event
155
+ * @param [opentelemetry] - Optional OpenTelemetry configuration for tracing
156
+ *
157
+ * @returns A system error ArvoEvent containing the error details
129
158
  *
130
- * @template TExtension - The type of extensions to add to the event.
131
- * @param event - The event to create, including the error.
132
- * @param [extensions] - Optional extensions to add to the event.
133
- * @param [opentelemetry] - Optional opentelemtry configuration object
134
- * @returns The created system error ArvoEvent.
159
+ * @throws {Error} If event creation fails
160
+ * @throws {Error} If OpenTelemetry operations fail
135
161
  */
136
162
  ArvoEventFactory.prototype.systemError = function (event, extensions, opentelemetry) {
137
163
  var _this = this;
138
164
  opentelemetry = opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : {
139
165
  tracer: (0, OpenTelemetry_1.fetchOpenTelemetryTracer)(),
140
166
  };
141
- var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, ">.systemError<sys.").concat(this.contract.accepts.type, ".error>.create"));
167
+ var span = opentelemetry.tracer.startSpan("ArvoEventFactory<".concat(this.contract.uri, ">.systemError"));
142
168
  return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () {
143
169
  var _a, _b, _c, _d, _e;
144
170
  span.setStatus({ code: api_1.SpanStatusCode.OK });
145
171
  var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
146
172
  try {
147
173
  var error = event.error, _event = __rest(event, ["error"]);
148
- 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: "sys.".concat(_this.contract.accepts.type, ".error"), data: {
174
+ 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: "sys.".concat(_this.contract.type, ".error"), data: {
149
175
  errorName: error.name,
150
176
  errorMessage: error.message,
151
177
  errorStack: (_e = error.stack) !== null && _e !== void 0 ? _e : null,
152
- }, datacontenttype: schema_1.ArvoDataContentType, dataschema: _this.contract.uri }), extensions, opentelemetry);
178
+ }, datacontenttype: schema_1.ArvoDataContentType, dataschema: "".concat(_this.contract.uri, "/").concat(ArvoOrchestrationSubject_1.default.WildCardMachineVersion) }), extensions, opentelemetry);
153
179
  }
154
180
  catch (error) {
155
181
  (0, OpenTelemetry_1.exceptionToSpan)(error);
@@ -1,4 +1,5 @@
1
- import { ArvoOrchestratorVersion, ArvoOrchestrationSubjectContent } from './type';
1
+ import { ArvoOrchestrationSubjectContent } from './type';
2
+ import { ArvoSemanticVersion } from '../types';
2
3
  /**
3
4
  * Handles the creation and parsing of Arvo orchestration subjects.
4
5
  */
@@ -7,7 +8,7 @@ export default class ArvoOrchestrationSubject {
7
8
  * Represents a wildcard version number used when version matching is not required.
8
9
  * Format follows semantic versioning pattern.
9
10
  */
10
- static readonly WildCardMachineVersion: ArvoOrchestratorVersion;
11
+ static readonly WildCardMachineVersion: ArvoSemanticVersion;
11
12
  /**
12
13
  * Creates a new Arvo orchestration subject with basic required parameters.
13
14
  * This is a convenience method that wraps the more detailed {@link create} method.
@@ -42,7 +43,7 @@ export default class ArvoOrchestrationSubject {
42
43
  */
43
44
  static new(param: {
44
45
  orchestator: string;
45
- version: ArvoOrchestratorVersion | null;
46
+ version: ArvoSemanticVersion | null;
46
47
  initiator: string;
47
48
  meta?: Record<string, string>;
48
49
  }): string;
@@ -81,7 +82,7 @@ export default class ArvoOrchestrationSubject {
81
82
  */
82
83
  static from(param: {
83
84
  orchestator: string;
84
- version: ArvoOrchestratorVersion | null;
85
+ version: ArvoSemanticVersion | null;
85
86
  subject: string;
86
87
  meta?: Record<string, string>;
87
88
  }): string;
@@ -87,7 +87,7 @@ var ArvoOrchestrationSubject = /** @class */ (function () {
87
87
  id: (0, uuid_1.v4)(),
88
88
  initiator: param.initiator,
89
89
  },
90
- meta: (_b = param.meta) !== null && _b !== void 0 ? _b : {}
90
+ meta: (_b = param.meta) !== null && _b !== void 0 ? _b : {},
91
91
  });
92
92
  };
93
93
  /**
@@ -130,7 +130,7 @@ var ArvoOrchestrationSubject = /** @class */ (function () {
130
130
  initiator: parsedSubject.orchestrator.name,
131
131
  version: (_a = param.version) !== null && _a !== void 0 ? _a : ArvoOrchestrationSubject.WildCardMachineVersion,
132
132
  orchestator: param.orchestator,
133
- meta: __assign(__assign({}, ((_b = parsedSubject.meta) !== null && _b !== void 0 ? _b : {})), ((_c = param.meta) !== null && _c !== void 0 ? _c : {}))
133
+ meta: __assign(__assign({}, ((_b = parsedSubject.meta) !== null && _b !== void 0 ? _b : {})), ((_c = param.meta) !== null && _c !== void 0 ? _c : {})),
134
134
  });
135
135
  };
136
136
  /**
@@ -1,9 +1,8 @@
1
1
  import { z } from 'zod';
2
- export declare const ArvoOrchestratorVersionSchema: z.ZodEffects<z.ZodString, string, string>;
3
2
  export declare const ArvoOrchestrationSubjectContentSchema: z.ZodObject<{
4
3
  orchestrator: z.ZodObject<{
5
4
  name: z.ZodEffects<z.ZodString, string, string>;
6
- version: z.ZodEffects<z.ZodString, string, string>;
5
+ version: z.ZodString;
7
6
  }, "strip", z.ZodTypeAny, {
8
7
  name: string;
9
8
  version: string;
@@ -1,14 +1,9 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.ArvoOrchestrationSubjectContentSchema = exports.ArvoOrchestratorVersionSchema = void 0;
3
+ exports.ArvoOrchestrationSubjectContentSchema = void 0;
4
4
  var zod_1 = require("zod");
5
5
  var utils_1 = require("../utils");
6
- // Zod schema for ArvoOchestratorVersion
7
- exports.ArvoOrchestratorVersionSchema = zod_1.z
8
- .string()
9
- .regex(/^\d+\.\d+\.\d+$/, 'Invalid version format')
10
- .refine(function (value) { return !value.includes(';'); }, 'Version must not contain semicolon')
11
- .describe('Semantic version of the Arvo Orchestrator in the format X.Y.Z');
6
+ var schema_1 = require("../schema");
12
7
  // Zod schema for ArvoOrchestrationSubjectContent
13
8
  exports.ArvoOrchestrationSubjectContentSchema = zod_1.z
14
9
  .object({
@@ -19,7 +14,7 @@ exports.ArvoOrchestrationSubjectContentSchema = zod_1.z
19
14
  .regex(/^[a-z0-9]+(\.[a-z0-9]+)+\.[a-z0-9]+$/, 'Orchestrator name should be prefixed with a reverse-DNS name')
20
15
  .refine(function (value) { return !value.includes(';'); }, 'Orchestrator name must not contain semicolon')
21
16
  .describe('Name of the orchestrator'),
22
- version: exports.ArvoOrchestratorVersionSchema,
17
+ version: schema_1.ArvoSemanticVersionSchema,
23
18
  })
24
19
  .describe('Information about the orchestrator'),
25
20
  execution: zod_1.z
@@ -36,8 +31,6 @@ exports.ArvoOrchestrationSubjectContentSchema = zod_1.z
36
31
  .describe('Entity or process that initiated the execution'),
37
32
  })
38
33
  .describe('Details about the current execution'),
39
- meta: zod_1.z
40
- .record(zod_1.z.string(), zod_1.z.string())
41
- .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 "))
34
+ 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 ")),
42
35
  })
43
36
  .describe('Context information for Arvo orchestration');
@@ -1,14 +1,4 @@
1
- /**
2
- * Represents the version of the Arvo Orchestrator.
3
- *
4
- * @remark
5
- * The version follows the Semantic Versioning format: MAJOR.MINOR.PATCH
6
- * **Note**: The string must not contain ';'
7
- *
8
- * @example
9
- * "1.0.0", "2.3.1", "0.5.2"
10
- */
11
- export type ArvoOrchestratorVersion = `${number}.${number}.${number}`;
1
+ import { ArvoSemanticVersion } from '../types';
12
2
  /**
13
3
  * Represents the content for Arvo orchestration subject.
14
4
  * This type provides information about the orchestrator and the current execution.
@@ -32,7 +22,7 @@ export type ArvoOrchestrationSubjectContent = {
32
22
  /**
33
23
  * The version of the orchestrator.
34
24
  */
35
- version: ArvoOrchestratorVersion;
25
+ version: ArvoSemanticVersion;
36
26
  };
37
27
  /**
38
28
  * Details about the current execution.
@@ -1,68 +1,74 @@
1
1
  import { z } from 'zod';
2
- import ArvoContract from '../ArvoContract';
3
- import { IArvoOrchestratorContract } from './types';
2
+ import { ICreateArvoOrchestratorContract, ArvoOrchestratorContract } from './types';
3
+ import { ArvoSemanticVersion } from '../types';
4
4
  /**
5
- * Defines the contract for the Arvo Orchestrator, specifying accepted events and emitted events.
5
+ * Creates an ArvoOrchestratorContract with specified parameters.
6
6
  *
7
- * The ArvoOrchestratorContract is a specialized contract class designed to manage the lifecycle
8
- * of orchestration processes within the Arvo framework. It extends the base ArvoContract class
9
- * to provide specific functionality for orchestration scenarios.
7
+ * The ArvoOrchestratorContract is a specialized contract designed to manage the lifecycle
8
+ * of orchestration processes within the Arvo framework. It creates a contract with an init event
9
+ * type and a corresponding complete event type.
10
10
  *
11
11
  * Key features:
12
- * 1. Initialization: Defines the structure and validation for the initial event that starts the orchestration.
13
- * 2. Completion: Specifies the event type and data emitted when the orchestration process concludes.
14
- * 3. Type Safety: Utilizes TypeScript generics to ensure type consistency across the contract definition.
15
- * 4. Runtime Validation: Employs Zod schemas for robust runtime type checking and data validation.
12
+ * 1. Type Validation: Ensures the type parameter follows lowercase alphanumeric with dots format
13
+ * 2. Event Type Generation: Automatically generates init and complete event types based on the provided type
14
+ * 3. Schema Merging: Merges provided init schemas with the OrchestrationInitEventBaseSchema
15
+ * 4. Version Support: Handles multiple versions of the contract with their respective schemas
16
16
  *
17
- * This contract serves as a crucial component in maintaining consistency and type safety
18
- * throughout the orchestration process, from initiation to completion.
17
+ * @template TUri - The URI type for the contract
18
+ * @template TType - The type identifier for the contract events
19
+ * @template TVersions - Record of versions with their corresponding init and complete schemas
20
+ *
21
+ * @param param - Configuration object for the orchestrator contract
22
+ * @param param.uri - The URI that uniquely identifies this contract
23
+ * @param param.type - The base type identifier (must be lowercase alphanumeric with dots)
24
+ * @param param.versions - Record of version configurations
25
+ * @param param.versions[version].init - Zod schema for initialization event (merged with OrchestrationInitEventBaseSchema)
26
+ * @param param.versions[version].complete - Zod schema for completion event
27
+ *
28
+ * @throws {Error} If the type parameter contains invalid characters (must be lowercase alphanumeric with dots)
29
+ *
30
+ * @returns An ArvoOrchestratorContract instance configured with the specified parameters
19
31
  *
20
32
  * @example
21
33
  * ```typescript
22
- * import { createArvoOrchestratorContract } from 'arvo-core'
23
- * import { z } from 'zod'
24
- *
25
34
  * const contract = createArvoOrchestratorContract({
26
- * uri: '#/example/contract',
27
- * name: 'rag',
28
- * schema: {
29
- * init: z.object({
30
- * request: z.string()
31
- * vectorStore: z.string(),
32
- * llm: z.string()
33
- * }),
34
- * complete: z.object({
35
- * response: z.string()
36
- * })
37
- * }
38
- * })
35
+ * uri: '#/orchestrators/data/processor',
36
+ * type: 'data.processor',
37
+ * versions: {
38
+ * '1.0.0': {
39
+ * init: z.object({
40
+ * data: z.string(),
41
+ * options: z.object({
42
+ * format: z.string()
43
+ * })
44
+ * }),
45
+ * complete: z.object({
46
+ * processedData: z.string(),
47
+ * metadata: z.record(z.string())
48
+ * })
49
+ * },
50
+ * '1.1.0': {
51
+ * init: z.object({
52
+ * data: z.string(),
53
+ * options: z.object({
54
+ * format: z.string(),
55
+ * compression: z.boolean().optional()
56
+ * })
57
+ * }),
58
+ * complete: z.object({
59
+ * processedData: z.string(),
60
+ * metadata: z.record(z.string()),
61
+ * performance: z.object({
62
+ * duration: z.number(),
63
+ * bytesProcessed: z.number()
64
+ * })
65
+ * })
66
+ * }
67
+ * }
68
+ * });
39
69
  * ```
40
70
  */
41
- export default class ArvoOrchestratorContract<TUri extends string = string, TInitType extends string = string, TInit extends z.ZodTypeAny = z.ZodTypeAny, TCompleteType extends string = string, TComplete extends z.ZodTypeAny = z.ZodTypeAny> extends ArvoContract<TUri, TInitType, TInit, {
42
- [K in TCompleteType]: TComplete;
43
- }> {
44
- /**
45
- * Constructs a new ArvoOrchestratorContract instance.
46
- *
47
- * @param param - The configuration object for the contract.
48
- */
49
- constructor(param: IArvoOrchestratorContract<TUri, TInitType, TInit, TCompleteType, TComplete>);
50
- /**
51
- * Gets the initialization event configuration.
52
- *
53
- * @returns An object containing the type and schema for the initialization event.
54
- */
55
- get init(): {
56
- type: TInitType;
57
- schema: TInit;
58
- };
59
- /**
60
- * Gets the completion event configuration.
61
- *
62
- * @returns An object containing the type and schema for the completion event.
63
- */
64
- get complete(): {
65
- type: TCompleteType;
66
- schema: TComplete;
67
- };
68
- }
71
+ export declare const createArvoOrchestratorContract: <TUri extends string, TType extends string, TVersions extends Record<ArvoSemanticVersion, {
72
+ init: z.ZodObject<any, any, any>;
73
+ complete: z.ZodObject<any, any, any>;
74
+ }>>(param: ICreateArvoOrchestratorContract<TUri, TType, TVersions>) => ArvoOrchestratorContract<TUri, TType, TVersions>;