temporal-contract

Appearance

@temporal-contract/worker

@temporal-contract/worker / workflow

workflow ​

Classes ​

ActivityCancelledError ​

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

Discriminated variant surfaced when a call to an activity was cancelled (the workflow itself, or an enclosing cancellation scope) — every activity call rides this branch now, not only ones that declare an errors map. Detected via @temporalio/workflow's isCancellation(...).

A sibling of ActivityError rather than a subclass, for the same reason ChildWorkflowCancelledError is a sibling of ChildWorkflowError: call sites discriminate on the _tag.

Swallowing this error changes the workflow outcome. Cancellation rides the modeled Err(...) channel here, so generic error handling (e.g. mapping every Err to a "failed" result and returning normally) makes the workflow complete as Completed instead of Cancelled. When the workflow should honor the cancellation request, re-raise it with rethrowCancellation.

Unlike ActivityError, cause here is already the value exactly as caught (classifyActivityError checks cancellation before unwrapping ActivityFailure) — so there is no separate originalFailure to retain; propagateFailure re-raises cause directly.

Extends ​

  • TaggedErrorInstance<"@temporal-contract/ActivityCancelledError", { activityName: string; cause?: unknown; }>

Constructors ​

Constructor ​
ts
new ActivityCancelledError(activityName, cause?): ActivityCancelledError;

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

Parameters ​
ParameterType
activityNamestring
cause?unknown
Returns ​

ActivityCancelledError

Overrides ​
ts
TaggedError(ACTIVITY_CANCELLED_ERROR_TAG, {
  name: "ActivityCancelledError",
})<{
  activityName: string;
  cause?: unknown;
}>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
_tagreadonly"@temporal-contract/ActivityCancelledError"TaggedError(ACTIVITY_CANCELLED_ERROR_TAG, { name: "ActivityCancelledError", })._tagnode_modules/.pnpm/unthrown@5.11.0/node_modules/unthrown/dist/index.d.mts:2332
activityNamereadonlystringTaggedError(ACTIVITY_CANCELLED_ERROR_TAG, { name: "ActivityCancelledError", }).activityNamepackages/worker/src/errors.ts:402
cause?publicunknownActivityDefinitionNotFoundError.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringTaggedError(ACTIVITY_CANCELLED_ERROR_TAG, { name: "ActivityCancelledError", }).messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringTaggedError(ACTIVITY_CANCELLED_ERROR_TAG, { name: "ActivityCancelledError", }).namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstringTaggedError(ACTIVITY_CANCELLED_ERROR_TAG, { name: "ActivityCancelledError", }).stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

ActivityError ​

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

Generic error surfaced on the Err(...) branch when an activity that declares contract errors fails for a reason other than one of its declared errors — retries exhausted on a technical failure, a timeout, an undeclared ApplicationFailure type, or a validation failure at the workflow → activity boundary.

Mirrors ChildWorkflowError: cause is the unwrapped actionable failure (Temporal's ActivityFailure wrapper is seen through), so callers can branch on the failure category in one step.

Every activity call surfaces this — the workflow-side call convention no longer depends on whether the contract declares an errors map; only the error channel's declared-error members do.

originalFailure is a second, separate retention: the value exactly as it was caught, before classifyActivityError unwrapped it into cause (typically Temporal's ActivityFailure wrapper). cause's unwrapping is documented, caller-facing behavior and stays as-is — originalFailure exists purely so propagateFailure can re-raise the exact failure Temporal originally produced, without changing what cause means. Unset when there is no separate wrapper to retain (e.g. the input/output validation branches, where cause is already the terminal failure).

Extends ​

  • TaggedErrorInstance<"@temporal-contract/ActivityError", { activityName: string; cause?: unknown; originalFailure?: unknown; }>

Constructors ​

Constructor ​
ts
new ActivityError(
   activityName, 
   message, 
   cause?, 
   originalFailure?
): ActivityError;

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

Parameters ​
ParameterType
activityNamestring
messagestring
cause?unknown
originalFailure?unknown
Returns ​

ActivityError

Overrides ​
ts
TaggedError(ACTIVITY_ERROR_TAG, {
  name: "ActivityError",
})<{
  activityName: string;
  cause?: unknown;
  originalFailure?: unknown;
}>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
_tagreadonly"@temporal-contract/ActivityError"TaggedError(ACTIVITY_ERROR_TAG, { name: "ActivityError", })._tagnode_modules/.pnpm/unthrown@5.11.0/node_modules/unthrown/dist/index.d.mts:2332
activityNamereadonlystringTaggedError(ACTIVITY_ERROR_TAG, { name: "ActivityError", }).activityNamepackages/worker/src/errors.ts:367
cause?publicunknownActivityDefinitionNotFoundError.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringTaggedError(ACTIVITY_ERROR_TAG, { name: "ActivityError", }).messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringTaggedError(ACTIVITY_ERROR_TAG, { name: "ActivityError", }).namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
originalFailure?readonlyunknownTaggedError(ACTIVITY_ERROR_TAG, { name: "ActivityError", }).originalFailurepackages/worker/src/errors.ts:369
stack?publicstringTaggedError(ACTIVITY_ERROR_TAG, { name: "ActivityError", }).stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

ChildWorkflowCancelledError ​

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

Discriminated variant surfaced when a child workflow operation (start, execute, or wait-for-result) was cancelled — either because the parent workflow itself was cancelled, the child was explicitly cancelled, or its enclosing cancellation scope was. Detected via @temporalio/workflow's isCancellation(...), which sees through nested ChildWorkflowFailure / CancelledFailure chains.

A sibling of ChildWorkflowError rather than a subclass: both are distinct TaggedErrors, so call sites discriminate on the _tag (or instanceof ChildWorkflowCancelledError) instead of relying on an instanceof ChildWorkflowError that also matches cancellation. A result.match with the exhaustive errCases matcher folds the ChildWorkflowError | ChildWorkflowCancelledError union exhaustively.

Swallowing this error changes the workflow outcome. Cancellation rides the modeled Err(...) channel here, so generic error handling (e.g. mapping every Err to a "failed" result and returning normally) makes the parent workflow complete as Completed instead of Cancelled. When the workflow should honor the cancellation request, re-raise it with rethrowCancellation.

Extends ​

  • TaggedErrorInstance<"@temporal-contract/ChildWorkflowCancelledError", { cause?: unknown; workflowName: string; }>

Constructors ​

Constructor ​
ts
new ChildWorkflowCancelledError(workflowName, cause?): ChildWorkflowCancelledError;

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

Parameters ​
ParameterType
workflowNamestring
cause?unknown
Returns ​

ChildWorkflowCancelledError

Overrides ​
ts
TaggedError(CHILD_WORKFLOW_CANCELLED_ERROR_TAG, {
  name: "ChildWorkflowCancelledError",
})<{
  workflowName: string;
  cause?: unknown;
}>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
_tagreadonly"@temporal-contract/ChildWorkflowCancelledError"TaggedError(CHILD_WORKFLOW_CANCELLED_ERROR_TAG, { name: "ChildWorkflowCancelledError", })._tagnode_modules/.pnpm/unthrown@5.11.0/node_modules/unthrown/dist/index.d.mts:2332
cause?publicunknownActivityDefinitionNotFoundError.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringTaggedError(CHILD_WORKFLOW_CANCELLED_ERROR_TAG, { name: "ChildWorkflowCancelledError", }).messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringTaggedError(CHILD_WORKFLOW_CANCELLED_ERROR_TAG, { name: "ChildWorkflowCancelledError", }).namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstringTaggedError(CHILD_WORKFLOW_CANCELLED_ERROR_TAG, { name: "ChildWorkflowCancelledError", }).stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
workflowNamereadonlystringTaggedError(CHILD_WORKFLOW_CANCELLED_ERROR_TAG, { name: "ChildWorkflowCancelledError", }).workflowNamepackages/worker/src/errors.ts:477

ChildWorkflowError ​

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

Generic error for child workflow operations.

When the child execution itself fails (Temporal's ChildWorkflowFailure), cause is set to the unwrapped underlying failure (ApplicationFailure, TimeoutFailure, TerminatedFailure, etc.) lifted from Temporal's wrapper — mirroring the client-side WorkflowFailedError.cause behavior, so callers can branch on the failure category in one step instead of unwrapping twice.

Carries the child's workflowName as a structured field (matching its sibling ChildWorkflowCancelledError) so callers don't have to parse it out of message.

Extends ​

  • TaggedErrorInstance<"@temporal-contract/ChildWorkflowError", { cause?: unknown; workflowName: string; }>

Constructors ​

Constructor ​
ts
new ChildWorkflowError(
   workflowName, 
   message, 
   cause?
): ChildWorkflowError;

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

Parameters ​
ParameterType
workflowNamestring
messagestring
cause?unknown
Returns ​

ChildWorkflowError

Overrides ​
ts
TaggedError(CHILD_WORKFLOW_ERROR_TAG, {
  name: "ChildWorkflowError",
})<{
  workflowName: string;
  cause?: unknown;
}>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
_tagreadonly"@temporal-contract/ChildWorkflowError"TaggedError(CHILD_WORKFLOW_ERROR_TAG, { name: "ChildWorkflowError", })._tagnode_modules/.pnpm/unthrown@5.11.0/node_modules/unthrown/dist/index.d.mts:2332
cause?publicunknownActivityDefinitionNotFoundError.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringTaggedError(CHILD_WORKFLOW_ERROR_TAG, { name: "ChildWorkflowError", }).messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringTaggedError(CHILD_WORKFLOW_ERROR_TAG, { name: "ChildWorkflowError", }).namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstringTaggedError(CHILD_WORKFLOW_ERROR_TAG, { name: "ChildWorkflowError", }).stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
workflowNamereadonlystringTaggedError(CHILD_WORKFLOW_ERROR_TAG, { name: "ChildWorkflowError", }).workflowNamepackages/worker/src/errors.ts:443

ChildWorkflowNotFoundError ​

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

Error thrown when a child workflow is not found in the contract

Extends ​

  • TaggedErrorInstance<"@temporal-contract/ChildWorkflowNotFoundError", { availableWorkflows: readonly string[]; workflowName: string; }>

Constructors ​

Constructor ​
ts
new ChildWorkflowNotFoundError(workflowName, availableWorkflows?): ChildWorkflowNotFoundError;

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

Parameters ​
ParameterTypeDefault value
workflowNamestringundefined
availableWorkflowsreadonly string[][]
Returns ​

ChildWorkflowNotFoundError

Overrides ​
ts
TaggedError(CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG, {
  name: "ChildWorkflowNotFoundError",
})<{
  workflowName: string;
  availableWorkflows: readonly string[];
}>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
_tagreadonly"@temporal-contract/ChildWorkflowNotFoundError"TaggedError(CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG, { name: "ChildWorkflowNotFoundError", })._tagnode_modules/.pnpm/unthrown@5.11.0/node_modules/unthrown/dist/index.d.mts:2332
availableWorkflowsreadonlyreadonly string[]TaggedError(CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG, { name: "ChildWorkflowNotFoundError", }).availableWorkflowspackages/worker/src/errors.ts:418
cause?publicunknownTaggedError(CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG, { name: "ChildWorkflowNotFoundError", }).causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringTaggedError(CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG, { name: "ChildWorkflowNotFoundError", }).messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringTaggedError(CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG, { name: "ChildWorkflowNotFoundError", }).namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstringTaggedError(CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG, { name: "ChildWorkflowNotFoundError", }).stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
workflowNamereadonlystringTaggedError(CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG, { name: "ChildWorkflowNotFoundError", }).workflowNamepackages/worker/src/errors.ts:417

QueryInputValidationError ​

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

Error thrown when query input validation fails.

Extends ​

Constructors ​

Constructor ​
ts
new QueryInputValidationError(queryName, issues): QueryInputValidationError;

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

Parameters ​
ParameterType
queryNamestring
issuesreadonly Issue[]
Returns ​

QueryInputValidationError

Overrides ​
ts
ValidationError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
category?readonly"BENIGN" | null-ValidationError.categorynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:114
cause?readonlyError-ValidationError.causenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:72
details?readonlyunknown[] | null-ValidationError.detailsnode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:112
directionreadonly"input"--packages/worker/src/errors.ts:211
failure?publicIFailureThe original failure that constructed this error. Only present if this error was generated from an external operation.ValidationError.failurenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:78
issuesreadonlyreadonly Issue[]-ValidationError.issuespackages/worker/src/errors.ts:64
messagepublicstring-ValidationError.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-ValidationError.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
nextRetryDelay?readonlyany-ValidationError.nextRetryDelaynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:113
nonRetryable?readonlyboolean | null-ValidationError.nonRetryablenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:111
queryNamereadonlystring--packages/worker/src/errors.ts:214
stack?publicstring-ValidationError.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
type?readonlystring | null-ValidationError.typenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:110
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.ValidationError.stackTraceLimitnode_modules/.pnpm/@types+node@22.20.4/node_modules/@types/node/globals.d.ts:68

Methods ​

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

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

ValidationError.captureStackTrace

create() ​
ts
static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:131

Create a new ApplicationFailure.

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

Parameters ​
ParameterType
optionsApplicationFailureOptions
Returns ​

ApplicationFailure

Inherited from ​

ValidationError.create

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:125

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

Inherited from ​

ValidationError.fromError

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:151

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

Inherited from ​

ValidationError.nonRetryable

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

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

ValidationError.prepareStackTrace

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:140

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

Inherited from ​

ValidationError.retryable

QueryOutputValidationError ​

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

Error thrown when query output validation fails.

Extends ​

Constructors ​

Constructor ​
ts
new QueryOutputValidationError(queryName, issues): QueryOutputValidationError;

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

Parameters ​
ParameterType
queryNamestring
issuesreadonly Issue[]
Returns ​

QueryOutputValidationError

Overrides ​
ts
ValidationError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
category?readonly"BENIGN" | null-ValidationError.categorynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:114
cause?readonlyError-ValidationError.causenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:72
details?readonlyunknown[] | null-ValidationError.detailsnode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:112
directionreadonly"output"--packages/worker/src/errors.ts:227
failure?publicIFailureThe original failure that constructed this error. Only present if this error was generated from an external operation.ValidationError.failurenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:78
issuesreadonlyreadonly Issue[]-ValidationError.issuespackages/worker/src/errors.ts:64
messagepublicstring-ValidationError.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-ValidationError.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
nextRetryDelay?readonlyany-ValidationError.nextRetryDelaynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:113
nonRetryable?readonlyboolean | null-ValidationError.nonRetryablenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:111
queryNamereadonlystring--packages/worker/src/errors.ts:230
stack?publicstring-ValidationError.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
type?readonlystring | null-ValidationError.typenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:110
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.ValidationError.stackTraceLimitnode_modules/.pnpm/@types+node@22.20.4/node_modules/@types/node/globals.d.ts:68

Methods ​

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

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

ValidationError.captureStackTrace

create() ​
ts
static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:131

Create a new ApplicationFailure.

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

Parameters ​
ParameterType
optionsApplicationFailureOptions
Returns ​

ApplicationFailure

Inherited from ​

ValidationError.create

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:125

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

Inherited from ​

ValidationError.fromError

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:151

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

Inherited from ​

ValidationError.nonRetryable

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

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

ValidationError.prepareStackTrace

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:140

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

Inherited from ​

ValidationError.retryable

UpdateInputValidationError ​

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

Error thrown when update input validation fails.

Extends ​

Constructors ​

Constructor ​
ts
new UpdateInputValidationError(updateName, issues): UpdateInputValidationError;

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

Parameters ​
ParameterType
updateNamestring
issuesreadonly Issue[]
Returns ​

UpdateInputValidationError

Overrides ​
ts
ValidationError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
category?readonly"BENIGN" | null-ValidationError.categorynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:114
cause?readonlyError-ValidationError.causenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:72
details?readonlyunknown[] | null-ValidationError.detailsnode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:112
directionreadonly"input"--packages/worker/src/errors.ts:243
failure?publicIFailureThe original failure that constructed this error. Only present if this error was generated from an external operation.ValidationError.failurenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:78
issuesreadonlyreadonly Issue[]-ValidationError.issuespackages/worker/src/errors.ts:64
messagepublicstring-ValidationError.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-ValidationError.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
nextRetryDelay?readonlyany-ValidationError.nextRetryDelaynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:113
nonRetryable?readonlyboolean | null-ValidationError.nonRetryablenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:111
stack?publicstring-ValidationError.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
type?readonlystring | null-ValidationError.typenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:110
updateNamereadonlystring--packages/worker/src/errors.ts:246
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.ValidationError.stackTraceLimitnode_modules/.pnpm/@types+node@22.20.4/node_modules/@types/node/globals.d.ts:68

Methods ​

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

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

ValidationError.captureStackTrace

create() ​
ts
static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:131

Create a new ApplicationFailure.

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

Parameters ​
ParameterType
optionsApplicationFailureOptions
Returns ​

ApplicationFailure

Inherited from ​

ValidationError.create

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:125

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

Inherited from ​

ValidationError.fromError

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:151

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

Inherited from ​

ValidationError.nonRetryable

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

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

ValidationError.prepareStackTrace

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:140

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

Inherited from ​

ValidationError.retryable

UpdateOutputValidationError ​

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

Error thrown when update output validation fails.

Extends ​

Constructors ​

Constructor ​
ts
new UpdateOutputValidationError(updateName, issues): UpdateOutputValidationError;

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

Parameters ​
ParameterType
updateNamestring
issuesreadonly Issue[]
Returns ​

UpdateOutputValidationError

Overrides ​
ts
ValidationError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
category?readonly"BENIGN" | null-ValidationError.categorynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:114
cause?readonlyError-ValidationError.causenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:72
details?readonlyunknown[] | null-ValidationError.detailsnode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:112
directionreadonly"output"--packages/worker/src/errors.ts:259
failure?publicIFailureThe original failure that constructed this error. Only present if this error was generated from an external operation.ValidationError.failurenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:78
issuesreadonlyreadonly Issue[]-ValidationError.issuespackages/worker/src/errors.ts:64
messagepublicstring-ValidationError.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-ValidationError.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
nextRetryDelay?readonlyany-ValidationError.nextRetryDelaynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:113
nonRetryable?readonlyboolean | null-ValidationError.nonRetryablenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:111
stack?publicstring-ValidationError.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
type?readonlystring | null-ValidationError.typenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:110
updateNamereadonlystring--packages/worker/src/errors.ts:262
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.ValidationError.stackTraceLimitnode_modules/.pnpm/@types+node@22.20.4/node_modules/@types/node/globals.d.ts:68

Methods ​

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

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

ValidationError.captureStackTrace

create() ​
ts
static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:131

Create a new ApplicationFailure.

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

Parameters ​
ParameterType
optionsApplicationFailureOptions
Returns ​

ApplicationFailure

Inherited from ​

ValidationError.create

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:125

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

Inherited from ​

ValidationError.fromError

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:151

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

Inherited from ​

ValidationError.nonRetryable

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

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

ValidationError.prepareStackTrace

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:140

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

Inherited from ​

ValidationError.retryable

WorkflowCancelledError ​

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

Error surfaced in the Err(...) branch of an AsyncResult when a typed cancellation scope is cancelled via Temporal's cancellation propagation. Returned by both context.cancellableScope (when the workflow or an ancestor scope cancels) and context.nonCancellableScope (when cancellation is raised from inside the scope). Distinct from arbitrary thrown errors so call sites can branch on cancellation explicitly.

Non-cancellation errors thrown inside a scope are unmodeled failures: they surface on the scope's defect channel (re-thrown at the edge / inspectable via result.isDefect() and result.cause), not as a typed Err(...).

Swallowing this error changes the workflow outcome. Cancellation rides the modeled Err(...) channel here, so generic error handling (e.g. mapping every Err to a "failed" result and returning normally) makes the workflow complete as Completed instead of Cancelled. When the workflow should honor the cancellation request after cleanup, re-raise it with rethrowCancellation.

Extends ​

  • TaggedErrorInstance<"@temporal-contract/WorkflowCancelledError", { cause?: unknown; }>

Constructors ​

Constructor ​
ts
new WorkflowCancelledError(cause?): WorkflowCancelledError;

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

Parameters ​
ParameterType
cause?unknown
Returns ​

WorkflowCancelledError

Overrides ​
ts
TaggedError(WORKFLOW_CANCELLED_ERROR_TAG, {
  name: "WorkflowCancelledError",
})<{
  cause?: unknown;
}>.constructor

Properties ​

PropertyModifierTypeInherited fromDefined in
_tagreadonly"@temporal-contract/WorkflowCancelledError"TaggedError(WORKFLOW_CANCELLED_ERROR_TAG, { name: "WorkflowCancelledError", })._tagnode_modules/.pnpm/unthrown@5.11.0/node_modules/unthrown/dist/index.d.mts:2332
cause?publicunknownActivityDefinitionNotFoundError.causenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
messagepublicstringTaggedError(WORKFLOW_CANCELLED_ERROR_TAG, { name: "WorkflowCancelledError", }).messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstringTaggedError(WORKFLOW_CANCELLED_ERROR_TAG, { name: "WorkflowCancelledError", }).namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
stack?publicstringTaggedError(WORKFLOW_CANCELLED_ERROR_TAG, { name: "WorkflowCancelledError", }).stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

WorkflowInputValidationError ​

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

Error thrown when workflow input validation fails.

Extends ​

Constructors ​

Constructor ​
ts
new WorkflowInputValidationError(workflowName, issues): WorkflowInputValidationError;

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

Parameters ​
ParameterType
workflowNamestring
issuesreadonly Issue[]
Returns ​

WorkflowInputValidationError

Overrides ​
ts
ValidationError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
category?readonly"BENIGN" | null-ValidationError.categorynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:114
cause?readonlyError-ValidationError.causenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:72
details?readonlyunknown[] | null-ValidationError.detailsnode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:112
directionreadonly"input"--packages/worker/src/errors.ts:179
failure?publicIFailureThe original failure that constructed this error. Only present if this error was generated from an external operation.ValidationError.failurenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:78
issuesreadonlyreadonly Issue[]-ValidationError.issuespackages/worker/src/errors.ts:64
messagepublicstring-ValidationError.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-ValidationError.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
nextRetryDelay?readonlyany-ValidationError.nextRetryDelaynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:113
nonRetryable?readonlyboolean | null-ValidationError.nonRetryablenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:111
stack?publicstring-ValidationError.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
type?readonlystring | null-ValidationError.typenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:110
workflowNamereadonlystring--packages/worker/src/errors.ts:182
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.ValidationError.stackTraceLimitnode_modules/.pnpm/@types+node@22.20.4/node_modules/@types/node/globals.d.ts:68

Methods ​

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

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

ValidationError.captureStackTrace

create() ​
ts
static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:131

Create a new ApplicationFailure.

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

Parameters ​
ParameterType
optionsApplicationFailureOptions
Returns ​

ApplicationFailure

Inherited from ​

ValidationError.create

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:125

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

Inherited from ​

ValidationError.fromError

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:151

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

Inherited from ​

ValidationError.nonRetryable

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

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

ValidationError.prepareStackTrace

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:140

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

Inherited from ​

ValidationError.retryable

WorkflowOutputValidationError ​

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

Error thrown when workflow output validation fails.

Extends ​

Constructors ​

Constructor ​
ts
new WorkflowOutputValidationError(workflowName, issues): WorkflowOutputValidationError;

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

Parameters ​
ParameterType
workflowNamestring
issuesreadonly Issue[]
Returns ​

WorkflowOutputValidationError

Overrides ​
ts
ValidationError.constructor

Properties ​

PropertyModifierTypeDescriptionInherited fromDefined in
category?readonly"BENIGN" | null-ValidationError.categorynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:114
cause?readonlyError-ValidationError.causenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:72
details?readonlyunknown[] | null-ValidationError.detailsnode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:112
directionreadonly"output"--packages/worker/src/errors.ts:195
failure?publicIFailureThe original failure that constructed this error. Only present if this error was generated from an external operation.ValidationError.failurenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:78
issuesreadonlyreadonly Issue[]-ValidationError.issuespackages/worker/src/errors.ts:64
messagepublicstring-ValidationError.messagenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
namepublicstring-ValidationError.namenode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
nextRetryDelay?readonlyany-ValidationError.nextRetryDelaynode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:113
nonRetryable?readonlyboolean | null-ValidationError.nonRetryablenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:111
stack?publicstring-ValidationError.stacknode_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
type?readonlystring | null-ValidationError.typenode_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:110
workflowNamereadonlystring--packages/worker/src/errors.ts:198
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.ValidationError.stackTraceLimitnode_modules/.pnpm/@types+node@22.20.4/node_modules/@types/node/globals.d.ts:68

Methods ​

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

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

ValidationError.captureStackTrace

create() ​
ts
static create(options): ApplicationFailure;

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:131

Create a new ApplicationFailure.

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

Parameters ​
ParameterType
optionsApplicationFailureOptions
Returns ​

ApplicationFailure

Inherited from ​

ValidationError.create

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:125

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

Inherited from ​

ValidationError.fromError

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:151

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

Inherited from ​

ValidationError.nonRetryable

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

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

ValidationError.prepareStackTrace

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

Defined in: node_modules/.pnpm/@temporalio+common@1.24.0/node_modules/@temporalio/common/lib/failure.d.ts:140

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

Inherited from ​

ValidationError.retryable

Type Aliases ​

ActivityErrorsFor ​

ts
type ActivityErrorsFor<TActivity> = TActivity extends object ? 
  | ContractErrorUnion<TErrors>
  | ActivityError
  | ActivityCancelledError : 
  | ActivityError
  | ActivityCancelledError;

Defined in: packages/worker/src/activities-proxy.ts:46

The error channel for an activity call: declared contract errors when the activity declares an errors map, plus the two failures every activity can produce.

  • With an errors map — declared failures are rehydrated from the ApplicationFailure wire shape into typed ContractErrorUnion members (data re-validated against the declared schema).
  • Always — any other failure surfaces as ActivityError (with Temporal's ActivityFailure wrapper unwrapped to its actionable cause) or ActivityCancelledError (mirroring the child-workflow API).

Type Parameters ​

Type Parameter
TActivity extends ActivityDefinition

ChildWorkflowContractErrorsOf ​

ts
type ChildWorkflowContractErrorsOf<TWorkflow> = TWorkflow extends object ? ContractErrorUnion<TErrors> : never;

Defined in: packages/worker/src/child-workflow.ts:44

The typed child-call error channel's declared members: the child workflow's own declared errors, rehydrated from the failure it ended with (never when it declares none). Mirrors ActivityErrorsFor.

Type Parameters ​

Type Parameter
TWorkflow extends AnyWorkflowDefinition

ContractErrorUnion ​

ts
type ContractErrorUnion<TErrors> = { [K in keyof TErrors & string]: ContractError<K, InferErrorData<TErrors[K]>> }[keyof TErrors & string];

Defined in: packages/contract/dist/errors-impl-D7p9uupF.d.mts:79

Consumer-side union of ContractError instances for a declared errors map — data is typed with each schema's output (post-transform) shape. This is the union surfaced on the error channel of workflow-side activity calls and client-side workflow results.

Type Parameters ​

Type Parameter
TErrors extends Record<string, ErrorDefinition>

DeclareWorkflowOptions ​

ts
type DeclareWorkflowOptions<TContract, TWorkflowName> = object;

Defined in: packages/worker/src/workflow.ts:531

Options for declaring a workflow implementation

Type Parameters ​

Type Parameter
TContract extends ContractDefinition
TWorkflowName extends keyof TContract["workflows"] & string

Properties ​

PropertyTypeDescriptionDefined in
activityOptions?ActivityOptionsDefault activity options applied to every activity reachable from this workflow (workflow-local + global) unless overridden. Merge precedence per activity (least → most specific): this workflow-wide default → the activity's contract-level defineActivity({ activityOptions }) → the explicit activityOptionsByName entry. See Temporal's ActivityOptions for the full set of fields: - startToCloseTimeout: Maximum time for a single attempt to run - scheduleToCloseTimeout: End-to-end timeout including queuing and retries - scheduleToStartTimeout: Maximum time the activity can wait in the queue - heartbeatTimeout: Time between heartbeats before the activity is considered dead - retry: Retry policy for failed activities Example activityOptions: { startToCloseTimeout: '5m', retry: { maximumAttempts: 3 }, } Optional in isolation, but every activity reachable from this workflow (workflow-local + global) must end up with a bounded merged result: a per-attempt bound (startToCloseTimeout or scheduleToCloseTimeout) AND a total bound (scheduleToCloseTimeout, or a finite positive retry.maximumAttempts) — otherwise a failing activity retries forever. This is checked unconditionally on the MERGE of all three layers (activityOptions → the activity's contract-level defineActivity({ activityOptions }) → activityOptionsByName), not on any single layer in isolation: since each layer shallow-merges over the previous — replacing a retry block wholesale, not field-by-field — two individually-bounded layers can still merge to something unbounded. Supplying activityOptions here does not exempt an activity that carries its own contract-level or per-name options; if the FINAL merged result for any reachable activity is missing either bound, declareWorkflow throws ContractMisuseError at declaration time (workflow-bundle load), naming every offending activity and which bound(s) it lacks.packages/worker/src/workflow.ts:577
activityOptionsByName?Partial<Record<ActivityNamesFor<TContract, TWorkflowName>, ActivityOptions>>Per-activity ActivityOptions overrides. Each entry shallow-merges over activityOptions for that activity only — the override wins on every property it specifies, replacing the default value (including the entire nested retry block when present, matching Temporal's single-options-per-proxyActivities-call semantics). The override value is Temporal's full ActivityOptions, so any field is fair game — including taskQueue, which lets you route individual activities to dedicated worker pools (e.g. concurrency-capped queues for LLM calls) while the rest of the workflow's activities stay on the default queue. This keeps the Zod-validated typed-activities boundary intact, where a raw proxyActivities({ taskQueue }) would forfeit it. Activity names are typed against the contract; typos surface as TypeScript errors rather than running silently with the default options. Examples Tune timeouts and retries per activity // default — both bounds live here; fastValidationbelow only // overridesstartToCloseTimeout, so it still inherits this retry. activityOptions: { startToCloseTimeout: '1 minute', retry: { maximumAttempts: 3 } }, activityOptionsByName: { chargePayment: { startToCloseTimeout: '5 minutes', retry: { maximumAttempts: 5 }, }, fastValidation: { startToCloseTimeout: '5 seconds' }, }, Route specific activities to a dedicated task queue // default — both bounds live here; the taskQueue-only override below // still inherits this retry. activityOptions: { startToCloseTimeout: '10 minutes', retry: { maximumAttempts: 3 } }, // default queue activityOptionsByName: { // LLM call → dedicated, concurrency-capped queue. extractLayoutChunk: { taskQueue: 'gemini-pro' }, // finalizeLayout, extractImages, … fall through to the default queue. },packages/worker/src/workflow.ts:621
contractTContract-packages/worker/src/workflow.ts:536
implementationWorkflowImplementation<TContract, TWorkflowName>-packages/worker/src/workflow.ts:537
workflowNameTWorkflowName-packages/worker/src/workflow.ts:535

QueryHandlerImplementation ​

ts
type QueryHandlerImplementation<TQuery> = (args) => WorkerInferOutput<TQuery>;

Defined in: packages/worker/src/handlers.ts:48

Query handler implementation

Processes query input and returns a synchronous response. Must be synchronous to satisfy Temporal's query constraints.

Type Parameters ​

Type Parameter
TQuery extends QueryDefinition

Parameters ​

ParameterType
argsWorkerInferInput<TQuery>

Returns ​

WorkerInferOutput<TQuery>

SignalHandlerImplementation ​

ts
type SignalHandlerImplementation<TSignal> = (args) => void | Promise<void>;

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

Signal handler implementation

Processes signal input and can optionally perform asynchronous operations. Should not return a value (signals are fire-and-forget).

Type Parameters ​

Type Parameter
TSignal extends SignalDefinition

Parameters ​

ParameterType
argsWorkerInferInput<TSignal>

Returns ​

void | Promise<void>

TypedChildWorkflowHandle ​

ts
type TypedChildWorkflowHandle<TWorkflow> = object;

Defined in: packages/worker/src/child-workflow.ts:111

Typed handle for a child workflow with unthrown AsyncResult pattern.

Type Parameters ​

Type Parameter
TWorkflow extends AnyWorkflowDefinition

Properties ​

PropertyTypeDescriptionDefined in
firstExecutionRunIdstringRun ID of the child's first execution — the anchor of its execution chain (stable across continue-as-new), mirroring the field Temporal exposes on its own ChildWorkflowHandle.packages/worker/src/child-workflow.ts:136
result() => AsyncResult<ClientInferOutput<TWorkflow>, | ChildWorkflowError | ChildWorkflowCancelledError | ChildWorkflowContractErrorsOf<TWorkflow>>Get child workflow result with AsyncResult pattern.packages/worker/src/child-workflow.ts:115
signalsTypedChildWorkflowSignals<TWorkflow>Typed signal senders for the child's declared signals — see TypedChildWorkflowSignals. Empty when the child declares none.packages/worker/src/child-workflow.ts:124
workflowIdstringChild workflow ID.packages/worker/src/child-workflow.ts:129

TypedChildWorkflowOptions ​

ts
type TypedChildWorkflowOptions<TChildContract, TChildWorkflowName> = Omit<ChildWorkflowOptions, 
  | "taskQueue"
  | "args"
  | "parentClosePolicy"
  | "workflowId"
  | "workflowIdReusePolicy"> & ChildWorkflowIdField<TChildContract["workflows"][TChildWorkflowName]> & object;

Defined in: packages/worker/src/child-workflow.ts:79

Options for starting a child workflow. taskQueue and args come from the contract, as does workflowIdReusePolicy — derived from the target workflow's declared startPolicy, with no per-call override (as on the client) — and the workflowId when the target derives it; everything else is forwarded to Temporal's startChild / executeChild.

parentClosePolicy is required. Temporal's default is TERMINATE: when the parent closes, the child is killed — mid-payment included. That default is fine when chosen and dangerous when inherited, so it must be stated. TERMINATE remains available; it simply has to be written down.

The Exclude is load-bearing. The SDK's ParentClosePolicy union contains undefined (via the deprecated PARENT_CLOSE_POLICY_UNSPECIFIED member), so a bare required field would still accept undefined and require nothing.

Type Declaration ​

NameTypeDefined in
argsClientInferInput<TChildContract["workflows"][TChildWorkflowName]>packages/worker/src/child-workflow.ts:87
parentClosePolicyExclude<ParentClosePolicy, undefined>packages/worker/src/child-workflow.ts:88

Type Parameters ​

Type Parameter
TChildContract extends ContractDefinition
TChildWorkflowName extends keyof TChildContract["workflows"] & string

TypedChildWorkflowSignals ​

ts
type TypedChildWorkflowSignals<TWorkflow> = { [K in InferSignalNames<TWorkflow>]: (args: ClientInferInput<SignalDefOf<TWorkflow, K>>) => AsyncResult<void, ChildWorkflowError | ChildWorkflowCancelledError> };

Defined in: packages/worker/src/child-workflow.ts:102

Typed signal senders for a child workflow, keyed by the signal names declared on the child's contract entry. Mirrors the shape of the typed client handle's signals proxy: one function per declared signal, taking the signal's (client-perspective) input and returning an AsyncResult.

Per the wire-format rule (D1), the sender validates args against the signal's input schema — failing early with Err(ChildWorkflowError) — but transmits the caller's ORIGINAL value; the child's signal handler parses it on receive, so a transforming schema applies exactly once.

Type Parameters ​

Type Parameter
TWorkflow extends AnyWorkflowDefinition

TypedContinueAsNewOptions ​

ts
type TypedContinueAsNewOptions = Omit<ContinueAsNewOptions, "workflowType" | "taskQueue">;

Defined in: packages/worker/src/internal.ts:226

Continue-as-new options the typed wrapper does not own. workflowType and taskQueue are derived from the contract; everything else is forwarded to Temporal's makeContinueAsNewFunc.

TypedExecuteActivityOptions ​

ts
type TypedExecuteActivityOptions<TActivity> = Omit<ActivityOptions, "taskQueue"> & object;

Defined in: packages/worker/src/activities-proxy.ts:116

Options for context.executeActivity: the activity's args, plus Temporal's ActivityOptions minus taskQueue, which comes from the target contract.

Type Declaration ​

NameTypeDefined in
argsClientInferInput<TActivity>packages/worker/src/activities-proxy.ts:120

Type Parameters ​

Type Parameter
TActivity extends ActivityDefinition

UpdateHandlerImplementation ​

ts
type UpdateHandlerImplementation<TUpdate> = (args) => Promise<WorkerInferOutput<TUpdate>>;

Defined in: packages/worker/src/handlers.ts:58

Update handler implementation

Processes update input and returns a validated response after modifying workflow state. Can perform asynchronous operations.

Type Parameters ​

Type Parameter
TUpdate extends UpdateDefinition

Parameters ​

ParameterType
argsWorkerInferInput<TUpdate>

Returns ​

Promise<WorkerInferOutput<TUpdate>>

WorkflowContext ​

ts
type WorkflowContext<TContract, TWorkflowName> = object;

Defined in: packages/worker/src/workflow.ts:659

Workflow execution context providing typed activities, workflow info, and interaction handlers

Provides access to:

  • Typed activities (both workflow-specific and global)
  • Workflow metadata and execution info
  • Signal, query, and update handler registration
  • Child workflow execution capabilities

Type Parameters ​

Type Parameter
TContract extends ContractDefinition
TWorkflowName extends keyof TContract["workflows"] & string

Properties ​

PropertyModifierTypeDescriptionDefined in
activitiespublicReadonly<WorkflowInferWorkflowContextActivities<TContract, TWorkflowName>>-packages/worker/src/workflow.ts:663
cancellableScopepublic<T>(fn) => AsyncResult<Awaited<T>, WorkflowCancelledError>Run fn inside a cancellable Temporal scope. If the workflow (or an ancestor scope) is cancelled while fn is in flight, the resulting AsyncResult resolves to Err(WorkflowCancelledError) instead of rejecting — letting callers handle cancellation explicitly, typically to perform a graceful exit from the current step. Non-cancellation errors thrown by fn are unmodeled failures: they ride unthrown's defect channel (inspectable via result.isDefect() / result.cause, re-thrown at the edge), keeping the modeled error channel to the single anticipated outcome — cancellation. Example implementation: async (context, args) => { const result = await context.cancellableScope(async () => { // fn's return value is awaited, so returning the activity's // AsyncResult directly would make the scope's value its settled // Result(nested inside the scope's own). Narrowing it here instead // keeps the scope's value a plain domain value. const step = await context.activities.processStep(args); if (step.isDefect()) { throw step.cause; // an unmodeled bug — surfaces as the scope's own defect } return step.isOk() ? { status: "ok" as const } : { status: "failed" as const }; }); if (result.isDefect()) { throw result.cause; // a genuine bug thrown inside the scope, not a cancel } if (result.isErr()) { // The scope itself was cancelled — perform cleanup that must not be // cancelled. Capture nonCancellableScope's OWN AsyncResult too — a // bareawait here would silently discard a defect thrown inside // the cleanup callback. const released = await context.nonCancellableScope(async () => { const step = await context.activities.releaseResources(args); if (step.isErr()) { // best-effort cleanup — log and continue regardless } }); if (released.isDefect()) { throw released.cause; // a genuine bug in cleanup, not a cancel } return { status: "cancelled" }; } return result.value; }packages/worker/src/workflow.ts:999
continueAsNewpublic{ (args, options?): Promise<never>; <TOtherContract, TOtherWorkflowName> (contract, workflowName, args, options?): Promise<never>; }Continue this workflow execution as a new run, optionally with a different workflow type from another contract. Args are validated against the destination workflow's input schema before Temporal's continueAsNew is invoked. On validation failure, throws a WorkflowInputValidationError; on success, Temporal terminates the current execution and starts a fresh one — which is why the function never returns normally (Promise<never>). Idiomatic usage: Example // Same workflow, validated args implementation: async (context, args) => { if (shouldRoll(args)) { return context.continueAsNew({ ...args, retryCount: args.retryCount + 1 }); } return ...; } // Cross-contract continueAsNew (less common — taskQueue and workflow type // come from the other contract) return context.continueAsNew(otherContract, "otherWorkflow", { ...newArgs });packages/worker/src/workflow.ts:1078
errorspublicWorkflowErrorConstructorsOf<TContract["workflows"][TWorkflowName]>Typed constructors for the errors declared on this workflow's contract entry (defineWorkflow({ errors: {...} })). Throwing one fails the execution with a typed, schema-validated failure the client rehydrates into a ContractError: Example implementation: async (context, args) => { if (!args.items.length) { throw context.errors.EmptyOrder({ orderId: args.orderId }); } // ... }packages/worker/src/workflow.ts:687
executeActivitypublic<TTargetContract, TActivityName>(contract, activityName, options) => AsyncResult<ClientInferOutput<ContractActivityOf<TTargetContract, TActivityName>>, ActivityErrorsFor<ContractActivityOf<TTargetContract, TActivityName>>>Execute a global activity of any contract on that contract's task queue — typically an activity-only contract served by its own worker pool (PDF rendering, a rate-limited LLM lane). The queue is written once, on the contract whose worker polls it, instead of in an activityOptionsByName entry per calling workflow. The call behaves like context.activities.X: args is validated before dispatch, the result is parsed on receive, and failures come back as the activity's declared contract errors, ActivityError or ActivityCancelledError. Options merge shallowly: this workflow's activityOptions → the activity's contract-level activityOptions → the per-call options. The merged result needs a per-attempt and a total bound; an unbounded call, or an undeclared activity name, is a defect carrying a ContractMisuseError. Example // pdf.contract.ts — served by a dedicated worker on the "pdf" queue export const pdfContract = defineContract({ taskQueue: "pdf", workflows: {}, activities: { renderInvoice }, }); // in a workflow of another contract const pdf = await propagateFailure( context.executeActivity(pdfContract, "renderInvoice", { args: { invoiceId: order.invoiceId }, }), );packages/worker/src/workflow.ts:935
executeChildWorkflowpublic<TChildContract, TChildWorkflowName>(contract, workflowName, options) => AsyncResult<ClientInferOutput<TChildContract["workflows"][TChildWorkflowName]>, | ChildWorkflowError | ChildWorkflowCancelledError | ChildWorkflowNotFoundError | ChildWorkflowContractErrorsOf<TChildContract["workflows"][TChildWorkflowName]>>Execute a child workflow (start and wait for result) with AsyncResult pattern The contract argument is always required — it identifies the task queue and workflow definition the child runs against, and supplies the workflowIdReusePolicy from the target workflow's declared startPolicy: - Same-contract child: pass this worker's own contract and one of its workflow names. - Cross-contract child: pass another worker's contract to invoke a workflow it serves (the child's task queue comes from that contract). There is no per-call workflowIdReusePolicy override — the contract's startPolicy owns it, as on the client. A child that derives its ID on the contract (defineWorkflow({ workflowId })) gets it computed from the validated args, and options.workflowId is a type error. A child that fails with one of its own declared errors comes back as that typed ContractError (rehydrated against the child's errors), so context.saga compensates on it like a declared activity error. Example import { P } from "unthrown"; // Same contract child workflow const result = await context.executeChildWorkflow(myContract, 'processPayment', { workflowId: 'payment-123', args: { amount: 100 }, parentClosePolicy: 'TERMINATE' }); // Cross-contract child workflow (from another worker) const otherResult = await context.executeChildWorkflow(otherContract, 'sendNotification', { workflowId: 'notification-123', args: { message: 'Hello' }, parentClosePolicy: 'TERMINATE' }); await result.match({ ok: (output) => console.log('Payment processed:', output), errCases: (matcher) => matcher.with( P.tag('@temporal-contract/ChildWorkflowError'), P.tag('@temporal-contract/ChildWorkflowCancelledError'), P.tag('@temporal-contract/ChildWorkflowNotFoundError'), (error) => console.error('Processing failed:', error), ), defect: (cause) => console.error('Unexpected failure:', cause), });packages/worker/src/workflow.ts:887
handleQuerypublic<K>(queryName, handler) => voidBind a query handler within the workflow implementation (handle* — the in-workflow binding tier of the verb convention). Allows the query handler to access workflow state. Both query schemas (input and output) must validate synchronously — Temporal runs query handlers synchronously. A query whose schema validates asynchronously (e.g. zod async refine) is rejected with a ContractMisuseError. Example implementation: async (context, args) => { let currentValue = args.initialValue; context.handleQuery('getCurrentValue', () => { return { value: currentValue }; }); // ... rest of workflow }packages/worker/src/workflow.ts:735
handleSignalpublic<K>(signalName, handler) => voidBind a signal handler within the workflow implementation (handle* — the in-workflow binding tier of the verb convention). Allows the signal handler to access workflow state. Example implementation: async (context, args) => { let currentValue = args.initialValue; context.handleSignal('increment', async (signalArgs) => { currentValue += signalArgs.amount; }); // ... rest of workflow }packages/worker/src/workflow.ts:707
handleUpdatepublic<K>(updateName, handler) => voidBind an update handler within the workflow implementation (handle* — the in-workflow binding tier of the verb convention). Allows the update handler to access and modify workflow state. The update's input schema must validate synchronously — it feeds Temporal's synchronous update validator slot. An update whose input validates asynchronously is rejected with a ContractMisuseError (the output schema may be async; it runs inside the handler body). A library error the handler throws (throw context.errors.X(...), throw result.error) rejects the update with the Temporal failure it carries, the same mapping declareWorkflow applies to the implementation. Example implementation: async (context, args) => { let currentValue = args.initialValue; context.handleUpdate('multiply', async (updateArgs) => { currentValue *= updateArgs.factor; return { newValue: currentValue }; }); // ... rest of workflow }packages/worker/src/workflow.ts:769
inforeadonlyWorkflowInfoThe current workflowInfo() — read on every access, so fields the SDK updates between activations (historyLength, continueAsNewSuggested, …) stay current. Don't destructure it once at the top of the workflow.packages/worker/src/workflow.ts:669
nonCancellableScopepublic<T>(fn) => AsyncResult<Awaited<T>, WorkflowCancelledError>Run fn inside a non-cancellable Temporal scope. Cancellation requests from outside the scope are ignored for its duration — the idiomatic way to perform cleanup work that must not be interrupted. Returns the same AsyncResult<...> shape as WorkflowContext.cancellableScope for symmetry; the Err(WorkflowCancelledError) branch only triggers when cancellation is raised from inside the scope, which is rare. Non-cancellation errors surface on the defect channel.packages/worker/src/workflow.ts:1014
sagapublic(options?) => WorkflowSagaBuilder<undefined, never>Open a saga: a sequence of steps whose compensations are unwound LIFO when a later step fails. The undos run on a declared contract error — a permanent domain answer, where what the step did before saying no is knowable. They do NOT run on an ActivityError, a ChildWorkflowError or a defect: an activity that failed unmodelled left state nobody can see, and un-deciding what you cannot see is a second bug. That failure propagates untouched, so propagateFailure still re-raises Temporal's original failure. Cancellation is the one case a caller may opt back in to, with saga({ compensateOnCancellation: true }). Every undo runs inside a non-cancellable scope, so a cancellation cannot interrupt the walk-back it triggered. Example const fulfilled = await context .saga() .step( () => context.activities.reserveStock(order), (reservation) => context.activities.releaseStock({ id: reservation.id }), ) .step( () => context.activities.chargeCard(order), (charge) => context.activities.refund({ id: charge.id }), ) .step(() => context.activities.ship(order)) .run();packages/worker/src/workflow.ts:1049
startChildWorkflowpublic<TChildContract, TChildWorkflowName>(contract, workflowName, options) => AsyncResult<TypedChildWorkflowHandle<TChildContract["workflows"][TChildWorkflowName]>, | ChildWorkflowError | ChildWorkflowCancelledError | ChildWorkflowNotFoundError>Start a child workflow and return a typed handle with AsyncResult pattern The contract argument is always required — it identifies the task queue and workflow definition the child runs against, and supplies the workflowIdReusePolicy from the target workflow's declared startPolicy: - Same-contract child: pass this worker's own contract and one of its workflow names. - Cross-contract child: pass another worker's contract to invoke a workflow it serves (the child's task queue comes from that contract). There is no per-call workflowIdReusePolicy override — the contract's startPolicy owns it, as on the client. A child that derives its ID on the contract (defineWorkflow({ workflowId })) gets it computed from the validated args, and options.workflowId is a type error. Example import { P } from "unthrown"; // Same contract child workflow const childResult = await context.startChildWorkflow(myContract, 'processPayment', { workflowId: 'payment-123', args: { amount: 100 }, parentClosePolicy: 'TERMINATE' }); // Cross-contract child workflow (from another worker) const otherResult = await context.startChildWorkflow(otherContract, 'sendNotification', { workflowId: 'notification-123', args: { message: 'Hello' }, parentClosePolicy: 'TERMINATE' }); await childResult.match({ ok: async (handle) => { const result = await handle.result(); // ... handle result }, errCases: (matcher) => matcher.with( P.tag('@temporal-contract/ChildWorkflowError'), P.tag('@temporal-contract/ChildWorkflowCancelledError'), P.tag('@temporal-contract/ChildWorkflowNotFoundError'), (error) => console.error('Failed to start:', error), ), defect: (cause) => console.error('Unexpected failure:', cause), });packages/worker/src/workflow.ts:824

WorkflowImplementation ​

ts
type WorkflowImplementation<TContract, TWorkflowName> = (context, args) => Promise<WorkerInferOutput<TContract["workflows"][TWorkflowName]>>;

Defined in: packages/worker/src/workflow.ts:632

Workflow implementation function

Receives a workflow context (with typed activities and utilities) and validated input arguments. Returns the workflow output which will be validated against the contract schema.

Type Parameters ​

Type Parameter
TContract extends ContractDefinition
TWorkflowName extends keyof TContract["workflows"] & string

Parameters ​

ParameterType
contextWorkflowContext<TContract, TWorkflowName>
argsWorkerInferInput<TContract["workflows"][TWorkflowName]>

Returns ​

Promise<WorkerInferOutput<TContract["workflows"][TWorkflowName]>>

WorkflowInferActivity ​

ts
type WorkflowInferActivity<TActivity> = (args) => AsyncResult<ClientInferOutput<TActivity>, ActivityErrorsFor<TActivity>>;

Defined in: packages/worker/src/activities-proxy.ts:66

Activity function signature from workflow execution perspective.

Workflows call activities with the input schema's input type and receive the output schema's output (parsed) type: the workflow side validates the input but transmits the original value (the activity worker parses it on receive), and parses the activity's result on receive.

Every activity call returns an AsyncResult — the call convention no longer depends on whether the contract declared errors, only the error channel does. To let a failure escape and have Temporal decide the workflow's outcome, use propagateFailure rather than unthrown's .getOrThrow(); see that function's documentation for why.

Type Parameters ​

Type Parameter
TActivity extends ActivityDefinition

Parameters ​

ParameterType
argsClientInferInput<TActivity>

Returns ​

AsyncResult<ClientInferOutput<TActivity>, ActivityErrorsFor<TActivity>>

WorkflowInferWorkflowContextActivities ​

ts
type WorkflowInferWorkflowContextActivities<TContract, TWorkflowName> = WorkflowInferWorkflowActivities<TContract["workflows"][TWorkflowName]> & WorkflowInferActivities<TContract>;

Defined in: packages/worker/src/activities-proxy.ts:95

All activities available in a workflow context (workflow execution perspective).

Combines workflow-specific activities with global contract activities.

Type Parameters ​

Type Parameter
TContract extends ContractDefinition
TWorkflowName extends keyof TContract["workflows"] & string

WorkflowSagaBuilder ​

ts
type WorkflowSagaBuilder<T, E> = object;

Defined in: packages/worker/src/saga.ts:46

The builder workflowSaga returns.

Type Parameters ​

Type ParameterDescription
Twhat the last step produced, and what run() answers.
Ethe union of every step's modeled error type.

Properties ​

PropertyModifierTypeDescriptionDefined in
runreadonly() => AsyncResult<T, E>Run the steps in order, unwinding LIFO on a failure the policy compensates.packages/worker/src/saga.ts:67
stepreadonly<T2, E2, U, E3>(run, undo?) => WorkflowSagaBuilder<T2, E | E2>Add a step, with the undo that takes it back. Remarks run is a thunk and takes no argument; undo receives the value its own step produced. Either may answer a plain Result in place of an AsyncResult, so an undo is written as the ordinary activity call it is. The undo runs only when the failure that triggered the unwind is one the policy compensates — see workflowSaga. A compensation that itself fails becomes a defect carrying its own failure, which takes precedence over the failure that triggered the unwind and fails the workflow loudly: a refund that never happened is worse news than the order that could not ship. The remaining undos still run first.packages/worker/src/saga.ts:62

WorkflowSagaOptions ​

ts
type WorkflowSagaOptions = object;

Defined in: packages/worker/src/saga.ts:24

Options for workflowSaga.

Properties ​

PropertyModifierTypeDefault valueDescriptionDefined in
compensateOnCancellation?readonlybooleanfalseAlso compensate when a step fails because the workflow, an activity or a child workflow was cancelled. Remarks Off by default: a cancelled step stopped at a point nobody observed, so un-doing what it may or may not have done is a second bug. Turn it on for a workflow whose steps hold something a cancellation must release anyway — a seat, a reservation, a lock.packages/worker/src/saga.ts:37

Functions ​

bestEffort() ​

ts
function bestEffort<T, E>(result, onFailure): Promise<T | undefined>;

Defined in: packages/worker/src/activity-failure.ts:202

Await a call whose failure is not worth ending the workflow over — a notification, a metric, an audit write — and hand that failure to onFailure instead. Returns the value on success and undefined on failure, so a caller that wants the value can still narrow it.

The counterpart to propagateFailure: that one says "let Temporal decide", this one says "log it and carry on".

Cancellation is the exception, and that is the whole point of having this as a helper. A cancelled call arrives on the modeled Err channel like any other failure, so a hand-written best-effort fold absorbs it — and a workflow that absorbs its own cancellation runs to Completed after someone asked it to stop. Every cancellation shape (ActivityCancelledError, ChildWorkflowCancelledError, WorkflowCancelledError) is re-raised through rethrowCancellation before onFailure is ever reached, so the rule is structural instead of remembered at each call site.

A Defect (an unmodeled failure — a bug) is passed to onFailure like any other: the caller has already declared this call non-critical, and a notification bug must not block an outcome that is already authoritative. Reach for propagateFailure when that is not true.

Type Parameters ​

Type Parameter
T
E

Parameters ​

ParameterType
resultAsyncResult<T, E>
onFailure(failure) => void

Returns ​

Promise<T | undefined>

Example ​

ts
await bestEffort(
  context.activities.sendNotification({ customerId, subject, message }),
  (failure) => log.warn(`notification failed: ${String(failure)}`),
);

declareWorkflow() ​

ts
function declareWorkflow<TContract, TWorkflowName>(__namedParameters): (...args) => Promise<WorkerInferOutput<TContract["workflows"][TWorkflowName]>>;

Defined in: packages/worker/src/workflow.ts:279

Create a typed workflow implementation with automatic validation

This wraps a workflow implementation with:

  • Input/output validation
  • Typed workflow context with activities
  • Workflow info access

Workflows must be defined in separate files and imported by the Temporal Worker via workflowsPath.

Type Parameters ​

Type Parameter
TContract extends ContractDefinition
TWorkflowName extends string

Parameters ​

ParameterType
__namedParametersDeclareWorkflowOptions<TContract, TWorkflowName>

Returns ​

(...args) => Promise<WorkerInferOutput<TContract["workflows"][TWorkflowName]>>

Example ​

ts
// workflows/processOrder.ts
import { declareWorkflow } from '@temporal-contract/worker/workflow';
import myContract from '../contract.js';

export const processOrder = declareWorkflow({
  workflowName: 'processOrder',
  contract: myContract,
  activityOptions: {
    startToCloseTimeout: '1 minute',
    retry: { maximumAttempts: 3 },
  },
  // Optional: override `activityOptions` for specific activities. Each
  // entry shallow-merges over the workflow default — the override wins on
  // every property it specifies, including the whole `retry` block. The
  // override is Temporal's full `ActivityOptions`, so `taskQueue` works too,
  // letting you route individual activities to a dedicated worker pool.
  //
  // Every reachable activity's MERGED options need both a per-attempt bound
  // (`startToCloseTimeout` or `scheduleToCloseTimeout`) and a total bound
  // (`scheduleToCloseTimeout`, or a finite positive `retry.maximumAttempts`)
  // — the workflow default above supplies both, so `scoreRisk` below only
  // needs to override what it's actually changing (`taskQueue`).
  activityOptionsByName: {
    chargePayment: {
      startToCloseTimeout: '5 minutes',
      retry: { maximumAttempts: 5 },
    },
    // Route this activity to a dedicated, concurrency-capped queue; it
    // still inherits the workflow default's bounds (only `taskQueue` is
    // overridden here).
    scoreRisk: { taskQueue: 'ml-inference' },
  },
  implementation: async (context, args) => {
    // context.activities: typed activities (workflow + global)
    // context.info: WorkflowInfo

    // Every activity call returns an AsyncResult with three channels —
    // narrow `isDefect()`/`isErr()` (or use `propagateFailure` to
    // let Temporal decide the outcome) before reaching `.value`.
    const inventory = await context.activities.validateInventory({
      orderId: args.orderId,
    });
    if (inventory.isDefect()) throw inventory.cause;
    if (inventory.isErr()) {
      return { orderId: args.orderId, status: 'out_of_stock' };
    }

    if (!inventory.value.available) {
      return { orderId: args.orderId, status: 'out_of_stock' };
    }

    const payment = await context.activities.chargePayment({
      customerId: args.customerId,
      amount: 100,
    });
    if (payment.isDefect()) throw payment.cause;
    if (payment.isErr()) {
      return { orderId: args.orderId, status: 'failed' };
    }

    return {
      orderId: args.orderId,
      status: payment.value.success ? 'success' : 'failed',
      transactionId: payment.value.transactionId,
    };
  },
});

Then in your worker setup:

ts
// worker.ts
import { TypedWorker, workflowsPathFromURL } from '@temporal-contract/worker/worker';
import { activities } from './activities.js';
import myContract from './contract.js';

// `TypedWorker.create` returns AsyncResult<TypedWorker, never> — setup
// failures ride the defect channel, so `.get()` unwraps directly.
const worker = await TypedWorker.create({
  contract: myContract,
  connection,
  workflowsPath: workflowsPathFromURL(import.meta.url, './workflows.js'),
  activities,
}).get();

propagateFailure() ​

ts
function propagateFailure<T, E>(result): Promise<T>;

Defined in: packages/worker/src/activity-failure.ts:92

Await an activity call and return its value, re-raising the failure so Temporal decides the workflow's fate — the workflow-side equivalent of "let it fail".

Prefer this to unthrown's .getOrThrow(). getOrThrow throws the ActivityError / ActivityCancelledError wrapper itself, which is a TaggedError and NOT a TemporalFailure — Temporal would retry it as a workflow-TASK failure forever. declareWorkflow maps it at the boundary (see toTemporalFailure), but code in between sees the wrapper. This helper re-raises the original Temporal failure that classifyActivityError observed, right here — exactly what would have escaped the workflow before activity calls returned AsyncResult.

Two things are preserved on ActivityError, and they are NOT interchangeable:

  • cause — the unwrapped actionable failure (Temporal's ActivityFailure wrapper seen through). This is documented, caller-facing behavior that existing consumers narrow on, and this helper does not change it.
  • originalFailure — the value exactly as classifyActivityError caught it, before that unwrap (typically the ActivityFailure wrapper itself). This helper re-raises originalFailure (falling back to cause, then the wrapper) so the failure Temporal observes here is byte-for-byte what it would have observed had the activity call thrown directly — rethrowing cause instead would hand Temporal a bare ApplicationFailure where it previously saw an ActivityFailure, changing what a caller further up (e.g. the client's WorkflowFailedError.cause) sees.

ActivityCancelledError has no separate originalFailure: cancellation is detected before the unwrap, so its cause already holds the pre-unwrap original failure.

A rehydrated contract error (a ContractError read back from an activity's or child workflow's declared errors) re-raises its cause — the ApplicationFailure Temporal put on the wire — so the workflow fails with the callee's real typed failure. Any other ContractError is rethrown as-is, and declareWorkflow converts it against the workflow's own errors map. For a declared error the client therefore sees WorkflowFailedError.cause as a bare ApplicationFailure, never wrapped in Temporal's ActivityFailure / ChildWorkflowFailure — unlike the ActivityError path above, which preserves the wrapper.

Not just activity calls — hence the name. The same non-TemporalFailure-stall hazard applies to context.executeChildWorkflow / context.startChildWorkflow (ChildWorkflowError, ChildWorkflowCancelledError) and to context.cancellableScope / context.nonCancellableScope (WorkflowCancelledError, whose cause holds the original CancelledFailure). This helper accepts any of those too — E is intentionally unconstrained so a bare throw error at the bottom doesn't quietly stall the workflow for a union this module didn't anticipate.

ChildWorkflowCancelledError mirrors ActivityCancelledError: every construction site (classifyChildWorkflowError) supplies cause as the pre-unwrap cancellation failure Temporal produced, so it is always safe to re-raise. ChildWorkflowError, however, does NOT uniformly mirror ActivityError: classifyChildWorkflowError's own construction sites do set cause to the unwrapped actionable failure, but three OTHER construction sites in child-workflow.ts — input validation, output validation, and signal-input validation — build a ChildWorkflowError with no cause at all, because those failures are detected locally (a schema mismatch) before any Temporal call happens, so there is no Temporal-observed failure to carry. Re-raising the bare TaggedError in that case would reproduce the exact stall this helper exists to prevent, so when cause is absent this helper converts it to a ContractMisuseError instead — the same treatment ChildWorkflowNotFoundError gets below.

ChildWorkflowNotFoundError is the other case with no cause to rethrow: it fires before any Temporal call, when the target contract doesn't declare the child workflow name at all — a deterministic programmer bug, not a Temporal-observed failure. It is converted to a ContractMisuseError (a non-retryable ApplicationFailure) instead, so it still fails the workflow terminally rather than stalling it.

Type Parameters ​

Type Parameter
T
E

Parameters ​

ParameterType
resultAsyncResult<T, E>

Returns ​

Promise<T>

rethrowCancellation() ​

ts
function rethrowCancellation(error): never;

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

Re-raise a cancellation error surfaced on the modeled Err(...) channel so Temporal records the workflow execution as Cancelled.

The typed surfaces fold Temporal cancellation into Err(ActivityCancelledError | WorkflowCancelledError | ChildWorkflowCancelledError). That is deliberate — cancellation becomes an explicit branch — but it has a footgun: generic error handling that maps every Err to a domain "failed" outcome and returns normally makes the workflow complete as Completed, silently overriding the server's cancellation request. When the workflow should honor the cancellation (typically after nonCancellableScope cleanup), call this helper: it throws the original CancelledFailure carried in error.cause (or a fresh CancelledFailure when no cause was attached — the bare tagged error is not a TemporalFailure and would stall the workflow), which Temporal recognizes and turns into a Cancelled workflow outcome.

Workflow-sandbox safe: no I/O, no wall clock — it only rethrows.

Parameters ​

ParameterType
error| ChildWorkflowCancelledError | WorkflowCancelledError | ActivityCancelledError

Returns ​

never

Example ​

ts
// `fn`'s return value is awaited; narrow the activity's own Result HERE so
// the scope's value is a plain domain value, not a nested `Result`.
const result = await context.cancellableScope(async () => {
  const step = await context.activities.processStep(args);
  if (step.isDefect()) {
    throw step.cause;
  }
  return step.isOk();
});
if (result.isDefect()) {
  throw result.cause; // a genuine bug thrown inside the scope, not a cancel
}
if (result.isErr()) {
  // Capture nonCancellableScope's OWN AsyncResult too — a bare `await`
  // would silently discard a defect thrown during cleanup.
  const released = await context.nonCancellableScope(async () => {
    const step = await context.activities.releaseResources(args);
    if (step.isErr()) {
      // best-effort cleanup — log and continue regardless
    }
  });
  if (released.isDefect()) {
    throw released.cause; // a genuine bug in cleanup, not a cancel
  }
  // Honor the cancellation instead of completing normally:
  rethrowCancellation(result.error);
}

workflowSaga() ​

ts
function workflowSaga(options?): WorkflowSagaBuilder<undefined, never>;

Defined in: packages/worker/src/saga.ts:138

Open a saga whose undos run only on a failure the policy compensates.

Parameters ​

ParameterType
options?WorkflowSagaOptions

Returns ​

WorkflowSagaBuilder<undefined, never>

Remarks ​

Pure control flow — no timers, no clock, no randomness — so it replays deterministically inside the workflow sandbox. The failure comes back unchanged, so a caller triages exactly what it would have without the saga.

Example ​

ts
const fulfilled = await context
  .saga()
  .step(
    () => context.activities.reserveStock(order),
    (reservation) => context.activities.releaseStock({ id: reservation.id }),
  )
  .step(
    () => context.activities.chargeCard(order),
    (charge) => context.activities.refund({ id: charge.id }),
  )
  .step(() => context.activities.ship(order))
  .run();

References ​

ACTIVITY_CANCELLED_ERROR_TAG ​

Re-exports ACTIVITY_CANCELLED_ERROR_TAG

ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG ​

Re-exports ACTIVITY_DEFINITION_NOT_FOUND_ERROR_TAG

ACTIVITY_ERROR_TAG ​

Re-exports ACTIVITY_ERROR_TAG

ActivityInputValidationError ​

Re-exports ActivityInputValidationError

ActivityOutputValidationError ​

Re-exports ActivityOutputValidationError

AnyContractError ​

Re-exports AnyContractError

CHILD_WORKFLOW_CANCELLED_ERROR_TAG ​

Re-exports CHILD_WORKFLOW_CANCELLED_ERROR_TAG

CHILD_WORKFLOW_ERROR_TAG ​

Re-exports CHILD_WORKFLOW_ERROR_TAG

CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG ​

Re-exports CHILD_WORKFLOW_NOT_FOUND_ERROR_TAG

ContractError ​

Re-exports ContractError

ContractErrorConstructors ​

Re-exports ContractErrorConstructors

ContractErrorDataValidationError ​

Re-exports ContractErrorDataValidationError

ContractErrorOptions ​

Re-exports ContractErrorOptions

ContractMisuseError ​

Re-exports ContractMisuseError

ValidationError ​

Re-exports ValidationError

WORKFLOW_CANCELLED_ERROR_TAG ​

Re-exports WORKFLOW_CANCELLED_ERROR_TAG

Released under the MIT License.

Copyright © 2026 Benoit TRAVERS

Part ofBtravStack