@temporalio/common 1.11.2 → 1.11.4

package/src/converter/failure-converter.ts

@@ -3,14 +3,16 @@ import {
   ApplicationFailure,
   CancelledFailure,
   ChildWorkflowFailure,
+  decodeRetryState,
+  decodeTimeoutType,
+  encodeRetryState,
+  encodeTimeoutType,
   FAILURE_SOURCE,
   ProtoFailure,
-  RetryState,
   ServerFailure,
   TemporalFailure,
   TerminatedFailure,
   TimeoutFailure,
-  TimeoutType,
 } from '../failure';
 import { isError } from '../type-helpers';
 import { msOptionalToTs } from '../time';
@@ -139,7 +141,7 @@ export class DefaultFailureConverter implements FailureConverter {
       return new TimeoutFailure(
         failure.message ?? undefined,
         fromPayloadsAtIndex(payloadConverter, 0, failure.timeoutFailureInfo.lastHeartbeatDetails?.payloads),
-        failure.timeoutFailureInfo.timeoutType ?? TimeoutType.TIMEOUT_TYPE_UNSPECIFIED
+        decodeTimeoutType(failure.timeoutFailureInfo.timeoutType)
       );
     }
     if (failure.terminatedFailureInfo) {
@@ -173,7 +175,7 @@ export class DefaultFailureConverter implements FailureConverter {
         namespace ?? undefined,
         workflowExecution,
         workflowType.name,
-        retryState ?? RetryState.RETRY_STATE_UNSPECIFIED,
+        decodeRetryState(retryState),
         this.optionalFailureToOptionalError(failure.cause, payloadConverter)
       );
     }
@@ -185,7 +187,7 @@ export class DefaultFailureConverter implements FailureConverter {
         failure.message ?? undefined,
         failure.activityFailureInfo.activityType.name,
         failure.activityFailureInfo.activityId ?? undefined,
-        failure.activityFailureInfo.retryState ?? RetryState.RETRY_STATE_UNSPECIFIED,
+        decodeRetryState(failure.activityFailureInfo.retryState),
         failure.activityFailureInfo.identity ?? undefined,
         this.optionalFailureToOptionalError(failure.cause, payloadConverter)
       );
@@ -244,6 +246,7 @@ export class DefaultFailureConverter implements FailureConverter {
           ...base,
           activityFailureInfo: {
             ...err,
+            retryState: encodeRetryState(err.retryState),
             activityType: { name: err.activityType },
           },
         };
@@ -253,6 +256,7 @@ export class DefaultFailureConverter implements FailureConverter {
           ...base,
           childWorkflowExecutionFailureInfo: {
             ...err,
+            retryState: encodeRetryState(err.retryState),
             workflowExecution: err.execution,
             workflowType: { name: err.workflowType },
           },
@@ -287,7 +291,7 @@ export class DefaultFailureConverter implements FailureConverter {
         return {
           ...base,
           timeoutFailureInfo: {
-            timeoutType: err.timeoutType,
+            timeoutType: encodeTimeoutType(err.timeoutType),
             lastHeartbeatDetails: err.lastHeartbeatDetails
               ? { payloads: toPayloads(payloadConverter, err.lastHeartbeatDetails) }
               : undefined,

package/src/converter/payload-converter.ts

@@ -232,7 +232,7 @@ export class JsonPayloadConverter implements PayloadConverterWithEncoding {
     let json;
     try {
       json = JSON.stringify(value);
-    } catch (err) {
+    } catch (_err) {
       return undefined;
     }
 

package/src/failure.ts

@@ -1,38 +1,105 @@
 import type { temporal } from '@temporalio/proto';
-import { checkExtends, errorMessage, isRecord, SymbolBasedInstanceOfError } from './type-helpers';
+import { errorMessage, isRecord, SymbolBasedInstanceOfError } from './type-helpers';
 import { Duration } from './time';
+import { makeProtoEnumConverters } from './internal-workflow';
 
 export const FAILURE_SOURCE = 'TypeScriptSDK';
 export type ProtoFailure = temporal.api.failure.v1.IFailure;
 
-// Avoid importing the proto implementation to reduce workflow bundle size
-// Copied from temporal.api.enums.v1.TimeoutType
-export enum TimeoutType {
-  TIMEOUT_TYPE_UNSPECIFIED = 0,
-  TIMEOUT_TYPE_START_TO_CLOSE = 1,
-  TIMEOUT_TYPE_SCHEDULE_TO_START = 2,
-  TIMEOUT_TYPE_SCHEDULE_TO_CLOSE = 3,
-  TIMEOUT_TYPE_HEARTBEAT = 4,
-}
+export const TimeoutType = {
+  START_TO_CLOSE: 'START_TO_CLOSE',
+  SCHEDULE_TO_START: 'SCHEDULE_TO_START',
+  SCHEDULE_TO_CLOSE: 'SCHEDULE_TO_CLOSE',
+  HEARTBEAT: 'HEARTBEAT',
 
-checkExtends<temporal.api.enums.v1.TimeoutType, TimeoutType>();
-checkExtends<TimeoutType, temporal.api.enums.v1.TimeoutType>();
-
-// Avoid importing the proto implementation to reduce workflow bundle size
-// Copied from temporal.api.enums.v1.RetryState
-export enum RetryState {
-  RETRY_STATE_UNSPECIFIED = 0,
-  RETRY_STATE_IN_PROGRESS = 1,
-  RETRY_STATE_NON_RETRYABLE_FAILURE = 2,
-  RETRY_STATE_TIMEOUT = 3,
-  RETRY_STATE_MAXIMUM_ATTEMPTS_REACHED = 4,
-  RETRY_STATE_RETRY_POLICY_NOT_SET = 5,
-  RETRY_STATE_INTERNAL_SERVER_ERROR = 6,
-  RETRY_STATE_CANCEL_REQUESTED = 7,
-}
+  /** @deprecated Use {@link START_TO_CLOSE} instead. */
+  TIMEOUT_TYPE_START_TO_CLOSE: 'START_TO_CLOSE', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use {@link SCHEDULE_TO_START} instead. */
+  TIMEOUT_TYPE_SCHEDULE_TO_START: 'SCHEDULE_TO_START', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use {@link SCHEDULE_TO_CLOSE} instead. */
+  TIMEOUT_TYPE_SCHEDULE_TO_CLOSE: 'SCHEDULE_TO_CLOSE', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use {@link HEARTBEAT} instead. */
+  TIMEOUT_TYPE_HEARTBEAT: 'HEARTBEAT', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use `undefined` instead. */
+  TIMEOUT_TYPE_UNSPECIFIED: undefined, // eslint-disable-line deprecation/deprecation
+} as const;
+export type TimeoutType = (typeof TimeoutType)[keyof typeof TimeoutType];
+
+export const [encodeTimeoutType, decodeTimeoutType] = makeProtoEnumConverters<
+  temporal.api.enums.v1.TimeoutType,
+  typeof temporal.api.enums.v1.TimeoutType,
+  keyof typeof temporal.api.enums.v1.TimeoutType,
+  typeof TimeoutType,
+  'TIMEOUT_TYPE_'
+>(
+  {
+    [TimeoutType.START_TO_CLOSE]: 1,
+    [TimeoutType.SCHEDULE_TO_START]: 2,
+    [TimeoutType.SCHEDULE_TO_CLOSE]: 3,
+    [TimeoutType.HEARTBEAT]: 4,
+    UNSPECIFIED: 0,
+  } as const,
+  'TIMEOUT_TYPE_'
+);
+
+export const RetryState = {
+  IN_PROGRESS: 'IN_PROGRESS',
+  NON_RETRYABLE_FAILURE: 'NON_RETRYABLE_FAILURE',
+  TIMEOUT: 'TIMEOUT',
+  MAXIMUM_ATTEMPTS_REACHED: 'MAXIMUM_ATTEMPTS_REACHED',
+  RETRY_POLICY_NOT_SET: 'RETRY_POLICY_NOT_SET',
+  INTERNAL_SERVER_ERROR: 'INTERNAL_SERVER_ERROR',
+  CANCEL_REQUESTED: 'CANCEL_REQUESTED',
+
+  /** @deprecated Use {@link IN_PROGRESS} instead. */
+  RETRY_STATE_IN_PROGRESS: 'IN_PROGRESS', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use {@link NON_RETRYABLE_FAILURE} instead. */
+  RETRY_STATE_NON_RETRYABLE_FAILURE: 'NON_RETRYABLE_FAILURE', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use {@link TIMEOUT} instead. */
+  RETRY_STATE_TIMEOUT: 'TIMEOUT', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use {@link MAXIMUM_ATTEMPTS_REACHED} instead. */
+  RETRY_STATE_MAXIMUM_ATTEMPTS_REACHED: 'MAXIMUM_ATTEMPTS_REACHED', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use {@link RETRY_POLICY_NOT_SET} instead. */
+  RETRY_STATE_RETRY_POLICY_NOT_SET: 'RETRY_POLICY_NOT_SET', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use {@link INTERNAL_SERVER_ERROR} instead. */
+  RETRY_STATE_INTERNAL_SERVER_ERROR: 'INTERNAL_SERVER_ERROR', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use {@link CANCEL_REQUESTED} instead. */
+  RETRY_STATE_CANCEL_REQUESTED: 'CANCEL_REQUESTED', // eslint-disable-line deprecation/deprecation
+
+  /** @deprecated Use `undefined` instead. */
+  RETRY_STATE_UNSPECIFIED: undefined, // eslint-disable-line deprecation/deprecation
+} as const;
+export type RetryState = (typeof RetryState)[keyof typeof RetryState];
 
-checkExtends<temporal.api.enums.v1.RetryState, RetryState>();
-checkExtends<RetryState, temporal.api.enums.v1.RetryState>();
+export const [encodeRetryState, decodeRetryState] = makeProtoEnumConverters<
+  temporal.api.enums.v1.RetryState,
+  typeof temporal.api.enums.v1.RetryState,
+  keyof typeof temporal.api.enums.v1.RetryState,
+  typeof RetryState,
+  'RETRY_STATE_'
+>(
+  {
+    [RetryState.IN_PROGRESS]: 1,
+    [RetryState.NON_RETRYABLE_FAILURE]: 2,
+    [RetryState.TIMEOUT]: 3,
+    [RetryState.MAXIMUM_ATTEMPTS_REACHED]: 4,
+    [RetryState.RETRY_POLICY_NOT_SET]: 5,
+    [RetryState.INTERNAL_SERVER_ERROR]: 6,
+    [RetryState.CANCEL_REQUESTED]: 7,
+    UNSPECIFIED: 0,
+  } as const,
+  'RETRY_STATE_'
+);
 
 export type WorkflowExecution = temporal.api.common.v1.IWorkflowExecution;
 
@@ -279,7 +346,7 @@ export class ChildWorkflowFailure extends TemporalFailure {
 
 /**
  * This exception is thrown in the following cases:
- *  - Workflow with the same Workflow Id is currently running
+ *  - Workflow with the same Workflow ID is currently running and the {@link WorkflowOptions.workflowIdConflictPolicy} is `WORKFLOW_ID_CONFLICT_POLICY_FAIL`
  *  - There is a closed Workflow with the same Workflow Id and the {@link WorkflowOptions.workflowIdReusePolicy}
  *    is `WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE`
  *  - There is closed Workflow in the `Completed` state with the same Workflow Id and the {@link WorkflowOptions.workflowIdReusePolicy}

package/src/interfaces.ts

@@ -128,11 +128,11 @@ export interface HistoryAndWorkflowId {
  * Policy defining actions taken when a workflow exits while update or signal handlers are running.
  * The workflow exit may be due to successful return, failure, cancellation, or continue-as-new.
  */
-export enum HandlerUnfinishedPolicy {
+export const HandlerUnfinishedPolicy = {
   /**
    * Issue a warning in addition to abandoning the handler execution. The warning will not be issued if the workflow fails.
    */
-  WARN_AND_ABANDON = 1,
+  WARN_AND_ABANDON: 'WARN_AND_ABANDON',
 
   /**
    * Abandon the handler execution.
@@ -140,5 +140,6 @@ export enum HandlerUnfinishedPolicy {
    * In the case of an update handler this means that the client will receive an error rather than
    * the update result.
    */
-  ABANDON = 2,
-}
+  ABANDON: 'ABANDON',
+} as const;
+export type HandlerUnfinishedPolicy = (typeof HandlerUnfinishedPolicy)[keyof typeof HandlerUnfinishedPolicy];

package/src/internal-non-workflow/data-converter-helpers.ts

@@ -37,7 +37,7 @@ function requireConverter<T>(
 ): T {
   let module;
   try {
-    module = require(path); // eslint-disable-line @typescript-eslint/no-var-requires
+    module = require(path); // eslint-disable-line @typescript-eslint/no-require-imports
   } catch (error) {
     if (errorCode(error) === 'MODULE_NOT_FOUND') {
       throw new ValueError(`Could not find a file at the specified ${type}Path: '${path}'.`);

package/src/internal-non-workflow/parse-host-uri.ts

@@ -80,23 +80,24 @@ export function joinProtoHostPort(components: ProtoHostPort): string {
  * Parse the address for the gRPC endpoint of a Temporal server.
  *
  * - The URI may only contain a hostname and a port.
- * - Port is optional; it defaults to 7233.
+ * - Port is optional; if not specified, set it to `defaultPort`.
  *
- * Examples of valid URIs:
+ * Examples of valid URIs (assuming `defaultPort` is 7233):
  *
  * ```
- * 127.0.0.1:7233 => { host: '192.168.0.1', port: 7233 }
+ * 127.0.0.1 => { host: '127.0.0.1', port: 7233 }
+ * 192.168.0.1:7233 => { host: '192.168.0.1', port: 7233 }
  * my.temporal.service.com:7233 => { host: 'my.temporal.service.com', port: 7233 }
  * [::ffff:192.0.2.128]:8080 => { host: '[::ffff:192.0.2.128]', port: 8080 }
  * ```
  */
-export function normalizeTemporalGrpcEndpointAddress(uri: string): string {
+export function normalizeGrpcEndpointAddress(uri: string, defaultPort: number): string {
   const splitted = splitProtoHostPort(uri);
   if (!splitted || splitted.scheme !== undefined) {
     throw new TypeError(
       `Invalid address for Temporal gRPC endpoint: expected URI of the form 'hostname' or 'hostname:port'; got '${uri}'`
     );
   }
-  splitted.port ??= 7233;
+  splitted.port ??= defaultPort;
   return joinProtoHostPort(splitted);
 }

package/src/internal-non-workflow/tls-config.ts

@@ -27,11 +27,11 @@ export interface TLSConfig {
  * Pass a falsy value to use a non-encrypted connection or `true` or `{}` to
  * connect with TLS without any customization.
  */
-export type TLSConfigOption = TLSConfig | boolean | null;
+export type TLSConfigOption = TLSConfig | boolean | undefined | null;
 
 /**
  * Normalize {@link TLSConfigOption} by turning false and null to undefined and true to and empty object
  */
-export function normalizeTlsConfig(tls?: TLSConfigOption): TLSConfig | undefined {
+export function normalizeTlsConfig(tls: TLSConfigOption): TLSConfig | undefined {
   return typeof tls === 'object' ? (tls === null ? undefined : tls) : tls ? {} : undefined;
 }

package/src/internal-workflow/enums-helpers.ts

@@ -0,0 +1,301 @@
+import { ValueError } from '../errors';
+import { Exact, RemovePrefix, UnionToIntersection } from '../type-helpers';
+
+/**
+ * Create encoding and decoding functions to convert between the numeric `enum` types produced by our
+ * Protobuf compiler and "const object of strings" enum values that we expose in our public APIs.
+ *
+ * ### Usage
+ *
+ * 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;
+ *
+ *     const [encodeParentClosePolicy, decodeParentClosePolicy] = //
+ *       makeProtoEnumConverters<
+ *         coresdk.child_workflow.ParentClosePolicy,
+ *         typeof coresdk.child_workflow.ParentClosePolicy,
+ *         keyof typeof coresdk.child_workflow.ParentClosePolicy,
+ *         typeof ParentClosePolicy,
+ *         'PARENT_CLOSE_POLICY_'  // This may be an empty string if the proto enum doesn't add a repeated prefix on values
+ *       >(
+ *         {
+ *           [ParentClosePolicy.TERMINATE]: 1, // These numbers must match the ones in the proto enum
+ *           [ParentClosePolicy.ABANDON]: 2,
+ *           [ParentClosePolicy.REQUEST_CANCEL]: 3,
+ *
+ *           UNSPECIFIED: 0,
+ *         } as const,
+ *         'PARENT_CLOSE_POLICY_'
+ *       );
+ * ```
+ *
+ * `makeProtoEnumConverters` supports other usage patterns, but they are only meant for
+ * backward compatibility with former enum definitions and should not be used for new enums.
+ *
+ * ### Context
+ *
+ * Temporal's Protobuf APIs define several `enum` types; our Protobuf compiler transforms these to
+ * traditional (i.e. non-const) [TypeScript numeric `enum`s](https://www.typescriptlang.org/docs/handbook/enums.html#numeric-enums).
+ *
+ * For various reasons, this is far from ideal:
+ *
+ *  - Due to the dual nature of non-const TypeScript `enum`s (they are both a type and a value),
+ *    it is not possible to refer to an enum value from code without a "real" import of the enum type
+ *    (i.e. can't simply do `import type ...`). In Workflow code, such an import would result in
+ *    loading our entire Protobuf definitions into the workflow sandbox, adding several megabytes to
+ *    the per-workflow memory footprint, which is unacceptable; to avoid that, we need to maintain
+ *    a mirror copy of each enum types used by in-workflow APIs, and export these from either
+ *    `@temporalio/common` or `@temporalio/workflow`.
+ *  - It is not desirable for users to need an explicit dependency on `@temporalio/proto` just to
+ *    get access to these enum types; we therefore made it a common practice to reexport these enums
+ *    from our public facing packages. However, experience demontrated that these reexports effectively
+ *    resulted in poor and inconsistent documentation coverage compared to mirrored enums types.
+ *  - Our Protobuf enum types tend to follow a verbose and redundant naming convention, which feels
+ *    unatural and excessive according to most TypeScript style guides; e.g. instead of
+ *    `workflowIdReusePolicy: WorkflowIdReusePolicy.WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE`,
+ *    a TypeScript developer would generally expect to be able to write something similar to
+ *    `workflowIdReusePolicy: 'REJECT_DUPLICATE'`.
+ *  - Because of the way Protobuf works, many of our enum types contain an `UNSPECIFIED` value, which
+ *    is used to explicitly identify a value that is unset. In TypeScript code, the `undefined` value
+ *    already serves that purpose, and is definitely more idiomatic to TS developers, whereas these
+ *    `UNSPECIFIED` values create noise and confusion in our APIs.
+ *  - TypeScript editors generally do a very bad job at providing autocompletion that implies reaching
+ *    for values of a TypeScript enum type, forcing developers to explicitly type in at least part
+ *    of the name of the enum type before they can get autocompletion for its values. On the other
+ *    hand, all TS editors immediately provide autocompletion for string union types.
+ *  - The [TypeScript's official documentation](https://www.typescriptlang.org/docs/handbook/enums.html#objects-vs-enums)
+ *    itself suggests that, in modern TypeScript, the use of `as const` objects may generally suffice
+ *    and may be advantageous over the use of `enum` types.
+ *
+ * A const object of strings, combined with a union type of possible string values, provides a much
+ * more idiomatic syntax and a better DX for TypeScript developers. This however requires a way to
+ * convert back and forth between the `enum` values produced by the Protobuf compiler and the
+ * equivalent string values.
+ *
+ * This helper dynamically creates these conversion functions for a given Protobuf enum type,
+ * strongly building upon specific conventions that we have adopted in our Protobuf definitions.
+ *
+ * ### Validations
+ *
+ * The complex type signature of this helper is there to prevent most potential incoherencies
+ * that could result from having to manually synchronize the const object of strings enum and the
+ * conversion table with the proto enum, while not requiring a regular import on the Protobuf enum
+ * itself (so it can be used safely for enums meant to be used from workflow code).
+ *
+ * In particular, failing any of the following invariants will result in build time errors:
+ *
+ * - For every key of the form `PREFIX_KEY: number` in the proto enum, excluding the `UNSPECIFIED` key:
+ *   - There MUST be a corresponding `KEY: 'KEY'` entry in the const object of strings enum;
+ *   - There MAY be a corresponding `PREFIX_KEY: 'KEY'` in the const object of strings enum
+ *     (this is meant to preserve backward compatibility with the former syntax; such aliases should
+ *     not be added for new enums and enum entries introduced going forward);
+ *   - There MUST be a corresponding `KEY: number` in the mapping table.
+ * - If the proto enum contains a `PREFIX_UNSPECIFIED` entry, then:
+ *   - There MAY be a corresponding `PREFIX_UNSPECIFIED: undefined` and/or `UNSPECIFIED: undefined`
+ *     entries in the const object of strings enum — this is meant to preserve backward compatibility
+ *     with the former syntax; this alias should not be added for new enums introduced going forward;
+ *   - There MUST be an `UNSPECIFIED: 0` in the mapping table.
+ * - The const object of strings enum MUST NOT contain any other keys than the ones mandated or
+ *   optionally allowed be the preceeding rules.
+ * - The mapping table MUST NOT contain any other keys than the ones mandated above.
+ *
+ * These rules notably ensure that whenever a new value is added to an existing Proto enum, the code
+ * will fail to compile until the corresponding entry is added on the const object of strings enum
+ * and the mapping table.
+ *
+ * @internal
+ */
+export function makeProtoEnumConverters<
+  ProtoEnumValue extends number,
+  ProtoEnum extends { [k in ProtoEnumKey]: ProtoEnumValue },
+  ProtoEnumKey extends `${Prefix}${string}`,
+  StringEnumTypeActual extends Exact<StringEnumType, StringEnumTypeActual>,
+  Prefix extends string,
+  //
+  // Parameters after this point will be inferred; they're not meant not to be specified by developers
+  Unspecified = ProtoEnumKey extends `${Prefix}UNSPECIFIED` ? 'UNSPECIFIED' : never,
+  ShortStringEnumKey extends RemovePrefix<Prefix, ProtoEnumKey> = Exclude<
+    RemovePrefix<Prefix, ProtoEnumKey>,
+    Unspecified
+  >,
+  StringEnumType extends ProtoConstObjectOfStringsEnum<
+    ShortStringEnumKey,
+    Prefix,
+    Unspecified
+  > = ProtoConstObjectOfStringsEnum<ShortStringEnumKey, Prefix, Unspecified>,
+  MapTable extends ProtoEnumToConstObjectOfStringMapTable<
+    StringEnumType,
+    ProtoEnumValue,
+    ProtoEnum,
+    ProtoEnumKey,
+    Prefix,
+    Unspecified,
+    ShortStringEnumKey
+  > = ProtoEnumToConstObjectOfStringMapTable<
+    StringEnumType,
+    ProtoEnumValue,
+    ProtoEnum,
+    ProtoEnumKey,
+    Prefix,
+    Unspecified,
+    ShortStringEnumKey
+  >,
+>(
+  mapTable: MapTable,
+  prefix: Prefix
+): [
+  (
+    input: ShortStringEnumKey | `${Prefix}${ShortStringEnumKey}` | ProtoEnumValue | null | undefined
+  ) => ProtoEnumValue | undefined, //
+  (input: ProtoEnumValue | null | undefined) => ShortStringEnumKey | undefined, //
+] {
+  const reverseTable: Record<ProtoEnumValue, ShortStringEnumKey> = Object.fromEntries(
+    Object.entries(mapTable).map(([k, v]) => [v, k])
+  );
+  const hasUnspecified = (mapTable as any)['UNSPECIFIED'] === 0 || (mapTable as any)[`${prefix}UNSPECIFIED`] === 0;
+
+  function isShortStringEnumKeys(x: unknown): x is ShortStringEnumKey {
+    return typeof x === 'string' && x in mapTable;
+  }
+
+  function isNumericEnumValue(x: unknown): x is ProtoEnum[keyof ProtoEnum] {
+    return typeof x === 'number' && x in reverseTable;
+  }
+
+  function encode(
+    input: ShortStringEnumKey | `${Prefix}${ShortStringEnumKey}` | ProtoEnumValue | null | undefined
+  ): ProtoEnumValue | undefined {
+    if (input == null) {
+      return undefined;
+    } else if (typeof input === 'string') {
+      let shorten: string = input;
+      if (shorten.startsWith(prefix)) {
+        shorten = shorten.slice(prefix.length);
+      }
+      if (isShortStringEnumKeys(shorten)) {
+        return mapTable[shorten];
+      }
+      throw new ValueError(`Invalid enum value: '${input}'`);
+    } else if (typeof input === 'number') {
+      return input;
+    } else {
+      throw new ValueError(`Invalid enum value: '${input}' of type ${typeof input}`);
+    }
+  }
+
+  function decode(input: ProtoEnumValue | null | undefined): ShortStringEnumKey | undefined {
+    if (input == null) {
+      return undefined;
+    } else if (typeof input === 'number') {
+      if (hasUnspecified && input === 0) {
+        return undefined;
+      }
+
+      if (isNumericEnumValue(input)) {
+        return reverseTable[input];
+      }
+
+      // We got a proto enum value that we don't yet know about (i.e. it didn't exist when this code
+      // was compiled). This is certainly a possibility, but given how our APIs evolve, this is is
+      // unlikely to be a terribly bad thing by itself (we avoid adding new enum values in places
+      // that would break backward compatibility with existing deployed code). Therefore, throwing
+      // on "unexpected" values is likely to end up causing more problems than it might avoid,
+      // especially given that the decoded value may actually never get read anwyay.
+      //
+      // Therefore, we instead cheat on type constraints and return a string of the form "unknown_23".
+      // That somewhat mirrors the behavior we'd get with the pure numerical approach.
+      return `unknown_${input}` as ShortStringEnumKey;
+    }
+
+    throw new ValueError(`Invalid proto enum value: '${input}' of type ${typeof input}`);
+  }
+
+  return [encode, decode] as const;
+}
+
+/**
+ * Given the exploded parameters of a proto enum (i.e. short keys, prefix, and short key of the
+ * unspecified value), make a type that _exactly_ corresponds to the const object of strings enum,
+ * e.g. the type that the developer is expected to write.
+ *
+ * For example, for coresdk.child_workflow.ParentClosePolicy, this evaluates to:
+ *
+ * {
+ *   TERMINATE: "TERMINATE";
+ *   ABANDON: "ABANDON";
+ *   REQUEST_CANCEL: "REQUEST_CANCEL";
+ *
+ *   PARENT_CLOSE_POLICY_TERMINATE?: "TERMINATE";
+ *   PARENT_CLOSE_POLICY_ABANDON?: "ABANDON";
+ *   PARENT_CLOSE_POLICY_REQUEST_CANCEL?: "REQUEST_CANCEL";
+ *
+ *   PARENT_CLOSE_POLICY_UNSPECIFIED?: undefined;
+ * }
+ */
+type ProtoConstObjectOfStringsEnum<
+  ShortStringEnumKey extends string,
+  Prefix extends string,
+  Unspecified, // e.g. 'UNSPECIFIED'
+> = UnionToIntersection<
+  | {
+      // e.g.: "TERMINATE": "TERMINATE"
+      readonly [k in ShortStringEnumKey]: k;
+    }
+  | {
+      [k in ShortStringEnumKey]: Prefix extends ''
+        ? object
+        : {
+            // e.g.: "PARENT_CLOSE_POLICY_TERMINATE"?: "TERMINATE"
+            readonly [kk in `${Prefix}${k}`]?: k;
+          };
+    }[ShortStringEnumKey]
+  | (Unspecified extends string
+      ? {
+          // e.g.: "PARENT_CLOSE_POLICY_UNSPECIFIED"?: undefined
+          [k in `${Prefix}${Unspecified}`]?: undefined;
+        }
+      : object)
+  | (Unspecified extends string
+      ? {
+          // e.g.: "UNSPECIFIED"?: undefined
+          [k in `${Unspecified}`]?: undefined;
+        }
+      : object)
+>;
+
+/**
+ * Given the exploded parameters of a proto enum (i.e. short keys, prefix, and short key of the
+ * unspecified value), make a type that _exactly_ corresponds to the mapping table that the user is
+ * expected to provide.
+ *
+ * For example, for coresdk.child_workflow.ParentClosePolicy, this evaluates to:
+ *
+ * {
+ *  UNSPECIFIED: 0,
+ *  TERMINATE: 1,
+ *  ABANDON: 2,
+ *  REQUEST_CANCEL: 3,
+ * }
+ */
+type ProtoEnumToConstObjectOfStringMapTable<
+  _StringEnum extends ProtoConstObjectOfStringsEnum<ShortStringEnumKey, Prefix, Unspecified>,
+  ProtoEnumValue extends number,
+  ProtoEnum extends { [k in ProtoEnumKey]: ProtoEnumValue },
+  ProtoEnumKey extends `${Prefix}${string}`,
+  Prefix extends string,
+  Unspecified,
+  ShortStringEnumKey extends RemovePrefix<Prefix, ProtoEnumKey>,
+> = UnionToIntersection<
+  {
+    [k in ProtoEnumKey]: {
+      [kk in RemovePrefix<Prefix, k>]: ProtoEnum[k] extends number ? ProtoEnum[k] : never;
+    };
+  }[ProtoEnumKey]
+>;

package/src/internal-workflow/index.ts

@@ -0,0 +1 @@
+export * from './enums-helpers';