toiljs 0.0.85 → 0.0.87

package/docs/streams.md

@@ -1,178 +0,0 @@
-# Streams
-
-A `@stream` declares a long-lived, stateful protocol handler over WebTransport -
-the **L2/L3** (regional / continental) stream tier of the Toil edge. Unlike a
-`@rest` route, which is a fresh handler per request, a `@stream` is a **resident
-WebAssembly box per connection**: it is created when the connection opens, lives
-for the whole connection, and is torn down on close. State stored on its fields
-**persists across events**, because it is the same box every time.
-
-```ts
-@stream('echo')
-class Echo {
-  private count: i32 = 0;
-
-  @connect
-  onConnect(): void {
-    this.count = 0;
-  }
-
-  @message
-  onMessage(): void {
-    this.count = this.count + 1;
-  }
-
-  @close
-  onClose(): void {}
-}
-```
-
-## Declaring a stream
-
-`@stream(name)` marks a class as a stream handler and mounts it at the given
-name/route. The class becomes a resident box; its fields are the connection's
-state.
-
-```ts
-@stream('echo')            // mounted at /echo
-class Echo { /* ... */ }
-```
-
-A stream lives on the **L2/L3 stream tier** and its default scope is **Regional
-(L2)**. See [Tiers](./tiers.md) for the full tier model.
-
-## Lifecycle hooks
-
-A stream method is a lifecycle hook, chosen by its decorator. All hooks are
-optional - declare only the ones you need; a missing hook is a no-op.
-
-| Decorator | Fires when |
-| --- | --- |
-| `@connect` | the connection opens (the box has just been created). |
-| `@message` | an inbound frame arrives. |
-| `@close` | the connection closes gracefully (the box is torn down after this hook). |
-| `@disconnect` | the transport is lost abruptly. |
-
-The `Echo` example above shows why state survives: `count` is set to `0` in
-`@connect`, incremented on every `@message`, and the increments **accumulate**.
-That is only possible because the same resident box handles every event for the
-connection. A `@rest` handler's fields would reset on each request, since a
-fresh handler is constructed per request.
-
-Distributed stream channels are not part of the live v1 ABI. The edge rejects
-stream artifacts that declare a channel hook until the channel fan-out runtime
-exists.
-
-## Placement
-
-A `@stream` is distributed across the eligible L2/L3 stream nodes and pinned to
-**ONE worker** for the connection's lifetime via QUIC connection-id steering. The
-connection always lands on the same worker, so the box - and the state on its
-fields - survives every event. You do not manage placement; the edge steers each
-connection to its resident box automatically.
-
-## The entry: `main.stream.ts`
-
-The stream surface has its own entry, `server/main.stream.ts`, distinct from the
-request entry (`server/main.ts`). It re-exports the WASM runtime exports and
-imports the `@stream` classes, which pulls their compiler-generated
-`stream_dispatch` export into the artifact.
-
-```ts
-import { revertOnError } from 'toiljs/server/runtime/abort/abort';
-
-import './streams/Echo';
-
-// Re-export the WASM entry points the host binds, exactly like main.ts.
-export * from 'toiljs/server/runtime/exports';
-export function abort(message: string, fileName: string, line: u32, column: u32): void {
-  revertOnError(message, fileName, line, column);
-}
-```
-
-This entry compiles into its **own artifact**, `build/server/release-stream.wasm`
-- the resident stream box - separate from the request build,
-`build/server/release.wasm`. Add a stream as you grow by importing it here:
-
-```ts
-import './streams/Echo';
-```
-
-## Build
-
-`toiljs build` produces `release-stream.wasm` automatically when the project
-declares a `@stream` surface. The single build runs one toilscript pass per tier,
-handing each pass only the entries that belong to it, so `release.wasm` never
-contains `stream_dispatch` and the stream artifact never contains the request
-`handle`. Plain `@data` and helper modules are shared into every artifact.
-
-```sh
-$ toiljs build
-$ 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)
-```
-
-See [Tiers](./tiers.md) for how the three artifacts map to the deployment tiers.
-
-## Reading and replying to messages
-
-`@message` receives the inbound frame as a `StreamPacket` and returns a
-`StreamOutbound`. `StreamPacket.bytes()` is the raw frame payload;
-`StreamOutbound.reply(bytes)` stages one frame back to the client (return an empty
-`StreamOutbound` to accept the frame without replying). The same resident box
-handles every frame, so state on its fields persists across messages.
-
-```ts
-@message
-reply(packet: StreamPacket): StreamOutbound {
-  return StreamOutbound.reply(packet.bytes());   // echo the bytes back
-}
-```
-
-## Typed messages
-
-By default a `@message` payload is **raw bytes**. Opt into a decoded `@data` value
-with `@stream({ message: T })`: the `@message` hook then receives the named `@data`
-class, decoded from the frame for you. The reply stays raw (`StreamOutbound`).
-
-```ts
-@data
-class ChatMsg { text: string = ''; }
-
-@stream({ message: ChatMsg })
-class Chat {
-  @message
-  onMessage(msg: ChatMsg): StreamOutbound {       // decoded @data, not raw bytes
-    return StreamOutbound.reply(new TextEncoder().encode(msg.text));
-  }
-}
-```
-
-## The client
-
-A `@stream` class is reachable from the browser as `Server.Stream.<ClassName>`. The
-typed client is generated into `shared/server.ts` (the same place `Server.REST`
-lands), so no manual wiring is needed. `connect()` opens a WebSocket to the class's
-route and resolves a channel:
-
-```ts
-const chat = await Server.Stream.Chat.connect();
-chat.onMessage((bytes) => { /* a reply frame, always raw bytes */ });
-chat.send(new ChatMsg('hello'));   // a typed stream: send() encodes the @data for you
-chat.onClose((code) => { /* a 0x02xx stream close code */ });
-chat.close();
-```
-
-- The channel key is the **class name** (`Server.Stream.Chat`); it connects to the
-  class's mount route (`/Chat`).
-- A **raw** `@stream` channel sends `Uint8Array`; a **typed** `@stream({ message: T })`
-  channel sends the `@data` class and encodes it on the wire for you.
-- The inbound reply is **always raw bytes** - the server's `StreamOutbound` is raw.
-- `connect()` resolves once the upgrade completes; a `@connect` reject (or any
-  later server close) surfaces through `onClose(code)`.
-
----
-
-See also: [Tiers](./tiers.md), [Daemon](./daemon.md), [Routing](./routing.md).

package/docs/styling.md

@@ -1,22 +0,0 @@
-# Styling
-
-The app imports one stylesheet from `client/toil.tsx` (e.g. `./styles/main.css`).
-
-## Preprocessors & Tailwind
-
-Pick a CSS preprocessor (none / Sass / Less / Stylus) and optionally Tailwind at
-`toiljs create`, or change it later on an existing project:
-
-```sh
-toiljs configure                 # interactive
-toiljs configure --tailwind      # add Tailwind
-toiljs configure --style sass    # switch preprocessor
-```
-
-`configure` installs/removes the right packages and rewrites the imports. Tailwind lives
-in its own `styles/tailwind.css` (`@import "tailwindcss";`).
-
-## Imports
-
-`.css` / `.scss` / `.sass` / `.less` / `.styl` and image imports (`.svg`, `.png`, …) are
-typed via `toil-env.d.ts`.

package/docs/tiers.md

@@ -1,133 +0,0 @@
-# Deployment tiers
-
-A Toil app's server runs across several deployment **tiers** from one source
-tree. Each tier has a different lifetime and placement on the edge, and compiles
-into its own WebAssembly artifact. You write one project; `toiljs build` decides
-which entries belong to which tier and emits one `.wasm` per tier. You opt into a
-tier purely by adding its entry file and surface decorator; nothing else changes.
-
-## The tiers
-
-| Entry (`server/`) | Surface                          | Artifact                           | Tier             | Lifetime / placement                                                                                                                              |
-| ----------------- | -------------------------------- | ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `main.ts`         | `@rest` / `@service` / `@remote` | `build/server/release.wasm`        | **L1** request   | A fresh handler per request, anywhere on the edge.                                                                                                |
-| `main.stream.ts`  | `@stream`                        | `build/server/release-stream.wasm` | **L2/L3** stream | One resident box per connection, pinned to a worker via QUIC connection-id steering; its state survives every event. See [Streams](./streams.md). |
-| `main.daemon.ts`  | `@daemon` / `@scheduled`         | `build/server/release-cold.wasm`   | **L4** daemon    | Exactly one leader-elected box per domain (warm standby, at-most-once failover) firing `@scheduled` tasks. See [Daemon](./daemon.md).             |
-
-The three tiers differ in how long a box lives and how many of it exist:
-
-- **L1 request** is stateless. A `@rest` handler's fields reset each request,
-  because a fresh box serves each one, anywhere on the edge.
-- **L2/L3 stream** is resident per connection. A `@stream` box is created when a
-  connection opens, lives for its lifetime, and is torn down on close, so its
-  fields persist across every event.
-- **L4 daemon** is a single elected leader per domain - the global coordination
-  tier - running recurring background work on a cadence.
-
-## How the build works
-
-`toiljs build` runs one toilscript pass per tier, handing each pass only the
-entries that belong to it. Tier membership is decided by the surface decorator or
-by the entry naming convention:
-
-- a runtime-export entry that is **not** `*.stream.ts` or `*.daemon.ts` is the
-  **request** entry (`main.ts`), which compiles `@rest` / `@service` / `@remote`;
-- `*.stream.ts` is the **stream** entry, which compiles `@stream`;
-- `*.daemon.ts` is the **daemon** entry, which compiles `@daemon` / `@scheduled`.
-
-Plain `@data` and helper modules carry no tier of their own, so they are shared
-into every artifact. Routing each entry to exactly one tier is what keeps
-`release.wasm` free of `stream_dispatch` and keeps the daemon artifact free of
-the request `handle`.
-
-Each entry is a thin file that imports its tier's modules and re-exports the
-right runtime hooks. The stream and request entries re-export the request runtime
-exports; the daemon entry does not, because a cold artifact exposes
-`daemon_start` / `scheduled_tick`, not `handle`:
-
-```ts
-// server/main.stream.ts - the L2/L3 stream entry
-import { revertOnError } from 'toiljs/server/runtime/abort/abort';
-import './streams/Echo';
-
-export * from 'toiljs/server/runtime/exports';
-export function abort(message: string, fileName: string, line: u32, column: u32): void {
-    revertOnError(message, fileName, line, column);
-}
-```
-
-```ts
-// server/main.daemon.ts - the L4 daemon entry
-import { revertOnError } from 'toiljs/server/runtime/abort/abort';
-import './daemon/Jobs';
-
-// NOTE: no `export *` from 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);
-}
-```
-
-A single build produces the artifacts side by side:
-
-```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)
-```
-
-## Single-artifact default
-
-A project with no `@stream` and no `@daemon` surface keeps the default
-single-artifact build - just `build/server/release.wasm`. The stream and daemon
-tiers are opt-in: add `main.stream.ts` (and a `@stream` class) to get
-`release-stream.wasm`, add `main.daemon.ts` (and a `@daemon` class) to get
-`release-cold.wasm`. Existing request-only apps build exactly as before.
-
-## When to use each tier
-
-- **L1 request** for request/response and RPC: `@rest` controllers, `@service` /
-  `@remote` callable surface. The default tier; most code lives here.
-- **L2/L3 stream** for stateful, long-lived connections where per-connection
-  state must survive across events - the resident box is pinned to one worker for
-  the connection's lifetime.
-- **L4 daemon** for scheduled and coordination work: rollups, cleanup, polling an
-  upstream, anything that should run exactly once per domain on a cadence rather
-  than per request.
-
-```ts
-// server/streams/Echo.ts - L2/L3: the box is resident, so `count` persists.
-@stream('echo')
-class Echo {
-    private count: i32 = 0;
-
-    @connect onConnect(): void {
-        this.count = 0;
-    }
-    @message onMessage(): void {
-        this.count = this.count + 1;
-    }
-    @close onClose(): void {
-        /* box torn down after this hook */
-    }
-}
-```
-
-```ts
-// server/daemon/Jobs.ts - L4: one leader per domain runs this hourly.
-@daemon
-class Jobs {
-    @scheduled('1h')
-    hourly(): void {
-        // Recurring background work: rollups, cleanup, polling an upstream, ...
-    }
-}
-```
-
-## See also
-
-- [Streams](./streams.md) - the `@stream` surface and the L2/L3 tier.
-- [Daemon](./daemon.md) - the `@daemon` surface and the L4 tier.
-- [Routing](./routing.md) - `@rest` controllers on the L1 request tier.
-- [RPC](./rpc.md) - `@service` / `@remote` and the generated client.

package/docs/time.md

@@ -1,43 +0,0 @@
-# Time
-
-`Time` is the guest's wall-clock. It is the toiljs-blessed way to read the
-current time, backed by the host's `Date.now()` binding (`env.Date.now`). Both
-the edge and the dev server provide that binding, so time behaves identically in
-`toiljs dev` and in production.
-
-It is available as an ambient global (`@global`, no import) and is also exported
-from `toiljs/server/runtime`.
-
-```ts
-import { Time } from 'toiljs/server/runtime'; // optional; Time is also a global
-
-const ms = Time.nowMillis();   // u64 milliseconds since the Unix epoch
-const s  = Time.nowSeconds();  // u64 whole seconds since the Unix epoch
-```
-
-## API
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Time.nowMillis()` | `static nowMillis(): u64` | Milliseconds since the Unix epoch (the raw host `Date.now()` value). |
-| `Time.nowSeconds()` | `static nowSeconds(): u64` | Whole seconds since the epoch (`nowMillis() / 1000`). The unit used by sessions and login challenges. |
-
-## Semantics
-
-`Time` is **wall-clock, not monotonic**, exactly like browser `Date.now()`. It
-tracks the system clock and can step backward across an NTP correction.
-
-- Use it to stamp and compare absolute instants: session `iat`/`exp`, login
-  challenge expiry, cache ages.
-- Do **not** use it to measure elapsed time or as a high-resolution timer; a
-  backward step would produce a negative or zero interval.
-
-## Relationship to `Date.now()`
-
-ToilScript's `Date.now()` lowers to the same `env.Date.now` host import, so you
-*can* call it directly. Prefer `Time`: it makes the host boundary (and the
-single millisecond unit) explicit and easy to find, and it gives you
-`nowSeconds()` without an open-coded `/ 1000` cast at every call site.
-
-`AuthService` uses `Time.nowSeconds()` internally for session `iat`/`exp`, so
-session timing and any timing you do in a handler share one clock.