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, TType, TVersions, TMetaData>(params): 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, ZodTypeAny>;
  }> = Record<`${number}.${number}.${number}`, {
      accepts: ZodTypeAny;
      emits: Record<string, 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
- Defined in src/ArvoContract/index.ts:94

Properties

`Protected` `Readonly`_description

_description: null | string

`Protected` `Readonly`_metadata

_metadata: TMetaData

`Protected` `Readonly`_type

_type: TType

`Protected` `Readonly`_uri

_uri: TUri

`Protected` `Readonly`_versions

_versions: TVersions

Accessors

description

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

metadata

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

systemError

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

type

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

uri

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

versions

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

Methods

export

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

getSortedVersionNumbers

getSortedVersionNumbers(ordering): `${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:184

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:208

version

version<V>(option): 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:156

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

Properties

Protected Readonly_description

Protected Readonly_metadata

Protected Readonly_type

Protected Readonly_uri

Protected Readonly_versions

Accessors

description

Returns null | string

metadata

Returns TMetaData

systemError

type

Returns TType

uri

Returns TUri

versions

Returns TVersions

Methods

export

Returns IArvoContract<TUri, TType, TVersions, Record<string, any>>

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`_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>