arvo-core 0.0.1 → 0.0.2

package/README.md

@@ -1,8 +1,3 @@
----
-title: ArvoEvent
-group: Guides
----
-
 # Arvo
 
 ## What is Arvo

package/dist/ArvoContract/helpers.d.ts

@@ -1,15 +1,35 @@
 import { IArvoContract } from './types';
 import ArvoContract from '.';
-import { TelemetryContext } from '../OpenTelemetry/types';
 /**
  * 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;
 /**
  * Creates an ArvoContract instance from the given contract specification.
+ *
+ * This function provides a convenient way to create and initialize an ArvoContract
+ * with proper type inference.
+ *
  * @template TContract - The type of the contract specification.
- * @param {TContract} contractSpec - The contract specification.
- * @param {TelemetryContext} [telemetry] - Optional telemetry context for tracing.
+ * @param {TContract} 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.
+ *   The returned type is inferred from the input contract specification.
+ *
+ * @example
+ * const myContract = createArvoContract({
+ *   uri: 'https://example.com/contracts/myContract',
+ *   accepts: {
+ *     type: 'com.example.input',
+ *     schema: z.object({ name: z.string() }),
+ *   },
+ *   emits: [
+ *     {
+ *       type: 'com.example.output',
+ *       schema: z.object({ result: z.number() }),
+ *     },
+ *   ],
+ * });
  */
-export declare const createArvoContract: <const TContract extends IArvoContract>(contract: TContract, telemetry?: TelemetryContext) => InferArvoContract<TContract>;
+export declare const createArvoContract: <const TContract extends IArvoContract>(contract: TContract) => InferArvoContract<TContract>;

package/dist/ArvoContract/helpers.js

@@ -5,15 +5,35 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createArvoContract = void 0;
 var _1 = __importDefault(require("."));
-var OpenTelemetry_1 = require("../OpenTelemetry");
 /**
  * Creates an ArvoContract instance from the given contract specification.
+ *
+ * This function provides a convenient way to create and initialize an ArvoContract
+ * with proper type inference.
+ *
  * @template TContract - The type of the contract specification.
- * @param {TContract} contractSpec - The contract specification.
- * @param {TelemetryContext} [telemetry] - Optional telemetry context for tracing.
+ * @param {TContract} 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.
+ *   The returned type is inferred from the input contract specification.
+ *
+ * @example
+ * const myContract = createArvoContract({
+ *   uri: 'https://example.com/contracts/myContract',
+ *   accepts: {
+ *     type: 'com.example.input',
+ *     schema: z.object({ name: z.string() }),
+ *   },
+ *   emits: [
+ *     {
+ *       type: 'com.example.output',
+ *       schema: z.object({ result: z.number() }),
+ *     },
+ *   ],
+ * });
  */
-var createArvoContract = function (contract, telemetry) {
-    return (0, OpenTelemetry_1.createOtelSpan)(telemetry || 'Arvo Contract Creator', 'Create ArvoContract', {}, function () { return new _1.default(contract); });
+var createArvoContract = function (contract) {
+    return new _1.default(contract);
 };
 exports.createArvoContract = createArvoContract;

package/dist/ArvoContract/index.d.ts

@@ -19,18 +19,19 @@ export default class ArvoContract<T extends string = string, TAccepts extends Ar
     private readonly _uri;
     private readonly _accepts;
     private readonly _emits;
+    readonly description: string | null;
     /**
      * Creates an instance of ArvoContract.
      * @param {IArvoContract<T, TAccepts, TEmits>} params - The contract parameters.
      */
     constructor(params: IArvoContract<T, TAccepts, TEmits>);
     get uri(): T;
-    get accepts(): Readonly<TAccepts>;
+    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.
      */
-    get emits(): Readonly<Record<ExtractEventType<TEmits>, TEmits>>;
+    get emits(): Record<ExtractEventType<TEmits>, TEmits>;
     /**
      * Gets a specific emitted event type and schema.
      * Use this when you need to access a single emitted event by its type.
@@ -39,9 +40,9 @@ export default class ArvoContract<T extends string = string, TAccepts extends Ar
      * @returns {Readonly<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): Readonly<Extract<TEmits, {
+    getEmit<U extends ExtractEventType<TEmits>>(type: U): Extract<TEmits, {
         type: U;
-    }>>;
+    }>;
     /**
      * Validates the input against the contract's accept schema.
      * @template U - The type of the input to validate.
@@ -72,9 +73,49 @@ export default class ArvoContract<T extends string = string, TAccepts extends Ar
     /**
      * Validates the emits records.
      * @param {TEmits[]} emits - The emits records to validate.
-     * @returns {ReadonlyArray<TEmits>} The validated emits records.
+     * @returns {Array<TEmits>} The validated emits records.
      * @private
      */
     private validateEmits;
+    /**
+     * 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<T, TAccepts, TEmits>} An object representing the contract, including its URI, accepts, and emits properties.
+     */
+    export(): IArvoContract<T, TAccepts, 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 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
+     *   - emits: An array of objects, each containing an emitted event type and its JSON Schema representation
+     */
+    toJsonSchema(): {
+        uri: T;
+        description: string | null;
+        accepts: {
+            type: string;
+            schema: import("zod-to-json-schema").JsonSchema7Type & {
+                $schema?: string | undefined;
+                definitions?: {
+                    [key: string]: import("zod-to-json-schema").JsonSchema7Type;
+                } | undefined;
+            };
+        };
+        emits: {
+            type: z.ZodLiteral<string>;
+            schema: import("zod-to-json-schema").JsonSchema7Type & {
+                $schema?: string | undefined;
+                definitions?: {
+                    [key: string]: import("zod-to-json-schema").JsonSchema7Type;
+                } | undefined;
+            };
+        }[];
+    };
 }
 export {};

package/dist/ArvoContract/index.js

@@ -1,6 +1,8 @@
 "use strict";
 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");
 /**
  * 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.
@@ -18,6 +20,7 @@ var ArvoContract = /** @class */ (function () {
         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", {
@@ -29,7 +32,7 @@ var ArvoContract = /** @class */ (function () {
     });
     Object.defineProperty(ArvoContract.prototype, "accepts", {
         get: function () {
-            return this._accepts;
+            return Object.freeze(this._accepts);
         },
         enumerable: false,
         configurable: true
@@ -62,7 +65,7 @@ var ArvoContract = /** @class */ (function () {
         if (!emit) {
             throw new Error("Emit type \"".concat(type, "\" not found in contract"));
         }
-        return emit;
+        return Object.freeze(emit);
     };
     /**
      * Validates the input against the contract's accept schema.
@@ -108,7 +111,7 @@ var ArvoContract = /** @class */ (function () {
     /**
      * Validates the emits records.
      * @param {TEmits[]} emits - The emits records to validate.
-     * @returns {ReadonlyArray<TEmits>} The validated emits records.
+     * @returns {Array<TEmits>} The validated emits records.
      * @private
      */
     ArvoContract.prototype.validateEmits = function (emits) {
@@ -117,6 +120,51 @@ var ArvoContract = /** @class */ (function () {
             schema: item.schema,
         }); }));
     };
+    /**
+     * 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<T, TAccepts, TEmits>} An object representing the contract, including its URI, accepts, and emits properties.
+     */
+    ArvoContract.prototype.export = function () {
+        return {
+            uri: this._uri,
+            description: this.description,
+            accepts: {
+                type: this._accepts.type,
+                schema: this._accepts.schema,
+            },
+            emits: this._emits.map(function (emit) { return ({
+                type: emit.type,
+                schema: emit.schema,
+            }); }),
+        };
+    };
+    /**
+     * 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 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
+     *   - emits: An array of objects, each containing an emitted event type and its JSON Schema representation
+     */
+    ArvoContract.prototype.toJsonSchema = function () {
+        return {
+            uri: this._uri,
+            description: this.description,
+            accepts: {
+                type: this._accepts.type,
+                schema: (0, zod_to_json_schema_1.zodToJsonSchema)(this._accepts.schema),
+            },
+            emits: this._emits.map(function (item) { return ({
+                type: zod_1.z.literal(item.type),
+                schema: (0, zod_to_json_schema_1.zodToJsonSchema)(item.schema),
+            }); }),
+        };
+    };
     return ArvoContract;
 }());
 exports.default = ArvoContract;

package/dist/ArvoContract/types.d.ts

@@ -23,6 +23,8 @@ export interface IArvoContract<TUri extends string = string, TAccepts extends Ar
     accepts: TAccepts;
     /** An array of record types that the contract can emit */
     emits: TEmits[];
+    /** (Optional) The description of the contract or its handler */
+    description?: string | null;
 }
 /**
  * Resolves the inferred type of an ArvoContractRecord's schema.

package/dist/ArvoContractLibrary/helpers.d.ts

@@ -0,0 +1,10 @@
+import ArvoContractLibrary from '.';
+import ArvoContract from '../ArvoContract';
+/**
+ * Creates a new ArvoContractLibrary instance with the given ArvoContract instances.
+ *
+ * @template T - The type of ArvoContract to be stored in the library.
+ * @param {...T[]} args - One or more ArvoContract instances to initialize the library.
+ * @returns {ArvoContractLibrary<T>} A new ArvoContractLibrary instance containing the provided contracts.
+ */
+export declare const createArvoContractLibrary: <T extends ArvoContract>(...args: T[]) => ArvoContractLibrary<T>;

package/dist/ArvoContractLibrary/helpers.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createArvoContractLibrary = void 0;
+var _1 = __importDefault(require("."));
+/**
+ * Creates a new ArvoContractLibrary instance with the given ArvoContract instances.
+ *
+ * @template T - The type of ArvoContract to be stored in the library.
+ * @param {...T[]} args - One or more ArvoContract instances to initialize the library.
+ * @returns {ArvoContractLibrary<T>} A new ArvoContractLibrary instance containing the provided contracts.
+ */
+var createArvoContractLibrary = function () {
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    return new _1.default(args);
+};
+exports.createArvoContractLibrary = createArvoContractLibrary;

package/dist/ArvoContractLibrary/index.d.ts

@@ -0,0 +1,53 @@
+import ArvoContract from '../ArvoContract';
+/**
+ * Extracts the URI type from a given ArvoContract type.
+ * @template T - The ArvoContract type to extract from.
+ */
+type ExtractContractUri<T> = T extends {
+    uri: infer U;
+} ? U : never;
+/**
+ * A library class for managing and accessing ArvoContract instances.
+ * @template T - The type of ArvoContract stored in the library.
+ */
+export default class ArvoContractLibrary<T extends ArvoContract> {
+    /**
+     * The array of ArvoContract instances stored in the library.
+     * @private
+     * @readonly
+     */
+    private readonly _contracts;
+    /**
+     * Creates an instance of ArvoContractLibrary.
+     * @param {T[]} contracts - An array of ArvoContract instances to initialize the library.
+     * @throws An error in case the URI are duplicated
+     */
+    constructor(contracts: T[]);
+    /**
+     * Returns a readonly array of all ArvoContract instances in the library.
+     * @returns {Array<T>} A readonly array of ArvoContract instances.
+     */
+    list(): Array<T>;
+    /**
+     * Retrieves an ArvoContract instance by its URI.
+     * @template U - The type of the URI to search for.
+     * @param {U} uri - The URI of the contract to retrieve.
+     * @returns {Extract<T, { uri: U }>} A readonly ArvoContract instance matching the given URI.
+     * @throws {Error} If no contract with the given URI is found in the library.
+     */
+    get<U extends ExtractContractUri<T>>(uri: U): Extract<T, {
+        uri: U;
+    }>;
+    /**
+     * Checks if the library contains a contract with the given URI.
+     * @param {string} uri - The URI to check for.
+     * @returns {boolean} True if a contract with the given URI exists in the library, false otherwise.
+     */
+    has(uri: string): boolean;
+    /**
+     * Returns the number of contracts in the library.
+     * @returns {number} The number of contracts in the library.
+     */
+    get size(): number;
+}
+export {};

package/dist/ArvoContractLibrary/index.js

@@ -0,0 +1,74 @@
+"use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * A library class for managing and accessing ArvoContract instances.
+ * @template T - The type of ArvoContract stored in the library.
+ */
+var ArvoContractLibrary = /** @class */ (function () {
+    /**
+     * Creates an instance of ArvoContractLibrary.
+     * @param {T[]} contracts - An array of ArvoContract instances to initialize the library.
+     * @throws An error in case the URI are duplicated
+     */
+    function ArvoContractLibrary(contracts) {
+        var uriSet = new Set();
+        contracts.forEach(function (contract) {
+            if (uriSet.has(contract.uri)) {
+                throw new Error("Duplicate contract URI found: ".concat(contract.uri));
+            }
+            uriSet.add(contract.uri);
+        });
+        this._contracts = __spreadArray([], contracts, true);
+    }
+    /**
+     * Returns a readonly array of all ArvoContract instances in the library.
+     * @returns {Array<T>} A readonly array of ArvoContract instances.
+     */
+    ArvoContractLibrary.prototype.list = function () {
+        return Object.freeze(__spreadArray([], this._contracts, true));
+    };
+    /**
+     * Retrieves an ArvoContract instance by its URI.
+     * @template U - The type of the URI to search for.
+     * @param {U} uri - The URI of the contract to retrieve.
+     * @returns {Extract<T, { uri: U }>} A readonly ArvoContract instance matching the given URI.
+     * @throws {Error} If no contract with the given URI is found in the library.
+     */
+    ArvoContractLibrary.prototype.get = function (uri) {
+        var contract = this._contracts.find(function (item) { return item.uri === uri; });
+        if (!contract) {
+            throw new Error("ArvoContract with URI \"".concat(uri, "\" not found in the library"));
+        }
+        return Object.freeze(contract);
+    };
+    /**
+     * Checks if the library contains a contract with the given URI.
+     * @param {string} uri - The URI to check for.
+     * @returns {boolean} True if a contract with the given URI exists in the library, false otherwise.
+     */
+    ArvoContractLibrary.prototype.has = function (uri) {
+        return this._contracts.some(function (contract) { return contract.uri === uri; });
+    };
+    Object.defineProperty(ArvoContractLibrary.prototype, "size", {
+        /**
+         * Returns the number of contracts in the library.
+         * @returns {number} The number of contracts in the library.
+         */
+        get: function () {
+            return this._contracts.length;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return ArvoContractLibrary;
+}());
+exports.default = ArvoContractLibrary;

package/dist/index.d.ts

@@ -5,6 +5,12 @@ import { CloudEventContext, CloudEventExtension, ArvoEventData, ArvoExtension, O
 import { exceptionToSpan, logToSpan, getTelemetryContext, getTelemetryCarrier, createOtelSpan, OTelNull } from './OpenTelemetry';
 import { TelemetryCarrier, TelemetryContext, TelemetryLogLevel } from './OpenTelemetry/types';
 import { validateURI, cleanString } from './utils';
+import ArvoContract from './ArvoContract';
+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';
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.
@@ -71,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, };
+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, };

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.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.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");
@@ -20,6 +20,16 @@ Object.defineProperty(exports, "OTelNull", { enumerable: true, get: function ()
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "validateURI", { enumerable: true, get: function () { return utils_1.validateURI; } });
 Object.defineProperty(exports, "cleanString", { enumerable: true, get: function () { return utils_1.cleanString; } });
+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; } });
+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; } });
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.

package/package.json

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