Durable Object Namespace

Description

The DurableObjectNamespace interface is used to obtain a reference to a new or existing Durable Object instance. The interface is accessible from the fetch handler on a Cloudflare Worker via the env parameter, which is the standard interface when referencing bindings declared in wrangler.toml.

This interface defines several methods that can be used to create an ID for a Durable Object instance. Note that creating an ID for a Durable Object instance does not create the Durable Object. The Durable Object is created lazily after calling DurableObjectNamespace::get to create a DurableObjectStub from a DurableObjectId. This ensures that objects are not constructed until they are actually accessed.

JavaScript

import { DurableObject } from "cloudflare:workers";

// Durable Object
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 instance
    const stub = env.MY_DURABLE_OBJECT.get(id);
    ...
  }
}

TypeScript

import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObject>;
}

// Durable Object
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 instance
    const stub = env.MY_DURABLE_OBJECT.get(id);
    ...
  }
} satisfies ExportedHandler<Env>;

Methods

idFromName

idFromName creates a DurableObjectId which refers to an individual instance of the Durable Object class from a particular name.

const fooId = env.MY_DURABLE_OBJECT.idFromName("foo");
const barId = env.MY_DURABLE_OBJECT.idFromName("bar");

Parameters

• A required string to be used to generate a DurableObjectId corresponding to the name of a Durable Object instance.

Return values

• A DurableObjectId referring to an instance of a Durable Object class.

newUniqueId

newUniqueId creates a DurableObjectId which refers to an individual instance of the Durable Object class.

const id = env.MY_DURABLE_OBJECT.newUniqueId();
const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" });

newUniqueId

IDs created by newUniqueId will result in lower latencies when getting a DurableObjectStub relative to idFromName.

Parameters

• An optional object with the key jurisdiction and value of a jurisdiction string.

Return values

• A DurableObjectId referring to an instance of the Durable Object class.

idFromString

idFromString creates a DurableObjectId from a previously generated ID that has been converted to a string. This method ensures the ID is valid, for example, it checks that the ID consists of 64 hex digits.

// Create a new unique ID
const id = env.MY_DURABLE_OBJECT.newUniqueId();
// Save the unique ID elsewhere, e.g. a session cookie via id.toString()
...
// Recreate the ID from the string
const id = env.MY_DURABLE_OBJECT.idFromString(session_id);

Parameters

• A required string corresponding to a DurableObjectId previously generated either by newUniqueId or idFromName.

Return values

• A DurableObjectId referring to an instance of a Durable Object class.

get

get obtains a DurableObjectStub from a DurableObjectId which can be used to invoke methods on a Durable Object instance.

const id = env.MY_DURABLE_OBJECT.newUniqueId();
const stub = env.MY_DURABLE_OBJECT.get(id);

Parameters

• A required DurableObjectId and an optional object with the key locationHint and value of a locationHint string.

Return values

• A DurableObjectStub referring to an instance of a Durable Object class.

jurisdiction

jurisdiction creates a subnamespace from a namespace where all Durable Object instance IDs and references created from that subnamespace will be restricted to the specified jurisdiction.

const subnamespace = env.MY_DURABLE_OBJECT.jurisdiction("foo");
const euId = subnamespace.idFromName("foo");

Parameters

• A required jurisdiction string.

Return values

• A DurableObjectNamespace scoped to a particular geographic jurisdiction.

Related resources

• Durable Objects: Easy, Fast, Correct – Choose Three ↗.
• Durable Objects best practices.