Class ArvoContract<TUri, TType, TVersions, TMetaData>

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

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() })
      }
    }
  }
});

Type Parameters

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>

Index

Constructors

constructor

new ArvoContract<
    TUri extends string = string,
    TType extends string = string,
    TVersions extends
        Record<
            `${number}.${number}.${number}`,
            { accepts: ZodTypeAny; emits: Record<string, z.ZodTypeAny> },
        > = Record<
        `${number}.${number}.${number}`,
        { accepts: ZodTypeAny; emits: Record<string, z.ZodTypeAny> },
    >,
    TMetaData extends Record<string, any> = Record<string, any>,
>(
    params: IArvoContract<TUri, TType, TVersions, TMetaData>,
): ArvoContract<TUri, TType, TVersions, TMetaData>
Creates a new ArvoContract instance with validated parameters.
Type Parameters
- TUri extends string = string
- TType extends string = string
- TVersions extends Record<
      `${number}.${number}.${number}`,
      { accepts: ZodTypeAny; emits: Record<string, z.ZodTypeAny> },
  > = Record<
      `${number}.${number}.${number}`,
      { accepts: ZodTypeAny; emits: Record<string, z.ZodTypeAny> },
  >
- TMetaData extends Record<string, any> = Record<string, any>
Parameters
- params: IArvoContract<TUri, TType, TVersions, TMetaData>
  Contract configuration parameters
Returns ArvoContract<TUri, TType, TVersions, TMetaData>
Throws
When URI format is invalid

Throws
When event type format is invalid

Throws
When version string is not valid semantic version

Throws
When version is a reserved wildcard version

Throws
When emit type format is invalid

Throws
When no versions are provided

Throws
When domain does not have follow the condition Domain must contain only lowercase letters, numbers, and dots
- Defined in src/ArvoContract/index.ts:99

Properties

`Protected` `Readonly`_description

_description: string | null

`Protected` `Readonly`_domain

_domain: string | null

`Protected` `Readonly`_metadata

_metadata: TMetaData

`Protected` `Readonly`_type

_type: TType

`Protected` `Readonly`_uri

_uri: TUri

`Protected` `Readonly`_versions

_versions: TVersions

Accessors

description

get description(): string | null
Returns string | null
- Defined in src/ArvoContract/index.ts:76

domain

get domain(): string | null
Returns string | null
- Defined in src/ArvoContract/index.ts:82

metadata

get metadata(): TMetaData
Returns TMetaData
- Defined in src/ArvoContract/index.ts:79

systemError

get systemError(): ArvoContractRecord<
    `sys.${TType}.error`,
    ZodObject<
        {
            errorMessage: ZodString;
            errorName: ZodString;
            errorStack: ZodNullable<ZodString>;
        },
        "strip",
        ZodTypeAny,
        { errorMessage: string; errorName: string; errorStack: string
        | null },
        { errorMessage: string; errorName: string; errorStack: string | null },
    >,
>
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)
Returns ArvoContractRecord<
    `sys.${TType}.error`,
    ZodObject<
        {
            errorMessage: ZodString;
            errorName: ZodString;
            errorStack: ZodNullable<ZodString>;
        },
        "strip",
        ZodTypeAny,
        { errorMessage: string; errorName: string; errorStack: string
        | null },
        { errorMessage: string; errorName: string; errorStack: string | null },
    >,
>
- Defined in src/ArvoContract/index.ts:144

type

get type(): TType
Returns TType
- Defined in src/ArvoContract/index.ts:70

uri

get uri(): TUri
Returns TUri
- Defined in src/ArvoContract/index.ts:67

versions

get versions(): TVersions
Returns TVersions
- Defined in src/ArvoContract/index.ts:73

Methods

export

export(): IArvoContract<TUri, TType, TVersions>
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<TUri, TType, TVersions>
- Defined in src/ArvoContract/index.ts:200

getSortedVersionNumbers

getSortedVersionNumbers(
ordering: "ASC" | "DESC",
): `${number}.${number}.${number}`[]
Retrieves version numbers in sorted order based on semantic versioning rules.
Parameters
- ordering: "ASC" | "DESC"
Returns `${number}.${number}.${number}`[]
Array of semantic versions sorted according to specified ordering
- Defined in src/ArvoContract/index.ts:191

toJsonSchema

toJsonSchema(): ArvoContractJSONSchema
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 ArvoContractJSONSchema
- Defined in src/ArvoContract/index.ts:216

version

version<V extends `${number}.${number}.${number}` | "any" | "latest" | "oldest">(
    option: V,
): V extends `${number}.${number}.${number}` & keyof TVersions
    ? VersionedArvoContract<
        ArvoContract<TUri, TType, TVersions, TMetaData>,
        V<V>,
    >
    : VersionedArvoContract<any, any>
Retrieves a specific version of the contract or resolves special version identifiers.
Type Parameters
- V extends `${number}.${number}.${number}` | "any" | "latest" | "oldest"
Parameters
- option: V
  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 V extends `${number}.${number}.${number}` & keyof TVersions
    ? VersionedArvoContract<
        ArvoContract<TUri, TType, TVersions, TMetaData>,
        V<V>,
    >
    : VersionedArvoContract<any, any>
A versioned contract instance with type-safe schemas

Throws
When an invalid or non-existent version is requested
- Defined in src/ArvoContract/index.ts:163

Class ArvoContract<TUri, TType, TVersions, TMetaData>

Example

Type Parameters

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns ArvoContract<TUri, TType, TVersions, TMetaData>

Throws

Throws

Throws

Throws

Throws

Throws

Throws

Properties

Protected Readonly_description

Protected Readonly_domain

Protected Readonly_metadata

Protected Readonly_type

Protected Readonly_uri

Protected Readonly_versions

Accessors

description

Returns string | null

domain

Returns string | null

metadata

Returns TMetaData

systemError

type

Returns TType

uri

Returns TUri

versions

Returns TVersions

Methods

export

Returns IArvoContract<TUri, TType, TVersions>

getSortedVersionNumbers

Parameters

Returns `${number}.${number}.${number}`[]

toJsonSchema

Returns ArvoContractJSONSchema

version

Type Parameters

Parameters

Returns V extends `${number}.${number}.${number}` & keyof TVersions ? VersionedArvoContract< ArvoContract<TUri, TType, TVersions, TMetaData>, V<V>, > : VersionedArvoContract<any, any>

Throws

Settings

On This Page

`Protected` `Readonly`_description

`Protected` `Readonly`_domain

`Protected` `Readonly`_metadata

`Protected` `Readonly`_type

`Protected` `Readonly`_uri

`Protected` `Readonly`_versions

Returns V extends `${number}.${number}.${number}` & keyof TVersions
? VersionedArvoContract<
ArvoContract<TUri, TType, TVersions, TMetaData>,
V<V>,
>
: VersionedArvoContract<any, any>