arvo-core 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -28,3 +28,7 @@
 
 - Updates to OpenTelemetry functions
 
+## [1.0.8] - 2024-09-01
+
+- Added support for system error in ArvoContract
+

package/README.md

@@ -51,6 +51,7 @@ At its core, Arvo has only three main data structures:
 - [ArvoEvent](src/ArvoEvent/README.md) aims to provide a extendible variant of the open-source CloudEvent spec-ed object to define all the event in the system.
 - [ArvoContract](src/ArvoContract/README.md) is a basic class to define and impose contracts between services, ensuring trust in decoupled systems during build and development.
 - [ArvoContractLibrary](src/ArvoContractLibrary/README.md) is a utility class designed to manage and access multiple ArvoContract instances efficiently.
+- `ArvoErrorSchema` is the recommeded zod schema for all the errors in the ArvoEvents
 
 ## Utilities
 

package/dist/ArvoContract/helpers.d.ts

@@ -1,13 +1,9 @@
 import { IArvoContract } from './types';
 import ArvoContract from '.';
-import { CreateArvoEvent } from '../ArvoEvent/types';
-import { TelemetryContext } from '../OpenTelemetry/types';
-import { ArvoContractRecord } from './types';
-import { z } from 'zod';
 /**
  * Infers the ArvoContract type from a given IArvoContract.
  */
-export type InferArvoContract<T> = T extends IArvoContract<infer U, infer V, infer W> ? ArvoContract<U, V, W> : never;
+export type InferArvoContract<T> = T extends IArvoContract<infer S, infer U, infer V, infer W> ? ArvoContract<S, U, V, W> : never;
 /**
  * Creates an ArvoContract instance from the given contract specification.
  *
@@ -15,10 +11,11 @@ export type InferArvoContract<T> = T extends IArvoContract<infer U, infer V, inf
  * with proper type inference.
  *
  * @template TContract - The type of the contract specification.
- * @param {TContract} contractSpec - The contract specification object.
+ *
+ * @param contractSpec - The contract specification object.
  *   This should include the URI, accepts, and emits properties as defined in IArvoContract.
  *
- * @returns {InferArvoContract<TContract>} The created ArvoContract instance.
+ * @returns The created ArvoContract instance.
  *   The returned type is inferred from the input contract specification.
  *
  * @example
@@ -28,48 +25,9 @@ export type InferArvoContract<T> = T extends IArvoContract<infer U, infer V, inf
  *     type: 'com.example.input',
  *     schema: z.object({ name: z.string() }),
  *   },
- *   emits: [
- *     {
- *       type: 'com.example.output',
- *       schema: z.object({ result: z.number() }),
- *     },
- *   ],
+ *   emits: {
+ *     'com.example.output': z.object({ result: z.number() }),
+ *   },
  * });
  */
 export declare const createArvoContract: <const TContract extends IArvoContract>(contract: TContract) => InferArvoContract<TContract>;
-/**
- * Creates a contractual ArvoEvent factory based on the provided contract.
- *
- * @template T - The type of the contract.
- * @template TAccepts - The type of record the contract bound handler accepts, defaults to ArvoContractRecord.
- * @template TEmits - The type of records the contract bound handler emits.
- * @param {ArvoContract<T, TAccepts, TEmits>} contract - The ArvoContract to base the events on.
- * @returns {Object} An object with 'accepts' and 'emits' methods for creating events.
- */
-export declare const contractualArvoEventFactory: <T extends string = string, TAccepts extends ArvoContractRecord = ArvoContractRecord, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>>(contract: ArvoContract<T, TAccepts, TEmits>) => {
-    /**
-     * Creates an ArvoEvent as per the accept record of the contract.
-     *
-     * @template TExtension - The type of extensions to add to the event.
-     * @param {CreateArvoEvent<z.infer<TAccepts['schema']>, TAccepts['type']>} event - The event to create.
-     * @param {TExtension} [extensions] - Optional extensions to add to the event.
-     * @param {TelemetryContext} [telemetry] - Optional telemetry context for tracing.
-     * @returns The created ArvoEvent as per the accept record of the contract.
-     * @throws {Error} If the event data fails validation against the contract.
-     */
-    accepts: <TExtension extends Record<string, any>>(event: CreateArvoEvent<z.infer<TAccepts["schema"]>, TAccepts["type"]>, extensions?: TExtension, telemetry?: TelemetryContext) => import("..").ArvoEvent<z.TypeOf<z.TypeOf<TAccepts["schema"]>>, TExtension, string>;
-    /**
-     * Creates an ArvoEvent as per one of the emits record in the contract.
-     *
-     * @template U - The specific event type from TEmits.
-     * @template TExtension - The type of extensions to add to the event.
-     * @param {CreateArvoEvent<z.infer<Extract<TEmits, { type: U }>['schema']>, U>} event - The event to create.
-     * @param {TExtension} [extensions] - Optional extensions to add to the event.
-     * @param {TelemetryContext} [telemetry] - Optional telemetry context for tracing.
-     * @returns The created ArvoEvent as per one of the emits records of the contract.
-     * @throws {Error} If the event data fails validation against the contract.
-     */
-    emits: <U extends keyof TEmits & string, TExtension extends Record<string, any>>(event: CreateArvoEvent<z.infer<TEmits[U]>, U>, extensions?: TExtension, telemetry?: TelemetryContext) => import("..").ArvoEvent<z.TypeOf<Extract<TEmits, {
-        type: U;
-    }>["schema"]>, TExtension, string>;
-};

package/dist/ArvoContract/helpers.js

@@ -1,23 +1,10 @@
 "use strict";
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.contractualArvoEventFactory = exports.createArvoContract = void 0;
+exports.createArvoContract = void 0;
 var _1 = __importDefault(require("."));
-var helpers_1 = require("../ArvoEvent/helpers");
-var OpenTelemetry_1 = require("../OpenTelemetry");
 /**
  * Creates an ArvoContract instance from the given contract specification.
  *
@@ -25,10 +12,11 @@ var OpenTelemetry_1 = require("../OpenTelemetry");
  * with proper type inference.
  *
  * @template TContract - The type of the contract specification.
- * @param {TContract} contractSpec - The contract specification object.
+ *
+ * @param contractSpec - The contract specification object.
  *   This should include the URI, accepts, and emits properties as defined in IArvoContract.
  *
- * @returns {InferArvoContract<TContract>} The created ArvoContract instance.
+ * @returns The created ArvoContract instance.
  *   The returned type is inferred from the input contract specification.
  *
  * @example
@@ -38,66 +26,12 @@ var OpenTelemetry_1 = require("../OpenTelemetry");
  *     type: 'com.example.input',
  *     schema: z.object({ name: z.string() }),
  *   },
- *   emits: [
- *     {
- *       type: 'com.example.output',
- *       schema: z.object({ result: z.number() }),
- *     },
- *   ],
+ *   emits: {
+ *     'com.example.output': z.object({ result: z.number() }),
+ *   },
  * });
  */
 var createArvoContract = function (contract) {
     return new _1.default(contract);
 };
 exports.createArvoContract = createArvoContract;
-/**
- * Creates a contractual ArvoEvent factory based on the provided contract.
- *
- * @template T - The type of the contract.
- * @template TAccepts - The type of record the contract bound handler accepts, defaults to ArvoContractRecord.
- * @template TEmits - The type of records the contract bound handler emits.
- * @param {ArvoContract<T, TAccepts, TEmits>} contract - The ArvoContract to base the events on.
- * @returns {Object} An object with 'accepts' and 'emits' methods for creating events.
- */
-var contractualArvoEventFactory = function (contract) { return ({
-    /**
-     * Creates an ArvoEvent as per the accept record of the contract.
-     *
-     * @template TExtension - The type of extensions to add to the event.
-     * @param {CreateArvoEvent<z.infer<TAccepts['schema']>, TAccepts['type']>} event - The event to create.
-     * @param {TExtension} [extensions] - Optional extensions to add to the event.
-     * @param {TelemetryContext} [telemetry] - Optional telemetry context for tracing.
-     * @returns The created ArvoEvent as per the accept record of the contract.
-     * @throws {Error} If the event data fails validation against the contract.
-     */
-    accepts: function (event, extensions, telemetry) {
-        return (0, OpenTelemetry_1.createOtelSpan)(telemetry || 'ArvoEvent Creation Tracer', 'contractualArvoEventFactory.accepts', {}, function () {
-            var validationResult = contract.validateInput(event.type, event.data);
-            if (!validationResult.success) {
-                throw new Error("Accept Event data validation failed: ".concat(validationResult.error.message));
-            }
-            return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { data: validationResult.data }), extensions, telemetry);
-        });
-    },
-    /**
-     * Creates an ArvoEvent as per one of the emits record in the contract.
-     *
-     * @template U - The specific event type from TEmits.
-     * @template TExtension - The type of extensions to add to the event.
-     * @param {CreateArvoEvent<z.infer<Extract<TEmits, { type: U }>['schema']>, U>} event - The event to create.
-     * @param {TExtension} [extensions] - Optional extensions to add to the event.
-     * @param {TelemetryContext} [telemetry] - Optional telemetry context for tracing.
-     * @returns The created ArvoEvent as per one of the emits records of the contract.
-     * @throws {Error} If the event data fails validation against the contract.
-     */
-    emits: function (event, extensions, telemetry) {
-        return (0, OpenTelemetry_1.createOtelSpan)(telemetry || 'ArvoEvent Creation Tracer', 'contractualArvoEventFactory.emits', {}, function () {
-            var validationResult = contract.validateOutput(event.type, event.data);
-            if (!validationResult.success) {
-                throw new Error("Emit Event data validation failed: ".concat(validationResult.error.message));
-            }
-            return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { data: validationResult.data }), extensions, telemetry);
-        });
-    },
-}); };
-exports.contractualArvoEventFactory = contractualArvoEventFactory;

package/dist/ArvoContract/index.d.ts

@@ -1,16 +1,18 @@
 import { z } from 'zod';
 import { ArvoContractRecord, IArvoContract } from './types';
+import { ArvoErrorSchema } from '../schema';
 /**
  * ArvoContract class represents a contract with defined input and output schemas.
  * It provides methods for validating inputs and outputs based on the contract's specifications.
  * An event handler can be bound to it so the this contract may impose the types
  * on inputs and outputs of it
  *
- * @template TUri - The URI type, defaults to string.
- * @template TAccepts - The type of record the contract bound handler accepts, defaults to ArvoContractRecord.
+ * @template TUri - The URI of the contract
+ * @template TType - The accept type, defaults to string.
+ * @template TAcceptSchema - The of the data which the contract bound can accept
  * @template TEmits - The type of records the contract bound handler emits.
  */
-export default class ArvoContract<TUri extends string = string, TAccepts extends ArvoContractRecord = ArvoContractRecord, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> {
+export default class ArvoContract<TUri extends string = string, TType extends string = string, TAcceptSchema extends z.ZodTypeAny = z.ZodTypeAny, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> {
     private readonly _uri;
     private readonly _accepts;
     private readonly _emits;
@@ -18,60 +20,57 @@ export default class ArvoContract<TUri extends string = string, TAccepts extends
     readonly description: string | null;
     /**
      * Creates an instance of ArvoContract.
-     * @param {IArvoContract<TUri, TAccepts, TEmits>} params - The contract parameters.
+     * @param params - The contract parameters.
      */
-    constructor(params: IArvoContract<TUri, TAccepts, TEmits>);
+    constructor(params: IArvoContract<TUri, TType, TAcceptSchema, TEmits>);
     /**
      * Gets the URI of the contract.
-     * @returns {T} The contract's URI.
      */
     get uri(): TUri;
     /**
      * Gets the type and schema of the event that the contact
      * bound handler listens to.
-     * @returns {TAccepts} The frozen accepts object.
      */
-    get accepts(): TAccepts;
+    get accepts(): ArvoContractRecord<TType, TAcceptSchema>;
     /**
      * Gets all event types and schemas that can be emitted by the
      * contract bound handler.
-     *
-     * @returns {TEmits} A record of all emitted events.
      */
     get emits(): TEmits;
+    get systemError(): ArvoContractRecord<`sys.${TType}.error`, typeof ArvoErrorSchema>;
     /**
      * Validates the contract bound handler's input against the
      * contract's accept schema.
      * @template U - The type of the input to validate.
-     * @param {TAccepts['type']} type - The type of the input event.
-     * @param {U} input - The input data to validate.
-     * @returns {z.SafeParseReturnType<U, z.infer<TAccepts['schema']>>} The validation result.
-     * @throws {Error} If the accept type is not found in the contract.
+     * @param type - The type of the input event.
+     * @param input - The input data to validate.
+     * @returns The validation result.
+     * @throws If the accept type is not found in the contract.
      */
-    validateInput<U>(type: TAccepts['type'], input: U): z.SafeParseReturnType<U, z.infer<TAccepts['schema']>>;
+    validateInput<U>(type: TType, input: U): z.SafeParseReturnType<U, z.infer<TAcceptSchema>>;
     /**
      * Validates the contract bound handler's output against the
      * contract's emit schema.
      * @template U - The type of the output to validate.
-     * @param {U} type - The type of the output event.
-     * @param {unknown} output - The output data to validate.
-     * @returns {z.SafeParseReturnType<unknown, z.infer<Extract<TEmits, { type: U }>['schema']>>} The validation result.
-     * @throws {Error} If the emit type is not found in the contract.
+     * @param type - The type of the output event.
+     * @param output - The output data to validate.
+     * @returns The validation result.
+     * @throws If the emit type is not found in the contract.
      */
     validateOutput<U extends keyof TEmits>(type: U, output: unknown): z.SafeParseReturnType<unknown, z.infer<Extract<TEmits, {
         type: U;
     }>['schema']>>;
     /**
      * Validates the accepts record.
-     * @param {TAccepts} accepts - The accepts record to validate.
-     * @returns {TAccepts} The validated accepts record.
+     * @param accepts - The accepts record to validate.
+     * @returns The validated accepts record.
      * @private
      */
     private validateAccepts;
     /**
      * Validates the emits records.
-     * @param {TEmits} emits - The emits records to validate.
-     * @returns {TEmits} The validated emits records.
+     * @param emits - The emits records to validate.
+     * @returns The validated emits records.
      * @private
      */
     private validateEmits;
@@ -79,15 +78,15 @@ export default class ArvoContract<TUri extends string = string, TAccepts extends
      * Exports the ArvoContract instance as a plain object conforming to the IArvoContract interface.
      * This method can be used to serialize the contract or to create a new instance with the same parameters.
      *
-     * @returns {IArvoContract<TUri, TAccepts, TEmits>} An object representing the contract, including its URI, accepts, and emits properties.
+     * @returns An object representing the contract, including its URI, accepts, and emits properties.
      */
-    export(): IArvoContract<TUri, TAccepts, TEmits>;
+    export(): IArvoContract<TUri, TType, TAcceptSchema, TEmits>;
     /**
      * Converts the ArvoContract instance to a JSON Schema representation.
      * This method provides a way to represent the contract's structure and validation rules
      * in a format that conforms to the JSON Schema specification.
      *
-     * @returns {Object} An object representing the contract in JSON Schema format, including:
+     * @returns An object representing the contract in JSON Schema format, including:
      *   - uri: The contract's URI
      *   - description: The contract's description (if available)
      *   - accepts: An object containing the accepted input type and its JSON Schema representation
@@ -97,7 +96,7 @@ export default class ArvoContract<TUri extends string = string, TAccepts extends
         uri: TUri;
         description: string | null;
         accepts: {
-            type: string;
+            type: TType;
             schema: import("zod-to-json-schema").JsonSchema7Type & {
                 $schema?: string | undefined;
                 definitions?: {

package/dist/ArvoContract/index.js

@@ -14,32 +14,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var zod_1 = require("zod");
 var validators_1 = require("./validators");
 var zod_to_json_schema_1 = require("zod-to-json-schema");
+var schema_1 = require("../schema");
 /**
  * ArvoContract class represents a contract with defined input and output schemas.
  * It provides methods for validating inputs and outputs based on the contract's specifications.
  * An event handler can be bound to it so the this contract may impose the types
  * on inputs and outputs of it
  *
- * @template TUri - The URI type, defaults to string.
- * @template TAccepts - The type of record the contract bound handler accepts, defaults to ArvoContractRecord.
+ * @template TUri - The URI of the contract
+ * @template TType - The accept type, defaults to string.
+ * @template TAcceptSchema - The of the data which the contract bound can accept
  * @template TEmits - The type of records the contract bound handler emits.
  */
 var ArvoContract = /** @class */ (function () {
     /**
      * Creates an instance of ArvoContract.
-     * @param {IArvoContract<TUri, TAccepts, TEmits>} params - The contract parameters.
+     * @param params - The contract parameters.
      */
     function ArvoContract(params) {
         this._uri = validators_1.ArvoContractValidators.contract.uri.parse(params.uri);
         this._accepts = this.validateAccepts(params.accepts);
         this._emits = this.validateEmits(params.emits);
         this.description = params.description || null;
-        Object.freeze(this);
     }
     Object.defineProperty(ArvoContract.prototype, "uri", {
         /**
          * Gets the URI of the contract.
-         * @returns {T} The contract's URI.
          */
         get: function () {
             return this._uri;
@@ -51,10 +51,9 @@ var ArvoContract = /** @class */ (function () {
         /**
          * Gets the type and schema of the event that the contact
          * bound handler listens to.
-         * @returns {TAccepts} The frozen accepts object.
          */
         get: function () {
-            return Object.freeze(this._accepts);
+            return this._accepts;
         },
         enumerable: false,
         configurable: true
@@ -63,8 +62,6 @@ var ArvoContract = /** @class */ (function () {
         /**
          * Gets all event types and schemas that can be emitted by the
          * contract bound handler.
-         *
-         * @returns {TEmits} A record of all emitted events.
          */
         get: function () {
             return __assign({}, this._emits);
@@ -72,14 +69,24 @@ var ArvoContract = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(ArvoContract.prototype, "systemError", {
+        get: function () {
+            return {
+                type: "sys.".concat(this._accepts.type, ".error"),
+                schema: schema_1.ArvoErrorSchema,
+            };
+        },
+        enumerable: false,
+        configurable: true
+    });
     /**
      * Validates the contract bound handler's input against the
      * contract's accept schema.
      * @template U - The type of the input to validate.
-     * @param {TAccepts['type']} type - The type of the input event.
-     * @param {U} input - The input data to validate.
-     * @returns {z.SafeParseReturnType<U, z.infer<TAccepts['schema']>>} The validation result.
-     * @throws {Error} If the accept type is not found in the contract.
+     * @param type - The type of the input event.
+     * @param input - The input data to validate.
+     * @returns The validation result.
+     * @throws If the accept type is not found in the contract.
      */
     ArvoContract.prototype.validateInput = function (type, input) {
         if (type !== this._accepts.type) {
@@ -91,10 +98,10 @@ var ArvoContract = /** @class */ (function () {
      * Validates the contract bound handler's output against the
      * contract's emit schema.
      * @template U - The type of the output to validate.
-     * @param {U} type - The type of the output event.
-     * @param {unknown} output - The output data to validate.
-     * @returns {z.SafeParseReturnType<unknown, z.infer<Extract<TEmits, { type: U }>['schema']>>} The validation result.
-     * @throws {Error} If the emit type is not found in the contract.
+     * @param type - The type of the output event.
+     * @param output - The output data to validate.
+     * @returns The validation result.
+     * @throws If the emit type is not found in the contract.
      */
     ArvoContract.prototype.validateOutput = function (type, output) {
         var emit = this.emits[type];
@@ -105,8 +112,8 @@ var ArvoContract = /** @class */ (function () {
     };
     /**
      * Validates the accepts record.
-     * @param {TAccepts} accepts - The accepts record to validate.
-     * @returns {TAccepts} The validated accepts record.
+     * @param accepts - The accepts record to validate.
+     * @returns The validated accepts record.
      * @private
      */
     ArvoContract.prototype.validateAccepts = function (accepts) {
@@ -117,8 +124,8 @@ var ArvoContract = /** @class */ (function () {
     };
     /**
      * Validates the emits records.
-     * @param {TEmits} emits - The emits records to validate.
-     * @returns {TEmits} The validated emits records.
+     * @param emits - The emits records to validate.
+     * @returns The validated emits records.
      * @private
      */
     ArvoContract.prototype.validateEmits = function (emits) {
@@ -126,13 +133,13 @@ var ArvoContract = /** @class */ (function () {
             var key = _a[0];
             return validators_1.ArvoContractValidators.record.type.parse(key);
         });
-        return Object.freeze(emits);
+        return emits;
     };
     /**
      * Exports the ArvoContract instance as a plain object conforming to the IArvoContract interface.
      * This method can be used to serialize the contract or to create a new instance with the same parameters.
      *
-     * @returns {IArvoContract<TUri, TAccepts, TEmits>} An object representing the contract, including its URI, accepts, and emits properties.
+     * @returns An object representing the contract, including its URI, accepts, and emits properties.
      */
     ArvoContract.prototype.export = function () {
         return {
@@ -150,7 +157,7 @@ var ArvoContract = /** @class */ (function () {
      * This method provides a way to represent the contract's structure and validation rules
      * in a format that conforms to the JSON Schema specification.
      *
-     * @returns {Object} An object representing the contract in JSON Schema format, including:
+     * @returns An object representing the contract in JSON Schema format, including:
      *   - uri: The contract's URI
      *   - description: The contract's description (if available)
      *   - accepts: An object containing the accepted input type and its JSON Schema representation

package/dist/ArvoContract/types.d.ts

@@ -12,15 +12,17 @@ export type ArvoContractRecord<TType extends string = string, TSchema extends z.
 };
 /**
  * Interface for an Arvo contract.
- * @template TUri - The URI type, defaults to string.
- * @template TAccepts - The type of record the contract bound handler accepts, defaults to ArvoContractRecord.
+ *
+ * @template TUri - The URI of the contract
+ * @template TType - The accept type, defaults to string.
+ * @template TAcceptSchema - The of the data which the contract bound can accept
  * @template TEmits - The type of records the contract bound handler emits.
  */
-export interface IArvoContract<TUri extends string = string, TAccepts extends ArvoContractRecord = ArvoContractRecord, TEmits extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> {
+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>> {
     /** The unique identifier for the contract */
     uri: TUri;
     /** The record type that the contract accepts */
-    accepts: TAccepts;
+    accepts: ArvoContractRecord<TType, TAcceptSchema>;
     /** An array of record types that the contract can emit */
     emits: TEmits;
     /** (Optional) The description of the contract or its handler */

package/dist/ArvoEventFactory/helpers.d.ts

@@ -0,0 +1,15 @@
+import ArvoEventFactory from ".";
+import ArvoContract from "../ArvoContract";
+import { z } from 'zod';
+/**
+ * Creates a ArvoEventFactory instance based on the provided contract.
+ *
+ * @template TUri - The URI of the contract
+ * @template TType - The accept type, defaults to string.
+ * @template TAcceptSchema - The type of the data which the contract bound can accept
+ * @template TEmits - The type of records the contract bound handler emits.
+ *
+ * @param contract - The ArvoContract to base the events on.
+ * @returns An instance of ContractualArvoEventFactory.
+ */
+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>;

package/dist/ArvoEventFactory/helpers.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createArvoEventFactory = void 0;
+var _1 = __importDefault(require("."));
+/**
+ * Creates a ArvoEventFactory instance based on the provided contract.
+ *
+ * @template TUri - The URI of the contract
+ * @template TType - The accept type, defaults to string.
+ * @template TAcceptSchema - The type of the data which the contract bound can accept
+ * @template TEmits - The type of records the contract bound handler emits.
+ *
+ * @param contract - The ArvoContract to base the events on.
+ * @returns An instance of ContractualArvoEventFactory.
+ */
+var createArvoEventFactory = function (contract) { return new _1.default(contract); };
+exports.createArvoEventFactory = createArvoEventFactory;

package/dist/ArvoEventFactory/index.d.ts

@@ -0,0 +1,60 @@
+import ArvoContract from "../ArvoContract";
+import { z } from 'zod';
+import { CreateArvoEvent } from "../ArvoEvent/types";
+import { TelemetryContext } from "../OpenTelemetry/types";
+/**
+ * A factory class for creating contractual ArvoEvents based on a given ArvoContract.
+ *
+ * @template TUri - The URI of the contract
+ * @template TType - The accept type, defaults to string.
+ * @template TAcceptSchema - The type of the data which the contract bound can accept
+ * @template TEmits - The type of records the contract bound handler emits.
+ */
+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>> {
+    private contract;
+    /**
+     * Creates an instance of ContractualArvoEventFactory.
+     *
+     * @param contract - The ArvoContract to base the events on.
+     */
+    constructor(contract: ArvoContract<TUri, TType, TAcceptSchema, TEmits>);
+    /**
+     * Creates an ArvoEvent as per the accept record of the contract.
+     *
+     * @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 [telemetry] - Optional telemetry context for tracing.
+     * @returns The created ArvoEvent as per the accept record of the contract.
+     * @throws If the event data fails validation against the contract.
+     */
+    accepts<TExtension extends Record<string, any>>(event: CreateArvoEvent<z.infer<TAcceptSchema>, TType>, extensions?: TExtension, telemetry?: TelemetryContext): import("..").ArvoEvent<z.TypeOf<TAcceptSchema>, TExtension, string>;
+    /**
+     * Creates an ArvoEvent as per one of the emits record in the contract.
+     *
+     * @template U - The specific event type from TEmits.
+     * @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 [telemetry] - Optional telemetry context for tracing.
+     * @returns The created ArvoEvent as per one of the emits records of the contract.
+     * @throws If the event data fails validation against the contract.
+     */
+    emits<U extends keyof TEmits & string, TExtension extends Record<string, any>>(event: CreateArvoEvent<z.infer<TEmits[U]>, U>, extensions?: TExtension, telemetry?: TelemetryContext): import("..").ArvoEvent<z.TypeOf<z.TypeOf<TEmits[U]>>, TExtension, string>;
+    /**
+     * Creates a system error ArvoEvent.
+     *
+     * @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 [telemetry] - Optional telemetry context for tracing.
+     * @returns The created system error ArvoEvent.
+     */
+    systemError<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<any, any>, 'data' | 'type'> & {
+        error: Error;
+    }, extensions?: TExtension, telemetry?: TelemetryContext): import("..").ArvoEvent<{
+        errorName: string;
+        errorMessage: string;
+        errorStack: string | null;
+    }, TExtension, string>;
+}

package/dist/ArvoEventFactory/index.js

@@ -0,0 +1,108 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var helpers_1 = require("../ArvoEvent/helpers");
+var schema_1 = require("../ArvoEvent/schema");
+var OpenTelemetry_1 = require("../OpenTelemetry");
+/**
+ * A factory class for creating contractual ArvoEvents based on a given ArvoContract.
+ *
+ * @template TUri - The URI of the contract
+ * @template TType - The accept type, defaults to string.
+ * @template TAcceptSchema - The type of the data which the contract bound can accept
+ * @template TEmits - The type of records the contract bound handler emits.
+ */
+var ArvoEventFactory = /** @class */ (function () {
+    /**
+     * Creates an instance of ContractualArvoEventFactory.
+     *
+     * @param contract - The ArvoContract to base the events on.
+     */
+    function ArvoEventFactory(contract) {
+        this.contract = contract;
+    }
+    /**
+     * Creates an ArvoEvent as per the accept record of the contract.
+     *
+     * @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 [telemetry] - Optional telemetry context for tracing.
+     * @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, telemetry) {
+        var _this = this;
+        return (0, OpenTelemetry_1.createOtelSpan)(telemetry || 'ArvoEvent Creation Tracer', 'ContractualArvoEventFactory.accepts', {}, function () {
+            var validationResult = _this.contract.validateInput(event.type, event.data);
+            if (!validationResult.success) {
+                throw new Error("Accept Event data validation failed: ".concat(validationResult.error.message));
+            }
+            return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { datacontenttype: schema_1.ArvoDataContentType, dataschema: _this.contract.uri, data: validationResult.data }), extensions, telemetry);
+        });
+    };
+    /**
+     * Creates an ArvoEvent as per one of the emits record in the contract.
+     *
+     * @template U - The specific event type from TEmits.
+     * @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 [telemetry] - Optional telemetry context for tracing.
+     * @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, telemetry) {
+        var _this = this;
+        return (0, OpenTelemetry_1.createOtelSpan)(telemetry || 'ArvoEvent Creation Tracer', 'ContractualArvoEventFactory.emits', {}, function () {
+            var validationResult = _this.contract.validateOutput(event.type, event.data);
+            if (!validationResult.success) {
+                throw new Error("Emit Event data validation failed: ".concat(validationResult.error.message));
+            }
+            return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { datacontenttype: schema_1.ArvoDataContentType, dataschema: _this.contract.uri, data: validationResult.data }), extensions, telemetry);
+        });
+    };
+    /**
+     * Creates a system error ArvoEvent.
+     *
+     * @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 [telemetry] - Optional telemetry context for tracing.
+     * @returns The created system error ArvoEvent.
+     */
+    ArvoEventFactory.prototype.systemError = function (event, extensions, telemetry) {
+        var _this = this;
+        return (0, OpenTelemetry_1.createOtelSpan)(telemetry || 'ArvoEvent Creation Tracer', 'ContractualArvoEventFactory.systemError', {}, function () {
+            var error = event.error, _events = __rest(event, ["error"]);
+            return (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { type: "sys.".concat(_this.contract.accepts.type, ".error"), data: {
+                    errorName: error.name,
+                    errorMessage: error.message,
+                    errorStack: error.stack || null,
+                }, datacontenttype: schema_1.ArvoDataContentType, dataschema: _this.contract.uri }), extensions, telemetry);
+        });
+    };
+    return ArvoEventFactory;
+}());
+exports.default = ArvoEventFactory;

package/dist/OpenTelemetry/index.js

@@ -154,10 +154,11 @@ var createOtelSpan = function (telemetryContext, spanName, spanOptions, wrappedF
     var newSpan = activeTracer.startSpan(spanName, spanOptions, activeContext);
     try {
         var result = api_1.context.with(api_1.trace.setSpan(activeContext, newSpan), function () {
-            return wrappedFunction.call.apply(wrappedFunction, __spreadArray([thisArg, {
+            return wrappedFunction.call.apply(wrappedFunction, __spreadArray([thisArg,
+                {
                     span: newSpan,
                     tracer: activeTracer,
-                    carrier: (0, exports.getTelemetryCarrier)(newSpan, activeContext)
+                    carrier: (0, exports.getTelemetryCarrier)(newSpan, activeContext),
                 }], args, false));
         });
         newSpan.setStatus({

package/dist/index.d.ts

@@ -6,11 +6,14 @@ import { exceptionToSpan, logToSpan, getTelemetryContext, getTelemetryCarrier, c
 import { TelemetryCarrier, TelemetryContext, TelemetryLogLevel } from './OpenTelemetry/types';
 import { validateURI, cleanString } from './utils';
 import ArvoContract from './ArvoContract';
-import { createArvoContract, InferArvoContract, contractualArvoEventFactory } from './ArvoContract/helpers';
+import { createArvoContract, InferArvoContract } from './ArvoContract/helpers';
 import { ArvoContractValidators } from './ArvoContract/validators';
 import { ArvoContractRecord, IArvoContract, ResolveArvoContractRecord } from './ArvoContract/types';
 import ArvoContractLibrary from './ArvoContractLibrary';
 import { createArvoContractLibrary } from './ArvoContractLibrary/helpers';
+import ArvoEventFactory from './ArvoEventFactory';
+import { createArvoEventFactory } from './ArvoEventFactory/helpers';
+import { ArvoErrorSchema } from './schema';
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.
@@ -77,4 +80,4 @@ declare const ArvoEventSchemas: {
         tracestate: string | null;
     }>;
 };
-export { ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchemas, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, getTelemetryCarrier, getTelemetryContext, createOtelSpan, TelemetryCarrier, TelemetryContext, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, createArvoContract, ArvoContractValidators, ArvoContractRecord, InferArvoContract, IArvoContract, ResolveArvoContractRecord, ArvoContractLibrary, createArvoContractLibrary, contractualArvoEventFactory, };
+export { ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchemas, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, getTelemetryCarrier, getTelemetryContext, createOtelSpan, TelemetryCarrier, TelemetryContext, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, createArvoContract, ArvoContractValidators, ArvoContractRecord, InferArvoContract, IArvoContract, ResolveArvoContractRecord, ArvoContractLibrary, createArvoContractLibrary, ArvoEventFactory, createArvoEventFactory, ArvoErrorSchema };

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.contractualArvoEventFactory = exports.createArvoContractLibrary = exports.ArvoContractLibrary = exports.ArvoContractValidators = exports.createArvoContract = exports.ArvoContract = exports.cleanString = exports.validateURI = exports.OTelNull = exports.createOtelSpan = exports.getTelemetryContext = exports.getTelemetryCarrier = exports.logToSpan = exports.exceptionToSpan = exports.ArvoEventSchemas = exports.ArvoDataContentType = exports.createArvoEvent = exports.ArvoEvent = void 0;
+exports.ArvoErrorSchema = exports.createArvoEventFactory = exports.ArvoEventFactory = exports.createArvoContractLibrary = exports.ArvoContractLibrary = exports.ArvoContractValidators = exports.createArvoContract = exports.ArvoContract = exports.cleanString = exports.validateURI = exports.OTelNull = exports.createOtelSpan = exports.getTelemetryContext = exports.getTelemetryCarrier = exports.logToSpan = exports.exceptionToSpan = exports.ArvoEventSchemas = exports.ArvoDataContentType = exports.createArvoEvent = exports.ArvoEvent = void 0;
 var ArvoEvent_1 = __importDefault(require("./ArvoEvent"));
 exports.ArvoEvent = ArvoEvent_1.default;
 var schema_1 = require("./ArvoEvent/schema");
@@ -24,13 +24,18 @@ var ArvoContract_1 = __importDefault(require("./ArvoContract"));
 exports.ArvoContract = ArvoContract_1.default;
 var helpers_2 = require("./ArvoContract/helpers");
 Object.defineProperty(exports, "createArvoContract", { enumerable: true, get: function () { return helpers_2.createArvoContract; } });
-Object.defineProperty(exports, "contractualArvoEventFactory", { enumerable: true, get: function () { return helpers_2.contractualArvoEventFactory; } });
 var validators_1 = require("./ArvoContract/validators");
 Object.defineProperty(exports, "ArvoContractValidators", { enumerable: true, get: function () { return validators_1.ArvoContractValidators; } });
 var ArvoContractLibrary_1 = __importDefault(require("./ArvoContractLibrary"));
 exports.ArvoContractLibrary = ArvoContractLibrary_1.default;
 var helpers_3 = require("./ArvoContractLibrary/helpers");
 Object.defineProperty(exports, "createArvoContractLibrary", { enumerable: true, get: function () { return helpers_3.createArvoContractLibrary; } });
+var ArvoEventFactory_1 = __importDefault(require("./ArvoEventFactory"));
+exports.ArvoEventFactory = ArvoEventFactory_1.default;
+var helpers_4 = require("./ArvoEventFactory/helpers");
+Object.defineProperty(exports, "createArvoEventFactory", { enumerable: true, get: function () { return helpers_4.createArvoEventFactory; } });
+var schema_2 = require("./schema");
+Object.defineProperty(exports, "ArvoErrorSchema", { enumerable: true, get: function () { return schema_2.ArvoErrorSchema; } });
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.

package/dist/schema.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+/**
+ * Schema for Arvo error objects.
+ *
+ * This schema defines the structure of error objects used in the Arvo system.
+ * It uses Zod for runtime type checking and validation.
+ */
+export declare const ArvoErrorSchema: z.ZodObject<{
+    errorName: z.ZodString;
+    errorMessage: z.ZodString;
+    errorStack: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    errorName: string;
+    errorMessage: string;
+    errorStack: string | null;
+}, {
+    errorName: string;
+    errorMessage: string;
+    errorStack: string | null;
+}>;

package/dist/schema.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArvoErrorSchema = void 0;
+var zod_1 = require("zod");
+/**
+ * Schema for Arvo error objects.
+ *
+ * This schema defines the structure of error objects used in the Arvo system.
+ * It uses Zod for runtime type checking and validation.
+ */
+exports.ArvoErrorSchema = zod_1.z.object({
+    errorName: zod_1.z.string().describe('The name of the error.'),
+    errorMessage: zod_1.z.string().describe('A descriptive message for the error.'),
+    errorStack: zod_1.z.string().nullable().describe('The stack trace of the error.'),
+});

package/package.json

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