Skip to content

Commit d373342

Browse files
committed
Not recommending newUniqueId(jurisdiction) approach
1 parent 5bb5f56 commit d373342

File tree

1 file changed

+15
-6
lines changed

1 file changed

+15
-6
lines changed

src/content/docs/durable-objects/reference/data-location.mdx

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,31 +19,40 @@ A [`DurableObjectId`](/durable-objects/api/id) will be logged outside of the spe
1919

2020
:::
2121

22-
Durable Objects can be restricted to a specific jurisdiction either by creating a [`DurableObjectNamespace`](/durable-objects/api/namespace/) restricted to a jurisdiction, or by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction:
22+
Durable Objects can be restricted to a specific jurisdiction by creating a [`DurableObjectNamespace`](/durable-objects/api/namespace/) restricted to a jurisdiction:
2323

2424
```js
2525
const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu");
2626
const euId = euSubnamespace.newUniqueId();
27-
// or
28-
const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" });
2927
```
3028

29+
This approach works with all of the [ID methods](/durable-objects/api/id/).
30+
3131
Methods on a [`DurableObjectNamespace`](/durable-objects/api/namespace/) that take a [`DurableObjectId`](/durable-objects/api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. To achieve this, a [`DurableObjectId`](/durable-objects/api/id) encodes its jurisdiction. As a consequence, it is possible to have the same name represent different IDs in different jurisdictions.
3232

3333
```js
3434
const euId1 = env.MY_DURABLE_OBJECT.idFromName("my-name");
3535
const euId2 = env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("my-name");
3636
console.assert(!euId1.equal(euId2), "This should always be true");
3737
```
38-
39-
Methods on a [`DurableObjectNamespace`](/durable-objects/api/namespace/) that take a [`DurableObjectId`](/durable-objects/api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. However, these methods will not throw an exception if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction. The common case is that any valid [`DurableObjectId`](/durable-objects/api/id) can be used in the top-level namespace's methods.
38+
However, these methods will not throw an exception if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction. The common case is that any valid [`DurableObjectId`](/durable-objects/api/id) can be used in the top-level namespace's methods.
4039

4140
```js
4241
const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu");
4342
const euId = euSubnamespace.idFromName(name);
4443
const stub = env.MY_DURABLE_OBJECT.get(euId);
4544
```
4645

46+
:::caution[Do not use `newUniqueId(jurisdiction)`]
47+
Note that it is possible to specify a jurisdiction by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction:
48+
49+
```sh
50+
const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" });
51+
```
52+
53+
**However, we do not recommend this approach.** Instead, first create a namespace restricted to a jurisdiction, as explained above.
54+
:::
55+
4756
### Supported locations
4857

4958
| Parameter | Location |
@@ -96,4 +105,4 @@ future.
96105
<sup>2</sup> Durable Objects currently do not spawn in this location. Instead,
97106
the Durable Object will spawn in a nearby location which does support Durable
98107
Objects. For example, Durable Objects hinted to South America spawn in Eastern
99-
North America instead.
108+
North America instead.

0 commit comments

Comments
 (0)