Skip to content

Commit 03a6231

Browse files
cardmagiccardmagic
committed
docs: tighten README claims
Classify the package immediately, describe the exact browser coverage, and scope the quickstart assertions to one local run. Put the runnable example before the broader use-case table. See #2
1 parent 70293eb commit 03a6231

1 file changed

Lines changed: 32 additions & 33 deletions

File tree

‎README.md‎

Lines changed: 32 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,19 @@
33
[![CI](https://github.com/cardmagic/solid-objects-js/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cardmagic/solid-objects-js/actions/workflows/ci.yml)
44
[![npm](https://img.shields.io/npm/v/solid-objects)](https://www.npmjs.com/package/solid-objects)
55

6-
Solid Objects gives each logical application identity—such as a room, cart,
7-
account, device, document, or agent session—durable state and a sequential
8-
mailbox. Concurrent calls for one identity cannot overwrite each other. Calls
9-
for different identities can run at the same time.
6+
Solid Objects is a TypeScript actor library for Node.js that gives each
7+
application-defined identity durable state and a sequential mailbox, backed by
8+
SQLite, PostgreSQL, or MySQL. Concurrent calls for one identity cannot
9+
overwrite each other. Calls for different identities can run at the same time.
1010

1111
Define ordinary TypeScript classes and run them in ordinary Node.js processes.
1212
State, queued operations, retries, reminders, effects, and realtime
13-
invalidations are stored in the SQLite, PostgreSQL, or MySQL database the
14-
application already operates.
13+
invalidations are stored in the database the application already operates.
1514

1615
> **Early release:** the correctness core has automated coverage across the
17-
> supported databases, browsers, process recovery, and packaged artifacts, but
18-
> the TypeScript implementation is new. Read the [delivery boundaries](#delivery-boundaries)
19-
> before using it for important data.
16+
> supported databases, the Chromium browser client, process recovery, and
17+
> packaged artifacts, but the TypeScript implementation is new. Read the
18+
> [delivery boundaries](#delivery-boundaries) before using it for important data.
2019
2120
## The programming model
2221

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

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-
6744
## Run it now with SQLite
6845

6946
Node.js 24.15 or newer is required. The `0.13.0` release includes a
@@ -77,8 +54,8 @@ The command needs no repository checkout, database server, Redis, container, or
7754
application configuration. It uses Node's built-in SQLite module and removes
7855
its scoped temporary database before exiting.
7956

80-
The executable asserts rather than merely printing a plausible result. It
81-
proves that:
57+
The executable asserts rather than merely printing a plausible result. In one
58+
local run, it verifies that:
8259

8360
- 25 concurrent calls to one identity produce the exact committed state `25`;
8461
- their return values are the complete sequence from `1` through `25`;
@@ -88,6 +65,28 @@ proves that:
8865
Before `0.13.0` reaches the registry, maintainers can run the identical
8966
executable from a generated package tarball with `pnpm run test:package`.
9067

68+
## What Solid Objects is for
69+
70+
Use Solid Objects when more than one request, job, or process can act on the
71+
same logical thing and the next action must use its latest committed state.
72+
These are the stateful coordination patterns for which people often reach for
73+
Durable Objects:
74+
75+
| Pattern | One identity per | What the object coordinates |
76+
| --------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
77+
| Multiplayer, presence, or collaboration | Room, session, or document | Joins, moves, and edits commit in order; subscribers refresh from committed state |
78+
| Reservations and expiring holds | Show, resource, or stock item | Availability checks and holds cannot interleave; a durable reminder can release an old hold |
79+
| Checkout and account workflows | Cart, order, account, device | The current step, retries, and effect results return to the same ordered mailbox |
80+
| Per-key rate limits | API key, account, or device | Token checks and decrements are serialized; a reminder can refill the bucket |
81+
| Stateful agent sessions | Agent session | Messages and tool results apply in order and pending work survives a worker exit |
82+
83+
The common shape is one durable coordination boundary with an application
84+
defined identity. Work for that identity is serialized, while unrelated rooms,
85+
carts, accounts, or sessions can progress concurrently. A single global rate
86+
limiter or another very hot identity is a poor fit because it becomes an
87+
intentional bottleneck. If one ordinary row transaction solves the problem,
88+
prefer that. See [Choosing Solid Objects](docs/fit.md) for the longer guide.
89+
9190
## How it works
9291

9392
An object is addressed by its TypeScript class and application-defined ID.

0 commit comments

Comments
 (0)