Make duration strings type safe

Author: jamescmartinez

packages/openworkflow/client.ts

@@ -1,4 +1,5 @@
 import type { Backend, WorkflowRun } from "./backend.js";
+import { DurationString } from "./duration.js";
 import { Worker } from "./worker.js";
 
 const DEFAULT_RESULT_POLL_INTERVAL_MS = 1000; // 1s
@@ -170,7 +171,7 @@ export interface StepApi {
     config: StepFunctionConfig,
     fn: StepFunction<Output>,
   ): Promise<Output>;
-  sleep(name: string, duration: string): Promise<void>;
+  sleep(name: string, duration: DurationString): Promise<void>;
 }
 
 /**

packages/openworkflow/duration.test.ts

@@ -193,10 +193,15 @@ describe("parseDuration", () => {
     });
 
     test("parses case-insensitive long format", () => {
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
       expect(parseDuration("53 YeArS")).toBe(1_672_552_800_000);
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
       expect(parseDuration("53 WeEkS")).toBe(32_054_400_000);
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
       expect(parseDuration("53 DaYS")).toBe(4_579_200_000);
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
       expect(parseDuration("53 HoUrs")).toBe(190_800_000);
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
       expect(parseDuration("53 MiLliSeCondS")).toBe(53);
     });
   });
@@ -237,43 +242,55 @@ describe("parseDuration", () => {
 
   describe("error cases", () => {
     test("throws on invalid format", () => {
+      // @ts-expect-error - invalid format
       expect(() => parseDuration("invalid")).toThrow(
         'Invalid duration format: "invalid"',
       );
+      // @ts-expect-error - invalid format
       expect(() => parseDuration("10-.5")).toThrow(
         'Invalid duration format: "10-.5"',
       );
+      // @ts-expect-error - invalid format
       expect(() => parseDuration("foo")).toThrow(
         'Invalid duration format: "foo"',
       );
     });
 
     test("throws on empty string", () => {
+      // @ts-expect-error - empty string
       expect(() => parseDuration("")).toThrow('Invalid duration format: ""');
     });
 
     test("throws on missing number", () => {
+      // @ts-expect-error - unit without number
       expect(() => parseDuration("ms")).toThrow(
         'Invalid duration format: "ms"',
       );
+      // @ts-expect-error - unit without number
       expect(() => parseDuration("s")).toThrow('Invalid duration format: "s"');
+      // @ts-expect-error - unit without number
       expect(() => parseDuration("m")).toThrow('Invalid duration format: "m"');
+      // @ts-expect-error - unit without number
       expect(() => parseDuration("h")).toThrow('Invalid duration format: "h"');
     });
 
     test("throws on unknown unit", () => {
+      // @ts-expect-error - unknown unit
       expect(() => parseDuration("100x")).toThrow(
         'Invalid duration format: "100x"',
       );
+      // @ts-expect-error - unknown unit
       expect(() => parseDuration("5z")).toThrow(
         'Invalid duration format: "5z"',
       );
     });
 
     test("throws on multiple units", () => {
+      // @ts-expect-error - multiple units
       expect(() => parseDuration("1h30m")).toThrow(
         'Invalid duration format: "1h30m"',
       );
+      // @ts-expect-error - multiple units
       expect(() => parseDuration("5s100ms")).toThrow(
         'Invalid duration format: "5s100ms"',
       );
@@ -283,34 +300,44 @@ describe("parseDuration", () => {
       expect(() => parseDuration(" 5s")).toThrow(
         'Invalid duration format: " 5s"',
       );
+      // @ts-expect-error - trailing space
       expect(() => parseDuration("5s ")).toThrow(
         'Invalid duration format: "5s "',
       );
     });
 
     test("throws on special characters", () => {
+      // @ts-expect-error - special characters
       expect(() => parseDuration("5s!")).toThrow(
         'Invalid duration format: "5s!"',
       );
+      // @ts-expect-error - special characters
       expect(() => parseDuration("@5s")).toThrow(
         'Invalid duration format: "@5s"',
       );
     });
 
     test("throws on non-string types", () => {
+      // @ts-expect-error - non-string type
       expect(() => parseDuration(undefined as unknown as string)).toThrow(
         TypeError,
       );
+      // @ts-expect-error - non-string type
       expect(() => parseDuration(null as unknown as string)).toThrow(TypeError);
+      // @ts-expect-error - non-string type
       expect(() => parseDuration([] as unknown as string)).toThrow(TypeError);
+      // @ts-expect-error - non-string type
       expect(() => parseDuration({} as unknown as string)).toThrow(TypeError);
+      // @ts-expect-error - non-string type
       expect(() => parseDuration(Number.NaN as unknown as string)).toThrow(
         TypeError,
       );
       expect(() =>
+        // @ts-expect-error - non-string type
         parseDuration(Number.POSITIVE_INFINITY as unknown as string),
       ).toThrow(TypeError);
       expect(() =>
+        // @ts-expect-error - non-string type
         parseDuration(Number.NEGATIVE_INFINITY as unknown as string),
       ).toThrow(TypeError);
     });

packages/openworkflow/duration.ts

@@ -1,24 +1,46 @@
+type Years = "years" | "year" | "yrs" | "yr" | "y";
+type Months = "months" | "month" | "mo";
+type Weeks = "weeks" | "week" | "w";
+type Days = "days" | "day" | "d";
+type Hours = "hours" | "hour" | "hrs" | "hr" | "h";
+type Minutes = "minutes" | "minute" | "mins" | "min" | "m";
+type Seconds = "seconds" | "second" | "secs" | "sec" | "s";
+type Milliseconds = "milliseconds" | "millisecond" | "msecs" | "msec" | "ms";
+type Unit =
+  | Years
+  | Months
+  | Weeks
+  | Days
+  | Hours
+  | Minutes
+  | Seconds
+  | Milliseconds;
+type UnitAnyCase = Capitalize<Unit> | Uppercase<Unit> | Lowercase<Unit>;
+export type DurationString =
+  | `${number}`
+  | `${number}${UnitAnyCase}`
+  | `${number} ${UnitAnyCase}`;
+
 /**
  * Parse a duration string into milliseconds. Exmaples:
  * - short units: "1ms", "5s", "30m", "2h", "7d", "3w", "1y"
  * - long units: "1 millisecond", "5 seconds", "30 minutes", "2 hours", "7 days", "3 weeks", "1 year"
  */
-export function parseDuration(duration: string): number {
-  if (typeof duration !== "string") {
+export function parseDuration(str: DurationString): number {
+  if (typeof str !== "string") {
     throw new TypeError(
-      "Invalid duration format: expected a string but received " +
-        typeof duration,
+      "Invalid duration format: expected a string but received " + typeof str,
     );
   }
 
-  if (duration.length === 0) {
+  if (str.length === 0) {
     throw new Error('Invalid duration format: ""');
   }
 
-  const match = /^(-?\.?\d+(?:\.\d+)?)\s*([a-z]+)?$/i.exec(duration);
+  const match = /^(-?\.?\d+(?:\.\d+)?)\s*([a-z]+)?$/i.exec(str);
 
   if (!match?.[1]) {
-    throw new Error(`Invalid duration format: "${duration}"`);
+    throw new Error(`Invalid duration format: "${str}"`);
   }
 
   const numValue = Number.parseFloat(match[1]);
@@ -63,7 +85,7 @@ export function parseDuration(duration: string): number {
 
   const multiplier = multipliers[unit];
   if (multiplier === undefined) {
-    throw new Error(`Invalid duration format: "${duration}"`);
+    throw new Error(`Invalid duration format: "${str}"`);
   }
 
   return numValue * multiplier;

packages/openworkflow/worker.ts

@@ -10,7 +10,7 @@ import {
   StepFunctionConfig,
   WorkflowDefinition,
 } from "./client.js";
-import { parseDuration } from "./duration.js";
+import { DurationString, parseDuration } from "./duration.js";
 import { randomUUID } from "node:crypto";
 
 const DEFAULT_LEASE_DURATION_MS = 30 * 1000; // 30s
@@ -428,7 +428,7 @@ class StepExecutor implements StepApi {
     }
   }
 
-  async sleep(name: string, duration: string): Promise<void> {
+  async sleep(name: string, duration: DurationString): Promise<void> {
     // return cached result if this sleep already completed
     const existingAttempt = this.successfulAttemptsByName.get(name);
     if (existingAttempt) return;