toiljs 0.0.15 → 0.0.19

package/src/cli/updates.ts

@@ -1,69 +1,69 @@
-/**
- * Pure helpers for `toiljs update`: parse `npm-check-updates --jsonUpgraded` output and classify the
- * semver bump of each upgrade. IO-free so it can be unit-tested; the spawn/UI live in `update.ts`.
- */
-
-/** The kind of version jump an upgrade represents. */
-export type Bump = 'major' | 'minor' | 'patch' | 'other';
-
-/** One available upgrade: package, current range, target range, and bump kind. */
-export interface UpdateRow {
-    readonly name: string;
-    readonly from: string;
-    readonly to: string;
-    readonly bump: Bump;
-}
-
-/** Extracts a version's leading `x.y.z` (ignoring `^`, `~`, `>=`, etc.); missing parts become 0. */
-function parseVersion(v: string): [number, number, number] {
-    const m = /(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(v);
-    if (!m) return [0, 0, 0];
-    return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
-}
-
-/** Classifies the bump from `from` to `to` (both may be ranges like `^1.2.3`). */
-export function classifyBump(from: string, to: string): Bump {
-    const [fa, fb, fc] = parseVersion(from);
-    const [ta, tb, tc] = parseVersion(to);
-    if (ta !== fa) return 'major';
-    if (tb !== fb) return 'minor';
-    if (tc !== fc) return 'patch';
-    return 'other';
-}
-
-/**
- * Parses the JSON object `npm-check-updates --jsonUpgraded` prints (a `{ name: range }` map). Tolerant
- * of leading/trailing noise (npx banners) by slicing to the outermost braces. Returns `{}` on failure.
- */
-export function parseNcuJson(stdout: string): Record<string, string> {
-    const start = stdout.indexOf('{');
-    const end = stdout.lastIndexOf('}');
-    if (start === -1 || end <= start) return {};
-    try {
-        const parsed: unknown = JSON.parse(stdout.slice(start, end + 1));
-        if (typeof parsed !== 'object' || parsed === null) return {};
-        const out: Record<string, string> = {};
-        for (const [k, v] of Object.entries(parsed)) if (typeof v === 'string') out[k] = v;
-        return out;
-    } catch {
-        return {};
-    }
-}
-
-const SEVERITY: Record<Bump, number> = { major: 0, minor: 1, patch: 2, other: 3 };
-
-/**
- * Builds the upgrade rows from the ncu map and the project's current dependency ranges, sorted by
- * bump severity (major first) then name.
- */
-export function buildRows(
-    upgraded: Record<string, string>,
-    currentDeps: Record<string, string>,
-): UpdateRow[] {
-    return Object.entries(upgraded)
-        .map(([name, to]) => {
-            const from = currentDeps[name] ?? '?';
-            return { name, from, to, bump: classifyBump(from, to) };
-        })
-        .sort((a, b) => SEVERITY[a.bump] - SEVERITY[b.bump] || a.name.localeCompare(b.name));
-}
+/**
+ * Pure helpers for `toiljs update`: parse `npm-check-updates --jsonUpgraded` output and classify the
+ * semver bump of each upgrade. IO-free so it can be unit-tested; the spawn/UI live in `update.ts`.
+ */
+
+/** The kind of version jump an upgrade represents. */
+export type Bump = 'major' | 'minor' | 'patch' | 'other';
+
+/** One available upgrade: package, current range, target range, and bump kind. */
+export interface UpdateRow {
+    readonly name: string;
+    readonly from: string;
+    readonly to: string;
+    readonly bump: Bump;
+}
+
+/** Extracts a version's leading `x.y.z` (ignoring `^`, `~`, `>=`, etc.); missing parts become 0. */
+function parseVersion(v: string): [number, number, number] {
+    const m = /(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(v);
+    if (!m) return [0, 0, 0];
+    return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
+}
+
+/** Classifies the bump from `from` to `to` (both may be ranges like `^1.2.3`). */
+export function classifyBump(from: string, to: string): Bump {
+    const [fa, fb, fc] = parseVersion(from);
+    const [ta, tb, tc] = parseVersion(to);
+    if (ta !== fa) return 'major';
+    if (tb !== fb) return 'minor';
+    if (tc !== fc) return 'patch';
+    return 'other';
+}
+
+/**
+ * Parses the JSON object `npm-check-updates --jsonUpgraded` prints (a `{ name: range }` map). Tolerant
+ * of leading/trailing noise (npx banners) by slicing to the outermost braces. Returns `{}` on failure.
+ */
+export function parseNcuJson(stdout: string): Record<string, string> {
+    const start = stdout.indexOf('{');
+    const end = stdout.lastIndexOf('}');
+    if (start === -1 || end <= start) return {};
+    try {
+        const parsed: unknown = JSON.parse(stdout.slice(start, end + 1));
+        if (typeof parsed !== 'object' || parsed === null) return {};
+        const out: Record<string, string> = {};
+        for (const [k, v] of Object.entries(parsed)) if (typeof v === 'string') out[k] = v;
+        return out;
+    } catch {
+        return {};
+    }
+}
+
+const SEVERITY: Record<Bump, number> = { major: 0, minor: 1, patch: 2, other: 3 };
+
+/**
+ * Builds the upgrade rows from the ncu map and the project's current dependency ranges, sorted by
+ * bump severity (major first) then name.
+ */
+export function buildRows(
+    upgraded: Record<string, string>,
+    currentDeps: Record<string, string>,
+): UpdateRow[] {
+    return Object.entries(upgraded)
+        .map(([name, to]) => {
+            const from = currentDeps[name] ?? '?';
+            return { name, from, to, bump: classifyBump(from, to) };
+        })
+        .sort((a, b) => SEVERITY[a.bump] - SEVERITY[b.bump] || a.name.localeCompare(b.name));
+}

package/src/cli/validate.ts

@@ -1,31 +1,31 @@
-/**
- * Pure input validation for `toiljs create`, kept dependency-light (only node:path) so it can be
- * unit-tested without pulling in the rest of the CLI.
- */
-import path from 'node:path';
-
-/** Package managers the scaffolder may invoke. Allowlisted so a hostile `--pm` can't inject a shell command. */
-export const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
-
-/** Validates a project name's characters. Returns `true`, or an error message. */
-export function isValidName(name: string): true | string {
-    if (!name.trim()) return 'Please enter a project name.';
-    if (!/^[a-z0-9._@/-]+$/i.test(name)) return 'Use letters, numbers, dashes, dots or slashes.';
-    return true;
-}
-
-/**
- * Resolves `name` to an absolute directory under `cwd`, refusing to escape it (a name like
- * `../x` or an absolute path). Returns the resolved dir, or `null` if it would escape `cwd`.
- */
-export function resolveProjectDir(cwd: string, name: string): string | null {
-    const target = path.resolve(cwd, name);
-    const rel = path.relative(cwd, target);
-    if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
-    return target;
-}
-
-/** Whether `pm` is a supported package manager (guards shell use of `--pm`). */
-export function isPackageManager(pm: string): boolean {
-    return PACKAGE_MANAGERS.includes(pm);
-}
+/**
+ * Pure input validation for `toiljs create`, kept dependency-light (only node:path) so it can be
+ * unit-tested without pulling in the rest of the CLI.
+ */
+import path from 'node:path';
+
+/** Package managers the scaffolder may invoke. Allowlisted so a hostile `--pm` can't inject a shell command. */
+export const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+
+/** Validates a project name's characters. Returns `true`, or an error message. */
+export function isValidName(name: string): true | string {
+    if (!name.trim()) return 'Please enter a project name.';
+    if (!/^[a-z0-9._@/-]+$/i.test(name)) return 'Use letters, numbers, dashes, dots or slashes.';
+    return true;
+}
+
+/**
+ * Resolves `name` to an absolute directory under `cwd`, refusing to escape it (a name like
+ * `../x` or an absolute path). Returns the resolved dir, or `null` if it would escape `cwd`.
+ */
+export function resolveProjectDir(cwd: string, name: string): string | null {
+    const target = path.resolve(cwd, name);
+    const rel = path.relative(cwd, target);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
+    return target;
+}
+
+/** Whether `pm` is a supported package manager (guards shell use of `--pm`). */
+export function isPackageManager(pm: string): boolean {
+    return PACKAGE_MANAGERS.includes(pm);
+}

package/src/client/channel/channel.ts

@@ -1,146 +1,146 @@
-/**
- * Client for the toil backend's WebSocket channel (served by the hyper-express/uWS backend at
- * `/_toil`). Supports text and binary (`ArrayBuffer`) frames, auto-reconnect, and a React hook.
- */
-import { useCallback, useEffect, useRef, useState } from 'react';
-
-/** A frame received from / sent to the channel. */
-export type ChannelData = string | ArrayBuffer;
-
-/** Whatever `WebSocket.send` accepts (string / BufferSource / Blob), per the DOM lib. */
-export type SendData = Parameters<WebSocket['send']>[0];
-
-export interface ChannelOptions {
-    /** Channel path on the toil backend. Default `/_toil`. */
-    readonly path?: string;
-    /** Full `ws(s)://` URL override (takes precedence over `path`). */
-    readonly url?: string;
-    /** Auto-reconnect after an unexpected close. Default `true`. */
-    readonly reconnect?: boolean;
-    /** Reconnect delay in ms. Default `1000`. */
-    readonly reconnectDelay?: number;
-}
-
-export interface Channel {
-    /** Sends a text or binary frame (no-op until the socket is open). */
-    send(data: SendData): void;
-    /** Closes the channel and stops reconnecting. */
-    close(): void;
-}
-
-/** Derives the channel's `ws(s)://` URL from the current page location. */
-export function resolveChannelUrl(
-    path: string = '/_toil',
-    location: { protocol: string; host: string } = window.location,
-): string {
-    const scheme = location.protocol === 'https:' ? 'wss:' : 'ws:';
-    const normalized = path.startsWith('/') ? path : `/${path}`;
-    return `${scheme}//${location.host}${normalized}`;
-}
-
-/**
- * Opens a channel to the backend, invoking `onMessage` for each frame. Reconnects on unexpected
- * close unless disabled. Returns a handle to `send()` and `close()`.
- */
-export function connectChannel(
-    onMessage: (data: ChannelData) => void,
-    options: ChannelOptions = {},
-): Channel {
-    const url = options.url ?? resolveChannelUrl(options.path);
-    const reconnect = options.reconnect ?? true;
-    const delay = options.reconnectDelay ?? 1000;
-
-    let socket: WebSocket | null = null;
-    let stopped = false;
-    let timer: ReturnType<typeof setTimeout> | undefined;
-
-    const open = (): void => {
-        const ws = new WebSocket(url);
-        ws.binaryType = 'arraybuffer';
-        socket = ws;
-        ws.addEventListener('message', (event: MessageEvent) => {
-            if (typeof event.data === 'string') onMessage(event.data);
-            else if (event.data instanceof ArrayBuffer) onMessage(event.data);
-        });
-        ws.addEventListener('close', () => {
-            if (!stopped && reconnect) timer = setTimeout(open, delay);
-        });
-    };
-    open();
-
-    return {
-        send: (data: SendData): void => {
-            if (socket && socket.readyState === WebSocket.OPEN) socket.send(data);
-        },
-        close: (): void => {
-            stopped = true;
-            if (timer !== undefined) clearTimeout(timer);
-            socket?.close();
-        },
-    };
-}
-
-export interface ChannelHook {
-    /** Whether the socket is currently open. */
-    readonly connected: boolean;
-    /** Frames received so far, in order. */
-    readonly messages: ChannelData[];
-    /** Sends a text or binary frame. */
-    send: (data: SendData) => void;
-}
-
-/**
- * React hook wrapping {@link connectChannel}: connects on mount, tracks `connected` state and the
- * received `messages`, and cleans up on unmount.
- */
-export function useChannel(options: ChannelOptions = {}): ChannelHook {
-    const { path, url, reconnect, reconnectDelay } = options;
-    const [connected, setConnected] = useState<boolean>(false);
-    const [messages, setMessages] = useState<ChannelData[]>([]);
-    const socketRef = useRef<WebSocket | null>(null);
-
-    useEffect(() => {
-        const target = url ?? resolveChannelUrl(path);
-        const shouldReconnect = reconnect ?? true;
-        const delay = reconnectDelay ?? 1000;
-        let stopped = false;
-        let timer: ReturnType<typeof setTimeout> | undefined;
-
-        const open = (): void => {
-            const ws = new WebSocket(target);
-            ws.binaryType = 'arraybuffer';
-            socketRef.current = ws;
-            ws.addEventListener('open', () => {
-                if (!stopped) setConnected(true);
-            });
-            ws.addEventListener('message', (event: MessageEvent) => {
-                if (typeof event.data === 'string') {
-                    const data = event.data;
-                    setMessages((prev) => [...prev, data]);
-                } else if (event.data instanceof ArrayBuffer) {
-                    const data = event.data;
-                    setMessages((prev) => [...prev, data]);
-                }
-            });
-            ws.addEventListener('close', () => {
-                if (stopped) return;
-                setConnected(false);
-                if (shouldReconnect) timer = setTimeout(open, delay);
-            });
-        };
-        open();
-
-        return () => {
-            stopped = true;
-            if (timer !== undefined) clearTimeout(timer);
-            socketRef.current?.close();
-        };
-    }, [path, url, reconnect, reconnectDelay]);
-
-    const send = useCallback((data: SendData): void => {
-        const socket = socketRef.current;
-        if (socket && socket.readyState === WebSocket.OPEN) socket.send(data);
-    }, []);
-
-    return { connected, messages, send };
-}
+/**
+ * Client for the toil backend's WebSocket channel (served by the hyper-express/uWS backend at
+ * `/_toil`). Supports text and binary (`ArrayBuffer`) frames, auto-reconnect, and a React hook.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** A frame received from / sent to the channel. */
+export type ChannelData = string | ArrayBuffer;
+
+/** Whatever `WebSocket.send` accepts (string / BufferSource / Blob), per the DOM lib. */
+export type SendData = Parameters<WebSocket['send']>[0];
+
+export interface ChannelOptions {
+    /** Channel path on the toil backend. Default `/_toil`. */
+    readonly path?: string;
+    /** Full `ws(s)://` URL override (takes precedence over `path`). */
+    readonly url?: string;
+    /** Auto-reconnect after an unexpected close. Default `true`. */
+    readonly reconnect?: boolean;
+    /** Reconnect delay in ms. Default `1000`. */
+    readonly reconnectDelay?: number;
+}
+
+export interface Channel {
+    /** Sends a text or binary frame (no-op until the socket is open). */
+    send(data: SendData): void;
+    /** Closes the channel and stops reconnecting. */
+    close(): void;
+}
+
+/** Derives the channel's `ws(s)://` URL from the current page location. */
+export function resolveChannelUrl(
+    path: string = '/_toil',
+    location: { protocol: string; host: string } = window.location,
+): string {
+    const scheme = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const normalized = path.startsWith('/') ? path : `/${path}`;
+    return `${scheme}//${location.host}${normalized}`;
+}
+
+/**
+ * Opens a channel to the backend, invoking `onMessage` for each frame. Reconnects on unexpected
+ * close unless disabled. Returns a handle to `send()` and `close()`.
+ */
+export function connectChannel(
+    onMessage: (data: ChannelData) => void,
+    options: ChannelOptions = {},
+): Channel {
+    const url = options.url ?? resolveChannelUrl(options.path);
+    const reconnect = options.reconnect ?? true;
+    const delay = options.reconnectDelay ?? 1000;
+
+    let socket: WebSocket | null = null;
+    let stopped = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    const open = (): void => {
+        const ws = new WebSocket(url);
+        ws.binaryType = 'arraybuffer';
+        socket = ws;
+        ws.addEventListener('message', (event: MessageEvent) => {
+            if (typeof event.data === 'string') onMessage(event.data);
+            else if (event.data instanceof ArrayBuffer) onMessage(event.data);
+        });
+        ws.addEventListener('close', () => {
+            if (!stopped && reconnect) timer = setTimeout(open, delay);
+        });
+    };
+    open();
+
+    return {
+        send: (data: SendData): void => {
+            if (socket && socket.readyState === WebSocket.OPEN) socket.send(data);
+        },
+        close: (): void => {
+            stopped = true;
+            if (timer !== undefined) clearTimeout(timer);
+            socket?.close();
+        },
+    };
+}
+
+export interface ChannelHook {
+    /** Whether the socket is currently open. */
+    readonly connected: boolean;
+    /** Frames received so far, in order. */
+    readonly messages: ChannelData[];
+    /** Sends a text or binary frame. */
+    send: (data: SendData) => void;
+}
+
+/**
+ * React hook wrapping {@link connectChannel}: connects on mount, tracks `connected` state and the
+ * received `messages`, and cleans up on unmount.
+ */
+export function useChannel(options: ChannelOptions = {}): ChannelHook {
+    const { path, url, reconnect, reconnectDelay } = options;
+    const [connected, setConnected] = useState<boolean>(false);
+    const [messages, setMessages] = useState<ChannelData[]>([]);
+    const socketRef = useRef<WebSocket | null>(null);
+
+    useEffect(() => {
+        const target = url ?? resolveChannelUrl(path);
+        const shouldReconnect = reconnect ?? true;
+        const delay = reconnectDelay ?? 1000;
+        let stopped = false;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+
+        const open = (): void => {
+            const ws = new WebSocket(target);
+            ws.binaryType = 'arraybuffer';
+            socketRef.current = ws;
+            ws.addEventListener('open', () => {
+                if (!stopped) setConnected(true);
+            });
+            ws.addEventListener('message', (event: MessageEvent) => {
+                if (typeof event.data === 'string') {
+                    const data = event.data;
+                    setMessages((prev) => [...prev, data]);
+                } else if (event.data instanceof ArrayBuffer) {
+                    const data = event.data;
+                    setMessages((prev) => [...prev, data]);
+                }
+            });
+            ws.addEventListener('close', () => {
+                if (stopped) return;
+                setConnected(false);
+                if (shouldReconnect) timer = setTimeout(open, delay);
+            });
+        };
+        open();
+
+        return () => {
+            stopped = true;
+            if (timer !== undefined) clearTimeout(timer);
+            socketRef.current?.close();
+        };
+    }, [path, url, reconnect, reconnectDelay]);
+
+    const send = useCallback((data: SendData): void => {
+        const socket = socketRef.current;
+        if (socket && socket.readyState === WebSocket.OPEN) socket.send(data);
+    }, []);
+
+    return { connected, messages, send };
+}

package/src/client/components/Form.tsx

@@ -1,65 +1,65 @@
-import { useRef, type ReactNode, type SyntheticEvent } from 'react';
-
-import { useAction, type ActionState, type RevalidateTarget } from '../routing/action.js';
-
-/** Props for {@link Form}. */
-export interface FormProps {
-    /** Handles the submission, receiving the form's `FormData`. May be async. */
-    action: (data: FormData) => void | Promise<void>;
-    /** Loader data to revalidate after a successful submit. Default `true` (the current route). */
-    revalidate?: RevalidateTarget;
-    /** Called after a successful submit. */
-    onSuccess?: () => void;
-    /** Called when the action throws. */
-    onError?: (error: unknown) => void;
-    /** Reset the form fields after a successful submit. Default `false`. */
-    resetOnSuccess?: boolean;
-    className?: string;
-    /**
-     * Form contents. Pass a render function to receive live submit state, e.g. to disable the
-     * button while pending: `{({ pending }) => <button disabled={pending}>Save</button>}`.
-     */
-    children?: ReactNode | ((state: ActionState<void>) => ReactNode);
-}
-
-/**
- * A `<form>` that runs an {@link useAction} on submit (no page reload) and revalidates loader data
- * on success, the write half of the loader/action data loop. Tracks pending/error state, which a
- * render-function child can read.
- */
-export function Form({
-    action,
-    revalidate,
-    onSuccess,
-    onError,
-    resetOnSuccess = false,
-    className,
-    children,
-}: FormProps): ReactNode {
-    const formRef = useRef<HTMLFormElement | null>(null);
-    const handle = useAction((data: FormData) => action(data), {
-        revalidate,
-        onError,
-        onSuccess: () => {
-            if (resetOnSuccess) formRef.current?.reset();
-            onSuccess?.();
-        },
-    });
-
-    const onSubmit = (event: SyntheticEvent<HTMLFormElement>): void => {
-        event.preventDefault();
-        formRef.current = event.currentTarget;
-        void handle.run(new FormData(event.currentTarget));
-    };
-
-    return (
-        <form
-            ref={formRef}
-            className={className}
-            onSubmit={onSubmit}>
-            {typeof children === 'function'
-                ? children({ pending: handle.pending, error: handle.error, data: handle.data })
-                : children}
-        </form>
-    );
-}
+import { useRef, type ReactNode, type SyntheticEvent } from 'react';
+
+import { useAction, type ActionState, type RevalidateTarget } from '../routing/action.js';
+
+/** Props for {@link Form}. */
+export interface FormProps {
+    /** Handles the submission, receiving the form's `FormData`. May be async. */
+    action: (data: FormData) => void | Promise<void>;
+    /** Loader data to revalidate after a successful submit. Default `true` (the current route). */
+    revalidate?: RevalidateTarget;
+    /** Called after a successful submit. */
+    onSuccess?: () => void;
+    /** Called when the action throws. */
+    onError?: (error: unknown) => void;
+    /** Reset the form fields after a successful submit. Default `false`. */
+    resetOnSuccess?: boolean;
+    className?: string;
+    /**
+     * Form contents. Pass a render function to receive live submit state, e.g. to disable the
+     * button while pending: `{({ pending }) => <button disabled={pending}>Save</button>}`.
+     */
+    children?: ReactNode | ((state: ActionState<void>) => ReactNode);
+}
+
+/**
+ * A `<form>` that runs an {@link useAction} on submit (no page reload) and revalidates loader data
+ * on success, the write half of the loader/action data loop. Tracks pending/error state, which a
+ * render-function child can read.
+ */
+export function Form({
+    action,
+    revalidate,
+    onSuccess,
+    onError,
+    resetOnSuccess = false,
+    className,
+    children,
+}: FormProps): ReactNode {
+    const formRef = useRef<HTMLFormElement | null>(null);
+    const handle = useAction((data: FormData) => action(data), {
+        revalidate,
+        onError,
+        onSuccess: () => {
+            if (resetOnSuccess) formRef.current?.reset();
+            onSuccess?.();
+        },
+    });
+
+    const onSubmit = (event: SyntheticEvent<HTMLFormElement>): void => {
+        event.preventDefault();
+        formRef.current = event.currentTarget;
+        void handle.run(new FormData(event.currentTarget));
+    };
+
+    return (
+        <form
+            ref={formRef}
+            className={className}
+            onSubmit={onSubmit}>
+            {typeof children === 'function'
+                ? children({ pending: handle.pending, error: handle.error, data: handle.data })
+                : children}
+        </form>
+    );
+}