Skip to content

feat(debounce): add maxDelay option to limit total debounce time #2984

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ericallam merged 2 commits into from
Feb 2, 2026
Merged

feat(debounce): add maxDelay option to limit total debounce time #2984

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f072c96
feat(debounce): add maxDelay option to limit total debounce time
ericallam Feb 2, 2026
2576a8e
Add the maxDelay to the engine trigger types
ericallam Feb 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .changeset/add-debounce-maxdelay.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
"@trigger.dev/core": patch
"@trigger.dev/sdk": patch
---

Add `maxDelay` option to debounce feature. This allows setting a maximum time limit for how long a debounced run can be delayed, ensuring execution happens within a specified window even with continuous triggers.

```typescript
await myTask.trigger(payload, {
debounce: {
key: "my-key",
delay: "5s",
maxDelay: "30m", // Execute within 30 minutes regardless of continuous triggers
},
});
```
30 changes: 27 additions & 3 deletions internal-packages/run-engine/src/engine/systems/debounceSystem.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@ import {
type Result,
} from "@internal/redis";
import { startSpan } from "@internal/tracing";
import { parseNaturalLanguageDuration } from "@trigger.dev/core/v3/isomorphic";
import {
parseNaturalLanguageDuration,
parseNaturalLanguageDurationInMs,
} from "@trigger.dev/core/v3/isomorphic";
import { PrismaClientOrTransaction, TaskRun, Waitpoint } from "@trigger.dev/database";
import { nanoid } from "nanoid";
import { SystemResources } from "./systems.js";
Expand All @@ -17,6 +20,12 @@ export type DebounceOptions = {
key: string;
delay: string;
mode?: "leading" | "trailing";
/**
* Maximum total delay before the run must execute, regardless of subsequent triggers.
* This prevents indefinite delays when continuous triggers keep pushing the execution time.
* If not specified, falls back to the server's maxDebounceDurationMs config.
*/
maxDelay?: string;
/** When mode: "trailing", these fields will be used to update the existing run */
updateData?: {
payload: string;
Expand Down Expand Up @@ -521,8 +530,22 @@ return 0
}

// Check if max debounce duration would be exceeded
// Use per-trigger maxDelay if provided, otherwise use global config
let maxDurationMs = this.maxDebounceDurationMs;
if (debounce.maxDelay) {
const parsedMaxDelay = parseNaturalLanguageDurationInMs(debounce.maxDelay);
if (parsedMaxDelay !== undefined) {
maxDurationMs = parsedMaxDelay;
} else {
this.$.logger.warn("handleExistingRun: invalid maxDelay duration, using global config", {
maxDelay: debounce.maxDelay,
fallbackMs: this.maxDebounceDurationMs,
});
}
}

const runCreatedAt = existingRun.createdAt;
const maxDelayUntil = new Date(runCreatedAt.getTime() + this.maxDebounceDurationMs);
const maxDelayUntil = new Date(runCreatedAt.getTime() + maxDurationMs);

if (newDelayUntil > maxDelayUntil) {
this.$.logger.debug("handleExistingRun: max debounce duration would be exceeded", {
Expand All @@ -531,7 +554,8 @@ return 0
runCreatedAt,
newDelayUntil,
maxDelayUntil,
maxDebounceDurationMs: this.maxDebounceDurationMs,
maxDurationMs,
maxDelayProvided: debounce.maxDelay,
});
// Clean up Redis key since this debounce window is closed
await this.redis.del(redisKey);
Expand Down
Loading