ferrovue 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,14 +1,77 @@
 #!/usr/bin/env node
-/* `ferrovue` — compile the project's components, run from its root.
+/* `ferrovue`: compile the project's components, run from its root.
  *
- *   ferrovue          write the Rust modules to the configured output directory
- *   ferrovue --check  write nothing; exit 1 if the committed modules are not what would be written */
-import { readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-import { generate, loadConfig, write } from "./compiler.js";
+ *   ferrovue                  write the Rust modules to the configured output directory
+ *   ferrovue --check          write nothing; exit 1 if the committed modules are not what would be written
+ *   ferrovue --check --diff   show a unified diff of differences
+ *   ferrovue --watch          write them, then again whenever a component, store, type file, the routes
+ *                             or the configuration changes, until interrupted
+ *   ferrovue init             scaffold a starter ferrovue.config.json and components directory
+ *   ferrovue -c, --config     path to configuration file (default: ferrovue.config.json)
+ *   ferrovue -v, --version    print the version and exit
+ *   ferrovue -h, --help       print this help and exit */
+import { existsSync, mkdirSync, readFileSync, readdirSync, watch, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { CONFIG_FILE, GenError, generate, loadConfig, VERSION, write } from "./compiler.js";
+import { unifiedDiff } from "./diff.js";
 const root = process.cwd();
-const config = loadConfig(root);
-if (process.argv.includes("--check")) {
+const HELP = `Usage: ferrovue [command] [options]
+
+Compile Vue components to Rust render functions, run from the project root.
+
+Commands:
+  init                     scaffold starter ferrovue.config.json and components
+
+Options:
+      --check              check that generated files match committed files without writing
+  -d, --diff               show unified diff of changes when checking (use with --check)
+      --watch              watch components, stores, routes and config for changes and regenerate
+  -c, --config <path>      path to configuration file (default: ferrovue.config.json)
+  -v, --version            print the version and exit
+  -h, --help               print this help and exit
+`;
+/** A refused construct, or a broken configuration: the message alone, which names the file. */
+function report(e) {
+    if (e instanceof GenError || e instanceof SyntaxError)
+        console.error(`error: ${e.message}`);
+    else
+        throw e;
+}
+function initProject(targetRoot, configPath) {
+    const configFile = configPath ? resolve(targetRoot, configPath) : join(targetRoot, CONFIG_FILE);
+    if (existsSync(configFile)) {
+        console.error(`error: configuration file already exists: ${relative(targetRoot, configFile) || CONFIG_FILE}`);
+        return 1;
+    }
+    const defaultComponents = "components";
+    const defaultOut = "src/generated";
+    mkdirSync(dirname(configFile), { recursive: true });
+    const config = {
+        components: defaultComponents,
+        out: defaultOut,
+    };
+    writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
+    console.log(`created ${relative(targetRoot, configFile) || CONFIG_FILE}`);
+    const compDir = join(targetRoot, defaultComponents);
+    mkdirSync(compDir, { recursive: true });
+    const helloVue = join(compDir, "Hello.vue");
+    if (!existsSync(helloVue)) {
+        writeFileSync(helloVue, `<script setup lang="ts">
+defineProps<{ name: string }>();
+</script>
+
+<template>
+  <p>Hello, {{ name }}!</p>
+</template>
+`);
+        console.log(`created ${join(defaultComponents, "Hello.vue")}`);
+    }
+    const outDir = join(targetRoot, defaultOut);
+    mkdirSync(outDir, { recursive: true });
+    console.log("\nNext steps:\n  1. Run `ferrovue` to generate Rust render functions into src/generated\n  2. In your Rust crate, declare `mod generated;` to use them");
+    return 0;
+}
+function check(config, showDiff = false) {
     const want = generate(root, config);
     const dir = join(root, config.out);
     let have = [];
@@ -28,16 +91,122 @@ if (process.argv.includes("--check")) {
     });
     const extra = have.filter((name) => !want.has(name));
     if (stale.length || extra.length) {
-        for (const name of stale)
+        const committed = (name) => {
+            try {
+                return readFileSync(join(dir, name), "utf8");
+            }
+            catch {
+                return "";
+            }
+        };
+        for (const name of stale) {
             console.error(`stale: ${config.out}/${name}`);
-        for (const name of extra)
+            if (showDiff)
+                console.error(unifiedDiff(`${config.out}/${name}`, committed(name), want.get(name)));
+        }
+        for (const name of extra) {
             console.error(`not generated: ${config.out}/${name}`);
+            if (showDiff)
+                console.error(unifiedDiff(`${config.out}/${name}`, committed(name), ""));
+        }
         console.error("run `ferrovue` to regenerate");
-        process.exit(1);
+        return 1;
     }
     console.log(`${config.out} is up to date`);
+    return 0;
+}
+function once(config) {
+    const { files, changed, removed } = write(root, config);
+    const what = changed.length || removed.length ? `${changed.length} changed, ${removed.length} removed` : "nothing changed";
+    console.log(`${config.out}: ${files.length} files, ${what}`);
+}
+/** Regenerate on every change to what the components are compiled from, reporting errors and
+ * carrying on. The output directory itself, dependencies and build output are ignored. */
+function watchProject(configPath) {
+    const run = () => {
+        try {
+            once(loadConfig(root, configPath));
+        }
+        catch (e) {
+            report(e);
+        }
+    };
+    run();
+    const ignored = (file) => {
+        let out = "";
+        try {
+            out = loadConfig(root, configPath).out;
+        }
+        catch {
+            // A broken configuration ignores nothing; the next run reports it.
+        }
+        const parts = file.split(sep);
+        return (parts.some((p) => p === "node_modules" || p === "target" || p === ".git" || p === "dist") ||
+            (out !== "" && (file === out || file.startsWith(out + sep))) ||
+            !/\.(vue|ts|json)$/.test(file));
+    };
+    let timer = null;
+    watch(root, { recursive: true }, (_event, name) => {
+        if (!name || ignored(relative(root, join(root, name))))
+            return;
+        // Editors write a file in several steps: one run once they are done.
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(run, 50);
+    });
+    console.log("watching for changes (Ctrl-C to stop)");
+}
+try {
+    const rawArgs = process.argv.slice(2);
+    let configPath;
+    const args = [];
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        if (arg === "-c" || arg === "--config") {
+            if (i + 1 >= rawArgs.length || rawArgs[i + 1].startsWith("-")) {
+                console.error(`error: option '${arg}' requires an argument`);
+                process.exit(1);
+            }
+            configPath = rawArgs[++i];
+        }
+        else if (arg.startsWith("--config=")) {
+            configPath = arg.slice("--config=".length);
+        }
+        else {
+            args.push(arg);
+        }
+    }
+    const known = new Set(["init", "--check", "--diff", "-d", "--watch", "-v", "--version", "-h", "--help"]);
+    const unknown = args.find((a) => !known.has(a));
+    if (unknown !== undefined) {
+        console.error(`error: unknown option or command '${unknown}'\n\nRun \`ferrovue --help\` for usage.`);
+        process.exit(1);
+    }
+    if ((args.includes("--diff") || args.includes("-d")) && !args.includes("--check")) {
+        console.error("error: '--diff' requires '--check'");
+        process.exit(1);
+    }
+    if (args.includes("--version") || args.includes("-v")) {
+        console.log(VERSION);
+    }
+    else if (args.includes("--help") || args.includes("-h")) {
+        console.log(HELP.trimEnd());
+    }
+    else if (args.includes("init")) {
+        process.exitCode = initProject(root, configPath);
+    }
+    else if (args.includes("--watch")) {
+        watchProject(configPath);
+    }
+    else if (args.includes("--check")) {
+        const showDiff = args.includes("--diff") || args.includes("-d");
+        process.exitCode = check(loadConfig(root, configPath), showDiff);
+    }
+    else {
+        once(loadConfig(root, configPath));
+    }
 }
-else {
-    const files = write(root, config);
-    console.log(`wrote ${files.length} files to ${config.out}`);
+catch (e) {
+    report(e);
+    process.exitCode = 1;
 }

package/dist/client.d.ts

@@ -1,4 +1,40 @@
+import { type App, type Component, type Plugin } from "vue";
 import type { Pinia } from "pinia";
+import type { Router } from "vue-router";
 /** Give Pinia the state the server rendered with — what `ferrovue::state_script_into` wrote — before
  * the app mounts, so every store starts from it and the hydrated markup agrees with the server's. */
 export declare function hydrateState(pinia: Pinia, id?: string, doc?: Document): void;
+export interface MountOptions {
+    /** One Pinia for every island, so they share stores. Call `hydrateState` on it first. */
+    pinia?: Pinia;
+    /** One router for every island that renders a `<RouterLink>` or reads the route. Mounting waits
+     * until it has resolved the current location, which the server rendered against. */
+    router?: Router;
+    /** Anything else each island's app should `use`: i18n, a component library. */
+    plugins?: Plugin[];
+    /** Where to look for islands: the whole document by default. */
+    root?: ParentNode;
+    /** Told about an island left as the server rendered it, because its component is not among
+     * those given or its props are malformed. Warns on the console by default. */
+    onError?: (element: Element, problem: string) => void;
+}
+/** A component, or a function that loads one — `() => import("./Counter.vue")` — so that the code
+ * of an island not on the page is never fetched. A function is taken for a loader as vue-router
+ * takes one for a lazy route: unless it has `props` or `displayName`, which mark a functional
+ * component, or `__vccOpts`, a class component. `ferrovue/islands` maps the name of every island
+ * to a loader. */
+export type IslandComponent = Component | (() => Promise<Component | {
+    default: Component;
+}>);
+/** The islands mounted. */
+export interface Islands {
+    /** One app per island, in document order. */
+    apps: App[];
+    /** Unmount every island, as a page leaving would. */
+    unmount(): void;
+}
+/** Hydrate every island on the page: each `<div data-island="Name" data-props="…">` that
+ * `Html::island` wrote becomes an app of the component of that name, given the props the server
+ * rendered it with, mounted where it is. A loader is called only for an island the page holds, all
+ * of them at once, and the islands mount in document order once every one has loaded. */
+export declare function mountIslands(components: Record<string, IslandComponent>, options?: MountOptions): Promise<Islands>;

package/dist/client.js

@@ -1,7 +1,99 @@
+/* What the browser does with a page ferrovue rendered. */
+import { createSSRApp } from "vue";
+/** A JSON string, skipped whole as it may hold the same letters, or a bare number JSON has no word
+ * for, which the server writes as JavaScript does where `serde_json` alone would write `null`. */
+const BARE = /"(?:[^"\\]|\\.)*"|-?Infinity|NaN/g;
+const NON_FINITE = { NaN: Number.NaN, Infinity: Number.POSITIVE_INFINITY, "-Infinity": Number.NEGATIVE_INFINITY };
+/** `JSON.parse`, reading back the bare `NaN`, `Infinity` and `-Infinity` that an island's props and
+ * the state script hold for a number that is not finite, so the client renders what the server did.
+ * Throws as `JSON.parse` does on anything else that is not JSON. */
+function parseJson(text) {
+    // Plain JSON: almost everything the server writes, and all it wrote before it wrote these.
+    if (!/NaN|Infinity/.test(text))
+        return JSON.parse(text);
+    // Each token becomes a string that starts with more NULs in a row than any string in the text
+    // holds (JSON has one way to write a NUL, `\u0000`), so no other value can be mistaken for one.
+    let escaped = "\\u0000";
+    while (text.includes(escaped))
+        escaped += "\\u0000";
+    const tag = JSON.parse(`"${escaped}"`);
+    const quoted = text.replace(BARE, (match) => (match.startsWith('"') ? match : `"${escaped}${match}"`));
+    return JSON.parse(quoted, (_key, value) => (typeof value === "string" && value.startsWith(tag) ? NON_FINITE[value.slice(tag.length)] : value));
+}
 /** Give Pinia the state the server rendered with — what `ferrovue::state_script_into` wrote — before
  * the app mounts, so every store starts from it and the hydrated markup agrees with the server's. */
 export function hydrateState(pinia, id = "__pinia", doc = document) {
     const text = doc.getElementById(id)?.textContent;
     if (text)
-        pinia.state.value = JSON.parse(text);
+        pinia.state.value = parseJson(text);
+}
+/** Hydrate every island on the page: each `<div data-island="Name" data-props="…">` that
+ * `Html::island` wrote becomes an app of the component of that name, given the props the server
+ * rendered it with, mounted where it is. A loader is called only for an island the page holds, all
+ * of them at once, and the islands mount in document order once every one has loaded. */
+export async function mountIslands(components, options = {}) {
+    const root = options.root ?? document;
+    const report = options.onError ?? ((el, problem) => console.warn(`[ferrovue] island left unhydrated: ${problem}`, el));
+    const elements = Array.from(root.querySelectorAll("[data-island]"));
+    // Each component the page names, loaded once however many islands it has.
+    const loading = new Map();
+    for (const el of elements) {
+        const name = el.dataset.island ?? "";
+        if (Object.hasOwn(components, name) && !loading.has(name))
+            loading.set(name, load(components[name]));
+    }
+    const [loaded] = await Promise.all([
+        Promise.all([...loading].map(async ([name, pending]) => [name, await pending])).then((pairs) => new Map(pairs)),
+        options.router?.isReady(),
+    ]);
+    const apps = [];
+    for (const el of elements) {
+        const name = el.dataset.island ?? "";
+        const component = loaded.get(name);
+        if (!component) {
+            report(el, `no component called ${JSON.stringify(name)} was given (\`ferrovue/islands\` holds every component that has an \`island()\`)`);
+            continue;
+        }
+        if (component instanceof Error) {
+            report(el, `${name} did not load: ${component.message}`);
+            continue;
+        }
+        let props;
+        try {
+            props = parseJson(el.dataset.props ?? "{}");
+        }
+        catch {
+            report(el, `the props of ${name} are not JSON`);
+            continue;
+        }
+        const app = createSSRApp(component, props);
+        if (options.pinia)
+            app.use(options.pinia);
+        if (options.router)
+            app.use(options.router);
+        for (const plugin of options.plugins ?? [])
+            app.use(plugin);
+        app.mount(el);
+        apps.push(app);
+    }
+    return {
+        apps,
+        unmount() {
+            for (const app of apps.splice(0))
+                app.unmount();
+        },
+    };
+}
+/** The component itself, or what its loader resolves to: a module's default export, or the
+ * component. A loader that rejects gives its error, which leaves only its own islands unhydrated. */
+async function load(component) {
+    if (typeof component !== "function" || "props" in component || "displayName" in component || "__vccOpts" in component)
+        return component;
+    try {
+        const loaded = await component();
+        return typeof loaded === "object" && "default" in loaded ? loaded.default : loaded;
+    }
+    catch (e) {
+        return e instanceof Error ? e : new Error(String(e));
+    }
 }

package/dist/compiler.d.ts

@@ -1,56 +1,23 @@
-/** A type a helper takes or returns, as the configuration spells it. */
-export type TypeName = "string" | "string?" | "int" | "int?" | "bool";
-/** A function a template may call, and the Rust function that is its twin. */
-export interface HelperSpec {
-    /** The Rust path the generated code calls, e.g. `crate::helpers::format_count`. */
-    rust: string;
-    params: TypeName[];
-    returns: TypeName;
-    /** The longest string it returns, which is what a call adds to the buffer reservation. */
-    maxLen?: number;
-}
-/** What `ferrovue.config.json` holds. Paths are relative to the project root. */
-export interface Config {
-    /** The directory of `.vue` files to compile. */
-    components: string;
-    /** The directory the Rust modules are written to. Everything in it is replaced. */
-    out: string;
-    /** The module components import their helpers from, and the Rust twin of each export. */
-    helpers?: {
-        module: string;
-        functions: Record<string, HelperSpec>;
-    };
-    /** The Rust type a `TrustedHtml` prop is, which must implement `ferrovue::TrustedHtml`, e.g.
-     * `crate::sanitize::SafeHtml`. A type that borrows names the props' lifetime, `'a`:
-     * `crate::render::Trusted<'a>`. Without it, a component cannot use `v-html` at all. */
-    trustedHtml?: string;
-    /** A JSON file listing the app's routes as vue-router paths (`/users/:id`), which `<RouterLink>`
-     * resolves against. Without it, a component cannot use `<RouterLink>`. */
-    routes?: string;
-    /** The router, in full: its routes file, the history's base, and the class names
-     * `createRouter` gives active links. `routes` alone is shorthand for `{ routes }`. */
-    router?: {
-        routes: string;
-        base?: string;
-        linkActiveClass?: string;
-        linkExactActiveClass?: string;
-    };
-    /** The directory of Pinia stores (`.ts` files), whose state a component may read while it renders
-     * on the server. */
-    stores?: string;
-    /** Custom directives that render nothing on the server — no `getSSRProps` — by name, without
-     * `v-`: `["focus", "click-outside"]`. Any other custom directive is refused, since the server
-     * cannot know what its `getSSRProps` would add. */
-    clientDirectives?: string[];
-}
-export declare const CONFIG_FILE = "ferrovue.config.json";
-/** Read the project's configuration. */
-export declare function loadConfig(root: string): Config;
-/** Where `TrustedHtml` comes from. Only that import names the type `v-html` will write raw. */
-export declare const TYPES_MODULE = "ferrovue/types";
-export declare class GenError extends Error {
-}
+import { type Config } from "./context.ts";
 /** Every generated file, keyed by its name in the output directory. */
 export declare function generate(root: string, config?: Config): Map<string, string>;
 /** Write what `generate` produces to the configured directory, replacing what is there. */
-export declare function write(root: string, config?: Config): string[];
+/** What \`write\` changed in the output directory. */
+export interface Written {
+    /** Every file the output directory now holds. */
+    files: string[];
+    /** The files whose text changed, or that are new. */
+    changed: string[];
+    /** The files removed, which the components no longer produce. */
+    removed: string[];
+    /** Every component that has an `island()`, by the name `data-island` carries, with its `.vue`
+     * file relative to the root: what `ferrovue/islands` loads. */
+    islands: Record<string, string>;
+}
+/** Write what \`generate\` produces to the configured directory: only the files whose text changed,
+ * so a Rust build that watches them rebuilds no more than it must, and removing what no component
+ * produces any more. */
+export declare function write(root: string, config?: Config): Written;
+export { CONFIG_FILE, loadConfig, TYPES_MODULE, type Config, type HelperSpec, type TypeName } from "./context.ts";
+export { GenError } from "./model.ts";
+export declare const VERSION: string;