Document prefered method getByName for creating Durable Object stubs (#24586)

* Document prefered method getByName for creating Durable Object stubs

* Apply suggestions from code review

* Fixing chapter

* Removing redundant line

* Fixing compilation error

---------

Co-authored-by: Jun Lee <[email protected]>

Author: joshthoward

src/content/docs/browser-rendering/workers-bindings/browser-rendering-with-DO.mdx

@@ -107,8 +107,7 @@ import puppeteer from "@cloudflare/puppeteer";
 
 export default {
 	async fetch(request, env) {
-		let id = env.BROWSER.idFromName("browser");
-		let obj = env.BROWSER.get(id);
+		let obj = env.BROWSER.getByName("browser");
 
 		// Send a request to the Durable Object, then await its response.
 		let resp = await obj.fetch(request.url);

src/content/docs/containers/examples/env-vars-and-secrets.mdx

@@ -1,5 +1,4 @@
 ---
-
 summary: Pass in environment variables and secrets to your container
 pcx_content_type: example
 title: Env Vars and Secrets
@@ -125,11 +124,8 @@ export class MyContainer extends Container {
 export default {
 	async fetch(request, env) {
 		if (new URL(request.url).pathname === "/launch-instances") {
-			let idOne = env.MY_CONTAINER.idFromName("foo");
-			let instanceOne = env.MY_CONTAINER.get(idOne);
-
-			let idTwo = env.MY_CONTAINER.idFromName("foo");
-			let instanceTwo = env.MY_CONTAINER.get(idTwo);
+			let instanceOne = env.MY_CONTAINER.getByName("foo");
+			let instanceTwo = env.MY_CONTAINER.getByName("foo");
 
 			// Each instance gets a different set of environment variables
 

src/content/docs/containers/get-started.mdx

@@ -27,8 +27,6 @@ the `docker info` command will hang or return an error including the message "Ca
 
 ## Deploy your first Container
 
-
-
 Run the following command to create and deploy a new Worker with a container, from the starter template:
 
 ```sh
@@ -102,7 +100,6 @@ on container status changes, and more.
 See the [documentation for Durable Object container methods](/durable-objects/api/container/) and the
 [`Container` class repository](https://github.com/cloudflare/containers) for more details.
 
-
 ### Configuration
 
 Your [Wrangler configuration file](/workers/wrangler/configuration/) defines the configuration for both your Worker and your container:
@@ -204,9 +201,8 @@ When a request enters Cloudflare, your Worker's [`fetch` handler](/workers/runti
 
   ```js
   if (pathname.startsWith("/container")) {
-  	const id = env.MY_CONTAINER.idFromName(pathname);
-		const container = env.MY_CONTAINER.get(id);
-		return await container.fetch(request);
+  	const container = env.MY_CONTAINER.getByName(pathname);
+  	return await container.fetch(request);
   }
   ```
 

src/content/docs/durable-objects/api/alarms.mdx

@@ -39,7 +39,10 @@ Alarms can be used to build distributed primitives, like queues or batching of w
 
 ### `setAlarm`
 
-- <code>{" "}setAlarm(scheduledTimeMs <Type text="number" />)</code>
+- <code>
+  	{" "}
+  	setAlarm(scheduledTimeMs <Type text="number" />)
+  </code>
   : <Type text="void" />
 
   - Set the time for the alarm to run. Specify the time as the number of milliseconds elapsed since the UNIX epoch.
@@ -63,11 +66,16 @@ This is due to the fact that, if the Durable Object wakes up after being inactiv
 
 ### `alarm`
 
-- <code>alarm(`alarmInfo`<Type text="Object"/>)</code>: <Type text='void' />
+- <code>
+  	alarm(`alarmInfo`
+  	<Type text="Object" />)
+  </code>
+  : <Type text="void" />
 
   - Called by the system when a scheduled alarm time is reached.
 
   - The optional parameter `alarmInfo` object has two properties:
+
     - `retryCount` <Type text="number"/>: The number of times this alarm event has been retried.
     - `isRetry` <Type text="boolean"/>: A boolean value to indicate if the alarm has been retried. This value is `true` if this alarm event is a retry.
 
@@ -89,8 +97,7 @@ import { DurableObject } from "cloudflare:workers";
 
 export default {
 	async fetch(request, env) {
-		let id = env.ALARM_EXAMPLE.idFromName("foo");
-		return await env.ALARM_EXAMPLE.get(id).fetch(request);
+		return await env.ALARM_EXAMPLE.getByName("foo").fetch(request);
 	},
 };
 
@@ -120,11 +127,13 @@ The following example shows how to use the `alarmInfo` property to identify if t
 
 ```js
 class MyDurableObject extends DurableObject {
-  async alarm(alarmInfo) {
-    if (alarmInfo?.retryCount != 0) {
-      console.log("This alarm event has been attempted ${alarmInfo?.retryCount} times before.");
-    }
-  }
+	async alarm(alarmInfo) {
+		if (alarmInfo?.retryCount != 0) {
+			console.log(
+				"This alarm event has been attempted ${alarmInfo?.retryCount} times before.",
+			);
+		}
+	}
 }
 ```
 

src/content/docs/durable-objects/api/namespace.mdx

@@ -28,11 +28,8 @@ export class MyDurableObject extends DurableObject {
 // Worker
 export default {
   async fetch(request, env) {
-    // Every unique ID refers to an individual instance of the Durable Object class
-    const id = env.MY_DURABLE_OBJECT.idFromName("foo");
-
     // A stub is a client Object used to invoke methods defined by the Durable Object
-    const stub = env.MY_DURABLE_OBJECT.get(id);
+    const stub = env.MY_DURABLE_OBJECT.getByName("foo");
     ...
   }
 }
@@ -55,11 +52,8 @@ export class MyDurableObject extends DurableObject {
 // Worker
 export default {
   async fetch(request, env) {
-    // Every unique ID refers to an individual instance of the Durable Object class
-    const id = env.MY_DURABLE_OBJECT.idFromName("foo");
-
     // A stub is a client Object used to invoke methods defined by the Durable Object
-    const stub = env.MY_DURABLE_OBJECT.get(id);
+    const stub = env.MY_DURABLE_OBJECT.getByName("foo");
     ...
   }
 } satisfies ExportedHandler<Env>;
@@ -145,13 +139,32 @@ const stub = env.MY_DURABLE_OBJECT.get(id);
 
 - A [`DurableObjectStub`](/durable-objects/api/stub) referring to an instance of a Durable Object class.
 
+### `getByName`
+
+`getByName` obtains a [`DurableObjectStub`](/durable-objects/api/stub) from a provided name, which can be used to invoke methods on a Durable Object.
+
+This method returns the <GlossaryTooltip term="stub">stub</GlossaryTooltip> immediately, often before a connection has been established to the Durable Object. This allows requests to be sent to the instance right away, without waiting for a network round trip.
+
+```js
+const fooStub = env.MY_DURABLE_OBJECT.getByName("foo");
+const barStub = env.MY_DURABLE_OBJECT.getByName("bar");
+```
+
+#### Parameters
+
+- A required string to be used to generate a [`DurableObjectStub`](/durable-objects/api/stub) corresponding to an instance of the Durable Object class with the provided name.
+
+#### Return values
+
+- A [`DurableObjectStub`](/durable-objects/api/stub) referring to an instance of a Durable Object class.
+
 ### `jurisdiction`
 
 `jurisdiction` creates a subnamespace from a namespace where all Durable Object IDs and references created from that subnamespace will be restricted to the specified [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction).
 
 ```js
 const subnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu");
-const euId = subnamespace.idFromName("foo");
+const euStub = subnamespace.getByName("foo");
 ```
 
 #### Parameters

src/content/docs/durable-objects/api/stub.mdx

@@ -31,11 +31,10 @@ console.assert(id.equals(stub.id), "This should always be true");
 
 ### `name`
 
-`name` is an optional property of a `DurableObjectStub`, which returns the name that was used to create the [`DurableObjectId`](/durable-objects/api/id) via [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname) which was then used to create the `DurableObjectStub`. This value is undefined if the [`DurableObjectId`](/durable-objects/api/id) used to create the `DurableObjectStub` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid).
+`name` is an optional property of a `DurableObjectStub`, which returns a name if it was provided upon stub creation either directly via [`DurableObjectNamespace::getByName`](/durable-objects/api/namespace/#getbyname) or indirectly via a [`DurableObjectId`](/durable-objects/api/id) created by [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname). This value is undefined if the [`DurableObjectId`](/durable-objects/api/id) used to create the `DurableObjectStub` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid).
 
 ```js
-const id = env.MY_DURABLE_OBJECT.idFromName("foo");
-const stub = env.MY_DURABLE_OBJECT.get(id);
+const stub = env.MY_DURABLE_OBJECT.getByName("foo");
 console.assert(stub.name === "foo", "This should always be true");
 ```
 

src/content/docs/durable-objects/best-practices/create-durable-object-stubs-and-send-requests.mdx

@@ -50,11 +50,8 @@ export class MyDurableObject extends DurableObject {
 // Worker
 export default {
 	async fetch(request, env) {
-		// Every unique ID refers to an individual instance of the Durable Object class
-		const id = env.MY_DURABLE_OBJECT.idFromName("foo");
-
 		// A stub is a client used to invoke methods on the Durable Object
-		const stub = env.MY_DURABLE_OBJECT.get(id);
+		const stub = env.MY_DURABLE_OBJECT.getByName("foo");
 
 		// Methods on the Durable Object are invoked via the stub
 		const response = await stub.fetch(request);
@@ -87,11 +84,8 @@ export class MyDurableObject extends DurableObject {
 // Worker
 export default {
 	async fetch(request, env) {
-		// Every unique ID refers to an individual instance of the Durable Object class
-		const id = env.MY_DURABLE_OBJECT.idFromName("foo");
-
 		// A stub is a client used to invoke methods on the Durable Object
-		const stub = env.MY_DURABLE_OBJECT.get(id);
+		const stub = env.MY_DURABLE_OBJECT.getByName("foo");
 
 		// Methods on the Durable Object are invoked via the stub
 		const response = await stub.fetch(request);
@@ -147,11 +141,8 @@ export class MyDurableObject extends DurableObject {
 // Worker
 export default {
 	async fetch(_request, env, _ctx) {
-		// Every unique ID refers to an individual instance of the Durable Object class
-		const id = env.MY_DURABLE_OBJECT.idFromName("foo");
-
 		// A stub is a client used to invoke methods on the Durable Object
-		const stub = env.MY_DURABLE_OBJECT.get(id);
+		const stub = env.MY_DURABLE_OBJECT.getByName("foo");
 
 		// Invoke the fetch handler on the Durable Object stub
 		let response = await stub.fetch("http://do/hello?name=World");
@@ -205,11 +196,8 @@ export class MyDurableObject extends DurableObject {
 // Worker
 export default {
 	async fetch(_request, env, _ctx) {
-		// Every unique ID refers to an individual instance of the Durable Object class
-		const id = env.MY_DURABLE_OBJECT.idFromName("foo");
-
 		// A stub is a client used to invoke methods on the Durable Object
-		const stub = env.MY_DURABLE_OBJECT.get(id);
+		const stub = env.MY_DURABLE_OBJECT.getByName("foo");
 
 		// Invoke the fetch handler on the Durable Object stub
 		let response = await stub.fetch("http://do/hello?name=World");

src/content/docs/durable-objects/best-practices/error-handling.mdx

@@ -7,7 +7,6 @@ sidebar:
 
 import { GlossaryTooltip } from "~/components";
 
-
 Any uncaught exceptions thrown by a <GlossaryTooltip term="Durable Object">Durable Object</GlossaryTooltip> or thrown by Durable Objects' infrastructure (such as overloads or network errors) will be propagated to the callsite of the client. Catching these exceptions allows you to retry creating the [`DurableObjectStub`](/durable-objects/api/stub) and sending requests.
 
 JavaScript Errors with the property `.retryable` set to True are suggested to be retried if requests to the Durable Object are idempotent, or can be applied multiple times without changing the response. If requests are not idempotent, then you will need to decide what is best for your application.
@@ -39,7 +38,6 @@ export interface Env {
 export default {
 	async fetch(request, env, ctx) {
 		let userId = new URL(request.url).searchParams.get("userId") || "";
-		const id = env.ErrorThrowingObject.idFromName(userId);
 
 		// Retry behavior can be adjusted to fit your application.
 		let maxAttempts = 3;
@@ -52,7 +50,7 @@ export default {
 			try {
 				// Create a Durable Object stub for each attempt, because certain types of
 				// errors will break the Durable Object stub.
-				const doStub = env.ErrorThrowingObject.get(id);
+				const doStub = env.ErrorThrowingObject.getByName(userId);
 				const resp = await doStub.fetch("http://your-do/");
 
 				return Response.json(resp);

src/content/docs/durable-objects/best-practices/websockets.mdx

@@ -168,7 +168,11 @@ The following are methods available on the **Native Durable Object WebSocket API
 
 #### `WebSocket.serializeAttachment()`
 
-- <code> serializeAttachment(value <Type text="any" />)</code>: <Type text="void" />
+- <code>
+  	{" "}
+  	serializeAttachment(value <Type text="any" />)
+  </code>
+  : <Type text="void" />
 
   - Keeps a copy of `value` associated with the WebSocket to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. If the value needs to be durable please use [Durable Object Storage](/durable-objects/api/storage-api/).
 
@@ -180,7 +184,6 @@ The following are methods available on the **Native Durable Object WebSocket API
 
   - Retrieves the most recent value passed to `serializeAttachment()`, or `null` if none exists.
 
-
 ## WebSocket Standard API
 
 WebSocket connections are established by making an HTTP GET request with the `Upgrade: websocket` header. A Cloudflare Worker is commonly used to validate the request, proxy the request to the Durable Object to accept the server side connection, and return the client side connection in the response.
@@ -213,8 +216,7 @@ export default {
 
 			// This example will refer to a single Durable Object instance, since the name "foo" is
 			// hardcoded
-			let id = env.WEBSOCKET_SERVER.idFromName("foo");
-			let stub = env.WEBSOCKET_SERVER.get(id);
+			let stub = env.WEBSOCKET_SERVER.getByName("foo");
 
 			// The Durable Object's fetch handler will accept the server side connection and return
 			// the client
@@ -254,8 +256,7 @@ export default {
 
 			// This example will refer to a single Durable Object instance, since the name "foo" is
 			// hardcoded
-			let id = env.WEBSOCKET_SERVER.idFromName("foo");
-			let stub = env.WEBSOCKET_SERVER.get(id);
+			let stub = env.WEBSOCKET_SERVER.getByName("foo");
 
 			// The Durable Object's fetch handler will accept the server side connection and return
 			// the client

src/content/docs/durable-objects/concepts/durable-object-lifecycle.mdx

@@ -14,8 +14,7 @@ Simply creating the Durable Object Stub does not send a request to the Durable O
 A request is sent to the Durable Object and its lifecycle begins only once a method is invoked on the Durable Object Stub.
 
 ```js
-const id = env.MY_DURABLE_OBJECT.idFromName("foo");
-const stub = env.MY_DURABLE_OBJECT.get(id);
+const stub = env.MY_DURABLE_OBJECT.getByName("foo");
 // Now the request is sent to the remote Durable Object.
 const rpcResponse = await stub.sayHello();
 ```