arvo-core 1.2.2 → 2.0.1

package/CHANGELOG.md

@@ -68,3 +68,7 @@
 
 - Added mandatory parent chaining in orchestration events so the process chaining and orchestration chaining can be traced
 
+## [2.0.0] - 2024-11-24
+
+- Added version support for contracts and simplified orchestrator contracts
+

package/dist/ArvoContract/helpers.d.ts

@@ -1,33 +1,132 @@
 import { IArvoContract } from './types';
 import ArvoContract from '.';
+import { ArvoSemanticVersion } from '../types';
+import { z } from 'zod';
 /**
- * Infers the ArvoContract type from a given IArvoContract.
+ * Infers the ArvoContract type from a given IArvoContract interface.
+ *
+ * @template T - The IArvoContract interface to infer from
  */
-export type InferArvoContract<T> = T extends IArvoContract<infer S, infer U, infer V, infer W> ? ArvoContract<S, U, V, W> : never;
+type InferArvoContract<T> = T extends IArvoContract<infer Uri, infer Type, infer Versions> ? ArvoContract<Uri, Type, Versions> : never;
 /**
- * Creates an ArvoContract instance from the given contract specification.
+ * Creates and validates an ArvoContract instance from a contract specification.
  *
- * This function provides a convenient way to create and initialize an ArvoContract
- * with proper type inference.
+ * @template TContract - The contract specification type, must extend IArvoContract
+ * @param contract - The contract specification object containing URI, type, and versioned schemas
+ * @throws {Error} If any event type uses the reserved orchestrator prefix
+ * @throws {Error} If URI or event types fail validation
+ * @returns A properly typed ArvoContract instance
  *
- * @template TContract - The type of the contract specification.
+ * @example
+ * ```typescript
+ * const contract = createArvoContract({
+ *   uri: 'com.example.contract',
+ *   type: 'input.event',
+ *   versions: {
+ *     '0.0.1': {
+ *       accepts: z.object({ data: z.string() }),
+ *       emits: {
+ *         'output.event': z.object({ result: z.number() })
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare const createArvoContract: <const TContract extends IArvoContract>(contract: TContract, isOrchestrationContract?: boolean) => InferArvoContract<TContract>;
+/**
+ * Creates a simplified ArvoContract with standardized type prefixes and emit patterns.
+ * This is a convenience function that automatically formats event types according to conventions:
+ * - Accept types are prefixed with "com."
+ * - Emit types are prefixed with "evt." and suffixed with ".success"
+ *
+ * @template TUri - The URI type for the contract
+ * @template TType - The base type name (without prefixes) for the contract
+ * @template TVersions - Record of versions containing accept and emit schemas
  *
- * @param contract - The contract specification object.
- *   This should include the URI, accepts, and emits properties as defined in IArvoContract.
+ * @param param - The configuration object for creating the contract
+ * @param param.uri - The URI identifying the contract
+ * @param param.type - The base type name (will be prefixed with "com.")
+ * @param param.versions - Version-specific schema definitions
+ * @param param.versions[version].accepts - Zod schema for validating incoming events
+ * @param param.versions[version].emits - Zod schema for validating outgoing events
  *
- * @returns The created ArvoContract instance.
- *   The returned type is inferred from the input contract specification.
+ * @returns An ArvoContract instance with standardized type formatting:
+ *          - Accept type will be "com.[type]"
+ *          - Emit type will be "evt.[type].success"
  *
  * @example
- * const myContract = createArvoContract({
- *   uri: 'https://example.com/contracts/myContract',
- *   accepts: {
- *     type: 'com.example.input',
- *     schema: z.object({ name: z.string() }),
- *   },
- *   emits: {
- *     'com.example.output': z.object({ result: z.number() }),
- *   },
+ * ```typescript
+ * const contract = createSimpleArvoContract({
+ *   uri: 'example.com/contracts/processor',
+ *   type: 'document.process',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({
+ *         documentId: z.string(),
+ *         options: z.object({ format: z.string() })
+ *       }),
+ *       emits: z.object({
+ *         processedDocument: z.string(),
+ *         metadata: z.object({ size: z.number() })
+ *       })
+ *     }
+ *   }
  * });
+ *
+ * // Results in a contract where:
+ * // - Accept type is "com.document.process"
+ * // - Emit type is "evt.document.process.success"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple versions example
+ * const contract = createSimpleArvoContract({
+ *   uri: 'api.example/contracts/user',
+ *   type: 'user.create',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({ name: z.string() }),
+ *       emits: z.object({ id: z.string() })
+ *     },
+ *     '2.0.0': {
+ *       accepts: z.object({
+ *         name: z.string(),
+ *         email: z.string().email()
+ *       }),
+ *       emits: z.object({
+ *         id: z.string(),
+ *         created: z.date()
+ *       })
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @remarks
+ * This function simplifies contract creation by:
+ * 1. Automatically prefixing accept types with "com."
+ * 2. Creating a single emit type prefixed with "evt." and suffixed with ".success"
+ * 3. Maintaining type safety and schema validation
+ *
+ * Use this when you have a simple contract pattern with:
+ * - A single accept type
+ * - A single success emit type
+ * - Standard type naming conventions
+ *
+ * For more complex contracts with multiple emit types or custom type naming,
+ * use {@link createArvoContract} instead.
  */
-export declare const createArvoContract: <const TContract extends IArvoContract>(contract: TContract) => InferArvoContract<TContract>;
+export declare const createSimpleArvoContract: <TUri extends string, TType extends string, TVersions extends Record<ArvoSemanticVersion, {
+    accepts: z.ZodTypeAny;
+    emits: z.ZodTypeAny;
+}>>(param: {
+    uri: TUri;
+    type: TType;
+    versions: TVersions;
+}) => ArvoContract<TUri, `com.${TType}`, { [V in ArvoSemanticVersion & keyof TVersions]: {
+    accepts: TVersions[V]["accepts"];
+    emits: { [K in `evt.${TType}.succes`]: TVersions[V]["emits"]; };
+}; }>;
+export {};

package/dist/ArvoContract/helpers.js

@@ -3,52 +3,170 @@ 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.createSimpleArvoContract = exports.createArvoContract = void 0;
 var _1 = __importDefault(require("."));
 var typegen_1 = require("../ArvoOrchestratorContract/typegen");
 var utils_1 = require("../utils");
+var validators_1 = require("./validators");
+var schema_1 = require("../schema");
+var ArvoOrchestrationSubject_1 = __importDefault(require("../ArvoOrchestrationSubject"));
 /**
- * Creates an ArvoContract instance from the given contract specification.
+ * Creates and validates an ArvoContract instance from a 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 contract - The contract specification object.
- *   This should include the URI, accepts, and emits properties as defined in IArvoContract.
- *
- * @returns The created ArvoContract instance.
- *   The returned type is inferred from the input contract specification.
+ * @template TContract - The contract specification type, must extend IArvoContract
+ * @param contract - The contract specification object containing URI, type, and versioned schemas
+ * @throws {Error} If any event type uses the reserved orchestrator prefix
+ * @throws {Error} If URI or event types fail validation
+ * @returns A properly typed ArvoContract instance
  *
  * @example
- * const myContract = createArvoContract({
- *   uri: 'https://example.com/contracts/myContract',
- *   accepts: {
- *     type: 'com.example.input',
- *     schema: z.object({ name: z.string() }),
- *   },
- *   emits: {
- *     'com.example.output': z.object({ result: z.number() }),
- *   },
+ * ```typescript
+ * const contract = createArvoContract({
+ *   uri: 'com.example.contract',
+ *   type: 'input.event',
+ *   versions: {
+ *     '0.0.1': {
+ *       accepts: z.object({ data: z.string() }),
+ *       emits: {
+ *         'output.event': z.object({ result: z.number() })
+ *       }
+ *     }
+ *   }
  * });
+ * ```
  */
-var createArvoContract = function (contract) {
-    var createErrorMessage = function (source, type) {
-        return (0, utils_1.cleanString)("\n    In contract (uri=".concat(contract.uri, "), the '").concat(source, "' event (type=").concat(type, ") must not start \n    with '").concat(typegen_1.ArvoOrchestratorEventTypeGen.prefix, "' becuase this a reserved pattern \n    for Arvo orchestrators.\n  "));
+var createArvoContract = function (contract, isOrchestrationContract) {
+    if (isOrchestrationContract === void 0) { isOrchestrationContract = false; }
+    var createErrorMessage = function (source, type, version) {
+        var versionString = version ? ", version=".concat(version) : '';
+        return (0, utils_1.cleanString)("\n      In contract (uri=".concat(contract.uri).concat(versionString, "), the '").concat(source, "' event (type=").concat(type, ") must not start\n      with '").concat(typegen_1.ArvoOrchestratorEventTypeGen.prefix, "' because this is a reserved pattern\n      for Arvo orchestrators.\n    "));
     };
-    var validator = function (value) {
-        return value.startsWith(typegen_1.ArvoOrchestratorEventTypeGen.prefix);
+    var isReservedPrefix = function (value) {
+        return !isOrchestrationContract &&
+            value.startsWith(typegen_1.ArvoOrchestratorEventTypeGen.prefix);
     };
-    if (validator(contract.accepts.type)) {
-        throw new Error(createErrorMessage('accepts', contract.accepts.type));
+    if (isReservedPrefix(contract.type)) {
+        throw new Error(createErrorMessage('accepts', contract.type, null));
     }
-    for (var _i = 0, _a = Object.keys(contract.emits); _i < _a.length; _i++) {
-        var item = _a[_i];
-        if (validator(item)) {
-            throw new Error(createErrorMessage('emits', item));
+    validators_1.ArvoContractValidators.contract.uri.parse(contract.uri);
+    for (var _i = 0, _a = Object.entries(contract.versions); _i < _a.length; _i++) {
+        var _b = _a[_i], version = _b[0], versionContract = _b[1];
+        schema_1.ArvoSemanticVersionSchema.parse(version);
+        if (version === ArvoOrchestrationSubject_1.default.WildCardMachineVersion) {
+            throw new Error("The version cannot be ".concat(ArvoOrchestrationSubject_1.default.WildCardMachineVersion));
+        }
+        for (var _c = 0, _d = Object.keys(versionContract.emits); _c < _d.length; _c++) {
+            var emitType = _d[_c];
+            validators_1.ArvoContractValidators.record.type.parse(emitType);
+            if (isReservedPrefix(emitType)) {
+                throw new Error(createErrorMessage('emits', emitType, version));
+            }
         }
     }
     return new _1.default(contract);
 };
 exports.createArvoContract = createArvoContract;
+/**
+ * Creates a simplified ArvoContract with standardized type prefixes and emit patterns.
+ * This is a convenience function that automatically formats event types according to conventions:
+ * - Accept types are prefixed with "com."
+ * - Emit types are prefixed with "evt." and suffixed with ".success"
+ *
+ * @template TUri - The URI type for the contract
+ * @template TType - The base type name (without prefixes) for the contract
+ * @template TVersions - Record of versions containing accept and emit schemas
+ *
+ * @param param - The configuration object for creating the contract
+ * @param param.uri - The URI identifying the contract
+ * @param param.type - The base type name (will be prefixed with "com.")
+ * @param param.versions - Version-specific schema definitions
+ * @param param.versions[version].accepts - Zod schema for validating incoming events
+ * @param param.versions[version].emits - Zod schema for validating outgoing events
+ *
+ * @returns An ArvoContract instance with standardized type formatting:
+ *          - Accept type will be "com.[type]"
+ *          - Emit type will be "evt.[type].success"
+ *
+ * @example
+ * ```typescript
+ * const contract = createSimpleArvoContract({
+ *   uri: 'example.com/contracts/processor',
+ *   type: 'document.process',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({
+ *         documentId: z.string(),
+ *         options: z.object({ format: z.string() })
+ *       }),
+ *       emits: z.object({
+ *         processedDocument: z.string(),
+ *         metadata: z.object({ size: z.number() })
+ *       })
+ *     }
+ *   }
+ * });
+ *
+ * // Results in a contract where:
+ * // - Accept type is "com.document.process"
+ * // - Emit type is "evt.document.process.success"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple versions example
+ * const contract = createSimpleArvoContract({
+ *   uri: 'api.example/contracts/user',
+ *   type: 'user.create',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({ name: z.string() }),
+ *       emits: z.object({ id: z.string() })
+ *     },
+ *     '2.0.0': {
+ *       accepts: z.object({
+ *         name: z.string(),
+ *         email: z.string().email()
+ *       }),
+ *       emits: z.object({
+ *         id: z.string(),
+ *         created: z.date()
+ *       })
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @remarks
+ * This function simplifies contract creation by:
+ * 1. Automatically prefixing accept types with "com."
+ * 2. Creating a single emit type prefixed with "evt." and suffixed with ".success"
+ * 3. Maintaining type safety and schema validation
+ *
+ * Use this when you have a simple contract pattern with:
+ * - A single accept type
+ * - A single success emit type
+ * - Standard type naming conventions
+ *
+ * For more complex contracts with multiple emit types or custom type naming,
+ * use {@link createArvoContract} instead.
+ */
+var createSimpleArvoContract = function (param) {
+    return (0, exports.createArvoContract)({
+        uri: param.uri,
+        type: "com.".concat(param.type),
+        versions: Object.fromEntries(Object.entries(param.versions).map(function (_a) {
+            var _b;
+            var version = _a[0], contract = _a[1];
+            return [
+                version,
+                {
+                    accepts: contract.accepts,
+                    emits: (_b = {},
+                        _b["evt.".concat(param.type, ".success")] = contract.emits,
+                        _b),
+                },
+            ];
+        })),
+    });
+};
+exports.createSimpleArvoContract = createSimpleArvoContract;

package/dist/ArvoContract/index.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ArvoContractJSONSchema, ArvoContractRecord, IArvoContract } from './types';
 import { ArvoErrorSchema } from '../schema';
+import { ArvoSemanticVersion } from '../types';
 /**
  * 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.
@@ -9,45 +10,64 @@ import { ArvoErrorSchema } from '../schema';
  *
  * @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.
+ * @template TVersion - The contract versions
  */
-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>> {
+export default class ArvoContract<TUri extends string = string, TType extends string = string, TVersions extends Record<ArvoSemanticVersion, {
+    accepts: z.ZodTypeAny;
+    emits: Record<string, z.ZodTypeAny>;
+}> = Record<ArvoSemanticVersion, {
+    accepts: z.ZodTypeAny;
+    emits: Record<string, z.ZodTypeAny>;
+}>> {
     private readonly _uri;
-    private readonly _accepts;
-    private readonly _emits;
-    /** (Optional) The Contract description */
+    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, TAcceptSchema, TEmits>);
+    constructor(params: IArvoContract<TUri, TType, TVersions>);
     /**
      * Gets the URI of the contract.
      */
     get uri(): TUri;
+    /**
+     * Get the type of the event the handler
+     * bound to the contract accepts
+     */
+    get type(): TType;
+    /**
+     * Gets the version of the contract
+     */
+    get versions(): TVersions;
+    /**
+     * Get the latest version of the contract
+     */
+    get latestVersion(): ArvoSemanticVersion | undefined;
     /**
      * Gets the type and schema of the event that the contact
      * bound handler listens to.
      */
-    get accepts(): ArvoContractRecord<TType, TAcceptSchema>;
+    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.
      */
-    get emits(): TEmits;
+    emits<V extends ArvoSemanticVersion & keyof TVersions>(version: V): TVersions[V]['emits'];
     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.
      */
-    validateAccepts<U>(type: TType, input: U): z.SafeParseReturnType<any, any>;
+    validateAccepts<V extends ArvoSemanticVersion & keyof TVersions, U>(version: V, type: TType, input: U): z.SafeParseReturnType<any, any>;
     /**
      * Validates the contract bound handler's output/ emits against the
      * contract's emit schema.
@@ -57,28 +77,14 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * @returns The validation result.
      * @throws If the emit type is not found in the contract.
      */
-    validateEmits<U extends keyof TEmits>(type: U, output: unknown): z.SafeParseReturnType<any, any>;
-    /**
-     * Validates the accepts record.
-     * @param accepts - The accepts record to validate.
-     * @returns The validated accepts record.
-     * @private
-     */
-    private _validateAccepts;
-    /**
-     * Validates the emits records.
-     * @param emits - The emits records to validate.
-     * @returns The validated emits records.
-     * @private
-     */
-    private _validateEmits;
+    validateEmits<V extends ArvoSemanticVersion & keyof TVersions, E extends string & keyof TVersions[V]['emits'], U>(version: V, type: E, output: U): z.SafeParseReturnType<any, any>;
     /**
      * 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 An object representing the contract, including its URI, accepts, and emits properties.
      */
-    export(): IArvoContract<TUri, TType, TAcceptSchema, TEmits>;
+    export(): IArvoContract<TUri, TType, TVersions>;
     /**
      * Converts the ArvoContract instance to a JSON Schema representation.
      * This method provides a way to represent the contract's structure and validation rules