create-jen-app 1.2.1 → 1.2.3

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

@@ -17,132 +17,191 @@
  */
 import { readdirSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
+/**
+ * Recursively walks a directory and returns all file paths.
+ * Used to discover all potential route files in the siteDir.
+ *
+ * @param dir Directory path to walk
+ * @returns Flat array of all file paths found, relative or absolute as provided
+ */
 function walk(dir) {
-    const out = [];
-    for (const name of readdirSync(dir)) {
-        const p = join(dir, name);
-        const st = statSync(p);
-        if (st.isDirectory())
-            out.push(...walk(p));
-        else
-            out.push(p);
-    }
-    return out;
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) out.push(...walk(p));
+    else out.push(p);
+  }
+  return out;
 }
+/**
+ * Normalizes filesystem path separators to forward slashes.
+ * Ensures consistent path format across Windows and Unix systems.
+ *
+ * @param p Path with possibly mixed separators
+ * @returns Path with forward slashes only
+ */
 function normalizeSlashes(p) {
-    return p.split(sep).join("/");
+  return p.split(sep).join("/");
 }
+/**
+ * Escapes special regex characters in a string.
+ * Prevents literal characters from being interpreted as regex syntax.
+ *
+ * @param s String to escape
+ * @returns Escaped string safe for regex
+ */
 function escapeRegex(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/**
+ * Converts a URL path segment to a regex pattern.
+ * Handles dynamic parameters (:id) and catch-alls (*rest).
+ * Side effect: appends parameter names to provided array.
+ *
+ * @param seg URL segment like "id", ":id", or "*rest"
+ * @param paramNames Array to accumulate discovered parameter names
+ * @returns Regex pattern for this segment
+ */
 function segmentToRegex(seg, paramNames) {
-    // (id) => ([^/]+)
-    // (...rest) => (.*)
-    if (seg.startsWith("...")) {
-        const name = seg.slice(3);
-        paramNames.push(name);
-        return "(.*)";
-    }
-    paramNames.push(seg);
-    return "([^/]+)";
+  // (id) => ([^/]+)
+  // (...rest) => (.*)
+  if (seg.startsWith("...")) {
+    const name = seg.slice(3);
+    paramNames.push(name);
+    return "(.*)";
+  }
+  paramNames.push(seg);
+  return "([^/]+)";
 }
+/**
+ * Converts a URL path string into a compiled regex pattern and parameter list.
+ * Handles static segments, dynamic parameters (:param), and catch-all routes (*rest).
+ *
+ * @param urlPath URL path like "/posts/:id" or "/docs/*rest"
+ * @returns Object with regex source string and ordered parameter names
+ *
+ * @example
+ * buildRoutePattern("/posts/:id") => {
+ *   src: "^/posts/([^/]+)/?$",
+ *   paramNames: ["id"]
+ * }
+ */
 function buildRoutePattern(urlPath) {
-    // Convert /user/:id into regex
-    // We store urlPath with placeholders already replaced during scan
-    const parts = urlPath.split("/").filter(Boolean);
-    const paramNames = [];
-    const regexParts = parts.map((p) => {
-        if (p.startsWith(":")) {
-            paramNames.push(p.slice(1));
-            return "([^/]+)";
-        }
-        if (p.startsWith("*")) {
-            paramNames.push(p.slice(1));
-            return "(.*)";
-        }
-        return escapeRegex(p);
-    });
-    const src = "^/" + regexParts.join("/") + "/?$";
-    return { src, paramNames };
+  // Convert /user/:id into regex
+  // We store urlPath with placeholders already replaced during scan
+  const parts = urlPath.split("/").filter(Boolean);
+  const paramNames = [];
+  const regexParts = parts.map((p) => {
+    if (p.startsWith(":")) {
+      paramNames.push(p.slice(1));
+      return "([^/]+)";
+    }
+    if (p.startsWith("*")) {
+      paramNames.push(p.slice(1));
+      return "(.*)";
+    }
+    return escapeRegex(p);
+  });
+  const src = "^/" + regexParts.join("/") + "/?$";
+  return { src, paramNames };
 }
+/**
+ * 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 function scanRoutes(config) {
-    const siteRoot = join(process.cwd(), config.siteDir);
-    const files = walk(siteRoot);
-    const routes = [];
-    for (const abs of files) {
-        const rel = normalizeSlashes(relative(siteRoot, abs));
-        const extMatch = config.routes.fileExtensions.some((ext) => rel.endsWith(ext));
-        if (!extMatch)
-            continue;
-        const base = rel.split("/").pop();
-        const m = base.match(config.routes.routeFilePattern);
-        if (!m)
-            continue;
-        const name = m[1]; // inside ( )
-        const relDir = rel.split("/").slice(0, -1).join("/");
-        // name parsing:
-        // home => /
-        // about => /about
-        // id => /:id
-        // ...rest => /*rest
-        let routeSeg = name;
-        let urlSeg = "";
-        if (routeSeg === "home")
-            urlSeg = "";
-        else if (routeSeg.startsWith("..."))
-            urlSeg = "*" + routeSeg.slice(3);
-        else
-            urlSeg = routeSeg;
-        // build url path
-        let url = "/" + (relDir ? relDir + "/" : "") + urlSeg;
-        url = url.replaceAll("//", "/");
-        // Dynamic route segment detection:
-        // Routes are determined by the filename within parentheses
-        // - (home).tsx => / (root) or /{dir}/ (in subdirectory)
-        // - ($paramName).tsx => /:paramName (dynamic param, requires $ prefix)
-        // - (...restName).tsx => /*restName (catch-all, requires ... prefix)
-        // - Any other (name).tsx => /name (literal segment)
-        const rawName = name;
-        // Handle special prefixes for dynamic routing
-        if (rawName.startsWith("$") && !rawName.startsWith("...")) {
-            // ($paramName) syntax for dynamic parameters
-            const param = rawName.slice(1);
-            if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param)) {
-                throw new Error(`Invalid parameter name: ${param} in route file ${rel}`);
-            }
-            url = "/" + (relDir ? relDir + "/" : "") + ":" + param;
-            url = url.replaceAll("//", "/");
-        }
-        else if (rawName.startsWith("...")) {
-            // (...restName) syntax for catch-all routes
-            const restName = rawName.slice(3);
-            if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(restName)) {
-                throw new Error(`Invalid rest parameter name: ${restName} in route file ${rel}`);
-            }
-            url = "/" + (relDir ? relDir + "/" : "") + "*" + restName;
-            url = url.replaceAll("//", "/");
-        }
-        else if (rawName === "home") {
-            // (home) is special - becomes root of its directory
-            url = relDir === "" ? "/" : "/" + relDir;
-        }
-        // else: (anything else) treated as literal segment
-        const { src, paramNames } = buildRoutePattern(url);
-        routes.push({
-            id: rel.replaceAll("/", "_"),
-            filePath: abs,
-            urlPath: url,
-            pattern: src,
-            paramNames,
-        });
+  const siteRoot = join(process.cwd(), config.siteDir);
+  const files = walk(siteRoot);
+  const routes = [];
+  for (const abs of files) {
+    const rel = normalizeSlashes(relative(siteRoot, abs));
+    const extMatch = config.routes.fileExtensions.some((ext) =>
+      rel.endsWith(ext),
+    );
+    if (!extMatch) continue;
+    const base = rel.split("/").pop();
+    const m = base.match(config.routes.routeFilePattern);
+    if (!m) continue;
+    const name = m[1]; // inside ( )
+    const relDir = rel.split("/").slice(0, -1).join("/");
+    // name parsing:
+    // home => /
+    // about => /about
+    // id => /:id
+    // ...rest => /*rest
+    let routeSeg = name;
+    let urlSeg = "";
+    if (routeSeg === "home") urlSeg = "";
+    else if (routeSeg.startsWith("...")) urlSeg = "*" + routeSeg.slice(3);
+    else urlSeg = routeSeg;
+    // build url path
+    let url = "/" + (relDir ? relDir + "/" : "") + urlSeg;
+    url = url.replaceAll("//", "/");
+    /**
+     * Dynamic route segment detection based on filename within parentheses.
+     * Routes are determined by the filename prefix conventions:
+     * - (home).tsx => / (root) or /{dir}/ (in subdirectory)
+     * - ($paramName).tsx => /:paramName (dynamic param, requires $ prefix)
+     * - (...restName).tsx => /*restName (catch-all, requires ... prefix)
+     * - Any other (name).tsx => /name (literal segment)
+     */
+    const rawName = name;
+    // Handle special prefixes for dynamic routing
+    if (rawName.startsWith("$") && !rawName.startsWith("...")) {
+      // ($paramName) syntax for dynamic parameters
+      const param = rawName.slice(1);
+      if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param)) {
+        throw new Error(
+          `Invalid parameter name: ${param} in route file ${rel}`,
+        );
+      }
+      url = "/" + (relDir ? relDir + "/" : "") + ":" + param;
+      url = url.replaceAll("//", "/");
+    } else if (rawName.startsWith("...")) {
+      // (...restName) syntax for catch-all routes
+      const restName = rawName.slice(3);
+      if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(restName)) {
+        throw new Error(
+          `Invalid rest parameter name: ${restName} in route file ${rel}`,
+        );
+      }
+      url = "/" + (relDir ? relDir + "/" : "") + "*" + restName;
+      url = url.replaceAll("//", "/");
+    } else if (rawName === "home") {
+      // (home) is special - becomes root of its directory
+      url = relDir === "" ? "/" : "/" + relDir;
     }
-    routes.sort((a, b) => {
-        // more specific first
-        const aDyn = a.urlPath.includes(":") || a.urlPath.includes("*");
-        const bDyn = b.urlPath.includes(":") || b.urlPath.includes("*");
-        if (aDyn !== bDyn)
-            return aDyn ? 1 : -1;
-        return a.urlPath.localeCompare(b.urlPath);
+    // else: (anything else) treated as literal segment
+    const { src, paramNames } = buildRoutePattern(url);
+    routes.push({
+      id: rel.replaceAll("/", "_"),
+      filePath: abs,
+      urlPath: url,
+      pattern: src,
+      paramNames,
     });
-    return routes;
+  }
+  // Sort by specificity: exact matches and static routes first, dynamic routes last
+  routes.sort((a, b) => {
+    // more specific first
+    const aDyn = a.urlPath.includes(":") || a.urlPath.includes("*");
+    const bDyn = b.urlPath.includes(":") || b.urlPath.includes("*");
+    if (aDyn !== bDyn) return aDyn ? 1 : -1;
+    return a.urlPath.localeCompare(b.urlPath);
+  });
+  return routes;
 }

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

@@ -1,18 +1,153 @@
 import type { RenderMode } from "./config.js";
+/**
+ * Exported interface that every route module (TSX/JSX file in siteDir) must conform to.
+ * Route modules define the page content, metadata, data loading, and rendering behavior.
+ *
+ * @example
+ * ```typescript
+ * import type { RouteModule } from "jenjs";
+ *
+ * export const mode = "ssg"; // Pre-render at build time
+ * export const revalidateSeconds = 3600; // Revalidate every hour for ISR
+ *
+ * export const loader = async (ctx) => {
+ *   return { posts: await fetchPosts() };
+ * };
+ *
+ * export function Head() {
+ *   return <title>My Page</title>;
+ * }
+ *
+ * export default function Page({ data, params }) {
+ *   return <div>Welcome!</div>;
+ * }
+ * ```
+ */
 export type RouteModule = {
-    mode?: RenderMode;
-    revalidateSeconds?: number;
-    hydrate?: boolean;
-    middleware?: any;
-    loader?: (ctx: LoaderContext) => Promise<any> | any;
-    Head?: (props: any) => any;
-    default: (props: any) => any;
+  /**
+   * Rendering mode for this route.
+   * If omitted, uses defaultMode from config.
+   *
+   * - "ssr": Server-side render on every request
+   * - "ssg": Pre-render once at build time
+   * - "isr": Pre-render, then revalidate on demand
+   * - "ppr": Partial pre-rendering (some sections static, some dynamic)
+   */
+  mode?: RenderMode;
+  /**
+   * For ISR routes, the time in seconds before cached page is considered stale.
+   * When a request comes to a stale page, it triggers a background revalidation.
+   * If omitted, uses defaultRevalidateSeconds from config.
+   *
+   * Example: 3600 = revalidate every hour
+   */
+  revalidateSeconds?: number;
+  /**
+   * Whether to inject hydration code and client-side JavaScript.
+   * Set to false for pure static HTML with no interactivity.
+   * Default: true (enables interactive components)
+   *
+   * Optimization: Static pages (false) have smaller payload and faster rendering.
+   */
+  hydrate?: boolean;
+  /**
+   * Route-level middleware functions that run before rendering.
+   * Can be a single middleware or array of middlewares.
+   * Executes on the server before loader is called.
+   * Can access request, set response headers, perform auth checks, etc.
+   *
+   * @see ../middleware-hooks.ts for RouteMiddleware interface
+   */
+  middleware?: any;
+  /**
+   * Data loading function called before rendering the page.
+   * Receives LoaderContext with URL, params, query, headers, cookies, and middleware data.
+   * Result is passed to the page component as `data` prop.
+   * Can be async (e.g., fetch from database or API).
+   *
+   * Only runs on the server (SSR/SSG), not on the client during hydration.
+   *
+   * @param ctx Loader context with request information
+   * @returns Data object merged with component props
+   */
+  loader?: (ctx: LoaderContext) => Promise<any> | any;
+  /**
+   * Optional Head component exported from route module.
+   * Renders into <head> section of the HTML document.
+   * Useful for meta tags, title, Open Graph tags, etc.
+   *
+   * Receives the same props as the default page component: { data, params, query }
+   *
+   * @example
+   * ```typescript
+   * export function Head({ params }) {
+   *   return <title>{params.id} - My Site</title>;
+   * }
+   * ```
+   */
+  Head?: (props: any) => any;
+  /**
+   * Required default export: the page component.
+   * Renders to HTML for SSR/SSG.
+   * Also used for client-side hydration if hydrate !== false.
+   *
+   * Receives props: { data, params, query }
+   *
+   * @example
+   * ```typescript
+   * export default function Page({ data, params, query }) {
+   *   return <main>{data?.title}</main>;
+   * }
+   * ```
+   */
+  default: (props: any) => any;
 };
+/**
+ * Context object passed to route loader functions.
+ * Contains all request-related data needed to load route data dynamically.
+ * Available in both SSR (runtime) and SSG (build-time) contexts.
+ */
 export type LoaderContext = {
-    url: URL;
-    params: Record<string, string>;
-    query: Record<string, string>;
-    headers: Record<string, string>;
-    cookies: Record<string, string>;
-    data?: Record<string, any>;
+  /**
+   * The full URL object for the current request.
+   * Includes pathname, search, searchParams, etc.
+   * @example new URL("http://example.com/posts?sort=date")
+   */
+  url: URL;
+  /**
+   * Named route parameters extracted from the URL path.
+   * For route /posts/:id, accessing /posts/42 yields { id: "42" }
+   * For catch-all routes /docs/...rest, yields { rest: "getting-started/setup" }
+   */
+  params: Record<string, string>;
+  /**
+   * Query string parameters from the URL search string.
+   * For URL /search?q=test&limit=10, yields { q: "test", limit: "10" }
+   * Always strings; parsing to numbers/booleans is the loader's responsibility.
+   */
+  query: Record<string, string>;
+  /**
+   * HTTP request headers as a flat object.
+   * Keys are lowercase; multiple header values are comma-separated.
+   * Not available during static site generation (SSG build-time).
+   *
+   * @example { "content-type": "application/json", "user-agent": "..." }
+   */
+  headers: Record<string, string>;
+  /**
+   * Parsed HTTP cookies from the request.
+   * Automatically extracted from the Cookie header.
+   * Not available during static site generation (SSG build-time).
+   *
+   * @example { "sessionId": "abc123", "theme": "dark" }
+   */
+  cookies: Record<string, string>;
+  /**
+   * Additional data attached by route middleware.
+   * Middleware can populate this field to pass data to the loader and page component.
+   * Useful for authentication info, locale, user preferences, etc.
+   *
+   * @example { "userId": 42, "isAdmin": true }
+   */
+  data?: Record<string, any>;
 };

package/templates/static/lib/css/compiler.d.ts

@@ -1,20 +1,23 @@
 export interface CompileOptions {
-    inputPath: string;
-    outputPath?: string;
-    minified?: boolean;
-    sourceMap?: boolean;
-    watch?: boolean;
+  inputPath: string;
+  outputPath?: string;
+  minified?: boolean;
+  sourceMap?: boolean;
+  watch?: boolean;
 }
 export interface CompileResult {
-    css: string;
-    sourceMap?: string;
-    error?: string;
+  css: string;
+  sourceMap?: string;
+  error?: string;
 }
 export declare class ScssCompiler {
-    compile(options: CompileOptions): CompileResult;
-    compileString(scss: string, options?: {
-        minified?: boolean;
-    }): CompileResult;
-    compileGlob(pattern: string, outputDir: string, minified?: boolean): number;
+  compile(options: CompileOptions): CompileResult;
+  compileString(
+    scss: string,
+    options?: {
+      minified?: boolean;
+    },
+  ): CompileResult;
+  compileGlob(pattern: string, outputDir: string, minified?: boolean): number;
 }
 export declare function createScssCompiler(): ScssCompiler;

package/templates/static/lib/css/compiler.js

@@ -21,67 +21,71 @@ import { writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { log } from "../shared/log.js";
 export class ScssCompiler {
-    compile(options) {
-        const { inputPath, outputPath, minified = false, sourceMap = false, } = options;
-        try {
-            if (!existsSync(inputPath)) {
-                return { css: "", error: `File not found: ${inputPath}` };
-            }
-            const result = compile(inputPath, {
-                style: minified ? "compressed" : "expanded",
-                sourceMap,
-            });
-            if (outputPath) {
-                mkdirSync(dirname(outputPath), { recursive: true });
-                writeFileSync(outputPath, result.css);
-                if (result.sourceMap && sourceMap) {
-                    writeFileSync(outputPath + ".map", JSON.stringify(result.sourceMap));
-                }
-                log.info(`[SCSS] ✓ ${relative(process.cwd(), inputPath)} → ${relative(process.cwd(), outputPath)}`);
-            }
-            return {
-                css: result.css,
-                sourceMap: result.sourceMap
-                    ? JSON.stringify(result.sourceMap)
-                    : undefined,
-            };
-        }
-        catch (err) {
-            const message = err.message || String(err);
-            log.error(`[SCSS] ✗ ${inputPath}: ${message}`);
-            return { css: "", error: message };
-        }
-    }
-    compileString(scss, options) {
-        try {
-            const result = compileString(scss, {
-                style: options?.minified ? "compressed" : "expanded",
-            });
-            return { css: result.css };
-        }
-        catch (err) {
-            const message = err.message || String(err);
-            log.error(`[SCSS] ✗ Inline compilation error: ${message}`);
-            return { css: "", error: message };
+  compile(options) {
+    const {
+      inputPath,
+      outputPath,
+      minified = false,
+      sourceMap = false,
+    } = options;
+    try {
+      if (!existsSync(inputPath)) {
+        return { css: "", error: `File not found: ${inputPath}` };
+      }
+      const result = compile(inputPath, {
+        style: minified ? "compressed" : "expanded",
+        sourceMap,
+      });
+      if (outputPath) {
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, result.css);
+        if (result.sourceMap && sourceMap) {
+          writeFileSync(outputPath + ".map", JSON.stringify(result.sourceMap));
         }
+        log.info(
+          `[SCSS] ✓ ${relative(process.cwd(), inputPath)} → ${relative(process.cwd(), outputPath)}`,
+        );
+      }
+      return {
+        css: result.css,
+        sourceMap: result.sourceMap
+          ? JSON.stringify(result.sourceMap)
+          : undefined,
+      };
+    } catch (err) {
+      const message = err.message || String(err);
+      log.error(`[SCSS] ✗ ${inputPath}: ${message}`);
+      return { css: "", error: message };
     }
-    compileGlob(pattern, outputDir, minified = false) {
-        const files = globSync(pattern);
-        let count = 0;
-        files.forEach((file) => {
-            const rel = relative(outputDir, file);
-            const output = join(outputDir, rel.replace(/\.scss$/, ".css"));
-            const result = this.compile({
-                inputPath: file,
-                outputPath: output,
-                minified,
-            });
-            if (!result.error)
-                count++;
-        });
-        return count;
+  }
+  compileString(scss, options) {
+    try {
+      const result = compileString(scss, {
+        style: options?.minified ? "compressed" : "expanded",
+      });
+      return { css: result.css };
+    } catch (err) {
+      const message = err.message || String(err);
+      log.error(`[SCSS] ✗ Inline compilation error: ${message}`);
+      return { css: "", error: message };
     }
+  }
+  compileGlob(pattern, outputDir, minified = false) {
+    const files = globSync(pattern);
+    let count = 0;
+    files.forEach((file) => {
+      const rel = relative(outputDir, file);
+      const output = join(outputDir, rel.replace(/\.scss$/, ".css"));
+      const result = this.compile({
+        inputPath: file,
+        outputPath: output,
+        minified,
+      });
+      if (!result.error) count++;
+    });
+    return count;
+  }
 }
 export function createScssCompiler() {
-    return new ScssCompiler();
+  return new ScssCompiler();
 }