filesystem-routing 0.1.0

package/dist/vite/index.js

@@ -0,0 +1,215 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { PageFileSystemRouter } from "../convention.js";
+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 { serializeTypes } from "./types.js";
+export { DEFAULT_EXTENSIONS, moduleId };
+export { treeShake } from "./tree-shake.js";
+export { fileSystemWatcher } from "./fs-watcher.js";
+/**
+ * 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 function fileRoutes(options = {}) {
+    const virtualId = options.moduleId ?? moduleId;
+    const buildInputs = options.buildInputs === undefined
+        ? []
+        : Array.isArray(options.buildInputs)
+            ? options.buildInputs
+            : [options.buildInputs];
+    let defaultRouter = options.router;
+    let root = process.cwd();
+    const getRouter = (environment) => options.routers?.[environment] ?? defaultRouter;
+    /**
+     * The manifest the declaration describes. With per-environment routers the
+     * browser's is the one an app's routes are built from, so it wins.
+     */
+    const typesRouter = () => getRouter("client");
+    const typesFile = () => options.types === undefined || options.types === false
+        ? undefined
+        : resolve(root, options.types === true ? "file-routes.d.ts" : options.types);
+    async function writeTypes() {
+        const file = typesFile();
+        const router = typesRouter();
+        if (!file || !router)
+            return;
+        const routes = (await router.getRoutes()) ?? [];
+        const contents = serializeTypes(virtualId, routes, buildRouteTree(routes.filter(route => route.page)), dirname(file));
+        // Only touch the file when it actually changes: every environment calls
+        // this, and rewriting it would churn the watcher for no reason.
+        let previous;
+        try {
+            previous = readFileSync(file, "utf-8");
+        }
+        catch { }
+        if (previous === contents)
+            return;
+        mkdirSync(dirname(file), { recursive: true });
+        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("&")}`;
+    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
+                    }
+                };
+            },
+            configResolved(config) {
+                root = config.root;
+                if (!defaultRouter) {
+                    defaultRouter = new PageFileSystemRouter({
+                        dir: normalizePath(resolve(config.root, options.dir ?? "src/routes")),
+                        extensions: options.extensions ?? DEFAULT_EXTENSIONS,
+                        components: options.components,
+                        httpMethods: options.httpMethods,
+                        toPath: options.toPath,
+                        toRoute: options.toRoute
+                    });
+                }
+            },
+            async buildStart() {
+                await writeTypes();
+            },
+            async configEnvironment(name, _config, env) {
+                if (env.command !== "build" || !buildInputs.includes(name))
+                    return;
+                const router = getRouter(name);
+                if (!router)
+                    return;
+                // Every code-split route module is an entry of its own, so the
+                // manifest's dynamic imports resolve to real chunks. `$$` refs are
+                // inlined into the manifest and need no entry.
+                const input = [];
+                for (const route of await router.getRoutes()) {
+                    for (const [key, ref] of Object.entries(route)) {
+                        if (ref && key.startsWith("$") && !key.startsWith("$$")) {
+                            input.push(toModuleId(ref));
+                        }
+                    }
+                }
+                if (!input.length)
+                    return;
+                return { build: { rollupOptions: { input } } };
+            },
+            resolveId(source) {
+                if (source === virtualId)
+                    return virtualId;
+            },
+            async load(loadedId) {
+                if (loadedId !== virtualId)
+                    return;
+                const root = this.environment.config.root;
+                const isBuild = this.environment.mode === "build";
+                const js = jsCode();
+                const router = getRouter(this.environment.name);
+                const routes = (router ? await router.getRoutes() : []) ?? [];
+                const serializeEntry = (entry) => JSON.stringify(entry, (key, value) => {
+                    if (value === undefined)
+                        return undefined;
+                    if (key.startsWith("$$")) {
+                        const buildId = toModuleId(value);
+                        const refs = {};
+                        for (const pick of value.pick) {
+                            refs[pick] = js.addNamedImport(pick, buildId);
+                        }
+                        return {
+                            require: `_$() => ({ ${Object.entries(refs)
+                                .map(([pick, namedImport]) => `'${pick}': ${namedImport}`)
+                                .join(", ")} })$_`
+                        };
+                    }
+                    else if (key.startsWith("$")) {
+                        const buildId = toModuleId(value);
+                        return {
+                            src: relative(root, buildId),
+                            build: isBuild ? `_$() => import('${buildId}')$_` : undefined,
+                            import: `_$() => import('${buildId}')$_`
+                        };
+                    }
+                    return value;
+                })
+                    .replaceAll('"_$(', "(")
+                    .replaceAll(')$_"', ")");
+                // Entries are emitted once and both views reference them, so the
+                // nested view costs its own paths and nothing else.
+                const bindings = routes.map((route, index) => `const route${index} = ${serializeEntry(route)};`);
+                const tree = buildRouteTree(routes
+                    .map((route, index) => ({ path: route.path, page: route.page, index }))
+                    .filter(stub => stub.page));
+                const serializeTree = (nodes) => `[${nodes
+                    .map(node => {
+                    const fields = [
+                        `...route${node.index}`,
+                        `id: ${JSON.stringify(node.id)}`,
+                        `path: ${JSON.stringify(node.path)}`
+                    ];
+                    if (node.children)
+                        fields.push(`children: ${serializeTree(node.children)}`);
+                    return `{ ${fields.join(", ")} }`;
+                })
+                    .join(", ")}]`;
+                return `${js.getImportStatements()}
+${bindings.join("\n")}
+const routes = [${routes.map((_, index) => `route${index}`).join(", ")}];
+export default routes;
+export const pageRoutes = ${serializeTree(tree)};
+`;
+            }
+        },
+        treeShake(),
+        fileSystemWatcher(getRouter, virtualId, writeTypes)
+    ];
+}
+function jsCode() {
+    const imports = new Map();
+    let vars = 0;
+    function addNamedImport(name, source) {
+        let names = imports.get(source);
+        if (!names) {
+            names = {};
+            imports.set(source, names);
+        }
+        // The same export can be reached through more than one ref; reuse the
+        // binding instead of importing it twice.
+        const existing = names[name];
+        if (existing)
+            return existing;
+        const alias = "routeData" + vars++;
+        names[name] = alias;
+        return alias;
+    }
+    const getImportStatements = () => {
+        return [...imports.entries()]
+            .map(([source, names]) => `import { ${Object.entries(names)
+            .map(([name, alias]) => `${name} as ${alias}`)
+            .join(", ")} } from '${source}';`)
+            .join("\n");
+    };
+    return {
+        addNamedImport,
+        getImportStatements
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function treeShake(): Plugin;

package/dist/vite/tree-shake.js

@@ -0,0 +1,448 @@
+// 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";
+function treeShakeTransform({ types: t }) {
+    function getIdentifier(path) {
+        const parentPath = path.parentPath;
+        if (parentPath.type === "VariableDeclarator") {
+            const pp = parentPath;
+            const name = pp.get("id");
+            return name.node.type === "Identifier" ? name : null;
+        }
+        if (parentPath.type === "AssignmentExpression") {
+            const pp = parentPath;
+            const name = pp.get("left");
+            return name.node.type === "Identifier" ? name : null;
+        }
+        if (path.node.type === "ArrowFunctionExpression") {
+            return null;
+        }
+        return path.node.id && path.node.id.type === "Identifier" ? path.get("id") : null;
+    }
+    function isTypeOnlyReference(path) {
+        return path.getAncestry().some(parent => {
+            if (parent.isTSType())
+                return true;
+            if (parent.isExportNamedDeclaration())
+                return parent.node.exportKind === "type";
+            if (parent.isExportSpecifier())
+                return parent.node.exportKind === "type";
+            return false;
+        });
+    }
+    function runtimeReferences(binding) {
+        return binding.referencePaths.filter(ref => !isTypeOnlyReference(ref));
+    }
+    function isIdentifierReferenced(ident, includeTypes = false) {
+        const b = ident.scope.getBinding(ident.node.name);
+        if (b) {
+            const references = b.constantViolations.concat(includeTypes ? b.referencePaths : runtimeReferences(b));
+            if (!references.length)
+                return false;
+            if (b.path.type === "FunctionDeclaration") {
+                return !references.every(ref => ref.findParent(p => p === b.path));
+            }
+            return true;
+        }
+        return false;
+    }
+    function markFunction(path, state) {
+        const ident = getIdentifier(path);
+        if (ident && ident.node && isIdentifierReferenced(ident, true)) {
+            state.refs.add(ident);
+        }
+    }
+    function markImport(path, state) {
+        const local = path.get("local");
+        if (isIdentifierReferenced(local, true)) {
+            state.refs.add(local);
+        }
+    }
+    return {
+        visitor: {
+            Program: {
+                enter(path, state) {
+                    state.refs = new Set();
+                    state.candidates = new Set();
+                    state.done = false;
+                    path.traverse({
+                        VariableDeclarator(variablePath, variableState) {
+                            if (variablePath.node.id.type === "Identifier") {
+                                const local = variablePath.get("id");
+                                if (isIdentifierReferenced(local, true)) {
+                                    variableState.refs.add(local);
+                                }
+                            }
+                            else if (variablePath.node.id.type === "ObjectPattern") {
+                                const pattern = variablePath.get("id");
+                                const properties = pattern.get("properties");
+                                properties.forEach(p => {
+                                    const local = p.get(p.node.type === "ObjectProperty"
+                                        ? "value"
+                                        : p.node.type === "RestElement"
+                                            ? "argument"
+                                            : (() => {
+                                                throw new Error("invariant");
+                                            })());
+                                    if (isIdentifierReferenced(local, true)) {
+                                        variableState.refs.add(local);
+                                    }
+                                });
+                            }
+                            else if (variablePath.node.id.type === "ArrayPattern") {
+                                const pattern = variablePath.get("id");
+                                const elements = pattern.get("elements");
+                                elements.forEach(e => {
+                                    let local;
+                                    if (e.node && e.node.type === "Identifier") {
+                                        local = e;
+                                    }
+                                    else if (e.node && e.node.type === "RestElement") {
+                                        local = e.get("argument");
+                                    }
+                                    else {
+                                        return;
+                                    }
+                                    if (isIdentifierReferenced(local, true)) {
+                                        variableState.refs.add(local);
+                                    }
+                                });
+                            }
+                        },
+                        ExportDefaultDeclaration(exportNamedPath) {
+                            if (state.opts.pick && !state.opts.pick.includes("default")) {
+                                const decl = exportNamedPath.node.declaration;
+                                // A named function/class declaration creates a module-scope
+                                // binding that picked exports may reference, so only strip
+                                // the `export default`; the sweep below removes the
+                                // declaration again if nothing references it.
+                                if ((t.isFunctionDeclaration(decl) || t.isClassDeclaration(decl)) && decl.id) {
+                                    const [newPath] = exportNamedPath.replaceWith(decl);
+                                    const id = newPath.get("id");
+                                    state.refs.add(id);
+                                    state.candidates.add(id);
+                                }
+                                else {
+                                    exportNamedPath.remove();
+                                }
+                            }
+                        },
+                        ExportNamedDeclaration(exportNamedPath) {
+                            // No pick list means nothing gets pruned.
+                            if (!state.opts.pick) {
+                                return;
+                            }
+                            const specifiers = exportNamedPath.get("specifiers");
+                            if (specifiers.length) {
+                                specifiers.forEach(s => {
+                                    const exported = s.node.exported;
+                                    const exportedName = t.isIdentifier(exported) ? exported.name : exported.value;
+                                    if (!state.opts.pick.includes(exportedName)) {
+                                        s.remove();
+                                    }
+                                });
+                                if (exportNamedPath.node.specifiers.length < 1) {
+                                    exportNamedPath.remove();
+                                }
+                                return;
+                            }
+                            const decl = exportNamedPath.get("declaration");
+                            if (decl == null || decl.node == null) {
+                                return;
+                            }
+                            switch (decl.node.type) {
+                                case "FunctionDeclaration":
+                                case "ClassDeclaration": {
+                                    const name = decl.node.id?.name;
+                                    if (name && state.opts.pick && !state.opts.pick.includes(name)) {
+                                        // Keep the declaration in module scope since picked
+                                        // exports may reference it; the sweep below removes it
+                                        // again if unreferenced.
+                                        const [newPath] = exportNamedPath.replaceWith(decl.node);
+                                        const id = newPath.get("id");
+                                        state.refs.add(id);
+                                        state.candidates.add(id);
+                                    }
+                                    break;
+                                }
+                                case "VariableDeclaration": {
+                                    const declNode = decl.node;
+                                    // Destructuring declarators are conservatively treated as
+                                    // picked (matching the previous behavior of leaving them
+                                    // untouched).
+                                    const isPicked = (d) => d.id.type !== "Identifier" || state.opts.pick.includes(d.id.name);
+                                    if (declNode.declarations.every(isPicked)) {
+                                        break;
+                                    }
+                                    // Split into one declaration per declarator (preserving
+                                    // evaluation order) and export only the picked ones.
+                                    // Unpicked bindings are kept since picked exports may
+                                    // reference them; the sweep below removes them again if
+                                    // unreferenced.
+                                    const statements = declNode.declarations.map(d => {
+                                        const single = t.variableDeclaration(declNode.kind, [d]);
+                                        single.declare = declNode.declare;
+                                        return isPicked(d) ? t.exportNamedDeclaration(single, []) : single;
+                                    });
+                                    const newPaths = exportNamedPath.replaceWithMultiple(statements);
+                                    for (const p of newPaths) {
+                                        if (!p.isVariableDeclaration())
+                                            continue;
+                                        for (const d of p.get("declarations")) {
+                                            if (d.node.id.type === "Identifier") {
+                                                const id = d.get("id");
+                                                state.refs.add(id);
+                                                state.candidates.add(id);
+                                            }
+                                        }
+                                    }
+                                    break;
+                                }
+                                default: {
+                                    break;
+                                }
+                            }
+                        },
+                        FunctionDeclaration: markFunction,
+                        FunctionExpression: markFunction,
+                        ArrowFunctionExpression: markFunction,
+                        ClassDeclaration: markFunction,
+                        ClassExpression: markFunction,
+                        ImportSpecifier: markImport,
+                        ImportDefaultSpecifier: markImport,
+                        ImportNamespaceSpecifier: markImport,
+                        ImportDeclaration: (path, state) => {
+                            if (path.node.source.value.endsWith(".css") &&
+                                state.opts.pick &&
+                                !state.opts.pick.includes("$css")) {
+                                path.remove();
+                            }
+                        }
+                    }, state);
+                    // References alone cannot distinguish live bindings from dead cycles.
+                    // Build a graph of localized exports and retain only those reachable
+                    // from runtime code outside that graph.
+                    path.scope.crawl();
+                    const tracked = new Map();
+                    const candidateOwners = new Map();
+                    const addOwner = (owners, binding, owner) => {
+                        const paths = owners.get(binding) ?? new Set();
+                        paths.add(owner);
+                        owners.set(binding, paths);
+                    };
+                    for (const identifier of state.refs) {
+                        if (identifier.node?.type !== "Identifier" || !identifier.parentPath)
+                            continue;
+                        const binding = identifier.scope.getBinding(identifier.node.name);
+                        if (binding)
+                            addOwner(tracked, binding, identifier.parentPath);
+                    }
+                    for (const identifier of state.candidates) {
+                        if (!identifier.parentPath)
+                            continue;
+                        const binding = identifier.scope.getBinding(identifier.node.name);
+                        if (!binding)
+                            continue;
+                        addOwner(tracked, binding, identifier.parentPath);
+                        addOwner(candidateOwners, binding, identifier.parentPath);
+                    }
+                    const dependencies = new Map();
+                    const live = new Set();
+                    for (const [binding, owners] of tracked) {
+                        dependencies.set(binding, new Set());
+                        if ([...owners].some(owner => owner.findParent(parent => parent.isExportNamedDeclaration() || parent.isExportDefaultDeclaration()))) {
+                            live.add(binding);
+                        }
+                    }
+                    const ownerBindings = new Map();
+                    for (const [binding, owners] of tracked) {
+                        for (const owner of owners) {
+                            ownerBindings.set(owner, binding);
+                        }
+                    }
+                    const owningBinding = (reference) => {
+                        const owner = reference.find(parent => ownerBindings.has(parent));
+                        return owner && ownerBindings.get(owner);
+                    };
+                    for (const target of tracked.keys()) {
+                        const references = target.constantViolations.concat(runtimeReferences(target));
+                        for (const reference of references) {
+                            const source = owningBinding(reference);
+                            if (source)
+                                dependencies.get(source)?.add(target);
+                            else
+                                live.add(target);
+                        }
+                    }
+                    const pending = [...live];
+                    while (pending.length) {
+                        const source = pending.pop();
+                        for (const dependency of dependencies.get(source) ?? []) {
+                            if (live.has(dependency))
+                                continue;
+                            live.add(dependency);
+                            pending.push(dependency);
+                        }
+                    }
+                    const deadCandidates = new Set([...candidateOwners.keys()].filter(candidate => !live.has(candidate)));
+                    path.traverse({
+                        VariableDeclarator(variablePath) {
+                            if (variablePath.node.id.type !== "Identifier")
+                                return;
+                            const binding = variablePath.scope.getBinding(variablePath.node.id.name);
+                            if (binding && deadCandidates.has(binding))
+                                variablePath.remove();
+                        }
+                    });
+                    for (const [candidate, owners] of candidateOwners) {
+                        if (!deadCandidates.has(candidate))
+                            continue;
+                        for (const owner of owners) {
+                            if (!owner.removed && !owner.isVariableDeclarator())
+                                owner.remove();
+                        }
+                    }
+                    const refs = state.refs;
+                    const refNodes = new Set([...refs].map(ref => ref.node));
+                    let count = 0;
+                    const sweepFunction = (sweepPath) => {
+                        const ident = getIdentifier(sweepPath);
+                        if (ident && ident.node && refNodes.has(ident.node) && !isIdentifierReferenced(ident)) {
+                            ++count;
+                            if (t.isAssignmentExpression(sweepPath.parentPath) ||
+                                t.isVariableDeclarator(sweepPath.parentPath)) {
+                                sweepPath.parentPath.remove();
+                            }
+                            else {
+                                sweepPath.remove();
+                            }
+                        }
+                    };
+                    function sweepImport(sweepPath) {
+                        const local = sweepPath.get("local");
+                        if (refNodes.has(local.node) && !isIdentifierReferenced(local)) {
+                            ++count;
+                            sweepPath.remove();
+                            if (sweepPath.parent.specifiers.length === 0) {
+                                sweepPath.parentPath.remove();
+                            }
+                        }
+                    }
+                    do {
+                        path.scope.crawl();
+                        count = 0;
+                        path.traverse({
+                            VariableDeclarator(variablePath) {
+                                if (variablePath.node.id.type === "Identifier") {
+                                    const local = variablePath.get("id");
+                                    if (refNodes.has(local.node) && !isIdentifierReferenced(local)) {
+                                        ++count;
+                                        variablePath.remove();
+                                    }
+                                }
+                                else if (variablePath.node.id.type === "ObjectPattern") {
+                                    const pattern = variablePath.get("id");
+                                    const beforeCount = count;
+                                    const properties = pattern.get("properties");
+                                    properties.forEach(p => {
+                                        const local = p.get(p.node.type === "ObjectProperty"
+                                            ? "value"
+                                            : p.node.type === "RestElement"
+                                                ? "argument"
+                                                : (() => {
+                                                    throw new Error("invariant");
+                                                })());
+                                        if (refNodes.has(local.node) && !isIdentifierReferenced(local)) {
+                                            ++count;
+                                            p.remove();
+                                        }
+                                    });
+                                    if (beforeCount !== count && pattern.get("properties").length < 1) {
+                                        variablePath.remove();
+                                    }
+                                }
+                                else if (variablePath.node.id.type === "ArrayPattern") {
+                                    const pattern = variablePath.get("id");
+                                    const beforeCount = count;
+                                    const elements = pattern.get("elements");
+                                    elements.forEach(e => {
+                                        let local;
+                                        if (e.node && e.node.type === "Identifier") {
+                                            local = e;
+                                        }
+                                        else if (e.node && e.node.type === "RestElement") {
+                                            local = e.get("argument");
+                                        }
+                                        else {
+                                            return;
+                                        }
+                                        if (refNodes.has(local.node) && !isIdentifierReferenced(local)) {
+                                            ++count;
+                                            e.remove();
+                                        }
+                                    });
+                                    if (beforeCount !== count && pattern.get("elements").length < 1) {
+                                        variablePath.remove();
+                                    }
+                                }
+                            },
+                            FunctionDeclaration: sweepFunction,
+                            FunctionExpression: sweepFunction,
+                            ArrowFunctionExpression: sweepFunction,
+                            ClassDeclaration: sweepFunction,
+                            ClassExpression: sweepFunction,
+                            ImportSpecifier: sweepImport,
+                            ImportDefaultSpecifier: sweepImport,
+                            ImportNamespaceSpecifier: sweepImport
+                        });
+                    } while (count);
+                }
+            }
+        }
+    };
+}
+export function treeShake() {
+    async function transform(id, code) {
+        const [path, queryString] = id.split("?");
+        const query = new URLSearchParams(queryString);
+        if (query.has("pick")) {
+            const babel = await import("@babel/core");
+            const transformed = await babel.transformAsync(code, {
+                plugins: [[treeShakeTransform, { pick: query.getAll("pick") }]],
+                parserOpts: {
+                    plugins: ["jsx", "typescript"]
+                },
+                filename: basename(id),
+                ast: false,
+                sourceMaps: true,
+                configFile: false,
+                babelrc: false,
+                sourceFileName: id
+            });
+            return transformed;
+        }
+    }
+    return {
+        name: "filesystem-routing:tree-shake",
+        enforce: "pre",
+        async transform(code, id) {
+            const [path, queryString] = id.split("?");
+            if (!path)
+                return;
+            const query = new URLSearchParams(queryString);
+            const ext = path.split(".").pop();
+            if (!ext)
+                return;
+            if (query.has("pick") && ["js", "jsx", "ts", "tsx"].includes(ext)) {
+                const transformed = await transform(id, code);
+                if (!transformed?.code)
+                    return;
+                return {
+                    code: transformed.code,
+                    map: transformed.map
+                };
+            }
+        }
+    };
+}

package/dist/vite/types.d.ts

@@ -0,0 +1,10 @@
+import type { RouteManifestEntry } from "../manifest.ts";
+import type { RouteTreeEntry } from "../tree.ts";
+/**
+ * Builds the ambient declaration for `moduleId`. It is self-contained and
+ * replaces `filesystem-routing/types` — reference one or the other, never
+ * both, or TypeScript sees two declarations of the same module.
+ */
+export declare function serializeTypes(moduleId: string, routes: readonly RouteManifestEntry[], pageRoutes: readonly RouteTreeEntry[], 
+/** Directory the declaration is written to; module specifiers are relative to it. */
+from: string): string;