better docs for options

Author: ericallam

internal-packages/run-engine/src/engine/tests/debounce.test.ts

@@ -480,7 +480,7 @@ describe("RunEngine debounce", () => {
 
         await setupBackgroundWorker(engine, authenticatedEnvironment, taskIdentifier);
 
-        // First trigger with 500ms delay
+        // First trigger with 1s delay
         const run = await engine.trigger(
           {
             number: 1,
@@ -497,10 +497,10 @@ describe("RunEngine debounce", () => {
             queue: "task/test-task",
             isTest: false,
             tags: [],
-            delayUntil: new Date(Date.now() + 500),
+            delayUntil: new Date(Date.now() + 1000),
             debounce: {
               key: "user-123",
-              delay: "500ms",
+              delay: "1s",
             },
           },
           prisma
@@ -512,7 +512,7 @@ describe("RunEngine debounce", () => {
         expect(executionData.snapshot.executionStatus).toBe("DELAYED");
 
         // Wait for delay to pass
-        await setTimeout(1000);
+        await setTimeout(1500);
 
         // Should now be QUEUED
         executionData = await engine.getRunExecutionData({ runId: run.id });

packages/core/src/v3/types/tasks.ts

@@ -920,13 +920,17 @@ export type TriggerOptions = {
   debounce?: {
     /**
      * Unique key scoped to the task identifier. Runs with the same key will be debounced together.
+     * Maximum length is 512 characters.
      */
     key: string;
     /**
      * Duration string specifying how long to delay the run. If another trigger with the same key
      * occurs within this duration, the delay is extended.
      *
-     * @example "5s", "1m", "30s"
+     * Supported formats: `{number}s` (seconds), `{number}m` (minutes), `{number}h` (hours),
+     * `{number}d` (days), `{number}w` (weeks). Minimum delay is 1 second.
+     *
+     * @example "1s", "5s", "1m", "30m", "1h"
      */
     delay: string;
   };

references/hello-world/src/trigger/debounce.ts

@@ -523,8 +523,8 @@ export const parentWithDebouncedChild = task({
 export const shortDebounce = task({
   id: "short-debounce",
   run: async (payload: { key: string }) => {
-    logger.info("Short debounce task (500ms)", { key: payload.key });
-    return { key: payload.key, delay: "500ms" };
+    logger.info("Short debounce task (1s)", { key: payload.key });
+    return { key: payload.key, delay: "1s" };
   },
 });
 
@@ -549,10 +549,10 @@ export const testDifferentDelays = task({
   run: async (payload: { key: string }) => {
     logger.info("Testing different debounce delays", { key: payload.key });
 
-    // 500ms debounce - good for rapid UI updates
+    // 1 second debounce - good for rapid UI updates
     await shortDebounce.trigger(
       { key: `${payload.key}-short` },
-      { debounce: { key: `${payload.key}-short`, delay: "500ms" } }
+      { debounce: { key: `${payload.key}-short`, delay: "1s" } }
     );
 
     // 5 second debounce - good for user input