@jay-framework/stack-route-scanner 0.25.1 → 0.25.2

package/dist/index.d.mts

@@ -33,6 +33,24 @@ type JayRoute = {
     devOnly?: boolean;
 };
 type JayRoutes = JayRoute[];
+/**
+ * A reserved top-level error-page folder (Design Log #218). `pages/404/`, `pages/5xx/`, etc. are
+ * not routable; they are collected here instead of in {@link JayRoutes}.
+ */
+type JayErrorPage = {
+    /** HTTP status token: exact (`404`, `502`) or family (`4xx`, `5xx`). */
+    token: string;
+    jayHtmlPath: string;
+    compPath: string;
+};
+type JayErrorPages = JayErrorPage[];
+/** Result of a route scan: navigable routes plus reserved error pages (DL#218). */
+interface ScanResult {
+    routes: JayRoutes;
+    errorPages: JayErrorPages;
+}
+/** True when a top-level folder name is a reserved HTTP status token (DL#218). */
+declare function isStatusToken(name: string): boolean;
 interface ScanFilesOptions {
     jayHtmlFilename: string;
     compFilename: string;
@@ -55,8 +73,13 @@ declare function createRoute(routePath: string, jayHtmlPath: string, compPath: s
     devOnly?: boolean;
     clientCompPath?: string;
 }): JayRoute;
-declare function scanRoutes(baseDir: string, options: ScanFilesOptions): Promise<JayRoutes>;
+/**
+ * Scan a pages directory for navigable routes and reserved error pages (DL#218).
+ *
+ * Returns `{ routes, errorPages }`. Callers that only need routes destructure `{ routes }`.
+ */
+declare function scanRoutes(baseDir: string, options: ScanFilesOptions): Promise<ScanResult>;
 
 declare function routeToExpressRoute(route: JayRoute): string;
 
-export { type JayRoute, type JayRouteParam, JayRouteParamType, type JayRouteSegment, type JayRoutes, type ScanFilesOptions, createRoute, parseRouteSegments, routeToExpressRoute, scanRoutes, sortRoutesByPriority };
+export { type JayErrorPage, type JayErrorPages, type JayRoute, type JayRouteParam, JayRouteParamType, type JayRouteSegment, type JayRoutes, type ScanFilesOptions, type ScanResult, createRoute, isStatusToken, parseRouteSegments, routeToExpressRoute, scanRoutes, sortRoutesByPriority };

package/dist/index.mjs

@@ -9,6 +9,10 @@ var JayRouteParamType = /* @__PURE__ */ ((JayRouteParamType2) => {
   JayRouteParamType2[JayRouteParamType2["optional"] = 2] = "optional";
   return JayRouteParamType2;
 })(JayRouteParamType || {});
+const STATUS_TOKEN = /^([1-5][0-9]{2}|[1-5]xx)$/;
+function isStatusToken(name) {
+  return STATUS_TOKEN.test(name);
+}
 const PARSE_PARAM = /^\[(\[)?(\.\.\.)?([^\]]+)\]?\]$/;
 function convertToRoutePath(BASE_DIR, jayHtmlPath, { jayHtmlFilename, compFilename }) {
   let rawRoute = jayHtmlPath.replace(BASE_DIR, "").replace(`/${jayHtmlFilename}`, "").replace("\\", "/");
@@ -29,14 +33,22 @@ function convertToRoutePath(BASE_DIR, jayHtmlPath, { jayHtmlFilename, compFilena
   return { segments, jayHtmlPath, compPath, rawRoute };
 }
 const IGNORED_DIRS = /* @__PURE__ */ new Set(["build", "node_modules", "dist", ".git"]);
-async function scanDirectory(BASE_DIR, directory, options) {
+async function scanDirectory(BASE_DIR, directory, options, depth = 0) {
   let routes = [];
+  let errorPages = [];
   const items = await promises.readdir(directory, { withFileTypes: true });
   for (const item of items) {
     const fullPath = path.join(directory, item.name);
     if (item.isDirectory()) {
       if (IGNORED_DIRS.has(item.name)) continue;
-      routes = [...routes, ...await scanDirectory(BASE_DIR, fullPath, options)];
+      if (depth === 0 && isStatusToken(item.name)) {
+        const errorPage = toErrorPage(item.name, fullPath, options);
+        if (errorPage) errorPages.push(errorPage);
+        continue;
+      }
+      const nested = await scanDirectory(BASE_DIR, fullPath, options, depth + 1);
+      routes = [...routes, ...nested.routes];
+      errorPages = [...errorPages, ...nested.errorPages];
     } else if (item.name === options.jayHtmlFilename) {
       const route = convertToRoutePath(BASE_DIR, fullPath, options);
       const { params, validations } = await parseHeadlessProps(fullPath);
@@ -69,7 +81,14 @@ async function scanDirectory(BASE_DIR, directory, options) {
       routes.push(route);
     }
   }
-  return routes;
+  return { routes, errorPages };
+}
+function toErrorPage(token, folderPath, { jayHtmlFilename, compFilename }) {
+  const jayHtmlPath = path.join(folderPath, jayHtmlFilename);
+  if (!existsSync(jayHtmlPath)) return void 0;
+  const candidateCompPath = path.join(folderPath, compFilename);
+  const compPath = existsSync(candidateCompPath) ? candidateCompPath : "";
+  return { token, jayHtmlPath, compPath };
 }
 function getSegmentPriority(segment) {
   if (typeof segment === "string") return 0;
@@ -174,7 +193,7 @@ function createRoute(routePath, jayHtmlPath, compPath, componentExport, options)
 }
 async function scanRoutes(baseDir, options) {
   const BASE_DIR = path.resolve(baseDir);
-  const routes = await scanDirectory(BASE_DIR, BASE_DIR, options);
+  const { routes, errorPages } = await scanDirectory(BASE_DIR, BASE_DIR, options);
   const sortedRoutes = sortRoutesByPriority(routes);
   const routesWithParams = sortedRoutes.filter((r) => r.inferredParams);
   if (routesWithParams.length > 0) {
@@ -183,7 +202,7 @@ async function scanRoutes(baseDir, options) {
       getLogger().info(`  ${route.rawRoute} → ${JSON.stringify(route.inferredParams)}`);
     }
   }
-  return sortedRoutes;
+  return { routes: sortedRoutes, errorPages };
 }
 function routeToExpressRoute(route) {
   const parts = [];
@@ -203,6 +222,7 @@ function routeToExpressRoute(route) {
 export {
   JayRouteParamType,
   createRoute,
+  isStatusToken,
   parseRouteSegments,
   routeToExpressRoute,
   scanRoutes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-route-scanner",
-  "version": "0.25.1",
+  "version": "0.25.2",
   "license": "Apache-2.0",
   "main": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -9,7 +9,7 @@
     "readme.md"
   ],
   "dependencies": {
-    "@jay-framework/logger": "^0.25.1",
+    "@jay-framework/logger": "^0.25.2",
     "node-html-parser": "^6.1.12",
     "yaml": "^2.3.4"
   },
@@ -25,7 +25,7 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.25.1",
+    "@jay-framework/dev-environment": "^0.25.2",
     "@types/node": "^20.11.5",
     "nodemon": "^3.0.3",
     "replace-in-file": "^7.1.0",