toiljs 0.0.85 → 0.0.87

package/docs/daemon.md

@@ -1,123 +0,0 @@
-# Daemon
-
-`@daemon` declares a single, leader-elected background worker for your domain -
-the **L4** (global) coordination tier of the Toil edge. Where a `@rest` handler
-is a fresh instance per request and a `@stream` box is one instance per
-connection, there is exactly **one** daemon per domain at a time. The edge keeps
-a warm standby ready and fails over at-most-once, so the daemon is the right
-place for work that must happen once globally rather than once per request.
-
-```ts
-@daemon
-class Jobs {
-  @scheduled('1h')
-  hourly(): void {
-    // Runs once an hour on the elected leader. Put recurring background work
-    // here (rollups, cleanup, polling an upstream, ...).
-  }
-}
-```
-
-## `@daemon` classes
-
-`@daemon` marks a class as the domain's background worker. The class is resident:
-it is created once on the elected leader and lives for as long as that leader
-holds the lease, so its fields persist across scheduled runs (a `@rest`
-handler's fields would reset every request).
-
-Exactly one daemon instance runs per domain at any moment. A second node stays a
-warm standby and only becomes active if the current leader's lease lapses. You do
-not start, stop, or place the daemon yourself - the edge elects the leader and
-drives it.
-
-## `@scheduled`
-
-A `@scheduled` method declares a task that fires on a cadence, always on the
-**elected leader**. The single string argument is the cadence:
-
-```ts
-@scheduled('1h')
-hourly(): void { /* ... */ }
-```
-
-- **Interval strings** like `'1h'` fire on that fixed period.
-- **Cron expressions** are also supported when you need a wall-clock schedule
-  rather than a fixed interval.
-
-A class can declare several `@scheduled` methods; each runs on its own cadence.
-Because only the leader fires them, a task runs once per domain per tick, not
-once per node.
-
-## The daemon entry
-
-The daemon surface has its own entry module, `server/main.daemon.ts`. It imports
-the `@daemon` classes so the compiler-generated `daemon_start` / `scheduled_tick`
-exports are pulled into the artifact:
-
-```ts
-// server/main.daemon.ts
-import { revertOnError } from 'toiljs/server/runtime/abort/abort';
-
-import './daemon/Jobs';
-
-// The abort hook (the daemon box reports a trap through it). NOTE: unlike main.ts /
-// main.stream.ts, the daemon entry does NOT re-export the request runtime - a cold
-// artifact exposes daemon_start/scheduled_tick, not the request `handle`.
-export function abort(message: string, fileName: string, line: u32, column: u32): void {
-  revertOnError(message, fileName, line, column);
-}
-```
-
-Note what is **not** here: unlike `main.ts` and `main.stream.ts`, the daemon
-entry does not `export * from 'toiljs/server/runtime/exports'`. A daemon (cold)
-artifact exposes `daemon_start` and `scheduled_tick`, not the request `handle`.
-Add a daemon as you grow by importing its module here.
-
-## Build
-
-`toiljs build` runs one toilscript pass per tier and hands each pass only the
-entries that belong to it. When the project declares a `@daemon` / `@scheduled`
-surface, the daemon pass compiles `server/main.daemon.ts` into its own artifact,
-`build/server/release-cold.wasm`:
-
-```sh
-$ ls build/server/*.wasm
-build/server/release.wasm          # L1 request    (exports: handle)
-build/server/release-stream.wasm   # L2/L3 stream   (exports: stream_dispatch)
-build/server/release-cold.wasm     # L4 daemon      (exports: daemon_start, scheduled_tick)
-```
-
-So `release.wasm` never contains `scheduled_tick` and the daemon artifact never
-contains the request `handle`. Plain `@data` and helper modules are shared into
-every artifact. See [Tiers](./tiers.md) for how the three artifacts are produced
-from one source tree.
-
-## Use cases
-
-The daemon is the once-per-domain tier, so it fits work you want to happen
-globally on a cadence rather than per request:
-
-- **Periodic rollups** - aggregate counters or events into summaries.
-- **Cleanup** - expire stale rows, prune logs, reclaim resources.
-- **Polling an upstream** - pull from an external API on a schedule.
-- **Global coordination** - any task that must run exactly once across the
-  domain, not once per node.
-
-## Failover
-
-Scheduling is **at-most-once**. A `@scheduled` task fires on whichever node
-currently holds the leader lease. If that leader fails, the warm standby takes
-over and fires the **subsequent** runs; the edge does not retry or duplicate the
-tick that was in flight when the leader was lost. This trades exactly-once
-delivery for the guarantee that two nodes never run the same scheduled tick at
-once, so design tasks to be safe to skip an occasional run and to be idempotent
-where a missed run matters.
-
----
-
-See also:
-
-- [Tiers](./tiers.md) - the three deployment tiers and how one source tree
-  compiles to a separate artifact per tier.
-- [Streams](./streams.md) - the L2/L3 `@stream` tier (one resident box per
-  connection).

package/docs/data.md

@@ -1,131 +0,0 @@
-# Data codec (`@data`)
-
-`@data` turns a plain class into a typed, versionable value with a deterministic
-binary codec and a JSON codec. It is the backbone of request/response bodies,
-RPC arguments, sessions, and anything you persist. The same class becomes a
-fully typed client type in the generated `shared/server.ts` (see
-[RPC](./rpc.md)).
-
-```ts
-@data
-class Player {
-  username: string = '';
-  admin: bool = false;
-  score: u64 = 0;
-}
-```
-
-From that the compiler synthesizes, on the class:
-
-- `encode(): Uint8Array` / `static decode(buf): T`, the binary codec (with a
-  4-byte type id prefix).
-- `encodeInto(w: DataWriter)` / `static decodeFrom(r: DataReader)`, the codec
-  without the type-id frame, for nesting.
-- `toJSON()` / `static fromJSON(v)`, the JSON codec (64-bit-and-larger integers
-  as decimal strings, so they survive `JSON.parse` exactly).
-- `static dataId(): u32`, a stable FNV-1a hash of the class name, written as the
-  type-id prefix by `encode()`.
-
-Fields may be scalars (`u8`..`u256`, `i8`..`i256`, `f32`, `f64`, `bool`),
-`string`, a nested `@data` class, or an array `T[]` of any of these. Give every
-field a default; the generated decoder and the client constructor use them.
-
-## Using `@data` in routes
-
-In a **JSON** route, a `@data` parameter is revived from the parsed body and a
-`@data` return value is serialized with `toJSON()`. In a **Binary** route, the
-parameter is `decode`d from the raw body and the return value is `encode`d. The
-route's stream mode (see [Routing](./routing.md#data-streams)) picks which.
-
-```ts
-@post('/')                       // JSON route
-public create(input: NewPlayer): Player { /* input from JSON, Player to JSON */ }
-
-@route({ method: Methods.POST, path: '/blob', stream: DataStream.Binary })
-public blob(input: FileData): FileResult { /* input.decode, result.encode */ }
-```
-
-## The binary codec: `DataWriter` / `DataReader`
-
-When you need to lay out bytes yourself, custom bodies, session payloads,
-challenge messages, use the codec directly. It lives in the `data` module:
-
-```ts
-import { DataWriter, DataReader } from 'data';
-```
-
-The codec has a byte-for-byte identical TypeScript implementation in
-`toiljs/io` (`src/io/codec.ts`), so the client can read and write the exact same
-wire format the wasm guest does.
-
-### `DataWriter`
-
-Every writer method returns the writer for chaining.
-
-| Method | Signature | Wire format |
-| --- | --- | --- |
-| `writeU8` / `writeI8` | `(v): DataWriter` | 1 byte |
-| `writeU16` / `writeI16` | `(v): DataWriter` | 2 bytes, little-endian |
-| `writeU32` / `writeI32` | `(v): DataWriter` | 4 bytes, LE |
-| `writeU64` / `writeI64` | `(v): DataWriter` | 8 bytes, LE |
-| `writeF32` / `writeF64` | `(v): DataWriter` | 4 / 8 bytes, IEEE-754 LE |
-| `writeBool` | `(v): DataWriter` | 1 byte (`1`/`0`) |
-| `writeBytes` | `(b: Uint8Array): DataWriter` | `u32` length (LE) + raw bytes |
-| `writeString` | `(s: string): DataWriter` | `u32` length (LE) + UTF-8 bytes |
-| `writeU128` / `writeI128` | `(v): DataWriter` | two `u64` limbs (lo, hi) |
-| `writeU256` / `writeI256` | `(v): DataWriter` | four `u64` limbs (lo1, lo2, hi1, hi2) |
-| `length` | `(): i32` | bytes written so far |
-| `toBytes` | `(): Uint8Array` | an exact-length copy of the buffer |
-
-### `DataReader`
-
-Reads are bounds-safe: an over-read never traps. It returns a zero/empty default
-and sets the public `ok` flag to `false`. Check `ok` after a sequence of reads
-to detect a truncated or malformed buffer.
-
-| Method | Signature | On over-read |
-| --- | --- | --- |
-| `readU8` / `readI8` | `(): u8 / i8` | `0` |
-| `readU16`..`readU64`, `readI16`..`readI64` | `(): integer` | `0` |
-| `readF32` / `readF64` | `(): f32 / f64` | `0` |
-| `readBool` | `(): bool` | `false` |
-| `readBytes` | `(): Uint8Array` | empty array |
-| `readString` | `(): string` | `""` |
-| `readU128`/`readI128`/`readU256`/`readI256` | `(): bignum` | `0` |
-| `remaining` | `(): i32` | bytes left unread |
-| `ok` | `bool` (field) | `false` once any read over-ran |
-
-### Example
-
-```ts
-import { DataWriter, DataReader } from 'data';
-
-// Write: u8 version, str name, u64 score, bytes blob
-const out = new DataWriter()
-  .writeU8(1)
-  .writeString('alice')
-  .writeU64(1234)
-  .writeBytes(payload)
-  .toBytes();
-
-// Read it back
-const r = new DataReader(out);
-const version = r.readU8();
-const name = r.readString();
-const score = r.readU64();
-const blob = r.readBytes();
-if (!r.ok) return Response.badRequest('truncated');
-```
-
-## Notes
-
-- **Endianness.** The AS guest codec is little-endian. The TypeScript `toiljs/io`
-  codec defaults to little-endian and also accepts a per-call `be` flag for
-  big-endian network formats; keep both ends on the same setting.
-- **Field order is the format.** The binary layout is exactly the field
-  declaration order. Reordering fields, or changing a type, is a breaking format
-  change. Add new fields at the end and bump a leading version byte if you need
-  to evolve a hand-rolled payload.
-- **`encode()` carries a type id.** The 4-byte `dataId()` prefix lets a decoder
-  confirm it is reading the type it expects. `encodeInto`/`decodeFrom` skip the
-  frame for nesting one `@data` value inside another.

package/docs/derive.md

@@ -1,159 +0,0 @@
-# Derive (materialized views)
-
-`@derive` precomputes a read-optimized **view** from your data so reads stay
-fast and never scan. A request handler (`@get` runs as a *query*, `@post`/`@put`/
-`@delete` as an *action*) is not allowed to scan, reading "the latest N events"
-or "every member of a set" could fan out across unbounded rows, so those scans
-are barred on the request path. A `@derive` does the scan **off** the request
-path: it folds your event log / counters into a `View`, and your route serves
-that view with a single keyed read.
-
-```ts
-@database
-class GuestbookDb {
-  @collection static entries: Events<GuestKey, GuestEntry>;
-  @collection static totals: Counter<GuestKey>;
-  @collection static book: View<GuestKey, GuestbookView>;
-
-  // Recompute the view from the sources. Runs after a signature is written
-  // (and when a box first loads). A derive MAY scan + publish; a route may not.
-  @derive
-  recompute(): void {
-    const key = new GuestKey('main');
-    const view = new GuestbookView();
-    view.total = GuestbookDb.totals.get(key);      // counter read
-    view.entries = GuestbookDb.entries.latest(key, 10); // scan, allowed here
-    GuestbookDb.book.publish(key, view);           // publish the materialized view
-  }
-}
-```
-
-## Why a derive
-
-ToilDB gates every data op by the *function kind* it runs under:
-
-- **query** (`@get`/`@head`) and **action** (`@post`/`@put`/`@patch`/`@delete`)
-  may do keyed reads and (actions only) writes, but **not scans**
-  (`events.latest`, `membership.list`).
-- **derive** may do everything a read can, **plus** scans, plus
-  `view.publish`/`append`/`counter.add`.
-
-So if a page needs "the 10 newest entries" or "the leaderboard", you cannot read
-that directly in the `@get`. Instead a `@derive` builds it once into a `View`,
-and the `@get` reads the view by key, which is not a scan.
-
-## Declaring a derive
-
-A derive is a method on your `@database` class, alongside the collections it
-reads and the `View` it writes:
-
-```ts
-@database
-class MyDb {
-  @collection static events: Events<Key, Fact>;   // a source
-  @collection static home: View<Key, HomePage>;    // the materialized view
-
-  @derive
-  rebuild(): void {
-    // read sources, build the value, publish it
-  }
-}
-```
-
-Rules:
-
-- A `@derive` method takes **no arguments and returns `void`**.
-- A `@database` may declare **multiple** `@derive` methods; each is run
-  independently.
-- The view value (`HomePage` above) and the key are ordinary `@data` types, so
-  they round-trip through the codec like any other stored value.
-
-## `View<K, V>`
-
-A `View` is a published, read-optimized projection. Its API:
-
-```ts
-view.get(key)       // V | null   - the published view, or null if none yet
-view.require(key)   // V          - like get, but traps if nothing is published
-view.publish(key, value) // void  - overwrite the view (derive/job only)
-```
-
-`publish` is only allowed from a `@derive` (or a `@job`); the host assigns the
-version so a later publish always supersedes an earlier one. `get`/`require` are
-plain keyed reads, allowed from any handler, including a `@get` route.
-
-## When derives run
-
-You never call a derive yourself. The runtime runs it for you:
-
-- **After a write to a source.** When a request writes one of a database's
-  source collections (an `events.append`/`append_once`, a `counter.add`, or a
-  record `create`/`patch`), that database's derives run right after the response
-  is produced, so the view reflects the new data on the next read. Many writes to
-  one database in a single request coalesce into one recompute.
-- **On box load.** When a server box starts or hot-reloads (or the underlying
-  source data changed out of band), the views are rebuilt from their sources
-  before the first read is served. This is also where a value type's `@migrate`
-  runs against old stored events, as the derive re-reads and republishes them.
-
-A derive's own writes (its `view.publish`) never re-trigger it.
-
-The same code runs under `toiljs dev` (the in-process emulator) and on the
-production edge, no flags or wiring to change.
-
-## Reading a view from a route
-
-The route just reads the view by key, which is a non-scan read and so is legal in
-a `@get`:
-
-```ts
-@rest('guestbook')
-class Guestbook {
-  @get('/')
-  list(): GuestbookView {
-    const key = new GuestKey('main');
-    const view = GuestbookDb.book.get(key);
-    return view == null ? new GuestbookView() : view; // empty until first publish
-  }
-
-  @post('/')
-  sign(input: NewMessage): GuestbookView {
-    const key = new GuestKey('main');
-    GuestbookDb.entries.append(key, new GuestEntry(input.author, input.message, 0));
-    GuestbookDb.totals.add(key, 1);
-    // The @derive republishes `book` right after this action returns, so the
-    // entries list is served by GET. The action just acks with the new total
-    // (a counter read is allowed here; a scan is not).
-    const view = new GuestbookView();
-    view.total = GuestbookDb.totals.get(key);
-    return view;
-  }
-}
-```
-
-## How it fits together (the guestbook)
-
-The `examples/basic` guestbook is the end-to-end demo:
-
-1. `POST /guestbook` (an action) appends the signature to an `Events` stream and
-   bumps a `Counter`. It returns the running total, but it does **not** read the
-   entry list (that would be a scan).
-2. The runtime then runs `@derive recompute()` under the derive kind: it scans
-   `entries.latest(...)`, reads the `totals` counter, and `publish`es a fresh
-   `GuestbookView`.
-3. `GET /guestbook` (a query) reads `book.get(...)`, a single keyed read, and
-   returns the precomputed total + newest entries.
-
-Sign twice and the total climbs across requests, because the data lives in
-ToilDB (and its view), not in module memory.
-
-## Notes
-
-- A derive **recomputes** the view from whatever its method reads (here, the
-  latest 10 events). It is a fresh recompute on each trigger, so it suits views
-  built from a bounded read (latest N, a counter total, a small set). Folding an
-  unbounded full event log incrementally is a separate, more advanced pattern.
-- Because publishes are last-writer-wins and a derive recomputes from the source
-  of truth, a view always converges to a correct snapshot of its sources.
-- See also: [`data.md`](data.md) for `@data` value types, and the ToilDB host
-  ABI for the exact `derive_run` / `toildb.derives` contract.