Skip to content

Commit 70293eb

Browse files
committed
docs: reorder README introduction
Lead with the programming model, follow with concrete coordination use cases, and keep the SQLite quickstart directly after both sections. See #2
1 parent 6594af7 commit 70293eb

1 file changed

Lines changed: 22 additions & 22 deletions

File tree

‎README.md‎

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -18,28 +18,6 @@ application already operates.
1818
> the TypeScript implementation is new. Read the [delivery boundaries](#delivery-boundaries)
1919
> before using it for important data.
2020
21-
## What Solid Objects is for
22-
23-
Use Solid Objects when more than one request, job, or process can act on the
24-
same logical thing and the next action must use its latest committed state.
25-
These are the stateful coordination patterns for which people often reach for
26-
Durable Objects:
27-
28-
| Pattern | One identity per | What the object coordinates |
29-
| --------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
30-
| Multiplayer, presence, or collaboration | Room, session, or document | Joins, moves, and edits commit in order; subscribers refresh from committed state |
31-
| Reservations and expiring holds | Show, resource, or stock item | Availability checks and holds cannot interleave; a durable reminder can release an old hold |
32-
| Checkout and account workflows | Cart, order, account, device | The current step, retries, and effect results return to the same ordered mailbox |
33-
| Per-key rate limits | API key, account, or device | Token checks and decrements are serialized; a reminder can refill the bucket |
34-
| Stateful agent sessions | Agent session | Messages and tool results apply in order and pending work survives a worker exit |
35-
36-
The common shape is one durable coordination boundary with an application
37-
defined identity. Work for that identity is serialized, while unrelated rooms,
38-
carts, accounts, or sessions can progress concurrently. A single global rate
39-
limiter or another very hot identity is a poor fit because it becomes an
40-
intentional bottleneck. If one ordinary row transaction solves the problem,
41-
prefer that. See [Choosing Solid Objects](docs/fit.md) for the longer guide.
42-
4321
## The programming model
4422

4523
```typescript
@@ -64,6 +42,28 @@ Both calls enter the durable mailbox for `cart-123`. They execute in order and
6442
commit one state transition at a time, even when different requests or Node.js
6543
processes submit them concurrently.
6644

45+
## What Solid Objects is for
46+
47+
Use Solid Objects when more than one request, job, or process can act on the
48+
same logical thing and the next action must use its latest committed state.
49+
These are the stateful coordination patterns for which people often reach for
50+
Durable Objects:
51+
52+
| Pattern | One identity per | What the object coordinates |
53+
| --------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
54+
| Multiplayer, presence, or collaboration | Room, session, or document | Joins, moves, and edits commit in order; subscribers refresh from committed state |
55+
| Reservations and expiring holds | Show, resource, or stock item | Availability checks and holds cannot interleave; a durable reminder can release an old hold |
56+
| Checkout and account workflows | Cart, order, account, device | The current step, retries, and effect results return to the same ordered mailbox |
57+
| Per-key rate limits | API key, account, or device | Token checks and decrements are serialized; a reminder can refill the bucket |
58+
| Stateful agent sessions | Agent session | Messages and tool results apply in order and pending work survives a worker exit |
59+
60+
The common shape is one durable coordination boundary with an application
61+
defined identity. Work for that identity is serialized, while unrelated rooms,
62+
carts, accounts, or sessions can progress concurrently. A single global rate
63+
limiter or another very hot identity is a poor fit because it becomes an
64+
intentional bottleneck. If one ordinary row transaction solves the problem,
65+
prefer that. See [Choosing Solid Objects](docs/fit.md) for the longer guide.
66+
6767
## Run it now with SQLite
6868

6969
Node.js 24.15 or newer is required. The `0.13.0` release includes a

0 commit comments

Comments
 (0)