Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 18 additions & 9 deletions src/content/docs/durable-objects/api/storage-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,13 @@ sidebar:
order: 6
---

import { Render, Type, MetaInfo, GlossaryTooltip, TypeScriptExample } from "~/components";
import {
Render,
Type,
MetaInfo,
GlossaryTooltip,
TypeScriptExample,
} from "~/components";

The Durable Object Storage API allows <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> to access transactional and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects.

Expand All @@ -18,9 +24,9 @@ Note that Durable Object storage is scoped by individual <GlossaryTooltip term="
However, storage is scoped per individual Durable Object.
:::

Durable Objects gain access to a persistent Durable Object Storage API via `ctx.storage`, on the `ctx` parameter passed to the Durable Object constructor.
Durable Objects gain access to a persistent Durable Object Storage API via the `DurableObjectStorage` interface and accessed by the `DurableObjectState::storage` property. This is frequently accessed via `this.ctx.storage` when the `ctx` parameter passed to the Durable Object constructor.

While access to a Durable Object is single-threaded, request executions can still interleave with each other when they wait on I/O, such as when waiting on the promises returned by persistent storage methods or `fetch()` requests.
JavaScript is a single-threaded and event-driven programming language. This means that JavaScript runtimes by default, allow requests to interleave with each other which can lead to concurrency bugs. The Durable Objects runtime uses a combination of <GlossaryTooltip term="input gate">input gates</GlossaryTooltip> and <GlossaryTooltip term="output gate">output gates</GlossaryTooltip> to avoid this type of concurrency bug when performing storage operations.

The following code snippet shows you how to store and retrieve data using the Durable Object Storage API.

Expand All @@ -31,13 +37,15 @@ export class Counter extends DurableObject {
super(ctx, env);
}

async increment(): Promise<number> {
let value: number = (await this.ctx.storage.get('value')) || 0;
value += 1;
await this.ctx.storage.put('value', value);
return value;
}
async increment(): Promise<number> {
let value: number = (await this.ctx.storage.get('value')) || 0;
value += 1;
await this.ctx.storage.put('value', value);
return value;
}

}

```
</TypeScriptExample>

Expand Down Expand Up @@ -255,3 +263,4 @@ The `put()` method returns a `Promise`, but most applications can discard this p

- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/)
- [WebSockets API](/durable-objects/best-practices/websockets/)
```
8 changes: 8 additions & 0 deletions src/content/glossary/durable-objects.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -63,3 +63,11 @@ entries:
- term: "event context"
general_definition: |-
The duration of time that a Durable Object is processing an event, such as a remote procedure call. [Compute duration charges](/durable-objects/platform/pricing) are incurred for the duration of the event context.

- term: "input gate"
general_definition: |-
While a storage operation is executing, no events shall be delivered to a Durable Object except for storage completion events. Any other events will be deferred until such a time as the object is no longer executing JavaScript code and is no longer waiting for any storage operations. We say that these events are waiting for the "input gate" to open.

- term: "output gate"
general_definition: |-
When a storage write operation is in progress, any new outgoing network messages will be held back until the write has completed. We say that these messages are waiting for the "output gate" to open. If the write ultimately fails, the outgoing network messages will be discarded and replaced with errors, while the Durable Object will be shut down and restarted from scratch.
Loading