filesystem-routing 0.1.0

package/dist/index.js

@@ -0,0 +1,5 @@
+export { analyzeModule, getExportName, getLocalExportName } from "./analyze.js";
+export { BaseFileSystemRouter, cleanPath, glob, normalizePath } from "./router.js";
+export { HTTP_METHODS, PageFileSystemRouter, routePathFromFile } from "./convention.js";
+export { FlatFileSystemRouter, flatRoutePathFromFile } from "./flat.js";
+export { buildRouteTree, stripRouteGroups } from "./tree.js";

package/dist/manifest.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The neutral route manifest.
+ *
+ * A file-system router produces a flat list of `RouteManifestEntry` objects.
+ * The manifest is deliberately router-agnostic: it records paths, params,
+ * module refs and export info, but says nothing about how a router turns
+ * those into its own route definitions. Each router ships a small emission
+ * adapter for that (e.g. `@solidjs/router/fs` emits `RouteDefinition`s),
+ * and each bundler ships a delivery adapter (e.g. `filesystem-routing/vite`
+ * serializes the manifest into a virtual module).
+ */
+/**
+ * A reference to a subset of a route module's exports.
+ *
+ * Delivery adapters materialize refs into code. The key the ref is stored
+ * under decides how:
+ * - keys prefixed `$` become lazy refs: `{ src, import: () => import(...) }`
+ * - keys prefixed `$$` become eager refs: `{ require: () => ({ ...exports }) }`
+ */
+export interface ModuleRef {
+    /** Absolute path of the source module. */
+    src: string;
+    /** The named exports (or `"default"`) this ref selects from the module. */
+    pick: string[];
+}
+export interface RouteManifestEntry {
+    /**
+     * The route path in the neutral pattern language proven by SolidStart:
+     * `:param`, `:param?` (optional) and `*rest` (catch-all) segments.
+     * Group segments (`(name)`) are retained; emission adapters decide how
+     * to nest and strip them.
+     */
+    path: string;
+    /** `true` when the module renders a page (has a default export). */
+    page?: boolean;
+    /** Lazy ref to the page component module. */
+    $component?: ModuleRef;
+    /** Eager ref to the route config (`route` export), when present. */
+    $$route?: ModuleRef;
+    /**
+     * Additional refs and metadata added by convention extensions, e.g. a
+     * server convention may add `$GET`/`$POST` handler refs. Keys prefixed
+     * `$`/`$$` are treated as lazy/eager module refs by delivery adapters.
+     */
+    [key: string]: unknown;
+}

package/dist/manifest.js

@@ -0,0 +1,12 @@
+/**
+ * The neutral route manifest.
+ *
+ * A file-system router produces a flat list of `RouteManifestEntry` objects.
+ * The manifest is deliberately router-agnostic: it records paths, params,
+ * module refs and export info, but says nothing about how a router turns
+ * those into its own route definitions. Each router ships a small emission
+ * adapter for that (e.g. `@solidjs/router/fs` emits `RouteDefinition`s),
+ * and each bundler ships a delivery adapter (e.g. `filesystem-routing/vite`
+ * serializes the manifest into a virtual module).
+ */
+export {};

package/dist/router.d.ts

@@ -0,0 +1,54 @@
+import type { RouteManifestEntry } from "./manifest.ts";
+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. */
+    dir: string;
+    /** File extensions (without the dot) that participate in routing. */
+    extensions: string[];
+    /**
+     * Pluggable filename convention: maps a route file (relative to `dir`,
+     * extension stripped, e.g. `/blog/[id]`) to a route path in the neutral
+     * pattern language, or `undefined` to skip the file. When omitted, the
+     * router's own `toPath` implementation is used.
+     */
+    toPath?: (routeFile: string, config: FileSystemRouterConfig) => string | undefined;
+    /**
+     * Pluggable module convention: maps a source file to a manifest entry,
+     * or `undefined` to skip the file. When omitted, the router's own
+     * `toRoute` implementation is used.
+     */
+    toRoute?: (src: string, router: BaseFileSystemRouter) => RouteManifestEntry | undefined;
+}
+type RouterEvent = CustomEvent<{
+    route: string;
+    type: "update" | "remove" | "add";
+}>;
+/** Strips the route dir prefix and the file extension from a source path. */
+export declare function cleanPath(src: string, config: FileSystemRouterConfig): string;
+/**
+ * Bundler-agnostic file-system router: scans a directory into a flat, neutral
+ * route manifest and keeps it up to date as files are added, changed and
+ * removed. Delivery adapters (e.g. the Vite plugin) subscribe to `reload`
+ * events; emission adapters consume the manifest.
+ */
+export declare class BaseFileSystemRouter extends EventTarget {
+    routes: RouteManifestEntry[];
+    config: FileSystemRouterConfig;
+    constructor(config: FileSystemRouterConfig);
+    glob(): string;
+    buildRoutes(): Promise<RouteManifestEntry[]>;
+    isRoute(src: string): boolean;
+    toPath(src: string): string | undefined;
+    toRoute(src: string): RouteManifestEntry | undefined;
+    _addRoute(route: RouteManifestEntry): boolean;
+    addRoute(src: string): Promise<void>;
+    reload(route: string, type: "update" | "remove" | "add"): void;
+    updateRoute(src_: string): Promise<void>;
+    removeRoute(src: string): void;
+    on(type: string, cb: (evt: RouterEvent) => void): () => void;
+    buildRoutesPromise?: Promise<RouteManifestEntry[]>;
+    getRoutes(): Promise<RouteManifestEntry[]>;
+}
+export {};

package/dist/router.js

@@ -0,0 +1,128 @@
+import fg from "fast-glob";
+import micromatch from "micromatch";
+import { posix, 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) {
+    return sep === "\\" ? path.replace(/\\/g, "/") : path;
+}
+/** Strips the route dir prefix and the file extension from a source path. */
+export function cleanPath(src, config) {
+    return src
+        .slice(config.dir.length)
+        .replace(new RegExp(`\.(${(config.extensions ?? []).join("|")})$`), "");
+}
+/**
+ * Bundler-agnostic file-system router: scans a directory into a flat, neutral
+ * route manifest and keeps it up to date as files are added, changed and
+ * removed. Delivery adapters (e.g. the Vite plugin) subscribe to `reload`
+ * events; emission adapters consume the manifest.
+ */
+export class BaseFileSystemRouter extends EventTarget {
+    routes;
+    config;
+    constructor(config) {
+        super();
+        this.routes = [];
+        this.config = config;
+    }
+    glob() {
+        const extensions = this.config.extensions;
+        // a single-entry brace pattern like `.{tsx}` is treated as a literal
+        const suffix = extensions.length === 1 ? `.${extensions[0]}` : `.{${extensions.join(",")}}`;
+        return posix.join(fg.convertPathToPattern(this.config.dir), "**/*") + suffix;
+    }
+    async buildRoutes() {
+        for (const src of glob(this.glob())) {
+            await this.addRoute(src);
+        }
+        return this.routes;
+    }
+    isRoute(src) {
+        return Boolean(micromatch(src, this.glob())?.length);
+    }
+    toPath(src) {
+        if (this.config.toPath)
+            return this.config.toPath(cleanPath(src, this.config), this.config);
+        throw new Error("Not implemented");
+    }
+    toRoute(src) {
+        if (this.config.toRoute)
+            return this.config.toRoute(src, this);
+        throw new Error("Not implemented");
+    }
+    _addRoute(route) {
+        const idx = this.routes.findIndex(r => r.path === route.path);
+        if (idx >= 0)
+            this.routes.splice(idx, 1);
+        this.routes.push(route);
+        return idx >= 0;
+    }
+    async addRoute(src) {
+        src = normalizePath(src);
+        if (this.isRoute(src)) {
+            try {
+                const route = this.toRoute(src);
+                if (route) {
+                    this._addRoute(route);
+                    this.reload(route.path, "add");
+                }
+            }
+            catch (e) {
+                console.error(e);
+            }
+        }
+    }
+    reload(route, type) {
+        this.dispatchEvent(new CustomEvent("reload", {
+            detail: {
+                route,
+                type
+            }
+        }));
+    }
+    async updateRoute(src_) {
+        const src = normalizePath(src_);
+        if (this.isRoute(src)) {
+            try {
+                const route = this.toRoute(src);
+                if (route) {
+                    const updated = this._addRoute(route);
+                    this.reload(route.path, updated ? "update" : "add");
+                }
+                else {
+                    this.removeRoute(src_);
+                }
+            }
+            catch (e) {
+                console.error(e);
+            }
+        }
+    }
+    removeRoute(src) {
+        src = normalizePath(src);
+        if (this.isRoute(src)) {
+            const path = this.toPath(src);
+            if (path === undefined) {
+                return;
+            }
+            const idx = this.routes.findIndex(r => r.path === path);
+            if (idx === -1)
+                return;
+            this.routes.splice(idx, 1);
+            this.reload(path, "remove");
+        }
+    }
+    on(type, cb) {
+        this.addEventListener(type, cb);
+        return () => this.removeEventListener(type, cb);
+    }
+    buildRoutesPromise;
+    async getRoutes() {
+        if (!this.buildRoutesPromise) {
+            this.buildRoutesPromise = this.buildRoutes();
+        }
+        await this.buildRoutesPromise;
+        return this.routes;
+    }
+}

package/dist/tree.d.ts

@@ -0,0 +1,26 @@
+import type { RouteManifestEntry } from "./manifest.ts";
+/**
+ * Nesting and group-stripping for the neutral route manifest.
+ *
+ * This module is deliberately free of Node and bundler imports: delivery
+ * adapters run it at build time (the Vite adapter serializes the resulting
+ * tree into the virtual module), and runtime consumers that receive only a
+ * flat manifest can run it themselves.
+ */
+export interface RouteTreeEntry extends RouteManifestEntry {
+    /** The manifest path this node was nested under, group segments included. */
+    id: string;
+    children?: RouteTreeEntry[];
+}
+/** Removes `(group)` segments from a route path: `/(app)/home` → `/home`. */
+export declare function stripRouteGroups(path: string): string;
+/**
+ * Nests a flat manifest by path prefix and strips `(group)` segments, so
+ * `/(app)/dashboard` renders at `/dashboard` inside the `/(app)` layout.
+ *
+ * Nested entries keep the path *relative to their parent*, which is what
+ * nested routers expect. Pass only the entries that participate in the tree
+ * (typically `entries.filter(entry => entry.page)`); the input is not
+ * mutated.
+ */
+export declare function buildRouteTree(entries: readonly RouteManifestEntry[]): RouteTreeEntry[];

package/dist/tree.js

@@ -0,0 +1,29 @@
+/** Removes `(group)` segments from a route path: `/(app)/home` → `/home`. */
+export function stripRouteGroups(path) {
+    return path.replace(/\([^)/]+\)/g, "").replace(/\/+/g, "/");
+}
+/**
+ * Nests a flat manifest by path prefix and strips `(group)` segments, so
+ * `/(app)/dashboard` renders at `/dashboard` inside the `/(app)` layout.
+ *
+ * Nested entries keep the path *relative to their parent*, which is what
+ * nested routers expect. Pass only the entries that participate in the tree
+ * (typically `entries.filter(entry => entry.page)`); the input is not
+ * mutated.
+ */
+export function buildRouteTree(entries) {
+    function processRoute(routes, route, id) {
+        const parentRoute = routes.find(o => id.startsWith(o.id + "/"));
+        if (!parentRoute) {
+            routes.push({ ...route, id, path: stripRouteGroups(id) });
+            return;
+        }
+        processRoute(parentRoute.children || (parentRoute.children = []), route, id.slice(parentRoute.id.length));
+    }
+    return [...entries]
+        .sort((a, b) => a.path.length - b.path.length)
+        .reduce((routes, route) => {
+        processRoute(routes, route, route.path);
+        return routes;
+    }, []);
+}

package/dist/vite/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The virtual module that serves the serialized route manifest.
+ *
+ * `virtual:` is Vite's convention for plugin-served modules, and the name is
+ * not tied to any router. Override it with the plugin's `moduleId` option.
+ */
+export declare const moduleId = "virtual:file-routes";
+export declare const DEFAULT_EXTENSIONS: string[];

package/dist/vite/constants.js

@@ -0,0 +1,8 @@
+/**
+ * The virtual module that serves the serialized route manifest.
+ *
+ * `virtual:` is Vite's convention for plugin-served modules, and the name is
+ * not tied to any router. Override it with the plugin's `moduleId` option.
+ */
+export const moduleId = "virtual:file-routes";
+export const DEFAULT_EXTENSIONS = ["js", "jsx", "ts", "tsx"];

package/dist/vite/debounce.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Creates a debounced function that delays the invocation of a function
+ */
+export declare const debounce: <T extends (...args: any[]) => void>(cb: T, debounceMs: number) => (...args: Parameters<T>) => void;

package/dist/vite/debounce.js

@@ -0,0 +1,10 @@
+/**
+ * Creates a debounced function that delays the invocation of a function
+ */
+export const debounce = (cb, debounceMs) => {
+    let timeout;
+    return (...args) => {
+        clearTimeout(timeout);
+        timeout = setTimeout(() => cb(...args), debounceMs);
+    };
+};

package/dist/vite/fs-watcher.d.ts

@@ -0,0 +1,5 @@
+import type { PluginOption } from "vite";
+import type { BaseFileSystemRouter } from "../router.ts";
+export declare const fileSystemWatcher: (getRouter: (environment: string) => BaseFileSystemRouter | undefined, moduleId: string, 
+/** Runs on every route change, before the module is invalidated. */
+onReload?: () => void | Promise<void>) => PluginOption;

package/dist/vite/fs-watcher.js

@@ -0,0 +1,69 @@
+import { debounce } from "./debounce.js";
+function setupWatcher(watcher, routes) {
+    watcher.on("unlink", path => routes.removeRoute(path));
+    watcher.on("add", path => routes.addRoute(path));
+    watcher.on("change", path => routes.updateRoute(path));
+}
+function createRoutesReloader(server, routes, environment, moduleId, onReload) {
+    const devEnv = server.environments[environment];
+    if (!devEnv?.moduleGraph)
+        return;
+    /**
+     * Debounce catches multiple route changes in a row
+     * Short timeout for inexpensive invalidations
+     */
+    const invalidateModule = debounce((mod) => {
+        devEnv.moduleGraph.invalidateModule(mod);
+    }, 0);
+    /**
+     * Long debounce timeout for expensive reloads
+     */
+    const reloadModule = debounce((mod) => {
+        devEnv.reloadModule(mod);
+    }, 200);
+    return routes.on("reload", function handleRoutesReload(evt) {
+        void onReload?.();
+        const mod = devEnv.moduleGraph.getModuleById(moduleId);
+        if (!mod) {
+            devEnv.hot.send({ type: "full-reload" });
+            return;
+        }
+        if (evt.detail.type !== "update") {
+            // Adding or removing a route changes the manifest itself, and marking
+            // it invalid is not enough to replace it: whoever evaluated the module
+            // holds their own copy — the browser, or a server-side module runner
+            // like the one nitro serves SSR from — and only a reload displaces it.
+            // An `update` needs no reload: the entries are unchanged, and the route
+            // module's own HMR covers its contents.
+            reloadModule(mod);
+        }
+        else {
+            invalidateModule(mod);
+        }
+    });
+}
+export const fileSystemWatcher = (getRouter, moduleId, 
+/** Runs on every route change, before the module is invalidated. */
+onReload) => {
+    const plugin = {
+        name: "filesystem-routing:watcher",
+        async configureServer(server) {
+            const watched = new Set();
+            for (const environment of Object.keys(server.environments)) {
+                const router = getRouter(environment);
+                if (!router)
+                    continue;
+                if (!watched.has(router)) {
+                    watched.add(router);
+                    setupWatcher(server.watcher, router);
+                }
+                // Build the manifest before listening for reloads, so the initial
+                // scan's `add` events don't invalidate the module mid-page-load.
+                router
+                    .getRoutes()
+                    .then(() => createRoutesReloader(server, router, environment, moduleId, onReload));
+            }
+        }
+    };
+    return plugin;
+};

package/dist/vite/index.d.ts

@@ -0,0 +1,69 @@
+import type { PluginOption } from "vite";
+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 { 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`. */
+    dir?: string;
+    /** File extensions that participate in routing. Defaults to js/jsx/ts/tsx. */
+    extensions?: string[];
+    /**
+     * A custom file-system router (scanning + convention) used for every Vite
+     * environment. Defaults to a `PageFileSystemRouter` over `dir`, configured
+     * with the convention options above.
+     */
+    router?: BaseFileSystemRouter;
+    /**
+     * Per-environment file-system routers, keyed by Vite environment name.
+     * Frameworks (e.g. SolidStart) use this to serve different conventions to
+     * client and server environments. Falls back to `router` for environments
+     * not listed.
+     */
+    routers?: Record<string, BaseFileSystemRouter>;
+    /** The id the route manifest is served from. Defaults to `virtual:file-routes`. */
+    moduleId?: string;
+    /**
+     * Vite environments whose build should take every route module as an
+     * entry, so routes are code-split into their own chunks. Frameworks pass
+     * their browser environment's name; the inputs are added to whatever the
+     * framework already configures.
+     */
+    buildInputs?: string | string[];
+    /**
+     * Packages that import the virtual module and must therefore stay out of
+     * esbuild's dependency prebundling, which cannot resolve it. Emission
+     * adapters are expected to take the manifest as an argument instead of
+     * importing the virtual module (so app source holds the only import, which
+     * prebundling never touches), making this an escape hatch for packages
+     * that import it anyway. Defaults to `[]`.
+     */
+    optimizeDepsExclude?: string[];
+    /**
+     * Write a declaration for the virtual module typing the manifest as a
+     * literal tuple, and keep it in step with the route directory. Routers
+     * that derive types from their route table need this: a runtime array
+     * tells them nothing, so path-derived types silently degrade without it.
+     *
+     * `true` writes `file-routes.d.ts` next to the Vite root; pass a path to
+     * put it elsewhere. The generated file is self-contained — reference it
+     * *instead of* `filesystem-routing/types`, never both.
+     */
+    types?: boolean | string;
+}
+/**
+ * The Vite delivery adapter for `filesystem-routing`.
+ *
+ * Serializes the neutral route manifest into the virtual module — module refs
+ * become code-split dynamic imports (`$`-prefixed keys) or eagerly required
+ * static imports (`$$`-prefixed keys) — and keeps it hot as route files are
+ * added, changed and removed.
+ *
+ * The module serves two views of the same entries: the default export is the
+ * flat manifest, and `pageRoutes` is the page entries nested by path with
+ * `(group)` segments stripped, so emission adapters don't each reimplement
+ * the tree.
+ */
+export declare function fileRoutes(options?: FileRoutesOptions): PluginOption[];