toiljs 0.0.85 → 0.0.87

package/docs/services/time.md

@@ -0,0 +1,85 @@
+# Time
+
+**`Time` is the edge's clock: the blessed way to read the current time in your backend.** It gives you the number of milliseconds or seconds since a fixed reference point, so you can stamp events and compute expiries.
+
+## How to use it
+
+`Time` is an ambient global (no import needed), and is also exported from `toiljs/server/runtime`:
+
+```ts
+const ms = Time.nowMillis();   // milliseconds since the Unix epoch (a u64)
+const s  = Time.nowSeconds();  // whole seconds since the Unix epoch (a u64)
+```
+
+| Member | Returns | Description |
+| --- | --- | --- |
+| `Time.nowMillis()` | `u64` | Milliseconds since the **Unix epoch** (midnight UTC on 1 January 1970). This is the same value as JavaScript's `Date.now()`. |
+| `Time.nowSeconds()` | `u64` | Whole seconds since the epoch (`nowMillis() / 1000`). This is the unit sessions and login challenges use. |
+
+The **Unix epoch** is just the agreed "time zero" that computers count from. "Milliseconds since the epoch" is a single number that unambiguously names an instant, with no time zone to worry about.
+
+## Why time is a "host import" (and what that means)
+
+Your backend runs as a **WebAssembly** module: a small, sandboxed program. A sandbox is deliberately sealed off from the outside world. It has no clock of its own, no network, no files, nothing except the memory it was given and a short list of functions the host chooses to hand it. Each of those handed-in functions is called a **host import**.
+
+This is on purpose. WebAssembly aims to be **deterministic**: given the same inputs, the same code produces the same outputs, every time. That makes it safe to run untrusted code, easy to cache, and easy to reason about. But the current time is not deterministic: it is different every time you ask. So a WebAssembly module cannot just "know" the time; it has to **ask the host** for it. Reading the clock is a call across the sandbox boundary.
+
+`Time` is the thin, friendly wrapper over that call. Under the hood it uses the host's `Date.now()` binding (`env.Date.now`).
+
+```mermaid
+flowchart LR
+    subgraph Sandbox["Your backend (WebAssembly sandbox)"]
+        C["Time.nowMillis()"]
+    end
+    subgraph Host["Dacely edge host"]
+        D["env.Date.now"]
+        K["real system clock"]
+    end
+    C -->|host import| D
+    D --> K
+    K -->|milliseconds| C
+```
+
+Both the edge and the dev server provide this binding, so time behaves **identically** in `toiljs dev` and in production.
+
+## `Time` vs calling `Date.now()`
+
+ToilScript's `Date.now()` lowers to the exact same 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 in a codebase.
+- It gives you `nowSeconds()` without writing an open-coded `/ 1000` at every call site.
+
+Both are the same clock, so timing you do in a handler lines up with timing the framework does. For example, the auth system uses `Time.nowSeconds()` for session issue and expiry times.
+
+## Correct usage: timestamps and TTLs
+
+`Time` is **wall-clock time**, exactly like a browser's `Date.now()`. It follows the system clock, which means it can occasionally **step backward** (for instance when the machine corrects its clock against a time server).
+
+Do:
+
+- **Stamp an instant.** Record when something happened, so you can compare it later: an event time, a "last seen" marker.
+- **Compute an expiry (a TTL).** A **TTL** ("time to live") is a deadline. You set it by adding a duration to *now*, and you check it by comparing *now* against the stored deadline:
+
+```ts
+const ttlSeconds: u64 = 3600;                 // valid for one hour
+const expiresAt = Time.nowSeconds() + ttlSeconds;
+
+// ...later, on another request...
+const expired = Time.nowSeconds() >= expiresAt;
+```
+
+Do not:
+
+- **Measure elapsed time with it.** Do not use it as a stopwatch to time how long an operation took. Because the wall clock can step backward, `end - start` could come out zero or negative. `Time` answers "what instant is it now?", not "how much time has passed?".
+
+## Gotchas
+
+- **It is wall-clock, not monotonic.** It can jump backward across a clock correction. Fine for timestamps and expiries; wrong for measuring durations.
+- **Milliseconds vs seconds.** `nowMillis()` and `nowSeconds()` differ by a factor of 1000. Mixing them (comparing a millisecond stamp to a second stamp) is a common bug. Sessions and login challenges use **seconds**.
+- **UTC only.** These are epoch counts, with no time zone. Format for display on the client if you need a local time.
+
+## Related
+
+- [Auth, sessions, and `@user`](../auth/usage.md): sessions use `Time.nowSeconds()` for their issue and expiry stamps.
+- [Caching](./caching.md): TTLs are the same idea, a deadline after which a saved value is stale.
+- [Compute tiers](../concepts/tiers.md): more on the WebAssembly sandbox your backend runs in.

package/examples/basic/client/routes/analytics.tsx

@@ -25,8 +25,10 @@ const METRICS = [
     { id: 13, label: 'DB ops', unit: 'count' },
     { id: 26, label: 'Stream bytes out', unit: 'bytes' },
     { id: 39, label: 'Memory bandwidth', unit: 'bytes' },
-    { id: 41, label: 'Connected streams', unit: 'count' },
-    { id: 43, label: 'Committed memory', unit: 'bytes' }
+    { id: 41, label: 'Cache hits', unit: 'count' },
+    { id: 42, label: 'Cache misses', unit: 'count' },
+    { id: 43, label: 'Connected streams', unit: 'count' },
+    { id: 45, label: 'Committed memory', unit: 'bytes' }
 ] as const;
 
 // AnalyticsRange (mirrors the server enum).
@@ -157,20 +159,19 @@ export default function AnalyticsDemo() {
 
             <section style={{ marginTop: 24 }}>
                 <h2>Snapshot</h2>
+                <p style={{ color: '#64748b', marginTop: 0 }}>
+                    The <code>live</code> gauges are the current level right now, and the windows are the
+                    current rate-limit usage vs the plan cap (cap ∞ = unlimited). To see a metric over time,
+                    use the chart above (the time-series), not an ever-growing lifetime total.
+                </p>
                 <button onClick={loadStats}>Load my site analytics</button>
                 {err && <p style={{ color: '#f87171' }}>{err}</p>}
                 {stats && (
                     <ul>
-                        <li>requests: {String(stats.requests)}</li>
-                        <li>bytes out (L1): {String(stats.bytesOutL1)}</li>
-                        <li>bytes in (L1): {String(stats.bytesInL1)}</li>
-                        <li>gas used: {String(stats.gasUsed)}</li>
-                        <li>2xx responses: {String(stats.status2xx)}</li>
-                        <li>db ops: {String(stats.dbOps)}</li>
-                        <li>connected streams (live): {String(stats.connectedStreams)}</li>
-                        <li>committed memory (live): {fmt(Number(stats.committedMemory), 'bytes')}</li>
-                        <li>requests this minute: {cap(stats.reqMinuteUsed, stats.reqMinuteCap)}</li>
-                        <li>requests today: {cap(stats.reqDayUsed, stats.reqDayCap)}</li>
+                        <li>connected streams (live): {String(stats.liveConnectedStreams)}</li>
+                        <li>committed memory (live): {fmt(Number(stats.liveCommittedMemoryBytes), 'bytes')}</li>
+                        <li>requests this minute: {cap(stats.requestsThisMinute, stats.requestsThisMinuteCap)}</li>
+                        <li>requests today: {cap(stats.requestsToday, stats.requestsTodayCap)}</li>
                     </ul>
                 )}
             </section>

package/examples/basic/server/models/SiteAnalytics.ts

@@ -1,25 +1,37 @@
-/** This site's own analytics, mapped from the toilscript `Analytics.self()` snapshot for the
- *  client. Counts + usage are i64; the rate-limit caps are i64 too (0 = unlimited). */
+/**
+ * This site's own analytics snapshot, mapped from the toilscript `Analytics.self()` frame.
+ *
+ * This example deliberately returns only CURRENT state: the `live*` gauges (the instantaneous level
+ * right now) and the request-window counters (usage in the current 1-minute and 24-hour rate-limit
+ * windows, paired with the plan cap, where cap `0` = unlimited). It does NOT surface lifetime
+ * cumulative `total*` counters. For historical, time-windowed values use the separate `SeriesData`
+ * time-series (`/series`), which reads per-bucket history rather than an ever-growing running total.
+ *
+ * All fields are `u64` (the guest exposes `u64` getters, so the mapping needs zero casts).
+ */
 @data
 export class SiteAnalytics {
-    requests: i64 = 0;
-    bytesOutL1: i64 = 0;
-    bytesInL1: i64 = 0;
-    status2xx: i64 = 0;
-    wasmDispatches: i64 = 0;
-    dbOps: i64 = 0;
-    gasUsed: i64 = 0;
-    connectedStreams: i64 = 0;
-    committedMemory: i64 = 0;
-    reqMinuteUsed: i64 = 0;
-    reqMinuteCap: i64 = 0;
-    reqDayUsed: i64 = 0;
-    reqDayCap: i64 = 0;
+    // --- Live gauges (current instantaneous level, right now, NOT a total) ---
+    /** Streams currently connected right now. */
+    liveConnectedStreams: u64 = 0;
+    /** Wasm linear memory currently committed right now, in bytes. */
+    liveCommittedMemoryBytes: u64 = 0;
+
+    // --- Request windows: current rate-limit usage vs plan cap (cap 0 = unlimited) ---
+    /** Requests used in the current 1-minute window. */
+    requestsThisMinute: u64 = 0;
+    /** Plan cap for the 1-minute window (0 = unlimited). */
+    requestsThisMinuteCap: u64 = 0;
+    /** Requests used in the current 24-hour window. */
+    requestsToday: u64 = 0;
+    /** Plan cap for the 24-hour window (0 = unlimited). */
+    requestsTodayCap: u64 = 0;
 }
 
-/** One metric's historical time-series for a range, from `Analytics.series(metric, range)`: the raw
+/** One metric's historical TIME-SERIES for a range, from `Analytics.series(metric, range)`: the raw
  *  per-bucket totals (oldest→newest) plus the bucket width + newest-bucket end, so the client can draw a
- *  graph and derive per-second rates. Demonstrates the typed series API. */
+ *  graph and derive per-second rates. This is per-bucket HISTORY: the right way to see a metric over time,
+ *  instead of an ever-growing lifetime counter. Demonstrates the typed series API. */
 @data
 export class SeriesData {
     metric: i32 = 0;

package/examples/basic/server/routes/Analytics.ts

@@ -16,23 +16,21 @@ import { SeriesData, SiteAnalytics } from '../models/SiteAnalytics';
 class AnalyticsRoutes {
     @get('/')
     public self(): SiteAnalytics {
-        const s = Analytics.self();
-        const r = new SiteAnalytics();
-        // Typed getters: no magic strings, no `.has()/.get()` map dance.
-        r.requests = s.requests;
-        r.bytesOutL1 = s.bytesOutL1;
-        r.bytesInL1 = s.bytesInL1;
-        r.status2xx = s.status2xx;
-        r.wasmDispatches = s.wasmDispatches;
-        r.dbOps = s.dbOps;
-        r.gasUsed = s.gasUsed;
-        r.connectedStreams = s.connectedStreams;
-        r.committedMemory = s.committedMemory;
-        r.reqMinuteUsed = s.reqMinuteUsed;
-        r.reqMinuteCap = <i64>s.reqMinuteCap;
-        r.reqDayUsed = s.reqDayUsed;
-        r.reqDayCap = <i64>s.reqDayCap;
-        return r;
+        const stats = Analytics.self();
+        const out = new SiteAnalytics();
+
+        // Live gauges (current instantaneous level, not a cumulative total).
+        out.liveConnectedStreams = stats.connectedStreams;
+        out.liveCommittedMemoryBytes = stats.committedMemory;
+
+        // Request windows: current usage vs plan cap (cap 0 = unlimited).
+        out.requestsThisMinute = stats.reqMinuteUsed;
+        out.requestsThisMinuteCap = stats.reqMinuteCap;
+        out.requestsToday = stats.reqDayUsed;
+        out.requestsTodayCap = stats.reqDayCap;
+
+        // For historical, time-windowed values (per-bucket, not a lifetime total), see `/series` below.
+        return out;
     }
 
     /// Any metric's historical time-series for a range, for graphs:

package/examples/basic/server/routes/UserId.ts

@@ -0,0 +1,22 @@
+import { Response } from 'toiljs/server/runtime';
+
+/**
+ * Demo of `ToilUserId` — the stable 256-bit user identity derived from the ML-DSA login public key +
+ * identifier (email/username) + tenant domain. Deterministic, opaque, O(1) to compare with `==` / `!=`.
+ */
+@rest('userid')
+class UserIdDemo {
+    @get('/demo')
+    public demo(): Response {
+        const key = new Uint8Array(1312); // an ML-DSA-44 public key (zeros for the demo)
+        const a = ToilUserId.derive(key, 'alice@example.com', 'acme.dacely.com');
+        const b = ToilUserId.derive(key, 'alice@example.com', 'acme.dacely.com');
+        const c = ToilUserId.derive(key, 'bob@example.com', 'acme.dacely.com');
+        // Same inputs => same id (a == b); a different identifier => a different id (a != c).
+        const same = a == b;
+        const diff = a != c;
+        return Response.text(
+            a.toHex() + '\nsame=' + same.toString() + ' diff=' + diff.toString() + '\n',
+        );
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.85",
+    "version": "0.0.87",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -67,6 +67,10 @@
             "types": "./server/runtime/*.ts",
             "default": "./server/runtime/*.ts"
         },
+        "./server/auth": {
+            "types": "./server/auth/index.ts",
+            "default": "./server/auth/index.ts"
+        },
         "./tsconfig": "./presets/tsconfig.json",
         "./eslint": "./presets/eslint.js",
         "./prettier": "./presets/prettier.json",
@@ -120,21 +124,21 @@
         "@dacely/hyper-express": "6.17.4",
         "@dacely/noble-post-quantum": "^0.6.1",
         "@dacely/toilscript-loader": "^0.1.0",
-        "@eslint-react/eslint-plugin": "^5.9.2",
+        "@eslint-react/eslint-plugin": "^5.10.1",
         "@eslint/js": "^10.0.1",
         "@noble/curves": "^2.2.0",
-        "@typescript-eslint/utils": "^8.62.0",
+        "@typescript-eslint/utils": "^8.62.1",
         "@vitejs/plugin-react": "^6.0.3",
         "eslint-plugin-react-hooks": "^7.1.1",
         "eslint-plugin-react-refresh": "^0.5.3",
         "hash-wasm": "^4.12.0",
         "juice": "^12.1.1",
-        "nodemailer": "^9.0.1",
+        "nodemailer": "^9.0.3",
         "picocolors": "^1.1.1",
-        "sharp": "^0.35.2",
-        "toilscript": "^0.1.48",
-        "typescript-eslint": "^8.62.0",
-        "vite": "^8.1.0",
+        "sharp": "^0.35.3",
+        "toilscript": "^0.1.52",
+        "typescript-eslint": "^8.62.1",
+        "vite": "^8.1.3",
         "vite-imagetools": "^10.0.1",
         "vite-plugin-node-polyfills": "^0.28.0"
     },
@@ -157,17 +161,17 @@
         "@microsoft/api-extractor": "7.58.9",
         "@testing-library/dom": "^10.4.1",
         "@testing-library/react": "^16.3.2",
-        "@types/node": "^26.0.0",
+        "@types/node": "^26.1.0",
         "@types/nodemailer": "^8.0.1",
         "@types/react": "^19.2.17",
         "@types/react-dom": "^19.2.3",
         "@vitest/coverage-v8": "^4.1.9",
         "@vitest/ui": "^4.1.9",
         "esbuild": "^0.28.1",
-        "eslint": "^10.5.0",
+        "eslint": "^10.6.0",
         "jsdom": "^29.1.1",
         "micromatch": "^4.0.8",
-        "prettier": "^3.8.4",
+        "prettier": "^3.9.4",
         "react": "^19.2.7",
         "react-dom": "^19.2.7",
         "typedoc": "^0.28.19",

package/scripts/gen-toil-docs.mjs

@@ -23,48 +23,37 @@ const docsDir = path.join(repoRoot, 'docs');
 const outFile = path.join(repoRoot, 'src', 'compiler', 'toil-docs.generated.ts');
 
 /**
- * Guides excluded from the AGENT doc set (still published as human docs):
- * - `auth-todo.md`: an internal tracking/roadmap doc, not project guidance.
- * - `README.md`: the human-site docs index; the agent gets `index.md` instead.
+ * Guides excluded from the AGENT doc set (still published as human docs).
+ * Nothing is excluded today: every folder's `README.md` landing page and its
+ * topic pages are bundled so the agent gets the full navigation.
  */
-const EXCLUDE = new Set(['auth-todo.md', 'README.md']);
+const EXCLUDE = new Set();
 
 /**
- * Stable order for the agent docs. Files not listed here are appended
- * alphabetically, so adding a new `docs/*.md` is picked up automatically.
+ * Stable order for the agent docs: the root landing page first, then every
+ * other guide alphabetically by its repo-relative path (which naturally groups
+ * each folder together, led by its `README.md` landing). Adding a new doc file
+ * is picked up automatically.
  */
-const ORDER = [
-    'index.md',
-    'getting-started.md',
-    'routing.md',
-    'client.md',
-    'styling.md',
-    'server.md',
-    'ssr.md',
-    'rpc.md',
-    'tiers.md',
-    'streams.md',
-    'daemon.md',
-    'data.md',
-    'caching.md',
-    'ratelimit.md',
-    'auth.md',
-    'environment.md',
-    'email.md',
-    'cookies.md',
-    'crypto.md',
-    'time.md',
-    'cli.md',
-];
+const ORDER = ['README.md'];
 
 function collect() {
-    const all = fs
-        .readdirSync(docsDir)
-        .filter((f) => f.endsWith('.md') && !EXCLUDE.has(f))
-        .sort();
+    // Recurse one+ levels so a topic FOLDER (e.g. `docs/auth/*.md`) is bundled too, keyed by its
+    // repo-relative path (`auth/index.md`). Adding a `docs/**/*.md` is picked up automatically.
+    const files = [];
+    const walk = (dir, prefix) => {
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (ent.isDirectory()) {
+                walk(path.join(dir, ent.name), prefix + ent.name + '/');
+            } else if (ent.name.endsWith('.md') && !EXCLUDE.has(prefix + ent.name) && !EXCLUDE.has(ent.name)) {
+                files.push(prefix + ent.name);
+            }
+        }
+    };
+    walk(docsDir, '');
     const ordered = [
-        ...ORDER.filter((f) => all.includes(f)),
-        ...all.filter((f) => !ORDER.includes(f)),
+        ...ORDER.filter((f) => files.includes(f)),
+        ...files.filter((f) => !ORDER.includes(f)),
     ];
     const out = {};
     for (const name of ordered) {