DurableState

class DurableState extends FlareService

Framework service exposing a Durable Object’s DurableObjectState (ctx) as a per-instance singleton.

Seeded per Durable Object instance by composeDurableInstance; a stateless Worker has no instance state to expose.

How you get one

Handed to you by the framework; see Bindings and services.

Properties

config

config: readonly ConfigToken<unknown>[]

Declares the config tokens this class requires.

Parallel to static deps. When declared, this.config(token) validates that the token is in this array before resolving, identical to how this.inject(token) validates static deps.

deps

deps: readonly []

Declares the service tokens this class is allowed to inject().

Tokens not listed here cause inject() to throw at the call site, naming both the class and the offending token.

state

state: DurableObjectState

Accessors

id

get id(): DurableObjectId

The instance’s Durable Object id (ctx.id).

returns DurableObjectId

storage

get storage(): DurableObjectStorage

The instance’s durable storage (ctx.storage), including the SQL API.

returns DurableObjectStorage

Methods

config()

config<T>(token: ConfigToken<T>): T

Resolves a typed config section by token.

Mirrors inject() + static deps: the class must declare a static config array, and the requested token must appear in it. Both checks throw a developer-facing error when violated.

token ConfigToken<T>

returns T

Example:

class DbService extends FlareService {
  static config = [DbConfig];

  async onStart() {
    const { url } = this.config(DbConfig);
  }
}

Throws:

When the class has no static config declaration.

Throws:

When the token is not present in static config.

dispose()

dispose(): void | Promise<void>

Called at the end of every request for scoped services, whether the handler succeeded or threw.

This is a correctness boundary: the framework waits for any returned promise before completing the request pipeline. Use it for per-request cleanup that must finish, such as rolling back transactions, releasing locks, or closing cursors.

If a service wants fire-and-forget background work, schedule that work inside dispose() and return void. Implies scoped lifetime: declaring this on a singleton class throws at build() time.

returns void | Promise<void>

inject()

inject<T extends FlareService>(token: ServiceToken<T>): Injected<T>

Resolves a dependency declared on static deps, returning the service with framework members hidden from its static type.

token ServiceToken<T>

returns Injected<T>

Throws:

When the token is not present in this class’s static deps array.

onStart()

onStart(): void | Promise<void>

Called once when a singleton service starts (FlareApp.start()).

Not called for scoped services.

returns void | Promise<void>

onStop()

onStop(): void | Promise<void>

Called once when a singleton service stops (FlareApp.stop()).

Not called for scoped services.

returns void | Promise<void>

Learn: Bindings and services