arvo-core 1.2.3 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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
@@ -11,9 +11,9 @@ var __assign = (this && this.__assign) || function () {
11
11
  return __assign.apply(this, arguments);
12
12
  };
13
13
  Object.defineProperty(exports, "__esModule", { value: true });
14
- var validators_1 = require("./validators");
15
14
  var zod_to_json_schema_1 = require("zod-to-json-schema");
16
15
  var schema_1 = require("../schema");
16
+ var utils_1 = require("../utils");
17
17
  /**
18
18
  * ArvoContract class represents a contract with defined input and output schemas.
19
19
  * It provides methods for validating inputs and outputs based on the contract's specifications.
@@ -22,8 +22,7 @@ var schema_1 = require("../schema");
22
22
  *
23
23
  * @template TUri - The URI of the contract
24
24
  * @template TType - The accept type, defaults to string.
25
- * @template TAcceptSchema - The of the data which the contract bound can accept
26
- * @template TEmits - The type of records the contract bound handler emits.
25
+ * @template TVersion - The contract versions
27
26
  */
28
27
  var ArvoContract = /** @class */ (function () {
29
28
  /**
@@ -32,9 +31,9 @@ var ArvoContract = /** @class */ (function () {
32
31
  */
33
32
  function ArvoContract(params) {
34
33
  var _a;
35
- this._uri = validators_1.ArvoContractValidators.contract.uri.parse(params.uri);
36
- this._accepts = this._validateAccepts(params.accepts);
37
- this._emits = this._validateEmits(params.emits);
34
+ this._uri = params.uri;
35
+ this._type = params.type;
36
+ this._versions = params.versions;
38
37
  this.description = (_a = params.description) !== null && _a !== void 0 ? _a : null;
39
38
  }
40
39
  Object.defineProperty(ArvoContract.prototype, "uri", {
@@ -47,32 +46,60 @@ var ArvoContract = /** @class */ (function () {
47
46
  enumerable: false,
48
47
  configurable: true
49
48
  });
50
- Object.defineProperty(ArvoContract.prototype, "accepts", {
49
+ Object.defineProperty(ArvoContract.prototype, "type", {
51
50
  /**
52
- * Gets the type and schema of the event that the contact
53
- * bound handler listens to.
51
+ * Get the type of the event the handler
52
+ * bound to the contract accepts
54
53
  */
55
54
  get: function () {
56
- return this._accepts;
55
+ return this._type;
57
56
  },
58
57
  enumerable: false,
59
58
  configurable: true
60
59
  });
61
- Object.defineProperty(ArvoContract.prototype, "emits", {
60
+ Object.defineProperty(ArvoContract.prototype, "versions", {
62
61
  /**
63
- * Gets all event types and schemas that can be emitted by the
64
- * contract bound handler.
62
+ * Gets the version of the contract
65
63
  */
66
64
  get: function () {
67
- return __assign({}, this._emits);
65
+ return this._versions;
68
66
  },
69
67
  enumerable: false,
70
68
  configurable: true
71
69
  });
70
+ Object.defineProperty(ArvoContract.prototype, "latestVersion", {
71
+ /**
72
+ * Get the latest version of the contract
73
+ */
74
+ get: function () {
75
+ return Object.keys(this._versions).sort(function (a, b) {
76
+ return (0, utils_1.compareSemanticVersions)(b, a);
77
+ })[0];
78
+ },
79
+ enumerable: false,
80
+ configurable: true
81
+ });
82
+ /**
83
+ * Gets the type and schema of the event that the contact
84
+ * bound handler listens to.
85
+ */
86
+ ArvoContract.prototype.accepts = function (version) {
87
+ return {
88
+ type: this._type,
89
+ schema: this._versions[version].accepts,
90
+ };
91
+ };
92
+ /**
93
+ * Gets all event types and schemas that can be emitted by the
94
+ * contract bound handler.
95
+ */
96
+ ArvoContract.prototype.emits = function (version) {
97
+ return __assign({}, this._versions[version].emits);
98
+ };
72
99
  Object.defineProperty(ArvoContract.prototype, "systemError", {
73
100
  get: function () {
74
101
  return {
75
- type: "sys.".concat(this._accepts.type, ".error"),
102
+ type: "sys.".concat(this._type, ".error"),
76
103
  schema: schema_1.ArvoErrorSchema,
77
104
  };
78
105
  },
@@ -83,16 +110,18 @@ var ArvoContract = /** @class */ (function () {
83
110
  * Validates the contract bound handler's input/ accept event against the
84
111
  * contract's accept schema.
85
112
  * @template U - The type of the input to validate.
113
+ * @template V - The version to use
114
+ * @param version - The version to use
86
115
  * @param type - The type of the input event.
87
116
  * @param input - The input data to validate.
88
117
  * @returns The validation result.
89
118
  * @throws If the accept type is not found in the contract.
90
119
  */
91
- ArvoContract.prototype.validateAccepts = function (type, input) {
92
- if (type !== this._accepts.type) {
93
- throw new Error("Accept type \"".concat(type, "\" not found in contract"));
120
+ ArvoContract.prototype.validateAccepts = function (version, type, input) {
121
+ if (type !== this._type) {
122
+ throw new Error("Accept type \"".concat(type, "\" for version \"").concat(version, "\" not found in contract \"").concat(this._uri, "\""));
94
123
  }
95
- return this._accepts.schema.safeParse(input);
124
+ return this._versions[version].accepts.safeParse(input);
96
125
  };
97
126
  /**
98
127
  * Validates the contract bound handler's output/ emits against the
@@ -103,38 +132,14 @@ var ArvoContract = /** @class */ (function () {
103
132
  * @returns The validation result.
104
133
  * @throws If the emit type is not found in the contract.
105
134
  */
106
- ArvoContract.prototype.validateEmits = function (type, output) {
107
- var emit = this.emits[type];
135
+ ArvoContract.prototype.validateEmits = function (version, type, output) {
136
+ var _a, _b, _c;
137
+ var emit = (_c = (_b = (_a = this._versions) === null || _a === void 0 ? void 0 : _a[version]) === null || _b === void 0 ? void 0 : _b.emits) === null || _c === void 0 ? void 0 : _c[type];
108
138
  if (!emit) {
109
- throw new Error("Emit type \"".concat(type.toString(), "\" not found in contract"));
139
+ throw new Error("Emit type \"".concat(type.toString(), "\" for version \"").concat(version, "\" not found in contract \"").concat(this._uri, "\""));
110
140
  }
111
141
  return emit.safeParse(output);
112
142
  };
113
- /**
114
- * Validates the accepts record.
115
- * @param accepts - The accepts record to validate.
116
- * @returns The validated accepts record.
117
- * @private
118
- */
119
- ArvoContract.prototype._validateAccepts = function (accepts) {
120
- return {
121
- type: validators_1.ArvoContractValidators.record.type.parse(accepts.type),
122
- schema: accepts.schema,
123
- };
124
- };
125
- /**
126
- * Validates the emits records.
127
- * @param emits - The emits records to validate.
128
- * @returns The validated emits records.
129
- * @private
130
- */
131
- ArvoContract.prototype._validateEmits = function (emits) {
132
- Object.entries(emits).forEach(function (_a) {
133
- var key = _a[0];
134
- return validators_1.ArvoContractValidators.record.type.parse(key);
135
- });
136
- return emits;
137
- };
138
143
  /**
139
144
  * Exports the ArvoContract instance as a plain object conforming to the IArvoContract interface.
140
145
  * This method can be used to serialize the contract or to create a new instance with the same parameters.
@@ -144,12 +149,9 @@ var ArvoContract = /** @class */ (function () {
144
149
  ArvoContract.prototype.export = function () {
145
150
  return {
146
151
  uri: this._uri,
152
+ type: this._type,
147
153
  description: this.description,
148
- accepts: {
149
- type: this._accepts.type,
150
- schema: this._accepts.schema,
151
- },
152
- emits: __assign({}, this._emits),
154
+ versions: this._versions,
153
155
  };
154
156
  };
155
157
  /**
@@ -164,18 +166,25 @@ var ArvoContract = /** @class */ (function () {
164
166
  * - emits: An array of objects, each containing an emitted event type and its JSON Schema representation
165
167
  */
166
168
  ArvoContract.prototype.toJsonSchema = function () {
169
+ var _this = this;
167
170
  return {
168
171
  uri: this._uri,
169
172
  description: this.description,
170
- accepts: {
171
- type: this._accepts.type,
172
- schema: (0, zod_to_json_schema_1.zodToJsonSchema)(this._accepts.schema),
173
- },
174
- emits: Object.entries(this._emits).map(function (_a) {
175
- var key = _a[0], value = _a[1];
173
+ versions: Object.entries(this._versions).map(function (_a) {
174
+ var version = _a[0], contract = _a[1];
176
175
  return ({
177
- type: key,
178
- schema: (0, zod_to_json_schema_1.zodToJsonSchema)(value),
176
+ version: version,
177
+ accepts: {
178
+ type: _this._type,
179
+ schema: (0, zod_to_json_schema_1.zodToJsonSchema)(contract.accepts),
180
+ },
181
+ emits: Object.entries(contract.emits).map(function (_a) {
182
+ var key = _a[0], value = _a[1];
183
+ return ({
184
+ type: key,
185
+ schema: (0, zod_to_json_schema_1.zodToJsonSchema)(value),
186
+ });
187
+ }),
179
188
  });
180
189
  }),
181
190
  };
@@ -1,59 +1,73 @@
1
1
  import { z } from 'zod';
2
2
  import zodToJsonSchema from 'zod-to-json-schema';
3
+ import { ArvoSemanticVersion } from '../types';
3
4
  /**
4
- * Represents a record in an Arvo contract.
5
- * @template TType - The type of the record, defaults to string.
6
- * @template TSchema - The Zod schema for the record, defaults to any Zod type.
5
+ * Represents a record in an Arvo contract, containing a type identifier and its validation schema.
6
+ *
7
+ * @template TType - The type identifier for the record, must be a string type
8
+ * @template TSchema - The Zod schema used for validation, must be a Zod type
7
9
  */
8
10
  export type ArvoContractRecord<TType extends string = string, TSchema extends z.ZodTypeAny = z.ZodTypeAny> = {
9
- /** The type identifier for the record */
11
+ /** The type identifier for this record */
10
12
  type: TType;
11
- /** The Zod schema used for validating the record */
13
+ /** The Zod schema used for validating data associated with this record */
12
14
  schema: TSchema;
13
15
  };
14
16
  /**
15
- * Interface for an Arvo contract.
17
+ * Defines the structure of an Arvo contract, including its identifier, type, and versioned schemas.
16
18
  *
17
- * @template TUri - The URI of the contract
18
- * @template TType - The accept type, defaults to string.
19
- * @template TAcceptSchema - The of the data which the contract bound can accept
20
- * @template TEmits - The type of records the contract bound handler emits.
19
+ * @template TUri - The unique URI identifier for the contract
20
+ * @template TType - The event type that the contract's handler accepts
21
+ * @template TVersions - A record of versioned schemas, mapping semantic versions to their accept/emit schemas
21
22
  */
22
- export interface IArvoContract<TUri extends string = string, TType extends string = string, TAcceptSchema extends z.ZodTypeAny = z.ZodTypeAny, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> {
23
- /** The unique identifier for the contract */
23
+ export interface IArvoContract<TUri extends string = string, TType extends string = string, TVersions extends Record<ArvoSemanticVersion, {
24
+ accepts: z.ZodTypeAny;
25
+ emits: Record<string, z.ZodTypeAny>;
26
+ }> = Record<ArvoSemanticVersion, {
27
+ accepts: z.ZodTypeAny;
28
+ emits: Record<string, z.ZodTypeAny>;
29
+ }>> {
30
+ /** The unique URI identifier for this contract */
24
31
  uri: TUri;
25
- /** The record type that the contract accepts */
26
- accepts: ArvoContractRecord<TType, TAcceptSchema>;
27
- /** An array of record types that the contract can emit */
28
- emits: TEmits;
29
- /** (Optional) The description of the contract or its handler */
32
+ /** The event type that this contract's handler accepts */
33
+ type: TType;
34
+ /** Optional description providing context about the contract or its handler */
30
35
  description?: string | null;
36
+ /** A record mapping semantic versions to their corresponding schemas */
37
+ versions: TVersions;
31
38
  }
32
39
  /**
33
- * Resolves the inferred type of an ArvoContractRecord's schema.
34
- * @template T - The ArvoContractRecord to resolve.
40
+ * Utility type that resolves the inferred TypeScript type from an ArvoContractRecord's schema.
41
+ *
42
+ * @template T - The ArvoContractRecord whose schema type should be inferred
35
43
  */
36
44
  export type ResolveArvoContractRecord<T extends ArvoContractRecord> = z.infer<T['schema']>;
37
45
  /**
38
- * Represents the JSON Schema representation of an ArvoContract.
46
+ * Represents the JSON Schema representation of an ArvoContract, used for serialization
47
+ * and documentation purposes. This structure follows the JSON Schema specification.
39
48
  */
40
49
  export type ArvoContractJSONSchema = {
41
- /** The unique identifier (URI) of the contract */
50
+ /** The unique URI identifier for the contract */
42
51
  uri: string;
43
- /** The description of the contract (null if not provided) */
52
+ /** The human-readable description of the contract */
44
53
  description: string | null;
45
- /** The accepted input schema for the contract */
46
- accepts: {
47
- /** The type identifier for the accepted input */
48
- type: string;
49
- /** The JSON Schema representation of the accepted input schema */
50
- schema: ReturnType<typeof zodToJsonSchema>;
51
- };
52
- /** An array of emitted event schemas for the contract */
53
- emits: {
54
- /** The type identifier for the emitted event */
55
- type: string;
56
- /** The JSON Schema representation of the emitted event schema */
57
- schema: ReturnType<typeof zodToJsonSchema>;
54
+ /** Array of versioned schemas for this contract */
55
+ versions: {
56
+ /** The semantic version identifier for this schema version */
57
+ version: ArvoSemanticVersion;
58
+ /** The schema for accepted inputs in this version */
59
+ accepts: {
60
+ /** The type identifier for accepted inputs */
61
+ type: string;
62
+ /** JSON Schema representation of the input validation schema */
63
+ schema: ReturnType<typeof zodToJsonSchema>;
64
+ };
65
+ /** Array of schemas for events that can be emitted in this version */
66
+ emits: {
67
+ /** The type identifier for the emitted event */
68
+ type: string;
69
+ /** JSON Schema representation of the event validation schema */
70
+ schema: ReturnType<typeof zodToJsonSchema>;
71
+ }[];
58
72
  }[];
59
73
  };
@@ -19,20 +19,20 @@ export declare const CloudEventContextSchema: z.ZodObject<{
19
19
  datacontenttype: z.ZodDefault<z.ZodEffects<z.ZodString, string, string>>;
20
20
  dataschema: z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>;
21
21
  }, "strip", z.ZodTypeAny, {
22
+ type: string;
22
23
  id: string;
23
24
  time: string;
24
25
  source: string;
25
26
  specversion: "1.0";
26
- type: string;
27
27
  subject: string;
28
28
  datacontenttype: string;
29
29
  dataschema: string | null;
30
30
  }, {
31
+ type: string;
31
32
  id: string;
32
33
  time: string;
33
34
  source: string;
34
35
  specversion: string;
35
- type: string;
36
36
  subject: string;
37
37
  dataschema: string | null;
38
38
  datacontenttype?: string | undefined;
@@ -1,15 +1,45 @@
1
1
  import ArvoEventFactory from '.';
2
2
  import ArvoContract from '../ArvoContract';
3
- import { z } from 'zod';
3
+ import { ArvoSemanticVersion } from '../types';
4
+ import ArvoEvent from '../ArvoEvent';
4
5
  /**
5
- * Creates a ArvoEventFactory instance based on the provided contract.
6
+ * Creates an ArvoEventFactory instance for a given contract.
7
+ * This is the recommended way to instantiate an ArvoEventFactory.
6
8
  *
7
- * @template TUri - The URI of the contract
8
- * @template TType - The accept type, defaults to string.
9
- * @template TAcceptSchema - The type of the data which the contract bound can accept
10
- * @template TEmits - The type of records the contract bound handler emits.
9
+ * @template TContract - The type of ArvoContract to create a factory for
11
10
  *
12
- * @param contract - The ArvoContract to base the events on.
13
- * @returns An instance of ContractualArvoEventFactory.
11
+ * @param contract - The ArvoContract instance to base the factory on
12
+ * @returns A new ArvoEventFactory instance bound to the provided contract
13
+ *
14
+ * @example
15
+ * ```typescript
16
+ * const contract = createArvoContract({...});
17
+ * const factory = createArvoEventFactory(contract);
18
+ * ```
19
+ */
20
+ export declare const createArvoEventFactory: <TContract extends ArvoContract>(contract: TContract) => ArvoEventFactory<TContract>;
21
+ /**
22
+ * Parses an event data schema string or ArvoEvent object to extract the URI and version.
23
+ * The schema is expected to be in the format "uri/version" where version follows semantic versioning.
24
+ *
25
+ * @param data - The input to parse, either a string containing the schema or an ArvoEvent object
26
+ * If an ArvoEvent is provided, its dataschema property will be used
27
+ *
28
+ * @returns An object containing the parsed URI and semantic version, or null if parsing fails
29
+ * The URI is everything before the last "/" and the version is everything after
30
+ *
31
+ * @example
32
+ * // String input
33
+ * parseEventDataSchema("com.example/schema/1.0.0")
34
+ * // Returns: { uri: "com.example/schema", version: "1.0.0" }
35
+ *
36
+ * // ArvoEvent input
37
+ * parseEventDataSchema({ dataschema: "com.example/schema/1.0.0" })
38
+ * // Returns: { uri: "com.example/schema", version: "1.0.0" }
39
+ *
40
+ * @throws Will not throw errors directly, but converts any parsing errors to spans
14
41
  */
15
- export declare const createArvoEventFactory: <TUri extends string = string, TType extends string = string, TAcceptSchema extends z.ZodTypeAny = z.ZodTypeAny, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>>(contract: ArvoContract<TUri, TType, TAcceptSchema, TEmits>) => ArvoEventFactory<TUri, TType, TAcceptSchema, TEmits>;
42
+ export declare const parseEventDataSchema: (data: string | ArvoEvent) => {
43
+ uri: string;
44
+ version: ArvoSemanticVersion;
45
+ } | null;
@@ -3,18 +3,60 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.createArvoEventFactory = void 0;
6
+ exports.parseEventDataSchema = exports.createArvoEventFactory = void 0;
7
7
  var _1 = __importDefault(require("."));
8
+ var OpenTelemetry_1 = require("../OpenTelemetry");
9
+ var schema_1 = require("../schema");
8
10
  /**
9
- * Creates a ArvoEventFactory instance based on the provided contract.
11
+ * Creates an ArvoEventFactory instance for a given contract.
12
+ * This is the recommended way to instantiate an ArvoEventFactory.
10
13
  *
11
- * @template TUri - The URI of the contract
12
- * @template TType - The accept type, defaults to string.
13
- * @template TAcceptSchema - The type of the data which the contract bound can accept
14
- * @template TEmits - The type of records the contract bound handler emits.
14
+ * @template TContract - The type of ArvoContract to create a factory for
15
15
  *
16
- * @param contract - The ArvoContract to base the events on.
17
- * @returns An instance of ContractualArvoEventFactory.
16
+ * @param contract - The ArvoContract instance to base the factory on
17
+ * @returns A new ArvoEventFactory instance bound to the provided contract
18
+ *
19
+ * @example
20
+ * ```typescript
21
+ * const contract = createArvoContract({...});
22
+ * const factory = createArvoEventFactory(contract);
23
+ * ```
18
24
  */
19
25
  var createArvoEventFactory = function (contract) { return new _1.default(contract); };
20
26
  exports.createArvoEventFactory = createArvoEventFactory;
27
+ /**
28
+ * Parses an event data schema string or ArvoEvent object to extract the URI and version.
29
+ * The schema is expected to be in the format "uri/version" where version follows semantic versioning.
30
+ *
31
+ * @param data - The input to parse, either a string containing the schema or an ArvoEvent object
32
+ * If an ArvoEvent is provided, its dataschema property will be used
33
+ *
34
+ * @returns An object containing the parsed URI and semantic version, or null if parsing fails
35
+ * The URI is everything before the last "/" and the version is everything after
36
+ *
37
+ * @example
38
+ * // String input
39
+ * parseEventDataSchema("com.example/schema/1.0.0")
40
+ * // Returns: { uri: "com.example/schema", version: "1.0.0" }
41
+ *
42
+ * // ArvoEvent input
43
+ * parseEventDataSchema({ dataschema: "com.example/schema/1.0.0" })
44
+ * // Returns: { uri: "com.example/schema", version: "1.0.0" }
45
+ *
46
+ * @throws Will not throw errors directly, but converts any parsing errors to spans
47
+ */
48
+ var parseEventDataSchema = function (data) {
49
+ var _a;
50
+ try {
51
+ var dataschema = typeof data === 'string' ? data : ((_a = data.dataschema) !== null && _a !== void 0 ? _a : '');
52
+ var items = dataschema.split('/');
53
+ var version = schema_1.ArvoSemanticVersionSchema.parse(items.pop());
54
+ var uri = items.join('/');
55
+ return { uri: uri, version: version };
56
+ }
57
+ catch (e) {
58
+ (0, OpenTelemetry_1.exceptionToSpan)(e);
59
+ return null;
60
+ }
61
+ };
62
+ exports.parseEventDataSchema = parseEventDataSchema;
@@ -2,53 +2,80 @@ import ArvoContract from '../ArvoContract';
2
2
  import { z } from 'zod';
3
3
  import { CreateArvoEvent } from '../ArvoEvent/types';
4
4
  import { ExecutionOpenTelemetryConfiguration } from '../OpenTelemetry/types';
5
+ import { ArvoSemanticVersion } from '../types';
5
6
  /**
6
- * A factory class for creating contractual ArvoEvents based on a given ArvoContract.
7
+ * Factory class for creating contractual ArvoEvents based on a given ArvoContract.
8
+ * This class handles the creation and validation of events according to contract specifications.
7
9
  *
8
- * @template TUri - The URI of the contract
9
- * @template TType - The accept type, defaults to string.
10
- * @template TAcceptSchema - The type of the data which the contract bound can accept
11
- * @template TEmits - The type of records the contract bound handler emits.
10
+ * @template TContract - The type of ArvoContract this factory is bound to
12
11
  */
13
- export default class ArvoEventFactory<TUri extends string = string, TType extends string = string, TAcceptSchema extends z.ZodTypeAny = z.ZodTypeAny, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> {
12
+ export default class ArvoEventFactory<TContract extends ArvoContract> {
14
13
  private readonly contract;
15
14
  /**
16
15
  * Creates an instance of ArvoEventFactory.
17
16
  *
18
17
  * @param contract - The ArvoContract to base the events on.
19
18
  */
20
- constructor(contract: ArvoContract<TUri, TType, TAcceptSchema, TEmits>);
19
+ constructor(contract: TContract);
21
20
  /**
22
- * Creates an ArvoEvent as per the accept record of the contract.
23
- *
24
- * @template TExtension - The type of extensions to add to the event.
25
- * @param event - The event to create. The field 'type' is automatically infered
26
- * @param [extensions] - Optional extensions to add to the event.
27
- * @param [opentelemetry] - Optional opentelemetry configuration object
28
- * @returns The created ArvoEvent as per the accept record of the contract.
29
- * @throws If the event data fails validation against the contract.
21
+ * Creates a validated ArvoEvent that matches the contract's accept specifications.
22
+ * This method ensures the created event conforms to the contract's input schema.
23
+ *
24
+ * @template V - The semantic version of the contract to use
25
+ * @template TExtension - Additional custom properties to include in the event
26
+ *
27
+ * @param event - The event configuration object
28
+ * @param event.version - The semantic version of the contract to use
29
+ * @param event.data - The event payload that must conform to the contract's accept schema
30
+ * @param [extensions] - Optional additional properties to include in the event
31
+ * @param [opentelemetry] - Optional OpenTelemetry configuration for tracing
32
+ *
33
+ * @returns A validated ArvoEvent instance conforming to the contract's accept specifications
34
+ *
35
+ * @throws {Error} If event data validation fails against the contract schema
36
+ * @throws {Error} If OpenTelemetry operations fail
30
37
  */
31
- accepts<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TAcceptSchema>, TType>, 'type' | 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TAcceptSchema>, TExtension, TType>;
38
+ accepts<V extends ArvoSemanticVersion & keyof TContract['versions'], TExtension extends Record<string, any>>(event: {
39
+ version: V;
40
+ } & Omit<CreateArvoEvent<z.input<TContract['versions'][V]['accepts']>, TContract['type']>, 'type' | 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TContract["versions"][V]["accepts"]>, TExtension, TContract["type"]>;
32
41
  /**
33
- * Creates an ArvoEvent as per one of the emits record in the contract.
34
- *
35
- * @template U - The specific event type from TEmits.
36
- * @template TExtension - The type of extensions to add to the event.
37
- * @param event - The event to create.
38
- * @param [extensions] - Optional extensions to add to the event.
39
- * @param [opentelemetry] - Optional opentelemetry configuration object
40
- * @returns The created ArvoEvent as per one of the emits records of the contract.
41
- * @throws If the event data fails validation against the contract.
42
+ * Creates a validated ArvoEvent that matches one of the contract's emit specifications.
43
+ * This method ensures the created event conforms to the contract's output schema.
44
+ *
45
+ * @template V - The semantic version of the contract to use
46
+ * @template U - The specific emit event type from the contract
47
+ * @template TExtension - Additional custom properties to include in the event
48
+ *
49
+ * @param event - The event configuration object
50
+ * @param event.version - The semantic version of the contract to use
51
+ * @param event.type - The type of emit event to create
52
+ * @param event.data - The event payload that must conform to the contract's emit schema
53
+ * @param [extensions] - Optional additional properties to include in the event
54
+ * @param [opentelemetry] - Optional OpenTelemetry configuration for tracing
55
+ *
56
+ * @returns A validated ArvoEvent instance conforming to the contract's emit specifications
57
+ *
58
+ * @throws {Error} If event data validation fails against the contract schema
59
+ * @throws {Error} If the specified emit type doesn't exist in the contract
60
+ * @throws {Error} If OpenTelemetry operations fail
42
61
  */
43
- emits<U extends keyof TEmits & string, TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TEmits[U]>, U>, 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TEmits[U]>, TExtension, U>;
62
+ emits<V extends ArvoSemanticVersion & keyof TContract['versions'], U extends string & keyof TContract['versions'][V]['emits'], TExtension extends Record<string, any>>(event: {
63
+ version: V;
64
+ } & Omit<CreateArvoEvent<z.input<TContract['versions'][V]['emits'][U]>, U>, 'datacontenttype' | 'dataschema'>, extensions?: TExtension, opentelemetry?: ExecutionOpenTelemetryConfiguration): import("..").ArvoEvent<z.TypeOf<TContract["versions"][V]["emits"][U]>, TExtension, U>;
44
65
  /**
45
- * Creates a system error ArvoEvent.
66
+ * Creates a system error ArvoEvent for handling and reporting errors within the system.
67
+ *
68
+ * @template TExtension - Additional custom properties to include in the error event
69
+ *
70
+ * @param event - The error event configuration object
71
+ * @param event.error - The Error instance to be converted into an event
72
+ * @param [extensions] - Optional additional properties to include in the event
73
+ * @param [opentelemetry] - Optional OpenTelemetry configuration for tracing
74
+ *
75
+ * @returns A system error ArvoEvent containing the error details
46
76
  *
47
- * @template TExtension - The type of extensions to add to the event.
48
- * @param event - The event to create, including the error.
49
- * @param [extensions] - Optional extensions to add to the event.
50
- * @param [opentelemetry] - Optional opentelemtry configuration object
51
- * @returns The created system error ArvoEvent.
77
+ * @throws {Error} If event creation fails
78
+ * @throws {Error} If OpenTelemetry operations fail
52
79
  */
53
80
  systemError<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<any, any>, 'data' | 'type' | 'datacontenttype' | 'dataschema'> & {
54
81
  error: Error;
@@ -56,5 +83,5 @@ export default class ArvoEventFactory<TUri extends string = string, TType extend
56
83
  errorMessage: string;
57
84
  errorName: string;
58
85
  errorStack: string | null;
59
- }, TExtension, `sys.${TType}.error`>;
86
+ }, TExtension, `sys.${TContract["type"]}.error`>;
60
87
  }