temporal-contract

Appearance

@temporal-contract/worker

@temporal-contract/worker / activity

activity ​

Classes ​

ActivityDefinitionNotFoundError ​

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

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

Extends ​

  • WorkerError

Constructors ​

Constructor ​
ts
new ActivityDefinitionNotFoundError(activityName, availableDefinitions?): ActivityDefinitionNotFoundError;

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

Parameters ​
ParameterTypeDefault value
activityNamestringundefined
availableDefinitionsreadonly string[][]
Returns ​

ActivityDefinitionNotFoundError

Overrides ​
ts
WorkerError.constructor

Properties ​

PropertyModifierTypeDefault valueDescriptionInherited fromDefined in
activityNamereadonlystringundefined--packages/worker/src/errors.ts:23
availableDefinitionsreadonlyreadonly string[][]--packages/worker/src/errors.ts:24
cause?publicunknownundefined-WorkerError.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringundefined-WorkerError.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringundefined-WorkerError.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstringundefined-WorkerError.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
stackTraceLimitstaticnumberundefinedThe 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.WorkerError.stackTraceLimitnode_modules/.pnpm/@types+node@24.12.2/node_modules/@types/node/globals.d.ts:68

Methods ​

captureStackTrace() ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@24.12.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.

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

js
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 ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​
ts
WorkerError.captureStackTrace
prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@24.12.2/node_modules/@types/node/globals.d.ts:56

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

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

Inherited from ​
ts
WorkerError.prepareStackTrace

ActivityInputValidationError ​

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

Error thrown when activity input validation fails

Extends ​

  • WorkerError

Constructors ​

Constructor ​
ts
new ActivityInputValidationError(activityName, issues): ActivityInputValidationError;

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

Parameters ​
ParameterType
activityNamestring
issuesreadonly Issue[]
Returns ​

ActivityInputValidationError

Overrides ​
ts
WorkerError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
activityNamereadonlystring--packages/worker/src/errors.ts:39
cause?publicunknown-WorkerError.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
issuesreadonlyreadonly Issue[]--packages/worker/src/errors.ts:40
messagepublicstring-WorkerError.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-WorkerError.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstring-WorkerError.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
stackTraceLimitstaticnumberThe 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.WorkerError.stackTraceLimitnode_modules/.pnpm/@types+node@24.12.2/node_modules/@types/node/globals.d.ts:68

Methods ​

captureStackTrace() ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@24.12.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.

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

js
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 ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​
ts
WorkerError.captureStackTrace
prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@24.12.2/node_modules/@types/node/globals.d.ts:56

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

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

Inherited from ​
ts
WorkerError.prepareStackTrace

ActivityOutputValidationError ​

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

Error thrown when activity output validation fails

Extends ​

  • WorkerError

Constructors ​

Constructor ​
ts
new ActivityOutputValidationError(activityName, issues): ActivityOutputValidationError;

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

Parameters ​
ParameterType
activityNamestring
issuesreadonly Issue[]
Returns ​

ActivityOutputValidationError

Overrides ​
ts
WorkerError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
activityNamereadonlystring--packages/worker/src/errors.ts:53
cause?publicunknown-WorkerError.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
issuesreadonlyreadonly Issue[]--packages/worker/src/errors.ts:54
messagepublicstring-WorkerError.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-WorkerError.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstring-WorkerError.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
stackTraceLimitstaticnumberThe 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.WorkerError.stackTraceLimitnode_modules/.pnpm/@types+node@24.12.2/node_modules/@types/node/globals.d.ts:68

Methods ​

captureStackTrace() ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@24.12.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.

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

js
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 ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​
ts
WorkerError.captureStackTrace
prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@24.12.2/node_modules/@types/node/globals.d.ts:56

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

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

Inherited from ​
ts
WorkerError.prepareStackTrace

ApplicationFailure ​

Defined in: node_modules/.pnpm/@temporalio+common@1.17.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

Constructors ​

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

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

Alternatively, use fromError or create.

Parameters ​
ParameterType
message?string | null
type?string | null
nonRetryable?boolean | null
details?unknown[] | null
cause?Error
nextRetryDelay?any
category?"BENIGN" | null
Returns ​

ApplicationFailure

Overrides ​
ts
TemporalFailure.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
category?readonly"BENIGN" | null--node_modules/.pnpm/@temporalio+common@1.17.0/node_modules/@temporalio/common/lib/failure.d.ts:113
cause?readonlyError-TemporalFailure.causenode_modules/.pnpm/@temporalio+common@1.17.0/node_modules/@temporalio/common/lib/failure.d.ts:72
details?readonlyunknown[] | null--node_modules/.pnpm/@temporalio+common@1.17.0/node_modules/@temporalio/common/lib/failure.d.ts:111
failure?publicIFailureThe original failure that constructed this error. Only present if this error was generated from an external operation.TemporalFailure.failurenode_modules/.pnpm/@temporalio+common@1.17.0/node_modules/@temporalio/common/lib/failure.d.ts:78
messagepublicstring-TemporalFailure.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-TemporalFailure.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
nextRetryDelay?readonlyany--node_modules/.pnpm/@temporalio+common@1.17.0/node_modules/@temporalio/common/lib/failure.d.ts:112
nonRetryable?readonlyboolean | null--node_modules/.pnpm/@temporalio+common@1.17.0/node_modules/@temporalio/common/lib/failure.d.ts:110
stack?publicstring-TemporalFailure.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
type?readonlystring | null--node_modules/.pnpm/@temporalio+common@1.17.0/node_modules/@temporalio/common/lib/failure.d.ts:109
stackTraceLimitstaticnumberThe 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.stackTraceLimitnode_modules/.pnpm/@types+node@24.12.2/node_modules/@types/node/globals.d.ts:68

Methods ​

captureStackTrace() ​
ts
static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@24.12.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.

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

js
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 ​
ParameterType
targetObjectobject
constructorOpt?Function
Returns ​

void

Inherited from ​
ts
TemporalFailure.captureStackTrace
create() ​
ts
static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.17.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 ​
ParameterType
optionsApplicationFailureOptions
Returns ​

ApplicationFailure

fromError() ​
ts
static fromError(error, overrides?): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.17.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 ​
ParameterType
errorunknown
overrides?ApplicationFailureOptions
Returns ​

ApplicationFailure

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

Defined in: node_modules/.pnpm/@temporalio+common@1.17.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 ​
ParameterTypeDescription
message?string | nullOptional error message
type?string | nullOptional error type
...details?unknown[]Optional details about the failure. Serialized by the Worker's PayloadConverter.
Returns ​

ApplicationFailure

prepareStackTrace() ​
ts
static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@24.12.2/node_modules/@types/node/globals.d.ts:56

Parameters ​
ParameterType
errError
stackTracesCallSite[]
Returns ​

any

See ​

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

Inherited from ​
ts
TemporalFailure.prepareStackTrace
retryable() ​
ts
static retryable(
   message?, 
   type?, ...
   details): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.17.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 ​
ParameterTypeDescription
message?string | nullOptional error message
type?string | nullOptional error type (used by RetryPolicy.nonRetryableErrorTypes)
...details?unknown[]Optional details about the failure. Serialized by the Worker's PayloadConverter.
Returns ​

ApplicationFailure

Type Aliases ​

ActivitiesHandler ​

ts
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:119

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

Functions ​

declareActivitiesHandler() ​

ts
function declareActivitiesHandler<TContract>(options): ActivitiesHandler<TContract>;

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

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

This wraps all activity implementations with:

  • Validation at network boundaries
  • ResultAsync<T, ApplicationFailure> pattern for explicit error handling
  • Automatic conversion from Result to Promise (throwing on Error)

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

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

Type Parameters ​

Type Parameter
TContract extends ContractDefinition

Parameters ​

ParameterType
optionsDeclareActivitiesHandlerOptions<TContract>

Returns ​

ActivitiesHandler<TContract>

Example ​

ts
import { declareActivitiesHandler, ApplicationFailure } from '@temporal-contract/worker/activity';
import { ResultAsync, errAsync, okAsync } from 'neverthrow';
import myContract from './contract';

export const activities = declareActivitiesHandler({
  contract: myContract,
  activities: {
    // Activity returns ResultAsync instead of throwing.
    sendEmail: (args) =>
      ResultAsync.fromPromise(
        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,
          }),
      ).map(() => ({ sent: true })),
  },
});

// Use with Temporal Worker
import { Worker } from '@temporalio/worker';

const worker = await Worker.create({
  workflowsPath: require.resolve('./workflows'),
  activities: activities,
  taskQueue: contract.taskQueue,
});

Remarks ​

The wrapper accepts implementations in the ResultAsync<T, ApplicationFailure> shape and produces ordinary Promise-returning Temporal handlers (err(...) → thrown ApplicationFailure; ok(...) → output validated against the contract and resolved). 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.

Released under the MIT License.

Copyright © 2026 Benoit TRAVERS