@temporal-contract/worker / activity

activity

Classes

ActivityDefinitionNotFoundError

Defined in: packages/worker/src/errors.ts:89

Error thrown when an activity definition is not found in the contract

Extends

TaggedErrorInstance<"@temporal-contract/ActivityDefinitionNotFoundError", { activityName: string; availableDefinitions: readonly string[]; }>

Constructors

Constructor

new ActivityDefinitionNotFoundError(activityName, availableDefinitions?): ActivityDefinitionNotFoundError;

Defined in: packages/worker/src/errors.ts:96

Parameters

Parameter	Type	Default value
`activityName`	`string`	`undefined`
`availableDefinitions`	readonly `string`[]	`[]`

Returns

ActivityDefinitionNotFoundError

Overrides

TaggedError(
  ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG,
  { name: "ActivityDefinitionNotFoundError" },
)<{
  activityName: string;
  availableDefinitions: readonly string[];
}>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
`_tag`	`readonly`	`"@temporal-contract/ActivityDefinitionNotFoundError"`	`TaggedError( ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG, { name: "ActivityDefinitionNotFoundError" }, )._tag`	node_modules/.pnpm/unthrown@5.7.0/node_modules/unthrown/dist/index.d.mts:2011
`activityName`	`readonly`	`string`	`TaggedError( ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG, { name: "ActivityDefinitionNotFoundError" }, ).activityName`	packages/worker/src/errors.ts:93
`availableDefinitions`	`readonly`	readonly `string`[]	`TaggedError( ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG, { name: "ActivityDefinitionNotFoundError" }, ).availableDefinitions`	packages/worker/src/errors.ts:94
`cause?`	`public`	`unknown`	`TaggedError( ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG, { name: "ActivityDefinitionNotFoundError" }, ).cause`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
`message`	`public`	`string`	`TaggedError( ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG, { name: "ActivityDefinitionNotFoundError" }, ).message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	`TaggedError( ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG, { name: "ActivityDefinitionNotFoundError" }, ).name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`stack?`	`public`	`string`	`TaggedError( ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG, { name: "ActivityDefinitionNotFoundError" }, ).stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

ActivityInputValidationError

Defined in: packages/worker/src/errors.ts:124

Error thrown when activity input validation fails.

Extends

ValidationError

Constructors

Constructor

new ActivityInputValidationError(activityName, issues): ActivityInputValidationError;

Defined in: packages/worker/src/errors.ts:127

Parameters

Parameter	Type
`activityName`	`string`
`issues`	readonly `Issue`[]

Returns

ActivityInputValidationError

Overrides

ValidationError.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`activityName`	`readonly`	`string`	-	-	packages/worker/src/errors.ts:128
`category?`	`readonly`	`"BENIGN"` \| `null`	-	`WorkflowOutputValidationError`.`category`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ActivityOutputValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	`WorkflowOutputValidationError`.`details`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:111
`direction`	`readonly`	`"input"`	-	-	packages/worker/src/errors.ts:125
`failure?`	`public`	`IFailure`	The original failure that constructed this error. Only present if this error was generated from an external operation.	`ValidationError`.`failure`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:78
`issues`	`readonly`	readonly `Issue`[]	-	`ValidationError`.`issues`	packages/worker/src/errors.ts:61
`message`	`public`	`string`	-	`ValidationError`.`message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	-	`ValidationError`.`name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`nextRetryDelay?`	`readonly`	`any`	-	`WorkflowOutputValidationError`.`nextRetryDelay`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	`WorkflowOutputValidationError`.`nonRetryable`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:110
`stack?`	`public`	`string`	-	`ValidationError`.`stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
`type?`	`readonly`	`string` \| `null`	-	`WorkflowOutputValidationError`.`type`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:109
`stackTraceLimit`	`static`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	`ValidationError`.`stackTraceLimit`	node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:67

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

ValidationError.captureStackTrace

create()

static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:130

Create a new ApplicationFailure.

By default, will be retryable (unless its type is included in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type
`options`	`ApplicationFailureOptions`

Returns

ApplicationFailure

Inherited from

ValidationError.create

fromError()

static fromError(error, overrides?): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:124

Create a new ApplicationFailure from an Error object.

First calls ensureApplicationFailure | `ensureApplicationFailure(error)` and then overrides any fields provided in overrides.

Parameters

Parameter	Type
`error`	`unknown`
`overrides?`	`ApplicationFailureOptions`

Returns

ApplicationFailure

Inherited from

ValidationError.fromError

nonRetryable()

static nonRetryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:150

Get a new ApplicationFailure with the nonRetryable flag set to true.

When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if type is not listed in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

Inherited from

ValidationError.nonRetryable

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:55

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

ValidationError.prepareStackTrace

retryable()

static retryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:139

Get a new ApplicationFailure with the nonRetryable flag set to false. Note that this error will still not be retried if its type is included in RetryPolicy.nonRetryableErrorTypes.

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type (used by RetryPolicy.nonRetryableErrorTypes)
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Error thrown when activity output validation fails.

Extends

ValidationError

Constructors

Constructor

new ActivityOutputValidationError(activityName, issues): ActivityOutputValidationError;

Defined in: packages/worker/src/errors.ts:143

Parameters

Parameter	Type
`activityName`	`string`
`issues`	readonly `Issue`[]

Returns

ActivityOutputValidationError

Overrides

ValidationError.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`activityName`	`readonly`	`string`	-	-	packages/worker/src/errors.ts:144
`category?`	`readonly`	`"BENIGN"` \| `null`	-	`ValidationError`.`category`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	`ValidationError`.`details`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:111
`direction`	`readonly`	`"output"`	-	-	packages/worker/src/errors.ts:141
`failure?`	`public`	`IFailure`	The original failure that constructed this error. Only present if this error was generated from an external operation.	`ValidationError`.`failure`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:78
`issues`	`readonly`	readonly `Issue`[]	-	`ValidationError`.`issues`	packages/worker/src/errors.ts:61
`message`	`public`	`string`	-	`ValidationError`.`message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	-	`ValidationError`.`name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`nextRetryDelay?`	`readonly`	`any`	-	`ValidationError`.`nextRetryDelay`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	`ValidationError`.`nonRetryable`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:110
`stack?`	`public`	`string`	-	`ValidationError`.`stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
`type?`	`readonly`	`string` \| `null`	-	`ValidationError`.`type`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:109
`stackTraceLimit`	`static`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	`ValidationError`.`stackTraceLimit`	node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:67

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

ValidationError.captureStackTrace

create()

static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:130

Create a new ApplicationFailure.

By default, will be retryable (unless its type is included in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type
`options`	`ApplicationFailureOptions`

Returns

ApplicationFailure

Inherited from

ValidationError.create

fromError()

static fromError(error, overrides?): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:124

Create a new ApplicationFailure from an Error object.

First calls ensureApplicationFailure | `ensureApplicationFailure(error)` and then overrides any fields provided in overrides.

Parameters

Parameter	Type
`error`	`unknown`
`overrides?`	`ApplicationFailureOptions`

Returns

ApplicationFailure

Inherited from

ValidationError.fromError

nonRetryable()

static nonRetryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:150

Get a new ApplicationFailure with the nonRetryable flag set to true.

When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if type is not listed in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

Inherited from

ValidationError.nonRetryable

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:55

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

ValidationError.prepareStackTrace

retryable()

static retryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:139

Get a new ApplicationFailure with the nonRetryable flag set to false. Note that this error will still not be retried if its type is included in RetryPolicy.nonRetryableErrorTypes.

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type (used by RetryPolicy.nonRetryableErrorTypes)
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

Inherited from

ValidationError.retryable

ApplicationFailure

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:108

ApplicationFailures are used to communicate application-specific failures in Workflows and Activities.

The type property is matched against RetryPolicy.nonRetryableErrorTypes to determine if an instance of this error is retryable. Another way to avoid retrying is by setting the nonRetryable flag to true.

In Workflows, if you throw a non-ApplicationFailure, the Workflow Task will fail and be retried. If you throw an ApplicationFailure, the Workflow Execution will fail.

In Activities, you can either throw an ApplicationFailure or another Error to fail the Activity Task. In the latter case, the Error will be converted to an ApplicationFailure. The conversion is done as following:

type is set to error.constructor?.name ?? error.name
message is set to error.message
nonRetryable is set to false
details are set to null
stack trace is copied from the original error

When an Activity Execution fails, the ApplicationFailure from the last Activity Task will be the cause of the ActivityFailure thrown in the Workflow.

Extends

TemporalFailure

Extended by

ValidationError

Constructors

Constructor

new ApplicationFailure(
   message?, 
   type?, 
   nonRetryable?, 
   details?, 
   cause?, 
   nextRetryDelay?, 
   category?
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:117

Alternatively, use fromError or create.

Parameters

Parameter	Type
`message?`	`string` \| `null`
`type?`	`string` \| `null`
`nonRetryable?`	`boolean` \| `null`
`details?`	`unknown`[] \| `null`
`cause?`	`Error`
`nextRetryDelay?`	`any`
`category?`	`"BENIGN"` \| `null`

Returns

ApplicationFailure

Overrides

TemporalFailure.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`category?`	`readonly`	`"BENIGN"` \| `null`	-	-	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ActivityOutputValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	-	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:111
`failure?`	`public`	`IFailure`	The original failure that constructed this error. Only present if this error was generated from an external operation.	`TemporalFailure.failure`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:78
`message`	`public`	`string`	-	`TemporalFailure.message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	-	`TemporalFailure.name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`nextRetryDelay?`	`readonly`	`any`	-	-	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	-	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:110
`stack?`	`public`	`string`	-	`TemporalFailure.stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
`type?`	`readonly`	`string` \| `null`	-	-	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:109
`stackTraceLimit`	`static`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	`TemporalFailure.stackTraceLimit`	node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:67

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

TemporalFailure.captureStackTrace

create()

static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:130

Create a new ApplicationFailure.

By default, will be retryable (unless its type is included in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type
`options`	`ApplicationFailureOptions`

Returns

ApplicationFailure

fromError()

static fromError(error, overrides?): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:124

Create a new ApplicationFailure from an Error object.

First calls ensureApplicationFailure | `ensureApplicationFailure(error)` and then overrides any fields provided in overrides.

Parameters

Parameter	Type
`error`	`unknown`
`overrides?`	`ApplicationFailureOptions`

Returns

ApplicationFailure

nonRetryable()

static nonRetryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:150

Get a new ApplicationFailure with the nonRetryable flag set to true.

When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if type is not listed in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:55

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

TemporalFailure.prepareStackTrace

retryable()

static retryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:139

Get a new ApplicationFailure with the nonRetryable flag set to false. Note that this error will still not be retried if its type is included in RetryPolicy.nonRetryableErrorTypes.

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type (used by RetryPolicy.nonRetryableErrorTypes)
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

ContractError

Defined in: packages/contract/dist/errors-impl-BxWuCbUU.d.mts:45

A typed domain error declared on a contract's errors map.

One class covers every declared error; the errorName field is the per-error discriminant (it equals the key in the contract's errors map and the ApplicationFailure.type on the wire). Narrow a union with it:

if (result.isErr() && result.error instanceof ContractError) {
  switch (result.error.errorName) {
    case "PaymentDeclined":
      result.error.data; // { reason: string }
  }
}

The unthrown _tag ("@temporal-contract/ContractError") discriminates a ContractError from the other tagged errors in a Result's error channel (e.g. via result.match({ errCases: (m) => m.with(P.tag("@temporal-contract/ContractError"), …) })); errorName then narrows to the concrete declared error.

Extends

ContractError_base<{ cause?: unknown; data: TData; errorName: TName; }>

Type Parameters

Type Parameter	Default type
`TName` extends `string`	`string`
`TData`	`unknown`

Constructors

Constructor

new ContractError<TName, TData>(args): ContractError<TName, TData>;

Defined in: packages/contract/dist/errors-impl-BxWuCbUU.d.mts:52

Parameters

Parameter	Type
`args`	{ `cause?`: `unknown`; `data`: `TData`; `errorName`: `TName`; `message`: `string`; }
`args.cause?`	`unknown`
`args.data`	`TData`
`args.errorName`	`TName`
`args.message`	`string`

Returns

ContractError<TName, TData>

Overrides

ContractError_base<{
  / Declared error name — the ApplicationFailure.type discriminator. /
  errorName: TName;
  / Structured payload validated against the declared data schema. /
  data: TData;
  cause?: unknown;
}>.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`_tag`	`readonly`	`"@temporal-contract/ContractError"`	-	`ContractError_base._tag`	node_modules/.pnpm/unthrown@5.7.0/node_modules/unthrown/dist/index.d.mts:2011
`cause?`	`public`	`unknown`	-	`ActivityDefinitionNotFoundError`.`cause`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
`data`	`readonly`	`TData`	Structured payload validated against the declared `data` schema.	`ContractError_base.data`	packages/contract/dist/errors-impl-BxWuCbUU.d.mts:49
`errorName`	`readonly`	`TName`	Declared error name — the `ApplicationFailure.type` discriminator.	`ContractError_base.errorName`	packages/contract/dist/errors-impl-BxWuCbUU.d.mts:47
`message`	`public`	`string`	-	`ContractError_base.message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	-	`ContractError_base.name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`stack?`	`public`	`string`	-	`ContractError_base.stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

ContractErrorDataValidationError

Defined in: packages/worker/src/errors.ts:258

Error thrown when a contract-declared error's data payload fails validation against its declared schema at the Temporal boundary, or when an implementation surfaces a ContractError whose name isn't declared on its activity/workflow. Both are deterministic contract-misuse bugs, so the failure is terminal (nonRetryable) like the other validation errors.

Extends

ValidationError

Constructors

Constructor

new ContractErrorDataValidationError(errorName, issues): ContractErrorDataValidationError;

Defined in: packages/worker/src/errors.ts:259

Parameters

Parameter	Type
`errorName`	`string`
`issues`	readonly `Issue`[]

Returns

ContractErrorDataValidationError

Overrides

ValidationError.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`category?`	`readonly`	`"BENIGN"` \| `null`	-	`ValidationError`.`category`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	`ValidationError`.`details`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:111
`errorName`	`readonly`	`string`	-	-	packages/worker/src/errors.ts:260
`failure?`	`public`	`IFailure`	The original failure that constructed this error. Only present if this error was generated from an external operation.	`ValidationError`.`failure`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:78
`issues`	`readonly`	readonly `Issue`[]	-	`ValidationError`.`issues`	packages/worker/src/errors.ts:61
`message`	`public`	`string`	-	`ValidationError`.`message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	-	`ValidationError`.`name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`nextRetryDelay?`	`readonly`	`any`	-	`ValidationError`.`nextRetryDelay`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	`ValidationError`.`nonRetryable`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:110
`stack?`	`public`	`string`	-	`ValidationError`.`stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
`type?`	`readonly`	`string` \| `null`	-	`ValidationError`.`type`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:109
`stackTraceLimit`	`static`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	`ValidationError`.`stackTraceLimit`	node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:67

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

ValidationError.captureStackTrace

create()

static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:130

Create a new ApplicationFailure.

By default, will be retryable (unless its type is included in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type
`options`	`ApplicationFailureOptions`

Returns

ApplicationFailure

Inherited from

ValidationError.create

fromError()

static fromError(error, overrides?): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:124

Create a new ApplicationFailure from an Error object.

First calls ensureApplicationFailure | `ensureApplicationFailure(error)` and then overrides any fields provided in overrides.

Parameters

Parameter	Type
`error`	`unknown`
`overrides?`	`ApplicationFailureOptions`

Returns

ApplicationFailure

Inherited from

ValidationError.fromError

nonRetryable()

static nonRetryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:150

Get a new ApplicationFailure with the nonRetryable flag set to true.

When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if type is not listed in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

Inherited from

ValidationError.nonRetryable

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:55

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

ValidationError.prepareStackTrace

retryable()

static retryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:139

Get a new ApplicationFailure with the nonRetryable flag set to false. Note that this error will still not be retried if its type is included in RetryPolicy.nonRetryableErrorTypes.

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type (used by RetryPolicy.nonRetryableErrorTypes)
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

Inherited from

ValidationError.retryable

`abstract` ValidationError

Defined in: packages/worker/src/errors.ts:57

Base class for the contract's runtime validation failures — workflow and activity input/output, plus query/update payloads. (Invalid signal payloads are not errors: signals are fire-and-forget, so the worker drops and logs them instead of failing the execution.)

These extend Temporal's ApplicationFailure with nonRetryable: true rather than a plain Error, and that distinction is load-bearing. The TypeScript SDK classifies a non-TemporalFailure thrown from workflow code as a Workflow Task failure — presumed to be a transient code bug or non-determinism — and retries the task indefinitely, leaving the execution silently Running forever (it looks like the worker "hung"). Only a TemporalFailure such as ApplicationFailure fails the Workflow Execution terminally. The same logic applies at the activity boundary, where Temporal's default retry policy has unlimited attempts: a plain Error would retry forever too.

Contract validation failures are deterministic — the schema is static, so bad input/output never becomes valid on replay or retry — so they are surfaced as non-retryable, failing fast with a clear error instead of an infinite retry loop.

The concrete subclass name is passed through as the failure type, so it stays discriminable after crossing Temporal's serialization boundary (where the JS class identity is lost) via failure.type. The failing field path is carried in the human-readable message (see summarizeIssues). The raw issues remain available as a property for in-process inspection.

See issue #251.

Extends

ApplicationFailure

Extended by

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`category?`	`readonly`	`"BENIGN"` \| `null`	-	`WorkflowOutputValidationError`.`category`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ActivityOutputValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	`WorkflowOutputValidationError`.`details`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:111
`failure?`	`public`	`IFailure`	The original failure that constructed this error. Only present if this error was generated from an external operation.	`ApplicationFailure`.`failure`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:78
`issues`	`readonly`	readonly `Issue`[]	-	-	packages/worker/src/errors.ts:61
`message`	`public`	`string`	-	`ApplicationFailure`.`message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	-	`ApplicationFailure`.`name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`nextRetryDelay?`	`readonly`	`any`	-	`WorkflowOutputValidationError`.`nextRetryDelay`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	`WorkflowOutputValidationError`.`nonRetryable`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:110
`stack?`	`public`	`string`	-	`ApplicationFailure`.`stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
`type?`	`readonly`	`string` \| `null`	-	`WorkflowOutputValidationError`.`type`	node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:109
`stackTraceLimit`	`static`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	`ApplicationFailure`.`stackTraceLimit`	node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:67

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

ApplicationFailure.captureStackTrace

create()

static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:130

Create a new ApplicationFailure.

By default, will be retryable (unless its type is included in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type
`options`	`ApplicationFailureOptions`

Returns

ApplicationFailure

Inherited from

ApplicationFailure.create

fromError()

static fromError(error, overrides?): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:124

Create a new ApplicationFailure from an Error object.

First calls ensureApplicationFailure | `ensureApplicationFailure(error)` and then overrides any fields provided in overrides.

Parameters

Parameter	Type
`error`	`unknown`
`overrides?`	`ApplicationFailureOptions`

Returns

ApplicationFailure

Inherited from

ApplicationFailure.fromError

nonRetryable()

static nonRetryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:150

Get a new ApplicationFailure with the nonRetryable flag set to true.

When thrown from an Activity or Workflow, the Activity or Workflow will not be retried (even if type is not listed in RetryPolicy.nonRetryableErrorTypes).

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

Inherited from

ApplicationFailure.nonRetryable

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@26.4.0/node_modules/@types/node/globals.d.ts:55

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

ApplicationFailure.prepareStackTrace

retryable()

static retryable(
   message?, 
   type?, 
   ...details
): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.23.0/node_modules/@temporalio/common/lib/failure.d.ts:139

Get a new ApplicationFailure with the nonRetryable flag set to false. Note that this error will still not be retried if its type is included in RetryPolicy.nonRetryableErrorTypes.

Parameters

Parameter	Type	Description
`message?`	`string` \| `null`	Optional error message
`type?`	`string` \| `null`	Optional error type (used by RetryPolicy.nonRetryableErrorTypes)
...`details?`	`unknown`[]	Optional details about the failure. Serialized by the Worker's PayloadConverter.

Returns

ApplicationFailure

Inherited from

ApplicationFailure.retryable

Type Aliases

ActivitiesHandler

type ActivitiesHandler<TContract> = TContract["activities"] extends Record<string, ActivityDefinition> ? ActivitiesImplementations<TContract["activities"]> : object & UnionToIntersection<{ [TWorkflow in keyof TContract["workflows"]]: TContract["workflows"][TWorkflow]["activities"] extends Record<string, ActivityDefinition> ? ActivitiesImplementations<TContract["workflows"][TWorkflow]["activities"]> : {} }[keyof TContract["workflows"]]>;

Defined in: packages/worker/src/activity.ts:790

Activities handler ready for Temporal's Worker.create({ activities }).

Flat shape: every activity (global + all workflow-local) lives at the root of the returned map. See the doc comment on ContractResultActivitiesImplementations for why the input you write is nested by workflow while this output is flat.

Type Parameters

Type Parameter
`TContract` extends `ContractDefinition`

ActivityIdempotencyKeyOf

type ActivityIdempotencyKeyOf<TActivity> = TActivity["idempotencyKey"] extends (input) => string ? string : undefined;

Defined in: packages/worker/src/activity.ts:296

string for an activity that declares idempotencyKey, undefined for one that does not.

Type Parameters

Type Parameter
`TActivity` extends `ActivityDefinition`

ActivityImplementationFor

type ActivityImplementationFor<TContract, TWorkflowName, TActivityName, TContext> = TContract["workflows"][TWorkflowName]["activities"] extends Record<string, ActivityDefinition> ? ResultActivityImplementation<TContract["workflows"][TWorkflowName]["activities"][TActivityName], TContext> : never;

Defined in: packages/worker/src/activity.ts:423

The correctly-typed implementation function for one workflow-local activity of a contract. Lets a standalone implementation typecheck outside the declareActivitiesHandler call so it can live in its own module (with precise args/helpers inference) and be assigned into the nested implementations map later:

Type Parameters

Type Parameter	Default type
`TContract` extends `ContractDefinition`	-
`TWorkflowName` extends keyof `TContract`[`"workflows"`] & `string`	-
`TActivityName` extends keyof `TContract`[`"workflows"`][`TWorkflowName`][`"activities"`] & `string`	-
`TContext` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`EmptyContext`

Example

const validateOrder: ActivityImplementationFor<
  typeof myContract,
  "orderWorkflow",
  "validateOrder"
> = ({ errors, input }) =>
  input.orderId ? OkAsync({ valid: true }) : ErrAsync(errors.EmptyOrder({}));

declareActivitiesHandler({
  contract: myContract,
  activities: { orderWorkflow: { validateOrder } },
});

The optional TContext parameter mirrors the handler's injected context (createContext seed + middleware accumulation); leave it defaulted when the implementation doesn't read helpers.context.

See GlobalActivityImplementationFor for the contract-global variant.

ActivityImplementationHelpers

type ActivityImplementationHelpers<TActivity, TContext> = object;

Defined in: packages/worker/src/activity.ts:271

First argument passed to every activity implementation — everything the invocation carries, including its input.

errors — typed constructors for the errors declared on this activity's contract entry. Err(errors.PaymentDeclined({ reason })) surfaces to the calling workflow as a typed, schema-validated error.
context — the accumulated typed context: the createContext seed plus everything injected by the middleware chain via next({ context }) (an empty object when neither is configured). Use it to inject dependencies (service clients, repositories) instead of closing over them at module scope.
input — the validated input, the SAME value the second parameter carries. It is on the record so a whole implementation is one destructuring, which is oRPC's own shape and its own word for it (ProcedureHandlerOptions carries input, and the handler still takes it positionally). One name across the three transports is the point: a developer moving between them destructures input in each.

Type Parameters

Type Parameter	Default type
`TActivity` extends `ActivityDefinition`	-
`TContext` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`EmptyContext`

Properties

Property	Modifier	Type	Description	Defined in
`context`	`readonly`	`TContext`	-	packages/worker/src/activity.ts:276
`errors`	`readonly`	`ActivityErrorConstructorsOf`<`TActivity`>	-	packages/worker/src/activity.ts:275
`idempotencyKey`	`readonly`	`ActivityIdempotencyKeyOf`<`TActivity`>	The activity's idempotency key for this invocation — `string` when the contract declares `idempotencyKey`, and `undefined` when it does not, so reaching for a key that was never declared is a type error rather than a silent `undefined` reaching a payment gateway. Derived from the validated input, verbatim. Stable across retries of this activity, across worker crashes, and across a fresh workflow execution with the same input — see `idempotencyKey` on the contract's `defineActivity`.	packages/worker/src/activity.ts:289
`input`	`readonly`	`WorkerInferInput`<`TActivity`>	-	packages/worker/src/activity.ts:277

ActivityInvocationInfo

type ActivityInvocationInfo = object;

Defined in: packages/worker/src/activity.ts:459

Per-invocation description handed to middleware and createContext.

Properties

Property	Modifier	Type	Description	Defined in
`activityName`	`readonly`	`string`	Flat runtime name of the activity (as Temporal sees it).	packages/worker/src/activity.ts:461
`workflowName`	`readonly`	`string` \| `undefined`	Owning workflow for workflow-local activities; `undefined` for global ones. Shared-definition caveat: `workflowName` identifies the scope the implementation was registered under, not the workflow that is calling right now (Temporal's flat activity namespace erases the caller). When one `defineActivity` object is referenced from several scopes and implemented with the same function reference, the activity registers once under the first scope encountered — global first, then the contract's workflow declaration order — and every invocation reports that scope's `workflowName`. To know the actual calling workflow inside an activity, read `Context.current().info.workflowType` from `@temporalio/activity`.	packages/worker/src/activity.ts:477

ActivityMiddleware

type ActivityMiddleware<TContextIn, TContextOut> = (invocation, next) => AsyncResult<unknown, 
  | ApplicationFailure
  | AnyContractError>;

Defined in: packages/worker/src/activity.ts:556

Contract-aware middleware wrapped around every activity implementation.

Middleware runs inside the validation boundary — invocation.input is already validated against the contract's input schema, and whatever the chain returns on the ok channel is still validated against the output schema afterwards. Because it operates on the unthrown AsyncResult rather than thrown exceptions, a middleware observes modeled failures (ApplicationFailure, contract errors) on the err channel and can short-circuit by returning its own result without calling next.

Context accumulates through the chain: TContextIn is what this middleware receives (the createContext seed for the outermost one), TContextOut extends TContextIn is what it passes downstream via next({ context }). A middleware that only reads context leaves both parameters equal and stays valid unchanged. Compose typed chains with composeActivityMiddleware; pin a middleware's context types without a variable annotation via declareActivityMiddleware.

Type Parameters

Type Parameter	Default type
`TContextIn` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`EmptyContext`
`TContextOut` extends `TContextIn`	`TContextIn`

Parameters

Parameter	Type
`invocation`	`ActivityInvocationInfo` & `object`
`next`	`ActivityMiddlewareNext`<`TContextOut`>

Returns

AsyncResult<unknown, | ApplicationFailure | AnyContractError>

Examples

Log every activity invocation and its outcome (read-only)

import { ApplicationFailure } from '@temporal-contract/worker/activity';
import { P } from "unthrown";

const logging: ActivityMiddleware = ({ activityName, workflowName }, next) =>
  next().tapErrCases((matcher) =>
    matcher.with(
      P.instanceOf(ApplicationFailure),
      P.tag("@temporal-contract/ContractError"),
      (error) => {
        logger.warn({ activityName, workflowName, error }, "activity failed");
      },
    ),
  );

Guard-and-narrow: inject a tenant id for everything downstream

const auth = declareActivityMiddleware<EmptyContext, { tenantId: string }>(
  (invocation, next) => {
    const tenantId = readTenant(invocation.input);
    if (!tenantId) {
      return ErrAsync(ApplicationFailure.create({ type: "Unauthenticated", nonRetryable: true }));
    }
    return next({ context: { tenantId } });
  },
);

ActivityMiddlewareNext

type ActivityMiddlewareNext<TContextOut> = (opts?) => AsyncResult<unknown, 
  | ApplicationFailure
  | AnyContractError>;

Defined in: packages/worker/src/activity.ts:500

Continuation invoked by an ActivityMiddleware.

next() — forward unchanged.
next({ context: { ... } }) — extend the typed context flowing downstream; the patch is shallow-merged over the current context, so later middleware and the implementation see the accumulated value.
next({ input: ... }) — substitute the input. A substituted input is re-validated against the activity's input schema before it flows downstream — an invalid substitution fails terminally with ActivityInputValidationError, so middleware cannot smuggle unvalidated data past the contract boundary.

Type Parameters

Type Parameter	Default type
`TContextOut` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`EmptyContext`

Parameters

Parameter	Type
`opts?`	{ `context?`: `TContextOut`; `input?`: `unknown`; }
`opts.context?`	`TContextOut`
`opts.input?`	`unknown`

Returns

AsyncResult<unknown, | ApplicationFailure | AnyContractError>

AnyActivityMiddleware

type AnyActivityMiddleware = ActivityMiddleware<Record<string, unknown>, Record<string, unknown>>;

Defined in: packages/worker/src/activity.ts:572

Context-erased middleware shape used by the runtime chain.

AnyContractError

type AnyContractError = ContractError<string, unknown>;

Defined in: packages/contract/dist/errors-impl-BxWuCbUU.d.mts:63

Widest ContractError instantiation — useful as a constraint or for instanceof-style narrowing before discriminating on errorName.

ContractErrorConstructors

type ContractErrorConstructors<TErrors> = { [K in keyof TErrors & string]: TErrors[K] extends { data: AnySchema } ? (data: InferErrorDataInput<TErrors[K]>, options?: ContractErrorOptions) => ContractError<K, InferErrorDataInput<TErrors[K]>> : (options?: ContractErrorOptions) => ContractError<K, undefined> };

Defined in: packages/contract/dist/errors-impl-BxWuCbUU.d.mts:91

Map of typed error constructors for a declared errors map, handed to implementations (activity helpers / workflow context). Errors with a data schema take the payload first; data-less errors take only options.

Type Parameters

Type Parameter
`TErrors` extends `Record`<`string`, `ErrorDefinition`>

ContractErrorOptions

type ContractErrorOptions = object;

Defined in: packages/contract/dist/errors-impl-BxWuCbUU.d.mts:69

Per-instance options accepted by a typed error constructor. The nonRetryable flag is deliberately absent: retry semantics live on the contract's ErrorDefinition, not the call site.

Properties

Property	Modifier	Type	Defined in
`cause?`	`readonly`	`unknown`	packages/contract/dist/errors-impl-BxWuCbUU.d.mts:71
`message?`	`readonly`	`string`	packages/contract/dist/errors-impl-BxWuCbUU.d.mts:70

DeclareActivitiesHandlerOptions

type DeclareActivitiesHandlerOptions<TContract, TContext, TInjected> = object;

Defined in: packages/worker/src/activity.ts:729

Options for declareActivitiesHandler.

Type Parameters

Type Parameter	Default type
`TContract` extends `ContractDefinition`	-
`TContext` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`EmptyContext`
`TInjected` extends `TContext`	`TContext`

Properties

Property	Type	Description	Defined in
`activities`	`NoInfer`<`ContractResultActivitiesImplementations`<`TContract`, `TInjected`>>	Nested implementations map mirroring the contract's structure — see ContractResultActivitiesImplementations. Wrapped in `NoInfer` so `TContract`/`TInjected` are inferred from `contract`/`middleware` only: letting TypeScript infer into the key-remapped mapped type breaks contextual typing of the implementation lambdas (their `args` degrade to implicit `any`).	packages/worker/src/activity.ts:744
`contract`	`TContract`	-	packages/worker/src/activity.ts:734
`createContext?`	(`info`) => `TContext` \| `Promise`<`TContext`>	Build the typed dependency context seed handed to the middleware chain and, accumulated, to every implementation as `helpers.context`. Invoked once per activity execution, so it can produce request-scoped values; close over singletons (DB pools, service clients) for per-worker dependencies. Omitted → the seed is an empty object. For scoped, resource-releasing contexts (per-invocation loggers, transactions), the recommended implementation is demesne's `Layer.forkScope` — see the "Dependency Injection" section of the activity-handlers guide.	packages/worker/src/activity.ts:757
`middleware?`	`ActivityMiddleware`<`TContext`, `TInjected`>	Contract-aware middleware wrapped around every activity implementation. Pass a single middleware, or a typed chain built with composeActivityMiddleware — the chain's final context type (`TInjected`) is what implementations receive as `helpers.context`. See ActivityMiddleware.	packages/worker/src/activity.ts:765

EmptyContext

type EmptyContext = Record<never, never>;

Defined in: packages/worker/src/activity.ts:485

The empty middleware context. Record<never, never> rather than {} so an empty context is a real "no properties" type instead of the anything-goes empty-object type. (Mirrors amqp-contract's EmptyContext.)

GlobalActivityImplementationFor

type GlobalActivityImplementationFor<TContract, TActivityName, TContext> = TContract["activities"] extends Record<string, ActivityDefinition> ? ResultActivityImplementation<TContract["activities"][TActivityName], TContext> : never;

Defined in: packages/worker/src/activity.ts:447

The correctly-typed implementation function for one global activity of a contract — the contract.activities-scoped sibling of ActivityImplementationFor.

Type Parameters

Type Parameter	Default type
`TContract` extends `ContractDefinition`	-
`TActivityName` extends keyof `TContract`[`"activities"`] & `string`	-
`TContext` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`EmptyContext`

Example

const sendEmail: GlobalActivityImplementationFor<typeof myContract, "sendEmail"> =
  ({ input: args }) => OkAsync({ sent: true });

QualifyFailureOptions

type QualifyFailureOptions = object;

Defined in: packages/worker/src/activity.ts:89

Options for qualifyFailure. expected is required — it is the triage decision that separates modeled failures from defects.

Properties

Property	Type	Description	Defined in
`details?`	`unknown`[]	Structured payload forwarded to the workflow (avoids parsing `message`).	packages/worker/src/activity.ts:117
`expected`	`ErrorClass` \| readonly `ErrorClass`[] \| ((`cause`) => `boolean`) \| `"any"`	Which rejection causes are anticipated and should be wrapped into the modeled ApplicationFailure: - an error-class constructor (matched with `instanceof`), - an array of error-class constructors (any match wraps), - a predicate `(cause: unknown) => boolean`, - the literal `"any"` — a deliberate, greppable escape hatch that wraps every rejection (the pre-v8 blanket behavior). Anything that doesn't match rides unthrown's defect channel instead: an unanticipated throw (a `TypeError` from a bug, an assertion failure) is not a domain outcome, and blanket-wrapping it would disguise the bug as the declared failure `type` and subject it to that type's retry semantics.	packages/worker/src/activity.ts:106
`message?`	`string`	Fallback message when the rejection is not an `Error` (default: `String(error)`).	packages/worker/src/activity.ts:108
`nonRetryable?`	`boolean`	Mark the failure non-retryable — Temporal stops retrying immediately. When omitted, a matched cause that is itself an `ApplicationFailure` with `nonRetryable: true` propagates its non-retryability (see remarks); set `false` explicitly to force the wrapped failure retryable.	packages/worker/src/activity.ts:115

Variables

ACTIVITY_CANCELLED_ERROR_TAG

const ACTIVITY_CANCELLED_ERROR_TAG: "@temporal-contract/ActivityCancelledError" = "@temporal-contract/ActivityCancelledError";

Defined in: packages/worker/src/error-tags.ts:24

_tag of ActivityCancelledError — a call to an activity was cancelled.

ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG

const ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG: "@temporal-contract/ActivityDefinitionNotFoundError" = "@temporal-contract/ActivityDefinitionNotFoundError";

Defined in: packages/worker/src/error-tags.ts:27

_tag of ActivityDefinitionNotFoundError — an implementation was supplied for an undeclared activity.

ACTIVITY_ERROR_TAG

const ACTIVITY_ERROR_TAG: "@temporal-contract/ActivityError" = "@temporal-contract/ActivityError";

Defined in: packages/worker/src/error-tags.ts:21

_tag of ActivityError — an activity call failed for a reason other than a declared contract error.

CHILD_WORKFLOW_CANCELLED_ERROR_TAG

const CHILD_WORKFLOW_CANCELLED_ERROR_TAG: "@temporal-contract/ChildWorkflowCancelledError" = "@temporal-contract/ChildWorkflowCancelledError";

Defined in: packages/worker/src/error-tags.ts:34

_tag of ChildWorkflowCancelledError — a child-workflow operation was cancelled.

CHILD_WORKFLOW_ERROR_TAG

const CHILD_WORKFLOW_ERROR_TAG: "@temporal-contract/ChildWorkflowError" = "@temporal-contract/ChildWorkflowError";

Defined in: packages/worker/src/error-tags.ts:31

_tag of ChildWorkflowError — a child-workflow operation failed.

CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG

const CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG: "@temporal-contract/ChildWorkflowNotFoundError" = "@temporal-contract/ChildWorkflowNotFoundError";

Defined in: packages/worker/src/error-tags.ts:37

_tag of ChildWorkflowNotFoundError — the child workflow isn't declared on the contract.

WORKFLOW_CANCELLED_ERROR_TAG

const WORKFLOW_CANCELLED_ERROR_TAG: "@temporal-contract/WorkflowCancelledError" = "@temporal-contract/WorkflowCancelledError";

Defined in: packages/worker/src/error-tags.ts:40

_tag of WorkflowCancelledError — a typed cancellation scope was cancelled.

Functions

composeActivityMiddleware()

Call Signature

function composeActivityMiddleware<TSeed, TA>(m1): ActivityMiddleware<TSeed, TA>;

Defined in: packages/worker/src/activity.ts:600

Compose middleware outermost-first into a single ActivityMiddleware whose context type accumulates across the chain — each middleware's TContextOut bounds the next one's TContextIn, so the composed result's out-context is the last middleware's. For chains longer than eight, nest: a composed chain is itself an ActivityMiddleware and can be the first argument of an outer composeActivityMiddleware call.

(Mirrors amqp-contract's composeMiddleware overload approach.)

Type Parameters

Type Parameter
`TSeed` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TA` extends `Record`<`string`, `unknown`> \| `EmptyContext`

Parameters

Parameter	Type
`m1`	`ActivityMiddleware`<`TSeed`, `TA`>

Returns

ActivityMiddleware<TSeed, TA>

Call Signature

function composeActivityMiddleware<TSeed, TA, TB>(m1, m2): ActivityMiddleware<TSeed, TB>;

Defined in: packages/worker/src/activity.ts:604

(Mirrors amqp-contract's composeMiddleware overload approach.)

Type Parameters

Type Parameter
`TSeed` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TA` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TB` extends `Record`<`string`, `unknown`> \| `EmptyContext`

Parameters

Parameter	Type
`m1`	`ActivityMiddleware`<`TSeed`, `TA`>
`m2`	`ActivityMiddleware`<`TA`, `TB`>

Returns

ActivityMiddleware<TSeed, TB>

Call Signature

function composeActivityMiddleware<TSeed, TA, TB, TC>(
   m1, 
   m2, 
   m3
): ActivityMiddleware<TSeed, TC>;

Defined in: packages/worker/src/activity.ts:609

(Mirrors amqp-contract's composeMiddleware overload approach.)

Type Parameters

Type Parameter
`TSeed` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TA` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TB` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TC` extends `Record`<`string`, `unknown`> \| `EmptyContext`

Parameters

Parameter	Type
`m1`	`ActivityMiddleware`<`TSeed`, `TA`>
`m2`	`ActivityMiddleware`<`TA`, `TB`>
`m3`	`ActivityMiddleware`<`TB`, `TC`>

Returns

ActivityMiddleware<TSeed, TC>

Call Signature

function composeActivityMiddleware<TSeed, TA, TB, TC, TD>(
   m1, 
   m2, 
   m3, 
   m4
): ActivityMiddleware<TSeed, TD>;

Defined in: packages/worker/src/activity.ts:619

(Mirrors amqp-contract's composeMiddleware overload approach.)

Type Parameters

Type Parameter
`TSeed` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TA` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TB` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TC` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TD` extends `Record`<`string`, `unknown`> \| `EmptyContext`

Parameters

Parameter	Type
`m1`	`ActivityMiddleware`<`TSeed`, `TA`>
`m2`	`ActivityMiddleware`<`TA`, `TB`>
`m3`	`ActivityMiddleware`<`TB`, `TC`>
`m4`	`ActivityMiddleware`<`TC`, `TD`>

Returns

ActivityMiddleware<TSeed, TD>

Call Signature

function composeActivityMiddleware<TSeed, TA, TB, TC, TD, TE>(
   m1, 
   m2, 
   m3, 
   m4, 
   m5
): ActivityMiddleware<TSeed, TE>;

Defined in: packages/worker/src/activity.ts:631

(Mirrors amqp-contract's composeMiddleware overload approach.)

Type Parameters

Type Parameter
`TSeed` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TA` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TB` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TC` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TD` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TE` extends `Record`<`string`, `unknown`> \| `EmptyContext`

Parameters

Parameter	Type
`m1`	`ActivityMiddleware`<`TSeed`, `TA`>
`m2`	`ActivityMiddleware`<`TA`, `TB`>
`m3`	`ActivityMiddleware`<`TB`, `TC`>
`m4`	`ActivityMiddleware`<`TC`, `TD`>
`m5`	`ActivityMiddleware`<`TD`, `TE`>

Returns

ActivityMiddleware<TSeed, TE>

Call Signature

function composeActivityMiddleware<TSeed, TA, TB, TC, TD, TE, TF>(
   m1, 
   m2, 
   m3, 
   m4, 
   m5, 
   m6
): ActivityMiddleware<TSeed, TF>;

Defined in: packages/worker/src/activity.ts:645

(Mirrors amqp-contract's composeMiddleware overload approach.)

Type Parameters

Type Parameter
`TSeed` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TA` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TB` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TC` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TD` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TE` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TF` extends `Record`<`string`, `unknown`> \| `EmptyContext`

Parameters

Parameter	Type
`m1`	`ActivityMiddleware`<`TSeed`, `TA`>
`m2`	`ActivityMiddleware`<`TA`, `TB`>
`m3`	`ActivityMiddleware`<`TB`, `TC`>
`m4`	`ActivityMiddleware`<`TC`, `TD`>
`m5`	`ActivityMiddleware`<`TD`, `TE`>
`m6`	`ActivityMiddleware`<`TE`, `TF`>

Returns

ActivityMiddleware<TSeed, TF>

Call Signature

function composeActivityMiddleware<TSeed, TA, TB, TC, TD, TE, TF, TG>(
   m1, 
   m2, 
   m3, 
   m4, 
   m5, 
   m6, 
   m7
): ActivityMiddleware<TSeed, TG>;

Defined in: packages/worker/src/activity.ts:661

(Mirrors amqp-contract's composeMiddleware overload approach.)

Type Parameters

Type Parameter
`TSeed` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TA` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TB` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TC` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TD` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TE` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TF` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TG` extends `Record`<`string`, `unknown`> \| `EmptyContext`

Parameters

Parameter	Type
`m1`	`ActivityMiddleware`<`TSeed`, `TA`>
`m2`	`ActivityMiddleware`<`TA`, `TB`>
`m3`	`ActivityMiddleware`<`TB`, `TC`>
`m4`	`ActivityMiddleware`<`TC`, `TD`>
`m5`	`ActivityMiddleware`<`TD`, `TE`>
`m6`	`ActivityMiddleware`<`TE`, `TF`>
`m7`	`ActivityMiddleware`<`TF`, `TG`>

Returns

ActivityMiddleware<TSeed, TG>

Call Signature

function composeActivityMiddleware<TSeed, TA, TB, TC, TD, TE, TF, TG, TH>(
   m1, 
   m2, 
   m3, 
   m4, 
   m5, 
   m6, 
   m7, 
   m8
): ActivityMiddleware<TSeed, TH>;

Defined in: packages/worker/src/activity.ts:679

(Mirrors amqp-contract's composeMiddleware overload approach.)

Type Parameters

Type Parameter
`TSeed` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TA` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TB` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TC` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TD` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TE` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TF` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TG` extends `Record`<`string`, `unknown`> \| `EmptyContext`
`TH` extends `Record`<`string`, `unknown`> \| `EmptyContext`

Parameters

Parameter	Type
`m1`	`ActivityMiddleware`<`TSeed`, `TA`>
`m2`	`ActivityMiddleware`<`TA`, `TB`>
`m3`	`ActivityMiddleware`<`TB`, `TC`>
`m4`	`ActivityMiddleware`<`TC`, `TD`>
`m5`	`ActivityMiddleware`<`TD`, `TE`>
`m6`	`ActivityMiddleware`<`TE`, `TF`>
`m7`	`ActivityMiddleware`<`TF`, `TG`>
`m8`	`ActivityMiddleware`<`TG`, `TH`>

Returns

ActivityMiddleware<TSeed, TH>

declareActivitiesHandler()

function declareActivitiesHandler<TContract, TContext, TInjected>(options): ActivitiesHandler<TContract>;

Defined in: packages/worker/src/activity.ts:895

Create a typed activities handler with automatic validation and Result pattern.

This wraps all activity implementations with:

Validation at network boundaries
AsyncResult<T, ApplicationFailure | declared errors> pattern for explicit error handling
Automatic conversion from Result to Promise (throwing on Error)
Typed constructors for contract-declared errors and an optional dependency context (see ActivityImplementationHelpers)
An optional contract-aware middleware chain (see ActivityMiddleware)

TypeScript ensures ALL activities (global + workflow-specific) are implemented.

Use this to create the activities object for the Temporal Worker.

Type Parameters

Type Parameter	Default type
`TContract` extends `ContractDefinition`	-
`TContext` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`EmptyContext`
`TInjected` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`TContext`

Parameters

Parameter	Type
`options`	`DeclareActivitiesHandlerOptions`<`TContract`, `TContext`, `TInjected`>

Returns

ActivitiesHandler<TContract>

Example

import { declareActivitiesHandler, ApplicationFailure } from '@temporal-contract/worker/activity';
import { fromPromise, Ok, Err } from 'unthrown';
import { myContract } from './contract.js';

export const activities = declareActivitiesHandler({
  contract: myContract,
  // Typed dependency injection: implementations receive this via
  // `helpers.context` instead of closing over module state.
  createContext: () => ({ emailService }),
  activities: {
    // Activity returns AsyncResult instead of throwing.
    sendEmail: (args, { errors, context }) =>
      fromPromise(
        context.emailService.send(args),
        (error) =>
          // Wrap technical errors in ApplicationFailure. `nonRetryable`
          // is per-instance: set it to true on permanent failures so
          // Temporal stops retrying immediately. Note the conditional
          // spread for `cause` — under `exactOptionalPropertyTypes`,
          // omit the key entirely rather than passing `undefined`.
          ApplicationFailure.create({
            type: 'EMAIL_SEND_FAILED',
            message: 'Failed to send email',
            nonRetryable: false,
            ...(error instanceof Error ? { cause: error } : {}),
          }),
      ).flatMap((outcome) =>
        outcome.accepted
          ? Ok({ sent: true })
          : // Contract-declared error: typed on the caller's side, with
            // `nonRetryable` taken from the contract declaration.
            Err(errors.RecipientRejected({ reason: outcome.reason })),
      ),
  },
});

// Wire into a worker with this package's typed factory — the task queue
// comes from the contract.
import { NativeConnection } from '@temporalio/worker';
import { TypedWorker, workflowsPathFromURL } from '@temporal-contract/worker/worker';

const connection = await NativeConnection.connect({ address: 'localhost:7233' });
const worker = await TypedWorker.create({
  contract: myContract,
  connection,
  workflowsPath: workflowsPathFromURL(import.meta.url, './workflows.js'),
  activities,
}).get();

Remarks

The wrapper accepts implementations in the AsyncResult<T, ApplicationFailure | declared errors> shape and produces ordinary Promise-returning Temporal handlers (Err(ApplicationFailure) → thrown; Err(ContractError) → data validated against the declared schema and thrown as an ApplicationFailure with type = error name, details[0] = data, nonRetryable from the contract; Ok(...) → output validated against the contract, then resolved with the implementation's original value — the calling side parses it on receive; defect → original cause re-thrown). It does not hide Temporal's @temporalio/activity runtime: inside the body you can still call Context.current() from @temporalio/activity to access heartbeats (heartbeat(details), heartbeatDetails), activity info (attempt number, workflow IDs), and the async-completion task token. See the "Working with the Activity Context" section of the worker implementation guide for end-to-end examples.

declareActivityMiddleware()

function declareActivityMiddleware<TContextIn, TContextOut>(middleware): ActivityMiddleware<TContextIn, TContextOut>;

Defined in: packages/worker/src/activity.ts:581

Identity helper that pins a middleware's context types without a variable annotation. (Mirrors amqp-contract's defineMiddleware.)

Type Parameters

Type Parameter	Default type
`TContextIn` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`EmptyContext`
`TContextOut` extends `Record`<`string`, `unknown`> \| `EmptyContext`	`TContextIn`

Parameters

Parameter	Type
`middleware`	`ActivityMiddleware`<`TContextIn`, `TContextOut`>

Returns

ActivityMiddleware<TContextIn, TContextOut>

qualifyFailure()

function qualifyFailure(errorType, options): <TDefect>(cause, defect) => TDefect | ApplicationFailure;

Defined in: packages/worker/src/activity.ts:208

Build a qualifier for fromPromise that triages each rejection: causes matching options.expected are wrapped in a modeled ApplicationFailure of the given errorType; everything else goes to unthrown's defect channel.

Triage philosophy: fromPromise's qualify step exists to force a per-cause decision — is this failure part of the activity's model, or a bug? A qualifier that wraps everything erases that decision: a TypeError from a typo would surface as, say, EMAIL_SEND_FAILED and inherit its retry semantics, hiding the defect from operators and from the defect channel's fail-loud handling. expected is therefore required: name the failure classes (or predicate) you anticipate; let the rest stay defects that re-throw at the activity edge with their original cause. The literal expected: "any" remains as an explicit, greppable escape hatch for the old blanket behavior.

For a matched Error cause, the wrapper keeps the cause's own message and preserves it as cause (so stack traces survive the activity → workflow boundary); a matched non-Error cause falls back to options.message (or String(cause)).

Parameters

Parameter	Type
`errorType`	`string`
`options`	`QualifyFailureOptions`

Returns

<TDefect>(cause, defect) => TDefect | ApplicationFailure

Example

import { declareActivitiesHandler, qualifyFailure } from '@temporal-contract/worker/activity';
import { fromPromise } from 'unthrown';

export const activities = declareActivitiesHandler({
  contract: myContract,
  activities: {
    sendEmail: ({ input: args }) =>
      fromPromise(
        emailService.send(args),
        // Anticipated: the SDK's typed error. Anything else (TypeError,
        // assertion failure, ...) is a defect and re-throws at the edge.
        qualifyFailure('EMAIL_SEND_FAILED', { expected: EmailServiceError }),
      ).map(() => ({ sent: true })),
    chargeCard: ({ input: args }) =>
      fromPromise(
        paymentGateway.charge(args),
        qualifyFailure('CARD_DECLINED', {
          // Several anticipated classes; a predicate works too.
          expected: [CardDeclinedError, GatewayTimeoutError],
          // Permanent failure: opt out of the configured retry policy.
          nonRetryable: true,
        }),
      ),
  },
});

Remarks

A matched cause is always wrapped — even when it is already an ApplicationFailure — so the resulting failure's type is guaranteed to be the declared one (retry policies keyed on retry.nonRetryableErrorTypes can rely on it), with the original failure preserved as cause. Retryability of the wrapper: when options.nonRetryable is set it wins unconditionally; when it is omitted and the matched cause is an ApplicationFailure with nonRetryable: true, the wrapper inherits nonRetryable: true (a permanent inner failure no longer silently becomes retryable just because it was re-typed).

activity ​

Classes ​

ActivityDefinitionNotFoundError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

Properties ​

ActivityInputValidationError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

Properties ​

Methods ​

captureStackTrace() ​

Parameters ​

Returns ​

Inherited from ​

create() ​

Parameters ​

Returns ​

Inherited from ​

fromError() ​

Parameters ​

Returns ​

Inherited from ​

nonRetryable() ​

Parameters ​

Returns ​

Inherited from ​

prepareStackTrace() ​

Parameters ​

Returns ​

See ​

Inherited from ​

retryable() ​

Parameters ​

Returns ​

Inherited from ​

ActivityOutputValidationError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

Properties ​

Methods ​

captureStackTrace() ​

Parameters ​

Returns ​

Inherited from ​

create() ​

Parameters ​

Returns ​

Inherited from ​

fromError() ​

Parameters ​

Returns ​

Inherited from ​

nonRetryable() ​

Parameters ​

Returns ​

Inherited from ​

prepareStackTrace() ​

Parameters ​

Returns ​

See ​

Inherited from ​

retryable() ​

Parameters ​

Returns ​

Inherited from ​

ApplicationFailure ​

Extends ​

activity

Classes

ActivityDefinitionNotFoundError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

Properties

ActivityInputValidationError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

Properties

Methods

captureStackTrace()

Parameters

Returns

Inherited from

create()

Parameters

Returns

Inherited from

fromError()

Parameters

Returns

Inherited from

nonRetryable()

Parameters

Returns

Inherited from

prepareStackTrace()

Parameters

Returns

See

Inherited from

retryable()

Parameters

Returns

Inherited from

ActivityOutputValidationError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

Properties

Methods

captureStackTrace()

Parameters

Returns

Inherited from

create()

Parameters

Returns

Inherited from

fromError()

Parameters

Returns

Inherited from

nonRetryable()

Parameters

Returns

Inherited from

prepareStackTrace()

Parameters

Returns

See

Inherited from

retryable()

Parameters

Returns

Inherited from

ApplicationFailure

Extends