toiljs 0.0.60 → 0.0.62

package/docs/email.md

@@ -5,17 +5,17 @@ toiljs can send transactional email from a route handler. A handler calls
 `emails/` folder, or the stateless `TwoFactor` helper); the edge hands the
 message to a single off-core mailer thread that talks to the provider over the
 kernel network (never the worker cores), and **suspends** the wasm call until the
-provider responds — so a slow send never blocks the worker.
+provider responds, so a slow send never blocks the worker.
 
 Everything here is an ambient **global** (no import), like `crypto` and
 `AuthService`. A tenant that never sends email pulls none of it into its build.
 
-- **`EmailService`** — send one email.
-- **`EmailTemplate`** — a reusable template with `{{placeholder}}` substitution
+- **`EmailService`**, send one email.
+- **`EmailTemplate`**, a reusable template with `{{placeholder}}` substitution
   (plain text and/or HTML).
-- **`emails/*.tsx`** — author emails as React components; the build renders them
+- **`emails/*.tsx`**, author emails as React components; the build renders them
   to static HTML and generates a typed `Emails.<Name>.send(...)`.
-- **`TwoFactor`** — stateless email verification codes (2FA / confirm), no DB.
+- **`TwoFactor`**, stateless email verification codes (2FA / confirm), no DB.
 
 > **The one rule of HTML email:** email clients run **no JavaScript** and strip
 > `<style>`/external CSS. So HTML email is a static, inline-styled string, and
@@ -24,7 +24,7 @@ Everything here is an ambient **global** (no import), like `crypto` and
 
 ## Configure email
 
-Email is a **framework-reserved namespace of the tenant's environment** — the
+Email is a **framework-reserved namespace of the tenant's environment**, the
 same out-of-band [Environment](./environment.md) store that backs
 `Environment.get` / `getSecure`, but the `[email]` block is **host-only**: it is
 read and used in Rust (the off-core mailer) and is **never exposed to the
@@ -35,7 +35,7 @@ On the edge today it lives in the tenant's env secrets file,
 `$TOIL_ENV_DIR/<host>.env.secrets` (default dir `/run/toil/env`), kept `0600` and
 **out of `hosts/`** so the config watcher never sees a credential (the dashboard /
 edge DB replaces this file later). Email config is a set of **reserved
-`TOIL_EMAIL_*` keys** — host-only, stripped from the guest buckets, so a tenant
+`TOIL_EMAIL_*` keys**, host-only, stripped from the guest buckets, so a tenant
 can never read them via `Environment.getSecure`:
 
 ```bash
@@ -57,15 +57,15 @@ reserved namespace the framework consumes.
 When `enabled` is `false` (the default) the host has no email capability and
 `EmailService.send` returns `Disabled`. The env is loaded **lazily** (on the
 first send) and the `api_key` is materialized into a zeroizing secret in host
-memory — never written to logs or `/_admin`. A malformed `[email]` block is
+memory, never written to logs or `/_admin`. A malformed `[email]` block is
 treated as "no email" (the host returns `Disabled`); validate config on the
 dashboard before deploying.
 
 ### Providers
 
-**Resend** (`provider = "resend"`) — a JSON API; `api_key` holds the API key.
+**Resend** (`provider = "resend"`), a JSON API; `api_key` holds the API key.
 
-**Gmail** (`TOIL_EMAIL_PROVIDER=gmail`) — SMTP with Gmail defaults:
+**Gmail** (`TOIL_EMAIL_PROVIDER=gmail`), SMTP with Gmail defaults:
 `smtp.gmail.com`, port `587` (STARTTLS), username = `from`. `TOIL_EMAIL_API_KEY`
 holds a Gmail **App Password** (create one at
 <https://myaccount.google.com/apppasswords>; the account needs 2-Step
@@ -78,7 +78,7 @@ TOIL_EMAIL_PROVIDER=gmail
 TOIL_EMAIL_API_KEY=abcd efgh ijkl mnop
 ```
 
-**Generic SMTP** (`TOIL_EMAIL_PROVIDER=smtp`) — any submission server (Outlook,
+**Generic SMTP** (`TOIL_EMAIL_PROVIDER=smtp`), any submission server (Outlook,
 SendGrid/Mailgun SMTP, your own). Requires `TOIL_EMAIL_SMTP_HOST`; port defaults
 to `587` (STARTTLS), or set `465` for implicit TLS. `TOIL_EMAIL_SMTP_USER`
 defaults to `from`.
@@ -95,9 +95,9 @@ TOIL_EMAIL_SMTP_USER=noreply@example.com
 
 ### In dev
 
-`toiljs dev` runs the **full email pipeline** in Node — recipient validation,
+`toiljs dev` runs the **full email pipeline** in Node, recipient validation,
 dedup, and the per-minute / per-day / per-recipient caps all behave exactly like
-the edge — and **really sends** once you configure a provider. Configure it in
+the edge, and **really sends** once you configure a provider. Configure it in
 `toil.config.ts` (non-secret) with the API key in `.env.secrets`:
 
 ```ts
@@ -153,7 +153,7 @@ class Notify {
 
 | Status            | Meaning                                                     | Retry?           |
 | ----------------- | ----------------------------------------------------------- | ---------------- |
-| `Sent`            | Accepted by the provider                                    | —                |
+| `Sent`            | Accepted by the provider                                    |, |
 | `Deduped`         | An identical recent `(recipient, purpose)` was collapsed    | treat as sent    |
 | `Budget`          | The host's per-minute budget is exhausted                   | yes, later       |
 | `TryLater`        | The mailer was saturated / a queue was full                 | yes, back off    |
@@ -193,7 +193,7 @@ const status = welcome.send('alice@example.com', vars, 'welcome');
 - `template.render(vars)` returns the rendered `{ subject, body, html }` without
   sending (useful for preview/testing).
 
-For anything richer than `{{token}}` substitution — real layout, CSS, brand —
+For anything richer than `{{token}}` substitution, real layout, CSS, brand,
 author the email as a React component instead.
 
 ## React email templates
@@ -247,7 +247,7 @@ Authoring notes:
   email name), `export const text` (a plain-text alternative; otherwise derived
   from the HTML), `export const purpose`.
 - **Build-time, field substitution only.** Because the component renders once at
-  build, per-send data is `{{token}}` substitution — a runtime `{items.map(...)}`
+  build, per-send data is `{{token}}` substitution, a runtime `{items.map(...)}`
   or conditional bakes in at build, it does not re-run per recipient. That covers
   transactional / 2FA / confirmation email; dynamic lists need a different
   approach.
@@ -265,7 +265,7 @@ editor. It refreshes live as you edit the template or its CSS.
 ## Email verification codes (`TwoFactor`)
 
 `TwoFactor` is a **stateless** email-code primitive (2FA, email confirmation,
-magic codes) — no database. It emails a random code and returns a signed
+magic codes), no database. It emails a random code and returns a signed
 **token** that commits to the code via HMAC, without putting the code in the
 token (the code is only in the email). Verification recomputes the HMAC from the
 token plus the user-entered code, so a valid `(token, code)` pair can only come
@@ -281,18 +281,18 @@ const challenge = TwoFactor.send('alice@example.com', 'login'); // emails the co
 const ok: bool = TwoFactor.verify(challenge.token, 'alice@example.com', userEntered);
 ```
 
-- **`send(recipient, purpose, ttlSecs = 600, digits = 6)`** — issues a code,
+- **`send(recipient, purpose, ttlSecs = 600, digits = 6)`**, issues a code,
   emails it with a built-in template, returns `{ token, status }`.
-- **`issue(recipient, purpose, ttlSecs, digits)`** — returns `{ code, token }`
+- **`issue(recipient, purpose, ttlSecs, digits)`**, returns `{ code, token }`
   **without** sending, so you can email `code` with your own `EmailTemplate` /
   `Emails.*` for a branded message.
-- **`verify(token, recipient, code)`** — `true` only for a code issued for that
+- **`verify(token, recipient, code)`**, `true` only for a code issued for that
   recipient that hasn't expired. Constant-time compare.
-- **`TwoFactor.setSecret(secret)`** — the HMAC secret for the tokens. Call once
+- **`TwoFactor.setSecret(secret)`**, the HMAC secret for the tokens. Call once
   at startup in `main.ts`; it must be identical on every edge instance and out of
   any client bundle. (This is separate from the provider `api_key`.)
 
-**Limitation:** this gives integrity + expiry but **not single-use** — a valid
+**Limitation:** this gives integrity + expiry but **not single-use**, a valid
 code verifies repeatedly within its TTL, because there is no server state to burn
 it. Keep the TTL short; for true single-use, store a per-recipient
 last-verified-at and reject at or before it.
@@ -302,13 +302,13 @@ last-verified-at and reject at or before it.
 All enforced authoritatively in the single mailer (so the counts are exact across
 all workers):
 
-- **Per-host budget** — two rolling windows, both enforced: a 1-minute cap
+- **Per-host budget**, two rolling windows, both enforced: a 1-minute cap
   (`max_per_min`) and a 24-hour cap (`max_per_day`, `0` = unlimited). Over either
   one → `Budget`. Each host's caps, in-window sends, and reject counts are visible
   per host at `GET /_admin/email`.
-- **Per-recipient cap** — `max_per_recipient_per_hour`. Over it →
+- **Per-recipient cap**, `max_per_recipient_per_hour`. Over it →
   `RecipientCapped`.
-- **Dedup** — identical `(host, recipient, purpose)` within ~30s → `Deduped`.
+- **Dedup**, identical `(host, recipient, purpose)` within ~30s → `Deduped`.
 
 Editing these in the host config takes effect on the next send (no restart).
 
@@ -316,11 +316,11 @@ Editing these in the host config takes effect on the next send (no restart).
 
 `GET /_admin/email` returns process-wide counters by reason (JSON), e.g.
 `submitted`, `sent`, `deduped`, `budget`, `recipient_capped`, `try_later`,
-`bad_recipient`, `provider_error`. It exposes **counts only** — never a
+`bad_recipient`, `provider_error`. It exposes **counts only**, never a
 recipient, code, subject, body, or secret.
 
 ## See also
 
-- [Rate limiting](./ratelimit.md) — protect your routes (including any email
+- [Rate limiting](./ratelimit.md), protect your routes (including any email
   trigger) with `@ratelimit`.
-- [Web Crypto](./crypto.md) — the `crypto` global `TwoFactor` builds on.
+- [Web Crypto](./crypto.md), the `crypto` global `TwoFactor` builds on.

package/docs/environment.md

@@ -2,7 +2,7 @@
 
 `Environment` gives a tenant **per-app environment variables and secrets**, set
 out of band (a dashboard, like GitHub Actions) so the deployed `.wasm` carries
-**no credentials**. It is read-only from app code — there is no `set`; values are
+**no credentials**. It is read-only from app code, there is no `set`; values are
 configured on the deployment side, never from the module.
 
 ```ts
@@ -20,15 +20,15 @@ class Cfg {
 }
 ```
 
-`Environment` is a global — no import needed (like `EmailService` / `AuthService`).
+`Environment` is a global, no import needed (like `EmailService` / `AuthService`).
 
 ## Two disjoint buckets
 
 Just like GitHub Actions' `vars` vs `secrets`:
 
-- **`Environment.get(key)`** reads **plain vars** — non-sensitive config (a public
+- **`Environment.get(key)`** reads **plain vars**, non-sensitive config (a public
   API base URL, a feature flag, a region). Returns the string, or `null`.
-- **`Environment.getSecure(key)`** reads **secrets** — sensitive values (a
+- **`Environment.getSecure(key)`** reads **secrets**, sensitive values (a
   third-party API key). Returns the string, or `null`.
 
 The buckets are **disjoint**: a secret is **never** returned by `get()`, and a
@@ -37,13 +37,13 @@ through a code path that logs the result of a `get()`. Keys are case-sensitive,
 exact-match.
 
 > Secrets you read with `getSecure` are plaintext in your module at runtime
-> (that's the point — you need them to call out). Don't log them, don't put them
+> (that's the point, you need them to call out). Don't log them, don't put them
 > in a response, and don't copy them into a client bundle.
 
 ## What is NOT here
 
-Framework-reserved namespaces (today: **email** provider config) are **host-only**
-— resolved and used in Rust where the framework needs them, and **never exposed to
+Framework-reserved namespaces (today: **email** provider config) are **host-only**,
+resolved and used in Rust where the framework needs them, and **never exposed to
 the `.wasm`**. There is no `Environment.email`; you configure email in the
 `[email]` block of the same env file and the platform uses it for you (see
 [Email](./email.md)). The env imports only ever see your own `vars` / `secrets`.
@@ -53,7 +53,7 @@ the `.wasm`**. There is no `Environment.email`; you configure email in the
 Vars and secrets live in **two separate dotenv (`.env`) files**, so the disjoint
 split is structural and the secrets file can be locked down on its own. On the
 edge they are per host, **out of `hosts/`** (so the config watcher never sees a
-credential) — the dashboard / edge database replaces them later:
+credential), the dashboard / edge database replaces them later:
 
 ```bash
 # $TOIL_ENV_DIR/<host>.env          (default dir /run/toil/env)
@@ -63,7 +63,7 @@ REGION=eu
 # $TOIL_ENV_DIR/<host>.env.secrets  (mode 0600)
 STRIPE_KEY=sk_live_xxx                     # -> Environment.getSecure("STRIPE_KEY")
 
-# host-only email config — reserved TOIL_EMAIL_* keys, NEVER exposed to the .wasm
+# host-only email config, reserved TOIL_EMAIL_* keys, NEVER exposed to the .wasm
 TOIL_EMAIL_ENABLED=true
 TOIL_EMAIL_PROVIDER=resend
 TOIL_EMAIL_FROM=noreply@example.com
@@ -72,7 +72,7 @@ TOIL_EMAIL_API_KEY=re_xxx
 
 Each file is plain dotenv: `KEY=value` per line, `#` comments, optional `export`,
 optional quotes. Keys with the reserved **`TOIL_`** prefix are framework/host-only
-and are stripped from BOTH guest buckets — a tenant can never read them via
+and are stripped from BOTH guest buckets, a tenant can never read them via
 `get`/`getSecure` (see [Email](./email.md) for `TOIL_EMAIL_*`).
 
 On the edge, env is loaded **lazily** (the first time your code reads it) into a

package/docs/index.md

@@ -0,0 +1,26 @@
+# toiljs
+
+A full-stack React framework: a Vite-bundled client SPA with file-based routing, plus a
+toilscript-to-WebAssembly server target.
+
+## Project layout
+
+- `client/`, the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,
+  `public/`, and `toil.tsx` (the entry that calls `Toil.mount`).
+- `server/`, the toilscript → WASM target (`@main` entry), compiled by `toilscript`.
+  `@data`/`@remote`/`@service` here generate the typed client `Server` API (see [server.md](./server.md)).
+- `toil.config.ts`, configuration via `defineConfig` (`toiljs.config.ts` also works).
+- Generated, gitignored, do not edit: `.toil/` (working dir), `toil-env.d.ts` (ambient
+  globals), `toil-routes.d.ts` (typed routes), `shared/server.ts` (the typed RPC module,
+  emitted by the server build; import `@data` classes from `shared/server`).
+
+## Key ideas
+
+- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,
+  etc. The IO classes (`FastMap`, `FastSet`, `DataWriter`, `DataReader`), `parseError`, and the
+  generated `Server` RPC surface are globals too.
+- Scripts: `npm run dev` (HMR), `npm run build` (→ `build/client` + `build/server`),
+  `npm start` (self-host the build).
+
+See [routing.md](./routing.md), [client.md](./client.md), [styling.md](./styling.md),
+[server.md](./server.md), [ssr.md](./ssr.md), [cli.md](./cli.md).

package/docs/ratelimit.md

@@ -1,6 +1,6 @@
 # Rate limiting
 
-The `@ratelimit` decorator throttles **any** `@rest` route — a login, a signup, a
+The `@ratelimit` decorator throttles **any** `@rest` route, a login, a signup, a
 public API, an email trigger, anything. It is enforced at the edge, before your
 handler runs, and keyed by default on the connecting client's **unspoofable** IP,
 so it works as an abuse / brute-force control out of the box.
@@ -28,9 +28,9 @@ class Auth {
 
 `@ratelimit(strategy, limit, window)`:
 
-- **`strategy`** — a `RateLimit` value (ambient global, no import):
+- **`strategy`**, a `RateLimit` value (ambient global, no import):
   `RateLimit.FixedWindow`, `RateLimit.SlidingWindow`, or `RateLimit.TokenBucket`.
-- **`limit`** and **`window`** — integer literals whose meaning depends on the
+- **`limit`** and **`window`**, integer literals whose meaning depends on the
   strategy (see below).
 
 When a request is over the limit the edge returns **`429 Too Many Requests`**
@@ -39,7 +39,7 @@ guard runs **before `@auth`**, so unauthenticated floods are limited too.
 
 > Both arguments must be **integer literals** and the strategy a `RateLimit`
 > member (or a bare integer tag). A malformed decorator emits no guard rather
-> than miscompiling — the same fail-safe rule as `@cache`.
+> than miscompiling, the same fail-safe rule as `@cache`.
 
 ## Strategies
 
@@ -64,17 +64,17 @@ Examples:
 
 ## How requests are keyed
 
-By default the limiter keys on the **client IP** — specifically the TCP peer
+By default the limiter keys on the **client IP**, specifically the TCP peer
 address the edge observed (`ctx.clientIp()`), **not** a header like
 `X-Forwarded-For`, which a client can forge. That makes it a real abuse control:
 a caller can't reset their bucket by spoofing a header.
 
 The count is **exact across all 14 edge workers** (a given IP always maps to one
 authoritative shard), so the limit is global per route, not per worker. Only
-routes that opt in with `@ratelimit` ever pay anything — the lock-free fast path
+routes that opt in with `@ratelimit` ever pay anything, the lock-free fast path
 for everything else is untouched.
 
-> Each rate-limited route has its own independent limiter — a limit on `/login`
+> Each rate-limited route has its own independent limiter, a limit on `/login`
 > does not consume the budget of `/signup`.
 
 ## Notes and limits
@@ -82,14 +82,14 @@ for everything else is untouched.
 - **Route-level only.** Put `@ratelimit` on each route you want limited; there is
   no controller-wide form yet (unlike `@auth`).
 - **Keyed on IP.** The decorator keys on the peer IP today. (A per-user / custom
-  key — limiting by account instead of IP — exists in the runtime but is not yet
+  key, limiting by account instead of IP, exists in the runtime but is not yet
   exposed through the decorator.)
 - **In dev.** `toiljs dev` runs a single-process mirror of the same three
   strategies, so a limited route behaves the same locally as on the edge.
 
 ## See also
 
-- [Email](./email.md) — `@ratelimit` pairs well with email triggers (verification
+- [Email](./email.md), `@ratelimit` pairs well with email triggers (verification
   codes, password resets) to blunt abuse.
-- [Auth, sessions, and `@user`](./auth.md) — `@ratelimit` runs before the `@auth`
+- [Auth, sessions, and `@user`](./auth.md), `@ratelimit` runs before the `@auth`
   guard, so it protects the login itself.

package/docs/routing.md

@@ -134,11 +134,11 @@ serialized.
 
 Each route is either **JSON** (default) or **Binary**:
 
-- **JSON** — the body is `JSON.parse`d and revived via the `@data` type's
+- **JSON**, the body is `JSON.parse`d and revived via the `@data` type's
   `fromJSON`; the response is the type's `toJSON()`. 64-bit-and-larger integers
   cross the wire as decimal strings (exact at any size). Best for endpoints a
   browser or third party calls directly.
-- **Binary** — the body is `Body.decode(bytes)` and the response is
+- **Binary**, the body is `Body.decode(bytes)` and the response is
   `value.encode()`, using the deterministic `DataWriter`/`DataReader` codec. No
   precision loss, smaller, faster. Best for app-to-app and anything
   security-sensitive.

package/docs/server.md

@@ -0,0 +1,61 @@
+# Server (toilscript → WebAssembly)
+
+`server/` is the toilscript source, compiled to WebAssembly by `toilscript`.
+
+- `server/main.ts`, the `@main` entry, exported as the WASM `main`.
+- `server/index.ts`, your functions.
+- `server/tsconfig.json`, extends `toilscript/std/assembly.json` (AssemblyScript/toilscript
+  globals like `i32`, not the DOM), so editors resolve server types correctly.
+- `npm run build:server` (or `npm run build`) emits `build/server/release.wasm` and
+  regenerates `shared/server.ts` (the typed client RPC module).
+
+## Typed RPC (`@data` / `@remote` / `@service`)
+
+Tag server code and the build generates a typed client `Server` surface:
+
+- `@data class X {}`, a serializable struct. Generates a client class with the same fields
+  plus `encode`/`decode`; construct it on the client: `import { X } from "shared/server"`.
+- `@remote function f(a: T): R`, a client-callable endpoint, becomes `Server.f(a)`.
+- `@service class S { @remote m(...) {} }`, namespaces methods: `Server.s.m(...)`.
+
+On the client, `Server` is a global (no import) and fully typed; every call is async
+(`Promise<R>`). Inputs/outputs are scalars, arrays, or `@data` classes, both directions.
+
+Note: the client↔server transport is not wired yet, so calling a `Server` method throws
+until it lands; the typed surface + codec are generated and ready.
+
+## HTTP REST (`@rest` / `@route`)
+
+Tag a class `@rest` and its methods with a verb to expose a real HTTP API. Unlike RPC,
+the generated client is working `fetch` code (it is just HTTP).
+
+- `@rest("api") class Todos {}`, mounts the controller at `/api` (bare `@rest` → `/`).
+- `@get("/todos/:id")` / `@post` / `@del` / `@put` / `@patch` / `@head` / `@options`, verb
+  shortcuts; or `@route({ method: Methods.GET, path: "/todos", stream: DataStream.JSON })`.
+- A method takes an optional `@data` body + an optional `ctx: RouteContext` (path params via
+  `ctx.param("id")`, `ctx.query(...)`, `ctx.header(...)`). It returns either a `@data` type,
+  which the compiler encodes per `stream` (`DataStream.JSON` default, or `DataStream.Binary`,
+  lossless for large `u64`/bignum), or a `Response` for full control - custom status and
+  headers, e.g. `Response.json(value.toJSON().toString()).setHeader("cache-control", "no-store")`
+  or `Response.notFound()`. (The editor sees the compiler-injected `@data` `toJSON`/`encode`
+  members via the toilscript plugin, so serializing into a `Response` is editor-clean.)
+
+Each `@rest` class self-registers; dispatch them from your handler - it composes, it never
+takes over `handle()`:
+
+```ts
+import { ToilHandler, Request, Response, Rest } from "toiljs/server/runtime";
+export class App extends ToilHandler {
+    public handle(req: Request): Response {
+        const hit = Rest.dispatch(req); // try every @rest controller
+        if (hit != null) return hit;
+        return Response.notFound();     // your own logic / static fallback
+    }
+}
+```
+
+For a REST-only project, `Server.handler = () => new RestHandler()` does the same with no
+boilerplate. On the client: `Server.REST.todos.getTodo({ params: { id } })` (see [client.md](./client.md)).
+
+For the full reference (`@rest`/verb decorators, `RouteContext`, `Request`, `Response`,
+dispatch + the 404 fallback) see [routing.md](./routing.md).