create-jen-app 1.2.3 → 1.2.4

package/templates/ssr-isr/lib/core/paths.js

@@ -0,0 +1,39 @@
+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);
+}
+/**
+ * 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);
+}

package/templates/ssr-isr/lib/core/routes/match.js

@@ -0,0 +1,47 @@
+/**
+ * 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;
+    /**
+     * 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 { route: r, params };
+  }
+  return null;
+}

package/templates/ssr-isr/lib/core/routes/scan.js

@@ -0,0 +1,190 @@
+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;
+}
+/**
+ * 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("/");
+}
+/**
+ * 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, "\\$&");
+}
+/**
+ * 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 "([^/]+)";
+}
+/**
+ * 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 };
+}
+/**
+ * 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 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;
+    }
+    // else: (anything else) treated as literal segment
+    const { src, paramNames } = buildRoutePattern(url);
+    routes.push({
+      id: rel.replaceAll("/", "_"),
+      filePath: abs,
+      urlPath: url,
+      pattern: src,
+      paramNames,
+    });
+  }
+  // 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/ssr-isr/lib/core/types.js

@@ -0,0 +1 @@
+export {};

package/templates/ssr-isr/lib/css/compiler.js

@@ -0,0 +1,74 @@
+import { compile, compileString } from "sass";
+import { globSync } from "glob";
+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 };
+    }
+  }
+  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();
+}

package/templates/ssr-isr/lib/db/connector.js

@@ -0,0 +1,42 @@
+import { JDBDriver } from "./drivers/jdb";
+import { SQLDriver } from "./drivers/sql";
+/**
+ * Factory class for creating database driver instances.
+ * The DBConnector uses the factory pattern to instantiate the appropriate driver
+ * based on the configured database type. This allows the application to support
+ * multiple database backends without tight coupling to any single implementation.
+ *
+ * Supported database types:
+ * - jdb: Embedded JSON database (built-in, no external dependencies)
+ * - sqlite: SQLite relational database
+ * - postgres: PostgreSQL relational database
+ * - mysql: MySQL relational database
+ */
+export class DBConnector {
+  /**
+   * Creates and returns a database driver instance based on the configuration.
+   * The driver implements the IDBDriver interface and provides the same API
+   * regardless of the underlying database type.
+   *
+   * @param config The database configuration including type and connection parameters.
+   * @returns An IDBDriver instance for the specified database type.
+   * @throws Error if the configured database type is not supported.
+   *
+   * @example
+   * const config: DBConfig = { type: 'sqlite', path: './data.db' };
+   * const driver = DBConnector.create(config);
+   * const records = await driver.query('SELECT * FROM users');
+   */
+  static create(config) {
+    switch (config.type) {
+      case "jdb":
+        return new JDBDriver(config);
+      case "sqlite":
+      case "postgres":
+      case "mysql":
+        return new SQLDriver(config);
+      default:
+        throw new Error(`Unsupported DB type: ${config.type}`);
+    }
+  }
+}

package/templates/ssr-isr/lib/db/drivers/jdb.js

@@ -0,0 +1,44 @@
+import { JDBEngine } from "../../jdb";
+export class JDBDriver {
+  engine;
+  constructor(config) {
+    const jdbConfig = config.jdb || {
+      root: "./data",
+      inMemory: false,
+    };
+    this.engine = new JDBEngine(jdbConfig);
+  }
+  async connect() {
+    await this.engine.connect();
+  }
+  async disconnect() {
+    await this.engine.disconnect();
+  }
+  async query(q) {
+    if (typeof q === "string") {
+      throw new Error(
+        "Raw string queries not supported in JDB directly. Use object syntax.",
+      );
+    }
+    if ("sql" in q) {
+      throw new Error("SQL queries not supported in JDB driver.");
+    }
+    const query = q;
+    const coll = this.engine.collection(query.find);
+    return await coll.find(query.where || {}, query.options);
+  }
+  async create(collection, data) {
+    return await this.engine.collection(collection).insert(data);
+  }
+  async update(collection, filter, update) {
+    return await this.engine
+      .collection(collection)
+      .update(filter, update, true);
+  }
+  async delete(collection, filter) {
+    return await this.engine.collection(collection).delete(filter, true);
+  }
+  async count(collection, filter) {
+    return await this.engine.collection(collection).count(filter);
+  }
+}

package/templates/ssr-isr/lib/db/drivers/sql.js

@@ -0,0 +1,182 @@
+// Whitelist of allowed identifiers (table/column names) - must be explicitly allowed
+const ALLOWED_IDENTIFIERS = new Set();
+/**
+ * Safely quote SQL identifier to prevent injection
+ * Only accepts alphanumeric, underscore, dollar sign
+ * Note: Hyphen is NOT allowed as it can cause confusion with operators
+ */
+function quoteIdentifier(id) {
+  if (!id || !/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(id)) {
+    throw new Error(
+      `Invalid SQL identifier: ${id}. Only alphanumeric, underscore, and dollar sign allowed. Must start with letter, underscore, or dollar.`,
+    );
+  }
+  return `\`${id}\``; // Use backticks for MySQL, adjust for other databases
+}
+/**
+ * Validate and register allowed table/collection names for security
+ */
+export function registerAllowedTable(tableName) {
+  if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(tableName)) {
+    ALLOWED_IDENTIFIERS.add(tableName);
+  } else {
+    throw new Error(
+      `Invalid table name: ${tableName}. Must start with letter, underscore, or dollar. Only alphanumeric, underscore, and dollar allowed.`,
+    );
+  }
+}
+/**
+ * Check if table is in allowed list
+ */
+function isTableAllowed(tableName) {
+  return ALLOWED_IDENTIFIERS.has(tableName);
+}
+/**
+ * Validate integer value (for LIMIT/OFFSET)
+ */
+function validateInteger(value) {
+  const num = parseInt(value, 10);
+  if (isNaN(num) || num < 0) {
+    throw new Error(`Invalid integer value: ${value}`);
+  }
+  return num;
+}
+export class SQLDriver {
+  executor;
+  constructor(config) {
+    if (typeof config.connection === "function") {
+      this.executor = config.connection;
+    } else if (config.connection && config.connection.query) {
+      // Support objects like Pool or Client from pg/mysql
+      this.executor = (sql, params) => config.connection.query(sql, params);
+    } else {
+      // Default stub that warns if no connection provided, or we could try to load a default
+      this.executor = async () => {
+        throw new Error("No SQL connection provided to SQLDriver");
+      };
+    }
+  }
+  async connect() {
+    // Connection management usually handled by the pool passed in, but we can add logic here if needed
+  }
+  async disconnect() {
+    // No-op or close pool
+  }
+  async query(q) {
+    if (typeof q === "string") {
+      return this.executor(q, []);
+    }
+    if ("sql" in q) {
+      return this.executor(q.sql, q.params || []);
+    }
+    // Convert NoSQL style to SQL (Basic translation)
+    const query = q;
+    const { sql, params } = this.translateQuery(query);
+    return this.executor(sql, params);
+  }
+  translateQuery(q) {
+    // Security: Validate table name
+    if (!isTableAllowed(q.find)) {
+      throw new Error(
+        `Table '${q.find}' not registered. Call registerAllowedTable() first.`,
+      );
+    }
+    let sql = `SELECT * FROM ${quoteIdentifier(q.find)}`;
+    const params = [];
+    if (q.where && Object.keys(q.where).length > 0) {
+      const conditions = [];
+      const whereRecord = q.where;
+      for (const key in whereRecord) {
+        // Security: Validate column name
+        if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
+          throw new Error(
+            `Invalid column name: ${key}. Must start with letter, underscore, or dollar. Only alphanumeric, underscore, and dollar allowed.`,
+          );
+        }
+        // Safely access where property
+        const val = whereRecord[key];
+        conditions.push(`${quoteIdentifier(key)} = ?`);
+        params.push(val);
+      }
+      sql += ` WHERE ${conditions.join(" AND ")}`;
+    }
+    if (q.options?.limit) {
+      // Security: Validate limit is a positive integer
+      const limit = validateInteger(q.options.limit);
+      sql += ` LIMIT ${limit}`;
+    }
+    if (q.options?.skip) {
+      // Security: Validate offset is a non-negative integer
+      const skip = validateInteger(q.options.skip);
+      sql += ` OFFSET ${skip}`;
+    }
+    return { sql, params };
+  }
+  async create(collection, data) {
+    // Security: Validate table name
+    if (!isTableAllowed(collection)) {
+      throw new Error(
+        `Table '${collection}' not registered. Call registerAllowedTable() first.`,
+      );
+    }
+    const keys = Object.keys(data);
+    // Security: Validate all column names
+    for (const key of keys) {
+      if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
+        throw new Error(
+          `Invalid column name: ${key}. Must start with letter, underscore, or dollar. Only alphanumeric, underscore, and dollar allowed.`,
+        );
+      }
+    }
+    const placeholders = keys.map(() => "?").join(",");
+    const quotedKeys = keys.map((k) => quoteIdentifier(k)).join(",");
+    const sql = `INSERT INTO ${quoteIdentifier(collection)} (${quotedKeys}) VALUES (${placeholders})`;
+    const params = keys.map((k) => data[k]);
+    await this.executor(sql, params);
+    // Retrieve generic - this might need adjustment per driver for "returning" support
+    return data;
+  }
+  async update(collection, filter, update) {
+    // Basic implementation requiring WHERE clause
+    // This is complex to map generic Mongo-style updates to SQL without a robust builder
+    throw new Error(
+      "Complex update translation not implemented for Generic SQL Driver yet. Use raw SQL.",
+    );
+  }
+  async delete(collection, filter) {
+    // Security: Validate table name
+    if (!isTableAllowed(collection)) {
+      throw new Error(
+        `Table '${collection}' not registered. Call registerAllowedTable() first.`,
+      );
+    }
+    // Validate that filter is not empty to prevent accidental full table delete
+    if (!filter || Object.keys(filter).length === 0) {
+      throw new Error(
+        "Delete requires at least one filter condition. Use truncate or raw SQL for full table deletion.",
+      );
+    }
+    const { sql, params } = this.translateQuery({
+      find: collection,
+      where: filter,
+    });
+    const deleteSql = sql.replace("SELECT \\*", "DELETE");
+    await this.executor(deleteSql, params);
+    return 1; // Unknown count without driver specific result
+  }
+  async count(collection, filter) {
+    // Security: Validate table name
+    if (!isTableAllowed(collection)) {
+      throw new Error(
+        `Table '${collection}' not registered. Call registerAllowedTable() first.`,
+      );
+    }
+    const { sql, params } = this.translateQuery({
+      find: collection,
+      where: filter,
+    });
+    const countSql = sql.replace("SELECT *", "SELECT COUNT(*) as count");
+    const res = await this.executor(countSql, params);
+    return res[0]?.count || 0;
+  }
+}

package/templates/ssr-isr/lib/db/index.js

@@ -0,0 +1,48 @@
+import { DBConnector } from "./connector";
+export * from "./types";
+export * from "./drivers/jdb";
+export * from "./drivers/sql";
+export class DB {
+  driver;
+  config;
+  constructor(config) {
+    this.config = config;
+    this.driver = DBConnector.create(config);
+  }
+  async connect() {
+    await this.driver.connect();
+  }
+  async disconnect() {
+    await this.driver.disconnect();
+  }
+  async query(q, params) {
+    if (typeof q === "string") {
+      return this.driver.query({ sql: q, params });
+    }
+    return this.driver.query(q);
+  }
+  // Fluent API Shortcuts
+  find(collection, filter, options) {
+    return this.driver.query({ find: collection, where: filter, options });
+  }
+  async findOne(collection, filter) {
+    const res = await this.driver.query({
+      find: collection,
+      where: filter,
+      options: { limit: 1 },
+    });
+    return res[0] || null;
+  }
+  create(collection, data) {
+    return this.driver.create(collection, data);
+  }
+  update(collection, filter, update) {
+    return this.driver.update(collection, filter, update);
+  }
+  delete(collection, filter) {
+    return this.driver.delete(collection, filter);
+  }
+  count(collection, filter) {
+    return this.driver.count(collection, filter);
+  }
+}

package/templates/ssr-isr/lib/db/types.js

@@ -0,0 +1 @@
+export {};