arvo-core 2.0.7 → 2.0.8

package/dist/ArvoContract/index.d.ts

@@ -4,14 +4,29 @@ import { ArvoErrorSchema } from '../schema';
 import { ArvoSemanticVersion } from '../types';
 import { VersionedArvoContract } from './VersionedArvoContract';
 /**
- * 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
+ * Represents a contract with defined input and output schemas for event-driven architectures.
+ * The ArvoContract class provides type-safe validation and versioning capabilities for event handling,
+ * ensuring consistency in message passing between different parts of the system.
  *
- * @template TUri - The URI of the contract
- * @template TType - The accept type, defaults to string.
- * @template TVersion - The contract versions
+ * @template TUri - The URI identifier for the contract, must be a string type
+ * @template TType - The accept type for the contract, must be a string type
+ * @template TVersions - Record of versioned schemas defining contract structure per version
+ *
+ * @example
+ * ```typescript
+ * const contract = createArvoContract({
+ *   uri: '#/my/service/data',
+ *   type: 'com.process.data',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({ data: z.string() }),
+ *       emits: {
+ *         'data.processed': z.object({ result: z.string() })
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
  */
 export default class ArvoContract<TUri extends string = string, TType extends string = string, TVersions extends Record<ArvoSemanticVersion, {
     accepts: z.ZodTypeAny;
@@ -24,30 +39,11 @@ export default class ArvoContract<TUri extends string = string, TType extends st
     private readonly _type;
     private readonly _versions;
     readonly description: string | null;
-    /**
-     * Creates an instance of ArvoContract.
-     * @param params - The contract parameters.
-     */
     constructor(params: IArvoContract<TUri, TType, TVersions>);
     /**
      * Gets the URI of the contract.
      */
     get uri(): TUri;
-    /**
-     * Creates a version-specific view of the contract, providing easy access to all
-     * schemas and specifications for a particular semantic version.
-     *
-     * @template V - The semantic version to create a view for, must be a valid version in the contract
-     *
-     * @param ver - The semantic version string (e.g., "1.0.0")
-     * @returns A VersionedArvoContract instance containing all specifications for the requested version
-     *
-     * The returned object provides a simpler, flatter structure compared to
-     * accessing version-specific information through the main contract methods.
-     *
-     * @see {@link VersionedArvoContract} for the structure of the returned object
-     */
-    version<V extends ArvoSemanticVersion & keyof TVersions>(ver: V): VersionedArvoContract<typeof this, V>;
     /**
      * Get the type of the event the handler
      * bound to the contract accepts
@@ -57,20 +53,6 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * Gets the version of the contract
      */
     get versions(): TVersions;
-    /**
-     * Get the latest version of the contract
-     */
-    get latestVersion(): ArvoSemanticVersion;
-    /**
-     * Gets the type and schema of the event that the contact
-     * bound handler listens to.
-     */
-    accepts<V extends ArvoSemanticVersion & keyof TVersions>(version: V): ArvoContractRecord<TType, TVersions[V]['accepts']>;
-    /**
-     * Gets all event types and schemas that can be emitted by the
-     * contract bound handler.
-     */
-    emits<V extends ArvoSemanticVersion & keyof TVersions>(version: V): TVersions[V]['emits'];
     /**
      * Gets the system error event specification for this contract.
      * System errors follow a standardized format to handle exceptional conditions
@@ -86,33 +68,34 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * - Use a standardized schema across all contracts
      * - Can capture error details, messages, and stack traces
      * - Are version-independent (work the same across all contract versions)
-     *
-     * @see {@link ArvoErrorSchema} for the detailed error schema definition
-     * @see {@link ArvoContractRecord} for the structure of the returned record
      */
     get systemError(): ArvoContractRecord<`sys.${TType}.error`, typeof ArvoErrorSchema>;
     /**
-     * Validates the contract bound handler's input/ accept event against the
-     * contract's accept schema.
-     * @template U - The type of the input to validate.
-     * @template V - The version to use
-     * @param version - The version to use
-     * @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.
+     * Retrieves a specific version of the contract or resolves special version identifiers.
+     *
+     * @template V - Type parameter constrained to valid semantic versions in TVersions
+     * @template S - Type parameter for special version identifiers
+     *
+     * @param option - Version identifier or special version string
+     * - Specific version (e.g., "1.0.0")
+     * - "latest" or "any" for the most recent version
+     * - "oldest" for the first version
+     *
+     * @returns A versioned contract instance with type-safe schemas
+     *
+     * @throws {Error} When an invalid or non-existent version is requested
      */
-    validateAccepts<V extends ArvoSemanticVersion & keyof TVersions, U>(version: V, type: TType, input: U): z.SafeParseReturnType<any, any>;
+    version<V extends ArvoSemanticVersion & keyof TVersions, S extends 'any' | 'latest' | 'oldest'>(option: V | S): V extends ArvoSemanticVersion ? VersionedArvoContract<typeof this, V> : VersionedArvoContract<typeof this, ArvoSemanticVersion & keyof TVersions>;
     /**
-     * Validates the contract bound handler's output/ emits against the
-     * contract's emit schema.
-     * @template U - The type of the output to validate.
-     * @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.
+     * Retrieves version numbers in sorted order based on semantic versioning rules.
+     *
+     * @param ordering - Sort direction for versions
+     * - 'ASC' - Ascending order (oldest to newest)
+     * - 'DESC' - Descending order (newest to oldest)
+     *
+     * @returns Array of semantic versions sorted according to specified ordering
      */
-    validateEmits<V extends ArvoSemanticVersion & keyof TVersions, E extends string & keyof TVersions[V]['emits'], U>(version: V, type: E, output: U): z.SafeParseReturnType<any, any>;
+    getSortedVersionNumbers(ordering: 'ASC' | 'DESC'): `${number}.${number}.${number}`[];
     /**
      * 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.

package/dist/ArvoContract/index.js

@@ -1,34 +1,34 @@
 "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);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 var zod_to_json_schema_1 = require("zod-to-json-schema");
 var schema_1 = require("../schema");
 var utils_1 = require("../utils");
 /**
- * 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
+ * Represents a contract with defined input and output schemas for event-driven architectures.
+ * The ArvoContract class provides type-safe validation and versioning capabilities for event handling,
+ * ensuring consistency in message passing between different parts of the system.
  *
- * @template TUri - The URI of the contract
- * @template TType - The accept type, defaults to string.
- * @template TVersion - The contract versions
+ * @template TUri - The URI identifier for the contract, must be a string type
+ * @template TType - The accept type for the contract, must be a string type
+ * @template TVersions - Record of versioned schemas defining contract structure per version
+ *
+ * @example
+ * ```typescript
+ * const contract = createArvoContract({
+ *   uri: '#/my/service/data',
+ *   type: 'com.process.data',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({ data: z.string() }),
+ *       emits: {
+ *         'data.processed': z.object({ result: z.string() })
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
  */
 var ArvoContract = /** @class */ (function () {
-    /**
-     * Creates an instance of ArvoContract.
-     * @param params - The contract parameters.
-     */
     function ArvoContract(params) {
         var _a;
         this._uri = params.uri;
@@ -36,7 +36,7 @@ var ArvoContract = /** @class */ (function () {
         this._versions = params.versions;
         this.description = (_a = params.description) !== null && _a !== void 0 ? _a : null;
         if (!Object.keys(this._versions).length) {
-            throw new Error("A contract must have at least one version");
+            throw new Error("An ArvoContract (uri=".concat(this._uri, ") must have at least one version"));
         }
     }
     Object.defineProperty(ArvoContract.prototype, "uri", {
@@ -49,33 +49,6 @@ var ArvoContract = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
-    /**
-     * Creates a version-specific view of the contract, providing easy access to all
-     * schemas and specifications for a particular semantic version.
-     *
-     * @template V - The semantic version to create a view for, must be a valid version in the contract
-     *
-     * @param ver - The semantic version string (e.g., "1.0.0")
-     * @returns A VersionedArvoContract instance containing all specifications for the requested version
-     *
-     * The returned object provides a simpler, flatter structure compared to
-     * accessing version-specific information through the main contract methods.
-     *
-     * @see {@link VersionedArvoContract} for the structure of the returned object
-     */
-    ArvoContract.prototype.version = function (ver) {
-        return {
-            uri: this._uri,
-            description: this.description,
-            version: ver,
-            accepts: {
-                type: this._type,
-                schema: this._versions[ver].accepts,
-            },
-            systemError: this.systemError,
-            emits: this._versions[ver].emits,
-        };
-    };
     Object.defineProperty(ArvoContract.prototype, "type", {
         /**
          * Get the type of the event the handler
@@ -97,35 +70,6 @@ var ArvoContract = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
-    Object.defineProperty(ArvoContract.prototype, "latestVersion", {
-        /**
-         * Get the latest version of the contract
-         */
-        get: function () {
-            return Object.keys(this._versions).sort(function (a, b) {
-                return (0, utils_1.compareSemanticVersions)(b, a);
-            })[0];
-        },
-        enumerable: false,
-        configurable: true
-    });
-    /**
-     * Gets the type and schema of the event that the contact
-     * bound handler listens to.
-     */
-    ArvoContract.prototype.accepts = function (version) {
-        return {
-            type: this._type,
-            schema: this._versions[version].accepts,
-        };
-    };
-    /**
-     * Gets all event types and schemas that can be emitted by the
-     * contract bound handler.
-     */
-    ArvoContract.prototype.emits = function (version) {
-        return __assign({}, this._versions[version].emits);
-    };
     Object.defineProperty(ArvoContract.prototype, "systemError", {
         /**
          * Gets the system error event specification for this contract.
@@ -142,9 +86,6 @@ var ArvoContract = /** @class */ (function () {
          * - Use a standardized schema across all contracts
          * - Can capture error details, messages, and stack traces
          * - Are version-independent (work the same across all contract versions)
-         *
-         * @see {@link ArvoErrorSchema} for the detailed error schema definition
-         * @see {@link ArvoContractRecord} for the structure of the returned record
          */
         get: function () {
             return {
@@ -156,38 +97,58 @@ var ArvoContract = /** @class */ (function () {
         configurable: true
     });
     /**
-     * Validates the contract bound handler's input/ accept event against the
-     * contract's accept schema.
-     * @template U - The type of the input to validate.
-     * @template V - The version to use
-     * @param version - The version to use
-     * @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.
+     * Retrieves a specific version of the contract or resolves special version identifiers.
+     *
+     * @template V - Type parameter constrained to valid semantic versions in TVersions
+     * @template S - Type parameter for special version identifiers
+     *
+     * @param option - Version identifier or special version string
+     * - Specific version (e.g., "1.0.0")
+     * - "latest" or "any" for the most recent version
+     * - "oldest" for the first version
+     *
+     * @returns A versioned contract instance with type-safe schemas
+     *
+     * @throws {Error} When an invalid or non-existent version is requested
      */
-    ArvoContract.prototype.validateAccepts = function (version, type, input) {
-        if (type !== this._type) {
-            throw new Error("Accept type \"".concat(type, "\" for version \"").concat(version, "\" not found in contract \"").concat(this._uri, "\""));
+    ArvoContract.prototype.version = function (option) {
+        var resolvedVersion;
+        if (option === 'any' || option === 'latest') {
+            resolvedVersion = this.getSortedVersionNumbers('DESC')[0];
         }
-        return this._versions[version].accepts.safeParse(input);
+        else if (option === 'oldest') {
+            resolvedVersion = this.getSortedVersionNumbers('ASC')[0];
+        }
+        else if (!this._versions[option]) {
+            throw new Error("The contract (uri=".concat(this._uri, ") does not have version=").concat(option));
+        }
+        else {
+            resolvedVersion = option;
+        }
+        return {
+            uri: this._uri,
+            description: this.description,
+            version: resolvedVersion,
+            accepts: {
+                type: this._type,
+                schema: this._versions[resolvedVersion].accepts,
+            },
+            systemError: this.systemError,
+            emits: this._versions[resolvedVersion].emits,
+        }; // needed due to TypeScript limitations with conditional types
     };
     /**
-     * Validates the contract bound handler's output/ emits against the
-     * contract's emit schema.
-     * @template U - The type of the output to validate.
-     * @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.
+     * Retrieves version numbers in sorted order based on semantic versioning rules.
+     *
+     * @param ordering - Sort direction for versions
+     * - 'ASC' - Ascending order (oldest to newest)
+     * - 'DESC' - Descending order (newest to oldest)
+     *
+     * @returns Array of semantic versions sorted according to specified ordering
      */
-    ArvoContract.prototype.validateEmits = function (version, type, output) {
-        var _a, _b, _c;
-        var emit = (_c = (_b = (_a = this._versions) === null || _a === void 0 ? void 0 : _a[version]) === null || _b === void 0 ? void 0 : _b.emits) === null || _c === void 0 ? void 0 : _c[type];
-        if (!emit) {
-            throw new Error("Emit type \"".concat(type.toString(), "\" for version \"").concat(version, "\" not found in contract \"").concat(this._uri, "\""));
-        }
-        return emit.safeParse(output);
+    ArvoContract.prototype.getSortedVersionNumbers = function (ordering) {
+        var sorted = Object.keys(this._versions).sort(function (a, b) { return (0, utils_1.compareSemanticVersions)(b, a); });
+        return ordering === 'DESC' ? sorted : sorted.reverse();
     };
     /**
      * Exports the ArvoContract instance as a plain object conforming to the IArvoContract interface.

package/dist/types.d.ts

@@ -129,12 +129,6 @@ type InferZodSchema<T> = T extends z.ZodTypeAny ? z.infer<T> : never;
  * //   systemError: { ... inferred system error event type ... };
  * // }
  * ```
- *
- * @remarks
- * - All version keys must be valid {@link ArvoSemanticVersion} strings
- * - The contract must define at least one version
- * - Each version must specify both accepted and emitted event schemas
- * - System error handling is automatically included for all contracts
  */
 export type InferArvoContract<T extends ArvoContract<string, string, Record<ArvoSemanticVersion, {
     accepts: z.ZodTypeAny;
@@ -184,19 +178,6 @@ export type ArvoErrorType = z.infer<typeof ArvoErrorSchema>;
  * @property systemError - The fully resolved system error event type
  * @property emits - Record of all fully resolved emit event types
  *
- * This type utility:
- * - Transforms Zod schemas into their inferred TypeScript types
- * - Wraps all event types in the full ArvoEvent structure
- * - Preserves all event type relationships and constraints
- * - Includes OpenTelemetry and Arvo extensions
- * - Maintains type safety across all transformations
- *
- * Common use cases:
- * - Type-safe event handling in version-specific contexts
- * - Generating TypeScript interfaces for API documentation
- * - Validating event payload types at compile time
- * - Creating type-safe event factories
- *
  * @see {@link VersionedArvoContract} for the input contract structure
  * @see {@link InferArvoEvent} for the event inference utility
  * @see {@link ArvoEvent} for the base event structure

package/package.json

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