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

[ericallam]

Summary

Adds a maxDelay option to the debounce feature that limits the maximum total time a debounced run can be delayed, regardless of how many subsequent triggers occur.

Linear issue: TRI-7234

Problem

With the current debounce implementation, continuous triggers can delay execution indefinitely. Each new trigger resets the delay window, meaning a run might never execute if triggers keep coming.

Example scenario: An AI chat application wants to summarize conversation threads. Messages come in frequently, and each message triggers a summarization task with debounce. Without maxDelay, the summary might never run if users keep chatting.

Solution

The new maxDelay option sets an upper bound on how long a debounced run can be delayed from its initial trigger time.

await summarizeConversation.trigger(payload, {
  debounce: {
    key: `conversation-${conversationId}`,
    delay: "10s",      // Wait 10s after each message before summarizing
    maxDelay: "5m",    // But always summarize within 5 minutes of first trigger
  },
});

How it works

Timeline example

Consider delay: "5s" and maxDelay: "30s" with messages arriving every 2 seconds:

Time    Event                           Run Status
─────────────────────────────────────────────────────────────
0s      Message 1 → trigger()           Run A created, delayed until 5s
2s      Message 2 → trigger()           Run A rescheduled to 7s
4s      Message 3 → trigger()           Run A rescheduled to 9s
6s      Message 4 → trigger()           Run A rescheduled to 11s
...
26s     Message 14 → trigger()          Run A rescheduled to 31s
28s     Message 15 → trigger()          ⚠️ Would reschedule to 33s, but that
                                        exceeds maxDelay (0s + 30s = 30s)
                                        → Run A executes, Run B created
30s     Message 16 → trigger()          Run B rescheduled to 35s
...

Behavior

• When newDelayUntil > runCreatedAt + maxDelay, the system returns max_duration_exceeded
• This allows the existing run to execute and creates a new run for subsequent triggers
• If maxDelay is not specified, falls back to the server's global config (default: 1 hour)

Test plan

• New unit tests for maxDelay behavior pass
• Manual testing with hello-world reference project confirms maxDelay creates new runs at the expected time
• Existing debounce tests continue to pass (backward compatible)

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 2576a8e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 28 packages

Name	Type
@trigger.dev/core	Patch
@trigger.dev/sdk	Patch
@trigger.dev/build	Patch
trigger.dev	Patch
@trigger.dev/python	Patch
@trigger.dev/redis-worker	Patch
@trigger.dev/schema-to-json	Patch
@internal/cache	Patch
@internal/clickhouse	Patch
@internal/redis	Patch
@internal/replication	Patch
@internal/run-engine	Patch
@internal/schedule-engine	Patch
@internal/testcontainers	Patch
@internal/tracing	Patch
@internal/tsql	Patch
@internal/zod-worker	Patch
@internal/sdk-compat-tests	Patch
d3-chat	Patch
references-d3-openai-agents	Patch
references-nextjs-realtime	Patch
references-realtime-hooks-test	Patch
references-realtime-streams	Patch
references-telemetry	Patch
@trigger.dev/react-hooks	Patch
@trigger.dev/rsc	Patch
@trigger.dev/database	Patch
@trigger.dev/otlp-importer	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Walkthrough

This pull request adds a per-trigger maxDelay option to debounce configurations, updating type definitions and API schemas to include maxDelay?: string. It refactors duration parsing by introducing parseNaturalLanguageDurationInMs, updates the debounce system to use a computed per-trigger max duration with fallback to the global maxDebounceDurationMs, and adds tests validating per-trigger override, fallback to global config, and long maxDelay behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding a maxDelay option to the debounce feature to limit total debounce time.
Description check	✅ Passed	The PR description is comprehensive, well-structured, and covers all required sections with clear examples and test documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/debounce-max-delay

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional flags.