docs: Improve API reference (#871)

Author: lorensr

CHANGELOG.md

@@ -1485,7 +1485,7 @@ Breaking changes marked with a :boom:
   - Add Workflow and WorkflowCreator interfaces to support pluggable workflow environments (prepare for VM)
   - :boom: Simplify external dependencies mechanism to only support void functions and remove the isolated-vm transfer options.
 
-- Support [`ms`](https://www.npmjs.com/package/ms) formatted string for activity.Context.sleep ([#322](https://github.com/temporalio/sdk-typescript/pull/322))
+- Support [`ms`](https://www.npmjs.com/package/ms)-formatted string for activity.Context.sleep ([#322](https://github.com/temporalio/sdk-typescript/pull/322))
 - :boom: Runtime determinism tweaks ([#326](https://github.com/temporalio/sdk-typescript/pull/326))
   - Undelete WeakMap and WeakSet
   - Delete FinalizationRegistry

packages/activity/src/index.ts

@@ -15,23 +15,45 @@
  *
  * ### Cancellation
  *
- * Activity Cancellation serves three purposes:
+ * Activity Cancellation:
  *
- * - It lets an Activity know it doesn't need to keep doing work.
- * - It gives the Activity time to clean up any resources it has created.
+ * - lets the Activity know it doesn't need to keep doing work, and
+ * - gives the Activity time to clean up any resources it has created.
  *
- * Activities may receive Cancellation only if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
+ * Activities can only receive Cancellation if they {@link Context.heartbeat | emit heartbeats} or are Local Activities
  * (which can't heartbeat but receive Cancellation anyway).
  *
- * There are two ways to handle Activity cancellation:
+ * An Activity may receive Cancellation if:
+ *
+ * - The Workflow scope containing the Activity call was requested to be Cancelled and
+ *   {@link ActivityOptions.cancellationType} was **not** set to {@link ActivityCancellationType.ABANDON}. The scope can
+ *   be cancelled in either of the following ways:
+ *   - The entire Workflow was Cancelled (via {@link WorkflowHandle.cancel}).
+ *   - Calling {@link CancellationScope.cancel}) from inside a Workflow.
+ * - The Worker has started to shut down. Shutdown is initiated by either:
+ *   - One of the {@link RuntimeOptions.shutdownSignals} was sent to the process.
+ *   - {@link Worker.shutdown | `Worker.shutdown()`} was called.
+ * - The Activity was considered failed by the Server because any of the Activity timeouts have triggered (for example,
+ *   the Server didn't receive a heartbeat within the {@link ActivityOptions.heartbeatTimeout}). The
+ *   {@link CancelledFailure} will have `message: 'TIMED_OUT'`.
+ * - An Activity sends a heartbeat with `Context.current().heartbeat()` and the heartbeat details can't be converted by
+ *   the Worker's configured {@link DataConverter}.
+ * - The Workflow Run reached a {@link https://docs.temporal.io/workflows#status | Closed state}, in which case the
+ *   {@link CancelledFailure} will have `message: 'NOT_FOUND'`.
+ *
+ * The reason for the Cancellation is available at {@link CancelledFailure.message} or
+ * {@link Context#cancellationSignal | Context.cancellationSignal.reason}.
+ *
+ * There are two ways to handle Activity Cancellation:
+ *
  * 1. await on {@link Context.cancelled | `Context.current().cancelled`} or
  *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
  * 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
  *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.
  *
  * ### Examples
  *
- * #### An Activity that sends progress heartbeats and can be cancelled
+ * #### An Activity that sends progress heartbeats and can be Cancelled
  *
  * <!--SNIPSTART typescript-activity-fake-progress-->
  * <!--SNIPEND-->
@@ -254,7 +276,7 @@ export class Context {
 
   /**
    * Helper function for sleeping in an Activity.
-   * @param ms Sleep duration: an {@link https://www.npmjs.com/package/ms | ms}-formatted string or number of milliseconds
+   * @param ms Sleep duration: number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @returns A Promise that either resolves when `ms` is reached or rejects when the Activity is cancelled
    */
   public sleep(ms: number | string): Promise<void> {

packages/client/src/connection.ts

@@ -63,7 +63,7 @@ export interface ConnectionOptions {
    * Used either when connecting eagerly with {@link Connection.connect} or
    * calling {@link Connection.ensureConnected}.
    *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 10 seconds
    */
   connectTimeout?: number | string;

packages/client/src/interceptors.ts

@@ -112,7 +112,7 @@ export interface WorkflowClientCallsInterceptor {
   describe?: (input: WorkflowDescribeInput, next: Next<this, 'describe'>) => Promise<DescribeWorkflowExecutionResponse>;
 }
 
-interface WorkflowClientCallsInterceptorFactoryInput {
+export interface WorkflowClientCallsInterceptorFactoryInput {
   workflowId: string;
   runId?: string;
 }

packages/client/src/workflow-client.ts

@@ -120,7 +120,17 @@ export interface WorkflowHandle<T extends Workflow = Workflow> extends BaseWorkf
   terminate(reason?: string): Promise<TerminateWorkflowExecutionResponse>;
 
   /**
-   * Cancel a running Workflow
+   * Cancel a running Workflow.
+   *
+   * When a Workflow is cancelled, the root scope throws {@link CancelledFailure} with `message: 'Workflow canceled'`.
+   * That means that all cancellable scopes will throw `CancelledFailure`.
+   *
+   * Cancellation may be propagated to Activities depending on {@link ActivityOptions#cancellationType}, after which
+   * Activity calls may throw an {@link ActivityFailure}, and `isCancellation(error)` will be true (see {@link isCancellation}).
+   *
+   * Cancellation may be propagated to Child Workflows depending on {@link ChildWorkflowOptions#cancellationType}, after
+   * which calls to {@link executeChild} and {@link ChildWorkflowHandle#result} will throw, and `isCancellation(error)`
+   * will be true (see {@link isCancellation}).
    */
   cancel(): Promise<RequestCancelWorkflowExecutionResponse>;
 

packages/internal-workflow-common/src/activity-options.ts

@@ -35,7 +35,7 @@ export interface ActivityOptions {
 
   /**
    * Heartbeat interval. Activity must heartbeat before this interval passes after a last heartbeat or activity start.
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   heartbeatTimeout?: string | number;
 
@@ -49,14 +49,14 @@ export interface ActivityOptions {
 Note that the Temporal Server doesn't detect Worker process failures directly. It relies on this timeout to detect that an Activity that didn't complete on time. So this timeout should be as short as the longest possible execution of the Activity body. Potentially long running Activities must specify {@link heartbeatTimeout} and call {@link activity.Context.heartbeat} periodically for timely failure detection.
 
    * Either this option or {@link scheduleToCloseTimeout} is required.
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   startToCloseTimeout?: string | number;
   /**
    * Time that the Activity Task can stay in the Task Queue before it is picked up by a Worker. Do not specify this timeout unless using host specific Task Queues for Activity Tasks are being used for routing.
    * `scheduleToStartTimeout` is always non-retryable. Retrying after this timeout doesn't make sense as it would just put the Activity Task back into the same Task Queue.
    * @default unlimited
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   scheduleToStartTimeout?: string | number;
 
@@ -66,7 +66,7 @@ Note that the Temporal Server doesn't detect Worker process failures directly. I
    *
    * Either this option or {@link startToCloseTimeout} is required
    * @default unlimited
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   scheduleToCloseTimeout?: string | number;
 
@@ -110,7 +110,7 @@ export interface LocalActivityOptions {
    * Either this option or {@link scheduleToCloseTimeout} is required.
    * If set, this must be <= {@link scheduleToCloseTimeout}, otherwise, it will be clamped down.
    *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   startToCloseTimeout?: string | number;
 
@@ -122,7 +122,7 @@ export interface LocalActivityOptions {
    * {@link scheduleToCloseTimeout} when set, otherwise, it will be clamped down.
    *
    * @default unlimited
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   scheduleToStartTimeout?: string | number;
 
@@ -134,7 +134,7 @@ export interface LocalActivityOptions {
    * Either this option or {@link startToCloseTimeout} is required.
    *
    * @default unlimited
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   scheduleToCloseTimeout?: string | number;
 
@@ -143,7 +143,7 @@ export interface LocalActivityOptions {
    * Otherwise, backoff will happen internally in the SDK.
    *
    * @default 1 minute
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    **/
   localRetryThreshold?: string | number;
 

packages/internal-workflow-common/src/retry-policy.ts

@@ -16,7 +16,7 @@ export interface RetryPolicy {
   /**
    * Interval of the first retry.
    * If coefficient is 1 then it is used for all retries
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 1 second
    */
   initialInterval?: string | number;
@@ -33,7 +33,7 @@ export interface RetryPolicy {
    * This value is the cap of the increase.
    *
    * @default 100x of {@link initialInterval}
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   maximumInterval?: string | number;
 

packages/internal-workflow-common/src/workflow-options.ts

@@ -111,7 +111,7 @@ export interface WorkflowDurationOptions {
    * rely on run timeout for business level timeouts. It is preferred to use in workflow timers
    * for this purpose.
    *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   workflowRunTimeout?: string | number;
 
@@ -121,14 +121,14 @@ export interface WorkflowDurationOptions {
    * automatically terminated by Temporal service. Do not rely on execution timeout for business
    * level timeouts. It is preferred to use in workflow timers for this purpose.
    *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   workflowExecutionTimeout?: string | number;
 
   /**
    * Maximum execution time of a single workflow task. Default is 10 seconds.
    *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   workflowTaskTimeout?: string | number;
 }

packages/test/src/worker/external-logger-example.ts

@@ -310,7 +310,7 @@ export class TestWorkflowEnvironment {
    *
    * This method is _likely_ to resolve in less than `durationMs` of "real time".
    *
-   * @param durationMs {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @param durationMs number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    *
    * @example
    *

packages/testing/src/index.ts

@@ -21,6 +21,7 @@ export {
 export { ActivityInboundLogInterceptor, activityLogAttributes } from './activity-log-interceptor';
 export { NativeConnection as NativeConnection } from './connection';
 export { NativeConnectionOptions, RequiredNativeConnectionOptions, TLSConfig } from './connection-options';
+export { startDebugReplayer } from './debug-replayer';
 export * from './errors';
 export * from './interceptors';
 export * from './logger';
@@ -33,11 +34,10 @@ export {
   defaultSinks,
   ReplayWorkerOptions,
   WorkerOptions,
-  WorkflowBundleOption,
   WorkflowBundle,
+  WorkflowBundleOption,
   WorkflowBundlePath,
   WorkflowBundlePathWithSourceMap, // eslint-disable-line deprecation/deprecation
 } from './worker-options';
-export { WorkflowInboundLogInterceptor, workflowLogAttributes } from './workflow-log-interceptor';
+export { LoggerSinks, WorkflowInboundLogInterceptor, workflowLogAttributes } from './workflow-log-interceptor';
 export { BundleOptions, bundleWorkflowCode, WorkflowBundleWithSourceMap } from './workflow/bundler';
-export { startDebugReplayer } from './debug-replayer';

packages/worker/src/index.ts

@@ -123,7 +123,7 @@ export interface WorkerOptions {
   /**
    * Time to wait for pending tasks to drain after shutdown was requested.
    *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 10s
    */
   shutdownGraceTime?: string | number;
@@ -185,7 +185,7 @@ export interface WorkerOptions {
   /**
    * How long a workflow task is allowed to sit on the sticky queue before it is timed out
    * and moved to the non-sticky queue where it may be picked up by any worker.
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 10s
    */
   stickyQueueScheduleToStartTimeout?: string;
@@ -208,7 +208,7 @@ export interface WorkerOptions {
 
   /**
    * Longest interval for throttling activity heartbeats
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 60 seconds
    */
   maxHeartbeatThrottleInterval?: number | string;
@@ -219,7 +219,7 @@ export interface WorkerOptions {
    * When the timeout *is* set in the `ActivityOptions`, throttling is set to
    * `heartbeat_timeout * 0.8`.
    *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 30 seconds
    */
   defaultHeartbeatThrottleInterval?: number | string;
@@ -342,7 +342,7 @@ export type WorkerOptionsWithDefaults = WorkerOptions &
 
     /**
      * Time to wait for result when calling a Workflow isolate function.
-     * @format {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
      *
      * This value is not exposed at the moment.
      *

packages/worker/src/worker-options.ts

@@ -8,7 +8,7 @@
  *
  * The recommended way of scheduling timers is by using the {@link sleep} function. We've replaced `setTimeout` and
  * `clearTimeout` with deterministic versions so these are also usable but have a limitation that they don't play well
- * with {@link https://docs.temporal.io/typescript/workflow-scopes-and-cancellation | cancellation scopes}.
+ * with {@link https://docs.temporal.io/typescript/cancellation-scopes | cancellation scopes}.
  *
  * <!--SNIPSTART typescript-sleep-workflow-->
  * <!--SNIPEND-->
@@ -34,16 +34,14 @@
  * <!--SNIPSTART typescript-workflow-signal-implementation-->
  * <!--SNIPEND-->
  *
- * ### Deterministic built-ins
- * It is safe to call `Math.random()` and `Date()` in workflow code as they are replaced with deterministic versions. We
- * also provide a deterministic {@link uuid4} function for convenience.
+ * ### More
  *
- * ### [Cancellation and scopes](https://docs.temporal.io/typescript/workflow-scopes-and-cancellation)
- * - {@link CancellationScope}
- * - {@link Trigger}
- *
- * ### [Sinks](https://docs.temporal.io/typescript/sinks)
- * - {@link Sinks}
+ * - [Deterministic built-ins](https://docs.temporal.io/typescript/determinism#sources-of-non-determinism)
+ * - [Cancellation and scopes](https://docs.temporal.io/typescript/cancellation-scopes)
+ *   - {@link CancellationScope}
+ *   - {@link Trigger}
+ * - [Sinks](https://docs.temporal.io/application-development/observability/?lang=ts#logging)
+ *   - {@link Sinks}
  *
  * @module
  */

packages/workflow/src/index.ts

@@ -169,12 +169,12 @@ export interface ContinueAsNewOptions {
   taskQueue?: string;
   /**
    * Timeout for the entire Workflow run
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   * @format {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   workflowRunTimeout?: string;
   /**
    * Timeout for a single Workflow task
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   * @format {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
   workflowTaskTimeout?: string;
   /**

packages/workflow/src/interfaces.ts

@@ -102,7 +102,7 @@ function timerNextHandler(input: TimerInput) {
  *
  * Schedules a timer on the Temporal service.
  *
- * @param ms sleep duration - {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds.
+ * @param ms sleep duration - number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}.
  * If given a negative number or 0, value will be set to 1.
  */
 export function sleep(ms: number | string): Promise<void> {
@@ -1068,7 +1068,7 @@ function patchInternal(patchId: string, deprecated: boolean): boolean {
 /**
  * Returns a Promise that resolves when `fn` evaluates to `true` or `timeout` expires.
  *
- * @param timeout {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+ * @param timeout number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
  *
  * @returns a boolean indicating whether the condition was true before the timeout expires
  */