@temporalio/common 1.7.4 → 1.8.1

package/src/activity-options.ts

@@ -1,6 +1,8 @@
 import type { coresdk } from '@temporalio/proto';
 import { RetryPolicy } from './retry-policy';
 import { checkExtends } from './type-helpers';
+import { Duration } from './time';
+import { VersioningIntent } from './versioning-intent';
 
 // Avoid importing the proto implementation to reduce workflow bundle size
 // Copied from coresdk.workflow_commands.ActivityCancellationType
@@ -37,7 +39,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 +58,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 +67,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 +78,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.
@@ -99,6 +101,14 @@ export interface ActivityOptions {
    * @default true
    */
   allowEagerDispatch?: boolean;
+
+  /**
+   * When using the Worker Versioning feature, specifies whether this Activity should run on a
+   * worker with a compatible Build Id or not. See {@link VersioningIntent}.
+   *
+   * @experimental
+   */
+  versioningIntent?: VersioningIntent;
 }
 
 /**
@@ -120,7 +130,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,19 +142,18 @@ 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
-   * long retries will be attempted. When not specified defaults to the workflow execution
-   * timeout (which may be unset).
+   * long retries will be attempted.
    *
    * Either this option or {@link startToCloseTimeout} is required.
    *
    * @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 +162,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.

package/src/converter/failure-converter.ts

@@ -57,8 +57,10 @@ export interface FailureConverter {
   errorToFailure(err: unknown, payloadConverter: PayloadConverter): ProtoFailure;
   /**
    * Converts a Failure proto message to a JS Error object.
+   *
+   * The returned error must be an instance of `TemporalFailure`.
    */
-  failureToError(err: ProtoFailure, payloadConverter: PayloadConverter): Error;
+  failureToError(err: ProtoFailure, payloadConverter: PayloadConverter): TemporalFailure;
 }
 
 /**
@@ -183,7 +185,7 @@ export class DefaultFailureConverter implements FailureConverter {
     );
   }
 
-  failureToError(failure: ProtoFailure, payloadConverter: PayloadConverter): Error {
+  failureToError(failure: ProtoFailure, payloadConverter: PayloadConverter): TemporalFailure {
     if (failure.encodedAttributes) {
       const attrs = payloadConverter.fromPayload<DefaultEncodedFailureAttributes>(failure.encodedAttributes);
       // Don't apply encodedAttributes unless they conform to an expected schema
@@ -217,7 +219,7 @@ export class DefaultFailureConverter implements FailureConverter {
   }
 
   errorToFailureInner(err: unknown, payloadConverter: PayloadConverter): ProtoFailure {
-    if (err instanceof TemporalFailure) {
+    if (TemporalFailure.is(err)) {
       if (err.failure) return err.failure;
       const base = {
         message: err.message,
@@ -226,7 +228,7 @@ export class DefaultFailureConverter implements FailureConverter {
         source: FAILURE_SOURCE,
       };
 
-      if (err instanceof ActivityFailure) {
+      if (ActivityFailure.is(err)) {
         return {
           ...base,
           activityFailureInfo: {
@@ -235,7 +237,7 @@ export class DefaultFailureConverter implements FailureConverter {
           },
         };
       }
-      if (err instanceof ChildWorkflowFailure) {
+      if (ChildWorkflowFailure.is(err)) {
         return {
           ...base,
           childWorkflowExecutionFailureInfo: {
@@ -245,7 +247,7 @@ export class DefaultFailureConverter implements FailureConverter {
           },
         };
       }
-      if (err instanceof ApplicationFailure) {
+      if (ApplicationFailure.is(err)) {
         return {
           ...base,
           applicationFailureInfo: {
@@ -258,7 +260,7 @@ export class DefaultFailureConverter implements FailureConverter {
           },
         };
       }
-      if (err instanceof CancelledFailure) {
+      if (CancelledFailure.is(err)) {
         return {
           ...base,
           canceledFailureInfo: {
@@ -269,7 +271,7 @@ export class DefaultFailureConverter implements FailureConverter {
           },
         };
       }
-      if (err instanceof TimeoutFailure) {
+      if (TimeoutFailure.is(err)) {
         return {
           ...base,
           timeoutFailureInfo: {
@@ -280,16 +282,16 @@ export class DefaultFailureConverter implements FailureConverter {
           },
         };
       }
-      if (err instanceof TerminatedFailure) {
+      if (ServerFailure.is(err)) {
         return {
           ...base,
-          terminatedFailureInfo: {},
+          serverFailureInfo: { nonRetryable: err.nonRetryable },
         };
       }
-      if (err instanceof ServerFailure) {
+      if (TerminatedFailure.is(err)) {
         return {
           ...base,
-          serverFailureInfo: { nonRetryable: err.nonRetryable },
+          terminatedFailureInfo: {},
         };
       }
       // Just a TemporalFailure
@@ -333,7 +335,7 @@ export class DefaultFailureConverter implements FailureConverter {
   optionalFailureToOptionalError(
     failure: ProtoFailure | undefined | null,
     payloadConverter: PayloadConverter
-  ): Error | undefined {
+  ): TemporalFailure | undefined {
     return failure ? this.failureToError(failure, payloadConverter) : undefined;
   }
 

package/src/converter/payload-converter.ts

@@ -1,5 +1,5 @@
 import { decode, encode } from '../encoding';
-import { IllegalStateError, PayloadConverterError, ValueError } from '../errors';
+import { PayloadConverterError, ValueError } from '../errors';
 import { Payload } from '../interfaces';
 import { encodingKeys, encodingTypes, METADATA_ENCODING_KEY } from './types';
 
@@ -209,7 +209,12 @@ export class BinaryPayloadConverter implements PayloadConverterWithEncoding {
   }
 
   public fromPayload<T>(content: Payload): T {
-    return content.data as any;
+    return (
+      // Wrap with Uint8Array from this context to ensure `instanceof` works
+      (
+        content.data ? new Uint8Array(content.data.buffer, content.data.byteOffset, content.data.length) : content.data
+      ) as any
+    );
   }
 }
 
@@ -227,7 +232,7 @@ export class JsonPayloadConverter implements PayloadConverterWithEncoding {
     let json;
     try {
       json = JSON.stringify(value);
-    } catch (e) {
+    } catch (err) {
       return undefined;
     }
 
@@ -290,7 +295,7 @@ export class SearchAttributePayloadConverter implements PayloadConverter {
     // JSON.stringify takes care of converting Dates to ISO strings
     const ret = this.jsonConverter.toPayload(values);
     if (ret === undefined) {
-      throw new IllegalStateError('Could not convert search attributes to payloads');
+      throw new ValueError('Could not convert search attributes to payloads');
     }
     return ret;
   }

package/src/converter/protobuf-payload-converters.ts

@@ -97,7 +97,9 @@ export class ProtobufBinaryPayloadConverter extends ProtobufPayloadConverter {
 
   public fromPayload<T>(content: Payload): T {
     const { messageType, data } = this.validatePayload(content);
-    return messageType.decode(data) as unknown as T;
+    // Wrap with Uint8Array from this context to ensure `instanceof` works
+    const localData = data ? new Uint8Array(data.buffer, data.byteOffset, data.length) : data;
+    return messageType.decode(localData) as unknown as T;
   }
 }
 

package/src/deprecated-time.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,7 +35,7 @@ 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);
 }
 
@@ -43,7 +43,7 @@ export function msToTs(str: string | number): Timestamp {
  * @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);
 }
 
@@ -51,7 +51,7 @@ export function msOptionalToTs(str: string | number | undefined): Timestamp | un
  * @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);
 }
 
@@ -59,7 +59,7 @@ export function msOptionalToNumber(val: string | number | undefined): number | u
  * @hidden
  * @deprecated - meant for internal use only
  */
-export function msToNumber(val: string | number): number {
+export function msToNumber(val: Duration): number {
   return time.msToNumber(val);
 }
 

package/src/errors.ts

@@ -25,6 +25,8 @@ export class IllegalStateError extends Error {
   public readonly name: string = 'IllegalStateError';
 }
 
+const isWorkflowExecutionAlreadyStartedError = Symbol.for('__temporal_isWorkflowExecutionAlreadyStartedError');
+
 /**
  * This exception is thrown in the following cases:
  *  - Workflow with the same Workflow Id is currently running
@@ -39,6 +41,21 @@ export class WorkflowExecutionAlreadyStartedError extends TemporalFailure {
   constructor(message: string, public readonly workflowId: string, public readonly workflowType: string) {
     super(message);
   }
+
+  /**
+   * Marker to determine whether an error is an instance of WorkflowExecutionAlreadyStartedError.
+   */
+  protected readonly [isWorkflowExecutionAlreadyStartedError] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/common are installed.
+   */
+  static is(error: unknown): error is WorkflowExecutionAlreadyStartedError {
+    return (
+      error instanceof WorkflowExecutionAlreadyStartedError ||
+      (error instanceof Error && (error as any)[isWorkflowExecutionAlreadyStartedError])
+    );
+  }
 }
 
 /**
@@ -55,3 +72,14 @@ export class WorkflowNotFoundError extends Error {
     super(message);
   }
 }
+
+/**
+ * Thrown when the specified namespace is not known to Temporal Server.
+ */
+export class NamespaceNotFoundError extends Error {
+  public readonly name: string = 'NamespaceNotFoundError';
+
+  constructor(public readonly namespace: string) {
+    super(`Namespace not found: '${namespace}'`);
+  }
+}

package/src/failure.ts

@@ -35,6 +35,8 @@ checkExtends<RetryState, temporal.api.enums.v1.RetryState>();
 
 export type WorkflowExecution = temporal.api.common.v1.IWorkflowExecution;
 
+const isTemporalFailure = Symbol.for('__temporal_isTemporalFailure');
+
 /**
  * Represents failures that can cross Workflow and Activity boundaries.
  *
@@ -54,8 +56,22 @@ export class TemporalFailure extends Error {
   constructor(message?: string | undefined | null, public readonly cause?: Error) {
     super(message ?? undefined);
   }
+
+  /**
+   * Marker to determine whether an error is an instance of TemporalFailure.
+   */
+  protected readonly [isTemporalFailure] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/common are installed.
+   */
+  static is(error: unknown): error is TemporalFailure {
+    return error instanceof TemporalFailure || (error as any)?.[isTemporalFailure] === true;
+  }
 }
 
+const isServerFailure = Symbol.for('__temporal_isServerFailure');
+
 /** Exceptions originated at the Temporal service. */
 export class ServerFailure extends TemporalFailure {
   public readonly name: string = 'ServerFailure';
@@ -63,8 +79,22 @@ export class ServerFailure extends TemporalFailure {
   constructor(message: string | undefined, public readonly nonRetryable: boolean, cause?: Error) {
     super(message, cause);
   }
+
+  /**
+   * Marker to determine whether an error is an instance of ServerFailure.
+   */
+  protected readonly [isServerFailure] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/common are installed.
+   */
+  static is(error: unknown): error is ServerFailure {
+    return error instanceof ServerFailure || (error as any)?.[isServerFailure] === true;
+  }
 }
 
+const isApplicationFailure = Symbol.for('__temporal_isApplicationFailure');
+
 /**
  * `ApplicationFailure`s are used to communicate application-specific failures in Workflows and Activities.
  *
@@ -103,6 +133,18 @@ export class ApplicationFailure extends TemporalFailure {
     super(message, cause);
   }
 
+  /**
+   * Marker to determine whether an error is an instance of ApplicationFailure.
+   */
+  protected readonly [isApplicationFailure] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/common are installed.
+   */
+  static is(error: unknown): error is ApplicationFailure {
+    return error instanceof ApplicationFailure || (error as any)?.[isApplicationFailure] === true;
+  }
+
   /**
    * Create a new `ApplicationFailure` from an Error object.
    *
@@ -181,6 +223,8 @@ export interface ApplicationFailureOptions {
   cause?: Error;
 }
 
+const isCancelledFailure = Symbol.for('__temporal_isCancelledFailure');
+
 /**
  * This error is thrown when Cancellation has been requested. To allow Cancellation to happen, let it propagate. To
  * ignore Cancellation, catch it and continue executing. Note that Cancellation can only be requested a single time, so
@@ -194,8 +238,22 @@ export class CancelledFailure extends TemporalFailure {
   constructor(message: string | undefined, public readonly details: unknown[] = [], cause?: Error) {
     super(message, cause);
   }
+
+  /**
+   * Marker to determine whether an error is an instance of CancelledFailure.
+   */
+  protected readonly [isCancelledFailure] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/common are installed.
+   */
+  static is(error: unknown): error is CancelledFailure {
+    return error instanceof CancelledFailure || (error as any)?.[isCancelledFailure] === true;
+  }
 }
 
+const isTerminatedFailure = Symbol.for('__temporal_isTerminatedFailure');
+
 /**
  * Used as the `cause` when a Workflow has been terminated
  */
@@ -205,8 +263,22 @@ export class TerminatedFailure extends TemporalFailure {
   constructor(message: string | undefined, cause?: Error) {
     super(message, cause);
   }
+
+  /**
+   * Marker to determine whether an error is an instance of TerminatedFailure.
+   */
+  protected readonly [isTerminatedFailure] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/common are installed.
+   */
+  static is(error: unknown): error is TerminatedFailure {
+    return error instanceof TerminatedFailure || (error as any)?.[isTerminatedFailure] === true;
+  }
 }
 
+const isTimeoutFailure = Symbol.for('__temporal_isTimeoutFailure');
+
 /**
  * Used to represent timeouts of Activities and Workflows
  */
@@ -220,8 +292,22 @@ export class TimeoutFailure extends TemporalFailure {
   ) {
     super(message);
   }
+
+  /**
+   * Marker to determine whether an error is an instance of TimeoutFailure.
+   */
+  protected readonly [isTimeoutFailure] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/common are installed.
+   */
+  static is(error: unknown): error is TimeoutFailure {
+    return error instanceof TimeoutFailure || (error as any)?.[isTimeoutFailure] === true;
+  }
 }
 
+const isActivityFailure = Symbol.for('__temporal_isActivityFailure');
+
 /**
  * Contains information about an Activity failure. Always contains the original reason for the failure as its `cause`.
  * For example, if an Activity timed out, the cause will be a {@link TimeoutFailure}.
@@ -241,8 +327,22 @@ export class ActivityFailure extends TemporalFailure {
   ) {
     super(message, cause);
   }
+
+  /**
+   * Marker to determine whether an error is an instance of ActivityFailure.
+   */
+  protected readonly [isActivityFailure] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/common are installed.
+   */
+  static is(error: unknown): error is ActivityFailure {
+    return error instanceof ActivityFailure || (error as any)?.[isActivityFailure] === true;
+  }
 }
 
+const isChildWorkflowFailure = Symbol.for('__temporal_isChildWorkflowFailure');
+
 /**
  * Contains information about a Child Workflow failure. Always contains the reason for the failure as its {@link cause}.
  * For example, if the Child was Terminated, the `cause` is a {@link TerminatedFailure}.
@@ -261,6 +361,18 @@ export class ChildWorkflowFailure extends TemporalFailure {
   ) {
     super('Child Workflow execution failed', cause);
   }
+
+  /**
+   * Marker to determine whether an error is an instance of ChildWorkflowFailure.
+   */
+  protected readonly [isChildWorkflowFailure] = true;
+
+  /**
+   * Instanceof check that works when multiple versions of @temporalio/common are installed.
+   */
+  static is(error: unknown): error is ChildWorkflowFailure {
+    return error instanceof ChildWorkflowFailure || (error as any)?.[isChildWorkflowFailure] === true;
+  }
 }
 
 /**
@@ -273,7 +385,7 @@ export class ChildWorkflowFailure extends TemporalFailure {
  * - `stack`: `error.stack` or `''`
  */
 export function ensureApplicationFailure(error: unknown): ApplicationFailure {
-  if (error instanceof ApplicationFailure) {
+  if (ApplicationFailure.is(error)) {
     return error;
   }
 
@@ -292,7 +404,7 @@ export function ensureApplicationFailure(error: unknown): ApplicationFailure {
  * Otherwise returns an `ApplicationFailure` with `String(err)` as the message.
  */
 export function ensureTemporalFailure(err: unknown): TemporalFailure {
-  if (err instanceof TemporalFailure) {
+  if (TemporalFailure.is(err)) {
     return err;
   }
   return ensureApplicationFailure(err);
@@ -305,7 +417,7 @@ export function ensureTemporalFailure(err: unknown): TemporalFailure {
  * Otherwise, return `error.message`.
  */
 export function rootCause(error: unknown): string | undefined {
-  if (error instanceof TemporalFailure) {
+  if (TemporalFailure.is(error)) {
     return error.cause ? rootCause(error.cause) : error.message;
   }
   if (error instanceof Error) {

package/src/index.ts

@@ -18,10 +18,12 @@ export * from './errors';
 export * from './failure';
 export { Headers, Next } from './interceptors';
 export * from './interfaces';
+export * from './logger';
 export * from './retry-policy';
-export { Timestamp } from './time';
+export { type Timestamp, Duration, StringValue } from './time';
 export * from './workflow-handle';
 export * from './workflow-options';
+export * from './versioning-intent';
 
 /**
  * Encode a UTF-8 string into a Uint8Array

package/src/logger.ts

@@ -0,0 +1,15 @@
+export type LogLevel = 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+
+export type LogMetadata = Record<string | symbol, any>;
+
+/**
+ * Implement this interface in order to customize worker logging
+ */
+export interface Logger {
+  log(level: LogLevel, message: string, meta?: LogMetadata): any;
+  trace(message: string, meta?: LogMetadata): any;
+  debug(message: string, meta?: LogMetadata): any;
+  info(message: string, meta?: LogMetadata): any;
+  warn(message: string, meta?: LogMetadata): any;
+  error(message: string, meta?: LogMetadata): any;
+}

package/src/retry-policy.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.

package/src/time.ts

@@ -1,6 +1,6 @@
 // eslint-disable-next-line import/no-named-as-default
 import Long from 'long';
-import ms from 'ms';
+import ms, { StringValue } from 'ms';
 import type { google } from '@temporalio/proto';
 import { ValueError } from './errors';
 
@@ -11,6 +11,13 @@ import { ValueError } from './errors';
 
 export type Timestamp = google.protobuf.ITimestamp;
 
+/**
+ * A duration, expressed either as a number of milliseconds, or as a {@link https://www.npmjs.com/package/ms | ms-formatted string}.
+ */
+export type Duration = StringValue | number;
+
+export type { StringValue } from 'ms';
+
 /**
  * Lossy conversion function from Timestamp to number due to possible overflow.
  * If ts is null or undefined returns undefined.
@@ -45,27 +52,32 @@ export function msNumberToTs(millis: number): Timestamp {
   return { seconds: Long.fromNumber(seconds), nanos };
 }
 
-export function msToTs(str: string | number): Timestamp {
-  if (typeof str === 'number') {
-    return msNumberToTs(str);
-  }
-  return msNumberToTs(ms(str));
+export function msToTs(str: Duration): Timestamp {
+  return msNumberToTs(msToNumber(str));
 }
 
-export function msOptionalToTs(str: string | number | undefined): Timestamp | undefined {
+export function msOptionalToTs(str: Duration | undefined): Timestamp | undefined {
   return str ? msToTs(str) : undefined;
 }
 
-export function msOptionalToNumber(val: string | number | undefined): number | undefined {
+export function msOptionalToNumber(val: Duration | undefined): number | undefined {
   if (val === undefined) return undefined;
   return msToNumber(val);
 }
 
-export function msToNumber(val: string | number): number {
+export function msToNumber(val: Duration): number {
   if (typeof val === 'number') {
     return val;
   }
-  return ms(val);
+  return msWithValidation(val);
+}
+
+function msWithValidation(str: StringValue): number {
+  const millis = ms(str);
+  if (millis == null || isNaN(millis)) {
+    throw new TypeError(`Invalid duration string: '${str}'`);
+  }
+  return millis;
 }
 
 export function tsToDate(ts: Timestamp): Date {