create-jen-app 1.2.2 → 1.2.4

package/templates/static/lib/jdb/utils.js

@@ -1,141 +1,176 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 import fs from "fs/promises";
 import crypto from "crypto";
+/**
+ * Ensure a directory exists, creating it recursively if necessary.
+ * Idempotent: does not throw if the directory already exists.
+ *
+ * @param dir Directory path to ensure exists.
+ * @throws Error if directory creation fails.
+ */
 export async function ensureDir(dir) {
-    try {
-        await fs.access(dir);
-    }
-    catch {
-        await fs.mkdir(dir, { recursive: true });
-    }
+  try {
+    await fs.access(dir);
+  } catch {
+    await fs.mkdir(dir, { recursive: true });
+  }
 }
+/**
+ * Read and parse a JSON file from disk.
+ * Returns null if the file does not exist (ENOENT).
+ * Other errors (invalid JSON, permission denied, etc.) are re-thrown.
+ *
+ * @template T The expected JSON structure type.
+ * @param file Path to the JSON file to read.
+ * @returns Parsed JSON data, or null if file does not exist.
+ * @throws Error if the file exists but cannot be read or parsed.
+ */
 export async function readJSON(file) {
-    try {
-        const data = await fs.readFile(file, "utf-8");
-        return JSON.parse(data);
-    }
-    catch (e) {
-        if (e.code === "ENOENT")
-            return null;
-        throw e;
-    }
+  try {
+    const data = await fs.readFile(file, "utf-8");
+    return JSON.parse(data);
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
 }
+/**
+ * Write data as JSON to a file atomically using a temporary file.
+ * Atomic writes prevent corruption if the process crashes during writing.
+ * The temporary file is renamed to the target file only after writing completes successfully.
+ *
+ * @param file Path to the target file (will be created or overwritten).
+ * @param data Object to serialize as JSON with pretty-printing (2-space indent).
+ * @throws Error if writing or renaming fails.
+ */
 export async function writeJSON(file, data) {
-    const tempFile = `${file}.tmp`;
-    await fs.writeFile(tempFile, JSON.stringify(data, null, 2));
-    await fs.rename(tempFile, file);
+  const tempFile = `${file}.tmp`;
+  await fs.writeFile(tempFile, JSON.stringify(data, null, 2));
+  await fs.rename(tempFile, file);
 }
+/**
+ * Generate a unique identifier for a new document.
+ * Uses cryptographically secure UUID v4 generation.
+ *
+ * @returns A UUID string suitable for use as a document _id.
+ */
 export function generateId() {
-    return crypto.randomUUID();
+  return crypto.randomUUID();
 }
+/**
+ * Test whether a document matches a filter query.
+ * Supports MongoDB-like query syntax including operators ($eq, $ne, $gt, etc.) and logical operators ($or, $and).
+ * Processes each field condition and returns false if any condition fails (AND semantics).
+ * Logical operators $or and $and are processed separately with their respective semantics.
+ *
+ * @param doc The document to test.
+ * @param filter The filter query to apply.
+ * @returns True if the document matches all filter conditions, false otherwise.
+ *
+ * @example
+ * matchFilter({ name: 'John', age: 30 }, { name: 'John' }) // true
+ * matchFilter({ age: 25 }, { age: { $gte: 18 } }) // true
+ * matchFilter({ name: 'Jane' }, { $or: [{ name: 'John' }, { name: 'Jane' }] }) // true
+ */
 export function matchFilter(doc, filter) {
-    for (const key in filter) {
-        if (key === "$or") {
-            if (!filter.$or.some((f) => matchFilter(doc, f)))
-                return false;
-            continue;
-        }
-        if (key === "$and") {
-            if (!filter.$and.every((f) => matchFilter(doc, f)))
-                return false;
-            continue;
-        }
-        const val = doc[key];
-        const cond = filter[key];
-        if (typeof cond === "object" && cond !== null && !Array.isArray(cond)) {
-            for (const op in cond) {
-                const target = cond[op];
-                switch (op) {
-                    case "$eq":
-                        if (val !== target)
-                            return false;
-                        break;
-                    case "$ne":
-                        if (val === target)
-                            return false;
-                        break;
-                    case "$gt":
-                        if (!(val > target))
-                            return false;
-                        break;
-                    case "$gte":
-                        if (!(val >= target))
-                            return false;
-                        break;
-                    case "$lt":
-                        if (!(val < target))
-                            return false;
-                        break;
-                    case "$lte":
-                        if (!(val <= target))
-                            return false;
-                        break;
-                    case "$in":
-                        if (!target.includes(val))
-                            return false;
-                        break;
-                    case "$nin":
-                        if (target.includes(val))
-                            return false;
-                        break;
-                    case "$regex":
-                        if (!new RegExp(target).test(val))
-                            return false;
-                        break;
-                }
-            }
-        }
-        else {
-            if (val !== cond)
-                return false;
+  for (const key in filter) {
+    if (key === "$or") {
+      // OR: at least one filter must match
+      if (!filter.$or.some((f) => matchFilter(doc, f))) return false;
+      continue;
+    }
+    if (key === "$and") {
+      // AND: all filters must match
+      if (!filter.$and.every((f) => matchFilter(doc, f))) return false;
+      continue;
+    }
+    const val = doc[key];
+    const cond = filter[key];
+    // If condition is an object (not array), it contains operators
+    if (typeof cond === "object" && cond !== null && !Array.isArray(cond)) {
+      for (const op in cond) {
+        const target = cond[op];
+        switch (op) {
+          case "$eq":
+            if (val !== target) return false;
+            break;
+          case "$ne":
+            if (val === target) return false;
+            break;
+          case "$gt":
+            if (!(val > target)) return false;
+            break;
+          case "$gte":
+            if (!(val >= target)) return false;
+            break;
+          case "$lt":
+            if (!(val < target)) return false;
+            break;
+          case "$lte":
+            if (!(val <= target)) return false;
+            break;
+          case "$in":
+            if (!target.includes(val)) return false;
+            break;
+          case "$nin":
+            if (target.includes(val)) return false;
+            break;
+          case "$regex":
+            if (!new RegExp(target).test(val)) return false;
+            break;
         }
+      }
+    } else {
+      // Simple equality check
+      if (val !== cond) return false;
     }
-    return true;
+  }
+  return true;
 }
+/**
+ * Apply update operators to a document, modifying it in place.
+ * Automatically updates the _updated timestamp to the current time.
+ * Supports $set, $unset, $inc, $push, and $pull operators.
+ *
+ * @param doc The document to update (modified in place).
+ * @param update Update specification with operators.
+ *
+ * @example
+ * const doc = { name: 'John', age: 30, tags: ['js'] };
+ * applyUpdate(doc, { $set: { name: 'Jane' }, $inc: { age: 1 }, $push: { tags: 'ts' } });
+ * // doc is now { name: 'Jane', age: 31, tags: ['js', 'ts'], _updated: <current-timestamp> }
+ */
 export function applyUpdate(doc, update) {
-    const now = Date.now();
-    doc._updated = now;
-    for (const op in update) {
-        const fields = update[op];
-        for (const key in fields) {
-            const val = fields[key];
-            switch (op) {
-                case "$set":
-                    doc[key] = val;
-                    break;
-                case "$unset":
-                    delete doc[key];
-                    break;
-                case "$inc":
-                    doc[key] = (doc[key] || 0) + val;
-                    break;
-                case "$push":
-                    if (!Array.isArray(doc[key]))
-                        doc[key] = [];
-                    doc[key].push(val);
-                    break;
-                case "$pull":
-                    if (Array.isArray(doc[key])) {
-                        doc[key] = doc[key].filter((item) => item !== val);
-                    }
-                    break;
-            }
-        }
+  const now = Date.now();
+  doc._updated = now;
+  for (const op in update) {
+    const fields = update[op];
+    for (const key in fields) {
+      const val = fields[key];
+      switch (op) {
+        case "$set":
+          // Set field to the specified value
+          doc[key] = val;
+          break;
+        case "$unset":
+          // Remove the field from the document
+          delete doc[key];
+          break;
+        case "$inc":
+          // Increment numeric field by the specified amount
+          doc[key] = (doc[key] || 0) + val;
+          break;
+        case "$push":
+          // Append to array (create array if doesn't exist)
+          if (!Array.isArray(doc[key])) doc[key] = [];
+          doc[key].push(val);
+          break;
+        case "$pull":
+          // Remove all occurrences of value from array
+          if (Array.isArray(doc[key])) {
+            doc[key] = doc[key].filter((item) => item !== val);
+          }
+          break;
+      }
     }
+  }
 }

package/templates/static/lib/middleware/builtins/cors.js

@@ -1,67 +1,58 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+/**
+ * CORS middleware with security defaults
+ * Prevents insecure origin sharing with credentials
  */
 export function cors(options = {}) {
-    const defaults = {
-        origin: ["http://localhost:3000", "http://localhost:5173"],
-        methods: ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"],
-        allowedHeaders: ["Content-Type", "Authorization"],
-        credentials: false, // Changed: credentials should be false with CORS by default for security
-        maxAge: 86400,
-    };
-    const opts = { ...defaults, ...options };
-    return async (ctx, next) => {
-        const origin = ctx.req.headers.origin;
-        // Validate origin against whitelist
-        let allowOrigin = false;
-        if (Array.isArray(opts.origin)) {
-            allowOrigin = origin && opts.origin.includes(origin);
-        }
-        else if (typeof opts.origin === "function") {
-            allowOrigin = origin && opts.origin(origin);
-        }
-        else if (opts.origin === "*") {
-            // DANGEROUS: only use with credentials: false
-            if (opts.credentials) {
-                console.warn("SECURITY WARNING: CORS origin '*' with credentials=true is insecure. Origin set to empty.");
-                allowOrigin = false;
-            }
-            else {
-                allowOrigin = true;
-            }
-        }
-        else if (opts.origin === origin) {
-            allowOrigin = true;
-        }
-        if (allowOrigin && origin) {
-            ctx.response.header("Access-Control-Allow-Origin", origin);
-        }
-        if (opts.credentials) {
-            ctx.response.header("Access-Control-Allow-Credentials", "true");
-        }
-        if (ctx.req.method === "OPTIONS") {
-            ctx.response.header("Access-Control-Allow-Methods", opts.methods?.join(","));
-            ctx.response.header("Access-Control-Allow-Headers", opts.allowedHeaders?.join(","));
-            if (opts.maxAge) {
-                ctx.response.header("Access-Control-Max-Age", opts.maxAge);
-            }
-            ctx.response.status(204).send();
-            return;
-        }
-        await next();
-    };
+  const defaults = {
+    origin: ["http://localhost:3000", "http://localhost:5173"],
+    methods: ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+    credentials: false, // Changed: credentials should be false with CORS by default for security
+    maxAge: 86400,
+  };
+  const opts = { ...defaults, ...options };
+  return async (ctx, next) => {
+    const origin = ctx.req.headers.origin;
+    // Validate origin against whitelist
+    let allowOrigin = false;
+    if (Array.isArray(opts.origin)) {
+      allowOrigin = origin && opts.origin.includes(origin);
+    } else if (typeof opts.origin === "function") {
+      allowOrigin = origin && opts.origin(origin);
+    } else if (opts.origin === "*") {
+      // DANGEROUS: only use with credentials: false
+      if (opts.credentials) {
+        console.warn(
+          "SECURITY WARNING: CORS origin '*' with credentials=true is insecure. Origin set to empty.",
+        );
+        allowOrigin = false;
+      } else {
+        allowOrigin = true;
+      }
+    } else if (opts.origin === origin) {
+      allowOrigin = true;
+    }
+    if (allowOrigin && origin) {
+      ctx.response.header("Access-Control-Allow-Origin", origin);
+    }
+    if (opts.credentials) {
+      ctx.response.header("Access-Control-Allow-Credentials", "true");
+    }
+    if (ctx.req.method === "OPTIONS") {
+      ctx.response.header(
+        "Access-Control-Allow-Methods",
+        opts.methods?.join(","),
+      );
+      ctx.response.header(
+        "Access-Control-Allow-Headers",
+        opts.allowedHeaders?.join(","),
+      );
+      if (opts.maxAge) {
+        ctx.response.header("Access-Control-Max-Age", opts.maxAge);
+      }
+      ctx.response.status(204).send();
+      return;
+    }
+    await next();
+  };
 }

package/templates/static/lib/middleware/context.js

@@ -1,50 +1,124 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
+import { ResponseBuilder } from "./response.js";
+/**
+ * Request context object passed through the middleware chain.
+ * Wraps Node.js req/res objects and provides helper methods and parsed request data.
+ * Each middleware receives this context and can read/modify its properties.
  *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * The context enables:
+ * - Access to parsed URL, query params, route params, cookies, headers
+ * - Convenient response building methods (json(), headers())
+ * - State storage for passing data between middlewares
+ * - Request body parsing and caching
  */
-import { ResponseBuilder } from "./response.js";
 export class Context {
-    req;
-    res;
-    url;
-    state;
-    response;
-    body; // For parsed body
-    query;
-    params;
-    constructor(req, res) {
-        this.req = req;
-        this.res = res;
-        this.url = new URL(req.url ?? "/", `http://${req.headers.host || "localhost"}`);
-        this.state = {};
-        this.response = new ResponseBuilder(res);
-        this.body = null;
-        this.query = Object.fromEntries(this.url.searchParams);
-        this.params = {};
-    }
-    get cookies() {
-        const header = this.req.headers.cookie;
-        if (!header)
-            return {};
-        return Object.fromEntries(header.split(";").map((c) => {
-            const [key, ...v] = c.trim().split("=");
-            return [key, decodeURIComponent(v.join("="))];
-        }));
-    }
-    json(data, status = 200) {
-        return this.response.status(status).json(data).send();
-    }
+  /**
+   * Raw Node.js IncomingMessage request object.
+   * Contains method, url, headers, socket, etc.
+   */
+  req;
+  /**
+   * Raw Node.js ServerResponse response object.
+   * Used to send response data back to the client.
+   */
+  res;
+  /**
+   * Parsed URL object with scheme, host, pathname, search, searchParams, etc.
+   * Automatically constructed from req.url and req.headers.host.
+   *
+   * @example ctx.url.pathname for "/posts/42", ctx.url.searchParams for query parsing
+   */
+  url;
+  /**
+   * Shared state object for middleware to store data.
+   * Useful for passing values between middlewares in the chain without response headers.
+   *
+   * @example ctx.state.userId = 42; // Set in auth middleware, read in handler
+   */
+  state;
+  /**
+   * ResponseBuilder instance for fluent response building.
+   * Use ctx.response.status().json() or ctx.response.header() to build responses.
+   * Alternatively, use ctx.json() shortcut for quick JSON responses.
+   */
+  response;
+  /**
+   * Parsed request body cache.
+   * Set by body parser middleware if request has a body.
+   * Can be null if no body parser ran or if the request has no body.
+   */
+  body;
+  /**
+   * Query string parameters as an object.
+   * Automatically parsed from ctx.url.searchParams on construction.
+   * Keys and values are always strings.
+   *
+   * @example For URL "/posts?sort=date&limit=10", yields { sort: "date", limit: "10" }
+   */
+  query;
+  /**
+   * Route parameters extracted from the URL path.
+   * Set by route matching middleware based on dynamic route patterns.
+   * Empty object initially; populated when a route matches.
+   *
+   * @example For route "/posts/:id" matching "/posts/42", yields { id: "42" }
+   */
+  params;
+  /**
+   * Initializes a request context from Node.js request and response objects.
+   * Parses the URL, extracts query parameters, and initializes helpers.
+   *
+   * @param req Node.js IncomingMessage
+   * @param res Node.js ServerResponse
+   */
+  constructor(req, res) {
+    this.req = req;
+    this.res = res;
+    this.url = new URL(
+      req.url ?? "/",
+      `http://${req.headers.host || "localhost"}`,
+    );
+    this.state = {};
+    this.response = new ResponseBuilder(res);
+    this.body = null;
+    this.query = Object.fromEntries(this.url.searchParams);
+    this.params = {};
+  }
+  /**
+   * Getter that parses and caches cookies from the request.
+   * Parses the Cookie header into an object of name-value pairs.
+   * Values are automatically decoded using decodeURIComponent.
+   * Memoization is implicit; called fresh each time.
+   *
+   * @returns Object with cookie names as keys and values as cookie values
+   *
+   * @example
+   * const sessionId = ctx.cookies.sessionId;  // Get a cookie value
+   * // For header "sessionId=abc123; theme=dark" yields { sessionId: "abc123", theme: "dark" }
+   */
+  get cookies() {
+    const header = this.req.headers.cookie;
+    if (!header) return {};
+    return Object.fromEntries(
+      header.split(";").map((c) => {
+        const [key, ...v] = c.trim().split("=");
+        return [key, decodeURIComponent(v.join("="))];
+      }),
+    );
+  }
+  /**
+   * Convenience method to send a JSON response.
+   * Combines ctx.response.status().json().send() into a single call.
+   *
+   * @param data Object to serialize as JSON and send
+   * @param status HTTP status code; defaults to 200 (OK)
+   *
+   * @returns Result of response.send() (undefined if response is sent)
+   *
+   * @example
+   * ctx.json({ success: true }, 201);
+   * ctx.json({ error: "Not found" }, 404);
+   */
+  json(data, status = 200) {
+    return this.response.status(status).json(data).send();
+  }
 }