@temporalio/common 0.15.0 → 0.17.1

package/src/converter/payload-converter.ts

@@ -1,5 +1,17 @@
-import { ValueError } from '../errors';
-import { u8, str, Payload, encodingTypes, encodingKeys, METADATA_ENCODING_KEY } from './types';
+import { ValueError, DataConverterError } from '../errors';
+import {
+  u8,
+  str,
+  Payload,
+  encodingTypes,
+  encodingKeys,
+  METADATA_ENCODING_KEY,
+  METADATA_MESSAGE_TYPE_KEY,
+} from './types';
+import { isRecord, hasOwnProperty, hasOwnProperties } from '../type-helpers';
+import { errorMessage } from '../errors';
+import * as protoJsonSerializer from 'proto3-json-serializer';
+import type { Root, Type, Namespace, Message } from 'protobufjs';
 
 /**
  * Used by the framework to serialize/deserialize method parameters that need to be sent over the
@@ -15,7 +27,7 @@ export interface PayloadConverter {
    * Implements conversion of value to payload
    *
    * @param value JS value to convert.
-   * @return converted value
+   * @return converted value or `undefined` if unable to convert.
    * @throws DataConverterException if conversion of the value passed as parameter failed for any
    *     reason.
    */
@@ -38,7 +50,7 @@ export interface PayloadConverter {
    * Implements conversion of value to payload
    *
    * @param value JS value to convert.
-   * @return converted value
+   * @return converted value or `undefined` if unable to convert.
    * @throws DataConverterException if conversion of the value passed as parameter failed for any
    *     reason.
    */
@@ -140,3 +152,142 @@ export class BinaryPayloadConverter extends AsyncFacadePayloadConverter {
     return content.data as any;
   }
 }
+
+abstract class ProtobufPayloadConverter extends AsyncFacadePayloadConverter {
+  protected readonly root: Root | undefined;
+
+  // Don't use type Root here because root.d.ts doesn't export Root, so users would have to type assert
+  constructor(root?: unknown) {
+    super();
+
+    if (root) {
+      if (!isRoot(root)) {
+        throw new TypeError('root must be an instance of a protobufjs Root');
+      }
+
+      this.root = root;
+    }
+  }
+
+  protected validatePayload(content: Payload): { messageType: Type; data: Uint8Array } {
+    if (content.data === undefined || content.data === null) {
+      throw new ValueError('Got payload with no data');
+    }
+    if (!content.metadata || !(METADATA_MESSAGE_TYPE_KEY in content.metadata)) {
+      throw new ValueError(`Got protobuf payload without metadata.${METADATA_MESSAGE_TYPE_KEY}`);
+    }
+    if (!this.root) {
+      throw new DataConverterError('Unable to deserialize protobuf message without `root` being provided');
+    }
+
+    const messageTypeName = str(content.metadata[METADATA_MESSAGE_TYPE_KEY]);
+    let messageType;
+    try {
+      messageType = this.root.lookupType(messageTypeName);
+    } catch (e) {
+      if (errorMessage(e)?.includes('no such type')) {
+        throw new DataConverterError(
+          `Got a \`${messageTypeName}\` protobuf message but cannot find corresponding message class in \`root\``
+        );
+      }
+
+      throw e;
+    }
+
+    return { messageType, data: content.data };
+  }
+
+  protected constructPayload({ messageTypeName, message }: { messageTypeName: string; message: Uint8Array }): Payload {
+    return {
+      metadata: {
+        [METADATA_ENCODING_KEY]: u8(this.encodingType),
+        [METADATA_MESSAGE_TYPE_KEY]: u8(messageTypeName),
+      },
+      data: message,
+    };
+  }
+}
+
+/**
+ * Converts between protobufjs Message instances and serialized Protobuf Payload
+ */
+export class ProtobufBinaryPayloadConverter extends ProtobufPayloadConverter {
+  public encodingType = encodingTypes.METADATA_ENCODING_PROTOBUF;
+
+  constructor(root?: unknown) {
+    super(root);
+  }
+
+  public toDataSync(value: unknown): Payload | undefined {
+    if (!isProtobufMessage(value)) {
+      return undefined;
+    }
+
+    return this.constructPayload({
+      messageTypeName: getNamespacedTypeName(value.$type),
+      message: value.$type.encode(value).finish(),
+    });
+  }
+
+  public fromDataSync<T>(content: Payload): T {
+    const { messageType, data } = this.validatePayload(content);
+    return messageType.decode(data) as unknown as T;
+  }
+}
+
+/**
+ * Converts between protobufjs Message instances and serialized JSON Payload
+ */
+export class ProtobufJsonPayloadConverter extends ProtobufPayloadConverter {
+  public encodingType = encodingTypes.METADATA_ENCODING_PROTOBUF_JSON;
+
+  constructor(root?: unknown) {
+    super(root);
+  }
+
+  public toDataSync(value: unknown): Payload | undefined {
+    if (!isProtobufMessage(value)) {
+      return undefined;
+    }
+
+    const jsonValue = protoJsonSerializer.toProto3JSON(value);
+
+    return this.constructPayload({
+      messageTypeName: getNamespacedTypeName(value.$type),
+      message: u8(JSON.stringify(jsonValue)),
+    });
+  }
+
+  public fromDataSync<T>(content: Payload): T {
+    const { messageType, data } = this.validatePayload(content);
+    return protoJsonSerializer.fromProto3JSON(messageType, JSON.parse(str(data))) as unknown as T;
+  }
+}
+
+function isProtobufType(type: unknown): type is Type {
+  return (
+    isRecord(type) &&
+    type.constructor.name === 'Type' &&
+    hasOwnProperties(type, ['parent', 'name', 'create', 'encode', 'decode']) &&
+    typeof type.name === 'string' &&
+    typeof type.create === 'function' &&
+    typeof type.encode === 'function' &&
+    typeof type.decode === 'function'
+  );
+}
+
+function isProtobufMessage(value: unknown): value is Message {
+  return isRecord(value) && hasOwnProperty(value, '$type') && isProtobufType(value.$type);
+}
+
+function getNamespacedTypeName(node: Type | Namespace): string {
+  if (node.parent && !isRoot(node.parent)) {
+    return getNamespacedTypeName(node.parent) + '.' + node.name;
+  } else {
+    return node.name;
+  }
+}
+
+function isRoot(root: unknown): root is Root {
+  return isRecord(root) && root.constructor.name === 'Root';
+}

package/src/converter/types.ts

@@ -1,4 +1,4 @@
-import * as iface from '@temporalio/proto/lib/coresdk';
+import type * as iface from '@temporalio/proto/lib/coresdk';
 import { TextEncoder, TextDecoder } from '../encoding';
 
 export type Payload = iface.coresdk.common.IPayload;
@@ -30,3 +30,5 @@ export const encodingKeys = {
   METADATA_ENCODING_PROTOBUF_JSON: u8(encodingTypes.METADATA_ENCODING_PROTOBUF_JSON),
   METADATA_ENCODING_PROTOBUF: u8(encodingTypes.METADATA_ENCODING_PROTOBUF),
 } as const;
+
+export const METADATA_MESSAGE_TYPE_KEY = 'messageType';

package/src/errors.ts

@@ -25,3 +25,21 @@ export function errorMessage(err: unknown): string | undefined {
   }
   return undefined;
 }
+
+interface ErrorWithCode {
+  code: string;
+}
+/**
+ * Get error code from an Error or return undefined
+ */
+export function errorCode(error: unknown): string | undefined {
+  if (
+    typeof error === 'object' &&
+    (error as ErrorWithCode).code !== undefined &&
+    typeof (error as ErrorWithCode).code === 'string'
+  ) {
+    return (error as ErrorWithCode).code;
+  }
+
+  return undefined;
+}

package/src/failure.ts

@@ -1,12 +1,36 @@
-import { temporal } from '@temporalio/proto/lib/coresdk';
+import type { temporal } from '@temporalio/proto/lib/coresdk';
 import { DataConverter, arrayFromPayloads } from './converter/data-converter';
+import { checkExtends } from './type-helpers';
 
 export const FAILURE_SOURCE = 'TypeScriptSDK';
 export type ProtoFailure = temporal.api.failure.v1.IFailure;
-export type TimeoutType = temporal.api.enums.v1.TimeoutType;
-export const TimeoutType = temporal.api.enums.v1.TimeoutType;
-export type RetryState = temporal.api.enums.v1.RetryState;
-export const RetryState = temporal.api.enums.v1.RetryState;
+// 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,
+}
+
+checkExtends<temporal.api.enums.v1.TimeoutType, 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,
+}
+
+checkExtends<temporal.api.enums.v1.RetryState, RetryState>();
+
 export type WorkflowExecution = temporal.api.common.v1.IWorkflowExecution;
 
 /**
@@ -90,8 +114,8 @@ export class ApplicationFailure extends TemporalFailure {
    * @param details optional details about the failure. They are serialized using the same approach
    *     as arguments and results.
    */
-  public static retryable(message: string | undefined, type: string, ...details: unknown[]): ApplicationFailure {
-    return new this(message, type, false, details);
+  public static retryable(message: string | undefined, type?: string, ...details: unknown[]): ApplicationFailure {
+    return new this(message, type ?? 'Error', false, details);
   }
 
   /**
@@ -105,8 +129,8 @@ export class ApplicationFailure extends TemporalFailure {
    * @param details optional details about the failure. They are serialized using the same approach
    *     as arguments and results.
    */
-  public static nonRetryable(message: string | undefined, type: string, ...details: unknown[]): ApplicationFailure {
-    return new this(message, type, true, details);
+  public static nonRetryable(message: string | undefined, type?: string, ...details: unknown[]): ApplicationFailure {
+    return new this(message, type ?? 'Error', true, details);
   }
 }
 
@@ -198,7 +222,7 @@ export async function optionalErrorToOptionalFailure(
  */
 const CUTTOFF_STACK_PATTERNS = [
   /** Activity execution */
-  /\s+at Activity\.execute \(.*\/worker\/(?:src|lib)\/activity\.[jt]s:\d+:\d+\)/,
+  /\s+at Activity\.execute \(.*[\\/]worker[\\/](?:src|lib)[\\/]activity\.[jt]s:\d+:\d+\)/,
   /** Workflow activation */
   /\s+at Activator\.\S+NextHandler \(webpack-internal:\/\/\/.*\/internals\.[jt]s:\d+:\d+\)/,
 ];

package/src/index.ts

@@ -5,11 +5,14 @@
  */
 export * from './activity-options';
 export * from './converter/data-converter';
+export * from './converter/helpers';
 export * from './errors';
 export * from './failure';
 export * from './interceptors';
 export * from './interfaces';
+export * from './retry-policy';
 export * from './time';
 export * from './tls-config';
 export * from './workflow-handle';
 export * from './workflow-options';
+export * from './utils';

package/src/interceptors.ts

@@ -1,4 +1,4 @@
-import { coresdk } from '@temporalio/proto/lib/coresdk';
+import type { coresdk } from '@temporalio/proto/lib/coresdk';
 import { AnyFunc, OmitLastParam } from './type-helpers';
 
 /**

package/src/interfaces.ts

@@ -13,6 +13,8 @@ export type Workflow = (...args: any[]) => WorkflowReturnType;
 
 /**
  * An interface representing a Workflow signal definition, as returned from {@link defineSignal}
+ *
+ * @remarks `_Args` can be used for parameter type inference in handler functions and *WorkflowHandle methods.
  */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export interface SignalDefinition<_Args extends any[] = []> {
@@ -22,6 +24,8 @@ export interface SignalDefinition<_Args extends any[] = []> {
 
 /**
  * An interface representing a Workflow query definition as returned from {@link defineQuery}
+ *
+ * @remarks `_Args` and `_Ret` can be used for parameter type inference in handler functions and *WorkflowHandle methods.
  */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export interface QueryDefinition<_Ret, _Args extends any[] = []> {
@@ -31,43 +35,3 @@ export interface QueryDefinition<_Ret, _Args extends any[] = []> {
 
 /** Get the "unwrapped" return type (without Promise) of the execute handler from Workflow type `W` */
 export type WorkflowResultType<W extends Workflow> = ReturnType<W> extends Promise<infer R> ? R : never;
-
-/**
- * Defines options for activity retries
- * @see {@link https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/common/RetryOptions.Builder.html | Java SDK definition}
- */
-export interface RetryOptions {
-  /**
-   * Coefficient used to calculate the next retry interval.
-   * The next retry interval is previous interval multiplied by this coefficient.
-   * @minimum 1
-   * @default 2
-   */
-  backoffCoefficient?: number;
-  /**
-   * 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
-   */
-  initialInterval: string | number;
-  /**
-   * Maximum number of attempts. When exceeded the retries stop even if not expired yet.
-   * @minimum 1
-   * @default Infinity
-   */
-  maximumAttempts?: number;
-  /**
-   * Maximum interval between retries.
-   * Exponential backoff leads to interval increase.
-   * 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
-   */
-  maximumInterval?: string | number;
-
-  /**
-   * List of application failures types to not retry.
-   */
-  nonRetryableErrorTypes?: string[];
-}

package/src/retry-policy.ts

@@ -0,0 +1,73 @@
+import type { temporal } from '@temporalio/proto';
+import { ValueError } from '.';
+import { msOptionalToNumber, msOptionalToTs, msToNumber, msToTs } from './time';
+
+/**
+ * Options for retrying Workflows and Activities
+ */
+export interface RetryPolicy {
+  /**
+   * Coefficient used to calculate the next retry interval.
+   * The next retry interval is previous interval multiplied by this coefficient.
+   * @minimum 1
+   * @default 2
+   */
+  backoffCoefficient?: number;
+  /**
+   * 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
+   * @default 1 second
+   */
+  initialInterval?: string | number;
+  /**
+   * Maximum number of attempts. When exceeded the retries stop even if not expired yet.
+   * @minimum 1
+   * @default Infinity
+   */
+  maximumAttempts?: number;
+  /**
+   * Maximum interval between retries.
+   * Exponential backoff leads to interval increase.
+   * 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
+   */
+  maximumInterval?: string | number;
+
+  /**
+   * List of application failures types to not retry.
+   */
+  nonRetryableErrorTypes?: string[];
+}
+
+/**
+ * Turns a TS RetryPolicy into a proto compatible RetryPolicy
+ */
+export function compileRetryPolicy(retryPolicy: RetryPolicy): temporal.api.common.v1.IRetryPolicy {
+  if (retryPolicy.backoffCoefficient != null && retryPolicy.backoffCoefficient <= 0) {
+    throw new ValueError('RetryPolicy.backoffCoefficient must be greater than 0');
+  }
+  if (retryPolicy.maximumAttempts != null && retryPolicy.maximumAttempts <= 0) {
+    throw new ValueError('RetryPolicy.maximumAttempts must be greater than 0');
+  }
+  const maximumInterval = msOptionalToNumber(retryPolicy.maximumInterval);
+  const initialInterval = msToNumber(retryPolicy.initialInterval ?? 1000);
+  if (maximumInterval === 0) {
+    throw new ValueError('RetryPolicy.maximumInterval cannot be 0');
+  }
+  if (initialInterval === 0) {
+    throw new ValueError('RetryPolicy.initialInterval cannot be 0');
+  }
+  if (maximumInterval != null && maximumInterval < initialInterval) {
+    throw new ValueError('RetryPolicy.maximumInterval cannot be less than its initialInterval');
+  }
+  return {
+    maximumAttempts: retryPolicy.maximumAttempts,
+    initialInterval: msToTs(initialInterval),
+    maximumInterval: msOptionalToTs(maximumInterval),
+    backoffCoefficient: retryPolicy.backoffCoefficient,
+    nonRetryableErrorTypes: retryPolicy.nonRetryableErrorTypes,
+  };
+}

package/src/time.ts

@@ -1,6 +1,6 @@
 import Long from 'long';
 import ms from 'ms';
-import * as iface from '@temporalio/proto/lib/coresdk';
+import type * as iface from '@temporalio/proto/lib/coresdk';
 import { ValueError } from './errors';
 
 // NOTE: these are the same interface in JS
@@ -59,6 +59,11 @@ export function msOptionalToTs(str: string | number | undefined): Timestamp | un
   return msNumberToTs(ms(str));
 }
 
+export function msOptionalToNumber(val: string | number | undefined): number | undefined {
+  if (val === undefined) return undefined;
+  return msToNumber(val);
+}
+
 export function msToNumber(val: string | number): number {
   if (typeof val === 'number') {
     return val;

package/src/type-helpers.ts

@@ -4,3 +4,26 @@ export type AnyFunc = (...args: any[]) => any;
 export type OmitLast<T> = T extends [...infer REST, any] ? REST : never;
 /** F with all arguments but the last */
 export type OmitLastParam<F extends AnyFunc> = (...args: OmitLast<Parameters<F>>) => ReturnType<F>;
+
+/** Verify that an type _Copy extends _Orig */
+export function checkExtends<_Orig, _Copy extends _Orig>(): void {
+  // noop, just type check
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+export function hasOwnProperty<X extends Record<string, unknown>, Y extends PropertyKey>(
+  record: X,
+  prop: Y
+): record is X & Record<Y, unknown> {
+  return prop in record;
+}
+
+export function hasOwnProperties<X extends Record<string, unknown>, Y extends PropertyKey>(
+  record: X,
+  props: Y[]
+): record is X & Record<Y, unknown> {
+  return props.every((prop) => prop in record);
+}

package/src/utils.ts

@@ -0,0 +1,6 @@
+/**
+ * Helper to prevent undefined and null values overriding defaults when merging maps
+ */
+export function filterNullAndUndefined<T extends Record<string, any>>(obj: T): T {
+  return Object.fromEntries(Object.entries(obj).filter(([_k, v]) => v != null)) as any;
+}

package/src/workflow-options.ts

@@ -1,19 +1,21 @@
-import { coresdk, google } from '@temporalio/proto/lib/coresdk';
+import type { coresdk, google } from '@temporalio/proto/lib/coresdk';
 import { Workflow } from './interfaces';
+import { RetryPolicy } from './retry-policy';
 import { msToTs } from './time';
+import { checkExtends } from './type-helpers';
+
+// Avoid importing the proto implementation to reduce workflow bundle size
+// Copied from coresdk.common.WorkflowIdReusePolicy
+export enum WorkflowIdReusePolicy {
+  WORKFLOW_ID_REUSE_POLICY_UNSPECIFIED = 0,
+  WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE = 1,
+  WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2,
+  WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE = 3,
+}
 
-export type WorkflowIdReusePolicy = coresdk.common.WorkflowIdReusePolicy;
-export const WorkflowIdReusePolicy = coresdk.common.WorkflowIdReusePolicy;
-export type RetryPolicy = coresdk.common.IRetryPolicy;
+checkExtends<coresdk.common.WorkflowIdReusePolicy, WorkflowIdReusePolicy>();
 
 export interface BaseWorkflowOptions {
-  /**
-   * Workflow id to use when starting. If not specified a UUID is generated. Note that it is
-   * dangerous as in case of client side retries no deduplication will happen based on the
-   * generated id. So prefer assigning business meaningful ids if possible.
-   */
-  workflowId?: string;
-
   /**
    * Specifies server behavior if a completed workflow with the same id exists. Note that under no
    * conditions Temporal allows two workflows with the same namespace and workflow id run
@@ -26,12 +28,12 @@ export interface BaseWorkflowOptions {
   workflowIdReusePolicy?: WorkflowIdReusePolicy;
 
   /**
-   * Task queue to use for Workflow tasks. It should match a task queue specified when creating a
-   * `Worker` that hosts the Workflow code.
+   * Controls how a Workflow is retried.
+   *
+   * Workflows should typically use the system default, do not set this unless
+   * you know what you're doing.
    */
-  taskQueue?: string;
-
-  retryPolicy?: coresdk.common.IRetryPolicy;
+  retry?: RetryPolicy;
 
   /**
    * Optional cron schedule for Workflow. If a cron schedule is specified, the Workflow will run
@@ -100,29 +102,22 @@ export interface WorkflowDurationOptions {
   workflowTaskTimeout?: string | number;
 }
 
-export type WorkflowOptions = BaseWorkflowOptions & WorkflowDurationOptions;
+export type CommonWorkflowOptions = BaseWorkflowOptions & WorkflowDurationOptions;
 
-export type RequiredWorkflowOptions<T extends Workflow = Workflow> = Required<
-  Pick<BaseWorkflowOptions, 'workflowId' | 'taskQueue'>
+export type WithCompiledWorkflowDurationOptions<T extends WorkflowDurationOptions> = Omit<
+  T,
+  'workflowExecutionTimeout' | 'workflowRunTimeout' | 'workflowTaskTimeout'
 > & {
-  args: Parameters<T>[];
+  workflowExecutionTimeout?: google.protobuf.IDuration;
+  workflowRunTimeout?: google.protobuf.IDuration;
+  workflowTaskTimeout?: google.protobuf.IDuration;
 };
 
-export type WorkflowOptionsWithDefaults<T extends Workflow = Workflow> = WorkflowOptions & RequiredWorkflowOptions<T>;
-
-export type CompiledWorkflowOptions<T extends Workflow = Workflow> = BaseWorkflowOptions &
-  RequiredWorkflowOptions<T> & {
-    workflowExecutionTimeout?: google.protobuf.IDuration;
-    workflowRunTimeout?: google.protobuf.IDuration;
-    workflowTaskTimeout?: google.protobuf.IDuration;
-  };
+export function compileWorkflowOptions<T extends WorkflowDurationOptions>(
+  options: T
+): WithCompiledWorkflowDurationOptions<T> {
+  const { workflowExecutionTimeout, workflowRunTimeout, workflowTaskTimeout, ...rest } = options;
 
-export function compileWorkflowOptions<T extends Workflow>({
-  workflowExecutionTimeout,
-  workflowRunTimeout,
-  workflowTaskTimeout,
-  ...rest
-}: WorkflowOptionsWithDefaults<T>): CompiledWorkflowOptions<T> {
   return {
     ...rest,
     workflowExecutionTimeout: workflowExecutionTimeout ? msToTs(workflowExecutionTimeout) : undefined,