@uniflowed/vite 0.0.0-alpha.1 → 0.0.0-alpha.4

package/internal/refresh.js

@@ -1,3 +1,5 @@
+// @noflow
+//
 // Plain JavaScript: executed by the host that runs Vite, before any transform.
 //
 // React Fast Refresh wiring for `uf dev`. The runtime itself is

package/internal/routes.js

@@ -1,3 +1,5 @@
+// @noflow
+//
 // Plain JavaScript: executed by the host that runs Vite, before any transform.
 //
 // The file-system router, as the build sees it.
@@ -21,6 +23,7 @@ export const RESERVED = Object.freeze({
   page: "_uf.page",
   middleware: "_uf.middleware",
   notFound: "_uf.not-found",
+  route: "_uf.route",
 });
 
 /** Extensions a page or layout may use; `.mdx` is a page written as content. */
@@ -43,6 +46,16 @@ const MAX_DEPTH = 32;
  * @property {boolean} mdx whether the page is MDX content
  */
 
+/**
+ * One route handler — a path that answers a request instead of rendering.
+ *
+ * @typedef {object} Handler
+ * @property {string} path route path such as `/api/users/:id`
+ * @property {string} pattern the same path with `*` for catch-alls
+ * @property {ReadonlyArray<{name: string, catchAll: boolean}>} params
+ * @property {string} module absolute path of the handler module
+ */
+
 /**
  * Scan `appRoot` for routes.
  *
@@ -55,8 +68,9 @@ const MAX_DEPTH = 32;
  */
 export function scanRoutes(appRoot) {
   const routes = [];
+  const handlers = [];
   let notFound = null;
-  if (!isDirectory(appRoot)) return { routes, notFound };
+  if (!isDirectory(appRoot)) return { routes, handlers, notFound };
 
   const walk = (directory, segments, layouts, middleware, depth) => {
     if (depth > MAX_DEPTH) return;
@@ -82,6 +96,15 @@ export function scanRoutes(appRoot) {
         mdx: page.endsWith(".mdx"),
       });
     }
+    // A handler answers the request itself, so it takes no layouts and is not
+    // MDX. It may sit beside a page: `/feed` can render for a browser and
+    // `/feed.xml` answer for a reader, and both are the same directory tree.
+    const handler = findModule(directory, RESERVED.route, MODULE_EXTENSIONS);
+    if (handler) {
+      const { path: routePath, pattern, params } = routeFromSegments(segments);
+      handlers.push({ path: routePath, pattern, params, module: handler });
+    }
+
     if (depth === 0) {
       const own = findModule(directory, RESERVED.notFound, PAGE_EXTENSIONS);
       if (own) notFound = { page: own, layouts: nextLayouts, mdx: own.endsWith(".mdx") };
@@ -103,8 +126,10 @@ export function scanRoutes(appRoot) {
   };
 
   walk(appRoot, [], [], [], 0);
-  routes.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-  return { routes, notFound };
+  const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  routes.sort(byPath);
+  handlers.sort(byPath);
+  return { routes, handlers, notFound };
 }
 
 function isDirectory(candidate) {
@@ -206,10 +231,25 @@ export function routesModuleSource(table) {
 }`
     : "null";
 
+  // Handlers are a separate table because nothing on the client wants them:
+  // a route handler answers a request, so shipping its module to the browser
+  // would ship server code to the page.
+  const handlerEntries = (table.handlers ?? []).map(
+    (handler) => `  {
+    path: ${JSON.stringify(handler.path)},
+    params: ${JSON.stringify(handler.params)},
+    file: ${JSON.stringify(handler.module)},
+    load: () => import(${JSON.stringify(handler.module)}),
+  }`,
+  );
+
   return `${layoutImports.join("\n")}
 export const routes = [
 ${entries.join(",\n")}
 ];
+export const handlers = [
+${handlerEntries.join(",\n")}
+];
 export const notFound = ${notFound};
 export default routes;
 `;
@@ -234,10 +274,11 @@ hydrate({ App, routes, notFound });
  * The source of `virtual:uf/server`: render one URL to HTML.
  */
 export function serverModuleSource(appEntry) {
-  return `import { createRenderer } from "@uniflowed/router/server";
-import { routes, notFound } from ${JSON.stringify(VIRTUAL.routes)};
+  return `import { createDispatcher, createRenderer } from "@uniflowed/router/server";
+import { routes, handlers, notFound } from ${JSON.stringify(VIRTUAL.routes)};
 import App from ${JSON.stringify(appEntry)};
-export { routes, notFound };
+export { routes, handlers, notFound };
 export const render = createRenderer({ App, routes, notFound });
+export const dispatch = createDispatcher({ handlers });
 `;
 }

package/merge.js

@@ -0,0 +1,87 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// Merging a project's own Vite configuration over the one uf generates.
+//
+// This exists because of a specific failure. uf's config re-declared Vite's
+// options one at a time — `host`, `port`, `strictPort`, `outDir`, `sourcemap`
+// — and the driver copied them across by hand. Anything Vite could do that uf
+// had not enumerated was unreachable until uf shipped a release naming it.
+// That is `react-scripts`: an integrated tool becoming the chokepoint every
+// upgrade in the ecosystem has to pass through.
+//
+// So `vite` in `uf.config.js` is Vite's own configuration, merged over uf's,
+// and uf makes no attempt to understand it. An option added to Vite tomorrow
+// works in a uf project tomorrow.
+//
+// # What uf still decides
+//
+// Three things are uf's rather than the project's, and the merge protects
+// them:
+//
+//   * `plugins`, which are concatenated rather than replaced — dropping uf's
+//     Flow transform would leave a project whose source no longer compiles,
+//     which is not a thing anyone means to configure.
+//   * `configFile`, because a `vite.config.ts` beside `uf.config.js` is two
+//     files disagreeing about one project.
+//   * `root`, which is the project uf resolved.
+//
+// Everything else is the project's to set, including options uf sets itself:
+// a default is a convenience, not an architecture.
+
+/** Keys uf owns outright, whatever the project's Vite config says. */
+const RESERVED = ["root", "configFile"];
+
+/**
+ * Deep-merge `overrides` onto `base`.
+ *
+ * Plain objects merge key by key; arrays and everything else replace, which is
+ * what a caller setting `build.rollupOptions.input` means. `plugins` is the
+ * exception and is handled by the caller, because concatenating is right there
+ * and replacing is right everywhere else.
+ */
+export function mergeConfig(base, overrides) {
+  if (overrides == null) return base;
+  const merged = { ...base };
+  for (const key of Object.keys(overrides)) {
+    const value = overrides[key];
+    if (value === undefined) continue;
+    merged[key] =
+      isPlainObject(value) && isPlainObject(base[key]) ? mergeConfig(base[key], value) : value;
+  }
+  return merged;
+}
+
+/**
+ * uf's generated config, with the project's Vite config merged over it.
+ *
+ * @param {object} generated what uf built from the semantics it owns
+ * @param {object | undefined} overrides `vite` from `uf.config.js`
+ */
+export function withProjectConfig(generated, overrides) {
+  if (overrides == null) return generated;
+
+  const owned = {};
+  for (const key of RESERVED) owned[key] = generated[key];
+
+  const merged = mergeConfig(generated, { ...overrides, ...owned });
+
+  // uf's plugins first, then the project's. First because the Flow transform
+  // has to see a module before anything that expects JavaScript does.
+  merged.plugins = [
+    ...(generated.plugins ?? []),
+    ...(Array.isArray(overrides.plugins) ? overrides.plugins : []),
+  ];
+  return merged;
+}
+
+function isPlainObject(value) {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    // A plugin, a logger or a URL is a value to replace, not a shape to merge.
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/vite",
-  "version": "0.0.0-alpha.1",
+  "version": "0.0.0-alpha.4",
   "description": "Vite, driven by uf.config.js: every Flow module through `uf transform`, MDX, the file-system router and static rendering as Vite plugins.",
   "type": "module",
   "license": "MIT",
@@ -13,25 +13,24 @@
   "exports": {
     ".": "./index.js",
     "./driver": "./driver.js",
-    "./register": "./register.js",
-    "./bun-preload": "./bun-preload.js",
-    "./transform": "./transform.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./merge": "./merge.js"
   },
   "files": [
-    "index.js",
     "driver.js",
-    "register.js",
-    "bun-preload.js",
-    "transform.js",
-    "internal"
+    "index.js",
+    "internal",
+    "merge.js"
   ],
   "dependencies": {
     "@mdx-js/rollup": "^3.1.1",
+    "@shikijs/rehype": "^3.23.0",
+    "@uniflowed/host": "0.0.0-alpha.4",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
     "remark-mdx-frontmatter": "^5.2.0",
+    "shiki": "^3.23.0",
     "vite": "^8.2.2"
   },
   "peerDependencies": {

package/bun-preload.js

@@ -1,22 +0,0 @@
-// Plain JavaScript: this file registers the loader, so it cannot need one.
-//
-// `bun --preload @uniflowed/vite/bun-preload app.js` runs a Flow project on
-// Bun without a build step, through Bun's own plugin API: every module uf is
-// responsible for is transformed by `uf transform` as Bun loads it. It is the
-// Bun counterpart of `./register.js`, and the policy of which files count is
-// the same `isFlowModule`.
-
-import { isFlowModule, transformFlow } from "./transform.js";
-
-Bun.plugin({
-  name: "uniflowed-flow",
-  setup(build) {
-    build.onLoad({ filter: /\.(js|jsx|mjs)$/ }, async (args) => {
-      if (!isFlowModule(args.path)) return undefined;
-      const source = await Bun.file(args.path).text();
-      const out = await transformFlow(source, args.path, { development: true, sourceMap: false });
-      if (out == null) return undefined;
-      return { contents: out.code, loader: "js" };
-    });
-  },
-});

package/internal/node-hooks.js

@@ -1,111 +0,0 @@
-// Plain JavaScript: this *is* the loader, so it cannot be Flow.
-//
-// Node.js module customization hooks that transform Flow on import.
-//
-// Registered by `@uniflowed/vite/register` (through `node:module`'s
-// `register()`), which makes `node --import @uniflowed/vite/register app.js`
-// run a Flow project directly: every `.js` module uf is responsible for is
-// transformed as it is loaded through `uf transform`, and everything else is
-// left to Node.
-//
-// Transforms are cached on disk under `.uf/cache/transform/` keyed by a hash
-// of the source, so a second run of the same file is a read rather than a
-// round trip. The cache is content-addressed: an edited file hashes
-// differently, so there is no invalidation to get wrong.
-
-import { createHash } from "node:crypto";
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { isFlowModule, transformFlow } from "../transform.js";
-
-/**
- * Write `contents` to `target` so a concurrent reader never sees half of it.
- *
- * `uf test` runs one of these processes per core and they all import the same
- * few modules at once, so two writers and a reader meet on the same cache
- * entry constantly. `writeFileSync` is not atomic — a reader can observe a
- * truncated file and report a module that "does not provide an export" — so
- * the content goes to a private temporary name first and is then renamed,
- * which is atomic within a filesystem.
- *
- * A failure here is not a failure: a read-only checkout still runs, just
- * without the cache.
- */
-function writeAtomically(target, contents) {
-  const temporary = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}`;
-  try {
-    mkdirSync(cacheDirectory, { recursive: true });
-    writeFileSync(temporary, contents);
-    renameSync(temporary, target);
-  } catch {
-    try {
-      unlinkSync(temporary);
-    } catch {
-      // Nothing to clean up.
-    }
-  }
-}
-
-/** Bumped whenever the transform's output shape changes, to retire old entries. */
-const CACHE_VERSION = "2";
-
-let cacheDirectory = null;
-let root = null;
-
-/**
- * Called once by `register()` with `{ root }`; the cache lives under it and
- * the transform service is started there so it reads the right config.
- */
-export async function initialize(data) {
-  root = data?.root ?? process.cwd();
-  cacheDirectory = path.join(root, ".uf", "cache", "transform");
-}
-
-/**
- * The `load` hook: transform Flow modules, defer everything else.
- */
-export async function load(url, context, nextLoad) {
-  if (!url.startsWith("file:")) return nextLoad(url, context);
-  const filename = fileURLToPath(url);
-  if (!isFlowModule(filename)) return nextLoad(url, context);
-
-  const source = readFileSync(filename, "utf8");
-  const code = await cachedTransform(source, filename);
-  if (code == null) return nextLoad(url, context);
-  // uf projects are ES modules. Forcing the format here means a project whose
-  // package.json forgot `"type": "module"` still runs, rather than failing on
-  // an `import` in what Node would have guessed was CommonJS.
-  return { format: "module", source: code, shortCircuit: true };
-}
-
-async function cachedTransform(source, filename) {
-  const key = createHash("sha256")
-    .update(CACHE_VERSION)
-    .update("\0")
-    .update(filename)
-    .update("\0")
-    .update(source)
-    .digest("hex");
-  const entry = cacheDirectory ? path.join(cacheDirectory, `${key}.mjs`) : null;
-
-  if (entry) {
-    try {
-      return readFileSync(entry, "utf8");
-    } catch {
-      // not cached yet
-    }
-  }
-
-  const out = await transformFlow(source, filename, { root, development: true, sourceMap: true });
-  if (out == null) return null;
-  const output = out.map
-    ? `${out.code}\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(out.map).toString("base64")}\n`
-    : out.code;
-
-  if (entry) {
-    writeAtomically(entry, output);
-  }
-  return output;
-}

package/register.js

@@ -1,11 +0,0 @@
-// Plain JavaScript: this file registers the loader, so it cannot need one.
-//
-// `node --import @uniflowed/vite/register app.js` runs a Flow project on
-// Node.js without a build step. Importing this module installs the hooks in
-// `./internal/node-hooks.js` for the rest of the process.
-
-import { register } from "node:module";
-
-register("./internal/node-hooks.js", import.meta.url, {
-  data: { root: process.env.UF_PROJECT_ROOT ?? process.cwd() },
-});

package/transform.js

@@ -1,187 +0,0 @@
-// Plain JavaScript: executed by the host that runs Vite, before any transform
-// exists — this module is how the transform is reached, so it cannot be Flow.
-//
-// The Flow → JavaScript transform lives in `uf` itself (`crates/uf_transform`:
-// the official Flow parser, Flow's own lowering rules, the official React
-// Compiler, oxc for JSX and code generation). This module is the JavaScript
-// side of the `uf transform` service: one long-lived `uf` process per host
-// process, newline-delimited JSON in, replies in request order out.
-//
-// Every host that runs Flow — the Vite plugin, the Node loader hook, the Bun
-// preload, the config loader — goes through here, which is what makes them
-// all produce the same module from the same source.
-
-import { spawn } from "node:child_process";
-import { createInterface } from "node:readline";
-
-/** File extensions uf treats as Flow source. */
-export const FLOW_EXTENSIONS = [".js", ".jsx", ".mjs", ".cjs"];
-
-/**
- * Whether uf is responsible for transforming this module.
- *
- * Mirrors `uf_transform::is_flow_module`, and must keep mirroring it: a `uf
- * dev` session and a `uf test` run that disagree about which files are Flow
- * disagree about what the code is.
- *
- * A build driver synthesises modules of its own (`\0vite/client`, Rolldown's
- * shims), and a third-party dependency ships JavaScript that is already
- * JavaScript; neither is Flow. `@uniflowed/*` under `node_modules` is the
- * deliberate exception: those packages ship Flow source, because that is what
- * uf tells everyone to write.
- */
-export function isFlowModule(id) {
-  if (id.startsWith("\0")) return false;
-  const clean = stripQuery(id);
-  if (!FLOW_EXTENSIONS.some((extension) => clean.endsWith(extension))) return false;
-  const at = clean.lastIndexOf("/node_modules/");
-  return at === -1 || clean.slice(at).startsWith("/node_modules/@uniflowed/");
-}
-
-function stripQuery(id) {
-  const at = id.indexOf("?");
-  return at === -1 ? id : id.slice(0, at);
-}
-
-/**
- * The `uf` binary to talk to.
- *
- * `uf dev`, `uf build` and `uf test` set `UF_BINARY` to themselves when they
- * start a host, so the host reaches exactly the binary that started it. A host
- * started by hand finds `uf` on PATH, which is what the installer arranges.
- */
-export function ufBinary() {
-  return process.env.UF_BINARY ?? "uf";
-}
-
-/**
- * An error the transform reported for one module, with its position when
- * the parser or the lowering rules gave one.
- */
-export class TransformError extends Error {
-  constructor(id, message, line, column) {
-    super(message);
-    this.name = "TransformError";
-    this.id = id;
-    this.loc = line != null ? { file: id, line, column: column ?? 0 } : undefined;
-  }
-}
-
-/**
- * One `uf transform` process, with requests answered in the order they were
- * sent.
- *
- * `uf transform` replies once per request, in order, so a plain queue of
- * resolvers pairs a reply with its caller — no correlation ids and no map to
- * leak. Any exit is final: a request made after the process has gone is
- * rejected at once rather than queued against something that will never
- * answer.
- */
-export class TransformService {
-  #child;
-  #pending = [];
-  #failure = null;
-
-  /**
-   * @param {object} [options]
-   * @param {string} [options.command] the `uf` binary; `ufBinary()` by default
-   * @param {string} [options.root] project root, so `uf.config.js` is found
-   */
-  constructor(options = {}) {
-    const command = options.command ?? ufBinary();
-    const root = options.root ?? process.cwd();
-    this.#child = spawn(command, ["--cwd", root, "transform"], {
-      stdio: ["pipe", "pipe", "inherit"],
-    });
-
-    createInterface({ input: this.#child.stdout }).on("line", (line) => {
-      const waiting = this.#pending.shift();
-      if (!waiting) return;
-      let reply;
-      try {
-        reply = JSON.parse(line);
-      } catch {
-        waiting.reject(new Error(`uf transform sent a malformed reply: ${line}`));
-        return;
-      }
-      if (reply.error != null) {
-        waiting.reject(new TransformError(waiting.id, reply.error, reply.line, reply.column));
-        return;
-      }
-      waiting.resolve(reply);
-    });
-
-    this.#child.on("error", (error) => {
-      this.#settleAll(new Error(`could not run \`${command} transform\`: ${error.message}`));
-    });
-    this.#child.on("close", (code) => {
-      this.#settleAll(new Error(`uf transform exited (${code})`));
-    });
-  }
-
-  #settleAll(error) {
-    this.#failure = error;
-    while (this.#pending.length > 0) this.#pending.shift().reject(error);
-  }
-
-  /**
-   * Transform one module.
-   *
-   * Resolves to `{ code, map, diagnostics }`, or to `null` when the module is
-   * not uf's to transform (see `isFlowModule`). Rejects with a
-   * `TransformError` carrying the position when the source is not valid Flow.
-   *
-   * @param {string} id absolute path, used for the map and for errors
-   * @param {string} code the Flow source
-   * @param {object} [options]
-   * @param {boolean} [options.development] readable output, `jsxDEV`
-   * @param {boolean} [options.refresh] Fast Refresh registrations (development only)
-   * @param {boolean} [options.sourceMap] produce a source map; on by default
-   */
-  transform(id, code, options = {}) {
-    if (this.#failure) return Promise.reject(this.#failure);
-    return new Promise((resolve, reject) => {
-      this.#pending.push({
-        id,
-        reject,
-        resolve: (reply) => {
-          if (reply.code == null) {
-            resolve(null);
-            return;
-          }
-          resolve({ code: reply.code, map: reply.map ?? null, diagnostics: reply.diagnostics ?? [] });
-        },
-      });
-      this.#child.stdin.write(`${JSON.stringify({ id, code, options })}\n`);
-    });
-  }
-
-  /** Stop the process. Outstanding requests are rejected. */
-  close() {
-    this.#child.stdin.end();
-    this.#child.kill();
-  }
-}
-
-let shared = null;
-
-/**
- * The process-wide service, started on first use.
- *
- * The loader hooks and the config loader share one process per host rather
- * than one per module; it lives as long as the host does.
- */
-export function sharedService(root) {
-  shared ??= new TransformService({ root: root ?? process.env.UF_PROJECT_ROOT ?? process.cwd() });
-  return shared;
-}
-
-/**
- * Transform one Flow module through the shared service.
- *
- * Returns `{ code, map, diagnostics }`; a module that is not uf's to transform
- * comes back as `null`.
- */
-export function transformFlow(code, filename, options = {}) {
-  return sharedService(options.root).transform(filename, code, options);
-}