Skip to content

Commit 5ebcb22

Browse files
authored
docs: Improve API reference (#826)
1 parent a9098ee commit 5ebcb22

File tree

4 files changed

+41
-29
lines changed

4 files changed

+41
-29
lines changed

packages/activity/src/index.ts

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,19 @@
1515
*
1616
* ### Cancellation
1717
*
18-
* Activities may be cancelled only if they {@link Context.heartbeat | emit heartbeats}.
18+
* Activity Cancellation serves three purposes:
19+
*
20+
* - It lets an Activity know it doesn't need to keep doing work.
21+
* - It gives the Activity time to clean up any resources it has created.
22+
*
23+
* Activities may receive Cancellation only if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
24+
* (which can't heartbeat but receive Cancellation anyway).
1925
*
2026
* There are two ways to handle Activity cancellation:
2127
* 1. await on {@link Context.cancelled | `Context.current().cancelled`} or
22-
* {@link Context.sleep | `Context.current().sleep()`}, which each throw a
23-
* {@link CancelledFailure}.
28+
* {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
2429
* 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
25-
* {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that
26-
* supports it.
30+
* {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.
2731
*
2832
* ### Examples
2933
*
@@ -145,13 +149,16 @@ export interface Info {
145149
*/
146150
heartbeatTimeoutMs?: number;
147151
/**
148-
* Hold the details supplied to the last heartbeat on previous attempts of this Activity.
149-
* Use this in order to resume your Activity from checkpoint.
152+
* The {@link Context.heartbeat | details} from the last recorded heartbeat from the last attempt of this Activity.
153+
*
154+
* Use this to resume your Activity from a checkpoint.
150155
*/
151156
heartbeatDetails: any;
152157

153158
/**
154-
* Task queue the Activity is scheduled in, set to the Workflow's task queue in case of local Activity.
159+
* Task Queue the Activity is scheduled in.
160+
*
161+
* For Local Activities, this is set to the Workflow's Task Queue.
155162
*/
156163
taskQueue: string;
157164
}
@@ -224,7 +231,9 @@ export class Context {
224231
* attribute set to a {@link TimeoutFailure}, which has the last value of `details` available at
225232
* {@link TimeoutFailure.lastHeartbeatDetails}.
226233
*
227-
* Activities must heartbeat in order to receive cancellation.
234+
* Calling `heartbeat()` from a Local Activity has no effect.
235+
*
236+
* Activities must heartbeat in order to receive Cancellation (unless they're Local Activities, which don't need to).
228237
*/
229238
public heartbeat(details?: unknown): void {
230239
this.heartbeatFn(details);

packages/common/src/failure.ts

Lines changed: 7 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,9 @@ export type WorkflowExecution = temporal.api.common.v1.IWorkflowExecution;
3737
/**
3838
* Represents failures that can cross Workflow and Activity boundaries.
3939
*
40-
* Only exceptions that extend this class will be propagated to the caller.
40+
* **Never extend this class or any of its children.**
4141
*
42-
* **Never extend this class or any of its derivatives.** They are to be used by the SDK code
43-
* only. Throw an instance {@link ApplicationFailure} to pass application specific errors between
44-
* Workflows and Activities.
45-
*
46-
* Any unhandled exception thrown by an Activity or Workflow will be converted to an instance of
47-
* {@link ApplicationFailure}.
42+
* The only child class you should ever throw from your code is {@link ApplicationFailure}.
4843
*/
4944
export class TemporalFailure extends Error {
5045
public readonly name: string = 'TemporalFailure';
@@ -79,19 +74,17 @@ export class ServerFailure extends TemporalFailure {
7974
* `ApplicationFailure`, the Workflow Execution will fail.
8075
*
8176
* In Activities, you can either throw an `ApplicationFailure` or another `Error` to fail the Activity Task. In the
82-
* latter case, the `Error` will be converted to an `ApplicationFailure`. If the
83-
* {@link https://docs.temporal.io/concepts/what-is-an-activity-execution | Activity Execution} fails, the
84-
* `ApplicationFailure` from the last Activity Task will be the `cause` of the {@link ActivityFailure} thrown in the
85-
* Workflow.
86-
*
87-
* The conversion of an error that doesn't extend {@link TemporalFailure} to an `ApplicationFailure` is done as
88-
* following:
77+
* latter case, the `Error` will be converted to an `ApplicationFailure`. The conversion is done as following:
8978
*
9079
* - `type` is set to `error.constructor?.name ?? error.name`
9180
* - `message` is set to `error.message`
9281
* - `nonRetryable` is set to false
9382
* - `details` are set to null
9483
* - stack trace is copied from the original error
84+
*
85+
* When an {@link https://docs.temporal.io/concepts/what-is-an-activity-execution | Activity Execution} fails, the
86+
* `ApplicationFailure` from the last Activity Task will be the `cause` of the {@link ActivityFailure} thrown in the
87+
* Workflow.
9588
*/
9689
export class ApplicationFailure extends TemporalFailure {
9790
public readonly name: string = 'ApplicationFailure';

packages/worker/src/worker-options.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,9 @@ export interface WorkerOptions {
8686
workflowsPath?: string;
8787

8888
/**
89-
* Use a pre-built bundle for Workflow code. Use {@link bundleWorkflowCode} to generate a bundle.
89+
* Use a pre-built bundle for Workflow code. Use {@link bundleWorkflowCode} to generate the bundle. The version of
90+
* `@temporalio/worker` used when calling `bundleWorkflowCode` must be the exact same version used when calling
91+
* `Worker.create`.
9092
*
9193
* This is the recommended way to deploy Workers to production.
9294
*

packages/worker/src/worker.ts

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -457,7 +457,7 @@ export class Worker {
457457
* Create a replay Worker, and run the provided history against it. Will resolve as soon as
458458
* the history has finished being replayed, or if the workflow produces a nondeterminism error.
459459
*
460-
* @throws DeterminismViolationError if the workflow code is not compatible with the history.
460+
* @throws {@link DeterminismViolationError} if the workflow code is not compatible with the history.
461461
*/
462462
public static async runReplayHistory(options: ReplayWorkerOptions, history: History | unknown): Promise<void> {
463463
if (typeof history !== 'object' || history == null) {
@@ -653,10 +653,18 @@ export class Worker {
653653
}
654654

655655
/**
656-
* Start shutting down the Worker. Immediately transitions {@link state} to `'STOPPING'` and asks Core to shut down.
657-
* Once Core has confirmed that it's shutting down, the Worker enters `'DRAINING'` state unless the Worker has already
658-
* been `'DRAINED'`. All currently running Activities are Cancelled. Once all currently running Activities and
659-
* Workflow Tasks have completed, the Worker transitions to `'STOPPED'`.
656+
* Start shutting down the Worker. The Worker stops polling for new tasks and sends
657+
* {@link https://typescript.temporal.io/api/namespaces/activity#cancellation | cancellation} (via a
658+
* {@link CancelledFailure} with `message` set to `'WORKER_SHUTDOWN'`) to running Activities. Note: if the Activity
659+
* accepts cancellation (i.e. re-throws or allows the `CancelledFailure` to be thrown out of the Activity function),
660+
* the Activity Task will be marked as failed, not cancelled. It's helpful for the Activity Task to be marked failed
661+
* during shutdown because the Server will retry the Activity sooner (than if the Server had to wait for the Activity
662+
* Task to time out).
663+
*
664+
* When called, immediately transitions {@link state} to `'STOPPING'` and asks Core to shut down. Once Core has
665+
* confirmed that it's shutting down, the Worker enters `'DRAINING'` state unless the Worker has already been
666+
* `'DRAINED'`. Once all currently running Activities and Workflow Tasks have completed, the Worker transitions to
667+
* `'STOPPED'`.
660668
*/
661669
shutdown(): void {
662670
if (this.state !== 'RUNNING') {

0 commit comments

Comments
 (0)