amqp-contract

Appearance

@amqp-contract/client

@amqp-contract/client ​

Classes ​

MessageValidationError ​

Defined in: packages/core/dist/index.d.mts:39

Error thrown when message validation fails (payload or headers).

Used by both the client (publish-time payload validation) and the worker (consume-time payload and headers validation). Carries a _tag of "@amqp-contract/MessageValidationError" (namespaced to avoid collisions); the Error.name is kept bare ("MessageValidationError").

Param ​

source

The name of the publisher or consumer that triggered the validation

Param ​

issues

The validation issues from the Standard Schema validation

Extends ​

  • MessageValidationError_base<{ issues: unknown; source: string; }>

Constructors ​

Constructor ​
ts
new MessageValidationError(source, issues): MessageValidationError;

Defined in: packages/core/dist/index.d.mts:43

Parameters ​
ParameterType
sourcestring
issuesunknown
Returns ​

MessageValidationError

Overrides ​
ts
MessageValidationError_base<{
  source: string;
  issues: unknown;
}>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
_tagreadonly"@amqp-contract/MessageValidationError"MessageValidationError_base._tagnode_modules/.pnpm/unthrown@4.1.0/node_modules/unthrown/dist/index.d.mts:1456
cause?publicunknownMessageValidationError_base.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
issuesreadonlyunknownMessageValidationError_base.issuespackages/core/dist/index.d.mts:41
messagepublicstringMessageValidationError_base.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringMessageValidationError_base.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
sourcereadonlystringMessageValidationError_base.sourcepackages/core/dist/index.d.mts:40
stack?publicstringMessageValidationError_base.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

RpcCancelledError ​

Defined in: packages/client/src/errors.ts:34

Returned from any in-flight RPC call when the client is closed before the reply is received. The correlation map is cleared on close and every pending caller's promise resolves with Err(RpcCancelledError). Carries a namespaced _tag of "@amqp-contract/RpcCancelledError"; the Error.name is kept bare ("RpcCancelledError").

Extends ​

  • TaggedErrorInstance<"@amqp-contract/RpcCancelledError", { rpcName: string; }>

Constructors ​

Constructor ​
ts
new RpcCancelledError(rpcName): RpcCancelledError;

Defined in: packages/client/src/errors.ts:39

Parameters ​
ParameterType
rpcNamestring
Returns ​

RpcCancelledError

Overrides ​
ts
TaggedError("@amqp-contract/RpcCancelledError", {
  name: "RpcCancelledError",
})<{
  rpcName: string;
}>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
_tagreadonly"@amqp-contract/RpcCancelledError"TaggedError("@amqp-contract/RpcCancelledError", { name: "RpcCancelledError", })._tagnode_modules/.pnpm/unthrown@4.1.0/node_modules/unthrown/dist/index.d.mts:1456
cause?publicunknownTaggedError("@amqp-contract/RpcCancelledError", { name: "RpcCancelledError", }).causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringTaggedError("@amqp-contract/RpcCancelledError", { name: "RpcCancelledError", }).messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringTaggedError("@amqp-contract/RpcCancelledError", { name: "RpcCancelledError", }).namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
rpcNamereadonlystringTaggedError("@amqp-contract/RpcCancelledError", { name: "RpcCancelledError", }).rpcNamepackages/client/src/errors.ts:37
stack?publicstringTaggedError("@amqp-contract/RpcCancelledError", { name: "RpcCancelledError", }).stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

RpcError ​

Defined in: packages/core/dist/index.d.mts:72

A typed, contract-declared RPC error — the business-failure channel of an RPC, as opposed to the transport failures modeled by TechnicalError.

Declared per-RPC via defineRpc(queue, { request, response, errors }), where each error code maps to a message definition validating the error's data payload. A worker handler surfaces one by returning Err(rpcError(code, data)); the worker validates data against the declared schema, publishes an error reply, and acks the request (business errors are not retried). The caller's client.call(...) resolves to Err(RpcError<code, data>) with data re-validated on arrival.

Carries a _tag of "@amqp-contract/RpcError" for exhaustive dispatch via matchTags; the Error.name is kept bare ("RpcError"). Discriminate between codes on the code property.

Extends ​

  • RpcError_base<{ code: string; data: unknown; }>

Type Parameters ​

Type ParameterDefault type
TCode extends stringstring
TDataunknown

Constructors ​

Constructor ​
ts
new RpcError<TCode, TData>(
   code, 
   data, 
   message?): RpcError<TCode, TData>;

Defined in: packages/core/dist/index.d.mts:78

Parameters ​
ParameterType
codeTCode
dataTData
message?string
Returns ​

RpcError<TCode, TData>

Overrides ​
ts
RpcError_base<{
  code: string;
  data: unknown;
}>.constructor

Properties ​

PropertyModifierTypeOverridesInherited fromDefined in
_tagreadonly"@amqp-contract/RpcError"-RpcError_base._tagnode_modules/.pnpm/unthrown@4.1.0/node_modules/unthrown/dist/index.d.mts:1456
cause?publicunknown-RpcError_base.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
codereadonlyTCodeRpcError_base.code-packages/core/dist/index.d.mts:76
datareadonlyTDataRpcError_base.data-packages/core/dist/index.d.mts:77
messagepublicstring-RpcError_base.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-RpcError_base.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstring-RpcError_base.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

RpcTimeoutError ​

Defined in: packages/client/src/errors.ts:15

Returned from TypedAmqpClient.call() when the configured timeoutMs elapses before the RPC server publishes a reply with the matching correlationId.

The pending call is removed from the in-memory correlation map; if a reply arrives after the timeout it is dropped (and a debug log is emitted by the client if a logger is configured). Carries a namespaced _tag of "@amqp-contract/RpcTimeoutError"; the Error.name is kept bare ("RpcTimeoutError").

Extends ​

  • TaggedErrorInstance<"@amqp-contract/RpcTimeoutError", { rpcName: string; timeoutMs: number; }>

Constructors ​

Constructor ​
ts
new RpcTimeoutError(rpcName, timeoutMs): RpcTimeoutError;

Defined in: packages/client/src/errors.ts:21

Parameters ​
ParameterType
rpcNamestring
timeoutMsnumber
Returns ​

RpcTimeoutError

Overrides ​
ts
TaggedError("@amqp-contract/RpcTimeoutError", {
  name: "RpcTimeoutError",
})<{
  rpcName: string;
  timeoutMs: number;
}>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
_tagreadonly"@amqp-contract/RpcTimeoutError"TaggedError("@amqp-contract/RpcTimeoutError", { name: "RpcTimeoutError", })._tagnode_modules/.pnpm/unthrown@4.1.0/node_modules/unthrown/dist/index.d.mts:1456
cause?publicunknownTaggedError("@amqp-contract/RpcTimeoutError", { name: "RpcTimeoutError", }).causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringTaggedError("@amqp-contract/RpcTimeoutError", { name: "RpcTimeoutError", }).messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringTaggedError("@amqp-contract/RpcTimeoutError", { name: "RpcTimeoutError", }).namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
rpcNamereadonlystringTaggedError("@amqp-contract/RpcTimeoutError", { name: "RpcTimeoutError", }).rpcNamepackages/client/src/errors.ts:18
stack?publicstringTaggedError("@amqp-contract/RpcTimeoutError", { name: "RpcTimeoutError", }).stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
timeoutMsreadonlynumberTaggedError("@amqp-contract/RpcTimeoutError", { name: "RpcTimeoutError", }).timeoutMspackages/client/src/errors.ts:19

TypedAmqpClient ​

Defined in: packages/client/src/client.ts:166

Type-safe AMQP client for publishing messages

Type Parameters ​

Type Parameter
TContract extends ContractDefinition

Methods ​

call() ​
ts
call<TName>(
   rpcName, 
   request, 
   options): AsyncResult<ClientInferRpcResponseOutput<TContract, TName>, 
  | TechnicalError
  | MessageValidationError
  | RpcTimeoutError
  | RpcCancelledError
  | ClientInferRpcErrors<TContract, TName>>;

Defined in: packages/client/src/client.ts:565

Invoke an RPC defined via defineRpc and await the typed response.

The request payload is validated against the RPC's request schema, then published to the AMQP default exchange with the server's queue name as routing key, replyTo set to amq.rabbitmq.reply-to, and a fresh UUID correlationId. The returned AsyncResult resolves once a matching reply arrives and validates against the response schema, or once timeoutMs elapses (whichever comes first).

Type Parameters ​
Type Parameter
TName extends string | number | symbol
Parameters ​
ParameterType
rpcNameTName
requestClientInferRpcRequestInput<TContract, TName>
optionsCallOptions
Returns ​

AsyncResult<ClientInferRpcResponseOutput<TContract, TName>, | TechnicalError | MessageValidationError | RpcTimeoutError | RpcCancelledError | ClientInferRpcErrors<TContract, TName>>

Example ​
typescript
const result = await client.call('calculate', { a: 1, b: 2 }, { timeoutMs: 5_000 });
result.match({
  ok: (value) => console.log(value.sum), // 3
  err: (error) => console.error(error),
  defect: (cause) => console.error(cause),
});
close() ​
ts
close(): AsyncResult<void, TechnicalError>;

Defined in: packages/client/src/client.ts:765

Close the channel and connection. Cancels the reply consumer (if any) and rejects every in-flight RPC call with RpcCancelledError.

Returns ​

AsyncResult<void, TechnicalError>

publish() ​
ts
publish<TName>(
   publisherName, 
   message, 
   options?): AsyncResult<void, TechnicalError | MessageValidationError>;

Defined in: packages/client/src/client.ts:431

Publish a message using a defined publisher.

Type Parameters ​
Type Parameter
TName extends string | number | symbol
Parameters ​
ParameterTypeDescription
publisherNameTNameThe name of the publisher to use
messageClientInferPublisherInput<TContract, TName>The message to publish
options?PublishOptionsOptional publish options including compression, headers, priority, etc.
Returns ​

AsyncResult<void, TechnicalError | MessageValidationError>

Remarks ​

If options.compression is specified, the message will be compressed before publishing and the contentEncoding property will be set automatically. Any contentEncoding value already in options will be overwritten by the compression algorithm.

create() ​
ts
static create<TContract>(__namedParameters): AsyncResult<TypedAmqpClient<TContract>, TechnicalError>;

Defined in: packages/client/src/client.ts:199

Create a type-safe AMQP client from a contract.

Connection management (including automatic reconnection) is handled internally by amqp-connection-manager via the AmqpClient. The client establishes infrastructure asynchronously in the background once the connection is ready.

Connections are automatically shared across clients with the same URLs and connection options, following RabbitMQ best practices.

Type Parameters ​
Type Parameter
TContract extends ContractDefinition
Parameters ​
ParameterType
__namedParametersCreateClientOptions<TContract>
Returns ​

AsyncResult<TypedAmqpClient<TContract>, TechnicalError>

Type Aliases ​

CallInterceptor ​

ts
type CallInterceptor = (args, next) => AsyncResult<unknown, CallError>;

Defined in: packages/client/src/interceptors.ts:106

Intercepts client.call(...): wraps the full request/reply round trip, so it can adjust timeouts, stamp request headers, observe replies and typed errors, or retry by calling next again. The first interceptor in the array is the outermost.

Parameters ​

ParameterType
argsCallInterceptorArgs
nextCallInterceptorNext

Returns ​

AsyncResult<unknown, CallError>

Example ​

Retry timed-out calls once

typescript
const retryOnce: CallInterceptor = (args, next) =>
  next().flatMapErr((error) =>
    error instanceof RpcTimeoutError ? next() : ErrAsync(error),
  );

CallInterceptorArgs ​

ts
type CallInterceptorArgs = object;

Defined in: packages/client/src/interceptors.ts:74

Arguments a call interceptor observes. request is the pre-validation request payload.

Properties ​

PropertyTypeDescriptionDefined in
optionsCallOptionsPer-call options (timeoutMs, publishOptions).packages/client/src/interceptors.ts:80
requestunknownThe (not yet validated) request payload.packages/client/src/interceptors.ts:78
rpcNamestringThe contract rpcs key being called.packages/client/src/interceptors.ts:76

CallInterceptorNext ​

ts
type CallInterceptorNext = (patch?) => AsyncResult<unknown, CallError>;

Defined in: packages/client/src/interceptors.ts:87

Continuation a call interceptor calls to run the rest of the chain. The resolved value is the RPC response (typed at the public call() boundary).

Parameters ​

ParameterType
patch?{ options?: CallOptions; request?: unknown; }
patch.options?CallOptions
patch.request?unknown

Returns ​

AsyncResult<unknown, CallError>

CallOptions ​

ts
type CallOptions = object;

Defined in: packages/client/src/client.ts:146

Per-call options for client.call().

Properties ​

PropertyTypeDescriptionDefined in
publishOptions?Omit<AmqpClientPublishOptions, "replyTo" | "correlationId">Optional AMQP message properties to merge into the request. replyTo and correlationId are managed by the client and cannot be overridden.packages/client/src/client.ts:160
timeoutMsnumberMaximum time in ms to wait for an RPC reply. If exceeded, the call resolves to Err(RpcTimeoutError) and the in-memory correlation entry is cleared. A late reply arriving after the timeout is silently dropped. Required: RPC without a timeout is a footgun.packages/client/src/client.ts:154

ClientInferPublisherInput ​

ts
type ClientInferPublisherInput<TContract, TName> = PublisherInferInput<InferPublisher<TContract, TName>>;

Defined in: packages/client/src/types.ts:46

Input type accepted by client.publish(name, ...) for a specific publisher.

Type Parameters ​

Type Parameter
TContract extends ContractDefinition
TName extends InferPublisherNames<TContract>

ClientInferRpcErrors ​

ts
type ClientInferRpcErrors<TContract, TName> = InferRpc<TContract, TName> extends RpcDefinition<MessageDefinition, MessageDefinition, QueueEntry, infer TErrors> ? TErrors extends RpcErrorMap ? { [K in keyof TErrors & string]: RpcError<K, InferSchemaOutput<TErrors[K]["payload"]>> }[keyof TErrors & string] : never : never;

Defined in: packages/client/src/types.ts:94

Typed error union for client.call(name, ...) — one RpcError<code, data> member per entry in the RPC's declared errors map, with data typed as the declared schema's output (the client re-validates error data when the reply arrives). Resolves to never when the RPC declares no errors, so the call's error union stays purely transport-level.

Type Parameters ​

Type Parameter
TContract extends ContractDefinition
TName extends InferRpcNames<TContract>

ClientInferRpcRequestInput ​

ts
type ClientInferRpcRequestInput<TContract, TName> = InferRpc<TContract, TName> extends RpcDefinition<infer TRequest, MessageDefinition> ? TRequest extends MessageDefinition ? InferSchemaInput<TRequest["payload"]> : never : never;

Defined in: packages/client/src/types.ts:64

Input type accepted by client.call(name, request, ...).

Type Parameters ​

Type Parameter
TContract extends ContractDefinition
TName extends InferRpcNames<TContract>

ClientInferRpcResponseOutput ​

ts
type ClientInferRpcResponseOutput<TContract, TName> = InferRpc<TContract, TName> extends RpcDefinition<MessageDefinition, infer TResponse> ? TResponse extends MessageDefinition ? InferSchemaOutput<TResponse["payload"]> : never : never;

Defined in: packages/client/src/types.ts:77

Output (validated) response type returned by client.call(name, ...).

Type Parameters ​

Type Parameter
TContract extends ContractDefinition
TName extends InferRpcNames<TContract>

CreateClientOptions ​

ts
type CreateClientOptions<TContract> = object;

Defined in: packages/client/src/client.ts:105

Options for creating a client

Type Parameters ​

Type Parameter
TContract extends ContractDefinition

Properties ​

PropertyTypeDescriptionDefined in
callInterceptors?readonly CallInterceptor[]Interceptors wrapping every call(...) round trip (request validation, publish, reply await): the first entry is the outermost.packages/client/src/client.ts:140
connectionOptions?AmqpConnectionManagerOptions-packages/client/src/client.ts:108
connectTimeoutMs?number | nullMaximum time in ms to wait for the AMQP connection to become ready before create() resolves to an Err(TechnicalError). Defaults to 30s (the AmqpClient's DEFAULT_CONNECT_TIMEOUT_MS). Pass null to disable the timeout and let amqp-connection-manager retry indefinitely.packages/client/src/client.ts:128
contractTContract-packages/client/src/client.ts:106
defaultPublishOptions?PublishOptionsDefault publish options that will be applied to all publish operations. These can be overridden by options passed to the publish method. By default, persistent is set to true for message durability.packages/client/src/client.ts:121
logger?Logger-packages/client/src/client.ts:109
publishInterceptors?readonly PublishInterceptor[]Interceptors wrapping every publish(...): the first entry is the outermost. Each can patch the message/options, observe the outcome, retry by calling next again, or short-circuit. A patched message is validated exactly like the caller's original.packages/client/src/client.ts:135
telemetry?TelemetryProviderOptional telemetry provider for tracing and metrics. If not provided, uses the default provider which attempts to load OpenTelemetry. OpenTelemetry instrumentation is automatically enabled if @opentelemetry/api is installed.packages/client/src/client.ts:115
urlsConnectionUrl[]-packages/client/src/client.ts:107

PublishInterceptor ​

ts
type PublishInterceptor = (args, next) => AsyncResult<void, PublishError>;

Defined in: packages/client/src/interceptors.ts:65

Intercepts client.publish(...): runs outside validation and publishing, so it can stamp headers (e.g. trace context), transform the payload, retry by calling next again, or short-circuit by returning without calling next. The first interceptor in the array is the outermost.

Parameters ​

ParameterType
argsPublishInterceptorArgs
nextPublishInterceptorNext

Returns ​

AsyncResult<void, PublishError>

Example ​

Stamp a correlation header on every outgoing message

typescript
const stampTenant: PublishInterceptor = (args, next) =>
  next({
    options: {
      ...args.options,
      headers: { ...args.options.headers, 'x-tenant-id': currentTenant() },
    },
  });

PublishInterceptorArgs ​

ts
type PublishInterceptorArgs = object;

Defined in: packages/client/src/interceptors.ts:29

Arguments a publish interceptor observes. message is the pre-validation payload — a patched message goes through schema validation exactly like the caller's original.

Properties ​

PropertyTypeDescriptionDefined in
messageunknownThe (not yet validated) message payload.packages/client/src/interceptors.ts:33
optionsPublishOptionsPer-call publish options (defaults are merged later, inside the client).packages/client/src/interceptors.ts:35
publisherNamestringThe contract publishers key being published.packages/client/src/interceptors.ts:31

PublishInterceptorNext ​

ts
type PublishInterceptorNext = (patch?) => AsyncResult<void, PublishError>;

Defined in: packages/client/src/interceptors.ts:43

Continuation a publish interceptor calls to run the rest of the chain. The optional patch replaces message and/or options for everything downstream (inner interceptors, validation, and the publish itself).

Parameters ​

ParameterType
patch?{ message?: unknown; options?: PublishOptions; }
patch.message?unknown
patch.options?PublishOptions

Returns ​

AsyncResult<void, PublishError>

PublishOptions ​

ts
type PublishOptions = AmqpClientPublishOptions & object;

Defined in: packages/client/src/client.ts:93

Publish options that extend amqp-client's PublishOptions with optional compression support.

Type Declaration ​

NameTypeDescriptionDefined in
compression?CompressionAlgorithmOptional compression algorithm to use for the message payload. When specified, the message will be compressed using the chosen algorithm and the contentEncoding header will be set automatically.packages/client/src/client.ts:99

Functions ​

isRpcError() ​

ts
function isRpcError(error): error is RpcError<string, unknown>;

Defined in: packages/core/dist/index.d.mts:86

Type guard to check if an error is an RpcError.

Narrowing to a specific code (and thus a typed data) is done on the code property after the guard, or via matchTags on the _tag.

Parameters ​

ParameterType
errorunknown

Returns ​

error is RpcError<string, unknown>

Released under the MIT License.

Copyright © 2026 Benoit TRAVERS

Part ofbtravstack