toiljs 0.0.115 → 0.0.117

package/docs/services/time.md

@@ -1,85 +0,0 @@
-# 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/eslint.config.js

@@ -1,57 +0,0 @@
-// @ts-check
-
-import eslint from '@eslint/js';
-import tseslint from 'typescript-eslint';
-
-export default tseslint.config(
-    // toilscript server (WASM) + its ambient std + build output are not part of the TS project.
-    // toil-docs.generated.ts is a build artifact (gitignored, emitted by gen:docs) — not linted.
-    {
-        ignores: [
-            'build/**',
-            'server/**',
-            'std/server/**',
-            'toil-env.d.ts',
-            'src/compiler/toil-docs.generated.ts',
-        ],
-    },
-    eslint.configs.recommended,
-    ...tseslint.configs.strictTypeChecked,
-    {
-        languageOptions: {
-            parserOptions: {
-                projectService: true,
-                tsconfigDirName: import.meta.dirname,
-            },
-        },
-        rules: {
-            'no-undef': 'off',
-            '@typescript-eslint/no-unused-vars': 'off',
-            'no-empty': 'off',
-            '@typescript-eslint/restrict-template-expressions': 'off',
-            '@typescript-eslint/only-throw-error': 'off',
-            '@typescript-eslint/no-unnecessary-condition': 'off',
-            '@typescript-eslint/unbound-method': 'warn',
-            '@typescript-eslint/no-confusing-void-expression': 'off',
-            '@typescript-eslint/no-extraneous-class': 'off',
-            'no-async-promise-executor': 'off',
-            '@typescript-eslint/no-misused-promises': 'off',
-            '@typescript-eslint/no-unnecessary-type-parameters': 'off',
-            '@typescript-eslint/no-duplicate-enum-values': 'off',
-            'prefer-spread': 'off',
-            '@typescript-eslint/no-empty-object-type': 'off',
-            '@typescript-eslint/no-base-to-string': 'off',
-            '@typescript-eslint/no-dynamic-delete': 'off',
-            '@typescript-eslint/no-redundant-type-constituents': 'off',
-
-            // This is stupid. null and undefined is not the same thing. who ever made this eslint rule is stupid.
-            'no-useless-assignment': 'off',
-            '@typescript-eslint/no-unnecessary-type-arguments': 'off',
-            '@typescript-eslint/no-unnecessary-type-assertion': 'off',
-        },
-    },
-    {
-        files: ['**/*.js'],
-        ...tseslint.configs.disableTypeChecked,
-    },
-);

package/examples/basic/client/routes/docs/[...slug].tsx

@@ -1,12 +0,0 @@
-export default function Docs() {
-    const { slug } = Toil.useParams();
-    return (
-        <main>
-            <h1>Docs</h1>
-            <p>
-                Catch-all route <code>client/routes/docs/[...slug].tsx</code> matched: <code>{slug}</code>
-            </p>
-            <Toil.Link href="/">Back home</Toil.Link>
-        </main>
-    );
-}

package/presets/eslint.js

@@ -1,88 +0,0 @@
-/** toiljs shared ESLint flat config: `import toiljs from 'toiljs/eslint'; export default toiljs;` */
-import eslintReact from '@eslint-react/eslint-plugin';
-import eslint from '@eslint/js';
-import reactHooks from 'eslint-plugin-react-hooks';
-import reactRefresh from 'eslint-plugin-react-refresh';
-import tseslint from 'typescript-eslint';
-
-import noUint8ArrayToString from './no-uint8array-tostring.js';
-
-export default tseslint.config(
-    { ignores: ['dist', 'build', '.toil', 'node_modules', 'toil-env.d.ts', 'server/**'] },
-    {
-        extends: [
-            eslint.configs.recommended,
-            ...tseslint.configs.recommended,
-            ...tseslint.configs.strictTypeChecked,
-        ],
-        files: ['**/*.{ts,tsx}'],
-        languageOptions: {
-            ecmaVersion: 2023,
-            parserOptions: {
-                projectService: true,
-            },
-        },
-        plugins: {
-            'react-hooks': reactHooks,
-            'react-refresh': reactRefresh,
-            '@eslint-react': eslintReact,
-            custom: noUint8ArrayToString,
-        },
-        rules: {
-            ...reactHooks.configs.recommended.rules,
-            // Route files conventionally export `loader` / `revalidate` / `metadata` /
-            // `generateMetadata` / `searchHints` alongside the default component; the toil compiler
-            // consumes them at runtime/build. Allow them (plus primitive constants) so Fast Refresh
-            // doesn't flag the pattern.
-            'react-refresh/only-export-components': [
-                'warn',
-                {
-                    allowConstantExport: true,
-                    allowExportNames: [
-                        'loader',
-                        'revalidate',
-                        'metadata',
-                        'generateMetadata',
-                        'searchHints',
-                    ],
-                },
-            ],
-            'no-undef': 'off',
-            '@typescript-eslint/no-unused-vars': 'off',
-            'no-empty': 'off',
-            '@typescript-eslint/restrict-template-expressions': 'off',
-            '@typescript-eslint/only-throw-error': 'off',
-            '@typescript-eslint/no-unnecessary-condition': 'off',
-            '@typescript-eslint/unbound-method': 'warn',
-            '@typescript-eslint/no-confusing-void-expression': 'off',
-            '@typescript-eslint/no-extraneous-class': 'off',
-            'no-async-promise-executor': 'off',
-            '@typescript-eslint/no-misused-promises': 'off',
-            '@typescript-eslint/no-unnecessary-type-parameters': 'off',
-            '@typescript-eslint/no-duplicate-enum-values': 'off',
-            'prefer-spread': 'off',
-            '@typescript-eslint/no-empty-object-type': 'off',
-            '@typescript-eslint/no-floating-promises': 'off',
-            '@typescript-eslint/ban-ts-comment': 'off',
-            'no-constant-binary-expression': 'off',
-            'no-useless-assignment': 'off',
-            '@typescript-eslint/no-unsafe-assignment': 'off',
-            '@typescript-eslint/no-unsafe-call': 'off',
-            '@typescript-eslint/no-unsafe-member-access': 'off',
-            '@typescript-eslint/no-unsafe-argument': 'off',
-            '@typescript-eslint/no-unnecessary-type-conversion': 'warn',
-            'react-hooks/set-state-in-effect': 'warn',
-            'custom/no-uint8array-tostring': 'error',
-            'padding-line-between-statements': [
-                'error',
-                { blankLine: 'always', prev: 'block-like', next: '*' },
-            ],
-            '@typescript-eslint/no-deprecated': 'off',
-            '@typescript-eslint/no-unnecessary-type-arguments': 'off',
-        },
-    },
-    {
-        files: ['**/*.js'],
-        ...tseslint.configs.disableTypeChecked,
-    },
-);

package/src/backend/index.ts

@@ -1,204 +0,0 @@
-/**
- * toiljs backend, the self-host / dev server, built on @dacely/hyper-express (uWebSockets.js)
- * for very high throughput. It serves the built client (static assets + SPA fallback) and exposes
- * a WebSocket channel for realtime / live updates.
- *
- * This is the Node "server" that hosts the app on a local machine; it is distinct from the
- * toilscript WASM runtime in `server/runtime` (the `toiljs/server/runtime` library export).
- */
-import fs from 'node:fs';
-import path from 'node:path';
-
-import {
-    type MiddlewareNext,
-    type Request,
-    type Response,
-    Server,
-    type Websocket,
-} from '@dacely/hyper-express';
-
-const DEFAULT_MAX_BODY_LENGTH = 1024 * 1024 * 8;
-const MAX_BODY_BUFFER = 1024 * 32;
-const HTTP_IDLE_TIMEOUT = 60;
-const HTTP_RESPONSE_TIMEOUT = 120;
-
-const WS_MAX_PAYLOAD_LENGTH = 1024 * 1024;
-const WS_IDLE_TIMEOUT = 120;
-const WS_MAX_BACKPRESSURE = 1024 * 1024 * 2;
-
-const CORS_METHODS = 'GET, POST, OPTIONS, PUT, PATCH, DELETE';
-const CORS_HEADERS = 'X-Requested-With, content-type';
-
-/** Options for {@link startBackend}. */
-export interface BackendOptions {
-    /** Directory to serve (the built client `outDir`, e.g. `dist`). */
-    readonly root: string;
-    /** Listening port. Default `3000`. */
-    readonly port?: number;
-    /**
-     * Bind host. Default `127.0.0.1` (loopback only). Pass `0.0.0.0` (or a specific interface) to
-     * expose the server on the network; do so deliberately, since the WebSocket channel relays
-     * messages between all connected clients.
-     */
-    readonly host?: string;
-    /**
-     * Extra origins allowed to open the WebSocket channel, in addition to the server's own origin.
-     * Cross-origin WebSocket handshakes from other origins are rejected (prevents cross-site
-     * WebSocket hijacking). Example: `['https://app.example.com']`.
-     */
-    readonly allowedOrigins?: readonly string[];
-    /** WebSocket channel path. Default `/_toil`. */
-    readonly wsPath?: string;
-    /** Send permissive CORS headers + handle preflight. Default `true`. */
-    readonly cors?: boolean;
-    /** Max request body length in bytes. Default 8 MB. */
-    readonly maxBodyLength?: number;
-}
-
-/** A running backend instance. */
-export interface RunningBackend {
-    readonly port: number;
-    readonly host: string;
-    readonly wsPath: string;
-    /** Sends a message to every connected WebSocket client. */
-    broadcast(message: string): void;
-    /** Number of currently-connected WebSocket clients. */
-    clientCount(): number;
-    /** Gracefully shuts the server down. */
-    close(): Promise<void>;
-}
-
-/**
- * Whether a WebSocket upgrade from `origin` may connect. A missing `Origin` (non-browser clients
- * like curl or server-to-server) is allowed; a browser `Origin` must match the host the server was
- * reached at (same-origin) or be in the explicit allowlist. This blocks cross-site WebSocket
- * hijacking, where a page the victim visits opens a socket to this server from their browser.
- */
-function isWsOriginAllowed(
-    origin: string | undefined,
-    hostHeader: string | undefined,
-    allowed: readonly string[] | undefined,
-): boolean {
-    if (!origin) return true;
-    if (allowed?.includes(origin)) return true;
-    try {
-        return new URL(origin).host === hostHeader;
-    } catch {
-        return false;
-    }
-}
-
-/** Resolves a request path to a file inside `root`, guarding against path traversal. */
-function resolveStaticFile(root: string, requestPath: string): string | null {
-    const decoded = decodeURIComponent(requestPath);
-    const resolved = path.join(root, decoded);
-    if (resolved !== root && !resolved.startsWith(root + path.sep)) return null;
-    if (decoded === '/' || decoded === '') return null;
-    if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved;
-    return null;
-}
-
-/**
- * Starts the hyper-express server serving `root` with an SPA fallback to `index.html`,
- * plus a WebSocket channel at `wsPath`. Resolves once the server is listening.
- */
-export async function startBackend(options: BackendOptions): Promise<RunningBackend> {
-    const port = options.port ?? 3000;
-    const host = options.host ?? '127.0.0.1';
-    const wsPath = options.wsPath ?? '/_toil';
-    const cors = options.cors ?? true;
-    const root = path.resolve(options.root);
-    const indexHtml = path.join(root, 'index.html');
-
-    const app = new Server({
-        max_body_length: options.maxBodyLength ?? DEFAULT_MAX_BODY_LENGTH,
-        max_body_buffer: MAX_BODY_BUFFER,
-        fast_abort: true,
-        idle_timeout: HTTP_IDLE_TIMEOUT,
-        response_timeout: HTTP_RESPONSE_TIMEOUT,
-    });
-
-    const clients = new Set<Websocket>();
-
-    app.set_error_handler((_request: Request, response: Response, _error: Error) => {
-        if (response.completed) return;
-        response.atomic(() => {
-            response.status(500).json({ error: 'Internal server error.' });
-        });
-    });
-
-    if (cors) {
-        app.use((request: Request, response: Response, next: MiddlewareNext) => {
-            if (request.method !== 'OPTIONS') {
-                response.setHeader('Access-Control-Allow-Origin', '*');
-                response.setHeader('Access-Control-Allow-Methods', CORS_METHODS);
-                response.setHeader('Access-Control-Allow-Headers', CORS_HEADERS);
-            }
-            response.removeHeader('uWebSockets');
-            next();
-        });
-        app.options('/*', (_request: Request, response: Response) => {
-            response.setHeader('Access-Control-Allow-Origin', '*');
-            response.setHeader('Access-Control-Allow-Methods', CORS_METHODS);
-            response.setHeader('Access-Control-Allow-Headers', CORS_HEADERS);
-            response.setHeader('Access-Control-Max-Age', '86400');
-            response.status(204).send();
-        });
-    }
-
-    app.ws(
-        wsPath,
-        {
-            message_type: 'String',
-            max_payload_length: WS_MAX_PAYLOAD_LENGTH,
-            idle_timeout: WS_IDLE_TIMEOUT,
-            max_backpressure: WS_MAX_BACKPRESSURE,
-        },
-        (ws) => {
-            clients.add(ws);
-            ws.send(JSON.stringify({ type: 'connected', clients: clients.size }));
-            ws.on('message', (message: string) => {
-                for (const client of clients) client.send(message);
-            });
-            ws.on('drain', () => {});
-            ws.on('close', () => {
-                clients.delete(ws);
-            });
-        },
-    );
-
-    // Gate the WebSocket upgrade on the request Origin, so a cross-origin page in a victim's browser
-    // cannot hijack the channel (CSWSH). Registered AFTER `app.ws` so it overrides that route's
-    // default upgrade handler (hyper-express links it to the companion ws route). Same-origin and
-    // non-browser clients pass; others get 403.
-    app.upgrade(wsPath, (request: Request, response: Response) => {
-        if (
-            !isWsOriginAllowed(request.headers.origin, request.headers.host, options.allowedOrigins)
-        ) {
-            response.status(403).send();
-            return;
-        }
-        response.upgrade({});
-    });
-
-    app.get('/*', (request: Request, response: Response) => {
-        if (response.completed) return;
-        const file = resolveStaticFile(root, request.path);
-        response.sendFile(file ?? indexHtml);
-    });
-
-    await app.listen(port, host);
-
-    return {
-        port,
-        host,
-        wsPath,
-        broadcast: (message: string): void => {
-            for (const client of clients) client.send(message);
-        },
-        clientCount: (): number => clients.size,
-        close: async (): Promise<void> => {
-            await app.shutdown();
-        },
-    };
-}