webspresso 0.0.98 → 0.0.100

package/src/file-router.js

@@ -17,9 +17,166 @@ const {
   registerClearHook,
 } = require('./njk-frontmatter');
 const { renderStream } = require('../core/ssr/stream');
+const {
+  loadCascadingMiddlewares,
+  runMiddlewareChain,
+  findCascadingLayouts,
+  executeCascadingLayoutLoads,
+  applyCascadingLayouts,
+  findNearestErrorBoundary,
+  findNearestLoadingTemplate,
+  templateHasExtends,
+} = require('./routing/cascading');
+const {
+  isMiddlewareFactory,
+  resolveNamedMiddleware,
+  resolveMiddlewares,
+} = require('./routing/middleware-resolver');
 
 const NOOP = () => {};
 const EMPTY_OBJECT = Object.freeze({});
+
+/**
+ * Handles directory-level error boundaries (_error.njk and companion _error.js)
+ * @returns {Promise<boolean>} True if rendered, false if unhandled
+ */
+async function handleDirectoryErrorBoundary({
+  err,
+  route,
+  req,
+  res,
+  ctx,
+  absolutePagesDir,
+  nunjucks,
+  isDev,
+  compiledStringTemplateCache,
+  baseHelpers,
+}) {
+  if (res.headersSent) {
+    return false;
+  }
+
+  const errorBoundary = findNearestErrorBoundary(absolutePagesDir, route.file, isDev);
+  if (!errorBoundary) {
+    return false;
+  }
+
+  const statusCode =
+    err?.status ||
+    err?.statusCode ||
+    (typeof err?.getStatus === 'function' ? err.getStatus() : null) ||
+    500;
+
+  try {
+    let errorData = {};
+    let errorConfig = null;
+
+    if (errorBoundary.configPath) {
+      try {
+        if (isDev && require.cache[require.resolve(errorBoundary.configPath)]) {
+          delete require.cache[require.resolve(errorBoundary.configPath)];
+        }
+        const mod = require(errorBoundary.configPath);
+        errorConfig = mod?.default || mod;
+        const loadFn = typeof errorConfig === 'function' ? errorConfig : errorConfig?.load;
+        if (typeof loadFn === 'function') {
+          const loaded = await loadFn({
+            req,
+            res,
+            error: err,
+            ctx,
+            db: req.db,
+          });
+          if (loaded && typeof loaded === 'object' && !Array.isArray(loaded)) {
+            Object.assign(errorData, loaded);
+          }
+        }
+      } catch (loadErr) {
+        console.error(`[webspresso] Error in _error.js loader "${errorBoundary.configPath}":`, loadErr.message);
+      }
+    }
+
+    const njkTpl = loadNjkRouteTemplate(errorBoundary.fullPath, isDev);
+    if (njkTpl.dataPatch && Object.keys(njkTpl.dataPatch).length > 0) {
+      Object.assign(errorData, njkTpl.dataPatch);
+    }
+
+    const errorRenderContext = {
+      ...(ctx?.data || {}),
+      ...errorData,
+      error: {
+        message: err?.message || 'An error occurred',
+        status: statusCode,
+        statusCode,
+        code: err?.code || 'ERROR',
+        name: err?.name || 'Error',
+        details: err?.details,
+        fields: err?.fields,
+        stack: isDev ? err?.stack : undefined,
+      },
+      route: {
+        routePath: route.routePath,
+        file: route.file,
+      },
+      meta: Object.assign({}, ctx?.meta, {
+        title: errorData.title || `Error ${statusCode}`,
+        description: errorData.description || err?.message,
+      }),
+      locale: ctx?.locale,
+      t: ctx?.t,
+      fsy: ctx?.fsy || (typeof createHelpers === 'function' ? createHelpers({ req, res, locale: ctx?.locale || 'en' }) : {}),
+      clientRuntime: ctx?.clientRuntime,
+      req: {
+        path: req.path,
+        query: req.query,
+        params: req.params,
+        method: req.method,
+        url: req.url,
+      },
+      isDev,
+    };
+
+    let html;
+    if (njkTpl.useStringRender && njkTpl.templateBody != null) {
+      if (typeof nunjucks.Template === 'function') {
+        let compiled = isDev ? null : compiledStringTemplateCache.get(errorBoundary.fullPath);
+        if (!compiled || (isDev && compiled._templateBody !== njkTpl.templateBody)) {
+          compiled = new nunjucks.Template(njkTpl.templateBody, nunjucks, errorBoundary.fullPath);
+          compiled._templateBody = njkTpl.templateBody;
+          compiledStringTemplateCache.set(errorBoundary.fullPath, compiled);
+        }
+        html = compiled.render(errorRenderContext);
+      } else if (typeof nunjucks.renderString === 'function') {
+        html = nunjucks.renderString(njkTpl.templateBody, errorRenderContext, { path: errorBoundary.fullPath });
+      } else {
+        html = nunjucks.render(errorBoundary.errorRelPath, errorRenderContext);
+      }
+    } else {
+      html = nunjucks.render(errorBoundary.errorRelPath, errorRenderContext);
+    }
+
+    const shouldApplyLayout = errorConfig?.layout !== false &&
+      errorData?.layout !== false &&
+      !templateHasExtends(njkTpl.templateBody, errorBoundary.fullPath);
+
+    if (shouldApplyLayout) {
+      const errorLayouts = findCascadingLayouts(absolutePagesDir, errorBoundary.errorRelPath, isDev);
+      if (errorLayouts.length > 0) {
+        const layoutCtx = { data: { ...errorRenderContext } };
+        await executeCascadingLayoutLoads(errorLayouts, req, layoutCtx, isDev);
+        const mergedLayoutContext = { ...errorRenderContext, ...(layoutCtx.data || {}) };
+        html = applyCascadingLayouts(nunjucks, errorLayouts, html, mergedLayoutContext, isDev);
+      }
+    }
+
+    res.status(statusCode);
+    res.send(html);
+    return true;
+  } catch (renderErr) {
+    console.error(`[webspresso] Failed rendering error boundary "${errorBoundary.errorRelPath}":`, renderErr);
+    return false;
+  }
+}
 const EMPTY_ARRAY = Object.freeze([]);
 
 // Cache for i18n files (key: filePath, value: { mtime, data })
@@ -173,6 +330,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 +410,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 +1097,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 +1220,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 +1356,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 +1514,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 +1541,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);
@@ -1434,15 +1603,26 @@ function mountPages(app, options) {
         
         // Render the template
         const templatePath = route.file.split(path.sep).join('/');
+        const nearestLoading = findNearestLoadingTemplate(absolutePagesDir, route.file, isDev);
+        if (nearestLoading) {
+          renderContext.loadingTemplate = nearestLoading.loadingRelPath;
+        }
 
         // SSR Streaming mode (chunked transfer)
-        if (config?.stream || ctx.data?.__stream || ctx.defer) {
-          const streamDefer = ctx.defer || ctx.data?.__defer || {};
+        if (config?.stream || ctx.data?.__stream || ctx.data?.stream || ctx.defer || ctx.data?.defer) {
+          const streamDefer = ctx.defer || ctx.data?.defer || ctx.data?.__defer || {};
           const status = (route.routePath === '/404' || route.file === '404.njk') ? 404 : 200;
+          const shouldApplyLayout = config?.layout !== false &&
+            ctx.data?.layout !== false &&
+            ctx.meta?.layout !== false &&
+            !templateHasExtends(njkTpl.templateBody, route.fullPath);
+
           return await renderStream(res, templatePath, renderContext, {
             env: nunjucks,
             defer: streamDefer,
             status,
+            loadingTemplate: nearestLoading?.loadingRelPath,
+            layouts: shouldApplyLayout && cascadingLayouts.length > 0 ? cascadingLayouts : undefined,
           });
         }
 
@@ -1465,6 +1645,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) {
@@ -1485,13 +1675,27 @@ function mountPages(app, options) {
         console.error(`SSR error ${route.routePath}:`, err);
         
         // Execute onError hook
-        const ctx = { req, res, error: err };
+        const hookCtx = { req, res, error: err };
         try {
-          await executeHook(globalHooks, 'onError', ctx, err);
+          await executeHook(globalHooks, 'onError', hookCtx, err);
         } catch (hookErr) {
           console.error('Error in onError hook:', hookErr);
         }
         
+        const handled = await handleDirectoryErrorBoundary({
+          err,
+          route,
+          req,
+          res,
+          ctx: req.context || hookCtx,
+          absolutePagesDir,
+          nunjucks,
+          isDev,
+          compiledStringTemplateCache,
+        });
+
+        if (handled) return;
+
         return next(err);
       }
     });
@@ -1535,6 +1739,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');
         }
@@ -285,7 +294,13 @@ class AssetManager {
     }
 
     if (routePath) {
-      let cleanPath = String(routePath).trim().replace(/^\/+/, '').replace(/\/+$/, '');
+      let cleanPath = String(routePath).trim();
+      while (cleanPath.startsWith('/')) {
+        cleanPath = cleanPath.slice(1);
+      }
+      while (cleanPath.endsWith('/')) {
+        cleanPath = cleanPath.slice(0, -1);
+      }
       if (cleanPath) {
         candidates.add(cleanPath);
         if (cleanPath.includes(':')) {

package/src/njk-frontmatter.js

@@ -83,6 +83,9 @@ function frontmatterToPatches(fm) {
   if (d && typeof d === 'object' && !Array.isArray(d)) {
     dataPatch = { ...d };
   }
+  if (Object.prototype.hasOwnProperty.call(fmObj, 'layout') && fmObj.layout !== undefined) {
+    dataPatch.layout = fmObj.layout;
+  }
 
   return { metaPatch, dataPatch };
 }