toiljs 0.0.21 → 0.0.23

package/examples/basic/server/api.ts

@@ -0,0 +1,137 @@
+// A small REST demo: a players list + a leaderboard.
+//
+// IMPORTANT - the server runs with a FRESH WebAssembly instance per request, so linear memory
+// (and any module-level state, like the `store` below) is reset on every request. It does NOT
+// persist across requests. We seed a few players at module init so the read routes always have
+// data; the write routes (create / addScore) take effect only for the current request's response.
+// For real persistence, call out to a database or KV store from your handler.
+//
+// `@data` types are the wire model (shared by HTTP and RPC). `@rest` controllers expose HTTP
+// routes; `@service`/`@remote` expose typed RPC. Building the server (toilscript --rpcModule)
+// regenerates the typed client into shared/server.ts:
+//   @rest    -> Server.REST.<controller>.<route>(args)  (a working fetch client)
+//   @service -> Server.<service>.<method>()             (RPC, transport TODO)
+
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+/** A leaderboard player. */
+@data
+class Player {
+    id: u64 = 0;
+    name: string = '';
+    score: i64 = 0;
+}
+
+/** Request body for `POST /players` - the fields a client supplies to create a player. */
+@data
+class NewPlayer {
+    name: string = '';
+}
+
+/** Request body for `POST /players/:id/score` - points to add to a player's score. */
+@data
+class ScoreDelta {
+    points: i64 = 0;
+}
+
+/** A leaderboard page. A `@data` wrapper so the `Player[]` round-trips through the codec. */
+@data
+class Standings {
+    players: Player[] = [];
+}
+
+// Re-seeded on EVERY request - module memory does not persist across requests (see the note at
+// the top of the file). Swap this for a database/KV to keep data between requests.
+const store = new Map<u64, Player>();
+let nextId: u64 = 1;
+
+function seed(name: string, score: i64): void {
+    const p = new Player();
+    p.id = nextId++;
+    p.name = name;
+    p.score = score;
+    store.set(p.id, p);
+}
+seed('Ada', 120);
+seed('Linus', 95);
+seed('Grace', 140);
+
+/**
+ * Players, mounted at `/players`. On the client:
+ *   await Server.REST.players.get({ params: { id } })
+ *   await Server.REST.players.create({ body: new NewPlayer('Bob') })
+ *   await Server.REST.players.addScore({ params: { id }, body: new ScoreDelta(10n) })
+ */
+@rest('players')
+class Players {
+    /** `GET /players/:id` - returns a `Response` for full control: a real 404 for a missing id,
+     *  a custom header, and the `@data` body serialized with `toJSON()`. (The toilscript editor
+     *  plugin types the compiler-injected `toJSON()`, so this is clean; return the `@data` type
+     *  directly, like the other routes, when you do not need that control.) */
+    @get('/:id')
+    public get(ctx: RouteContext): Response {
+        const id = u64.parse(ctx.param('id'));
+        if (!store.has(id)) return Response.notFound();
+        const p = store.get(id);
+
+        return Response.json(p.toJSON().toString()).setHeader('cache-control', 'no-store');
+    }
+
+    /** `POST /players` - build a player from the request body and return it with a fresh id.
+     *  Note: it is NOT saved (memory resets next request); persist to a real store to keep it. */
+    @post('/')
+    public create(input: NewPlayer): Player {
+        const p = new Player();
+        p.id = nextId++;
+        p.name = input.name;
+        p.score = 0;
+        store.set(p.id, p);
+
+        return p;
+    }
+
+    /** `POST /players/:id/score` - add `points` (from the body) to the seeded player named by
+     *  `:id` and return it. The change applies to this response only (memory resets next request). */
+    @post('/:id/score')
+    public addScore(input: ScoreDelta, ctx: RouteContext): Player {
+        const id = u64.parse(ctx.param('id'));
+        if (!store.has(id)) return new Player();
+        const p = store.get(id);
+        p.score += input.points;
+
+        return p;
+    }
+}
+
+/**
+ * The leaderboard, mounted at `/leaderboard`. On the client:
+ *   const board = await Server.REST.leaderboard.top(); // typed Standings { players: Player[] }
+ */
+@rest('leaderboard')
+class Leaderboard {
+    /** `GET /leaderboard` - the seeded players, highest score first. */
+    @get('/')
+    public top(): Standings {
+        const board = new Standings();
+        const all = store.values();
+        for (let i = 0; i < all.length; i++) board.players.push(all[i]);
+        board.players.sort((a: Player, b: Player): i32 => (a.score < b.score ? 1 : a.score > b.score ? -1 : 0));
+        return board;
+    }
+}
+
+/** Typed RPC service (transport still a TODO): reached as `Server.stats.playerCount()` on the client. */
+@service
+class Stats {
+    /** Number of seeded players (the RPC transport is a TODO, so this throws on the client for now). */
+    @remote
+    public playerCount(): i32 {
+        return store.size;
+    }
+}
+
+/** A free `@remote` function: `Server.ping(n)` on the client. */
+@remote
+function ping(n: i32): i32 {
+    return n + 1;
+}

package/examples/basic/server/main.ts

@@ -0,0 +1,19 @@
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { HelloHandler } from './HelloHandler';
+
+// DO NOT TOUCH THIS.
+Server.handler = () => {
+    // ONLY CHANGE THE HANDLER CLASS NAME.
+    // DO NOT ADD CUSTOM LOGIC HERE.
+
+    return new HelloHandler();
+};
+
+// VERY IMPORTANT
+export * from 'toiljs/server/runtime/exports';
+
+// VERY IMPORTANT
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}

package/examples/basic/server/tsconfig.json

@@ -0,0 +1,7 @@
+{
+    "extends": "toilscript/std/assembly.json",
+    "compilerOptions": {
+        "plugins": [{ "name": "toilscript/std/ts-plugin.cjs" }]
+    },
+    "include": ["./**/*.ts"]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.21",
+    "version": "0.0.23",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -121,7 +121,7 @@
         "eslint-plugin-react-refresh": "^0.5.2",
         "picocolors": "^1.1.1",
         "sharp": "^0.34.5",
-        "toilscript": "^0.1.14",
+        "toilscript": "^0.1.15",
         "typescript-eslint": "^8.60.0",
         "vite": "^8.0.14",
         "vite-imagetools": "^10.0.0",

package/src/cli/create.ts

@@ -114,7 +114,7 @@ function scaffold(
         '@types/react-dom': '^19.2.3',
         eslint: '^10.2.0',
         prettier: '^3.8.1',
-        toilscript: '^0.1.14',
+        toilscript: '^0.1.15',
         typescript: '^6.0.3',
     };
     for (const dep of requiredPackages(features).sort()) {
@@ -127,7 +127,7 @@ function scaffold(
         scripts: {
             dev: 'toiljs dev',
             build: 'toiljs build',
-            'build:server': 'toilscript --target release --rpcModule shared/server.ts',
+            'build:server': 'toiljs build --server',
             lint: 'eslint client',
             typecheck: 'tsc --noEmit',
             format: 'prettier --write "client/**/*.{ts,tsx,css,scss,less}" "client/public/**/*.html"',
@@ -175,7 +175,12 @@ function scaffold(
         'toilconfig.json':
             JSON.stringify(
                 {
-                    entries: ['server/main.ts'],
+                    // `toiljs build` compiles every server/*.ts so dropped-in @data/@rest files are
+                    // picked up; these entries are the fallback when running `toilscript` directly.
+                    entries:
+                        template === 'minimal'
+                            ? ['server/main.ts']
+                            : ['server/main.ts', 'server/api.ts'],
                     targets: {
                         release: {
                             outFile: 'build/server/release.wasm',
@@ -216,10 +221,6 @@ function scaffold(
                 null,
                 4,
             ) + '\n',
-        'server/index.ts': 'export function add(a: i32, b: i32): i32 {\n    return a + b;\n}\n',
-        'server/main.ts':
-            "import { add } from './index';\n\n" +
-            '@main\nfunction run(): i32 {\n    return add(40, 2);\n}\n',
         'README.md': [
             '# ' + path.basename(name),
             '',
@@ -237,9 +238,12 @@ function scaffold(
         ].join('\n'),
     };
 
-    // The `app` template's client UI is copied from examples/basic/client at runtime; `minimal` ships an
-    // inline client here.
-    if (template === 'minimal') Object.assign(files, minimalClient(name, features));
+    // The `app` template's client UI + server are copied from examples/basic at runtime; `minimal`
+    // ships an inline client + a minimal working server here.
+    if (template === 'minimal') {
+        Object.assign(files, minimalClient(name, features));
+        Object.assign(files, minimalServer());
+    }
 
     // Selected AI-assistant pointer files at the root (committed). The real docs are always seeded
     // under .toil/docs (gitignored; regenerated by dev/build) since the framework manages them.
@@ -251,6 +255,33 @@ function scaffold(
     return files;
 }
 
+/** A minimal but working server for the `minimal` template (the `app` template copies examples/basic/server). */
+function minimalServer(): Record<string, string> {
+    return {
+        'server/HelloHandler.ts':
+            "import { ToilHandler, Request, Response, Method } from 'toiljs/server/runtime';\n\n" +
+            'export class HelloHandler extends ToilHandler {\n' +
+            '    public handle(req: Request): Response {\n' +
+            '        if (req.method != Method.GET && req.method != Method.HEAD) {\n' +
+            "            return Response.empty(405).setHeader('allow', 'GET, HEAD');\n" +
+            '        }\n' +
+            "        return Response.text('hello from toiljs\\n');\n" +
+            '    }\n' +
+            '}\n',
+        'server/main.ts':
+            "import { Server } from 'toiljs/server/runtime';\n" +
+            "import { revertOnError } from 'toiljs/server/runtime/abort/abort';\n" +
+            "import { HelloHandler } from './HelloHandler';\n\n" +
+            '// Wire your handler here.\n' +
+            'Server.handler = () => new HelloHandler();\n\n' +
+            '// Required: re-export the WASM entry points and the abort hook.\n' +
+            "export * from 'toiljs/server/runtime/exports';\n" +
+            'export function abort(message: string, fileName: string, line: u32, column: u32): void {\n' +
+            '    revertOnError(message, fileName, line, column);\n' +
+            '}\n',
+    };
+}
+
 /** The inline client UI for the `minimal` template (the `app` template copies examples/basic/client). */
 function minimalClient(name: string, features: StyleFeatures): Record<string, string> {
     const files: Record<string, string> = {
@@ -351,6 +382,18 @@ function appClientDir(): string {
     );
 }
 
+/** Absolute path to the `app` starter server (`examples/basic/server`), shipped in the package. */
+function appServerDir(): string {
+    return path.resolve(
+        path.dirname(fileURLToPath(import.meta.url)),
+        '..',
+        '..',
+        'examples',
+        'basic',
+        'server',
+    );
+}
+
 /**
  * Applies the chosen styling to a copied template's client dir: renames the stylesheet to the
  * preprocessor's extension, adds the Tailwind entry, and rewrites `toil.tsx`'s style imports.
@@ -526,8 +569,9 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
     s.start('Scaffolding project');
     await writeFiles(targetDir, scaffold(name, template, features, aiTools, images));
     if (template === 'app') {
-        // Copy the example client (the single starter source), set its <title>, then apply styling.
+        // Copy the example client + server (the single starter source), set the <title>, then style.
         await fs.cp(appClientDir(), path.join(targetDir, 'client'), { recursive: true });
+        await fs.cp(appServerDir(), path.join(targetDir, 'server'), { recursive: true });
         const indexHtml = path.join(targetDir, 'client', 'public', 'index.html');
         const html = await fs.readFile(indexHtml, 'utf8');
         await fs.writeFile(

package/src/cli/diagnostics.ts

@@ -403,7 +403,7 @@ export function checkWasmBuilt(exists: boolean): Check {
 // --- Typed RPC (@data / @remote / @service) -------------------------------------------------------
 
 /** Minimum toilscript: @rest/@route HTTP layer + RPC codegen + hardened decoders + @data editor decls. */
-export const RPC_TOILSCRIPT_MIN = '0.1.14';
+export const RPC_TOILSCRIPT_MIN = '0.1.15';
 
 /** Whether each piece of the typed-RPC wiring is in place (computed in `doctor.ts`). */
 export interface RpcFacts {

package/src/cli/index.ts

@@ -30,6 +30,7 @@ interface Flags {
     json?: boolean;
     fix?: boolean;
     target?: string;
+    server?: boolean;
 }
 
 function parseArgs(argv: string[]): Flags {
@@ -106,6 +107,9 @@ function parseArgs(argv: string[]): Flags {
             case '--target':
                 flags.target = argv[++i];
                 break;
+            case '--server':
+                flags.server = true;
+                break;
             default:
                 if (!arg.startsWith('-') && flags.name === undefined) flags.name = arg;
         }
@@ -137,6 +141,7 @@ function printHelp(): void {
             cmd('--no-ai', 'create: skip AI assistant files (CLAUDE.md, etc.)'),
             cmd('-y, --yes', 'create: accept defaults (non-interactive)'),
             cmd('--no-install', "create: don't install dependencies"),
+            cmd('--server', 'build: build only the server (regenerate shared/server.ts + wasm)'),
             cmd('--json', 'doctor: machine-readable output'),
             cmd('--fix', 'doctor: auto-fix what it can (typed-RPC wiring)'),
             cmd('--target <t>', 'update: latest | minor | patch | newest | greatest'),
@@ -194,9 +199,17 @@ async function main(): Promise<void> {
 
         case 'build':
             banner();
-            process.stdout.write(dim('  building for production…') + '\n\n');
-            await build({ root: flags.root });
-            process.stdout.write('\n' + success('  ✓ ') + bold('build complete') + '\n\n');
+            process.stdout.write(
+                dim(flags.server ? '  building the server…' : '  building for production…') +
+                    '\n\n',
+            );
+            await build({ root: flags.root, serverOnly: flags.server });
+            process.stdout.write(
+                '\n' +
+                    success('  ✓ ') +
+                    bold(flags.server ? 'server build complete' : 'build complete') +
+                    '\n\n',
+            );
             break;
 
         case 'start': {
@@ -215,7 +228,12 @@ async function main(): Promise<void> {
         case 'doctor':
             // Skip the banner for --json so stdout stays valid JSON.
             if (!flags.json) banner();
-            await runDoctor({ root: flags.root, cwd: process.cwd(), json: flags.json, fix: flags.fix });
+            await runDoctor({
+                root: flags.root,
+                cwd: process.cwd(),
+                json: flags.json,
+                fix: flags.fix,
+            });
             break;
 
         case 'update':

package/src/compiler/index.ts

@@ -11,13 +11,81 @@ import { generate } from './generate.js';
 import { prerenderStaticParams } from './ssg.js';
 import { createViteConfig } from './vite.js';
 
+/**
+ * Every server `.ts` source file (under the directories of the toilconfig `entries`, or `server/`
+ * by default). Passed to toilscript as explicit entries so a dropped-in `@data`/`@rest` file is
+ * compiled - and its surface picked up into `shared/server.ts` - even if the toilconfig lists only
+ * `main.ts`. Paths are returned relative to `root`.
+ */
+/**
+ * A `@data`/`@rest`/`@service`/`@remote` declaration - a file with one defines client surface.
+ * Anchored to line-start (after indentation) so a mention in a comment (e.g. `// the @rest ...`)
+ * does not count.
+ */
+const SURFACE_DECORATOR = /^[ \t]*@(data|rest|service|remote)\b/m;
+
+function serverEntryFiles(root: string): string[] {
+    let entries: string[] = [];
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8')) as {
+            entries?: unknown;
+        };
+        if (Array.isArray(cfg.entries)) {
+            entries = cfg.entries.filter((e): e is string => typeof e === 'string');
+        }
+    } catch {
+        return [];
+    }
+
+    // Start from the toilconfig entries (normalized), then add any server file that declares a
+    // surface, so a dropped-in @data/@rest file is compiled even when it is not listed. Non-surface
+    // helpers stay out of the entry list - they are still compiled when imported - which also avoids
+    // toilscript's "class is not a WebAssembly export" warning for handler classes.
+    const result = new Set<string>(entries.map((e) => path.relative(root, path.resolve(root, e))));
+
+    const dirs = new Set<string>();
+    for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
+    if (dirs.size === 0) dirs.add(path.join(root, 'server'));
+
+    let scanned = 0;
+    const cap = 500;
+    const visit = (dir: string, depth: number): void => {
+        if (scanned >= cap || depth > 16) return;
+        let listing: fs.Dirent[];
+        try {
+            listing = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of listing) {
+            if (scanned >= cap) break;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name !== 'node_modules') visit(full, depth + 1);
+            } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+                scanned++;
+                try {
+                    if (SURFACE_DECORATOR.test(fs.readFileSync(full, 'utf8'))) {
+                        result.add(path.relative(root, full));
+                    }
+                } catch {
+                    // unreadable: skip
+                }
+            }
+        }
+    };
+    for (const dir of dirs) visit(dir, 0);
+    return [...result].sort();
+}
+
 /**
  * Builds the toilscript server target (which also regenerates `shared/server.ts` via
  * `--rpcModule`) when the project has one, signalled by a `toilconfig.json` at the root. This
  * runs before the client build/dev so the generated `@data` + `Server` module the client
  * imports is always current; without it a stale or missing `shared/server.ts` breaks the
- * client build. A no-op for client-only projects. Runs the locally installed `toilscript`
- * (resolved + invoked via Node, so no `.bin` shim / PATH assumptions).
+ * client build. A no-op for client-only projects. Compiles every server `.ts` file (not just the
+ * toilconfig entries) so dropped-in `@data`/`@rest` files are picked up. Runs the locally
+ * installed `toilscript`, resolved + invoked via Node (no `.bin` shim / PATH assumptions).
  */
 async function buildServer(root: string): Promise<void> {
     if (!fs.existsSync(path.join(root, 'toilconfig.json'))) return;
@@ -39,12 +107,13 @@ async function buildServer(root: string): Promise<void> {
         );
     }
 
+    // Explicit entries (every server file) override the toilconfig entries; the target options
+    // (optimization, features, runtime) still come from the toilconfig's `release` target.
+    const files = serverEntryFiles(root);
+    const args = [binJs, ...files, '--target', 'release', '--rpcModule', 'shared/server.ts'];
+
     await new Promise<void>((resolve, reject) => {
-        const child = spawn(
-            process.execPath,
-            [binJs, '--target', 'release', '--rpcModule', 'shared/server.ts'],
-            { cwd: root, stdio: 'inherit' },
-        );
+        const child = spawn(process.execPath, args, { cwd: root, stdio: 'inherit' });
         child.on('error', reject);
         child.on('close', (code) =>
             code === 0
@@ -59,6 +128,8 @@ export interface ToilCommandOptions {
     readonly port?: number;
     /** Bind host for `start`. Defaults to loopback (`127.0.0.1`); pass `0.0.0.0` to expose. */
     readonly host?: string;
+    /** `build` only: build the server (regenerate `shared/server.ts` + the wasm) and skip the client. */
+    readonly serverOnly?: boolean;
 }
 
 /** Starts the Vite dev server (HMR + transforms) for the client app. Returns the running server. */
@@ -72,10 +143,12 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
     return server;
 }
 
-/** Produces an optimized production SPA bundle in the configured `outDir`. */
+/** Produces an optimized production SPA bundle in the configured `outDir`. With `serverOnly`,
+ *  builds just the server (regenerates `shared/server.ts` + the wasm) and skips the client. */
 export async function build(opts: ToilCommandOptions = {}): Promise<void> {
     const cfg = await loadConfig(opts);
     await buildServer(cfg.root);
+    if (opts.serverOnly) return;
     generate(cfg);
     await viteBuild(await createViteConfig(cfg));
     // SSG: bake per-URL HTML + sitemap for dynamic routes that opt in via `generateStaticParams`.