-
-
Notifications
You must be signed in to change notification settings - Fork 988
chore(docs): cover maxDelay debounce option #2985
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.
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
base: main
Are you sure you want to change the base?
Conversation
|
WalkthroughThe pull request adds and expands documentation for a new optional Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
65e08f1 to
d27396d
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/triggering.mdx (1)
867-893:⚠️ Potential issue | 🟡 MinorClarify
maxDelayduration format and minimum supported value.The new option doesn’t state the accepted units or minimum value, and debounce durations don’t support milliseconds. Consider adding a brief note that
maxDelayuses the same duration format asdelay(w/d/hr/h/m/s) and is limited to ≥1s to avoid “500ms” confusion.Based on learnings: “In the debounce system … millisecond delays are not supported. The minimum debounce delay is 1 second (1s). The parseNaturalLanguageDuration function supports w/d/hr/h/m/s units only.”✍️ Suggested doc tweak
- - `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute + - `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute (duration string; units w/d/hr/h/m/s; minimum 1s)
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/triggering.mdx
🧰 Additional context used
🧠 Learnings (14)
📓 Common learnings
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Set default maximum duration in trigger.config.ts using `maxDuration` property
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Limit task duration using the `maxDuration` property (in seconds)
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Set default maximum duration in trigger.config.ts using `maxDuration` property
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Limit task duration using the `maxDuration` property (in seconds)
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `idempotencyKeyTTL` option to define a time window during which duplicate triggers return the original run
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-12-18T14:09:10.154Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 2794
File: internal-packages/run-engine/src/engine/systems/debounceSystem.ts:390-397
Timestamp: 2025-12-18T14:09:10.154Z
Learning: In the debounce system (internal-packages/run-engine/src/engine/systems/debounceSystem.ts), millisecond delays are not supported. The minimum debounce delay is 1 second (1s). The parseNaturalLanguageDuration function supports w/d/hr/h/m/s units only.
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.triggerAndWait()` to batch trigger multiple different tasks and wait for results
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use the `task()` function from `trigger.dev/sdk/v3` to define tasks with id and run properties
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.triggerByTaskAndWait()` to batch trigger tasks by passing task instances and wait for results
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Configure task retry behavior using the `retry` property with options like maxAttempts, factor, and timeout values
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `tasks.batchTrigger()` to trigger multiple runs of a single task with different payloads
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Control concurrency using the `queue` property with `concurrencyLimit` option
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `runs.subscribeToBatch()` to subscribe to changes for all runs in a batch
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Scope idempotency keys globally or to current run using the scope parameter
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Subscribe to run updates using `runs.subscribeToRun()` for realtime monitoring of task execution
Applied to files:
docs/triggering.mdx
🪛 Gitleaks (8.30.0)
docs/triggering.mdx
[high] 890-890: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
d27396d to
c79e958
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/triggering.mdx`:
- Around line 869-873: Update the docs for the maxDelay field to state the same
unit/minimum constraints as delay: it uses the same duration format as delay
(supported units: w, d, hr/h, m, s), millisecond values are not supported, and
the minimum allowed value is 1s; reference the debounce parser implementation
(parseNaturalLanguageDuration in debounceSystem.ts) to ensure wording matches
its behavior and mention both `delay` and `maxDelay` by name so readers know
both fields share these constraints.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/triggering.mdx
🧰 Additional context used
🧠 Learnings (12)
📓 Common learnings
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Set default maximum duration in trigger.config.ts using `maxDuration` property
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Limit task duration using the `maxDuration` property (in seconds)
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 2794
File: internal-packages/run-engine/src/engine/systems/debounceSystem.ts:390-397
Timestamp: 2025-12-18T14:09:10.154Z
Learning: In the debounce system (internal-packages/run-engine/src/engine/systems/debounceSystem.ts), millisecond delays are not supported. The minimum debounce delay is 1 second (1s). The parseNaturalLanguageDuration function supports w/d/hr/h/m/s units only.
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Set default maximum duration in trigger.config.ts using `maxDuration` property
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-12-18T14:09:10.154Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 2794
File: internal-packages/run-engine/src/engine/systems/debounceSystem.ts:390-397
Timestamp: 2025-12-18T14:09:10.154Z
Learning: In the debounce system (internal-packages/run-engine/src/engine/systems/debounceSystem.ts), millisecond delays are not supported. The minimum debounce delay is 1 second (1s). The parseNaturalLanguageDuration function supports w/d/hr/h/m/s units only.
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Limit task duration using the `maxDuration` property (in seconds)
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `idempotencyKeyTTL` option to define a time window during which duplicate triggers return the original run
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Configure task retry behavior using the `retry` property with options like maxAttempts, factor, and timeout values
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Control concurrency using the `queue` property with `concurrencyLimit` option
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.triggerAndWait()` to batch trigger multiple different tasks and wait for results
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `runs.subscribeToBatch()` to subscribe to changes for all runs in a batch
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Scope idempotency keys globally or to current run using the scope parameter
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Subscribe to run updates using `runs.subscribeToRun()` for realtime monitoring of task execution
Applied to files:
docs/triggering.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `tasks.batchTrigger()` to trigger multiple runs of a single task with different payloads
Applied to files:
docs/triggering.mdx
🪛 Gitleaks (8.30.0)
docs/triggering.mdx
[high] 890-890: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🔇 Additional comments (1)
docs/triggering.mdx (1)
881-925: SolidmaxDelaywalkthrough and timeline.The example, table, and note make the behavior easy to reason about.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
| - `key` - A unique string to identify the debounce group (scoped to the task) | ||
| - `delay` - Duration string specifying how long to delay (e.g., "5s", "1m", "30s") | ||
| - `delay` - Duration string specifying how long to delay. Supported units: `s` (seconds), `m` (minutes), `h`/`hr` (hours), `d` (days), `w` (weeks). Minimum is 1 second. Examples: `"5s"`, `"1m"`, `"2h30m"` | ||
| - `mode` - Optional. Controls which trigger's data is used: `"leading"` (default) or `"trailing"` | ||
| - `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute. Uses the same duration format as `delay` | ||
|
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Clarify maxDelay minimum/units to match debounce parser constraints.
Line 872 mentions the format but doesn’t call out the min 1s / unit limits, which can lead to unsupported values (e.g., ms). Consider adding the same constraints as delay.
📝 Suggested wording
- - `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute. Uses the same duration format as `delay`
+ - `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute. Uses the same duration format as `delay` (min 1s; units `s`, `m`, `h`/`hr`, `d`, `w`)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - `key` - A unique string to identify the debounce group (scoped to the task) | |
| - `delay` - Duration string specifying how long to delay (e.g., "5s", "1m", "30s") | |
| - `delay` - Duration string specifying how long to delay. Supported units: `s` (seconds), `m` (minutes), `h`/`hr` (hours), `d` (days), `w` (weeks). Minimum is 1 second. Examples: `"5s"`, `"1m"`, `"2h30m"` | |
| - `mode` - Optional. Controls which trigger's data is used: `"leading"` (default) or `"trailing"` | |
| - `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute. Uses the same duration format as `delay` | |
| - `key` - A unique string to identify the debounce group (scoped to the task) | |
| - `delay` - Duration string specifying how long to delay. Supported units: `s` (seconds), `m` (minutes), `h`/`hr` (hours), `d` (days), `w` (weeks). Minimum is 1 second. Examples: `"5s"`, `"1m"`, `"2h30m"` | |
| - `mode` - Optional. Controls which trigger's data is used: `"leading"` (default) or `"trailing"` | |
| - `maxDelay` - Optional. Maximum total time from the first trigger before the run must execute. Uses the same duration format as `delay` (min 1s; units `s`, `m`, `h`/`hr`, `d`, `w`) |
🤖 Prompt for AI Agents
In `@docs/triggering.mdx` around lines 869 - 873, Update the docs for the maxDelay
field to state the same unit/minimum constraints as delay: it uses the same
duration format as delay (supported units: w, d, hr/h, m, s), millisecond values
are not supported, and the minimum allowed value is 1s; reference the debounce
parser implementation (parseNaturalLanguageDuration in debounceSystem.ts) to
ensure wording matches its behavior and mention both `delay` and `maxDelay` by
name so readers know both fields share these constraints.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 3. Once no new triggers occur within the delay duration, the run executes | ||
| 4. After the run starts executing, a new trigger with the same key will create a new run | ||
|
|
||
| **Limiting total delay with `maxDelay`:** | ||
|
|
||
| By default, continuous triggers can delay execution indefinitely. The `maxDelay` option sets an upper bound on the total delay from the first trigger, ensuring the run eventually executes even with constant activity. | ||
|
|
||
| ```ts | ||
| await summarizeChat.trigger( | ||
| { conversationId: "123" }, | ||
| { | ||
| debounce: { | ||
| key: "conversation-123", | ||
| delay: "10s", // Wait 10s after each message | ||
| maxDelay: "5m", // But always run within 5 minutes of first trigger | ||
| }, | ||
| } | ||
| ); | ||
| ``` | ||
|
|
||
| This is useful for scenarios like: | ||
|
|
||
| - Summarizing AI chat threads that need periodic updates even during active conversations | ||
| - Syncing data that should happen regularly despite continuous changes | ||
| - Any case where you want debouncing but also guarantee timely execution | ||
|
|
||
| **Timeline example with `maxDelay`:** | ||
|
|
||
| Consider `delay: "5s"` and `maxDelay: "30s"` with triggers arriving every 2 seconds: | ||
|
|
||
| | Time | Event | Result | | ||
| | :--- | :--- | :--- | | ||
| | 0s | Trigger 1 | Run A created, scheduled for 5s | | ||
| | 2s | Trigger 2 | Run A rescheduled to 7s | | ||
| | 4s | Trigger 3 | Run A rescheduled to 9s | | ||
| | ... | ... | ... | | ||
| | 26s | Trigger 14 | Run A rescheduled to 31s | | ||
| | 28s | Trigger 15 | Would reschedule to 33s, but exceeds maxDelay (30s). Run A executes, Run B created | | ||
| | 30s | Trigger 16 | Run B rescheduled to 35s | | ||
|
|
||
| Without `maxDelay`, continuous triggers would prevent the run from ever executing. With `maxDelay: "30s"`, execution is guaranteed within 30 seconds of the first trigger. | ||
|
|
||
| <Note> | ||
| The `maxDelay` value is evaluated from each trigger call, not stored with the original run. This | ||
| means if you pass different `maxDelay` values for the same debounce key, each trigger uses its own | ||
| `maxDelay` to check against the original run's creation time. For consistent behavior, use the | ||
| same `maxDelay` value for all triggers with the same debounce key. | ||
| </Note> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🔴 Documentation describes non-existent maxDelay debounce option
The documentation adds extensive coverage of a maxDelay option for debounce that does not exist in the SDK or API.
Click to expand
Analysis
The PR adds documentation for maxDelay as a user-configurable option in the debounce settings (lines 872, 881-925). However, examining the actual implementation:
- SDK Types (
packages/core/src/v3/types/tasks.ts:922-948): Thedebounceoption only acceptskey,delay, andmode- nomaxDelay:
debounce?: {
key: string;
delay: string;
mode?: "leading" | "trailing";
};- API Schema (
packages/core/src/v3/schemas/api.ts:216-222): The Zod schema also only validateskey,delay, andmode:
debounce: z.object({
key: z.string().max(512),
delay: z.string(),
mode: z.enum(["leading", "trailing"]).optional(),
}).optional()- Server-side Implementation (
internal-packages/run-engine/src/engine/systems/debounceSystem.ts:16-31): TheDebounceOptionstype has nomaxDelayfield.
The maxDebounceDurationMs that exists in the codebase is a server-side configuration set via environment variable (RUN_ENGINE_MAXIMUM_DEBOUNCE_DURATION_MS), not a per-trigger option.
Impact
Users reading this documentation would attempt to use maxDelay in their trigger calls:
await myTask.trigger(payload, {
debounce: {
key: "my-key",
delay: "10s",
maxDelay: "5m", // This will be silently ignored!
}
});Since the property isn't in the schema, it would be silently ignored, leading to unexpected behavior where the max delay feature doesn't work as documented.
(Refers to lines 872-925)
Was this helpful? React with 👍 or 👎 to provide feedback.
Uh oh!
There was an error while loading. Please reload this page.