[Durable Objects] Document ctx.id.jurisdiction and improve ctx.id.name scanability#30900
Merged
Conversation
- Break up the dense 'undefined' sentence into a bulleted list, and consolidate the newUniqueId() case into the same list for completeness. - Add a tip callout highlighting alarms as a primary use case for ctx.id.name (companion to the existing historical-caveat note). - Add an in-Durable-Object code example (JavaScript and Python) showing ctx.id.name in use, alongside the existing client-side examples.
github-actions
Bot
added
product:durable-objects
github-actions
Bot
assigned
elithrar,
joshthoward,
lambrospetrou,
mikenomitch,
Oxyjun and
vy-ton
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Contributor
iglesiasbrandon
changed the title
maxmcd
reviewed
May 19, 2026
- Changelog: drop experimental flag framing; clarify idFromString bullet - id.mdx: invert 'jurisdiction' section framing to lead with availability and enumerate only the two undefined cases
maxmcd
approved these changes
May 20, 2026
vy-ton
reviewed
May 20, 2026
|
|
||
| `jurisdiction` is preserved across every ID-construction path, including: | ||
|
|
||
| - IDs created from a jurisdiction-restricted subnamespace, for example `env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("foo")` or `.newUniqueId()`. |
Contributor
There was a problem hiding this comment.
a lot of detail for the changelog. Let's make sure these bullets are in API reference docs and link to from the sentence above
Collaborator
Author
There was a problem hiding this comment.
Updated, thank you!
| date: 2026-03-26 | ||
| --- | ||
|
|
||
| `ctx.id.jurisdiction` inside a Durable Object now reports the [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) that the object was created in, matching the value seen client-side. If a Worker accesses a Durable Object through a jurisdiction-restricted namespace — for example `env.MY_DURABLE_OBJECT.jurisdiction("eu")` — the same jurisdiction is available on `ctx.id.jurisdiction` inside the object, so you can make region-aware decisions without passing the jurisdiction through method arguments or persisting it in storage. |
Contributor
There was a problem hiding this comment.
Second sentence repeats the same info, I would combine into 1
| - The Durable Object was created with `newUniqueId()`. | ||
|
|
||
| :::tip[Useful for alarms] | ||
| `ctx.id.name` is especially useful inside [alarm handlers](/durable-objects/api/alarms/), where there is no calling client to pass the name as an argument. When the alarm fires, `ctx.id.name` holds the same name the object was originally accessed with. |
Contributor
There was a problem hiding this comment.
Combine with note below for single one for alarms behavior
|
|
||
| <Tabs> | ||
|
|
||
| <TabItem label="JavaScript" icon="seti:javascript"> |
…t-id-jurisdiction.mdx Co-authored-by: Vy Ton <vy@cloudflare.com>
Co-authored-by: Vy Ton <vy@cloudflare.com>
- Changelog: collapse duplicate sentences in the opening paragraph into one and remove the 4-bullet ID-construction-path list (info now lives in the API reference, with an inline link from the changelog). - API reference: merge the 'Useful for alarms' tip and pre-2026-03-15 note in the name section into a single Alarms callout. - API reference: add TypeScript tabs to both Tabs groups in the name section for consistency with the JavaScript and Python examples. - API reference: add the 'preserved across every ID-construction path' bullets to the jurisdiction section so the detail dropped from the changelog has a home in the reference docs. Per Vy Ton's review on #30900.
vy-ton
approved these changes
May 27, 2026
vy-ton
marked this pull request as ready for review
May 27, 2026 21:19
vy-ton
requested review from
a team,
Oxyjun,
elithrar,
joshthoward,
lambrospetrou and
mikenomitch
as code owners
May 27, 2026 21:19
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR covers two related bodies of work on the Durable Objects
ctx.idAPI documentation:namesection insrc/content/docs/durable-objects/api/id.mdx(companion to [Durable Objects] Address review feedback on ctx.id.name changelog #30897 which addressed Vy's review feedback on thectx.id.namechangelog).jurisdictionproperty ofDurableObjectId, which is now generally available (no longer experimental). The property reports the jurisdiction a Durable Object is restricted to ("eu"or"fedramp"), and is now consistently available onctx.id.jurisdictioninside the Durable Object — including acrosstoString()/idFromString()round-trips and inside alarm handlers for alarms scheduled on 2026-03-15 or later.Changes
namesection scanability (existing commit)undefinedcases. The dense run-on sentence coveringidFromString(), names > 1,024 bytes, andnewUniqueId()is now a scannable three-bullet list. ThenewUniqueId()case is consolidated here for completeness (it was previously only in the first paragraph).:::tip[Useful for alarms]:::callout between the bulleted list and the existing historical-caveat note. Alarms are the strongest use case forctx.id.name— when an alarm fires, no client called the DO, soctx.id.nameis the only way to know which named object woke up. The existing historical-caveat note (pre-2026-03-15 alarms) is preserved unchanged.<Tabs>group (JavaScript + Python) showingctx.id.nameusage inside a Durable Object class, placed after the existing client-side code examples.jurisdictiondocumentation (new commit)src/content/changelog/durable-objects/2026-05-18-durable-object-id-jurisdiction.mdxsrc/content/docs/durable-objects/api/id.mdx### jurisdictionsection under Properties, modeled after the existing### namesectionsrc/content/docs/durable-objects/reference/data-location.mdxUpstream sources:
globalActorIdto actor invocation + alarm persistence soctx.id.jurisdictionis populated at runtimeRelated
Documentation checklist