toiljs 0.0.85 → 0.0.87

package/docs/concepts/tiers.md

@@ -0,0 +1,166 @@
+# Compute tiers
+
+Your toiljs backend runs across four **compute tiers**, from a per-request handler at the very edge (L1) up to a single worldwide coordinator (L4). You write one project; the build decides which code belongs to which tier.
+
+## What a tier is
+
+A **tier** is a place your server code runs, defined by two things: how *close* it sits to the user, and how *long* one copy of it lives. The Dacely **edge** is a fleet of servers in many cities. Some work wants to run as close to the user as possible for speed. Other work wants exactly one copy in the whole world so it stays coordinated. A tier is the framework's answer to "where and for how long should this piece of code live?"
+
+There are four tiers, named L1 through L4. The number is the **scope**: L1 is the smallest and nearest (one edge node), and each higher number widens the scope until L4 covers the entire globe.
+
+```mermaid
+flowchart TB
+    subgraph L4["L4 - Global (one leader worldwide)"]
+        direction TB
+        D["@daemon / @scheduled<br/>rollups, cleanup, polling"]
+        subgraph L3["L3 - Continental (per continent)"]
+            direction TB
+            C["@stream (Continental scope)<br/>cross-region coordination"]
+            subgraph L2["L2 - Regional (per region)"]
+                direction TB
+                R["@stream (Regional scope)<br/>chat, presence, live cursors"]
+                subgraph L1["L1 - Hot / edge (per request)"]
+                    H["@rest, @service, @remote<br/>HTTP + RPC, the default"]
+                end
+            end
+        end
+    end
+```
+
+Read the diagram as concentric rings: L1 is the inner ring nearest the user, and each outer ring is a wider, longer-lived scope. Most of your code lives in the innermost ring.
+
+## The four tiers at a glance
+
+| Tier | Name | How close | How many copies | Lives for | Runs |
+| --- | --- | --- | --- | --- | --- |
+| **L1** | Hot / edge | The exact node nearest the user | A fresh one per request | One request | `@rest`, `@service` / `@remote` |
+| **L2** | Regional | A region (a group of nearby cities) | One box per connection | The connection | `@stream` (Regional scope) |
+| **L3** | Continental | A continent | One box per connection | The connection | `@stream` (Continental scope) |
+| **L4** | Global / daemon | One place worldwide | Exactly one leader (plus a warm standby) | Until redeployed | `@daemon`, `@scheduled` |
+
+The tier names come straight from the edge runtime (its node roles are `Hot`, `Regional`, `Continental`, and `Daemon`).
+
+## L1: Hot (request/response)
+
+**What:** a plain request-in, response-out handler. This is the default tier and where most code lives.
+
+**How it behaves:** a fresh copy of your handler serves each request, on whatever node is nearest the caller. Nothing you store on a field survives to the next request, because the next request may be a brand-new copy on the other side of the planet. This is called being **stateless**. It is what lets your app scale to the whole world with no coordination. When you need something to persist, you write it to [ToilDB](../database/README.md), the shared database.
+
+L1 is the lowest latency tier: the code runs on the node the user already reached, so there is no extra hop.
+
+```ts
+// L1: a fresh box per request. `hits` does NOT persist across requests.
+@rest('hello')
+class Hello {
+    private hits: i32 = 0; // reset every request
+
+    @get('/')
+    public greet(): Response {
+        this.hits = this.hits + 1; // always 1
+        return Response.text('hi\n');
+    }
+}
+```
+
+See [REST](../backend/rest.md) and [RPC](../backend/rpc.md).
+
+## L2 and L3: streams (long-lived connections)
+
+**What:** a **stream** is a long-lived connection (think a chat socket) where the server keeps state *per connected client* for as long as they stay connected.
+
+**How it behaves:** when a client connects, the edge creates one resident **box** (one running copy of your `@stream` class) and pins it to a single worker. That same box handles every message from that client and is torn down when they leave. Because the box stays alive, its fields *do* persist across events, unlike L1. This is what makes a running message count, a game session, or a live cursor possible.
+
+A `@stream` picks its scope with `@stream({ scope })`:
+
+- **`StreamScope.Regional`** puts the box in the user's region (L2). Closest, lowest latency, smallest blast radius. Use it for per-connection state that only that one client cares about.
+- **`StreamScope.Continental`** puts the box at a continent-wide node (L3). A little farther, but many clients across a continent can be steered to the *same* box, which is what you want when connected users must share state (a shared room, a leaderboard everyone updates).
+
+The trade-off is the theme of this whole page: nearer (L2) is faster; wider (L3) lets more clients coordinate on one box.
+
+```ts
+// L2/L3: the box is resident, so `count` survives every message.
+@stream({ scope: StreamScope.Regional })
+class Echo {
+    private count: i32 = 0;
+
+    @connect onConnect(): StreamOutbound {
+        this.count = 0;
+        return StreamOutbound.accept();
+    }
+    @message onMessage(pkt: StreamPacket): StreamOutbound {
+        this.count = this.count + 1; // persists across events
+        return StreamOutbound.empty();
+    }
+    @close onClose(): void { /* box torn down after this */ }
+}
+```
+
+See [Realtime streams](../realtime/streams.md).
+
+## L4: the daemon (global coordination)
+
+**What:** the daemon is a single, elected leader for your whole app, running recurring background work on a schedule.
+
+**How it behaves:** unlike every other tier, there is exactly **one** live daemon box in the entire world for your domain (with a warm standby ready to take over if the leader fails). It is not tied to any request or connection. It wakes on a cadence (an interval like `"1h"`, or a cron schedule) and does coordination work: rolling up analytics, cleaning up expired rows, polling an upstream API. Because there is only ever one leader, a `@scheduled` task runs **at most once** per due tick across the planet, which is exactly what you want for work that must not double-fire.
+
+L4 is the highest-latency, most-consistent tier: it is far from any single user, but it is the one place where "do this exactly once, globally" is true.
+
+```ts
+// L4: one leader worldwide runs this hourly.
+@daemon
+class Jobs {
+    @scheduled('1h')
+    hourly(): void {
+        // rollups, cleanup, polling an upstream, ...
+    }
+}
+```
+
+See [Daemons](../background/daemons.md).
+
+## How code is routed to a tier
+
+You do not configure tiers. You opt into one by adding an **entry file** with the right name and using the matching **surface decorator**. A surface decorator is the top-level decorator that says what kind of endpoint a class is (`@rest`, `@stream`, `@daemon`).
+
+At build time, `toiljs build` runs the compiler once per tier and hands each pass only the code that belongs to it. Each tier compiles into its own WebAssembly file (its own `.wasm` **artifact**), so the request build never carries stream or daemon code, and vice versa.
+
+| Entry file (`server/`) | Surface decorator | Artifact | Tier |
+| --- | --- | --- | --- |
+| `main.ts` | `@rest`, `@service` / `@remote` | `release.wasm` | L1 request |
+| `main.stream.ts` | `@stream` | `release-stream.wasm` | L2 / L3 stream |
+| `main.daemon.ts` | `@daemon`, `@scheduled` | `release-cold.wasm` | L4 daemon |
+
+Shared building blocks carry no tier of their own. Your [`@data` classes](../backend/data.md) and your [`@database` schema](../database/README.md) are compiled into *every* artifact, because any tier may need to read or write the database. The stream and daemon tiers are opt-in: a project with no `@stream` and no `@daemon` just builds the single `release.wasm` and behaves exactly like a request-only app.
+
+For the entry-file conventions and the full build flow, see [Project structure](../getting-started/project-structure.md).
+
+## Why tiers matter: latency vs consistency
+
+Picking a tier is a trade-off between two things a junior developer should keep in mind:
+
+- **Latency** (how fast a single user gets an answer): lower tiers win. L1 runs on the node the user already reached.
+- **Consistency and shared state** (many actors agreeing on one thing): higher tiers win. L4 has exactly one copy in the world, so it is trivially consistent, but it is far from everyone.
+
+A rule of thumb:
+
+- Answering one request as fast as possible: **L1**.
+- Keeping per-connection state for one live client: **L2**.
+- Letting many connected clients across a continent share one box's state: **L3**.
+- Doing a job exactly once, globally, on a schedule: **L4**.
+
+## Gotchas
+
+- **L1 fields reset every request.** If you set a field in one request and read it in the next, it will be gone. Persist to [ToilDB](../database/README.md) instead.
+- **A project using `@stream` may not also declare `@service` or `@remote`** anywhere (the compiler enforces this). Streams and RPC live in different artifacts. Keep them in separate entry files (`main.stream.ts` vs `main.ts`).
+- **There is at most one `@daemon` class per project.** It compiles only into the cold artifact; a `@daemon` in the request build is a compile error.
+- **Higher tier is not "better".** Do not reach for L4 to hold shared state you read on every request; that adds a long hop. Use the database for shared reads, and the daemon only for scheduled, run-once work.
+
+## Related
+
+- [Backend overview](../backend/README.md): the L1 request model in depth.
+- [REST](../backend/rest.md) and [RPC](../backend/rpc.md): the L1 surfaces.
+- [Realtime streams](../realtime/streams.md): the L2 / L3 surface and `StreamScope`.
+- [Daemons](../background/daemons.md) and [@derive](../background/derive.md): scheduled and background work.
+- [The database (ToilDB)](../database/README.md): where shared, persistent state lives.
+- [Decorators](./decorators.md): the full list of surface decorators and their tiers.
+- [Project structure](../getting-started/project-structure.md): entry files and the build.

package/docs/concepts/types.md

@@ -0,0 +1,216 @@
+# The server type system
+
+Your backend is TypeScript, but a stricter, faster dialect of it. Numbers have an exact bit width (`u32`, `i64`, `f64`, and friends) instead of one loose `number`, and a few TypeScript features do not exist. This page explains the types you write in `server/` code.
+
+## Why the server types are different
+
+Your frontend TypeScript runs in a browser, where a JavaScript engine figures out types as it goes. Your **server** code is different: the **toilscript** compiler turns it into [WebAssembly](../backend/README.md) (WASM), a compact machine-like binary. To emit that binary, the compiler must know the *exact* size of every value ahead of time. "A number" is not enough; it needs to know "a 32-bit unsigned integer" so it can pick the right machine instruction and lay out memory.
+
+toilscript is built on **AssemblyScript**, a strict subset of TypeScript designed to compile to WASM. So the server language looks and reads like TypeScript, but every number is a fixed-width type, and there is no room for the fuzzy parts of JavaScript. The payoff is speed and safety: your code compiles to something close to hand-written native code, and whole classes of bugs cannot occur.
+
+You already know the syntax. You only need to learn the number types and a handful of rules.
+
+## The number types
+
+There is no plain `number` in server code. Instead you pick the exact type. The name tells you three things: signed or unsigned, how many bits, integer or float.
+
+- The letter: `u` = unsigned integer (zero and up), `i` = signed integer (can be negative), `f` = floating-point (has a fractional part).
+- The number: how many bits wide it is.
+
+| Type | Kind | Bits | Range | Use it for |
+| --- | --- | --- | --- | --- |
+| `bool` | boolean | 1 | `true` / `false` | flags, yes/no |
+| `u8` | unsigned int | 8 | 0 to 255 | a byte, a small enum |
+| `u16` | unsigned int | 16 | 0 to 65,535 | ports, small counts |
+| `u32` | unsigned int | 32 | 0 to ~4.29 billion | sizes, ids, most counts |
+| `u64` | unsigned int | 64 | 0 to ~1.8e19 | timestamps (ms), big counters, large ids |
+| `i8` | signed int | 8 | -128 to 127 | tiny signed values |
+| `i16` | signed int | 16 | -32,768 to 32,767 | small signed values |
+| `i32` | signed int | 32 | ~-2.1 to 2.1 billion | the default integer; loop counters, deltas |
+| `i64` | signed int | 64 | ~-9.2e18 to 9.2e18 | large signed counts, database counters |
+| `f32` | float | 32 | ~7 decimal digits | low-precision decimals (rare) |
+| `f64` | float | 64 | ~15-16 decimal digits | any value with a fraction: prices, ratios, math |
+
+There are also 128-bit and 256-bit integers (`u128`, `i128`, `u256`, `i256`) for cryptography and very large ids. See [Big integers](#big-integers-u128-to-u256) below.
+
+### Which one should I pick?
+
+When in doubt, use these defaults and you will rarely be wrong:
+
+- A counter, a size, a loop index, an id you do not do math on: **`u32`** (or `i32` if it can go negative).
+- A millisecond timestamp, a like count that might grow huge, or a value that must never wrap: **`u64`** / **`i64`**.
+- Anything with a decimal point (money, averages, percentages): **`f64`**.
+- A true/false flag: **`bool`**.
+- One raw byte, or an element of a byte buffer: **`u8`**.
+
+Smaller types do not make your program meaningfully faster; they exist to match binary layouts and save memory in big arrays. Default to 32-bit unless a value is genuinely large or genuinely a byte.
+
+## Integer overflow: it wraps, it does not throw
+
+This is the single most important difference from everyday JavaScript. Integer math is **modular**: if a value goes past the top of its range, it silently wraps around to the bottom (two's complement). It never throws an error and never turns into a bigger type on its own.
+
+```ts
+let x: u8 = 255;
+x = x + 1;   // x is now 0, not 256 (wrapped around)
+
+let y: u8 = 0;
+y = y - 1;   // y is now 255 (wrapped the other way)
+
+let z: i32 = 2147483647; // the largest i32
+z = z + 1;               // z is now -2147483648 (wrapped to the minimum)
+```
+
+The lesson: choose a type wide enough that your values cannot reach its edge. A counter that could exceed ~4.29 billion needs `u64`, not `u32`. Timestamps in milliseconds always use `u64`.
+
+Floating-point (`f32` / `f64`) does not wrap; it follows the usual IEEE rules (very large values become `Infinity`, `0/0` is `NaN`).
+
+## Casting between number types
+
+Because types are explicit, the compiler will not silently mix them. To convert, cast. There are two equivalent spellings; use whichever reads better:
+
+```ts
+const big: u64 = 300;
+const small: u8 = big as u8;   // "as" form
+const small2 = u8(big);        // call the type like a function
+```
+
+Casting a wider integer into a narrower one **truncates**: it keeps only the low bits, so `u8(300)` is `44` (300 wraps modulo 256). Casting a float to an integer drops the fraction toward zero (`i32(3.9)` is `3`). None of these throw, so cast deliberately.
+
+```ts
+const f: f64 = 3.9;
+const i = i32(f);   // 3 (fraction dropped)
+const n = u8(300);  // 44 (truncated to 8 bits)
+```
+
+Integer division also truncates (it is not float division):
+
+```ts
+const half = 5 / 2;        // both operands are i32 -> result is 2, not 2.5
+const real = 5.0 / 2.0;    // f64 division -> 2.5
+```
+
+## `bool`
+
+`bool` is a real 1-bit type, not "any truthy value". Comparisons (`==`, `<`, `>=`) produce a `bool`, and `if`/`while` expect one. It stores as 0 or 1.
+
+## Big integers: `u128` to `u256`
+
+For values too large for 64 bits, toilscript provides `u128`, `i128`, `u256`, and `i256` as native global types (no import needed). They support the normal operators (`+`, `-`, `*`, `/`, `==`, `<`, `<<`, and so on) through operator overloading, plus static helpers like `u256.fromString(...)` and instance methods like `.toString()`, `.toBytes()`, and `.toUint8Array()`.
+
+```ts
+const a = u256.fromString('123456789012345678901234567890');
+const b = a + u256.One;
+const hex = b.toString(16);
+```
+
+These are mainly for cryptography and very large ids. Everyday counts and sizes should stay in `u32` / `u64`.
+
+### `ToilUserId`: a 256-bit identity
+
+The built-in auth system represents a logged-in user as a **`ToilUserId`**, a stable 256-bit value (four `u64` words) derived from their key, identifier, and your domain. It is a global type, like `crypto`. It is the right key to store per-user data on. Comparison is overloaded and O(1), and `.toHex()` gives you a 64-character string key.
+
+```ts
+const id: ToilUserId = AuthService.userId()!; // the current user's stable id
+const key = id.toHex();                        // a convenient string key
+```
+
+Full reference (including the `==` null-check gotcha) is in [Extending auth](../auth/extending.md).
+
+## Strings
+
+Strings work as you expect: `'hello'`, template literals, `.length`, `.substring(...)`, `+` to concatenate. Under the hood a server string is **UTF-16** (the same 16-bit code units as JavaScript), so `.length` counts code units, not visible characters or bytes.
+
+When you need the **bytes** of a string (to hash it, write it to a binary body, or send it over a stream), encode it explicitly. UTF-8 is almost always what you want on the wire:
+
+```ts
+const buf: ArrayBuffer = String.UTF8.encode('hello'); // UTF-8 bytes
+const text: string = String.UTF8.decode(buf);         // back to a string
+```
+
+`String.UTF8.byteLength(s)` gives the encoded byte length. There is a matching `String.UTF16` namespace when you need raw UTF-16 bytes.
+
+## Binary data: `Uint8Array`
+
+Raw bytes are a `Uint8Array` (a fixed-length array of `u8`), exactly like the browser type. It is the standard currency for request bodies, hashes, crypto keys, and stream packets.
+
+```ts
+const bytes = new Uint8Array(32);
+bytes[0] = 0xff;          // each element is a u8
+const n: i32 = bytes.length;
+```
+
+You will also see `StaticArray<u8>` (a fixed-size, lower-overhead byte array) and `ArrayBuffer` (a raw buffer that `Uint8Array` and the encoders view). For most app code, `Uint8Array` is all you need.
+
+## Arrays and collections
+
+Typed arrays and the familiar collection types are available and must be typed:
+
+```ts
+const nums: i32[] = [1, 2, 3];        // Array<i32>
+const names = new Array<string>();
+const seen = new Map<string, u32>();
+const tags = new Set<string>();
+```
+
+`Array`, `Map`, and `Set` behave like their JavaScript counterparts (`.push`, `.get`, `.has`, `.forEach`), but every element type is fixed at compile time. There is no mixed-type array.
+
+## Objects: `@data` classes, not object literals
+
+Server code has no free-form object type. A structured value is a **class**, and to send it between the browser and the server (or in and out of the database) you tag it `@data`. That makes the compiler generate a binary codec plus a matching client type. See [Data types](../backend/data.md).
+
+```ts
+@data
+class Player {
+    username: string = '';
+    score: u64 = 0;
+    constructor(username: string = '', score: u64 = 0) {
+        this.username = username;
+        this.score = score;
+    }
+}
+```
+
+## Key differences from normal TypeScript
+
+| Thing | Normal TypeScript | Server (toilscript) |
+| --- | --- | --- |
+| Numbers | one `number` | explicit `u8` / `i32` / `u64` / `f64` / ... |
+| `number` type | everywhere | avoid it; pick a fixed-width type |
+| `any` | allowed | not allowed: everything is typed |
+| Integer overflow | numbers just get bigger | wraps around silently |
+| `/` on integers | `5 / 2` is `2.5` | `5 / 2` is `2` (truncates) |
+| Mixing number types | implicit | explicit cast (`x as u8` / `u8(x)`) |
+| npm packages | `import` anything | only toilscript's standard library and toiljs APIs |
+| `undefined` | common | use `null` (a `T | null`), not `undefined` |
+| Objects | `{ a: 1 }` literals | a `class` (usually `@data`) |
+| Strings | UTF-16 | UTF-16 (same), encode to bytes for the wire |
+
+A few rules worth stating plainly:
+
+- **No `any`.** Every value has a concrete type. This is what makes the code compile to WASM at all.
+- **No arbitrary npm.** Server code cannot pull in npm packages; it uses the toilscript standard library (the types on this page) plus the toiljs host APIs (database, crypto, email, and so on). This is the sandbox that keeps the edge safe.
+- **No plain `number`.** If you write `number`, it resolves to `f64` (a float), which is almost never what you want for an id or a count. Always pick an explicit type.
+- **Use `null`, not `undefined`,** for "no value": a nullable is written `T | null` and you narrow it with an `if (x != null)` check or a `!` assertion when you are sure.
+
+## How server types cross to the browser
+
+When a `@data` value or an RPC result travels to your frontend, the compiler maps each server type to a matching TypeScript type in the generated client. You do not write this mapping; it is generated. It matters because it tells you what your React code receives.
+
+| Server type | Browser (generated TS) |
+| --- | --- |
+| `u8`, `u16`, `u32`, `i8`, `i16`, `i32`, `f32`, `f64` | `number` |
+| `u64`, `i64`, `u128`, `i128`, `u256`, `i256` | `bigint` |
+| `bool` | `boolean` |
+| `string` | `string` |
+| a `@data` class `T` | the generated class `T` |
+| `T[]` | `T[]` |
+
+The important row is the 64-bit-and-larger integers: they become `bigint` on the client and travel as decimal strings on the JSON wire, so they stay **exact at any size** (they never lose precision the way a giant JavaScript `number` would). See [RPC](../backend/rpc.md) for the generated client.
+
+## Related
+
+- [Data types (`@data`)](../backend/data.md): defining structs that cross the wire and the database.
+- [RPC and the generated client](../backend/rpc.md): how server types map to browser types.
+- [Extending auth](../auth/extending.md): the `ToilUserId` 256-bit identity in full.
+- [The database (ToilDB)](../database/README.md): the collections your typed keys and values live in.
+- [Decorators](./decorators.md): the decorators referenced throughout this page.

package/docs/database/README.md

@@ -0,0 +1,143 @@
+# ToilDB
+
+ToilDB is the database built into toiljs. It is **global**, it needs **no setup or connection string**, and your backend talks to it with plain typed method calls.
+
+If you have used Postgres, MySQL, or MongoDB before, ToilDB will feel a little different, and this page explains why. If you have never used a database, that is fine too: read on and every term is defined as it appears.
+
+## What "a globally distributed edge database" means
+
+Let us take that phrase one word at a time.
+
+- A **database** is a place your program stores data so it is still there on the next request. Your handler runs, finishes, and forgets everything in memory (a fresh WebAssembly instance runs each request), so anything you want to keep, a user account, a like count, a guestbook entry, has to go into a database.
+- The **edge** is a network of servers spread around the world, each one physically close to some of your users. Your compiled backend runs on the edge server nearest whoever is calling it. (For the full picture of where code runs, see [Tiers](../concepts/tiers.md).)
+- **Globally distributed** means the database is not one machine in one city. Its data lives on many machines in many regions at once. A user in Tokyo and a user in Paris each read from a copy near them, so reads are fast everywhere instead of fast in one place and slow everywhere else.
+
+Put together: ToilDB is storage that lives out on that same worldwide edge, next to your code, so a database read does not have to fly across an ocean and back.
+
+```mermaid
+flowchart LR
+    subgraph edge["Dacely edge (worldwide)"]
+        direction LR
+        H1["Your backend<br/>(Tokyo)"] --> D1[("ToilDB<br/>copy near Tokyo")]
+        H2["Your backend<br/>(Paris)"] --> D2[("ToilDB<br/>copy near Paris")]
+    end
+    D1 <-->|"replication<br/>(keeps copies in sync)"| D2
+    UA["User in Tokyo"] --> H1
+    UB["User in Paris"] --> H2
+```
+
+You never pick a region, open a connection, or run a migration script. You declare what you want to store (see [Setup](./setup.md)) and ToilDB is there.
+
+## Why seven families instead of one big "table"
+
+Most databases give you one general-purpose tool: a table (or a collection) that you read and write however you like. That is flexible, but on a system spread across the whole planet, the flexible tool is also the slow and error-prone tool. The classic example is a counter. If two servers on opposite sides of the world both try to do "read the number, add one, write it back" at the same moment, one of the two increments is silently lost, because each read the same starting value.
+
+ToilDB solves this by giving you **seven specialized collection types**, called **families**. Each family is tuned for one job and exposes only the operations that are safe and fast for that job. A counter family, for instance, has no "set to this value" operation at all: you can only `add` a delta, and the database merges concurrent deltas from around the world without losing any. You cannot misuse it, because the unsafe operation does not exist.
+
+So instead of one generic table you reach for, you pick the family that matches what you are doing. Picking the right one is the main skill, and the guide below walks you through it.
+
+The seven families are:
+
+| Family | It stores | Read a page |
+| --- | --- | --- |
+| **Documents** | Records you look up by id (users, posts, orders). | [Documents](./documents.md) |
+| **Unique** | A claim on a value that must be one-of-a-kind (usernames, emails, slugs). | [Unique](./unique.md) |
+| **Counter** | A running total that many callers increment at once (likes, views). | [Counters](./counters.md) |
+| **Events** | An append-only log of things that happened (feeds, audit trails). | [Events](./events.md) |
+| **Capacity** | A limited quantity you hand out without overselling (tickets, seats). | [Capacity](./capacity.md) |
+| **Membership** | Sets of "who belongs to what" (followers, tags, room members). | [Membership](./membership.md) |
+| **View** | A precomputed, read-optimized snapshot (home pages, leaderboards). | [Views](./views.md) |
+
+## The one idea shared by all seven: key then value
+
+Every family, underneath, works the same way: it maps a **key** to a **value**.
+
+- A **key** is how you find your data. Think of it as the label on a drawer: a user id, a username, a room name.
+- A **value** is what is in the drawer: the user record, the owner of a username, the members of a room.
+
+In ToilDB, both the key and the value are ordinary TypeScript classes that you tag with `@data`. The `@data` tag tells toilscript (the compiler that turns your backend into WebAssembly) how to pack that class into bytes for storage and unpack it again. You write a normal class with normal fields, give each field a default, and the compiler does the rest.
+
+```ts
+// A key: how you address one record.
+@data
+class UserId {
+  id: string = '';
+  constructor(id: string = '') { this.id = id; }
+}
+
+// A value: what you store under that key.
+@data
+class User {
+  id: string = '';
+  name: string = '';
+  score: u64 = 0;
+}
+```
+
+You then declare a collection that maps that key type to that value type, for example `Documents<UserId, User>`. Every family is generic over its key and value types in exactly this way, so once you understand `@data` keys and values you understand all seven. The full `@data` reference is on the [data types page](../backend/data.md); how to declare collections is on [Setup](./setup.md).
+
+## Eventual consistency, in plain words
+
+Because ToilDB keeps copies of your data in many regions, there is one honest trade-off you need to understand: **eventual consistency**.
+
+Every key has one **home**: a single region that officially owns that key's data. All **writes** to a key travel to its home, where they are applied one at a time, in order. That is what makes writes safe: even if a thousand servers write the same key at once, the home lines them up so nothing is lost or corrupted.
+
+**Reads**, on the other hand, are served from the copy nearest the reader, which is fast but may be a beat behind. After a write lands at the home, it takes a brief moment (usually milliseconds) to fan out to the other regions' copies. During that moment, a reader in another region might still see the previous value. The copies always catch up; they are *eventually* consistent, not *instantly* consistent everywhere.
+
+What this means in practice:
+
+- **It is usually invisible.** The lag is tiny, and most apps never notice.
+- **Do not assume a write is visible everywhere the instant it returns.** For example, right after you create a record, a read from a far-away region might briefly not see it yet.
+- **Some families are stronger.** Because writes to a single key are serialized at its home, operations that must never race, claiming a unique username, reserving the last ticket, are decided at the home and are safe. The Unique and Capacity families lean on this so two callers can never both win. See [Unique](./unique.md) and [Capacity](./capacity.md).
+
+Each family page spells out its own consistency behavior, so you always know what to expect.
+
+## Choosing a family: the decision guide
+
+Start from what you are trying to do, not from a data structure. This table maps a real need to the family that was built for it.
+
+| I need to... | Use | Why |
+| --- | --- | --- |
+| Store and update a thing I look up by id (a user, a post, an order). | **Documents** | The general-purpose record store: create, read, update, delete by key. |
+| Guarantee a value is used by only one owner across the whole world (username, email, slug). | **Unique** | Claims are decided at the key's home, so two people cannot claim the same name. |
+| Count something that many people bump at the same time (likes, page views, stock tally). | **Counter** | Concurrent `add`s from anywhere merge without ever losing an increment. |
+| Keep a growing list of things that happened, in order (activity feed, audit log). | **Events** | Append-only: you add events and read the newest, but never edit history. |
+| Hand out a limited quantity and never sell more than exist (tickets, seats, inventory). | **Capacity** | Reserve/confirm/cancel holds at the home prevent overselling. |
+| Track which members belong to a set (followers, tags, room members, permissions). | **Membership** | Add/remove/check membership without loading a whole record to edit a list. |
+| Serve a precomputed, ready-to-render result quickly (leaderboard, home page snapshot). | **View** | A background job computes it once; requests read it with a single fast lookup. |
+
+If two families seem to fit, this flowchart resolves it. Read it top to bottom.
+
+```mermaid
+flowchart TD
+    START["What are you storing?"] --> Q1{"Is it a running<br/>total (a number many<br/>callers increase)?"}
+    Q1 -->|Yes| COUNTER["Counter"]
+    Q1 -->|No| Q2{"Must a value be<br/>one-of-a-kind across<br/>everyone (username,<br/>email, slug)?"}
+    Q2 -->|Yes| UNIQUE["Unique"]
+    Q2 -->|No| Q3{"Is it a limited stock<br/>you must not oversell<br/>(tickets, seats)?"}
+    Q3 -->|Yes| CAPACITY["Capacity"]
+    Q3 -->|No| Q4{"Is it an append-only<br/>log of events that<br/>happened, kept in order?"}
+    Q4 -->|Yes| EVENTS["Events"]
+    Q4 -->|No| Q5{"Is it a set of members<br/>you add/remove/check<br/>(followers, tags)?"}
+    Q5 -->|Yes| MEMBERSHIP["Membership"]
+    Q5 -->|No| Q6{"Is it a precomputed<br/>read-only snapshot a<br/>background job builds?"}
+    Q6 -->|Yes| VIEW["View"]
+    Q6 -->|No| DOCUMENTS["Documents<br/>(the default record store)"]
+```
+
+A quick sanity check when you land somewhere: **Documents is the default.** If you are storing "a thing with fields that I update by id," it is almost always Documents. The other six exist for the specific jobs above where Documents would be slow, unsafe under concurrency, or awkward.
+
+Real apps mix families freely. The demo guestbook, for example, uses **Events** for the log of signatures, a **Counter** for the running total, and a **View** for the ready-to-serve snapshot, all in one small feature.
+
+## Where to go next
+
+- [Setup](./setup.md): declare a database, its collections, and reach them from a handler.
+- [Documents](./documents.md): the general-purpose record store (start here).
+- [Unique](./unique.md), [Counters](./counters.md), [Events](./events.md), [Views](./views.md), [Membership](./membership.md), [Capacity](./capacity.md): the specialized families.
+
+## Related
+
+- [Setup](./setup.md): how to declare `@database`, `@collection`, and `@data` types.
+- [Data types (`@data`)](../backend/data.md): the typed keys and values every family uses.
+- [Tiers](../concepts/tiers.md): where your backend and its data run.
+- [Decorators](../concepts/decorators.md): `@query`, `@action`, `@derive`, and friends.