arvo-core 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -8,3 +8,11 @@
 
 - Update ArvoContract description
 
+## [1.0.3] - 2024-08-31
+
+- Making type in ArvoEvent a generic string for better type control
+
+## [0.0.4] - 2024-08-31
+
+- Created an event factory generator for creating contractually compliant events
+

package/README.md

@@ -1,5 +1,3 @@
-
-
 # Arvo
 
 ## What is Arvo
@@ -28,13 +26,11 @@ This core package defines primitive types and utility functions to help you quic
 
 ## Documentation & Resources
 
-
-| Source          | Link                   |
-| --------------- | ------------------------ 
-| Package         | https://www.npmjs.com/package/arvo-core?activeTab=readme  |
-| Github          | https://github.com/SaadAhmad123/arvo-core                 |
-| Documenation    | https://saadahmad123.github.io/arvo-core/index.html       |
-
+| Source       | Link                                                     |
+| ------------ | -------------------------------------------------------- |
+| Package      | https://www.npmjs.com/package/arvo-core?activeTab=readme |
+| Github       | https://github.com/SaadAhmad123/arvo-core                |
+| Documenation | https://saadahmad123.github.io/arvo-core/index.html      |
 
 ## Installation
 
@@ -43,11 +39,11 @@ You can install the core package via `npm` or `yarn`
 ```bash
 npm install arvo-core
 ```
+
 ```bash
 yarn add arvo-core
 ```
 
-
 ## Components
 
 At its core, Arvo has only three main data structures:
@@ -70,9 +66,15 @@ To start using Arvo in your project:
 
 - Install the package as shown in the Installation section.
 - Import the necessary components:
+
 ```javascript
-import { createArvoEvent, createArvoContract, createArvoContractLibrary } from 'arvo-core';
+import {
+  createArvoEvent,
+  createArvoContract,
+  createArvoContractLibrary,
+} from 'arvo-core';
 ```
+
 - Begin defining your events and contracts using the provided classes.
 
 ## License
@@ -80,4 +82,5 @@ import { createArvoEvent, createArvoContract, createArvoContractLibrary } from '
 This package is available under the MIT License. For more details, refer to the [LICENSE.md](LICENSE.md) file in the project repository.
 
 ## Change Logs
-For a detailed list of changes and updates, please refer to the [document](CHANGELOG.md) file.
+
+For a detailed list of changes and updates, please refer to the [document](CHANGELOG.md) file.

package/dist/ArvoContract/helpers.d.ts

@@ -1,5 +1,9 @@
 import { IArvoContract } from './types';
-import ArvoContract from '.';
+import ArvoContract, { ExtractEventType } 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.
  */
@@ -33,3 +37,41 @@ export type InferArvoContract<T> = T extends IArvoContract<infer U, infer V, inf
  * });
  */
 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 events the contract accepts.
+ * @template TEmits - The type of events the contract 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 createContractualArvoEvent: <T extends string = string, TAccepts extends ArvoContractRecord = ArvoContractRecord, TEmits extends ArvoContractRecord = ArvoContractRecord>(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 ExtractEventType<TEmits>, TExtension extends Record<string, any>>(event: CreateArvoEvent<z.infer<Extract<TEmits, {
+        type: U;
+    }>["schema"]>, U>, extensions?: TExtension, telemetry?: TelemetryContext) => import("..").ArvoEvent<z.TypeOf<Extract<TEmits, {
+        type: U;
+    }>["schema"]>, TExtension, string>;
+};

package/dist/ArvoContract/helpers.js

@@ -1,10 +1,23 @@
 "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.createArvoContract = void 0;
+exports.createContractualArvoEvent = 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.
  *
@@ -37,3 +50,54 @@ 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 events the contract accepts.
+ * @template TEmits - The type of events the contract 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 createContractualArvoEvent = 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', 'createArvoContractEvent.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', 'createArvoContractEvent.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.createContractualArvoEvent = createContractualArvoEvent;

package/dist/ArvoContract/index.d.ts

@@ -4,7 +4,7 @@ import { ArvoContractRecord, IArvoContract } from './types';
  * Extracts the event type from a given type T.
  * @template T - The type to extract the event type from.
  */
-type ExtractEventType<T> = T extends {
+export type ExtractEventType<T> = T extends {
     type: infer U;
 } ? U : never;
 /**
@@ -33,13 +33,13 @@ export default class ArvoContract<T extends string = string, TAccepts extends Ar
     get uri(): T;
     /**
      * Gets the accepted record type and schema.
-     * @returns {Readonly<TAccepts>} The frozen accepts object.
+     * @returns {TAccepts} The frozen accepts object.
      */
     get accepts(): TAccepts;
     /**
      * Gets all emitted event types and schemas as a readonly record.
      * Use this when you need to access all emitted events at once.
-     * @returns {Readonly<Record<ExtractEventType<TEmits>, TEmits>>} A frozen record of all emitted events.
+     * @returns {Record<ExtractEventType<TEmits>, TEmits>} A frozen record of all emitted events.
      */
     get emits(): Record<ExtractEventType<TEmits>, TEmits>;
     /**
@@ -47,7 +47,7 @@ export default class ArvoContract<T extends string = string, TAccepts extends Ar
      * Use this when you need to access a single emitted event by its type.
      * @template U - The type of the emit record to retrieve.
      * @param {U} type - The type of the emit record.
-     * @returns {Readonly<Extract<TEmits, { type: U }>>} The emit record.
+     * @returns {Extract<TEmits, { type: U }>} The emit record.
      * @throws {Error} If the emit type is not found in the contract.
      */
     getEmit<U extends ExtractEventType<TEmits>>(type: U): Extract<TEmits, {
@@ -128,4 +128,3 @@ export default class ArvoContract<T extends string = string, TAccepts extends Ar
         }[];
     };
 }
-export {};

package/dist/ArvoContract/index.js

@@ -37,7 +37,7 @@ var ArvoContract = /** @class */ (function () {
     Object.defineProperty(ArvoContract.prototype, "accepts", {
         /**
          * Gets the accepted record type and schema.
-         * @returns {Readonly<TAccepts>} The frozen accepts object.
+         * @returns {TAccepts} The frozen accepts object.
          */
         get: function () {
             return Object.freeze(this._accepts);
@@ -49,7 +49,7 @@ var ArvoContract = /** @class */ (function () {
         /**
          * Gets all emitted event types and schemas as a readonly record.
          * Use this when you need to access all emitted events at once.
-         * @returns {Readonly<Record<ExtractEventType<TEmits>, TEmits>>} A frozen record of all emitted events.
+         * @returns {Record<ExtractEventType<TEmits>, TEmits>} A frozen record of all emitted events.
          */
         get: function () {
             return Object.freeze(this._emits.reduce(function (acc, emit) {
@@ -66,7 +66,7 @@ var ArvoContract = /** @class */ (function () {
      * Use this when you need to access a single emitted event by its type.
      * @template U - The type of the emit record to retrieve.
      * @param {U} type - The type of the emit record.
-     * @returns {Readonly<Extract<TEmits, { type: U }>>} The emit record.
+     * @returns {Extract<TEmits, { type: U }>} The emit record.
      * @throws {Error} If the emit type is not found in the contract.
      */
     ArvoContract.prototype.getEmit = function (type) {

package/dist/ArvoEvent/helpers.d.ts

@@ -9,6 +9,7 @@ import { ArvoEventData, CloudEventExtension, CreateArvoEvent } from './types';
  *
  * @template TData - The type of the event data, extending ArvoEventData.
  * @template TExtension - The type of the cloud event extension, extending CloudEventExtension.
+ * @template TType - The type name of the event
  *
  * @param {CreateArvoEvent<TData>} event - The event data and metadata to create the ArvoEvent.
  * @param {TExtension} [extensions] - Optional cloud event extensions.
@@ -37,4 +38,4 @@ import { ArvoEventData, CloudEventExtension, CreateArvoEvent } from './types';
  *   telemetryContext
  * );
  */
-export declare const createArvoEvent: <TData extends ArvoEventData, TExtension extends CloudEventExtension>(event: CreateArvoEvent<TData>, extensions?: TExtension, telemetry?: TelemetryContext) => ArvoEvent<TData, TExtension>;
+export declare const createArvoEvent: <TData extends ArvoEventData, TExtension extends CloudEventExtension, TType extends string>(event: CreateArvoEvent<TData, TType>, extensions?: TExtension, telemetry?: TelemetryContext) => ArvoEvent<TData, TExtension>;

package/dist/ArvoEvent/helpers.js

@@ -17,6 +17,7 @@ var uuid_1 = require("uuid");
  *
  * @template TData - The type of the event data, extending ArvoEventData.
  * @template TExtension - The type of the cloud event extension, extending CloudEventExtension.
+ * @template TType - The type name of the event
  *
  * @param {CreateArvoEvent<TData>} event - The event data and metadata to create the ArvoEvent.
  * @param {TExtension} [extensions] - Optional cloud event extensions.
@@ -46,7 +47,7 @@ var uuid_1 = require("uuid");
  * );
  */
 var createArvoEvent = function (event, extensions, telemetry) {
-    return (0, OpenTelemetry_1.createOtelSpan)(telemetry || 'ArvoEvent Creation Tracer', 'Create ArvoEvent', {}, function (span) {
+    return (0, OpenTelemetry_1.createOtelSpan)(telemetry || 'ArvoEvent Creation Tracer', 'createArvoEvent', {}, function (span) {
         if (event.datacontenttype &&
             event.datacontenttype !== schema_1.ArvoDataContentType) {
             var warning = (0, utils_1.cleanString)("\n        Warning! The provided datacontenttype(=".concat(event.datacontenttype, ")\n        is not ArvoEvent compatible (=").concat(schema_1.ArvoDataContentType, "). There may \n        be some limited functionality.\n      "));

package/dist/ArvoEvent/index.d.ts

@@ -3,12 +3,13 @@ import { ArvoEventData, ArvoExtension, CloudEventContext, CloudEventExtension, O
  * Represents an ArvoEvent, which extends the CloudEvent specification.
  * @template TData - The type of the event data, extending ArvoEventData.
  * @template TExtension - The type of additional extensions, extending CloudEventExtension.
+ * @template TType - The type name of the event
  */
-export default class ArvoEvent<TData extends ArvoEventData = ArvoEventData, TExtension extends CloudEventExtension = CloudEventExtension> {
+export default class ArvoEvent<TData extends ArvoEventData = ArvoEventData, TExtension extends CloudEventExtension = CloudEventExtension, TType extends string = string> {
     readonly id: string;
     readonly source: string;
     readonly specversion: string;
-    readonly type: string;
+    readonly type: TType;
     readonly subject: string;
     readonly datacontenttype: string;
     readonly dataschema: string | null;
@@ -36,7 +37,7 @@ export default class ArvoEvent<TData extends ArvoEventData = ArvoEventData, TExt
             id: string;
             source: string;
             specversion: string;
-            type: string;
+            type: TType;
             subject: string;
             datacontenttype: string;
             dataschema: string | null;
@@ -77,7 +78,7 @@ export default class ArvoEvent<TData extends ArvoEventData = ArvoEventData, TExt
         'cloudevents.event_source': string;
         'cloudevents.event_spec_version': string;
         'cloudevents.event_subject': string;
-        'cloudevents.event_type': string;
+        'cloudevents.event_type': string | TType;
         'cloudevents.event_time': string;
         'cloudevents.event_datacontenttype': string;
         'cloudevents.event_dataschema': string;

package/dist/ArvoEvent/index.js

@@ -17,6 +17,7 @@ var OpenTelemetry_1 = require("../OpenTelemetry");
  * Represents an ArvoEvent, which extends the CloudEvent specification.
  * @template TData - The type of the event data, extending ArvoEventData.
  * @template TExtension - The type of additional extensions, extending CloudEventExtension.
+ * @template TType - The type name of the event
  */
 var ArvoEvent = /** @class */ (function () {
     /**

package/dist/ArvoEvent/types.d.ts

@@ -23,8 +23,9 @@ export type OpenTelemetryExtension = z.infer<typeof OpenTelemetryExtensionSchema
 /**
  * Represents the input parameters for creating an ArvoEvent.
  * @template TData - The type of the event data, extending ArvoEventData.
+ * @template TType - The type name of the event
  */
-export type CreateArvoEvent<TData extends ArvoEventData> = {
+export type CreateArvoEvent<TData extends ArvoEventData, TType extends string> = {
     /** Unique identifier of the event. Must be a non-empty string. If not provided, a UUID will be generated. */
     id?: string;
     /** Timestamp of when the occurrence happened. Must be in ISO 8601 format with timezone offset. */
@@ -34,7 +35,7 @@ export type CreateArvoEvent<TData extends ArvoEventData> = {
     /** The version of the CloudEvents specification used. Must be '1.0' for this version. */
     specversion?: '1.0';
     /** Describes the type of event. Should be prefixed with a reverse-DNS name. */
-    type: string;
+    type: TType;
     /** Identifies the subject of the event. For Arvo, this must be the Process Id. */
     subject: string;
     /** Content type of the data value. Must include 'application/cloudevents+json' or

package/dist/index.d.ts

@@ -6,7 +6,7 @@ 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 } from './ArvoContract/helpers';
+import { createArvoContract, InferArvoContract, createContractualArvoEvent } from './ArvoContract/helpers';
 import { ArvoContractValidators } from './ArvoContract/validators';
 import { ArvoContractRecord, IArvoContract, ResolveArvoContractRecord } from './ArvoContract/types';
 import ArvoContractLibrary from './ArvoContractLibrary';
@@ -77,4 +77,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, };
+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, createContractualArvoEvent, };

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.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.createContractualArvoEvent = 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,6 +24,7 @@ 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, "createContractualArvoEvent", { enumerable: true, get: function () { return helpers_2.createContractualArvoEvent; } });
 var validators_1 = require("./ArvoContract/validators");
 Object.defineProperty(exports, "ArvoContractValidators", { enumerable: true, get: function () { return validators_1.ArvoContractValidators; } });
 var ArvoContractLibrary_1 = __importDefault(require("./ArvoContractLibrary"));

package/package.json

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