create-jen-app 1.2.1 → 1.2.3

package/templates/static/lib/core/middleware-hooks.js

@@ -16,54 +16,99 @@
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
 /**
- * Note: Route module types (middleware, hydrate fields) are defined in core/types.ts
- * This module just provides the middleware execution primitives.
+ * Type definitions note:
+ * Route module types (middleware field, hydrate field) are defined in core/types.ts.
+ * This module provides the middleware execution engine and context object.
  */
 /**
- * Create middleware context from request.
- * Called by server before rendering route.
+ * Creates a middleware context object from request data.
+ * Called by the renderer before executing route middleware.
+ *
+ * Initializes:
+ * - All request data (req, res, url, params, query, headers, cookies)
+ * - Empty data object for middleware to populate
+ * - Helper methods (status, setHeader, redirect, json) as chainable methods
+ *
+ * @param opts Configuration with raw request data
+ * @param opts.req Node.js IncomingMessage
+ * @param opts.res Node.js ServerResponse
+ * @param opts.url Parsed URL from request
+ * @param opts.params Route parameters from URL path
+ * @param opts.query Query string parameters
+ * @param opts.headers Normalized headers object
+ * @param opts.cookies Parsed cookies from Cookie header
+ *
+ * @returns Initialized RouteMiddlewareContext ready for middleware execution
  */
 export function createRouteMiddlewareContext(opts) {
-    const ctx = {
-        ...opts,
-        data: {},
-        status: function (code) {
-            this.res.statusCode = code;
-            return this;
-        },
-        setHeader: function (key, value) {
-            this.res.setHeader(key, value);
-            return this;
-        },
-        redirect: function (url, statusCode = 302) {
-            this.res.statusCode = statusCode;
-            this.res.setHeader("location", url);
-            this.res.end();
-            throw new Error("__REDIRECT__");
-        },
-        json: function (data, statusCode = 200) {
-            this.res.statusCode = statusCode;
-            this.res.setHeader("content-type", "application/json; charset=utf-8");
-            this.res.end(JSON.stringify(data));
-            throw new Error("__JSON__");
-        },
-    };
-    return ctx;
+  const ctx = {
+    ...opts,
+    data: {},
+    status: function (code) {
+      this.res.statusCode = code;
+      return this;
+    },
+    setHeader: function (key, value) {
+      this.res.setHeader(key, value);
+      return this;
+    },
+    redirect: function (url, statusCode = 302) {
+      this.res.statusCode = statusCode;
+      this.res.setHeader("location", url);
+      this.res.end();
+      throw new Error("__REDIRECT__");
+    },
+    json: function (data, statusCode = 200) {
+      this.res.statusCode = statusCode;
+      this.res.setHeader("content-type", "application/json; charset=utf-8");
+      this.res.end(JSON.stringify(data));
+      throw new Error("__JSON__");
+    },
+  };
+  return ctx;
 }
 /**
- * Execute route middlewares in sequence.
- * If any middleware calls redirect() or json(), it throws and stops execution.
+ * Executes an array of route middleware sequentially for a route.
+ *
+ * Execution model:
+ * 1. Iterates through middlewares in order
+ * 2. Each middleware is awaited (even if synchronous)
+ * 3. Middleware can populate ctx.data for use by loader and page
+ * 4. If middleware calls ctx.redirect() or ctx.json(), error is caught and re-thrown
+ * 5. Other errors are propagated immediately
+ *
+ * Control flow:
+ * - Normal completion: all middlewares finish and function returns
+ * - Early exit: middleware calls ctx.redirect() or ctx.json()
+ * - Error: middleware throws or ctx.redirect()/json() throws sentinel error
+ *
+ * Side effects:
+ * - Response headers, status, and body may be sent by middleware
+ * - ctx.data may be modified by middleware
+ * - Should only be called in server context (SSR); not during SSG build
+ *
+ * @param middlewares Array of middleware functions to execute
+ * @param ctx RouteMiddlewareContext created by createRouteMiddlewareContext()
+ *
+ * @returns Promise that resolves if all middlewares complete normally
+ * @throws Error with message "__REDIRECT__" if middleware calls ctx.redirect()
+ * @throws Error with message "__JSON__" if middleware calls ctx.json()
+ * @throws Error from middleware if it throws
  */
 export async function executeRouteMiddleware(middlewares, ctx) {
-    for (const mw of middlewares) {
-        try {
-            await mw(ctx);
-        }
-        catch (err) {
-            if (err.message === "__REDIRECT__" || err.message === "__JSON__") {
-                throw err;
-            }
-            throw err;
-        }
+  for (const mw of middlewares) {
+    try {
+      await mw(ctx);
+    } catch (err) {
+      /**
+       * Sentinel errors from ctx.redirect() and ctx.json() are re-thrown
+       * to signal that the response was already sent.
+       * Other errors propagate normally for error handling middleware.
+       */
+      if (err.message === "__REDIRECT__" || err.message === "__JSON__") {
+        throw err;
+      }
+      throw err;
     }
+  }
 }

package/templates/static/lib/core/paths.d.ts

@@ -1,6 +1,44 @@
-export declare function resolveSitePath(config: {
+/**
+ * Resolve an absolute path relative to the configured site directory.
+ * Used throughout the framework to locate source files, assets, pages, and other site content.
+ *
+ * The site directory is typically where user-written code (pages, routes, components, etc.) resides.
+ * This function ensures consistent path resolution across different environments and working directories.
+ *
+ * @param config Framework configuration object containing the siteDir path.
+ * @param p Path segments to join with the site directory. Can be multiple arguments.
+ * @returns Absolute file system path.
+ *
+ * @example
+ * const config = { siteDir: 'src' };
+ * resolveSitePath(config, 'pages', 'index.tsx');
+ * // Returns: /absolute/path/to/project/src/pages/index.tsx
+ */
+export declare function resolveSitePath(
+  config: {
     siteDir: string;
-}, ...p: string[]): string;
-export declare function resolveDistPath(config: {
+  },
+  ...p: string[]
+): string;
+/**
+ * Resolve an absolute path relative to the configured distribution/build output directory.
+ * Used to locate compiled assets, static files, and build artifacts.
+ *
+ * The distribution directory contains the output of the build process: compiled HTML,
+ * CSS, JavaScript bundles, and other files ready for deployment or serving.
+ *
+ * @param config Framework configuration object containing the distDir path.
+ * @param p Path segments to join with the dist directory. Can be multiple arguments.
+ * @returns Absolute file system path.
+ *
+ * @example
+ * const config = { distDir: 'dist' };
+ * resolveDistPath(config, 'styles.css');
+ * // Returns: /absolute/path/to/project/dist/styles.css
+ */
+export declare function resolveDistPath(
+  config: {
     distDir: string;
-}, ...p: string[]): string;
+  },
+  ...p: string[]
+): string;

package/templates/static/lib/core/paths.js

@@ -16,9 +16,41 @@
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
 import { join } from "node:path";
+/**
+ * Resolve an absolute path relative to the configured site directory.
+ * Used throughout the framework to locate source files, assets, pages, and other site content.
+ *
+ * The site directory is typically where user-written code (pages, routes, components, etc.) resides.
+ * This function ensures consistent path resolution across different environments and working directories.
+ *
+ * @param config Framework configuration object containing the siteDir path.
+ * @param p Path segments to join with the site directory. Can be multiple arguments.
+ * @returns Absolute file system path.
+ *
+ * @example
+ * const config = { siteDir: 'src' };
+ * resolveSitePath(config, 'pages', 'index.tsx');
+ * // Returns: /absolute/path/to/project/src/pages/index.tsx
+ */
 export function resolveSitePath(config, ...p) {
-    return join(process.cwd(), config.siteDir, ...p);
+  return join(process.cwd(), config.siteDir, ...p);
 }
+/**
+ * Resolve an absolute path relative to the configured distribution/build output directory.
+ * Used to locate compiled assets, static files, and build artifacts.
+ *
+ * The distribution directory contains the output of the build process: compiled HTML,
+ * CSS, JavaScript bundles, and other files ready for deployment or serving.
+ *
+ * @param config Framework configuration object containing the distDir path.
+ * @param p Path segments to join with the dist directory. Can be multiple arguments.
+ * @returns Absolute file system path.
+ *
+ * @example
+ * const config = { distDir: 'dist' };
+ * resolveDistPath(config, 'styles.css');
+ * // Returns: /absolute/path/to/project/dist/styles.css
+ */
 export function resolveDistPath(config, ...p) {
-    return join(process.cwd(), config.distDir, ...p);
+  return join(process.cwd(), config.distDir, ...p);
 }

package/templates/static/lib/core/routes/match.d.ts

@@ -1,6 +1,54 @@
 import type { RouteEntry } from "./scan.js";
+/**
+ * Result of a successful route match operation.
+ * Contains the matched route and extracted URL parameters.
+ */
 export type MatchResult = {
-    route: RouteEntry;
-    params: Record<string, string>;
+  /**
+   * The route entry that matched the URL pathname.
+   * Includes all route metadata: file path, URL pattern, regex, parameter names.
+   */
+  route: RouteEntry;
+  /**
+   * Extracted URL parameters as key-value pairs.
+   * Keys correspond to parameter names from the route pattern.
+   * Values are URL-decoded strings extracted from the pathname.
+   *
+   * @example
+   * For route "/posts/:id" matching "/posts/42", yields { id: "42" }
+   * For route "/docs/*rest" matching "/docs/api/fetch", yields { rest: "api/fetch" }
+   */
+  params: Record<string, string>;
 };
-export declare function matchRoute(routes: RouteEntry[], pathname: string): MatchResult | null;
+/**
+ * Matches a URL pathname against a list of routes and returns the matching route with extracted parameters.
+ *
+ * Algorithm:
+ * 1. Iterate through routes in specificity order (most specific first)
+ * 2. For each route, compile its regex pattern and test against pathname
+ * 3. On first match, extract captured groups as parameters
+ * 4. URL-decode parameter values to handle special characters
+ * 5. Return matched route and parameters
+ *
+ * Route specificity:
+ * - Static routes (no parameters) are tried before dynamic routes
+ * - Exact matches are preferred over catch-alls
+ * - This order is determined by scanRoutes() and must not be changed
+ *
+ * @param routes Array of RouteEntry objects from scanRoutes(), must be pre-sorted by specificity
+ * @param pathname URL path to match, e.g., "/posts/42" or "/docs/api/reference"
+ *
+ * @returns MatchResult object with matched route and parameters, or null if no route matches
+ *
+ * @example
+ * const routes = scanRoutes(config);
+ * const match = matchRoute(routes, "/posts/42");
+ * if (match) {
+ *   console.log(match.route.urlPath);  // "/posts/:id"
+ *   console.log(match.params.id);       // "42"
+ * }
+ */
+export declare function matchRoute(
+  routes: RouteEntry[],
+  pathname: string,
+): MatchResult | null;

package/templates/static/lib/core/routes/match.js

@@ -15,17 +15,50 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
+/**
+ * Matches a URL pathname against a list of routes and returns the matching route with extracted parameters.
+ *
+ * Algorithm:
+ * 1. Iterate through routes in specificity order (most specific first)
+ * 2. For each route, compile its regex pattern and test against pathname
+ * 3. On first match, extract captured groups as parameters
+ * 4. URL-decode parameter values to handle special characters
+ * 5. Return matched route and parameters
+ *
+ * Route specificity:
+ * - Static routes (no parameters) are tried before dynamic routes
+ * - Exact matches are preferred over catch-alls
+ * - This order is determined by scanRoutes() and must not be changed
+ *
+ * @param routes Array of RouteEntry objects from scanRoutes(), must be pre-sorted by specificity
+ * @param pathname URL path to match, e.g., "/posts/42" or "/docs/api/reference"
+ *
+ * @returns MatchResult object with matched route and parameters, or null if no route matches
+ *
+ * @example
+ * const routes = scanRoutes(config);
+ * const match = matchRoute(routes, "/posts/42");
+ * if (match) {
+ *   console.log(match.route.urlPath);  // "/posts/:id"
+ *   console.log(match.params.id);       // "42"
+ * }
+ */
 export function matchRoute(routes, pathname) {
-    for (const r of routes) {
-        const re = new RegExp(r.pattern);
-        const m = pathname.match(re);
-        if (!m)
-            continue;
-        const params = {};
-        for (let i = 0; i < r.paramNames.length; i++) {
-            params[r.paramNames[i]] = decodeURIComponent(m[i + 1] ?? "");
-        }
-        return { route: r, params };
+  for (const r of routes) {
+    const re = new RegExp(r.pattern);
+    const m = pathname.match(re);
+    if (!m) continue;
+    /**
+     * Extract captured groups from the regex match.
+     * Captured group 0 is the entire match; groups 1+ are the parameters.
+     * Each parameter name from r.paramNames corresponds to its regex group by index.
+     * URL-decode parameter values since they came from a URL path.
+     */
+    const params = {};
+    for (let i = 0; i < r.paramNames.length; i++) {
+      params[r.paramNames[i]] = decodeURIComponent(m[i + 1] ?? "");
     }
-    return null;
+    return { route: r, params };
+  }
+  return null;
 }

package/templates/static/lib/core/routes/scan.d.ts

@@ -1,9 +1,53 @@
 import type { FrameworkConfig } from "../config.js";
+/**
+ * Represents a discovered route file with all metadata needed for routing and rendering.
+ * Created by scanRoutes() based on filesystem structure and file patterns.
+ */
 export type RouteEntry = {
-    id: string;
-    filePath: string;
-    urlPath: string;
-    pattern: string;
-    paramNames: string[];
+  /**
+   * Unique identifier for the route, derived from file path.
+   * Example: "posts_id_tsx" for "posts/(id).tsx"
+   */
+  id: string;
+  /**
+   * Absolute filesystem path to the route file.
+   * Examples: "/app/src/pages/(home).tsx", "/app/src/posts/($id).tsx"
+   */
+  filePath: string;
+  /**
+   * URL path that this route should respond to.
+   * Dynamic segments use colon prefix for params and asterisk for catch-all.
+   * Examples: "/", "/about", "/posts/:id", "/docs/*rest"
+   */
+  urlPath: string;
+  /**
+   * Regular expression pattern for URL matching.
+   * Compiled from urlPath to enable fast route matching at request time.
+   * Example: "^/posts/([^/]+)/?$" for route "/posts/:id"
+   */
+  pattern: string;
+  /**
+   * Array of parameter names in order they appear in the URL pattern.
+   * Used to extract and name captured groups from route.pattern regex matches.
+   * Examples: ["id"] for "/posts/:id", ["rest"] for "/docs/*rest"
+   */
+  paramNames: string[];
 };
+/**
+ * Scans the configured siteDir for route files and returns an ordered list.
+ * Files are matched against config.routes.routeFilePattern (typically /^\(([^)]+)\)/).
+ * Only files with extensions in config.routes.fileExtensions are considered.
+ *
+ * Naming conventions:
+ * - (home).tsx => route "/" (root, or within its directory)
+ * - ($paramName).tsx => dynamic route "/:paramName" (requires $ prefix)
+ * - (...restName).tsx => catch-all route "/*restName" (requires ... prefix)
+ * - (name).tsx => literal route "/name"
+ *
+ * Routes are sorted by specificity: static routes first, then dynamic/catch-all.
+ *
+ * @param config Framework configuration with siteDir and route patterns
+ * @returns Array of RouteEntry objects, sorted by specificity (most specific first)
+ * @throws {Error} If a parameter name is invalid (e.g., starts with number)
+ */
 export declare function scanRoutes(config: FrameworkConfig): RouteEntry[];