toiljs 0.0.54 → 0.0.56

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

@@ -3,14 +3,14 @@
 // surface plus HMAC signing and AES-256-GCM encryption, running in the server wasm.
 // These controls call the `/api/cookies/*` routes in `server/core/AppHandler.ts`.
 // Needs the server running to respond.
-import { useState, type CSSProperties } from 'react';
+import { type CSSProperties, useState } from 'react';
 
 import { useBrowserValue } from '../lib/useBrowserValue';
 
 export const metadata: Toil.Metadata = {
     title: 'Cookies',
     description:
-        'Server-side cookies as a global: the Cookie builder, parsing, HMAC signing, and AES-256-GCM encryption, running in the server wasm.',
+        'Server-side cookies as a global: the Cookie builder, parsing, HMAC signing, and AES-256-GCM encryption, running in the server wasm.'
 };
 
 interface SetResp {
@@ -39,7 +39,7 @@ const card: CSSProperties = {
     borderRadius: 8,
     padding: '12px 16px',
     margin: '12px 0',
-    background: '#0c1218',
+    background: '#0c1218'
 };
 const label: CSSProperties = { opacity: 0.7, fontSize: '0.8rem', marginTop: 6 };
 
@@ -94,22 +94,18 @@ export default function CookiesDemo() {
             readJs();
         });
     const doSeal = (): Promise<void> =>
-        guard(async () =>
-            setSeal(await getJSON<SealResp>('/api/cookies/seal?v=' + encodeURIComponent(sealInput))),
-        );
+        guard(async () => setSeal(await getJSON<SealResp>('/api/cookies/seal?v=' + encodeURIComponent(sealInput))));
 
     return (
         <main style={{ maxWidth: 760 }}>
             <h1>Cookies</h1>
             <p>
-                <code>Cookie</code>, <code>Cookies</code>, and <code>SecureCookies</code> are globals in
-                the server (no import), exactly like <code>crypto</code>: the full RFC 6265bis surface
-                plus HMAC signing and AES-256-GCM encryption, running in the server wasm. See{' '}
-                <code>server/core/AppHandler.ts</code>. Needs the server running (<code>toiljs dev</code>).
+                <code>Cookie</code>, <code>Cookies</code>, and <code>SecureCookies</code> are globals in the server (no
+                import), exactly like <code>crypto</code>: the full RFC 6265bis surface plus HMAC signing and
+                AES-256-GCM encryption, running in the server wasm. See <code>server/core/AppHandler.ts</code>. Needs
+                the server running (<code>toiljs dev</code>).
             </p>
-
             {err ? <p style={{ color: '#ff6b6b', ...mono }}>{err}</p> : null}
-
             <h2>1. Everything you can do</h2>
             <p>Every attribute and cookie type, with the exact `Set-Cookie` string it serializes to.</p>
             <button onClick={showGallery}>Show the gallery</button>
@@ -123,12 +119,11 @@ export default function CookiesDemo() {
                     ))}
                 </div>
             ) : null}
-
             <h2>2. Set cookies</h2>
             <p>
                 Stores three real cookies: a plain <code>visits</code> counter, an HMAC-signed{' '}
-                <code>__Host-session</code>, and an AES-GCM-encrypted <code>secret</code>. The last two
-                are <code>HttpOnly</code>, so JavaScript cannot read them, only the server can.
+                <code>__Host-session</code>, and an AES-GCM-encrypted <code>secret</code>. The last two are{' '}
+                <code>HttpOnly</code>, so JavaScript cannot read them, only the server can.
             </p>
             <button onClick={doSet}>Set cookies</button>
             {setResp ? (
@@ -141,12 +136,11 @@ export default function CookiesDemo() {
                     ))}
                 </div>
             ) : null}
-
             <h2>3. What JS sees vs what the server sees</h2>
             <p>
-                <code>document.cookie</code> only exposes non-<code>HttpOnly</code> cookies, so the
-                signed session and encrypted secret are hidden from it. The server parses all of them
-                and verifies/decrypts the protected ones.
+                <code>document.cookie</code> only exposes non-<code>HttpOnly</code> cookies, so the signed session and
+                encrypted secret are hidden from it. The server parses all of them and verifies/decrypts the protected
+                ones.
             </p>
             <button onClick={readJs}>Read document.cookie</button>{' '}
             <button onClick={doInspect}>Ask the server (/inspect)</button>
@@ -163,7 +157,6 @@ export default function CookiesDemo() {
                     <div style={mono}>secret (AES-GCM-decrypted): {inspect.secret ?? 'null (missing or tampered)'}</div>
                 </div>
             ) : null}
-
             <h2>4. Clear</h2>
             <button onClick={doClear}>Clear the demo cookies</button>
             {cleared ? (
@@ -175,12 +168,11 @@ export default function CookiesDemo() {
                     ))}
                 </div>
             ) : null}
-
             <h2>5. Sign &amp; encrypt a value</h2>
             <p>
                 <code>SecureCookies.signed(key)</code> (HMAC-SHA256, readable but tamper-proof) and{' '}
-                <code>SecureCookies.encrypted(key)</code> (AES-256-GCM, confidential). Both bind the
-                value to the cookie name, and a tampered signature fails to verify.
+                <code>SecureCookies.encrypted(key)</code> (AES-256-GCM, confidential). Both bind the value to the cookie
+                name, and a tampered signature fails to verify.
             </p>
             <input
                 value={sealInput}
@@ -198,7 +190,6 @@ export default function CookiesDemo() {
                     <div style={mono}>tampered signature verifies? {String(seal.tamperVerifies)}</div>
                 </div>
             ) : null}
-
             <p style={{ marginTop: 24 }}>
                 <Toil.Link href="/features">Back to features</Toil.Link>
             </p>

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

@@ -37,11 +37,10 @@ export default function CryptoDemo() {
         <main>
             <h1>Web Crypto</h1>
             <p>
-                <code>crypto</code> is a global in the server (no import), synchronous, the same
-                SubtleCrypto-style API as the browser, running in the server wasm via metered host
-                functions. These buttons call the server&apos;s <code>/api/hash</code> and{' '}
-                <code>/api/uuid</code> routes (see <code>server/HelloHandler.ts</code>). Needs the
-                server running to respond.
+                <code>crypto</code> is a global in the server (no import), synchronous, the same SubtleCrypto-style API
+                as the browser, running in the server wasm via metered host functions. These buttons call the
+                server&apos;s <code>/api/hash</code> and <code>/api/uuid</code> routes (see{' '}
+                <code>server/HelloHandler.ts</code>). Needs the server running to respond.
             </p>
             <button onClick={onHash}>SHA-256</button> <button onClick={onUuid}>random UUID</button>
             <ul style={{ marginTop: 16, listStyle: 'none', padding: 0 }}>

package/examples/basic/client/routes/features/template/template.tsx

@@ -1,4 +1,4 @@
-import { useState, type ReactNode } from 'react';
+import { type ReactNode, useState } from 'react';
 
 // A template wraps a segment like a layout, but RE-MOUNTS on every navigation within it (a layout
 // persists). This counter increments each time the template mounts, so navigating between the two

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

@@ -19,7 +19,7 @@ interface HelloData {
 
 export const loader = ({ params }: { params: Record<string, string> }): HelloData => ({
     name: params.name ?? 'world',
-    items: ['alpha', 'beta', 'gamma'],
+    items: ['alpha', 'beta', 'gamma']
 });
 
 export default function Hello(): React.JSX.Element {

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

@@ -49,7 +49,7 @@ interface VerifiedUser {
 export const metadata: Toil.Metadata = {
     title: 'Post-quantum auth',
     description:
-        'A server-keyed-salt OPRF + ML-DSA-44 (FIPS 204) auth + ML-KEM-768 (FIPS 203) mutual auth. The password never leaves the browser.',
+        'A server-keyed-salt OPRF + ML-DSA-44 (FIPS 204) auth + ML-KEM-768 (FIPS 203) mutual auth. The password never leaves the browser.'
 };
 
 type Note = { kind: 'ok' | 'err'; text: string } | null;
@@ -73,7 +73,7 @@ export default function Pq(): React.JSX.Element {
             await Auth.register(username, password);
             setNote({
                 kind: 'ok',
-                text: 'registered: the server stored only your public key and a proof-of-possession. Now log in to run the ML-KEM-768 mutual-auth step.',
+                text: 'registered: the server stored only your public key and a proof-of-possession. Now log in to run the ML-KEM-768 mutual-auth step.'
             });
         } catch (e) {
             setNote({ kind: 'err', text: e instanceof Error ? e.message : String(e) });
@@ -91,7 +91,7 @@ export default function Pq(): React.JSX.Element {
             await Auth.login(username, password);
             setNote({
                 kind: 'ok',
-                text: 'logged in: ML-KEM-768 mutual auth verified (the server proved it holds the KEM secret key).',
+                text: 'logged in: ML-KEM-768 mutual auth verified (the server proved it holds the KEM secret key).'
             });
             refreshCompanion();
         } catch (e) {
@@ -151,11 +151,7 @@ export default function Pq(): React.JSX.Element {
                 </label>
                 <label>
                     Password
-                    <input
-                        value={password}
-                        onChange={(e) => setPassword(e.target.value)}
-                        style={{ width: '100%' }}
-                    />
+                    <input value={password} onChange={(e) => setPassword(e.target.value)} style={{ width: '100%' }} />
                 </label>
                 <div style={{ display: 'flex', gap: 8 }}>
                     <button onClick={doRegister} disabled={busy}>
@@ -167,8 +163,8 @@ export default function Pq(): React.JSX.Element {
                 </div>
                 <p style={{ fontSize: '0.8rem', opacity: 0.7, margin: 0 }}>
                     Demo: pre-filled <code>ada</code> / <code>correct horse battery staple</code>. Register once, then
-                    log in. A wrong password fails at login (the derived key won&apos;t match the stored one). Storage is
-                    the DEV-only in-process KV (<code>src/devserver/kv.ts</code>); a real deployment wires an atomic
+                    log in. A wrong password fails at login (the derived key won&apos;t match the stored one). Storage
+                    is the DEV-only in-process KV (<code>src/devserver/kv.ts</code>); a real deployment wires an atomic
                     store, <code>server/routes/Auth.ts</code>.
                 </p>
             </div>
@@ -188,9 +184,13 @@ export default function Pq(): React.JSX.Element {
                             <div style={{ fontSize: '0.8em', opacity: 0.7 }}>readable companion, untrusted</div>
                             <pre>
                                 {JSON.stringify(
-                                    { username: companion.username, admin: companion.admin, score: String(companion.score) },
+                                    {
+                                        username: companion.username,
+                                        admin: companion.admin,
+                                        score: String(companion.score)
+                                    },
                                     null,
-                                    2,
+                                    2
                                 )}
                             </pre>
                         </div>
@@ -220,8 +220,8 @@ export default function Pq(): React.JSX.Element {
             )}
 
             <p style={{ marginTop: 24, opacity: 0.7, fontSize: '0.9rem' }}>
-                This is the full augmented-PAKE chain: OPRF keyed salt + ML-DSA client auth + ML-KEM mutual auth, with an
-                atomic single-use challenge consume. The OPRF layer is classical ristretto255 (the one non-PQ piece);
+                This is the full augmented-PAKE chain: OPRF keyed salt + ML-DSA client auth + ML-KEM mutual auth, with
+                an atomic single-use challenge consume. The OPRF layer is classical ristretto255 (the one non-PQ piece);
                 auth and key agreement are post-quantum. Plain sessions are on the{' '}
                 <Toil.Link href="/auth">Auth</Toil.Link> page.
             </p>

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

@@ -6,12 +6,20 @@
 // `Response` to inspect (status, `.json()`, ...). Needs the server running to respond.
 import { useState } from 'react';
 
-import { NewPlayer, ScoreDelta } from 'shared/server';
+import { NewMessage, NewPlayer, ScoreDelta } from 'shared/server';
 
 export default function RestDemo() {
     const [log, setLog] = useState<string[]>([]);
     const note = (line: string) => setLog((prev) => [line, ...prev].slice(0, 8));
 
+    // The guestbook is backed by ToilDB (an `events` stream + a `counter`), so unlike
+    // the players below its data PERSISTS across requests. Sign a few times, reload the
+    // page, and the total is still there.
+    const [book, setBook] = useState<{ total: bigint; entries: { author: string; message: string }[] }>({
+        total: 0n,
+        entries: []
+    });
+
     // POST /players  ->  typed Promise<Player>, body is a @data class. The server returns the
     // new player, but it is NOT saved (server memory resets per request); this is a preview.
     const onCreate = async () => {
@@ -67,6 +75,31 @@ export default function RestDemo() {
         }
     };
 
+    // POST /guestbook  ->  typed Promise<GuestbookView>. This one is PERSISTED in ToilDB
+    // (events + counter), so the total keeps climbing across requests and reloads.
+    const signers = ['Ada', 'Linus', 'Grace', 'Ken'];
+    const onSign = async () => {
+        try {
+            const author = signers[Math.floor(Math.random() * signers.length)];
+            const v = await Server.REST.guestbook.sign({ body: new NewMessage(author, 'was here') });
+            setBook(v);
+            note(`${author} signed -> ${v.total} signatures (persisted in ToilDB)`);
+        } catch (err) {
+            note(parseError(err));
+        }
+    };
+
+    // GET /guestbook  ->  the running total + the newest entries.
+    const onBook = async () => {
+        try {
+            const v = await Server.REST.guestbook.list();
+            setBook(v);
+            note(`guestbook: ${v.total} signatures`);
+        } catch (err) {
+            note(parseError(err));
+        }
+    };
+
     return (
         <main>
             <h1>REST</h1>
@@ -83,6 +116,22 @@ export default function RestDemo() {
                     <li key={i}>{line}</li>
                 ))}
             </ul>
+            <h2>Guestbook (persisted via ToilDB)</h2>
+            <p>
+                The same <code>Server.REST.*</code> client, but the route stores each signature in a ToilDB{' '}
+                <code>events</code> stream and a <code>counter</code>. So unlike the players above, these{' '}
+                <strong>persist</strong> across requests and page reloads - locally under <code>toil dev</code> and on
+                ScyllaDB at the edge, with the same code.
+            </p>
+            <button onClick={onSign}>sign the guestbook</button>{' '}
+            <button onClick={onBook}>refresh ({String(book.total)} signatures)</button>
+            <ul>
+                {book.entries.map((e, i) => (
+                    <li key={i}>
+                        <strong>{e.author}</strong>: {e.message}
+                    </li>
+                ))}
+            </ul>
             <Toil.Link href="/">Back home</Toil.Link>
         </main>
     );

package/examples/basic/client/styles/main.css

@@ -23,10 +23,9 @@ body {
     min-height: 100vh;
     background: var(--bg);
     color: var(--text);
-    font-family:
-        system-ui,
-        -apple-system,
-        sans-serif;
+    font-family: system-ui,
+    -apple-system,
+    sans-serif;
     line-height: 1.6;
 }
 
@@ -34,6 +33,7 @@ a {
     color: var(--accent);
     text-decoration: none;
 }
+
 a:hover {
     color: var(--accent3);
 }
@@ -99,6 +99,7 @@ a:hover {
 .nav-links a {
     color: var(--muted);
 }
+
 .nav-links a:hover {
     color: var(--text);
 }
@@ -117,9 +118,8 @@ a:hover {
     border-radius: 6px;
     font-size: 0.9rem;
     color: var(--muted) !important;
-    transition:
-        color 150ms,
-        background 150ms;
+    transition: color 150ms,
+    background 150ms;
 }
 
 .nav-center-link:hover {
@@ -182,10 +182,9 @@ a:hover {
     transform: scale(1.1);
     filter: blur(18px) saturate(1.4);
     opacity: 0.65;
-    transition:
-        opacity 300ms,
-        filter 300ms,
-        transform 300ms;
+    transition: opacity 300ms,
+    filter 300ms,
+    transform 300ms;
 }
 
 .hero-logo:hover .hero-logo-glow {
@@ -248,9 +247,8 @@ a:hover {
     border-radius: 999px;
     font-size: 0.88rem;
     color: var(--muted);
-    transition:
-        border-color 200ms,
-        color 200ms;
+    transition: border-color 200ms,
+    color 200ms;
 }
 
 .feature-badge svg {
@@ -289,10 +287,9 @@ a:hover {
     font-weight: 600;
     font-family: inherit;
     cursor: pointer;
-    transition:
-        filter 200ms,
-        background 200ms,
-        border-color 200ms;
+    transition: filter 200ms,
+    background 200ms,
+    border-color 200ms;
     text-decoration: none !important;
 }
 
@@ -422,10 +419,9 @@ code {
     display: flex;
     flex-direction: column;
     gap: 0.6rem;
-    transition:
-        border-color 200ms,
-        transform 200ms,
-        box-shadow 200ms;
+    transition: border-color 200ms,
+    transform 200ms,
+    box-shadow 200ms;
 }
 
 .gs-card {
@@ -436,6 +432,7 @@ code {
 .gs-card--accent1 {
     border-top: 2px solid var(--accent);
 }
+
 .gs-card--accent1:hover {
     box-shadow: 0 8px 32px rgba(37, 99, 255, 0.15);
 }
@@ -443,6 +440,7 @@ code {
 .gs-card--accent2 {
     border-top: 2px solid var(--accent2);
 }
+
 .gs-card--accent2:hover {
     box-shadow: 0 8px 32px rgba(124, 58, 237, 0.15);
 }
@@ -450,6 +448,7 @@ code {
 .gs-card--accent3 {
     border-top: 2px solid var(--accent3);
 }
+
 .gs-card--accent3:hover {
     box-shadow: 0 8px 32px rgba(34, 227, 171, 0.12);
 }
@@ -457,6 +456,7 @@ code {
 .gs-card--accent4 {
     border-top: 2px solid #f59e0b;
 }
+
 .gs-card--accent4:hover {
     box-shadow: 0 8px 32px rgba(245, 158, 11, 0.12);
 }
@@ -464,6 +464,7 @@ code {
 .gs-card--flat {
     border-top: 2px solid var(--accent);
 }
+
 .gs-card--flat:hover {
     border-color: var(--accent);
     box-shadow: 0 8px 32px rgba(37, 99, 255, 0.12);
@@ -485,10 +486,12 @@ code {
     background: rgba(124, 58, 237, 0.1);
     color: var(--accent2);
 }
+
 .gs-card--accent3 .gs-card-icon {
     background: rgba(34, 227, 171, 0.1);
     color: var(--accent3);
 }
+
 .gs-card--accent4 .gs-card-icon {
     background: rgba(245, 158, 11, 0.1);
     color: #f59e0b;

package/examples/basic/client/toil.tsx

@@ -1,4 +1,4 @@
-import { routes, layout, notFound, globalError, slots } from 'toiljs/routes';
+import { globalError, layout, notFound, routes, slots } from 'toiljs/routes';
 
 import './styles/main.css';
 

package/examples/basic/server/README.md

@@ -2,14 +2,14 @@
 
 Your ToilScript backend, compiled to a single WebAssembly module. One folder per concern:
 
-| Folder | What lives here |
-| --- | --- |
-| `main.ts` | The entry point: wires the handler and imports the surface modules. |
-| `core/` | The request handler and shared app logic (state, helpers). |
-| `models/` | `@data` classes, the typed wire model shared by HTTP and RPC. One type per file. |
-| `routes/` | `@rest` controllers (HTTP). One controller per file, named after its class. |
-| `services/` | `@service` classes and free `@remote` functions (typed RPC). |
-| `scheduled/` | Reserved for scheduled tasks (see its README). |
+| Folder       | What lives here                                                                  |
+|--------------|----------------------------------------------------------------------------------|
+| `main.ts`    | The entry point: wires the handler and imports the surface modules.              |
+| `core/`      | The request handler and shared app logic (state, helpers).                       |
+| `models/`    | `@data` classes, the typed wire model shared by HTTP and RPC. One type per file. |
+| `routes/`    | `@rest` controllers (HTTP). One controller per file, named after its class.      |
+| `services/`  | `@service` classes and free `@remote` functions (typed RPC).                     |
+| `scheduled/` | Reserved for scheduled tasks (see its README).                                   |
 
 Conventions:
 

package/examples/basic/server/core/AppHandler.ts

@@ -104,7 +104,7 @@ export class AppHandler extends ToilHandler {
                     .partitioned()
                     .priority('Medium')
                     .extension('CustomFlag')
-                    .serialize(),
+                    .serialize()
             );
 
             let json = '{';
@@ -127,10 +127,10 @@ export class AppHandler extends ToilHandler {
 
             const visits = Cookie.create('visits', next).path('/').sameSite(SameSite.Lax).maxAge(86400);
             const session = SecureCookies.signed(this.demoKey()).seal(
-                Cookie.create('session', 'user-42').httpOnly().sameSite(SameSite.Strict).asHostPrefixed(),
+                Cookie.create('session', 'user-42').httpOnly().sameSite(SameSite.Strict).asHostPrefixed()
             );
             const secret = SecureCookies.encrypted(this.demoKey()).seal(
-                Cookie.create('secret', 'top-secret-value').httpOnly().path('/'),
+                Cookie.create('secret', 'top-secret-value').httpOnly().path('/')
             );
 
             const json =
@@ -189,10 +189,7 @@ export class AppHandler extends ToilHandler {
                 '","' +
                 this.esc(this.clearString('secret')) +
                 '"]}';
-            return Response.json(json)
-                .clearCookie('visits')
-                .clearCookie('__Host-session')
-                .clearCookie('secret');
+            return Response.json(json).clearCookie('visits').clearCookie('__Host-session').clearCookie('secret');
         }
 
         // SEAL: sign and encrypt a value (from `?v=`), then recover both and show

package/examples/basic/server/main.ts

@@ -9,6 +9,7 @@ import { AppHandler } from './core/AppHandler';
 import './routes/Auth';
 import './routes/Players';
 import './routes/Leaderboard';
+import './routes/Guestbook';
 import './routes/Session';
 import './routes/EnvDemo';
 import './services/Stats';

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

@@ -0,0 +1,12 @@
+/** One signed guestbook entry, stored as a ToilDB `events` record. */
+@data
+export class GuestEntry {
+    author: string = '';
+    message: string = '';
+    at: u64 = 0;
+    constructor(author: string = '', message: string = '', at: u64 = 0) {
+        this.author = author;
+        this.message = message;
+        this.at = at;
+    }
+}

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

@@ -0,0 +1,10 @@
+import { GuestEntry } from './GuestEntry';
+
+/** The guestbook snapshot returned by the routes: the running signature count
+ *  plus the most-recent entries (newest first). A `@data` wrapper so the
+ *  `GuestEntry[]` round-trips through the codec. */
+@data
+export class GuestbookView {
+    total: i64 = 0;
+    entries: GuestEntry[] = [];
+}

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

@@ -0,0 +1,6 @@
+/** Request body for `POST /guestbook` - a new signature to append. */
+@data
+export class NewMessage {
+    author: string = '';
+    message: string = '';
+}