doc: Revisit doc on [Activity|ChildWorkflow]CancellationTypes + other minor lints (#1892)

Author: mjameswh

packages/client/src/schedule-types.ts

@@ -31,7 +31,7 @@ export interface ScheduleOptions<A extends ScheduleOptionsAction = ScheduleOptio
      * running. This can be changed after a Schedule has taken some Actions, and some changes might produce
      * unintuitive results. In general, the later policy overrides the earlier policy.
      *
-     * @default {@link ScheduleOverlapPolicy.SKIP}
+     * @default ScheduleOverlapPolicy.SKIP
      */
     overlap?: ScheduleOverlapPolicy;
 

packages/client/src/task-queue-client.ts

@@ -173,6 +173,13 @@ export class TaskQueueClient extends BaseClient {
  */
 export type ReachabilityOptions = RequireAtLeastOne<BaseReachabilityOptions, 'buildIds' | 'taskQueues'>;
 
+/**
+ * There are different types of reachability:
+ *   - `NEW_WORKFLOWS`: The Build Id might be used by new workflows
+ *   - `EXISTING_WORKFLOWS` The Build Id might be used by open workflows and/or closed workflows.
+ *   - `OPEN_WORKFLOWS` The Build Id might be used by open workflows
+ *   - `CLOSED_WORKFLOWS` The Build Id might be used by closed workflows
+ */
 export const ReachabilityType = {
   /** The Build Id might be used by new workflows. */
   NEW_WORKFLOWS: 'NEW_WORKFLOWS',
@@ -186,14 +193,6 @@ export const ReachabilityType = {
   /** The Build Id might be used by closed workflows. */
   CLOSED_WORKFLOWS: 'CLOSED_WORKFLOWS',
 } as const;
-
-/**
- * There are different types of reachability:
- *   - `NEW_WORKFLOWS`: The Build Id might be used by new workflows
- *   - `EXISTING_WORKFLOWS` The Build Id might be used by open workflows and/or closed workflows.
- *   - `OPEN_WORKFLOWS` The Build Id might be used by open workflows
- *   - `CLOSED_WORKFLOWS` The Build Id might be used by closed workflows
- */
 export type ReachabilityType = (typeof ReachabilityType)[keyof typeof ReachabilityType];
 
 export const [encodeTaskReachability, decodeTaskReachability] = makeProtoEnumConverters<

packages/common/src/activity-options.ts

@@ -5,10 +5,57 @@ import { VersioningIntent } from './versioning-intent';
 import { makeProtoEnumConverters } from './internal-workflow';
 import { Priority } from './priority';
 
+// Note: The types defined in this file are here for legacy reasons. They should have been defined
+// in the 'workflow' package, instead of 'common'. They are now reexported from the 'workflow'
+// package, which is the preferred way to import them, but we unfortunately can't remove them from
+// here as that would be a breaking change.
+
+/**
+ * Determines:
+ * - whether cancellation requests should be propagated from the current Workflow to the Activity; and
+ * - when should the Activity cancellation be reported to Workflow (i.e. at which moment should the
+ *   Activity call's promise fail with an `ActivityFailure`, with `cause` set to a `CancelledFailure`).
+ *
+ * Note that this setting only applies to cancellation originating from cancellation being
+ * externally requested on the Workflow itself, or from internal cancellation of the
+ * `CancellationScope` in which the Activity call was made. Termination of a Workflow Execution
+ * always results in cancellation of its outstanding Activity executions, regardless of those
+ * Activities' {@link ActivityCancellationType} settings.
+ *
+ * @default ActivityCancellationType.WAIT_CANCELLATION_COMPLETED
+ */
 export const ActivityCancellationType = {
+  /**
+   * Do not propagate cancellation requests to the Activity, and immediately report cancellation
+   * to the caller.
+   */
+  ABANDON: 'ABANDON',
+
+  /**
+   * Propagate cancellation request from the Workflow to the Activity, yet _immediately_ report
+   * cancellation to the caller, i.e. without waiting for the server to confirm the cancellation
+   * request.
+   *
+   * Note that this cancellation type provides no guarantee, from the Workflow-side, that the
+   * cancellation request will actually be delivered to the Activity; e.g. the calling Workflow
+   * may exit before the delivery is completed, or the Activity may complete (either successfully
+   * or uncessfully) before the cancellation is delivered, resulting in a situation where the
+   * workflow thinks the activity was cancelled, but the activity actually completed successfully.
+   *
+   * To ensure that the Workflow is properly informed of the Activity's final state (i.e. either
+   * completion or cancellation), use {@link WAIT_CANCELLATION_COMPLETED}.
+   */
   TRY_CANCEL: 'TRY_CANCEL',
+
+  /**
+   * Propagate cancellation request from the Workflow to the Activity, and wait for the activity
+   * to complete its execution (either successfully, uncessfully, or as cancelled).
+   *
+   * Note that the Activity must heartbeat to receive a cancellation notification. This can block
+   * the Workflow's cancellation for a long time if the Activity doesn't heartbeat or chooses to
+   * ignore the cancellation request.
+   */
   WAIT_CANCELLATION_COMPLETED: 'WAIT_CANCELLATION_COMPLETED',
-  ABANDON: 'ABANDON',
 } as const;
 export type ActivityCancellationType = (typeof ActivityCancellationType)[keyof typeof ActivityCancellationType];
 
@@ -93,12 +140,18 @@ export interface ActivityOptions {
   scheduleToCloseTimeout?: Duration;
 
   /**
-   * Determines what the SDK does when the Activity is cancelled.
-   * - `TRY_CANCEL` - Initiate a cancellation request and immediately report cancellation to the workflow.
-   * - `WAIT_CANCELLATION_COMPLETED` - Wait for activity cancellation completion. Note that activity must heartbeat to receive a
-   *   cancellation notification. This can block the cancellation for a long time if activity doesn't
-   *   heartbeat or chooses to ignore the cancellation request.
-   * - `ABANDON` - Do not request cancellation of the activity and immediately report cancellation to the workflow.
+   * Determines:
+   * - whether cancellation requests should be propagated from the current Workflow to the Activity; and
+   * - when should the Activity cancellation be reported to Workflow (i.e. at which moment should the
+   *   Activity call's promise fail with an `ActivityFailure`, with `cause` set to a `CancelledFailure`).
+   *
+   * Note that this setting only applies to cancellation originating from cancellation being
+   * externally requested on the Workflow itself, or from internal cancellation of the
+   * `CancellationScope` in which the Activity call was made. Termination of a Workflow Execution
+   * always results in cancellation of its outstanding Activity executions, regardless of those
+   * Activities' {@link ActivityCancellationType} settings.
+   *
+   * @default ActivityCancellationType.WAIT_CANCELLATION_COMPLETED
    */
   cancellationType?: ActivityCancellationType;
 
@@ -193,12 +246,18 @@ export interface LocalActivityOptions {
   localRetryThreshold?: Duration;
 
   /**
-   * Determines what the SDK does when the Activity is cancelled.
-   * - `TRY_CANCEL` - Initiate a cancellation request and immediately report cancellation to the workflow.
-   * - `WAIT_CANCELLATION_COMPLETED` - Wait for activity cancellation completion. Note that activity must heartbeat to receive a
-   *   cancellation notification. This can block the cancellation for a long time if activity doesn't
-   *   heartbeat or chooses to ignore the cancellation request.
-   * - `ABANDON` - Do not request cancellation of the activity and immediately report cancellation to the workflow.
+   * Determines:
+   * - whether cancellation requests should be propagated from the current Workflow to the Activity; and
+   * - when should the Activity cancellation be reported to Workflow (i.e. at which moment should the
+   *   Activity call's promise fail with an `ActivityFailure`, with `cause` set to a `CancelledFailure`).
+   *
+   * Note that this setting only applies to cancellation originating from cancellation being
+   * externally requested on the Workflow itself, or from internal cancellation of the
+   * `CancellationScope` in which the Activity call was made. Termination of a Workflow Execution
+   * always results in cancellation of its outstanding Activity executions, regardless of those
+   * Activities' {@link ActivityCancellationType} settings.
+   *
+   * @default ActivityCancellationType.WAIT_CANCELLATION_COMPLETED
    */
   cancellationType?: ActivityCancellationType;
 

packages/common/src/converter/failure-converter.ts

@@ -30,7 +30,6 @@ const NexusHandlerErrorRetryBehavior = {
   RETRYABLE: 'RETRYABLE',
   NON_RETRYABLE: 'NON_RETRYABLE',
 } as const;
-
 type NexusHandlerErrorRetryBehavior =
   (typeof NexusHandlerErrorRetryBehavior)[keyof typeof NexusHandlerErrorRetryBehavior];
 

packages/common/src/failure.ts

@@ -112,7 +112,6 @@ export const [encodeRetryState, decodeRetryState] = makeProtoEnumConverters<
 export const ApplicationFailureCategory = {
   BENIGN: 'BENIGN',
 } as const;
-
 export type ApplicationFailureCategory = (typeof ApplicationFailureCategory)[keyof typeof ApplicationFailureCategory];
 
 export const [encodeApplicationFailureCategory, decodeApplicationFailureCategory] = makeProtoEnumConverters<

packages/common/src/internal-workflow/enums-helpers.ts

@@ -10,12 +10,12 @@ import { Exact, RemovePrefix, UnionToIntersection } from '../type-helpers';
  * Newly introduced enums should follow the following pattern:
  *
  * ```ts
- *     type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
  *     const ParentClosePolicy = {
  *       TERMINATE: 'TERMINATE',
  *       ABANDON: 'ABANDON',
  *       REQUEST_CANCEL: 'REQUEST_CANCEL',
  *     } as const;
+ *     type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
  *
  *     const [encodeParentClosePolicy, decodeParentClosePolicy] = //
  *       makeProtoEnumConverters<

packages/common/src/search-attributes.ts

@@ -17,7 +17,6 @@ export const SearchAttributeType = {
   DATETIME: 'DATETIME',
   KEYWORD_LIST: 'KEYWORD_LIST',
 } as const;
-
 export type SearchAttributeType = (typeof SearchAttributeType)[keyof typeof SearchAttributeType];
 
 // Note: encodeSearchAttributeIndexedValueType exported for use in tests to register search attributes

packages/common/src/workflow-options.ts

@@ -93,7 +93,6 @@ export const [encodeWorkflowIdReusePolicy, decodeWorkflowIdReusePolicy] = makePr
  *
  * *Note: It is never possible to have two _actively running_ Workflows with the same ID.*
  */
-export type WorkflowIdConflictPolicy = (typeof WorkflowIdConflictPolicy)[keyof typeof WorkflowIdConflictPolicy];
 export const WorkflowIdConflictPolicy = {
   /**
    * Do not start a new Workflow. Instead raise a `WorkflowExecutionAlreadyStartedError`.
@@ -110,6 +109,7 @@ export const WorkflowIdConflictPolicy = {
    */
   TERMINATE_EXISTING: 'TERMINATE_EXISTING',
 } as const;
+export type WorkflowIdConflictPolicy = (typeof WorkflowIdConflictPolicy)[keyof typeof WorkflowIdConflictPolicy];
 
 export const [encodeWorkflowIdConflictPolicy, decodeWorkflowIdConflictPolicy] = makeProtoEnumConverters<
   temporal.api.enums.v1.WorkflowIdConflictPolicy,
@@ -133,7 +133,7 @@ export interface BaseWorkflowOptions {
    *
    * *Note: It is not possible to have two actively running Workflows with the same ID.*
    *
-   * @default {@link WorkflowIdReusePolicy.WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE}
+   * @default WorkflowIdReusePolicy.WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE
    */
   workflowIdReusePolicy?: WorkflowIdReusePolicy;
 
@@ -142,7 +142,7 @@ export interface BaseWorkflowOptions {
    *
    * *Note: It is not possible to have two actively running Workflows with the same ID.*
    *
-   * @default {@link WorkflowIdConflictPolicy.WORKFLOW_ID_CONFLICT_POLICY_UNSPECIFIED}
+   * @default WorkflowIdConflictPolicy.WORKFLOW_ID_CONFLICT_POLICY_UNSPECIFIED
    */
   workflowIdConflictPolicy?: WorkflowIdConflictPolicy;
 

packages/nexus/src/token.ts

@@ -1,4 +1,7 @@
 /**
+ * OperationTokenType is used to identify the type of Operation token.
+ * Currently, we only have one type of Operation token: WorkflowRun.
+ *
  * @internal
  * @hidden
  */
@@ -24,11 +27,6 @@ export interface WorkflowRunOperationToken {
    */
   wid: string;
 }
-
-/**
- * OperationTokenType is used to identify the type of Operation token.
- * Currently, we only have one type of Operation token: WorkflowRun.
- */
 type OperationTokenType = (typeof OperationTokenType)[keyof typeof OperationTokenType];
 
 /**

packages/test/src/test-enums-helpers.ts

@@ -4,13 +4,13 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
 
 // ASSERTION: There MUST be a corresponding `KEY: 'KEY'` in the const object of strings enum (must be present)
 {
-  type ParentClosePolicyMissingEntry =
-    (typeof ParentClosePolicyMissingEntry)[keyof typeof ParentClosePolicyMissingEntry];
   const ParentClosePolicyMissingEntry = {
     TERMINATE: 'TERMINATE',
     // ABANDON: 'ABANDON',  // Missing entry!
     REQUEST_CANCEL: 'REQUEST_CANCEL',
   } as const;
+  type ParentClosePolicyMissingEntry =
+    (typeof ParentClosePolicyMissingEntry)[keyof typeof ParentClosePolicyMissingEntry];
 
   makeProtoEnumConverters<
     coresdk.child_workflow.ParentClosePolicy,
@@ -30,13 +30,13 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
 
 // ASSERTION: There MUST be a corresponding `KEY: 'KEY'` in the const object of strings enum (must have correct value)
 {
-  type ParentClosePolicyIncorectEntry =
-    (typeof ParentClosePolicyIncorectEntry)[keyof typeof ParentClosePolicyIncorectEntry];
   const ParentClosePolicyIncorectEntry = {
     TERMINATE: 'TERMINATE',
     ABANDON: 'INCORRECT', // Incorrect entry!
     REQUEST_CANCEL: 'REQUEST_CANCEL',
   } as const;
+  type ParentClosePolicyIncorectEntry =
+    (typeof ParentClosePolicyIncorectEntry)[keyof typeof ParentClosePolicyIncorectEntry];
 
   makeProtoEnumConverters<
     coresdk.child_workflow.ParentClosePolicy,
@@ -57,8 +57,6 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
 
 // ASSERTION: There MAY be a corresponding `PREFIX_KEY: 'KEY'` in the const object of strings enum (may be present)
 {
-  type ParentClosePolicyWithPrefixedEntries =
-    (typeof ParentClosePolicyWithPrefixedEntries)[keyof typeof ParentClosePolicyWithPrefixedEntries];
   const ParentClosePolicyWithPrefixedEntries = {
     TERMINATE: 'TERMINATE',
     ABANDON: 'ABANDON',
@@ -68,6 +66,8 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
     PARENT_CLOSE_POLICY_ABANDON: 'ABANDON',
     PARENT_CLOSE_POLICY_REQUEST_CANCEL: 'REQUEST_CANCEL',
   } as const;
+  type ParentClosePolicyWithPrefixedEntries =
+    (typeof ParentClosePolicyWithPrefixedEntries)[keyof typeof ParentClosePolicyWithPrefixedEntries];
 
   makeProtoEnumConverters<
     coresdk.child_workflow.ParentClosePolicy,
@@ -88,13 +88,13 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
 
 // ASSERTION: There MAY be a corresponding `PREFIX_KEY: 'KEY'` in the const object of strings enum (may not be present)
 {
-  type ParentClosePolicyWithoutPrefixedEntries =
-    (typeof ParentClosePolicyWithoutPrefixedEntries)[keyof typeof ParentClosePolicyWithoutPrefixedEntries];
   const ParentClosePolicyWithoutPrefixedEntries = {
     TERMINATE: 'TERMINATE',
     ABANDON: 'ABANDON',
     REQUEST_CANCEL: 'REQUEST_CANCEL',
   } as const;
+  type ParentClosePolicyWithoutPrefixedEntries =
+    (typeof ParentClosePolicyWithoutPrefixedEntries)[keyof typeof ParentClosePolicyWithoutPrefixedEntries];
 
   makeProtoEnumConverters<
     coresdk.child_workflow.ParentClosePolicy,
@@ -115,8 +115,6 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
 
 // ASSERTION: There MAY be a corresponding `PREFIX_KEY: 'KEY'` in the const object of strings enum (if present, must have correct value)
 {
-  type ParentClosePolicyWithPrefixedEntries =
-    (typeof ParentClosePolicyWithPrefixedEntries)[keyof typeof ParentClosePolicyWithPrefixedEntries];
   const ParentClosePolicyWithPrefixedEntries = {
     TERMINATE: 'TERMINATE',
     ABANDON: 'ABANDON',
@@ -126,6 +124,8 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
     PARENT_CLOSE_POLICY_ABANDON: 'ABANDON',
     PARENT_CLOSE_POLICY_REQUEST_CANCEL: 'INCORRECT', // Incorrect entry!
   } as const;
+  type ParentClosePolicyWithPrefixedEntries =
+    (typeof ParentClosePolicyWithPrefixedEntries)[keyof typeof ParentClosePolicyWithPrefixedEntries];
 
   makeProtoEnumConverters<
     coresdk.child_workflow.ParentClosePolicy,
@@ -146,7 +146,6 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
 }
 
 {
-  type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
   const ParentClosePolicy = {
     TERMINATE: 'TERMINATE',
     ABANDON: 'ABANDON',
@@ -157,6 +156,7 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
     PARENT_CLOSE_POLICY_ABANDON: 'ABANDON',
     PARENT_CLOSE_POLICY_REQUEST_CANCEL: 'REQUEST_CANCEL',
   } as const;
+  type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
 
   // ASSERTION: There MUST be a corresponding `KEY: number` in the mapping table (must be there)
   makeProtoEnumConverters<
@@ -300,13 +300,13 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
 
 // ASSERTION: The const object of strings enum MUST NOT contain any other keys than the ones mandated or optionally allowed above.
 {
-  type ParentClosePolicyWithExtra = (typeof ParentClosePolicyWithExtra)[keyof typeof ParentClosePolicyWithExtra];
   const ParentClosePolicyWithExtra = {
     TERMINATE: 'TERMINATE',
     ABANDON: 'ABANDON',
     REQUEST_CANCEL: 'REQUEST_CANCEL',
     EXTRA: 'EXTRA', // Extra entry!
   } as const;
+  type ParentClosePolicyWithExtra = (typeof ParentClosePolicyWithExtra)[keyof typeof ParentClosePolicyWithExtra];
 
   makeProtoEnumConverters<
     coresdk.child_workflow.ParentClosePolicy,
@@ -327,7 +327,6 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
 }
 
 {
-  type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
   const ParentClosePolicy = {
     TERMINATE: 'TERMINATE',
     ABANDON: 'ABANDON',
@@ -338,6 +337,7 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
     PARENT_CLOSE_POLICY_ABANDON: 'ABANDON',
     PARENT_CLOSE_POLICY_REQUEST_CANCEL: 'REQUEST_CANCEL',
   } as const;
+  type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
 
   // ASSERTION: The mapping table MUST NOT contain any other keys than the ones mandated above
   makeProtoEnumConverters<
@@ -416,7 +416,6 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
 
 // Functionnal tests
 {
-  type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
   const ParentClosePolicy = {
     TERMINATE: 'TERMINATE',
     ABANDON: 'ABANDON',
@@ -427,6 +426,7 @@ import { makeProtoEnumConverters as makeProtoEnumConverters } from '@temporalio/
     PARENT_CLOSE_POLICY_ABANDON: 'ABANDON',
     PARENT_CLOSE_POLICY_REQUEST_CANCEL: 'REQUEST_CANCEL',
   } as const;
+  type ParentClosePolicy = (typeof ParentClosePolicy)[keyof typeof ParentClosePolicy];
 
   const [encodeParentClosePolicy, decodeParentClosePolicy] = //
     makeProtoEnumConverters<