chore(docs): Improvements to the idempotency key docs for the user expored itempotency key changes #2910
Conversation
…pored itempotency key changes
|
WalkthroughThis pull request updates the idempotency documentation file with significantly expanded content. The changes include a new explanatory section on why idempotency keys matter, a detailed treatment of how scoping works (with a table of available scopes: run, attempt, global), extended examples demonstrating scope-specific behavior, and a new section on how failed runs interact with idempotency. The documentation now includes a Mermaid sequence diagram, multiple code examples, a notes section on environment and task scoping, and clarifications about the breaking change in v4.3.1. No API signatures or exported entities were modified. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/idempotency.mdx (1)
64-66: Tighten wording and article usage in examples.Minor grammar tweaks improve readability.
✏️ Proposed text tweaks
-We automatically inject the run ID when generating the idempotency key when running inside a task by default. +We automatically inject the run ID when generating the idempotency key inside a task by default.-// You can also pass an array of strings to create a idempotency key +// You can also pass an array of strings to create an idempotency key-// You can also pass an array of strings to create a idempotency key +// You can also pass an array of strings to create an idempotency keyAlso applies to: 91-102
🤖 Fix all issues with AI agents
In `@docs/idempotency.mdx`:
- Line 247: Update the sentence that currently reads "When triggering tasks from
your backend code (outside of a task), there is no parent run context. In this
case, `\"run\"` and `\"attempt\"` scopes behave the same as `\"global\"` since
there's no run ID or attempt number to inject:" by removing the extra "of" and
using "outside a task" for tighter phrasing—i.e., change "outside of a task" to
"outside a task" while keeping the rest of the sentence and the quoted scopes
(`"run"`, `"attempt"`, `"global"`) unchanged.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/images/idempotency-key-dashboard.pngis excluded by!**/*.png
📒 Files selected for processing (1)
docs/idempotency.mdx
🧰 Additional context used
🧠 Learnings (18)
📓 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/**/*.{ts,tsx,js,jsx} : Use `idempotencyKeys.create()` to create idempotency keys for preventing duplicate task executions
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
📚 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/idempotency.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 `idempotencyKeys.create()` to create idempotency keys for preventing duplicate task executions
Applied to files:
docs/idempotency.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/idempotency.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/idempotency.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} : Export tasks with unique IDs within the project to enable proper task discovery and execution
Applied to files:
docs/idempotency.mdx
📚 Learning: 2026-01-15T11:50:06.044Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-15T11:50:06.044Z
Learning: Applies to **/*.{ts,tsx} : Every Trigger.dev task must be exported and have a unique `id` property with no timeouts in the run function
Applied to files:
docs/idempotency.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/idempotency.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 `yourTask.trigger()` to trigger a task from inside another task with specified payload
Applied to files:
docs/idempotency.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 `yourTask.batchTrigger()` to trigger multiple runs of a task from inside another task
Applied to files:
docs/idempotency.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} : Attach metadata to task runs using the metadata option when triggering, and access/update it inside runs using metadata functions
Applied to files:
docs/idempotency.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.trigger()` to trigger multiple different tasks at once from backend code
Applied to files:
docs/idempotency.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/idempotency.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.triggerByTask()` to batch trigger tasks by passing task instances for static task sets
Applied to files:
docs/idempotency.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/idempotency.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 `yourTask.batchTriggerAndWait()` to batch trigger tasks and wait for all results from a parent task
Applied to files:
docs/idempotency.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/idempotency.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/idempotency.mdx
🪛 LanguageTool
docs/idempotency.mdx
[style] ~247-~247: This phrase is redundant. Consider using “outside”.
Context: ...riggering tasks from your backend code (outside of a task), there is no parent run context...
(OUTSIDE_OF)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (6)
docs/idempotency.mdx (6)
6-7: Concise intro; please confirm the duplicate-return behavior wording.Reads well. Please double-check that the SDK returns the original run handle on duplicate idempotency keys (vs. another artifact) so the phrasing matches current behavior.
10-37: Diagram/use cases are strong; verify retry semantics.The narrative and diagram are clear. Please sanity‑check that the retry + idempotency behavior shown matches current SDK behavior.
124-218: Scopes section is clear; confirm hashing inputs and defaults.Great structure and examples. Please verify the hashed inputs and scope defaults reflect current SDK behavior.
233-235: Verify the v4.3.1 breaking‑change note.Please confirm the default‑scope change and version number match the current SDK release history.
311-335: Confirm failed/canceled key retention and reset signature.Please verify that failed runs clear keys (while successful/canceled retain) and that
idempotencyKeys.reset(taskIdentifier, idempotencyKey)matches the current SDK API.
384-404: Notes section is helpful; verify the scope‑hash bullets.Nice summary and debugging guidance. Please confirm the hash behavior bullets reflect current SDK logic.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
|
|
||
| ### Triggering from backend code | ||
|
|
||
| When triggering tasks from your backend code (outside of a task), there is no parent run context. In this case, `"run"` and `"attempt"` scopes behave the same as `"global"` since there's no run ID or attempt number to inject: |
There was a problem hiding this comment.
Minor phrasing: drop “of”.
Consider “outside a task” for a tighter read.
✏️ Suggested change
-When triggering tasks from your backend code (outside of a task), there is no parent run context.
+When triggering tasks from your backend code (outside a task), there is no parent run context.📝 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.
| When triggering tasks from your backend code (outside of a task), there is no parent run context. In this case, `"run"` and `"attempt"` scopes behave the same as `"global"` since there's no run ID or attempt number to inject: | |
| When triggering tasks from your backend code (outside a task), there is no parent run context. In this case, `"run"` and `"attempt"` scopes behave the same as `"global"` since there's no run ID or attempt number to inject: |
🧰 Tools
🪛 LanguageTool
[style] ~247-~247: This phrase is redundant. Consider using “outside”.
Context: ...riggering tasks from your backend code (outside of a task), there is no parent run context...
(OUTSIDE_OF)
🤖 Prompt for AI Agents
In `@docs/idempotency.mdx` at line 247, Update the sentence that currently reads
"When triggering tasks from your backend code (outside of a task), there is no
parent run context. In this case, `\"run\"` and `\"attempt\"` scopes behave the
same as `\"global\"` since there's no run ID or attempt number to inject:" by
removing the extra "of" and using "outside a task" for tighter phrasing—i.e.,
change "outside of a task" to "outside a task" while keeping the rest of the
sentence and the quoted scopes (`"run"`, `"attempt"`, `"global"`) unchanged.
No description provided.