You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/idempotency.mdx
+11-11Lines changed: 11 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -133,9 +133,9 @@ The `scope` option determines how your idempotency key is processed. When you pr
133
133
|`"attempt"`|`key + parentRunId + attemptNumber`| Key is combined with the parent run ID and attempt number | Allow child tasks to re-run on each retry of the parent |
134
134
|`"global"`|`key`| Key is used as-is, no context added | Ensure a task only runs once ever, regardless of parent |
135
135
136
-
### `"run"` scope (default)
136
+
### `run` scope (default)
137
137
138
-
The `"run"` scope makes the idempotency key unique to the current parent task run. This is the default behavior for both raw strings and `idempotencyKeys.create()`.
138
+
The `run` scope makes the idempotency key unique to the current parent task run. This is the default behavior for both raw strings and `idempotencyKeys.create()`.
With `"run"` scope, if you trigger `processOrder` twice with different run IDs, both will send emails because the idempotency keys are different (they include different parent run IDs).
162
+
With `run` scope, if you trigger `processOrder` twice with different run IDs, both will send emails because the idempotency keys are different (they include different parent run IDs).
163
163
164
-
### `"attempt"` scope
164
+
### `attempt` scope
165
165
166
-
The `"attempt"` scope makes the idempotency key unique to each attempt of the parent task. Use this when you want child tasks to re-execute on each retry.
166
+
The `attempt` scope makes the idempotency key unique to each attempt of the parent task. Use this when you want child tasks to re-execute on each retry.
The `"global"` scope makes the idempotency key truly global across all runs. Use this when you want to ensure a task only runs once ever (until the TTL expires), regardless of which parent task triggered it.
193
+
The `global` scope makes the idempotency key truly global across all runs. Use this when you want to ensure a task only runs once ever (until the TTL expires), regardless of which parent task triggered it.
Even with `"global"` scope, idempotency keys are still isolated to the specific task and environment. Using the same key to trigger *different* tasks will not deduplicate - both tasks will run. See [Environment and task scoping](#environment-and-task-scoping) for more details.
216
+
Even with `global` scope, idempotency keys are still isolated to the specific task and environment. Using the same key to trigger *different* tasks will not deduplicate - both tasks will run. See [Environment and task scoping](#environment-and-task-scoping) for more details.
217
217
</Note>
218
218
219
219
## Default behavior
@@ -222,7 +222,7 @@ Understanding the default behavior is important to avoid unexpected results:
222
222
223
223
### Passing a raw string
224
224
225
-
When you pass a raw string directly to the `idempotencyKey` option, it is automatically processed with `"run"` scope:
225
+
When you pass a raw string directly to the `idempotencyKey` option, it is automatically processed with `run` scope:
226
226
227
227
```ts
228
228
// These two are equivalent when called inside a task:
**Breaking change in v4.3.1:** In v4.3.0 and earlier, raw strings defaulted to `"global"` scope. Starting in v4.3.1, raw strings now default to `"run"` scope. If you're upgrading and relied on the previous global behavior, you must now explicitly use `idempotencyKeys.create("key", { scope: "global" })`.
234
+
**Breaking change in v4.3.1:** In v4.3.0 and earlier, raw strings defaulted to `global` scope. Starting in v4.3.1, raw strings now default to `run` scope. If you're upgrading and relied on the previous global behavior, you must now explicitly use `idempotencyKeys.create("key", { scope: "global" })`.
235
235
</Warning>
236
236
237
237
This means raw strings are scoped to the parent run by default. If you want global behavior, you must explicitly create the key with `scope: "global"`:
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:
247
+
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:
0 commit comments