webspresso 0.0.98 → 0.0.99

package/src/discovery/file-route-parser.js

@@ -158,8 +158,11 @@ function parseFileRoute(relativePath, options = {}) {
   // Replace last segment with cleanFilename
   const routeSegments = [...segments.slice(0, -1), cleanFilename];
 
+  // Filter out route group segments (e.g. (marketing), (auth))
+  const filteredSegments = routeSegments.filter((seg) => !isRouteGroupSegment(seg));
+
   // Process dynamic brackets in segments
-  const transformedSegments = routeSegments.map(transformDynamicSegment);
+  const transformedSegments = filteredSegments.map(transformDynamicSegment);
 
   // Handle 'index' at the end of path
   if (transformedSegments[transformedSegments.length - 1] === 'index') {
@@ -190,8 +193,48 @@ function parseFileRoute(relativePath, options = {}) {
   };
 }
 
+/**
+ * Checks if a path segment is a route group, e.g. '(marketing)', '(auth)'
+ * @param {string} segment
+ * @returns {boolean}
+ */
+function isRouteGroupSegment(segment) {
+  return (
+    typeof segment === 'string' &&
+    segment.length > 2 &&
+    segment.charCodeAt(0) === 40 /* '(' */ &&
+    segment.charCodeAt(segment.length - 1) === 41 /* ')' */
+  );
+}
+
+/**
+ * Checks if a file path belongs to an API route, accounting for optional parent route groups.
+ * E.g., 'api/users.get.js' -> true
+ *       'api/(v1)/users.get.js' -> true
+ *       '(marketing)/api/newsletter.post.js' -> true
+ *       'about.njk' -> false
+ * @param {string} file
+ * @returns {boolean}
+ */
+function isApiRouteFile(file) {
+  if (!file || typeof file !== 'string') return false;
+  const normalized = file.split(/[/\\]/).join('/');
+  if (normalized.startsWith('api/')) return true;
+  const parts = normalized.split('/');
+  const apiIndex = parts.indexOf('api');
+  if (apiIndex > 0) {
+    const prefix = parts.slice(0, apiIndex);
+    if (prefix.every(isRouteGroupSegment)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 module.exports = {
   parseFileRoute,
+  isRouteGroupSegment,
+  isApiRouteFile,
   isPrivateOrIgnored,
   normalizePrefix,
   transformDynamicSegment,

package/src/discovery/scan-routes.js

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { parseFileRoute, isPrivateOrIgnored } = require('./file-route-parser');
+const { parseFileRoute, isPrivateOrIgnored, isApiRouteFile } = require('./file-route-parser');
 const { discoverModuleDetails } = require('../modules/module-discovery');
 
 const SUPPORTED_EXTENSIONS = new Set(['.js', '.njk']);
@@ -99,7 +99,7 @@ function scanRoutes(options = {}) {
         }
 
         // Skip api directory inside pages (handled by classic mountPages or explicit api scan)
-        const isUnderApi = relativePath.startsWith('api' + path.sep) || relativePath.startsWith('api/');
+        const isUnderApi = isApiRouteFile(relativePath);
         if (isUnderApi) {
           continue;
         }

package/src/file-router.js

@@ -17,6 +17,19 @@ const {
   registerClearHook,
 } = require('./njk-frontmatter');
 const { renderStream } = require('../core/ssr/stream');
+const {
+  loadCascadingMiddlewares,
+  runMiddlewareChain,
+  findCascadingLayouts,
+  executeCascadingLayoutLoads,
+  applyCascadingLayouts,
+  templateHasExtends,
+} = require('./routing/cascading');
+const {
+  isMiddlewareFactory,
+  resolveNamedMiddleware,
+  resolveMiddlewares,
+} = require('./routing/middleware-resolver');
 
 const NOOP = () => {};
 const EMPTY_OBJECT = Object.freeze({});
@@ -173,6 +186,73 @@ function escapeRegExp(s) {
   return String(s).replace(/[\\^$*+?.()|[\]{}]/g, '\\$&');
 }
 
+/**
+ * Checks if a path segment is a route group, e.g. '(marketing)', '(auth)'.
+ * Route groups are enclosed in parentheses and do not affect the public URL path.
+ * @param {string} segment
+ * @returns {boolean}
+ */
+function isRouteGroupSegment(segment) {
+  return (
+    typeof segment === 'string' &&
+    segment.length > 2 &&
+    segment.charCodeAt(0) === 40 /* '(' */ &&
+    segment.charCodeAt(segment.length - 1) === 41 /* ')' */
+  );
+}
+
+/**
+ * Strips route group segments from a slash-separated route path.
+ * E.g., '(marketing)/about' -> 'about'
+ *       '/(auth)/login' -> '/login'
+ *       '/(marketing)/(sub)/page' -> '/page'
+ *       '(marketing)/index' -> 'index'
+ * @param {string} route
+ * @returns {string}
+ */
+function stripRouteGroups(route) {
+  if (!route || typeof route !== 'string' || !route.includes('(')) {
+    return route;
+  }
+  const hadLeadingSlash = route.startsWith('/');
+  const rawSegments = route.split('/');
+  const filtered = rawSegments.filter((seg) => !isRouteGroupSegment(seg));
+
+  if (filtered.length === 0 || (filtered.length === 1 && filtered[0] === '')) {
+    return hadLeadingSlash ? '/' : '';
+  }
+
+  let res = filtered.join('/');
+  if (hadLeadingSlash && !res.startsWith('/')) {
+    res = '/' + res;
+  }
+  return res;
+}
+
+/**
+ * Checks if a file path belongs to an API route, accounting for optional parent route groups.
+ * E.g., 'api/users.get.js' -> true
+ *       'api/(v1)/users.get.js' -> true
+ *       '(marketing)/api/newsletter.post.js' -> true
+ *       'about.njk' -> false
+ * @param {string} file
+ * @returns {boolean}
+ */
+function isApiRouteFile(file) {
+  if (!file || typeof file !== 'string') return false;
+  const normalized = file.split(/[/\\]/).join('/');
+  if (normalized.startsWith('api/')) return true;
+  const parts = normalized.split('/');
+  const apiIndex = parts.indexOf('api');
+  if (apiIndex > 0) {
+    const prefix = parts.slice(0, apiIndex);
+    if (prefix.every(isRouteGroupSegment)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Convert a file path to an Express route pattern
  * @param {string} filePath - Relative path from pages/
@@ -186,11 +266,14 @@ function filePathToRoute(filePath, ext) {
   // Normalize path separators to forward slashes (handle both / and \)
   route = route.split(path.sep).join('/');
   route = route.split('\\').join('/'); // Also handle literal backslashes
+
+  // Strip route group segments (e.g. (marketing), (auth), (dashboard))
+  route = stripRouteGroups(route);
   
   // Handle index files
   if (route.endsWith('/index')) {
     route = route.slice(0, -6) || '/';
-  } else if (route === 'index') {
+  } else if (route === 'index' || route === '') {
     route = '/';
   }
   
@@ -870,86 +953,6 @@ function detectLocale(req, supported = parseSupportedLocaleSet(), def = getDefau
   return def;
 }
 
-/**
- * True when the registry entry is (options) => (req, res, next) => …
- * Express handlers typically have length >= 2 (req, res) or 3 (req, res, next).
- */
-function isMiddlewareFactory(fn) {
-  return typeof fn === 'function' && fn.length <= 1;
-}
-
-/**
- * Resolve a named middleware from createApp({ middlewares }).
- * @param {string} name
- * @param {Function} entry
- * @param {boolean} fromTuple - true when route used ['name', options]
- * @param {unknown} tupleOptions - second element of the tuple (only when fromTuple)
- * @param {Object} middlewareRegistry - for error messages
- * @returns {Function} Express middleware
- */
-function resolveNamedMiddleware(name, entry, fromTuple, tupleOptions, middlewareRegistry) {
-  if (!entry) {
-    throw new Error(`Middleware "${name}" not found in registry. Available: ${Object.keys(middlewareRegistry).join(', ') || 'none'}`);
-  }
-  if (typeof entry !== 'function') {
-    throw new Error(`Middleware "${name}" must be a function`);
-  }
-
-  if (fromTuple) {
-    if (!isMiddlewareFactory(entry)) {
-      throw new Error(
-        `Middleware "${name}" must be a factory (options) => (req, res, next) => … when using ["${name}", options] tuple form`
-      );
-    }
-    const produced = entry(tupleOptions);
-    if (typeof produced !== 'function') {
-      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
-    }
-    return produced;
-  }
-
-  if (isMiddlewareFactory(entry)) {
-    const produced = entry({});
-    if (typeof produced !== 'function') {
-      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
-    }
-    return produced;
-  }
-
-  return entry;
-}
-
-/**
- * Resolve middleware from config — functions, string names, or [name, options] tuples
- * @param {Array} middlewareConfig - middleware functions, names, or ['name', options] tuples
- * @param {Object} middlewareRegistry - Named middleware registry (plain handlers or option factories)
- * @returns {Array} Array of resolved middleware functions
- */
-function resolveMiddlewares(middlewareConfig, middlewareRegistry = EMPTY_OBJECT) {
-  if (!middlewareConfig || !Array.isArray(middlewareConfig) || middlewareConfig.length === 0) {
-    return EMPTY_ARRAY;
-  }
-  
-  return middlewareConfig.map((mw, index) => {
-    if (typeof mw === 'function') {
-      return mw;
-    }
-    
-    if (typeof mw === 'string') {
-      return resolveNamedMiddleware(mw, middlewareRegistry[mw], false, undefined, middlewareRegistry);
-    }
-
-    if (Array.isArray(mw) && mw.length === 2 && typeof mw[0] === 'string') {
-      const name = mw[0];
-      return resolveNamedMiddleware(name, middlewareRegistry[name], true, mw[1], middlewareRegistry);
-    }
-    
-    throw new Error(
-      `Invalid middleware at index ${index}: must be a function, string name, or [name, options] tuple`
-    );
-  });
-}
-
 /**
  * Mount all pages as routes on the Express app
  * @param {Object} app - Express app
@@ -1073,7 +1076,7 @@ function mountPages(app, options) {
   
   for (const file of files) {
     const ext = path.extname(file);
-    const isApi = file.startsWith('api' + path.sep) || file.startsWith('api/');
+    const isApi = isApiRouteFile(file);
     
     if (isApi && ext === '.js') {
       // API route
@@ -1209,19 +1212,32 @@ function mountPages(app, options) {
             throw err;
           }
           
+          // Run cascading folder middlewares (_middleware.js)
+          const cascadingMw = loadCascadingMiddlewares(absolutePagesDir, route.file, middlewares, isDev);
+          if (cascadingMw.length) {
+            await runMiddlewareChain(cascadingMw, req, res);
+            if (res.headersSent) return;
+          }
+
           // Run middleware if defined (resolved at route registration — required for stateful middleware like express-rate-limit)
           if (preResolvedMw.length) {
-            for (const mw of preResolvedMw) {
-              await new Promise((resolve, reject) => {
-                mw(req, res, (err) => {
-                  if (err) reject(err);
-                  else resolve();
-                });
-              });
-            }
+            await runMiddlewareChain(preResolvedMw, req, res);
+            if (res.headersSent) return;
           }
-          
-          await fn(req, res, next);
+          const apiCtx = Object.assign((err) => next(err), {
+            req,
+            res,
+            next,
+            params: req.params || {},
+            query: req.query || {},
+            body: req.body || {},
+            input: req.input,
+            service: req.service,
+            db,
+            sse: res.sse,
+          });
+
+          await fn(req, res, apiCtx);
         } catch (err) {
           console.error(`API error ${route.routePath}:`, err);
           const hookCtx = { req, res, error: err };
@@ -1354,16 +1370,17 @@ function mountPages(app, options) {
         hookPromise = runHooks(globalHooks, routeHooks, 'beforeMiddleware', ctx);
         if (hookPromise) await hookPromise;
         
+        // Run cascading folder middlewares (_middleware.js)
+        const cascadingMw = loadCascadingMiddlewares(absolutePagesDir, route.file, middlewares, isDev);
+        if (cascadingMw.length) {
+          await runMiddlewareChain(cascadingMw, req, res);
+          if (res.headersSent) return;
+        }
+
         // Run route middleware (chain fixed at route registration; edit middleware in dev → restart)
         if (preResolvedPageMw.length) {
-          for (const mw of preResolvedPageMw) {
-            await new Promise((resolve, reject) => {
-              mw(req, res, (err) => {
-                if (err) reject(err);
-                else resolve();
-              });
-            });
-          }
+          await runMiddlewareChain(preResolvedPageMw, req, res);
+          if (res.headersSent) return;
         }
         
         // Execute hooks: afterMiddleware
@@ -1380,6 +1397,14 @@ function mountPages(app, options) {
         hookPromise = runHooks(globalHooks, routeHooks, 'beforeLoad', ctx);
         if (hookPromise) await hookPromise;
         
+        // Find cascading layouts (_layout.njk)
+        const cascadingLayouts = findCascadingLayouts(absolutePagesDir, route.file, isDev);
+
+        // Run cascading _layout.js load() functions in top-down order (outermost first)
+        if (cascadingLayouts.length > 0) {
+          await executeCascadingLayoutLoads(cascadingLayouts, req, ctx, isDev);
+        }
+
         // Run load function
         if (config?.load && typeof config.load === 'function') {
           const loadData = await config.load(req, ctx);
@@ -1465,6 +1490,16 @@ function mountPages(app, options) {
           html = nunjucks.render(templatePath, renderContext);
         }
 
+        // Apply cascading nested layouts if not opted-out and template does not extend another template
+        const shouldApplyLayout = config?.layout !== false &&
+          ctx.data?.layout !== false &&
+          ctx.meta?.layout !== false &&
+          !templateHasExtends(njkTpl.templateBody, route.fullPath);
+
+        if (shouldApplyLayout && cascadingLayouts.length > 0) {
+          html = applyCascadingLayouts(nunjucks, cascadingLayouts, html, renderContext, isDev);
+        }
+
         if (pluginManager) {
           const contentApi = pluginManager.getPluginAPI('content');
           if (contentApi?.maybeInjectInlineEdit) {
@@ -1535,6 +1570,8 @@ module.exports = {
   mountPages,
   filePathToRoute,
   extractMethodFromFilename,
+  isRouteGroupSegment,
+  stripRouteGroups,
   scanDirectory,
   loadI18n,
   createTranslator,

package/src/helpers.js

@@ -278,6 +278,15 @@ class AssetManager {
             candidates.add(staticParts.join('/'));
           }
         }
+        if (cleanFile.includes('(')) {
+          const withoutGroups = cleanFile.split('/').filter(p => !(p.startsWith('(') && p.endsWith(')'))).join('/');
+          if (withoutGroups) {
+            candidates.add(withoutGroups);
+            if (withoutGroups.endsWith('/index')) {
+              candidates.add(withoutGroups.slice(0, -6));
+            }
+          }
+        }
         if (cleanFile === 'index') {
           candidates.add('home');
         }