arvo-core/dist/ArvoContract/index.d.ts

The core Arvo package which provides application tier core primitives and contract system for building production-grade event-driven application. Provides ArvoEvent (CloudEvents-compliant), ArvoContract for type-safe service interfaces, event factories, O

import type { z } from 'zod';
import { ArvoErrorSchema } from '../schema';
import type { ArvoSemanticVersion } from '../types';
import { VersionedArvoContract } from './VersionedArvoContract';
import type { ArvoContractJSONSchema, ArvoContractParam, ArvoContractRecord } from './types';
/**
 * 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.
 *
 * @example
 * ```typescript
 * const contract = createArvoContract({
 *   uri: '#/my/service/data',
 *   type: 'com.process.data',
 *   description: 'An example contract',
 *   metadata: {
 *     visibility: "public"
 *   }
 *   versions: {
 *     '1.0.0': {
 *       accepts: z.object({ data: z.string() }),
 *       emits: {
 *         'data.processed': z.object({ result: z.string() })
 *       }
 *     },
 *     '2.0.0': {
 *       accepts: z.object({ data: z.number() }),
 *       emits: {
 *         'data.processed': z.object({ result: z.number() })
 *       }
 *     }
 *   }
 * });
 * ```
 */
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>;
}>, TMetaData extends Record<string, any> = Record<string, any>> {
    protected readonly _uri: TUri;
    protected readonly _type: TType;
    protected readonly _versions: TVersions;
    protected readonly _description: string | null;
    protected readonly _metadata: TMetaData;
    protected readonly _domain: string | null;
    get uri(): TUri;
    get type(): TType;
    get versions(): TVersions;
    get description(): string | null;
    get metadata(): TMetaData;
    get domain(): string | null;
    /**
     * Creates a new ArvoContract instance with validated parameters.
     *
     * @param params - Contract configuration parameters
     *
     * @throws {Error} When URI format is invalid
     * @throws {Error} When event type format is invalid
     * @throws {Error} When version string is not valid semantic version
     * @throws {Error} When version is a reserved wildcard version
     * @throws {Error} When emit type format is invalid
     * @throws {Error} When no versions are provided
     * @throws {Error} When domain does not have follow the condition Domain must contain only lowercase letters, numbers, and dots
     */
    constructor(params: ArvoContractParam<TUri, TType, TVersions, TMetaData>);
    /**
     * Gets the system error event specification for this contract.
     * System errors follow a standardized format to handle exceptional conditions
     * and failures in a consistent way across all contracts.
     *
     * The error schema includes:
     *   - errorName: The name/type of the error
     *   - errorMessage: A descriptive message about what went wrong
     *   - errorStack: Optional stack trace information (null if not available)
     *
     * System errors are special events that:
     * - Are automatically prefixed with 'sys.' and suffixed with '.error'
     * - 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)
     */
    get systemError(): ArvoContractRecord<`sys.${TType}.error`, typeof ArvoErrorSchema>;
    /**
     * Retrieves a specific version of the contract or resolves 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
     */
    version<V extends (ArvoSemanticVersion & keyof TVersions) | 'any' | 'latest' | 'oldest'>(option: V): V extends ArvoSemanticVersion & keyof TVersions ? VersionedArvoContract<typeof this, V> : VersionedArvoContract<any, any>;
    /**
     * Retrieves version numbers in sorted order based on semantic versioning rules.
     * @returns Array of semantic versions sorted according to specified ordering
     */
    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.
     */
    export(): ArvoContractParam<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
     * in a format that conforms to the JSON Schema specification.
     */
    toJsonSchema(): ArvoContractJSONSchema;
}