filesystem-routing 0.4.0 → 0.4.2

package/README.md

@@ -165,7 +165,8 @@ pages get:
 
 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:
+`(request, next)` or `(event, next)` chain, an SSR handler's middleware option
+(`@solidjs/vite-plugin`'s `start.middleware`) included:
 
 ```ts
 // src/middleware.ts
@@ -175,7 +176,8 @@ import { createAPIHandler } from "filesystem-routing/api";
 export default [createAPIHandler(routes)];
 ```
 
-Handlers receive the request event of the surrounding scope (the storage
+Handlers receive the event the chain passes in or, in a `(request, next)`
+chain, 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

package/dist/api.d.ts

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * middleware, so API routes compose into any `(request, next)` or
+ * `(event, 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`.
@@ -69,7 +69,8 @@ export interface APIHandlerOptions {
     base?: string;
     /**
      * How the adapter reaches the request event it hands to handlers. Defaults
-     * to the core request-event scope (the storage `provideRequestEvent`
+     * to the event the chain passes in or, when it passes a bare `Request`, 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.
      */
@@ -85,12 +86,18 @@ export interface APIHandlerOptions {
  * export default [createAPIHandler(routes)];
  * ```
  *
+ * The first argument is the request or a request event carrying it
+ * (`event.request`), so the handler fits `(request, next)` and
+ * `(event, next)` chains alike; it calls `next()` without arguments.
+ *
  * 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
+ * allowed for `GET` and `HEAD` 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>;
+export declare function createAPIHandler(routes: readonly FileRouteHandlers[], options?: APIHandlerOptions): (input: Request | {
+    request: Request;
+}, next: (request?: Request) => Response | Promise<Response>) => Promise<Response>;

package/dist/api.js

@@ -62,8 +62,8 @@ 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), " +
+        throw new Error("API route dispatched outside a request-event scope. Pass the request event " +
+            "instead of the request, compose the handler inside `provideRequestEvent`, " +
             "or pass `getEvent`.");
     }
     return event;
@@ -85,18 +85,22 @@ function toResponse(result) {
  * export default [createAPIHandler(routes)];
  * ```
  *
+ * The first argument is the request or a request event carrying it
+ * (`event.request`), so the handler fits `(request, next)` and
+ * `(event, next)` chains alike; it calls `next()` without arguments.
+ *
  * 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
+ * allowed for `GET` and `HEAD` 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) => {
+    return async (input, next) => {
+        const request = "request" in input ? input.request : input;
         const url = new URL(request.url);
         const matched = match(stripPathBase(url.pathname, options.base ?? "/"), request.method);
         if (!matched)
@@ -105,12 +109,12 @@ export function createAPIHandler(routes, options = {}) {
         const fn = request.method === "HEAD" ? mod.HEAD || mod.GET : mod[request.method];
         if (typeof fn !== "function")
             return next();
-        const event = getEvent();
+        const event = options.getEvent?.() ?? ("request" in input ? input : getScopedEvent());
         event.params = matched.params || {};
         const result = await fn(event);
         if (result !== undefined)
             return toResponse(result);
-        if (request.method !== "GET") {
+        if (request.method !== "GET" && request.method !== "HEAD") {
             throw new Error(`API handler for ${request.method} "${request.url}" did not return a response.`);
         }
         if (!matched.isPage)

package/dist/convention.js

@@ -12,8 +12,9 @@ export function routePathFromFile(routeFile) {
     const routePath = routeFile
         // remove the initial slash
         .slice(1)
-        // only strip a whole `index` segment, not a name that merely ends in "index" (e.g. `reindex`)
-        .replace(/(^|\/)index$/, "$1")
+        // only strip a whole `index` segment, not a name that merely ends in "index" (e.g. `reindex`);
+        // group prefixes such as SolidBase's `(0)index` ordering stay for the adapters to strip
+        .replace(/(^|\/)((?:\([^/()]*\))*)index$/, "$1$2")
         .replace(/\[([^/]+)\]/g, (_, m) => {
         if (m.length > 3 && m.startsWith("...")) {
             return `*${m.slice(3)}`;

package/dist/router.d.ts

@@ -38,14 +38,21 @@ export declare function cleanPath(src: string, config: FileSystemRouterConfig):
  */
 export declare class BaseFileSystemRouter extends EventTarget {
     routes: RouteManifestEntry[];
+    /** Source file that first produced each route path, so incremental changes keep scan order. */
+    private sources;
     config: FileSystemRouterConfig;
+    /**
+     * Route path each source file produced. A removed file can no longer be
+     * passed to `toRoute`, and `toPath` may give another file's route.
+     */
+    private routePaths;
     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(route: RouteManifestEntry, src?: string): boolean;
     addRoute(src: string): Promise<void>;
     reload(route: string, type: "update" | "remove" | "add"): void;
     updateRoute(src_: string): Promise<void>;

package/dist/router.js

@@ -20,7 +20,14 @@ export function cleanPath(src, config) {
  */
 export class BaseFileSystemRouter extends EventTarget {
     routes;
+    /** Source file that first produced each route path, so incremental changes keep scan order. */
+    sources = new Map();
     config;
+    /**
+     * Route path each source file produced. A removed file can no longer be
+     * passed to `toRoute`, and `toPath` may give another file's route.
+     */
+    routePaths = new Map();
     constructor(config) {
         super();
         this.routes = [];
@@ -54,12 +61,28 @@ export class BaseFileSystemRouter extends EventTarget {
             return this.config.toRoute(src, this);
         throw new Error("Not implemented");
     }
-    _addRoute(route) {
+    _addRoute(route, src) {
         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;
+        if (idx >= 0) {
+            // Replace in place: an edited file keeps its position. The source that
+            // first produced the path still decides it, as in a full scan.
+            this.routes[idx] = route;
+            return true;
+        }
+        if (src !== undefined)
+            this.sources.set(route.path, src);
+        // A new file goes where a full scan would put it.
+        const at = src === undefined
+            ? -1
+            : this.routes.findIndex(r => {
+                const other = this.sources.get(r.path);
+                return other !== undefined && other > src;
+            });
+        if (at === -1)
+            this.routes.push(route);
+        else
+            this.routes.splice(at, 0, route);
+        return false;
     }
     async addRoute(src) {
         src = normalizePath(src);
@@ -67,7 +90,10 @@ export class BaseFileSystemRouter extends EventTarget {
             try {
                 const route = this.toRoute(src);
                 if (route) {
-                    this._addRoute(route);
+                    if (this.routePaths.get(src) !== route.path)
+                        this.removeRoute(src);
+                    this._addRoute(route, src);
+                    this.routePaths.set(src, route.path);
                     this.reload(route.path, "add");
                 }
             }
@@ -90,7 +116,10 @@ export class BaseFileSystemRouter extends EventTarget {
             try {
                 const route = this.toRoute(src);
                 if (route) {
-                    const updated = this._addRoute(route);
+                    if (this.routePaths.get(src) !== route.path)
+                        this.removeRoute(src_);
+                    const updated = this._addRoute(route, src);
+                    this.routePaths.set(src, route.path);
                     this.reload(route.path, updated ? "update" : "add");
                 }
                 else {
@@ -104,17 +133,16 @@ export class BaseFileSystemRouter extends EventTarget {
     }
     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");
-        }
+        const path = this.routePaths.get(src);
+        if (path === undefined)
+            return;
+        this.routePaths.delete(src);
+        const idx = this.routes.findIndex(r => r.path === path);
+        if (idx === -1)
+            return;
+        this.routes.splice(idx, 1);
+        this.sources.delete(path);
+        this.reload(path, "remove");
     }
     on(type, cb) {
         this.addEventListener(type, cb);

package/dist/tree.js

@@ -20,8 +20,10 @@ export function buildRouteTree(entries) {
         }
         processRoute(parentRoute.children || (parentRoute.children = []), route, id.slice(parentRoute.id.length));
     }
+    // Ties break by UTF-16 code unit, as the scan sorts files, not by
+    // `localeCompare`: the generated output must not depend on the machine's locale.
     return [...entries]
-        .sort((a, b) => (a.path.length - b.path.length) || a.path.localeCompare(b.path))
+        .sort((a, b) => a.path.length - b.path.length || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
         .reduce((routes, route) => {
         processRoute(routes, route, route.path);
         return routes;

package/dist/vite/index.js

@@ -21,6 +21,15 @@ const HANDLER_REF = /^\$[A-Z]+$/;
  * own default: the `client` environment is the one client consumer.
  */
 const isServerConsumer = (name, consumer) => (consumer ?? (name === "client" ? "client" : "server")) === "server";
+/**
+ * The id a route module ref is loaded from: its source plus its picks. On the
+ * server a server page's module is loaded whole, because the server-function
+ * handler imports it whole too, and a second (picked) instance would register
+ * the page's server function twice.
+ */
+const toModuleId = (route, ref, serverConsumer) => serverConsumer && route.server === true && ref.src === route.$component?.src
+    ? ref.src
+    : toPickId(ref.src, ref.pick);
 /**
  * The client's view of a shared server manifest: handler refs removed. A
  * client bundle can never invoke a request handler, but serializing its ref
@@ -106,8 +115,6 @@ export function fileRoutes(options = {}) {
         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) => toPickId(ref.src, ref.pick);
     return [
         {
             name: "filesystem-routing",
@@ -161,7 +168,8 @@ export function fileRoutes(options = {}) {
                 // A client environment on the shared router never serializes
                 // handler refs (see load), so their modules must not become its
                 // build entries either.
-                const routes = options.routers?.[name] || isServerConsumer(name, _config.consumer)
+                const serverConsumer = isServerConsumer(name, _config.consumer);
+                const routes = options.routers?.[name] || serverConsumer
                     ? await router.getRoutes()
                     : stripHandlerRefs(await router.getRoutes());
                 // Every code-split route module is an entry of its own, so the
@@ -171,7 +179,7 @@ export function fileRoutes(options = {}) {
                 for (const route of routes) {
                     for (const [key, ref] of Object.entries(route)) {
                         if (ref && key.startsWith("$") && !key.startsWith("$$") && !ref.eager) {
-                            input.push(toModuleId(ref));
+                            input.push(toModuleId(route, ref, serverConsumer));
                         }
                     }
                 }
@@ -204,19 +212,19 @@ export function fileRoutes(options = {}) {
                 const environmentName = this.environment.name;
                 const router = getRouter(environmentName);
                 let routes = (router ? await router.getRoutes() : []) ?? [];
+                const serverConsumer = isServerConsumer(environmentName, this.environment.config.consumer);
                 // The shared router serves every environment, so the split is this
                 // adapter's job: client consumers get the manifest without handler
                 // refs. An explicit per-environment router already IS the split —
                 // serve whatever it emits.
-                if (!options.routers?.[environmentName] &&
-                    !isServerConsumer(environmentName, this.environment.config.consumer)) {
+                if (!options.routers?.[environmentName] && !serverConsumer) {
                     routes = stripHandlerRefs(routes);
                 }
                 const serializeEntry = (entry) => JSON.stringify(entry, (key, value) => {
                     if (value === undefined)
                         return undefined;
                     if (key.startsWith("$$")) {
-                        const buildId = toModuleId(value);
+                        const buildId = toModuleId(entry, value, serverConsumer);
                         const refs = {};
                         for (const pick of value.pick) {
                             refs[pick] = js.addNamedImport(pick, buildId);
@@ -228,7 +236,7 @@ export function fileRoutes(options = {}) {
                         };
                     }
                     else if (key.startsWith("$")) {
-                        const buildId = toModuleId(value);
+                        const buildId = toModuleId(entry, value, serverConsumer);
                         // With code splitting off — or a ref the convention marked
                         // `eager` — the ref is delivered eagerly: a namespace import
                         // (named imports would fail on the synthetic `$css` pick)

package/dist/vite/types.js

@@ -47,19 +47,22 @@ const REF_TYPES = `  /** A code-split ref: the delivery adapter emits it as a dy
 /** Extensions TypeScript can resolve through a `typeof import(...)`. */
 const TYPED_MODULE = /\.([mc]?[jt]sx?)$/;
 /**
- * Types a ref by the module it points at, so a page's `default` really is the
- * component and a `route` export really is the config the module declares —
- * which is what saves an emission adapter from casting either one. Modules
- * TypeScript cannot resolve (`.md`, `.mdx`) fall back to the generic ref.
+ * Types a ref by its picked exports, keeping the module's `default` and
+ * `route` types so an emission adapter can read either without a cast.
+ * Modules TypeScript cannot resolve (`.md`, `.mdx`) fall back to the generic ref.
  */
 function refType(ref, kind, from) {
     const name = kind === "eager" ? "FileRouteEagerRef" : "FileRouteLazyRef";
     if (!TYPED_MODULE.test(ref.src))
         return name;
+    const picks = ref.pick.filter(pick => pick !== "$css").map(pick => JSON.stringify(pick));
+    if (!picks.length)
+        return name;
     let specifier = normalizePath(relative(from, ref.src)).replace(TYPED_MODULE, "");
     if (!specifier.startsWith("."))
         specifier = `./${specifier}`;
-    return `${name}<typeof import(${JSON.stringify(specifier)})>`;
+    const moduleType = `typeof import(${JSON.stringify(specifier)})`;
+    return `${name}<Pick<${moduleType}, Extract<${picks.join(" | ")}, keyof ${moduleType}>>>`;
 }
 const isLazyRefKey = (key) => key.startsWith("$") && !key.startsWith("$$");
 const isEagerRefKey = (key) => key.startsWith("$$");

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.4.0",
+  "version": "0.4.2",
   "author": "Ryan Carniato",
   "homepage": "https://github.com/solidjs/filesystem-routing#readme",
   "repository": {