stx-router 0.2.415 → 0.2.416

package/dist/file-requests.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Does this request path ask for a file? True when its last segment ends in
+ * one of {@link FILE_REQUEST_EXTENSIONS} (all-lowercase or all-uppercase).
+ * Query strings and fragments are ignored; `/` and extensionless paths are
+ * never files.
+ */
+export declare function isFileRequestPath(pathname: string): boolean;
+/**
+ * Which request paths ask for a FILE rather than a page.
+ *
+ * An app whose routes start at the root has a dynamic page answering every
+ * one-segment path: `resources/views/[username].stx` renders a profile at
+ * `/chris`. Without a rule, it also answers `/favicon.ico`,
+ * `/apple-touch-icon.png`, `/robots.txt` on a site without one, and every
+ * `/wp-login.php` a scanner tries - each a full page render (often one that
+ * queries the database for a user called `favicon.ico`) shipped back as 80KB
+ * of HTML a browser expected to be an image.
+ *
+ * The rule: when the LAST segment of a request path ends in a known file
+ * extension, a dynamic page segment (`[param]`, `[[param]]`) never captures
+ * it. The request falls through to `publicDir`, and when nothing is there it
+ * gets a plain `404 Not Found` instead of a page.
+ *
+ * Why a list of known extensions rather than "anything after a dot":
+ *
+ *   - Identifiers carry dots. A username `john.doe`, a repository `three.js`
+ *     or `user.github.io`, a version `/docs/v1.2` or `/releases/1.0.0` are
+ *     all pages. Only an extension that names a file format nobody would use
+ *     as a name counts, and TLD-shaped ones (`.io`, `.dev`, `.sh`, `.me`,
+ *     `.app`, `.ai`) are deliberately absent.
+ *   - Page extensions stay routable: `.html`/`.htm` (the explicit spelling of
+ *     a page), and `.md`/`.stx` (a docs page addressed by its source name).
+ *   - Extensions are matched all-lowercase or all-uppercase (`.png`, `.PNG`),
+ *     which is how files are actually named, and keeps the guard expressible
+ *     in a case-sensitive route regex.
+ *
+ * Catch-alls (`[...path]`) are exempt on purpose. A catch-all is how an app
+ * says "the rest of the URL is mine, dots and all": a code browser serving
+ * `/owner/repo/tree/main/src/index.ts`, a docs site addressing `guide.md`.
+ * They still never shadow a file that really exists under `publicDir` (the
+ * serve path checks the disk first). That exemption is also the escape hatch:
+ * a segment that must accept file-shaped names (`[owner]/[repository]` for a
+ * repository called `three.js`) can be written as a catch-all.
+ *
+ * @module file-requests
+ */
+/**
+ * File extensions that mark a request as a file, never a page. Lowercase; see
+ * {@link isFileRequestPath} for how case is handled.
+ */
+export declare const FILE_REQUEST_EXTENSIONS: readonly string[];
+/**
+ * Regex source for a lookahead that refuses a final path segment naming a
+ * file. Placed in front of a dynamic segment's capture group, so the route
+ * regex itself - the one the server matches with and ships to the client
+ * router as an owned route - carries the rule. Non-capturing: group indices
+ * are unchanged.
+ */
+export declare const FILE_SEGMENT_GUARD: `(?![^/]*\\.(?:${alternation})$)`;

package/dist/file-requests.js

@@ -0,0 +1,99 @@
+export const FILE_REQUEST_EXTENSIONS = Object.freeze([
+  "ico",
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "avif",
+  "svg",
+  "bmp",
+  "tif",
+  "tiff",
+  "heic",
+  "css",
+  "js",
+  "mjs",
+  "cjs",
+  "map",
+  "wasm",
+  "webmanifest",
+  "json",
+  "xml",
+  "txt",
+  "rss",
+  "atom",
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "eot",
+  "mp3",
+  "mp4",
+  "m4a",
+  "m4v",
+  "mov",
+  "webm",
+  "ogg",
+  "ogv",
+  "oga",
+  "wav",
+  "flac",
+  "avi",
+  "mkv",
+  "pdf",
+  "csv",
+  "doc",
+  "docx",
+  "xls",
+  "xlsx",
+  "ppt",
+  "pptx",
+  "rtf",
+  "odt",
+  "zip",
+  "gz",
+  "tgz",
+  "tar",
+  "rar",
+  "7z",
+  "bz2",
+  "xz",
+  "php",
+  "phtml",
+  "asp",
+  "aspx",
+  "jsp",
+  "cgi",
+  "env",
+  "ini",
+  "yml",
+  "yaml",
+  "toml",
+  "sql",
+  "bak",
+  "old",
+  "swp",
+  "log",
+  "conf",
+  "cfg",
+  "exe",
+  "dmg",
+  "pkg",
+  "apk",
+  "ipa",
+  "msi",
+  "iso",
+  "bin",
+  "dll"
+]);
+const alternation = FILE_REQUEST_EXTENSIONS.flatMap((ext) => ext === ext.toUpperCase() ? [ext] : [ext, ext.toUpperCase()]).join("|"), FILE_SEGMENT = new RegExp(`\\.(?:${alternation})$`);
+export const FILE_SEGMENT_GUARD = `(?![^/]*\\.(?:${alternation})$)`;
+export function isFileRequestPath(pathname) {
+  let path = pathname;
+  const cut = path.search(/[?#]/);
+  if (cut !== -1)
+    path = path.slice(0, cut);
+  const last = path.slice(path.lastIndexOf("/") + 1);
+  return last.length > 0 && FILE_SEGMENT.test(last);
+}

package/dist/file-router.js

@@ -65,7 +65,7 @@ export class Router {
         if (seenPatterns.has(identity))
           continue;
         seenPatterns.add(identity);
-        const { regex, params } = patternToRegex(pattern), layouts = config.layouts !== !1 ? resolveLayoutChain(filePath, dir) : [];
+        const { regex, params } = patternToRegex(pattern, { page: !0 }), layouts = config.layouts !== !1 ? resolveLayoutChain(filePath, dir) : [];
         this.routes.push({
           pattern,
           regex,

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export type { PatternToRegexOptions } from './matcher';
 export type { LayoutMetadata } from './layout-metadata';
 // Types
 export type {
@@ -24,6 +25,8 @@ export type {
 export { createRouter, findErrorPage, formatRoutes, Router } from './file-router';
 // Route pattern matching
 export { bracketPathToRegex, filePathToPattern, matchRoute, patternToRegex } from './matcher';
+// Which request paths ask for a file, never a page
+export { FILE_REQUEST_EXTENSIONS, FILE_SEGMENT_GUARD, isFileRequestPath } from './file-requests';
 // Named routes
 export { defineRoute, defineRoutes, resetRoutes, route, setAppUrl } from './named-routes';
 // Middleware system

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createRouter, findErrorPage, formatRoutes, Router } from "./file-router.js";
 export { bracketPathToRegex, filePathToPattern, matchRoute, patternToRegex } from "./matcher.js";
+export { FILE_REQUEST_EXTENSIONS, FILE_SEGMENT_GUARD, isFileRequestPath } from "./file-requests.js";
 export { defineRoute, defineRoutes, resetRoutes, route, setAppUrl } from "./named-routes.js";
 export {
   abortNavigation,

package/dist/matcher.d.ts

@@ -1,21 +1,5 @@
 export declare function filePathToPattern(filePath: string, pagesDir: string): string;
-/**
- * Compile a route pattern into a regex and the parameter names its capture
- * groups correspond to.
- *
- * Single left-to-right pass, which is the whole point. Doing it as three
- * successive `.replace()` sweeps - optional, then catch-all, then required -
- * collects the names in *sweep* order while the capture groups end up in
- * *pattern* order, and the two disagree the moment one pattern mixes kinds.
- *
- * `/:owner/:repository/tree/:ref/:path*` collected as
- * `[path, owner, repository, ref]` against groups `(owner)(repository)(ref)(path)`,
- * so every value was bound to the wrong name: a repository browser given a URL
- * showed the root of a repository named after the branch. Nothing errored -
- * the regex matched and the page rendered - which is why it reads as a routing
- * mystery rather than an off-by-one.
- */
-export declare function patternToRegex(pattern: string): { regex: RegExp, params: string[] };
+export declare function patternToRegex(pattern: string, options?: PatternToRegexOptions): { regex: RegExp, params: string[] };
 export declare function matchRoute(pathname: string, routes: { pattern: string, regex: RegExp, params: string[] }[]): { route: typeof routes[0], params: Record<string, string> } | null;
 /**
  * Compile a *file-style* route path - the one with `[param]` brackets - into a
@@ -35,4 +19,23 @@ export declare function matchRoute(pathname: string, routes: { pattern: string,
  *
  * Exported so nothing has to write those two lines again.
  */
-export declare function bracketPathToRegex(routePath: string): { regex: RegExp, params: string[] };
+export declare function bracketPathToRegex(routePath: string, options?: PatternToRegexOptions): { regex: RegExp, params: string[] };
+/**
+ * Compile a route pattern into a regex and the parameter names its capture
+ * groups correspond to.
+ *
+ * Single left-to-right pass, which is the whole point. Doing it as three
+ * successive `.replace()` sweeps - optional, then catch-all, then required -
+ * collects the names in *sweep* order while the capture groups end up in
+ * *pattern* order, and the two disagree the moment one pattern mixes kinds.
+ *
+ * `/:owner/:repository/tree/:ref/:path*` collected as
+ * `[path, owner, repository, ref]` against groups `(owner)(repository)(ref)(path)`,
+ * so every value was bound to the wrong name: a repository browser given a URL
+ * showed the root of a repository named after the branch. Nothing errored -
+ * the regex matched and the page rendered - which is why it reads as a routing
+ * mystery rather than an off-by-one.
+ */
+export declare interface PatternToRegexOptions {
+  page?: boolean
+}

package/dist/matcher.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { FILE_SEGMENT_GUARD } from "./file-requests.js";
 export function filePathToPattern(filePath, pagesDir) {
   let route = path.relative(pagesDir, filePath).replace(/\.(stx|md)$/, "");
   route = route.split(path.sep).join("/");
@@ -11,14 +12,15 @@ export function filePathToPattern(filePath, pagesDir) {
   route = route.replace(/:\.\.\.([^/]+)/g, ":$1*");
   return `/${route}`;
 }
-export function patternToRegex(pattern) {
-  const params = [];
+export function patternToRegex(pattern, options = {}) {
+  const guard = options.page ? FILE_SEGMENT_GUARD : "", params = [];
   let regexStr = "", i = 0;
   while (i < pattern.length) {
     const rest = pattern.slice(i), optional = /^\/:([^/?*]+)\?/.exec(rest);
     if (optional) {
       params.push(optional[1]);
-      regexStr += "(?:/([^/]+))?";
+      const last = i + optional[0].length === pattern.length;
+      regexStr += `(?:/${last ? guard : ""}([^/]+))?`;
       i += optional[0].length;
       continue;
     }
@@ -32,7 +34,8 @@ export function patternToRegex(pattern) {
     const required = /^:([^/?*]+)/.exec(rest);
     if (required) {
       params.push(required[1]);
-      regexStr += "([^/]+)";
+      const last = i + required[0].length === pattern.length;
+      regexStr += `${last ? guard : ""}([^/]+)`;
       i += required[0].length;
       continue;
     }
@@ -55,7 +58,7 @@ export function matchRoute(pathname, routes) {
   }
   return null;
 }
-export function bracketPathToRegex(routePath) {
+export function bracketPathToRegex(routePath, options = {}) {
   const pattern = routePath.replace(/\[\[([^\]]+)\]\]/g, ":$1?").replace(/\[([^\]]+)\]/g, ":$1").replace(/:\.\.\.([^/]+)/g, ":$1*");
-  return patternToRegex(pattern);
+  return patternToRegex(pattern, options);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stx-router",
   "type": "module",
-  "version": "0.2.415",
+  "version": "0.2.416",
   "description": "File-based router for STX — .stx template discovery, nested layouts, typed route params, middleware, and client-side SPA navigation.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",