feat: Normalize construction of user facing enums (#1534)

Author: mjameswh

packages/client/src/client.ts

@@ -1,10 +1,9 @@
 import { filterNullAndUndefined } from '@temporalio/common/lib/internal-non-workflow';
-import { temporal } from '@temporalio/proto';
 import { AsyncCompletionClient } from './async-completion-client';
 import { BaseClient, BaseClientOptions, defaultBaseClientOptions, LoadedWithDefaults } from './base-client';
 import { ClientInterceptors } from './interceptors';
 import { ScheduleClient } from './schedule-client';
-import { WorkflowService } from './types';
+import { QueryRejectCondition, WorkflowService } from './types';
 import { WorkflowClient } from './workflow-client';
 import { TaskQueueClient } from './task-queue-client';
 
@@ -20,9 +19,9 @@ export interface ClientOptions extends BaseClientOptions {
     /**
      * Should a query be rejected by closed and failed workflows
      *
-     * @default QUERY_REJECT_CONDITION_UNSPECIFIED which means that closed and failed workflows are still queryable
+     * @default `undefined`, which means that closed and failed workflows are still queryable
      */
-    queryRejectCondition?: temporal.api.enums.v1.QueryRejectCondition;
+    queryRejectCondition?: QueryRejectCondition;
   };
 }
 
@@ -63,6 +62,7 @@ export class Client extends BaseClient {
       connection: this.connection,
       dataConverter: this.dataConverter,
       interceptors: interceptors?.workflow,
+      queryRejectCondition: workflow?.queryRejectCondition,
     });
 
     this.activity = new AsyncCompletionClient({

packages/client/src/schedule-client.ts

@@ -29,17 +29,17 @@ import {
   ScheduleUpdateOptions,
   ScheduleOptionsAction,
   ScheduleOptionsStartWorkflowAction,
+  encodeScheduleOverlapPolicy,
+  decodeScheduleOverlapPolicy,
 } from './schedule-types';
 import {
   compileScheduleOptions,
   compileUpdatedScheduleOptions,
-  decodeOverlapPolicy,
   decodeScheduleAction,
   decodeScheduleRecentActions,
   decodeScheduleRunningActions,
   decodeScheduleSpec,
   decodeSearchAttributes,
-  encodeOverlapPolicy,
   encodeScheduleAction,
   encodeSchedulePolicies,
   encodeScheduleSpec,
@@ -251,7 +251,7 @@ export class ScheduleClient extends BaseClient {
           ? opts.state.backfill.map((x) => ({
               startTime: optionalDateToTs(x.start),
               endTime: optionalDateToTs(x.end),
-              overlapPolicy: x.overlap ? encodeOverlapPolicy(x.overlap) : undefined,
+              overlapPolicy: x.overlap ? encodeScheduleOverlapPolicy(x.overlap) : undefined,
             }))
           : undefined,
       },
@@ -427,7 +427,8 @@ export class ScheduleClient extends BaseClient {
           memo: await decodeMapFromPayloads(this.client.dataConverter, raw.memo?.fields),
           searchAttributes: decodeSearchAttributes(raw.searchAttributes),
           policies: {
-            overlap: decodeOverlapPolicy(raw.schedule.policies?.overlapPolicy),
+            // 'overlap' should never be missing on describe, as the server will replace UNSPECIFIED by an actual value
+            overlap: decodeScheduleOverlapPolicy(raw.schedule.policies?.overlapPolicy) ?? ScheduleOverlapPolicy.SKIP,
             catchupWindow: optionalTsToMs(raw.schedule.policies?.catchupWindow) ?? 60_000,
             pauseOnFailure: raw.schedule.policies?.pauseOnFailure === true,
           },
@@ -485,7 +486,7 @@ export class ScheduleClient extends BaseClient {
         await this.client._patchSchedule(this.scheduleId, {
           triggerImmediately: {
             overlapPolicy: overlap
-              ? encodeOverlapPolicy(overlap)
+              ? encodeScheduleOverlapPolicy(overlap)
               : temporal.api.enums.v1.ScheduleOverlapPolicy.SCHEDULE_OVERLAP_POLICY_ALLOW_ALL,
           },
         });
@@ -497,7 +498,7 @@ export class ScheduleClient extends BaseClient {
           backfillRequest: backfills.map((x) => ({
             startTime: optionalDateToTs(x.start),
             endTime: optionalDateToTs(x.end),
-            overlapPolicy: x.overlap ? encodeOverlapPolicy(x.overlap) : undefined,
+            overlapPolicy: x.overlap ? encodeScheduleOverlapPolicy(x.overlap) : undefined,
           })),
         });
       },

packages/client/src/schedule-helpers.ts

@@ -32,7 +32,6 @@ import {
   CompiledScheduleUpdateOptions,
   Range,
   ScheduleOptions,
-  ScheduleOverlapPolicy,
   ScheduleUpdateOptions,
   DayOfWeek,
   DAYS_OF_WEEK,
@@ -47,6 +46,7 @@ import {
   ScheduleExecutionActionResult,
   ScheduleExecutionResult,
   ScheduleExecutionStartWorkflowActionResult,
+  encodeScheduleOverlapPolicy,
 } from './schedule-types';
 
 const [encodeSecond, decodeSecond] = makeCalendarSpecFieldCoders(
@@ -192,21 +192,6 @@ export function decodeOptionalStructuredCalendarSpecs(
   );
 }
 
-export function encodeOverlapPolicy(input: ScheduleOverlapPolicy): temporal.api.enums.v1.ScheduleOverlapPolicy {
-  return temporal.api.enums.v1.ScheduleOverlapPolicy[
-    `SCHEDULE_OVERLAP_POLICY_${ScheduleOverlapPolicy[input] as keyof typeof ScheduleOverlapPolicy}`
-  ];
-}
-
-export function decodeOverlapPolicy(input?: temporal.api.enums.v1.ScheduleOverlapPolicy | null): ScheduleOverlapPolicy {
-  if (!input) return ScheduleOverlapPolicy.UNSPECIFIED;
-  const encodedPolicyName = temporal.api.enums.v1.ScheduleOverlapPolicy[input];
-  const decodedPolicyName = encodedPolicyName.substring(
-    'SCHEDULE_OVERLAP_POLICY_'.length
-  ) as keyof typeof ScheduleOverlapPolicy;
-  return ScheduleOverlapPolicy[decodedPolicyName];
-}
-
 export function compileScheduleOptions(options: ScheduleOptions): CompiledScheduleOptions {
   const workflowTypeOrFunc = options.action.workflowType;
   const workflowType = extractWorkflowType(workflowTypeOrFunc);
@@ -290,7 +275,7 @@ export function encodeSchedulePolicies(
 ): temporal.api.schedule.v1.ISchedulePolicies {
   return {
     catchupWindow: msOptionalToTs(policies?.catchupWindow),
-    overlapPolicy: policies?.overlap ? encodeOverlapPolicy(policies.overlap) : undefined,
+    overlapPolicy: policies?.overlap ? encodeScheduleOverlapPolicy(policies.overlap) : undefined,
     pauseOnFailure: policies?.pauseOnFailure,
   };
 }

packages/client/src/schedule-types.ts

@@ -1,5 +1,6 @@
 import { checkExtends, Replace } from '@temporalio/common/lib/type-helpers';
 import { Duration, SearchAttributes, Workflow } from '@temporalio/common';
+import { makeProtoEnumConverters } from '@temporalio/common/lib/internal-workflow';
 import type { temporal } from '@temporalio/proto';
 import { WorkflowStartOptions } from './workflow-options';
 
@@ -795,57 +796,69 @@ export type CompiledScheduleAction = Replace<
 /**
  * Policy for overlapping Actions.
  */
-export enum ScheduleOverlapPolicy {
-  /**
-   * Use server default (currently SKIP).
-   *
-   * FIXME: remove this field if this issue is implemented: https://github.com/temporalio/temporal/issues/3240
-   */
-  UNSPECIFIED = 0,
-
+export const ScheduleOverlapPolicy = {
   /**
    * Don't start a new Action.
+   * @default
    */
-  SKIP,
+  SKIP: 'SKIP',
 
   /**
    * Start another Action as soon as the current Action completes, but only buffer one Action in this way. If another
    * Action is supposed to start, but one Action is running and one is already buffered, then only the buffered one will
    * be started after the running Action finishes.
    */
-  BUFFER_ONE,
+  BUFFER_ONE: 'BUFFER_ONE',
 
   /**
    * Allows an unlimited number of Actions to buffer. They are started sequentially.
    */
-  BUFFER_ALL,
+  BUFFER_ALL: 'BUFFER_ALL',
 
   /**
    * Cancels the running Action, and then starts the new Action once the cancelled one completes.
    */
-  CANCEL_OTHER,
+  CANCEL_OTHER: 'CANCEL_OTHER',
 
   /**
    * Terminate the running Action and start the new Action immediately.
    */
-  TERMINATE_OTHER,
+  TERMINATE_OTHER: 'TERMINATE_OTHER',
 
   /**
    * Allow any number of Actions to start immediately.
    *
    * This is the only policy under which multiple Actions can run concurrently.
    */
-  ALLOW_ALL,
-}
+  ALLOW_ALL: 'ALLOW_ALL',
 
-checkExtends<
+  /**
+   * Use server default (currently SKIP).
+   *
+   * @deprecated Either leave property `undefined`, or use {@link SKIP} instead.
+   */
+  UNSPECIFIED: undefined, // eslint-disable-line deprecation/deprecation
+} as const;
+export type ScheduleOverlapPolicy = (typeof ScheduleOverlapPolicy)[keyof typeof ScheduleOverlapPolicy];
+
+export const [encodeScheduleOverlapPolicy, decodeScheduleOverlapPolicy] = makeProtoEnumConverters<
+  temporal.api.enums.v1.ScheduleOverlapPolicy,
+  typeof temporal.api.enums.v1.ScheduleOverlapPolicy,
   keyof typeof temporal.api.enums.v1.ScheduleOverlapPolicy,
-  `SCHEDULE_OVERLAP_POLICY_${keyof typeof ScheduleOverlapPolicy}`
->();
-checkExtends<
-  `SCHEDULE_OVERLAP_POLICY_${keyof typeof ScheduleOverlapPolicy}`,
-  keyof typeof temporal.api.enums.v1.ScheduleOverlapPolicy
->();
+  typeof ScheduleOverlapPolicy,
+  'SCHEDULE_OVERLAP_POLICY_'
+>(
+  {
+    [ScheduleOverlapPolicy.SKIP]: 1,
+    [ScheduleOverlapPolicy.BUFFER_ONE]: 2,
+    [ScheduleOverlapPolicy.BUFFER_ALL]: 3,
+    [ScheduleOverlapPolicy.CANCEL_OTHER]: 4,
+    [ScheduleOverlapPolicy.TERMINATE_OTHER]: 5,
+    [ScheduleOverlapPolicy.ALLOW_ALL]: 6,
+    UNSPECIFIED: 0,
+  } as const,
+  'SCHEDULE_OVERLAP_POLICY_'
+);
 
 export interface Backfill {
   /**

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

@@ -1,6 +1,7 @@
 import { status } from '@grpc/grpc-js';
 import { filterNullAndUndefined } from '@temporalio/common/lib/internal-non-workflow';
 import { assertNever, SymbolBasedInstanceOfError, RequireAtLeastOne } from '@temporalio/common/lib/type-helpers';
+import { makeProtoEnumConverters } from '@temporalio/common/lib/internal-workflow';
 import { temporal } from '@temporalio/proto';
 import { BaseClient, BaseClientOptions, defaultBaseClientOptions, LoadedWithDefaults } from './base-client';
 import { WorkflowService } from './types';
@@ -148,7 +149,7 @@ export class TaskQueueClient extends BaseClient {
         namespace: this.options.namespace,
         taskQueues: options.taskQueues,
         buildIds,
-        reachability: reachabilityTypeToProto(options.reachability),
+        reachability: encodeTaskReachability(options.reachability),
       });
     } catch (e) {
       this.rethrowGrpcError(e, 'Unexpected error fetching Build Id reachability');
@@ -173,14 +174,45 @@ export class TaskQueueClient extends BaseClient {
  */
 export type ReachabilityOptions = RequireAtLeastOne<BaseReachabilityOptions, 'buildIds' | 'taskQueues'>;
 
+export const ReachabilityType = {
+  /** The Build Id might be used by new workflows. */
+  NEW_WORKFLOWS: 'NEW_WORKFLOWS',
+
+  /** The Build Id might be used by open workflows and/or closed workflows. */
+  EXISTING_WORKFLOWS: 'EXISTING_WORKFLOWS',
+
+  /** The Build Id might be used by open workflows. */
+  OPEN_WORKFLOWS: 'OPEN_WORKFLOWS',
+
+  /** 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 = 'NEW_WORKFLOWS' | 'EXISTING_WORKFLOWS' | 'OPEN_WORKFLOWS' | 'CLOSED_WORKFLOWS';
+export type ReachabilityType = (typeof ReachabilityType)[keyof typeof ReachabilityType];
+
+export const [encodeTaskReachability, decodeTaskReachability] = makeProtoEnumConverters<
+  temporal.api.enums.v1.TaskReachability,
+  typeof temporal.api.enums.v1.TaskReachability,
+  keyof typeof temporal.api.enums.v1.TaskReachability,
+  typeof ReachabilityType,
+  'TASK_REACHABILITY_'
+>(
+  {
+    [ReachabilityType.NEW_WORKFLOWS]: 1,
+    [ReachabilityType.EXISTING_WORKFLOWS]: 2,
+    [ReachabilityType.OPEN_WORKFLOWS]: 3,
+    [ReachabilityType.CLOSED_WORKFLOWS]: 4,
+    UNSPECIFIED: 0,
+  } as const,
+  'TASK_REACHABILITY_'
+);
 
 /**
  * See {@link ReachabilityOptions}
@@ -215,24 +247,6 @@ export interface BuildIdReachability {
   taskQueueReachability: Record<string, ReachabilityTypeResponse[]>;
 }
 
-function reachabilityTypeToProto(type: ReachabilityType | undefined | null): temporal.api.enums.v1.TaskReachability {
-  switch (type) {
-    case null:
-    case undefined:
-      return temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_UNSPECIFIED;
-    case 'NEW_WORKFLOWS':
-      return temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_NEW_WORKFLOWS;
-    case 'EXISTING_WORKFLOWS':
-      return temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_EXISTING_WORKFLOWS;
-    case 'OPEN_WORKFLOWS':
-      return temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_OPEN_WORKFLOWS;
-    case 'CLOSED_WORKFLOWS':
-      return temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_CLOSED_WORKFLOWS;
-    default:
-      assertNever('Unknown Build Id reachability operation', type);
-  }
-}
-
 export function reachabilityResponseFromProto(resp: GetWorkerTaskReachabilityResponse): ReachabilityResponse {
   return {
     buildIdReachability: Object.fromEntries(
@@ -247,7 +261,9 @@ export function reachabilityResponseFromProto(resp: GetWorkerTaskReachabilityRes
               taskQueueReachability[tqr.taskQueue] = [];
               continue;
             }
-            taskQueueReachability[tqr.taskQueue] = tqr.reachability.map(reachabilityTypeFromProto);
+            taskQueueReachability[tqr.taskQueue] = tqr.reachability.map(
+              (x) => decodeTaskReachability(x) ?? 'NOT_FETCHED'
+            );
           }
         }
         let bid: string | UnversionedBuildIdType;
@@ -262,23 +278,6 @@ export function reachabilityResponseFromProto(resp: GetWorkerTaskReachabilityRes
   };
 }
 
-function reachabilityTypeFromProto(rtype: temporal.api.enums.v1.TaskReachability): ReachabilityTypeResponse {
-  switch (rtype) {
-    case temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_UNSPECIFIED:
-      return 'NOT_FETCHED';
-    case temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_NEW_WORKFLOWS:
-      return 'NEW_WORKFLOWS';
-    case temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_EXISTING_WORKFLOWS:
-      return 'EXISTING_WORKFLOWS';
-    case temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_OPEN_WORKFLOWS:
-      return 'OPEN_WORKFLOWS';
-    case temporal.api.enums.v1.TaskReachability.TASK_REACHABILITY_CLOSED_WORKFLOWS:
-      return 'CLOSED_WORKFLOWS';
-    default:
-      return assertNever('Unknown Build Id reachability operation', rtype);
-  }
-}
-
 /**
  * Thrown when one or more Build Ids are not found while using the {@link TaskQueueClient}.
  *