toiljs 0.0.67 → 0.0.69

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.67",
+    "version": "0.0.69",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -134,7 +134,7 @@
         "nodemailer": "^9.0.1",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.2",
-        "toilscript": "^0.1.42",
+        "toilscript": "^0.1.44",
         "typescript-eslint": "^8.62.0",
         "vite": "^8.1.0",
         "vite-imagetools": "^10.0.1",

package/src/cli/index.ts

@@ -19,6 +19,7 @@ interface Flags {
     root?: string;
     port?: number;
     host?: string;
+    threads?: number;
     name?: string;
     template?: Template;
     preprocessor?: Preprocessor;
@@ -51,6 +52,12 @@ function parseArgs(argv: string[]): Flags {
             case '--host':
                 flags.host = argv[++i];
                 break;
+            case '--threads':
+            case '--workers': {
+                const threads = Number(argv[++i]);
+                if (!Number.isNaN(threads)) flags.threads = threads;
+                break;
+            }
             case '--template':
             case '-t': {
                 const t = argv[++i];
@@ -138,6 +145,7 @@ function printHelp(): void {
             bold('Options'),
             cmd('--root <dir>', 'project root (default: current directory)'),
             cmd('--port <n>', 'dev server port'),
+            cmd('--threads <n>', 'start: production HTTP worker count'),
             cmd('-t, --template', 'create: app | minimal'),
             cmd('--style <name>', 'create/configure: css | sass | less | stylus'),
             cmd('--tailwind', 'create/configure: enable Tailwind (--no-tailwind to remove)'),
@@ -226,7 +234,12 @@ async function main(): Promise<void> {
         case 'start': {
             banner();
             process.stdout.write(dim('  self-hosting the built app…') + '\n\n');
-            const server = await start({ root: flags.root, port: flags.port, host: flags.host });
+            const server = await start({
+                root: flags.root,
+                port: flags.port,
+                host: flags.host,
+                threads: flags.threads,
+            });
             process.stdout.write(
                 accent('  ➜ ') +
                     bold(`http://localhost:${String(server.port)}`) +

package/src/client/index.ts

@@ -79,6 +79,8 @@ export { matchRoute } from './routing/match.js';
 export type { RouteParams } from './routing/match.js';
 export { connectChannel, useChannel, resolveChannelUrl } from './channel/channel.js';
 export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel/channel.js';
+export { makeStreamClient } from './stream/client.js';
+export type { StreamChannel, StreamConnectable, StreamClient } from './stream/client.js';
 export { useHead, useTitle, Head, mergeHead } from './head/head.js';
 export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head/head.js';
 export { resolveMetadata, useMetadata, Metadata } from './head/metadata.js';

package/src/client/rpc.ts

@@ -24,7 +24,26 @@ function restMissingStub(path: string): unknown {
     return new Proxy(call, {
         get(_target, prop) {
             if (typeof prop === 'symbol' || prop === 'then') return undefined;
-            return restMissingStub(`${path}.${String(prop)}`);
+            return restMissingStub(`${path}.${prop}`);
+        },
+        apply() {
+            return call();
+        },
+    });
+}
+
+/** A recursive proxy that throws on call, used when the stream client hasn't loaded. */
+function streamMissingStub(path: string): unknown {
+    const call = (): never => {
+        throw new Error(
+            `toiljs Stream: ${path}() is unavailable. The generated stream client has not loaded - ` +
+                `import a type from your 'shared/server' (so the client attaches), or run 'npm run build:server'.`,
+        );
+    };
+    return new Proxy(call, {
+        get(_target, prop) {
+            if (typeof prop === 'symbol' || prop === 'then') return undefined;
+            return streamMissingStub(`${path}.${prop}`);
         },
         apply() {
             return call();
@@ -49,6 +68,11 @@ function rpcStub(path: string): unknown {
                 const rest = (globalThis as { __toilRest?: unknown }).__toilRest;
                 return rest !== undefined ? rest : restMissingStub('Server.REST');
             }
+            // `Server.Stream` surfaces the generated stream client attached by shared/server.ts.
+            if (path === 'Server' && prop === 'Stream') {
+                const stream = (globalThis as { __toilStream?: unknown }).__toilStream;
+                return stream !== undefined ? stream : streamMissingStub('Server.Stream');
+            }
             return rpcStub(`${path}.${prop}`);
         },
         apply() {

package/src/client/stream/client.ts

@@ -0,0 +1,109 @@
+/**
+ * Client runtime for the typed `@stream` channel (doc 08 section 8.2). `Server.Stream.<Class>.connect(path?)`
+ * opens a browser `WebSocket` to the class's `route` (same origin) and returns a channel:
+ * `onMessage` / `send` / `onClose` / `close`. A raw `@stream` channel sends `Uint8Array`; a typed
+ * `@stream({ message: T })` channel sends the `@data` class and encodes it on send (the per-class
+ * encoder the generated module passes). The inbound reply is always raw bytes. The generated
+ * `shared/server.ts` (toilscript hot pass) attaches `makeStreamClient(routes, undefined, encoders)` to
+ * `globalThis.__toilStream`, and `Server.Stream`
+ * (`rpc.ts`) surfaces it - the same wiring the REST client uses via `globalThis.__toilRest`.
+ */
+
+/** A live `@stream` connection. `TSend` is the outbound message type: `Uint8Array` for a raw `@stream`,
+ *  or the `@data` class for a typed `@stream({ message: T })` (the channel encodes it before sending).
+ *  The inbound reply is ALWAYS raw bytes - the server's `StreamOutbound` is raw (doc 03 2.5). */
+export interface StreamChannel<TSend = Uint8Array> {
+    /** Register the inbound-frame handler (one call per server reply frame). */
+    onMessage(cb: (data: Uint8Array) => void): void;
+    /** Send one outbound message (one `@message` on the server); a typed channel encodes it first. */
+    send(data: TSend): void;
+    /** Register the close handler (`code` is the `0x02xx` stream close code, or the WS code). */
+    onClose(cb: (code: number) => void): void;
+    /** Close the connection. */
+    close(): void;
+}
+
+/** The connect factory for one `@stream` class. `path` is the `@connect` path (default `''`). */
+export interface StreamConnectable<TSend = Uint8Array> {
+    connect(path?: string): Promise<StreamChannel<TSend>>;
+}
+
+/** `Server.Stream`: one `connect()` factory per `@stream` class name. */
+export type StreamClient = Record<string, StreamConnectable>;
+
+/** Open a WebSocket to `url` and resolve a channel once the upgrade completes; reject if the socket
+ *  closes/errors BEFORE it opens (a 421 redirect / wrong-node / unreachable). A server close AFTER
+ *  open (e.g. a `@connect` reject or a guest reject) surfaces through `onClose(code)`. */
+function connectStream<TSend = Uint8Array>(
+    url: string,
+    encode?: (msg: never) => Uint8Array,
+): Promise<StreamChannel<TSend>> {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        ws.binaryType = 'arraybuffer';
+        let opened = false;
+        let messageCb: ((data: Uint8Array) => void) | undefined;
+        let closeCb: ((code: number) => void) | undefined;
+
+        const channel: StreamChannel<TSend> = {
+            onMessage: (cb): void => {
+                messageCb = cb;
+            },
+            onClose: (cb): void => {
+                closeCb = cb;
+            },
+            send: (data): void => {
+                if (ws.readyState !== WebSocket.OPEN) return;
+                // A typed channel encodes the @data message; a raw channel sends the bytes as-is.
+                const bytes = encode ? encode(data as never) : (data as unknown as Uint8Array);
+                ws.send(bytes as BufferSource);
+            },
+            close: (): void => {
+                ws.close();
+            },
+        };
+
+        ws.addEventListener('open', () => {
+            opened = true;
+            resolve(channel);
+        });
+        ws.addEventListener('message', (event: MessageEvent) => {
+            if (event.data instanceof ArrayBuffer) messageCb?.(new Uint8Array(event.data));
+        });
+        ws.addEventListener('close', (event: CloseEvent) => {
+            if (!opened) reject(new Error(`stream connect failed (closed ${String(event.code)})`));
+            else closeCb?.(event.code);
+        });
+        ws.addEventListener('error', () => {
+            if (!opened) reject(new Error('stream connect error'));
+        });
+    });
+}
+
+/** The same-origin WebSocket base (`ws://` / `wss://` per the page protocol). */
+function defaultOrigin(): string {
+    const loc = globalThis.location;
+    return `${loc.protocol === 'https:' ? 'wss:' : 'ws:'}//${loc.host}`;
+}
+
+/**
+ * Build the `Server.Stream` client from the generated route map (`{ ClassName: route }`). `origin`
+ * defaults to the page origin. `encoders` carries one `@data` encoder per typed `@stream({ message: T })`
+ * class (the generated `(m) => m.encode()`); a class with no entry is a raw byte channel. The generated
+ * `shared/server.ts` calls this and assigns the result to `globalThis.__toilStream`.
+ */
+export function makeStreamClient(
+    routes: Record<string, string>,
+    origin?: string,
+    encoders?: Record<string, (msg: never) => Uint8Array>,
+): StreamClient {
+    const base = origin ?? defaultOrigin();
+    const client: StreamClient = {};
+    for (const [name, route] of Object.entries(routes)) {
+        const encode = encoders?.[name];
+        client[name] = {
+            connect: (path = ''): Promise<StreamChannel> => connectStream(`${base}${route}${path}`, encode),
+        };
+    }
+    return client;
+}

package/src/compiler/config.ts

@@ -142,6 +142,11 @@ export interface ServerConfig {
     readonly nodeMode?: DevNodeMode;
     /** Daemon (L4) config mirror (dev / self-host). */
     readonly daemon?: DaemonConfig;
+    /**
+     * Self-host HTTP worker count for `toiljs start`. Default `auto`
+     * (`os.availableParallelism()`). Set `1` to disable the worker pool.
+     */
+    readonly threads?: number | 'auto';
 }
 
 /** Fully-resolved {@link DaemonConfig}; every field non-optional, defaults applied. */
@@ -199,6 +204,8 @@ export interface ResolvedToilConfig {
     readonly nodeMode: DevNodeMode;
     /** Daemon (L4) config mirror (dev / self-host), every field resolved. */
     readonly daemon: ResolvedDaemonConfig;
+    /** Self-host HTTP worker count for `toiljs start`. */
+    readonly threads: number | 'auto';
     /** Absolute path to the framework client runtime (`toiljs/client`). */
     readonly runtimePath: string;
     readonly vite: InlineConfig;
@@ -273,18 +280,13 @@ export async function loadConfig(
         email: user.server?.email ?? null,
         nodeMode: resolveNodeMode(user.server?.nodeMode),
         daemon: resolveDaemonConfig(user.server?.daemon),
+        threads: resolveThreads(user.server?.threads),
         runtimePath: resolveRuntimePath(),
         vite: client.vite ?? {},
     };
 }
 
-const DEV_NODE_MODES: readonly DevNodeMode[] = [
-    'hot',
-    'regional',
-    'continental',
-    'daemon',
-    'all',
-];
+const DEV_NODE_MODES: readonly DevNodeMode[] = ['hot', 'regional', 'continental', 'daemon', 'all'];
 
 /** A `nodeMode` outside the enum falls back to `all` with a warning (fail-soft:
  *  the authoritative role is the edge's TCF + plan, so dev never bricks on it). */
@@ -319,3 +321,9 @@ function resolveDaemonConfig(d: DaemonConfig | undefined): ResolvedDaemonConfig
         maxTasks,
     };
 }
+
+function resolveThreads(threads: number | 'auto' | undefined): number | 'auto' {
+    if (threads === undefined || threads === 'auto') return 'auto';
+    if (!Number.isFinite(threads)) return 'auto';
+    return Math.max(1, Math.min(128, Math.floor(threads)));
+}

package/src/compiler/index.ts

@@ -524,6 +524,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;
+    /** `start` only: production HTTP worker count. Defaults to `server.threads` / auto. */
+    readonly threads?: number;
     /** `build` only: build the server (regenerate `shared/server.ts` + the wasm) and skip the client. */
     readonly serverOnly?: boolean;
 }
@@ -699,6 +701,10 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
         // The daemon (cold) emulator drives `release-cold.wasm` per `nodeMode`; absent for a
         // project with no `@daemon` (the cold artifact never gets built, so the host stays idle).
         coldWasmFile: serverArtifacts(cfg.root).cold,
+        // The stream router serves `@stream`-route WebSocket upgrades from `release-stream.wasm` per
+        // `nodeMode`; the path points at the (maybe-not-yet-built) stream artifact, mtime-reloaded so
+        // a `@stream` build activates it, and harmless for a project with no `@stream` (no routes).
+        streamWasmFile: serverArtifacts(cfg.root).stream,
         nodeMode: cfg.nodeMode,
         daemon: cfg.daemon,
         vite: { host: '127.0.0.1', port: vitePort },
@@ -779,9 +785,9 @@ export async function build(opts: ToilCommandOptions = {}): Promise<void> {
 }
 
 /**
- * Self-hosts the built client over the high-performance hyper-express backend (uWebSockets.js),
- * serving the configured `outDir` with an SPA fallback plus a WebSocket channel. Requires a prior
- * `build`. Returns the running backend.
+ * Self-hosts the built app over the high-performance hyper-express backend (uWebSockets.js).
+ * Server projects use the built wasm + SSR templates before the SPA fallback; client-only projects
+ * use the static backend. Requires a prior `build`. Returns the running backend.
  */
 export async function start(opts: ToilCommandOptions = {}): Promise<RunningBackend> {
     const cfg = await loadConfig(opts);
@@ -789,8 +795,21 @@ export async function start(opts: ToilCommandOptions = {}): Promise<RunningBacke
     if (!fs.existsSync(path.join(outDir, 'index.html'))) {
         throw new Error(`No build found in ${outDir}. Run \`toiljs build\` first.`);
     }
-    const { startBackend } = await import('toiljs/backend');
-    return startBackend({ root: outDir, port: cfg.port, host: opts.host });
+    const wasmFile = serverWasmFile(cfg.root);
+    const { startBuiltServer } = await import('toiljs/devserver');
+    const artifacts = serverArtifacts(cfg.root);
+    return startBuiltServer({
+        root: cfg.root,
+        staticRoot: outDir,
+        wasmFile: fs.existsSync(wasmFile) ? wasmFile : undefined,
+        coldWasmFile: artifacts.cold,
+        nodeMode: cfg.nodeMode,
+        daemon: cfg.daemon,
+        threads: opts.threads ?? cfg.threads,
+        port: cfg.port,
+        host: opts.host,
+        email: cfg.email ?? undefined,
+    });
 }
 
 export { defineConfig, loadConfig, AiProvider } from './config.js';