create-jen-app 1.2.3 → 1.2.4

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

@@ -0,0 +1,34 @@
+/**
+ * JDB (Jen Database) - A lightweight embedded JSON database for Jen.js applications.
+ *
+ * JDB provides MongoDB-like CRUD operations with file-based or in-memory storage.
+ * Perfect for small to medium applications that need data persistence without external dependencies.
+ *
+ * Features:
+ * - MongoDB-like query syntax with filter operators ($eq, $gt, $in, $regex, etc.)
+ * - Atomic update operations ($set, $inc, $push, etc.)
+ * - Pagination, sorting, and filtering
+ * - Lazy loading and deferred writes for performance
+ * - In-memory mode for testing
+ * - Simple JSON file format for easy inspection and migration
+ *
+ * @example
+ * import { JDBEngine, type ICollection, type Document } from '@src/jdb';
+ *
+ * interface User extends Document {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * const db = new JDBEngine({ root: './data' });
+ * await db.connect();
+ *
+ * const users = db.collection<User>('users');
+ * const user = await users.insert({ name: 'John', email: 'john@example.com', age: 30 });
+ * const found = await users.findOne({ email: 'john@example.com' });
+ * await users.update({ _id: user._id }, { $set: { age: 31 } });
+ * await users.delete({ _id: user._id });
+ */
+export * from "./types";
+export { JDBEngine } from "./engine";

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

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

package/templates/ssr-isr/lib/jdb/utils.js

@@ -0,0 +1,176 @@
+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 });
+  }
+}
+/**
+ * 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;
+  }
+}
+/**
+ * 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);
+}
+/**
+ * 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();
+}
+/**
+ * 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") {
+      // 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;
+}
+/**
+ * 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":
+          // 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 → ssr-isr}/lib/middleware/builtins/body-parser.js

@@ -1,20 +1,3 @@
-/*
- * 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/>.
- */
 /**
  * Request body parsing middleware.
  * Reads and parses the request body based on Content-Type header.

package/templates/ssr-isr/lib/middleware/builtins/cors.js

@@ -0,0 +1,54 @@
+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();
+  };
+}

package/templates/{static → ssr-isr}/lib/middleware/builtins/logger.js

@@ -1,20 +1,3 @@
-/*
- * 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 { log } from "../../shared/log.js";
 /**
  * Middleware that logs HTTP requests and responses with timing information.

package/templates/{static → ssr-isr}/lib/middleware/builtins/rate-limit.js

@@ -1,20 +1,3 @@
-/*
- * 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/>.
- */
 /**
  * Rate limiting middleware that protects against brute force and DDoS attacks.
  * Tracks request count per client IP within a time window and rejects excess requests.

package/templates/{static → ssr-isr}/lib/middleware/builtins/request-id.js

@@ -1,20 +1,3 @@
-/*
- * 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 { randomUUID } from "node:crypto";
 /**
  * Request ID middleware that assigns unique identifiers to incoming requests.

package/templates/{static → ssr-isr}/lib/middleware/builtins/security-headers.js

@@ -1,20 +1,3 @@
-/*
- * 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/>.
- */
 /**
  * Security headers middleware that sets HTTP response headers for defense against common attacks.
  * Implements a comprehensive security policy including:

package/templates/ssr-isr/lib/middleware/context.js

@@ -0,0 +1,124 @@
+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.
+ *
+ * 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
+ */
+export class Context {
+  /**
+   * 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();
+  }
+}

package/templates/{static → ssr-isr}/lib/middleware/decorators.js

@@ -1,20 +1,3 @@
-/*
- * 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/>.
- */
 /**
  * Metadata storage for decorator information.
  * Provides a fallback when Reflect.metadata is not available.

package/templates/{static → ssr-isr}/lib/middleware/errors/handler.js

@@ -1,20 +1,3 @@
-/*
- * 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 { HttpError } from "./http-error.js";
 export async function errorHandler(ctx, next) {
   try {

package/templates/ssr-isr/lib/middleware/errors/http-error.js

@@ -0,0 +1,10 @@
+export class HttpError extends Error {
+  statusCode;
+  details;
+  constructor(statusCode, message, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    Object.setPrototypeOf(this, HttpError.prototype);
+  }
+}

package/templates/ssr-isr/lib/middleware/kernel.js

@@ -0,0 +1,85 @@
+import { Pipeline } from "./pipeline.js";
+import { MiddlewareRegistry } from "./registry.js";
+import { Context } from "./context.js";
+/**
+ * Core HTTP request handler that manages middleware execution and request context.
+ *
+ * The Kernel implements a middleware pipeline pattern:
+ * 1. Receives Node.js req and res objects
+ * 2. Wraps them in a Context object with helper methods and properties
+ * 3. Composes registered middlewares into a callable pipeline
+ * 4. Executes the pipeline with the context for request processing
+ *
+ * Middlewares can:
+ * - Access/modify request and response via ctx.req, ctx.res, ctx.response
+ * - Read/set cookies, headers, query params, route params
+ * - Store and retrieve shared state in ctx.state
+ * - Call ctx.response.json() or other response builders
+ * - Control flow via next() to continue to next middleware
+ */
+export class Kernel {
+  /**
+   * Array of global middleware functions that run for every request.
+   * Middlewares are stored in order of registration (use() calls).
+   * Executed sequentially in Pipeline.compose().
+   */
+  globalMiddleware = [];
+  constructor() {}
+  /**
+   * Registers a middleware function to run for all requests.
+   * Middleware can be a function, a class constructor, or an object with handle() method.
+   *
+   * @param mw Middleware function: (ctx, next) => Promise<void>
+   *           Or class with: new MyMiddleware().handle(ctx, next)
+   *
+   * @example
+   * kernel.use(async (ctx, next) => {
+   *   console.log(`${ctx.req.method} ${ctx.url.pathname}`);
+   *   await next();
+   * });
+   */
+  use(mw) {
+    this.globalMiddleware.push(mw);
+  }
+  /**
+   * Processes an HTTP request through the global middleware pipeline.
+   * Creates a Context wrapping the request/response, composes middlewares, and executes them.
+   *
+   * @param req Node.js IncomingMessage (HTTP request object)
+   * @param res Node.js ServerResponse (HTTP response object)
+   *
+   * @returns Promise that resolves when middleware chain completes
+   *
+   * @example
+   * const server = createServer((req, res) => {
+   *   kernel.handle(req, res);
+   * });
+   */
+  async handle(req, res) {
+    const ctx = new Context(req, res);
+    const fn = Pipeline.compose(this.globalMiddleware);
+    await fn(ctx, async () => {});
+  }
+  /**
+   * Processes a request through global middleware plus a registered middleware group.
+   * Retrieves middleware from the registry by group name and composes them with global middleware.
+   * Useful for route-specific or feature-specific middleware chains.
+   *
+   * @param req Node.js IncomingMessage
+   * @param res Node.js ServerResponse
+   * @param groupName Name of the middleware group registered in MiddlewareRegistry
+   *
+   * @returns Promise that resolves when complete middleware chain executes
+   *
+   * @example
+   * // Given a group named "apiMiddleware" with auth and logging
+   * await kernel.handleWithGroup(req, res, "apiMiddleware");
+   */
+  async handleWithGroup(req, res, groupName) {
+    const ctx = new Context(req, res);
+    const registry = MiddlewareRegistry.get();
+    const groupMw = registry.getGroup(groupName);
+    const fn = Pipeline.compose([...this.globalMiddleware, ...groupMw]);
+    await fn(ctx, async () => {});
+  }
+}