@temporal-contract/worker / activity

activity

Classes

ActivityDefinitionNotFoundError

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

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

Parameters

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

Returns

ActivityDefinitionNotFoundError

Overrides

TaggedError(
  "@temporal-contract/ActivityDefinitionNotFoundError",
  { name: "ActivityDefinitionNotFoundError" },
)<{
  activityName: string;
  availableDefinitions: readonly string[];
}>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
`_tag`	`readonly`	`"@temporal-contract/ActivityDefinitionNotFoundError"`	`TaggedError( "@temporal-contract/ActivityDefinitionNotFoundError", { name: "ActivityDefinitionNotFoundError" }, )._tag`	node_modules/.pnpm/unthrown@4.1.0/node_modules/unthrown/dist/index.d.mts:1456
`activityName`	`readonly`	`string`	`TaggedError( "@temporal-contract/ActivityDefinitionNotFoundError", { name: "ActivityDefinitionNotFoundError" }, ).activityName`	packages/worker/src/errors.ts:68
`availableDefinitions`	`readonly`	readonly `string`[]	`TaggedError( "@temporal-contract/ActivityDefinitionNotFoundError", { name: "ActivityDefinitionNotFoundError" }, ).availableDefinitions`	packages/worker/src/errors.ts:69
`cause?`	`public`	`unknown`	`TaggedError( "@temporal-contract/ActivityDefinitionNotFoundError", { name: "ActivityDefinitionNotFoundError" }, ).cause`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
`message`	`public`	`string`	`TaggedError( "@temporal-contract/ActivityDefinitionNotFoundError", { name: "ActivityDefinitionNotFoundError" }, ).message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	`TaggedError( "@temporal-contract/ActivityDefinitionNotFoundError", { name: "ActivityDefinitionNotFoundError" }, ).name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`stack?`	`public`	`string`	`TaggedError( "@temporal-contract/ActivityDefinitionNotFoundError", { 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:81

Error thrown when activity input validation fails

Extends

ValidationError

Constructors

Constructor

new ActivityInputValidationError(activityName, issues): ActivityInputValidationError;

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

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:83
`category?`	`readonly`	`"BENIGN"` \| `null`	-	`WorkflowOutputValidationError`.`category`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ActivityOutputValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	`WorkflowOutputValidationError`.`details`	node_modules/.pnpm/@temporalio+common@1.18.1/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.	`ValidationError`.`failure`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:78
`issues`	`readonly`	readonly `Issue`[]	-	`ValidationError`.`issues`	packages/worker/src/errors.ts:38
`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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	`WorkflowOutputValidationError`.`nonRetryable`	node_modules/.pnpm/@temporalio+common@1.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:68

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@24.13.2/node_modules/@types/node/globals.d.ts:52

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.18.1/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.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:56

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.18.1/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:99

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:100
`category?`	`readonly`	`"BENIGN"` \| `null`	-	`ValidationError`.`category`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	`ValidationError`.`details`	node_modules/.pnpm/@temporalio+common@1.18.1/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.	`ValidationError`.`failure`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:78
`issues`	`readonly`	readonly `Issue`[]	-	`ValidationError`.`issues`	packages/worker/src/errors.ts:38
`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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	`ValidationError`.`nonRetryable`	node_modules/.pnpm/@temporalio+common@1.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:68

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@24.13.2/node_modules/@types/node/globals.d.ts:52

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.18.1/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.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:56

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.18.1/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.18.1/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.18.1/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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ActivityOutputValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	-	node_modules/.pnpm/@temporalio+common@1.18.1/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.18.1/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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	-	node_modules/.pnpm/@temporalio+common@1.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:68

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@24.13.2/node_modules/@types/node/globals.d.ts:52

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.18.1/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.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:56

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.18.1/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.d.mts:42

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 matchTags); 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.d.mts:47

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@4.1.0/node_modules/unthrown/dist/index.d.mts:1456
`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`	-	`ContractError_base.data`	packages/contract/dist/errors.d.mts:44
`errorName`	`readonly`	`TName`	Declared error name — the `ApplicationFailure.type` discriminator.	`ContractError_base.errorName`	packages/contract/dist/errors.d.mts:43
`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:238

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

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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	`ValidationError`.`details`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:111
`errorName`	`readonly`	`string`	-	-	packages/worker/src/errors.ts:240
`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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:78
`issues`	`readonly`	readonly `Issue`[]	-	`ValidationError`.`issues`	packages/worker/src/errors.ts:38
`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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	`ValidationError`.`nonRetryable`	node_modules/.pnpm/@temporalio+common@1.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:68

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@24.13.2/node_modules/@types/node/globals.d.ts:52

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.18.1/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.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:56

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.18.1/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:34

Base class for the contract's runtime validation failures — workflow and activity input/output, plus signal/query/update payloads.

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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:113
`cause?`	`readonly`	`Error`	-	`ActivityOutputValidationError`.`cause`	node_modules/.pnpm/@temporalio+common@1.18.1/node_modules/@temporalio/common/lib/failure.d.ts:72
`details?`	`readonly`	`unknown`[] \| `null`	-	`WorkflowOutputValidationError`.`details`	node_modules/.pnpm/@temporalio+common@1.18.1/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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:78
`issues`	`readonly`	readonly `Issue`[]	-	-	packages/worker/src/errors.ts:38
`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.18.1/node_modules/@temporalio/common/lib/failure.d.ts:112
`nonRetryable?`	`readonly`	`boolean` \| `null`	-	`WorkflowOutputValidationError`.`nonRetryable`	node_modules/.pnpm/@temporalio+common@1.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:68

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@24.13.2/node_modules/@types/node/globals.d.ts:52

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.18.1/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.18.1/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.18.1/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@24.13.2/node_modules/@types/node/globals.d.ts:56

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.18.1/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:539

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`

ActivityImplementationHelpers

type ActivityImplementationHelpers<TActivity, TContext> = object;

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

Second argument passed to every activity implementation.

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.

Type Parameters

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

Properties

Property	Modifier	Type	Defined in
`context`	`readonly`	`TContext`	packages/worker/src/activity.ts:163
`errors`	`readonly`	`ActivityErrorConstructorsOf`<`TActivity`>	packages/worker/src/activity.ts:162

ActivityInvocationInfo

type ActivityInvocationInfo = object;

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

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:242
`workflowName`	`readonly`	`string` \| `undefined`	Owning workflow for workflow-local activities; `undefined` for global ones.	packages/worker/src/activity.ts:244

ActivityMiddleware

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

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

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 defineActivityMiddleware.

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)

const logging: ActivityMiddleware = ({ activityName, workflowName }, next) =>
  next().tapErr((error) => {
    logger.warn({ activityName, workflowName, error }, "activity failed");
  });

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

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

ActivityMiddlewareNext

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

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

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

Context-erased middleware shape used by the runtime chain.

AnyContractError

type AnyContractError = ContractError<string, unknown>;

Defined in: packages/contract/dist/errors.d.mts:58

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.d.mts:86

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.d.mts:64

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.d.mts:66
`message?`	`readonly`	`string`	packages/contract/dist/errors.d.mts:65

EmptyContext

type EmptyContext = Record<never, never>;

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

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.)

Functions

composeActivityMiddleware()

Call Signature

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

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

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

(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:367

(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:377

(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:389

(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:403

(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:419

(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:437

(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:636

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.
          ApplicationFailure.create({
            type: 'EMAIL_SEND_FAILED',
            message: 'Failed to send email',
            nonRetryable: false,
            cause: error instanceof Error ? error : undefined,
          }),
      ).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 })),
      ),
  },
});

// Use with Temporal Worker
import { Worker } from '@temporalio/worker';
import { workflowsPathFromURL } from '@temporal-contract/worker/worker';

const worker = await Worker.create({
  workflowsPath: workflowsPathFromURL(import.meta.url, './workflows.js'),
  activities: activities,
  taskQueue: contract.taskQueue,
});

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 and resolved; 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.

defineActivityMiddleware()

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

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

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>

qualify()

function qualify(type, options?): (error) => ApplicationFailure;

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

Build a qualifier for fromPromise that wraps a rejection in an ApplicationFailure of the given type.

Replaces the hand-written wrapping every activity otherwise repeats: an Error rejection keeps its own message and is preserved as cause (so stack traces survive the activity → workflow boundary); anything else falls back to options.message (or String(error)).

Parameters

Parameter	Type	Description
`type`	`string`	-
`options?`	{ `details?`: `unknown`[]; `message?`: `string`; `nonRetryable?`: `boolean`; }	-
`options.details?`	`unknown`[]	Structured payload forwarded to the workflow (avoids parsing `message`).
`options.message?`	`string`	Fallback message when the rejection is not an `Error` (default: `String(error)`).
`options.nonRetryable?`	`boolean`	Mark the failure non-retryable — Temporal stops retrying immediately.

Returns

(error) => ApplicationFailure

Example

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

export const activities = declareActivitiesHandler({
  contract: myContract,
  activities: {
    sendEmail: (args) =>
      fromPromise(emailService.send(args), qualify('EMAIL_SEND_FAILED'))
        .map(() => ({ sent: true })),
    chargeCard: (args) =>
      fromPromise(
        paymentGateway.charge(args),
        // Permanent failure: opt out of the configured retry policy.
        qualify('CARD_DECLINED', { nonRetryable: true }),
      ),
  },
});

Remarks

The qualifier always wraps — even when the rejection 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). The original failure is preserved as cause. Note the flip side: because the wrapper's type and nonRetryable take precedence, an inner ApplicationFailure's own type/nonRetryable: true is masked — pass { nonRetryable: true } here (or write a custom qualifier) if that inner failure should stay non-retryable.

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