Allow specifying milliseconds to sleep() (#165)

Signed-off-by: David Khourshid <[email protected]>

Author: davidkpiano

.changeset/sixty-baboons-wonder.md

@@ -0,0 +1,5 @@
+---
+"@workflow/core": patch
+---
+
+Add support for specifying milliseconds in `sleep()`

packages/core/e2e/e2e.test.ts

@@ -27,7 +27,9 @@ async function triggerWorkflow(
   });
   if (!res.ok) {
     throw new Error(
-      `Failed to trigger workflow: ${res.url} ${res.status}: ${await res.text()}`
+      `Failed to trigger workflow: ${res.url} ${
+        res.status
+      }: ${await res.text()}`
     );
   }
   const run = await res.json();

packages/core/src/sleep.ts

@@ -24,7 +24,18 @@ export async function sleep(duration: StringValue): Promise<void>;
  */
 export async function sleep(date: Date): Promise<void>;
 
-export async function sleep(param: StringValue | Date): Promise<void> {
+/**
+ * Sleep within a workflow for a given duration in milliseconds.
+ *
+ * This is a built-in runtime function that uses timer events in the event log.
+ *
+ * @param durationMs - The duration to sleep for in milliseconds.
+ * @overload
+ * @returns A promise that resolves when the sleep is complete.
+ */
+export async function sleep(durationMs: number): Promise<void>;
+
+export async function sleep(param: StringValue | Date | number): Promise<void> {
   // Inside the workflow VM, the sleep function is stored in the globalThis object behind a symbol
   const sleepFn = (globalThis as any)[WORKFLOW_SLEEP];
   if (!sleepFn) {

packages/core/src/util.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest';
-import { buildWorkflowSuspensionMessage, getWorkflowRunStreamId } from './util';
+import {
+  buildWorkflowSuspensionMessage,
+  getWorkflowRunStreamId,
+  parseDurationToDate,
+} from './util';
 
 describe('buildWorkflowSuspensionMessage', () => {
   const runId = 'test-run-123';
@@ -165,3 +169,174 @@ describe('getWorkflowRunStreamId', () => {
     expect(result.includes('_user')).toBe(true);
   });
 });
+
+describe('parseDurationToDate', () => {
+  describe('string durations', () => {
+    it('should parse seconds', () => {
+      const before = Date.now();
+      const result = parseDurationToDate('5s');
+      const after = Date.now();
+      expect(result.getTime()).toBeGreaterThanOrEqual(before + 5000);
+      expect(result.getTime()).toBeLessThanOrEqual(after + 5000);
+    });
+
+    it('should parse minutes', () => {
+      const before = Date.now();
+      const result = parseDurationToDate('2m');
+      const after = Date.now();
+      const expected = before + 120000;
+      expect(result.getTime()).toBeGreaterThanOrEqual(expected);
+      expect(result.getTime()).toBeLessThanOrEqual(after + 120000);
+    });
+
+    it('should parse hours', () => {
+      const before = Date.now();
+      const result = parseDurationToDate('1h');
+      const after = Date.now();
+      const expected = before + 3600000;
+      expect(result.getTime()).toBeGreaterThanOrEqual(expected);
+      expect(result.getTime()).toBeLessThanOrEqual(after + 3600000);
+    });
+
+    it('should parse days', () => {
+      const before = Date.now();
+      const result = parseDurationToDate('1d');
+      const after = Date.now();
+      const expected = before + 86400000;
+      expect(result.getTime()).toBeGreaterThanOrEqual(expected);
+      expect(result.getTime()).toBeLessThanOrEqual(after + 86400000);
+    });
+
+    it('should parse milliseconds', () => {
+      const before = Date.now();
+      const result = parseDurationToDate('500ms');
+      const after = Date.now();
+      const expected = before + 500;
+      expect(result.getTime()).toBeGreaterThanOrEqual(expected);
+      expect(result.getTime()).toBeLessThanOrEqual(after + 500);
+    });
+
+    it('should throw error for invalid string', () => {
+      expect(() =>
+        parseDurationToDate(
+          // @ts-expect-error
+          'invalid'
+        )
+      ).toThrow(
+        'Invalid duration: "invalid". Expected a valid duration string like "1s", "1m", "1h", etc.'
+      );
+    });
+
+    it('should throw error for negative duration string', () => {
+      expect(() => parseDurationToDate('-1s')).toThrow(
+        'Invalid duration: "-1s". Expected a valid duration string like "1s", "1m", "1h", etc.'
+      );
+    });
+  });
+
+  describe('number durations (milliseconds)', () => {
+    it('should parse zero milliseconds', () => {
+      const before = Date.now();
+      const result = parseDurationToDate(0);
+      const after = Date.now();
+      expect(result.getTime()).toBeGreaterThanOrEqual(before);
+      expect(result.getTime()).toBeLessThanOrEqual(after);
+    });
+
+    it('should parse positive milliseconds', () => {
+      const before = Date.now();
+      const result = parseDurationToDate(10000);
+      const after = Date.now();
+      const expected = before + 10000;
+      expect(result.getTime()).toBeGreaterThanOrEqual(expected);
+      expect(result.getTime()).toBeLessThanOrEqual(after + 10000);
+    });
+
+    it('should parse large milliseconds', () => {
+      const before = Date.now();
+      const result = parseDurationToDate(1000000);
+      const after = Date.now();
+      const expected = before + 1000000;
+      expect(result.getTime()).toBeGreaterThanOrEqual(expected);
+      expect(result.getTime()).toBeLessThanOrEqual(after + 1000000);
+    });
+
+    it('should throw error for negative number', () => {
+      expect(() => parseDurationToDate(-1000)).toThrow(
+        'Invalid duration: -1000. Expected a non-negative finite number of milliseconds.'
+      );
+    });
+
+    it('should throw error for NaN', () => {
+      expect(() => parseDurationToDate(NaN)).toThrow(
+        'Invalid duration: NaN. Expected a non-negative finite number of milliseconds.'
+      );
+    });
+
+    it('should throw error for Infinity', () => {
+      expect(() => parseDurationToDate(Infinity)).toThrow(
+        'Invalid duration: Infinity. Expected a non-negative finite number of milliseconds.'
+      );
+    });
+
+    it('should throw error for -Infinity', () => {
+      expect(() => parseDurationToDate(-Infinity)).toThrow(
+        'Invalid duration: -Infinity. Expected a non-negative finite number of milliseconds.'
+      );
+    });
+  });
+
+  describe('Date objects', () => {
+    it('should return Date instance directly', () => {
+      const targetTime = Date.now() + 60000;
+      const futureDate = new Date(targetTime);
+      const result = parseDurationToDate(futureDate);
+      expect(result).toBe(futureDate);
+      expect(result.getTime()).toBe(targetTime);
+    });
+
+    it('should handle past dates', () => {
+      const targetTime = Date.now() - 60000;
+      const pastDate = new Date(targetTime);
+      const result = parseDurationToDate(pastDate);
+      expect(result).toBe(pastDate);
+      expect(result.getTime()).toBe(targetTime);
+    });
+
+    it('should handle date-like objects from deserialization', () => {
+      const targetTime = Date.now() + 30000;
+      const dateLike = {
+        getTime: () => targetTime,
+      };
+      const result = parseDurationToDate(dateLike as any);
+      expect(result.getTime()).toBe(targetTime);
+      expect(result instanceof Date).toBe(true);
+    });
+  });
+
+  describe('invalid inputs', () => {
+    it('should throw error for null', () => {
+      expect(() => parseDurationToDate(null as any)).toThrow(
+        'Invalid duration parameter. Expected a duration string, number (milliseconds), or Date object.'
+      );
+    });
+
+    it('should throw error for undefined', () => {
+      expect(() => parseDurationToDate(undefined as any)).toThrow(
+        'Invalid duration parameter. Expected a duration string, number (milliseconds), or Date object.'
+      );
+    });
+
+    it('should throw error for boolean', () => {
+      expect(() => parseDurationToDate(true as any)).toThrow(
+        'Invalid duration parameter. Expected a duration string, number (milliseconds), or Date object.'
+      );
+    });
+
+    it('should throw error for object without getTime', () => {
+      expect(() => parseDurationToDate({} as any)).toThrow(
+        'Invalid duration parameter. Expected a duration string, number (milliseconds), or Date object.'
+      );
+    });
+  });
+});

packages/core/src/util.ts

@@ -1,3 +1,6 @@
+import type { StringValue } from 'ms';
+import ms from 'ms';
+
 export interface PromiseWithResolvers<T> {
   promise: Promise<T>;
   resolve: (value: T) => void;
@@ -104,3 +107,46 @@ export function getWorkflowRunStreamId(runId: string, namespace?: string) {
   );
   return `${streamId}_${encodedNamespace}`;
 }
+
+/**
+ * Parses a duration parameter (string, number, or Date) and returns a Date object
+ * representing when the duration should elapse.
+ *
+ * - For strings: Parses duration strings like "1s", "5m", "1h", etc. using the `ms` library
+ * - For numbers: Treats as milliseconds from now
+ * - For Date objects: Returns the date directly (handles both Date instances and date-like objects from deserialization)
+ *
+ * @param param - The duration parameter (StringValue, Date, or number of milliseconds)
+ * @returns A Date object representing when the duration should elapse
+ * @throws {Error} If the parameter is invalid or cannot be parsed
+ */
+export function parseDurationToDate(param: StringValue | Date | number): Date {
+  if (typeof param === 'string') {
+    const durationMs = ms(param);
+    if (typeof durationMs !== 'number' || durationMs < 0) {
+      throw new Error(
+        `Invalid duration: "${param}". Expected a valid duration string like "1s", "1m", "1h", etc.`
+      );
+    }
+    return new Date(Date.now() + durationMs);
+  } else if (typeof param === 'number') {
+    if (param < 0 || !Number.isFinite(param)) {
+      throw new Error(
+        `Invalid duration: ${param}. Expected a non-negative finite number of milliseconds.`
+      );
+    }
+    return new Date(Date.now() + param);
+  } else if (
+    param instanceof Date ||
+    (param &&
+      typeof param === 'object' &&
+      typeof (param as any).getTime === 'function')
+  ) {
+    // Handle both Date instances and date-like objects (from deserialization)
+    return param instanceof Date ? param : new Date((param as any).getTime());
+  } else {
+    throw new Error(
+      `Invalid duration parameter. Expected a duration string, number (milliseconds), or Date object.`
+    );
+  }
+}

packages/core/src/workflow/sleep.ts

@@ -1,40 +1,18 @@
 import type { StringValue } from 'ms';
-import ms from 'ms';
 import { EventConsumerResult } from '../events-consumer.js';
 import { type WaitInvocationQueueItem, WorkflowSuspension } from '../global.js';
 import type { WorkflowOrchestratorContext } from '../private.js';
-import { withResolvers } from '../util.js';
+import { parseDurationToDate, withResolvers } from '../util.js';
 
 export function createSleep(ctx: WorkflowOrchestratorContext) {
-  return async function sleepImpl(param: StringValue | Date): Promise<void> {
+  return async function sleepImpl(
+    param: StringValue | Date | number
+  ): Promise<void> {
     const { promise, resolve } = withResolvers<void>();
     const correlationId = `wait_${ctx.generateUlid()}`;
 
     // Calculate the resume time
-    let resumeAt: Date;
-    if (typeof param === 'string') {
-      const durationMs = ms(param);
-      if (typeof durationMs !== 'number' || durationMs < 0) {
-        throw new Error(
-          `Invalid sleep duration: "${param}". Expected a valid duration string like "1s", "1m", "1h", etc.`
-        );
-      }
-      resumeAt = new Date(Date.now() + durationMs);
-    } else if (
-      param instanceof Date ||
-      (param &&
-        typeof param === 'object' &&
-        typeof (param as any).getTime === 'function')
-    ) {
-      // Handle both Date instances and date-like objects (from deserialization)
-      const dateParam =
-        param instanceof Date ? param : new Date((param as any).getTime());
-      resumeAt = dateParam;
-    } else {
-      throw new Error(
-        `Invalid sleep parameter. Expected a duration string or Date object.`
-      );
-    }
+    const resumeAt = parseDurationToDate(param);
 
     // Add wait to invocations queue
     ctx.invocationsQueue.push({

workbench/example/workflows/99_e2e.ts

@@ -205,6 +205,14 @@ export async function sleepingDateWorkflow(endDate: Date) {
   return { startTime, endTime };
 }
 
+export async function sleepingDurationMsWorkflow() {
+  'use workflow';
+  const startTime = Date.now();
+  await sleep(10000);
+  const endTime = Date.now();
+  return { startTime, endTime };
+}
+
 //////////////////////////////////////////////////////////
 
 async function nullByteStep() {