feat!: Protect against ms durations errors (#1136)

Author: mjameswh

package-lock.json

@@ -71,7 +71,7 @@
 
 import 'abort-controller/polyfill'; // eslint-disable-line import/no-unassigned-import
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { msToNumber } from '@temporalio/common/lib/time';
+import { Duration, msToNumber } from '@temporalio/common/lib/time';
 
 export {
   ActivityFunction,
@@ -279,7 +279,7 @@ export class Context {
    * @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> {
+  public sleep(ms: Duration): Promise<void> {
     let handle: NodeJS.Timeout;
     const timer = new Promise<void>((resolve) => {
       handle = setTimeout(resolve, msToNumber(ms));

packages/activity/src/index.ts

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import * as grpc from '@grpc/grpc-js';
 import type { RPCImpl } from 'protobufjs';
 import { filterNullAndUndefined, normalizeTlsConfig, TLSConfig } from '@temporalio/common/lib/internal-non-workflow';
-import { msOptionalToNumber } from '@temporalio/common/lib/time';
+import { Duration, msOptionalToNumber } from '@temporalio/common/lib/time';
 import { isServerErrorResponse, ServiceError } from './errors';
 import { defaultGrpcRetryOptions, makeGrpcRetryInterceptor } from './grpc-retry';
 import pkg from './pkg';
@@ -81,7 +81,7 @@ export interface ConnectionOptions {
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 10 seconds
    */
-  connectTimeout?: number | string;
+  connectTimeout?: Duration;
 }
 
 export type ConnectionOptionsWithDefaults = Required<Omit<ConnectionOptions, 'tls' | 'connectTimeout'>> & {

packages/client/src/connection.ts

@@ -1,5 +1,5 @@
 import { checkExtends, Replace } from '@temporalio/common/lib/type-helpers';
-import { SearchAttributes, Workflow } from '@temporalio/common';
+import { Duration, SearchAttributes, Workflow } from '@temporalio/common';
 import type { temporal } from '@temporalio/proto';
 import { WorkflowStartOptions } from './workflow-options';
 
@@ -46,7 +46,7 @@ export interface ScheduleOptions<A extends ScheduleOptionsAction = ScheduleOptio
      * @default 1 minute
      * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
      */
-    catchupWindow?: number | string;
+    catchupWindow?: Duration;
 
     /**
      * When an Action times out or reaches the end of its Retry Policy, {@link pause}.
@@ -465,7 +465,7 @@ export interface ScheduleSpec {
    * @default 0
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  jitter?: number | string;
+  jitter?: Duration;
 
   /**
    * IANA timezone name, for example `US/Pacific`.
@@ -659,15 +659,15 @@ export interface IntervalSpec {
    *
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  every: number | string;
+  every: Duration;
 
   /**
    * Value is rounded to the nearest second.
    *
    * @default 0
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  offset?: number | string;
+  offset?: Duration;
 }
 
 /**

packages/client/src/schedule-types.ts

@@ -15,7 +15,7 @@
     "@opentelemetry/api": "^1.4.1",
     "@temporalio/proto": "file:../proto",
     "long": "^5.2.0",
-    "ms": "^2.1.3",
+    "ms": "^3.0.0-canary.1",
     "proto3-json-serializer": "^1.0.3",
     "protobufjs": "^7.0.0"
   },

packages/common/package.json

@@ -1,6 +1,7 @@
 import type { coresdk } from '@temporalio/proto';
 import { RetryPolicy } from './retry-policy';
 import { checkExtends } from './type-helpers';
+import { Duration } from './time';
 
 // Avoid importing the proto implementation to reduce workflow bundle size
 // Copied from coresdk.workflow_commands.ActivityCancellationType
@@ -37,7 +38,7 @@ export interface ActivityOptions {
    * Heartbeat interval. Activity must heartbeat before this interval passes after a last heartbeat or activity start.
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  heartbeatTimeout?: string | number;
+  heartbeatTimeout?: Duration;
 
   /**
    * RetryPolicy that define how activity is retried in case of failure. If this is not set, then the server-defined default activity retry policy will be used. To ensure zero retries, set maximum attempts to 1.
@@ -56,7 +57,7 @@ export interface ActivityOptions {
    * @default `scheduleToCloseTimeout` or unlimited
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  startToCloseTimeout?: string | number;
+  startToCloseTimeout?: Duration;
 
   /**
    * 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.
@@ -65,7 +66,7 @@ export interface ActivityOptions {
    * @default `scheduleToCloseTimeout` or unlimited
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  scheduleToStartTimeout?: string | number;
+  scheduleToStartTimeout?: Duration;
 
   /**
    * Total time that a workflow is willing to wait for Activity to complete.
@@ -76,7 +77,7 @@ export interface ActivityOptions {
    * @default unlimited
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  scheduleToCloseTimeout?: string | number;
+  scheduleToCloseTimeout?: Duration;
 
   /**
    * Determines what the SDK does when the Activity is cancelled.
@@ -120,7 +121,7 @@ export interface LocalActivityOptions {
    *
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  startToCloseTimeout?: string | number;
+  startToCloseTimeout?: Duration;
 
   /**
    * Limits time the local activity can idle internally before being executed. That can happen if
@@ -132,7 +133,7 @@ export interface LocalActivityOptions {
    * @default unlimited
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  scheduleToStartTimeout?: string | number;
+  scheduleToStartTimeout?: Duration;
 
   /**
    * Indicates how long the caller is willing to wait for local activity completion. Limits how
@@ -144,7 +145,7 @@ export interface LocalActivityOptions {
    * @default unlimited
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  scheduleToCloseTimeout?: string | number;
+  scheduleToCloseTimeout?: Duration;
 
   /**
    * If the activity is retrying and backoff would exceed this value, a server side timer will be scheduled for the next attempt.
@@ -153,7 +154,7 @@ export interface LocalActivityOptions {
    * @default 1 minute
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    **/
-  localRetryThreshold?: string | number;
+  localRetryThreshold?: Duration;
 
   /**
    * Determines what the SDK does when the Activity is cancelled.

packages/common/src/activity-options.ts

@@ -1,5 +1,5 @@
 import * as time from './time';
-import { Timestamp } from './time';
+import { type Timestamp, Duration } from './time';
 
 /**
  * Lossy conversion function from Timestamp to number due to possible overflow.
@@ -35,31 +35,31 @@ export function msNumberToTs(millis: number): Timestamp {
  * @hidden
  * @deprecated - meant for internal use only
  */
-export function msToTs(str: string | number): Timestamp {
+export function msToTs(str: Duration): Timestamp {
   return time.msToTs(str);
 }
 
 /**
  * @hidden
  * @deprecated - meant for internal use only
  */
-export function msOptionalToTs(str: string | number | undefined): Timestamp | undefined {
+export function msOptionalToTs(str: Duration | undefined): Timestamp | undefined {
   return time.msOptionalToTs(str);
 }
 
 /**
  * @hidden
  * @deprecated - meant for internal use only
  */
-export function msOptionalToNumber(val: string | number | undefined): number | undefined {
+export function msOptionalToNumber(val: Duration | undefined): number | undefined {
   return time.msOptionalToNumber(val);
 }
 
 /**
  * @hidden
  * @deprecated - meant for internal use only
  */
-export function msToNumber(val: string | number): number {
+export function msToNumber(val: Duration): number {
   return time.msToNumber(val);
 }
 

packages/common/src/deprecated-time.ts

@@ -19,7 +19,7 @@ export * from './failure';
 export { Headers, Next } from './interceptors';
 export * from './interfaces';
 export * from './retry-policy';
-export { Timestamp } from './time';
+export { type Timestamp, Duration } from './time';
 export * from './workflow-handle';
 export * from './workflow-options';
 

packages/common/src/index.ts

@@ -1,6 +1,6 @@
 import type { temporal } from '@temporalio/proto';
 import { ValueError } from './errors';
-import { msOptionalToNumber, msOptionalToTs, msToNumber, msToTs, optionalTsToMs } from './time';
+import { Duration, msOptionalToNumber, msOptionalToTs, msToNumber, msToTs, optionalTsToMs } from './time';
 
 /**
  * Options for retrying Workflows and Activities
@@ -19,7 +19,7 @@ export interface RetryPolicy {
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 1 second
    */
-  initialInterval?: string | number;
+  initialInterval?: Duration;
   /**
    * Maximum number of attempts. When exceeded, retries stop (even if {@link ActivityOptions.scheduleToCloseTimeout}
    * hasn't been reached).
@@ -35,7 +35,7 @@ export interface RetryPolicy {
    * @default 100x of {@link initialInterval}
    * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    */
-  maximumInterval?: string | number;
+  maximumInterval?: Duration;
 
   /**
    * List of application failures types to not retry.