filesystem-routing 0.1.0 → 0.2.0

package/README.md

@@ -13,8 +13,8 @@ a delivery adapter that materializes the manifest into code.
 | Scanning, filename convention, neutral route manifest | `filesystem-routing` |
 | Nesting + `(group)` stripping | `filesystem-routing/tree` |
 | Vite delivery (virtual module, HMR, code splitting, build inputs) | `filesystem-routing/vite` |
-| `RouteDefinition` emission | `@solidjs/router/fs` |
-| Request handling for `GET`/`POST` routes, middleware | `@solidjs/start` |
+| Request dispatch for `GET`/`POST` routes, as fetch middleware | `filesystem-routing/api` |
+| `RouteDefinition` emission for Solid Router (code splitting, typed paths) | `@solidjs/router/fs` |
 
 Nothing here is Solid-specific: the core is bundler-agnostic — it never imports
 Vite — the Vite adapter is router-agnostic, and the conventions are the ones
@@ -47,9 +47,11 @@ const Router = createRouter({ routes: fileRoutes(pageRoutes) });
 export const App = () => <Router>{props => <>{props.children}</>}</Router>;
 ```
 
-The emission adapter never imports the virtual module itself — the app does,
-so the adapter resolves without the plugin, custom `moduleId`s work, and
-nothing needs excluding from dependency prebundling.
+The emission adapter ships with the router — `@solidjs/router/fs` for Solid
+Router; other routers mirror the same shape in their own packages. It never
+imports a virtual module itself — the app does, so the adapter resolves
+without the plugin, custom `moduleId`s work, and nothing needs excluding
+from dependency prebundling.
 
 Route modules live in `src/routes` (configurable via `fileRoutes({ dir })`).
 A module is a page when it has a default export, and may export a `route`
@@ -161,25 +163,29 @@ pages get:
 - The recognized set is `HEAD`/`GET`/`POST`/`PUT`/`DELETE`/`PATCH`/`OPTIONS`;
   pass an array instead of `true` to change it.
 
-This package stops at the manifest: it discovers handlers, it does not serve
-them. Dispatch is a few lines in whatever server consumes the manifest —
-match the URL, import the ref, call the export:
+Dispatch ships as fetch-style middleware — `filesystem-routing/api` matches
+requests against the manifest's handler refs and composes into any
+`(request, next)` chain, an SSR handler's middleware option included:
 
 ```ts
-// any SSR handler or middleware
+// src/middleware.ts
 import routes from "virtual:file-routes";
+import { createAPIHandler } from "filesystem-routing/api";
 
-async function handleApi(request: Request, entry, params) {
-  const ref = entry[`$${request.method}`];
-  if (!ref) return new Response(null, { status: 405 });
-  const handlers = await ref.import();
-  // a HEAD alias imports the GET handler
-  return (handlers[request.method] ?? handlers.GET)({ request, params });
-}
+export default [createAPIHandler(routes)];
 ```
 
-The handler's argument is whatever your server passes — the convention only
-dictates the export names. Frameworks typically enable `httpMethods` on the
+Handlers receive the request event of the surrounding scope (the storage
+`provideRequestEvent` establishes — pass `getEvent` to dispatch outside
+one), with the matched `params` written onto it. Unmatched requests (no
+route, or no handler for the method) advance the chain; `HEAD` falls back
+to the `GET` handler; returned strings and JSON values are coerced into
+responses. A `GET` handler may decline by returning `undefined`: a module
+that is also a page falls through to the chain (its component renders
+instead), a handler-only module answers 404. `createAPIMatcher` exposes the
+matching alone for servers with their own dispatch shape.
+
+Frameworks typically enable `httpMethods` on the
 server environment's router only (SolidStart pairs it with `components:
 false` in SPA mode, so the server manifest routes requests without shipping
 page modules) — see the per-environment `routers` option below.
@@ -247,10 +253,10 @@ with `(group)` segments stripped, so emission adapters don't each reimplement
 the tree (`buildRouteTree` from `filesystem-routing/tree` is the same
 function, for consumers holding only a flat manifest). An emission adapter is
 a function taking manifest entries and returning the router's shape — see
-`fileRoutes` in `@solidjs/router/fs` for Solid Router's, a ~30 line adapter
-other routers can mirror. Adapters take the manifest as an argument rather
-than importing the virtual module, so they work standalone and with custom
-module ids.
+`fileRoutes` in `@solidjs/router/fs` for Solid Router's, an
+adapter other routers can mirror. Adapters take the manifest as an argument
+rather than importing the virtual module, so they work standalone and with
+custom module ids.
 
 Add `/// <reference types="filesystem-routing/types" />` to type the import.
 

package/dist/api.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The API dispatch adapter: matches requests against the flat manifest's
+ * handler refs (`$GET`, `$POST`, …) and serves them as fetch-style
+ * middleware, so API routes compose into any `(request, next)` chain — an
+ * SSR handler's middleware option, a framework's request pipeline — with no
+ * bundler or server involvement.
+ *
+ * Ported from SolidStart's `server/routes.ts` (the radix3 matcher) and the
+ * method dispatch in its `server/handler.ts`.
+ */
+/**
+ * The event a handler receives. Structurally the core request event —
+ * `getRequestEvent()` inside the handler sees the same object — with the
+ * matched route params written onto it before dispatch.
+ */
+export interface APIEvent {
+    request: Request;
+    params?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * An API handler: an uppercase method export of a route module. Return a
+ * `Response` to answer the request; strings and JSON values are coerced
+ * (`new Response(text)` / `Response.json(value)`). A `GET` handler may
+ * return `undefined` to decline, falling through to the rest of the chain
+ * when the module is also a page.
+ */
+export type APIHandler = (event: APIEvent) => unknown;
+/** A manifest entry as the delivery adapter serves it. */
+export interface FileRouteHandlers {
+    path: string;
+    page?: boolean;
+    $component?: unknown;
+    $HEAD?: APIHandlerRef;
+    $GET?: APIHandlerRef;
+    $POST?: APIHandlerRef;
+    $PUT?: APIHandlerRef;
+    $PATCH?: APIHandlerRef;
+    $DELETE?: APIHandlerRef;
+    [key: string]: unknown;
+}
+export interface APIHandlerRef {
+    import(): Promise<Record<string, APIHandler>>;
+}
+export interface APIMatch {
+    handler: APIHandlerRef;
+    params?: Record<string, string>;
+    /** `true` when the module also renders a page at this path. */
+    isPage: boolean;
+}
+/**
+ * Builds a matcher over the flat manifest's handler-carrying entries. Route
+ * paths translate from the neutral pattern language to the radix tree —
+ * `(group)` segments stripped, `*rest` catch-alls, static segments
+ * URL-encoded. Optional parameters are rejected (a radix tree cannot
+ * represent them) and duplicate paths are a configuration error.
+ */
+export declare function createAPIMatcher(routes: readonly FileRouteHandlers[]): (path: string, method: string) => APIMatch | undefined;
+/** Strips a leading path base: `stripPathBase("/app/x", "/app")` → `/x`. */
+export declare function stripPathBase(path: string, base: string): string;
+export interface APIHandlerOptions {
+    /** A path base stripped from the URL before matching. Defaults to `/`. */
+    base?: string;
+    /**
+     * How the adapter reaches the request event it hands to handlers. Defaults
+     * to the core request-event scope (the storage `provideRequestEvent`
+     * establishes), which is where a middleware chain runs — override it when
+     * dispatching outside one, or to hand handlers a richer event.
+     */
+    getEvent?: () => APIEvent;
+}
+/**
+ * Fetch-style middleware serving the manifest's API routes:
+ *
+ * ```ts
+ * import routes from "virtual:file-routes";
+ * import { createAPIHandler } from "filesystem-routing/api";
+ *
+ * export default [createAPIHandler(routes)];
+ * ```
+ *
+ * Dispatch preserves SolidStart's semantics: unmatched requests (no route,
+ * or no handler for the method) advance the chain; `HEAD` falls back to the
+ * `GET` handler; matched params are written to `event.params` before the
+ * handler runs. A handler returning `undefined` declines the request —
+ * allowed for `GET` only (anything else throws): a page module falls
+ * through to the chain (its component renders instead), a handler-only
+ * module answers 404.
+ */
+export declare function createAPIHandler(routes: readonly FileRouteHandlers[], options?: APIHandlerOptions): (request: Request, next: (request?: Request) => Response | Promise<Response>) => Promise<Response>;

package/dist/api.js

@@ -0,0 +1,120 @@
+import { createRouter } from "radix3";
+function containsHTTP(route) {
+    return route.$HEAD || route.$GET || route.$POST || route.$PUT || route.$PATCH || route.$DELETE;
+}
+/**
+ * Builds a matcher over the flat manifest's handler-carrying entries. Route
+ * paths translate from the neutral pattern language to the radix tree —
+ * `(group)` segments stripped, `*rest` catch-alls, static segments
+ * URL-encoded. Optional parameters are rejected (a radix tree cannot
+ * represent them) and duplicate paths are a configuration error.
+ */
+export function createAPIMatcher(routes) {
+    const router = createRouter({
+        routes: routes.reduce((memo, route) => {
+            if (!containsHTTP(route))
+                return memo;
+            const path = route.path
+                .replace(/\([^)/]+\)/g, "")
+                .replace(/\/+/g, "/")
+                .replace(/\*([^/]*)/g, (_, m) => `**:${m}`)
+                .split("/")
+                .map(s => (s.startsWith(":") || s.startsWith("*") ? s : encodeURIComponent(s)))
+                .join("/");
+            if (/:[^/]*\?/g.test(path)) {
+                throw new Error(`Optional parameters are not supported in API routes: ${path}`);
+            }
+            if (memo[path]) {
+                throw new Error(`Duplicate API routes for "${path}" found at "${memo[path].route.path}" and "${route.path}"`);
+            }
+            memo[path] = { route };
+            return memo;
+        }, {})
+    });
+    return (path, method) => {
+        const match = router.lookup(path);
+        if (!match || !match.route)
+            return;
+        const route = match.route;
+        // A `GET` handler answers `HEAD` unless the module handles it itself.
+        const handler = method === "HEAD" ? route.$HEAD || route.$GET : route[`$${method}`];
+        if (handler === undefined)
+            return;
+        return {
+            handler: handler,
+            params: match.params,
+            isPage: route.page === true && route.$component !== undefined
+        };
+    };
+}
+/** Strips a leading path base: `stripPathBase("/app/x", "/app")` → `/x`. */
+export function stripPathBase(path, base) {
+    if (!base || base === "/")
+        return path;
+    const normalizedBase = base.endsWith("/") ? base.slice(0, -1) : base;
+    if (path === normalizedBase)
+        return "/";
+    if (path.startsWith(`${normalizedBase}/`))
+        return path.slice(normalizedBase.length);
+    return path;
+}
+const RequestContext = Symbol.for("solid.RequestContext");
+function getScopedEvent() {
+    const event = globalThis[RequestContext]?.getStore();
+    if (!event) {
+        throw new Error("API route dispatched outside a request-event scope. Compose the handler " +
+            "inside `provideRequestEvent` (any `ssr.middleware`-style chain already is), " +
+            "or pass `getEvent`.");
+    }
+    return event;
+}
+function toResponse(result) {
+    if (result instanceof Response)
+        return result;
+    if (typeof result === "string")
+        return new Response(result);
+    return Response.json(result);
+}
+/**
+ * Fetch-style middleware serving the manifest's API routes:
+ *
+ * ```ts
+ * import routes from "virtual:file-routes";
+ * import { createAPIHandler } from "filesystem-routing/api";
+ *
+ * export default [createAPIHandler(routes)];
+ * ```
+ *
+ * Dispatch preserves SolidStart's semantics: unmatched requests (no route,
+ * or no handler for the method) advance the chain; `HEAD` falls back to the
+ * `GET` handler; matched params are written to `event.params` before the
+ * handler runs. A handler returning `undefined` declines the request —
+ * allowed for `GET` only (anything else throws): a page module falls
+ * through to the chain (its component renders instead), a handler-only
+ * module answers 404.
+ */
+export function createAPIHandler(routes, options = {}) {
+    const match = createAPIMatcher(routes);
+    const getEvent = options.getEvent ?? getScopedEvent;
+    return async (request, next) => {
+        const url = new URL(request.url);
+        const matched = match(stripPathBase(url.pathname, options.base ?? "/"), request.method);
+        if (!matched)
+            return next();
+        const mod = await matched.handler.import();
+        const fn = request.method === "HEAD" ? mod.HEAD || mod.GET : mod[request.method];
+        if (typeof fn !== "function")
+            return next();
+        const event = getEvent();
+        event.params = matched.params || {};
+        const result = await fn(event);
+        if (result !== undefined)
+            return toResponse(result);
+        if (request.method !== "GET") {
+            throw new Error(`API handler for ${request.method} "${request.url}" did not return a response.`);
+        }
+        if (!matched.isPage)
+            return new Response(null, { status: 404 });
+        return next();
+    };
+}

package/dist/router.d.ts

@@ -3,7 +3,10 @@ export declare const glob: (path: string) => string[];
 /** Normalize a file path to posix separators (bundler-agnostic). */
 export declare function normalizePath(path: string): string;
 export interface FileSystemRouterConfig {
-    /** Absolute path of the route directory to scan. */
+    /**
+     * Route directory to scan. Relative paths are resolved against the
+     * current working directory.
+     */
     dir: string;
     /** File extensions (without the dot) that participate in routing. */
     extensions: string[];

package/dist/router.js

@@ -1,6 +1,6 @@
 import fg from "fast-glob";
 import micromatch from "micromatch";
-import { posix, sep } from "node:path";
+import { posix, resolve, sep } from "node:path";
 export const glob = (path) => fg.sync(path, { absolute: true });
 /** Normalize a file path to posix separators (bundler-agnostic). */
 export function normalizePath(path) {
@@ -24,7 +24,10 @@ export class BaseFileSystemRouter extends EventTarget {
     constructor(config) {
         super();
         this.routes = [];
-        this.config = config;
+        // A relative dir would glob fine, but the matched files come back
+        // absolute and would then fail `isRoute`'s micromatch against the
+        // relative pattern, silently yielding zero routes.
+        this.config = { ...config, dir: normalizePath(resolve(config.dir)) };
     }
     glob() {
         const extensions = this.config.extensions;

package/dist/vite/index.d.ts

@@ -3,7 +3,7 @@ import { type PageFileSystemRouterConfig } from "../convention.ts";
 import { BaseFileSystemRouter } from "../router.ts";
 import { DEFAULT_EXTENSIONS, moduleId } from "./constants.ts";
 export { DEFAULT_EXTENSIONS, moduleId };
-export { treeShake } from "./tree-shake.ts";
+export { sanitizeChunkFileName, toPickId, treeShake } from "./tree-shake.ts";
 export { fileSystemWatcher } from "./fs-watcher.ts";
 export interface FileRoutesOptions extends Pick<PageFileSystemRouterConfig, "components" | "httpMethods" | "toPath" | "toRoute"> {
     /** Route directory, relative to the Vite root. Defaults to `src/routes`. */

package/dist/vite/index.js

@@ -5,10 +5,10 @@ import { normalizePath } from "../router.js";
 import { buildRouteTree } from "../tree.js";
 import { DEFAULT_EXTENSIONS, moduleId } from "./constants.js";
 import { fileSystemWatcher } from "./fs-watcher.js";
-import { treeShake } from "./tree-shake.js";
+import { sanitizeChunkFileName, toPickId, treeShake } from "./tree-shake.js";
 import { serializeTypes } from "./types.js";
 export { DEFAULT_EXTENSIONS, moduleId };
-export { treeShake } from "./tree-shake.js";
+export { sanitizeChunkFileName, toPickId, treeShake } from "./tree-shake.js";
 export { fileSystemWatcher } from "./fs-watcher.js";
 /**
  * The Vite delivery adapter for `filesystem-routing`.
@@ -61,20 +61,27 @@ export function fileRoutes(options = {}) {
         writeFileSync(file, contents);
     }
     /** The id a route module ref is loaded from: its source plus its picks. */
-    const toModuleId = (ref) => `${ref.src}?${ref.pick.map(pick => `pick=${pick}`).join("&")}`;
+    const toModuleId = (ref) => toPickId(ref.src, ref.pick);
     return [
         {
             name: "filesystem-routing",
             enforce: "pre",
             config() {
-                // Packages importing the virtual module (which only this plugin can
-                // resolve) must stay out of esbuild prebundling.
-                if (!options.optimizeDepsExclude?.length)
-                    return;
                 return {
-                    optimizeDeps: {
-                        exclude: options.optimizeDepsExclude
-                    }
+                    build: {
+                        rollupOptions: {
+                            output: {
+                                // Keeps route chunks named after their file rather than after
+                                // the `?pick=...` id that addresses them. See toPickId.
+                                sanitizeFileName: sanitizeChunkFileName
+                            }
+                        }
+                    },
+                    // Packages importing the virtual module (which only this plugin can
+                    // resolve) must stay out of esbuild prebundling.
+                    ...(options.optimizeDepsExclude?.length
+                        ? { optimizeDeps: { exclude: options.optimizeDepsExclude } }
+                        : {})
                 };
             },
             configResolved(config) {

package/dist/vite/tree-shake.d.ts

@@ -1,2 +1,29 @@
 import type { Plugin } from "vite";
+/**
+ * Builds the module id used to import a subset of a route file's exports.
+ *
+ * The `pick` list has to live in the query so that the same file can be
+ * instantiated once per export subset (the client picks `default`/`$css`,
+ * the server picks its HTTP handlers). That query would otherwise leave the
+ * id ending in `?pick=GET`, which silently excludes route files from any
+ * plugin whose filter is anchored on the file extension -- a very common
+ * default, e.g. unplugin-macros' `/\.[cm]?[jt]sx?$/`.
+ *
+ * The trailing `lang.<ext>` marker is the same convention Vue SFCs use
+ * (`?vue&type=script&lang.ts`) and puts a real extension back at the end of
+ * the id, so those filters match again.
+ *
+ * @see https://github.com/solidjs/solid-start/issues/1918
+ */
+export declare function toPickId(src: string, pick: string[]): string;
+/**
+ * Rollup's default chunk name sanitizer, plus a pass that drops the
+ * `?pick=...&lang` tail so route chunks keep the short, stable filenames they
+ * had before the `lang` marker was introduced (`index-<hash>.js`, not
+ * `index.tsx_pick_default_pick__css_lang-<hash>.js`). Client chunk filenames
+ * are public URLs, so this is not purely cosmetic.
+ *
+ * @see https://github.com/rollup/rollup/blob/master/src/utils/sanitizeFileName.ts
+ */
+export declare function sanitizeChunkFileName(name: string): string;
 export declare function treeShake(): Plugin;

package/dist/vite/tree-shake.js

@@ -1,7 +1,52 @@
 // All credit for this work goes to the amazing Next.js team.
 // https://github.com/vercel/next.js/blob/canary/packages/next/build/babel/plugins/next-ssg-transform.ts
 // This is adapted to work with routeData functions. It can be run in two modes, one which preserves the routeData and the Component in the same file, and one which creates a
-import { basename } from "node:path";
+import { basename, extname } from "node:path";
+const PICKABLE_EXTENSIONS = ["js", "jsx", "ts", "tsx"];
+/**
+ * Builds the module id used to import a subset of a route file's exports.
+ *
+ * The `pick` list has to live in the query so that the same file can be
+ * instantiated once per export subset (the client picks `default`/`$css`,
+ * the server picks its HTTP handlers). That query would otherwise leave the
+ * id ending in `?pick=GET`, which silently excludes route files from any
+ * plugin whose filter is anchored on the file extension -- a very common
+ * default, e.g. unplugin-macros' `/\.[cm]?[jt]sx?$/`.
+ *
+ * The trailing `lang.<ext>` marker is the same convention Vue SFCs use
+ * (`?vue&type=script&lang.ts`) and puts a real extension back at the end of
+ * the id, so those filters match again.
+ *
+ * @see https://github.com/solidjs/solid-start/issues/1918
+ */
+export function toPickId(src, pick) {
+    const query = pick.map(p => `pick=${p}`).join("&");
+    const ext = extname(src).slice(1);
+    return PICKABLE_EXTENSIONS.includes(ext) ? `${src}?${query}&lang.${ext}` : `${src}?${query}`;
+}
+/**
+ * Matches the tail that {@link toPickId} appends, as it appears in a chunk
+ * name. Bundlers derive a chunk name from the module id by taking the
+ * basename minus its extension, so `index.tsx?pick=default&pick=$css&lang.tsx`
+ * arrives here as `index.tsx?pick=default&pick=$css&lang`.
+ */
+const PICK_CHUNK_NAME_RE = /\.[cm]?[jt]sx?\?pick=[^?]*&lang$/;
+const INVALID_CHAR_RE = /[\u0000-\u001F"#$&*+,:;<=>?[\]^`{|}\u007F]/g;
+const DRIVE_LETTER_RE = /^[a-z]:/i;
+/**
+ * Rollup's default chunk name sanitizer, plus a pass that drops the
+ * `?pick=...&lang` tail so route chunks keep the short, stable filenames they
+ * had before the `lang` marker was introduced (`index-<hash>.js`, not
+ * `index.tsx_pick_default_pick__css_lang-<hash>.js`). Client chunk filenames
+ * are public URLs, so this is not purely cosmetic.
+ *
+ * @see https://github.com/rollup/rollup/blob/master/src/utils/sanitizeFileName.ts
+ */
+export function sanitizeChunkFileName(name) {
+    const stripped = name.replace(PICK_CHUNK_NAME_RE, "");
+    const driveLetter = DRIVE_LETTER_RE.exec(stripped)?.[0] ?? "";
+    return driveLetter + stripped.slice(driveLetter.length).replace(INVALID_CHAR_RE, "_");
+}
 function treeShakeTransform({ types: t }) {
     function getIdentifier(path) {
         const parentPath = path.parentPath;
@@ -133,6 +178,11 @@ function treeShakeTransform({ types: t }) {
                             if (!state.opts.pick) {
                                 return;
                             }
+                            // Only module-level exports are route exports; `export` inside a
+                            // TS namespace/module block is unrelated to the pick list.
+                            if (!exportNamedPath.parentPath.isProgram()) {
+                                return;
+                            }
                             const specifiers = exportNamedPath.get("specifiers");
                             if (specifiers.length) {
                                 specifiers.forEach(s => {

package/package.json

@@ -2,7 +2,7 @@
   "name": "filesystem-routing",
   "description": "Router-neutral file-system routing: scans a route directory into a neutral route manifest with pluggable conventions and delivery adapters",
   "license": "MIT",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": "Ryan Carniato",
   "homepage": "https://github.com/solidjs/filesystem-routing#readme",
   "repository": {
@@ -40,6 +40,10 @@
       "types": "./dist/vite/index.d.ts",
       "default": "./dist/vite/index.js"
     },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    },
     "./types": {
       "types": "./types.d.ts"
     }
@@ -55,7 +59,8 @@
     "@types/micromatch": "^4.0.10",
     "fast-glob": "^3.3.3",
     "micromatch": "^4.0.8",
-    "oxc-parser": "^0.139.0"
+    "oxc-parser": "^0.139.0",
+    "radix3": "^1.1.2"
   },
   "peerDependencies": {
     "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"