npm - kaelum - Versions diffs - 1.2.0 → 1.3.1 - Mend

kaelum 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/README.md +158 -61
package/cli/create.js +71 -31
package/cli/index.js +49 -7
package/cli/templates/api/app.js +16 -2
package/cli/templates/api/controllers/usersController.js +58 -0
package/cli/templates/api/middlewares/authMock.js +13 -0
package/cli/templates/api/package.json +14 -7
package/cli/templates/api/routes.js +31 -8
package/cli/templates/web/app.js +15 -4
package/cli/templates/web/middlewares/logger.js +5 -5
package/cli/templates/web/package.json +17 -7
package/cli/templates/web/public/style.css +42 -35
package/cli/templates/web/routes.js +22 -17
package/cli/templates/web/views/index.html +39 -19
package/cli/utils.js +50 -4
package/core/addRoute.js +156 -5
package/core/apiRoute.js +135 -0
package/core/errorHandler.js +139 -0
package/core/healthCheck.js +204 -0
package/core/redirect.js +177 -0
package/core/setConfig.js +245 -20
package/core/setMiddleware.js +183 -6
package/core/start.js +111 -4
package/createApp.js +166 -13
package/package.json +4 -3
package/bin/.gitkeep +0 -0
package/cli/templates/api/controllers/userController.js +0 -13
package/cli/templates/api/middlewares/logger.js +0 -6
package/utils/.gitkeep +0 -0

package/core/errorHandler.js ADDED Viewed

@@ -0,0 +1,139 @@
+// core/errorHandler.js
+// Generic error handling middleware factory for Kaelum.
+//
+// Exports:
+//   - module.exports = errorHandlerFactory
+//   - module.exports.errorHandler = errorHandlerFactory
+//
+// Usage:
+//   const errorHandler = require('./core/errorHandler');
+//   app.use(errorHandler({ exposeStack: false }));
+//
+// Options:
+//   - exposeStack: boolean (default false) -> include stack trace in JSON when true
+//   - logger: function(err, req, info?) optional -> custom logger
+//   - onError: function(err, req, res) optional -> hook called before sending response
+//
+// Response JSON shape:
+//   { error: { message, code, ...(stack) } }
+// Status chosen from err.status || err.statusCode || 500
+/**
+ * @param {Object} options
+ * @param {boolean} [options.exposeStack=false] - include stack trace in responses
+ * @param {Function} [options.logger] - optional logger function: logger(err, req, info)
+ * @param {Function} [options.onError] - hook called before sending response: onError(err, req, res)
+ * @returns {Function} express error-handling middleware (err, req, res, next)
+ */
+function errorHandlerFactory(options = {}) {
+  const { exposeStack = false, logger = null, onError = null } = options || {};
+  /**
+   * Default logger used when no custom logger is provided.
+   * @param {Error|any} err
+   * @param {Object} req
+   */
+  function defaultLog(err, req) {
+    const status =
+      err && (err.status || err.statusCode)
+        ? err.status || err.statusCode
+        : 500;
+    if (status >= 500) {
+      if (err && err.stack) console.error(err.stack);
+      else console.error(err);
+    } else {
+      if (err && err.message) console.warn(err.message);
+      else console.warn(err);
+    }
+  }
+  return function errorHandler(err, req, res, next) {
+    // If headers already sent, fall back to default express handler
+    if (res.headersSent) {
+      return next(err);
+    }
+    // normalize non-error values (e.g., throw "string")
+    const normalizedErr =
+      err instanceof Error
+        ? err
+        : new Error(typeof err === "string" ? err : "Unknown error");
+    // determine HTTP status
+    const status =
+      err && (err.status || err.statusCode)
+        ? err.status || err.statusCode
+        : 500;
+    // prepare payload
+    const payload = {
+      error: {
+        message:
+          (err && (err.message || err.msg)) ||
+          normalizedErr.message ||
+          "Internal Server Error",
+        code: err && err.code ? err.code : "INTERNAL_ERROR",
+      },
+    };
+    if (exposeStack && normalizedErr && normalizedErr.stack) {
+      payload.error.stack = normalizedErr.stack;
+    }
+    // logging: prefer custom logger if provided
+    try {
+      if (typeof logger === "function") {
+        // allow custom logger to receive (err, req, { status })
+        logger(normalizedErr, req, { status });
+      } else {
+        defaultLog(normalizedErr, req);
+      }
+    } catch (logErr) {
+      // don't crash if logger fails
+      console.error("Kaelum errorHandler: logger threw an error", logErr);
+    }
+    // onError hook (e.g., report to external service)
+    try {
+      if (typeof onError === "function") {
+        try {
+          onError(normalizedErr, req, res);
+        } catch (hookErr) {
+          // don't block response if hook fails
+          console.error("Kaelum errorHandler: onError hook threw", hookErr);
+        }
+      }
+    } catch (_) {
+      // ignore
+    }
+    // Respond according to Accept header: JSON preferred, fallback to text/html
+    if (req && req.accepts && req.accepts("html") && !req.accepts("json")) {
+      // simple HTML response for browsers preferring HTML
+      const title = `Error ${status}`;
+      const body = `
+        <!doctype html>
+        <html>
+          <head><meta charset="utf-8"/><title>${title}</title></head>
+          <body>
+            <h1>${title}</h1>
+            <p>${payload.error.message}</p>
+            ${
+              exposeStack && payload.error.stack
+                ? `<pre>${payload.error.stack}</pre>`
+                : ""
+            }
+          </body>
+        </html>`;
+      res.status(status).type("html").send(body);
+      return;
+    }
+    // default: JSON response
+    res.status(status).json(payload);
+  };
+}
+// Export both default and named to keep compatibility with different import styles
+module.exports = errorHandlerFactory;
+module.exports.errorHandler = errorHandlerFactory;

package/core/healthCheck.js ADDED Viewed

@@ -0,0 +1,204 @@
+// core/healthCheck.js
+// Kaelum - health check helper
+//
+// Exports a factory function to register a health (liveness/readiness) endpoint.
+//
+// Usage examples:
+//   const registerHealth = require('./core/healthCheck');
+//   // simple
+//   registerHealth(app);
+//   // with options
+//   registerHealth(app, {
+//     path: '/health',
+//     readinessCheck: async () => {
+//       // custom checks (e.g. DB ping). Return { ok: true, details: { ... } } or { ok: false, details: {...} }
+//       const ok = await db.ping();
+//       return { ok, details: { db: ok } };
+//     },
+//     include: { uptime: true, pid: true, env: true, timestamp: true },
+//     replace: true
+//   });
+const DEFAULT_PATH = "/health";
+/**
+ * @typedef {Object} HealthOptions
+ * @property {string} [path] - Endpoint path (default '/health')
+ * @property {string} [method] - HTTP method for health endpoint (default 'get')
+ * @property {boolean} [replace] - If true and a previous Kaelum-installed endpoint exists, replace it (default false)
+ * @property {Function} [readinessCheck] - Optional async function that returns { ok: boolean, details?: Object }
+ * @property {Object} [include] - Which fields to include in payload. Defaults to all true.
+ * @property {boolean} [include.uptime]
+ * @property {boolean} [include.pid]
+ * @property {boolean} [include.env]
+ * @property {boolean} [include.timestamp]
+ * @property {boolean} [include.metrics] - reserved for future metrics (default false)
+ */
+/**
+ * Check if the same route path+method already exists in the app router.
+ * Only inspects Kaelum-installed layers conservatively.
+ * @param {Object} app - express app
+ * @param {string} path
+ * @param {string} method
+ * @returns {boolean}
+ */
+function routeExists(app, path, method) {
+  try {
+    if (!app || !app._router || !Array.isArray(app._router.stack)) return false;
+    return app._router.stack.some((layer) => {
+      if (!layer || !layer.route) return false;
+      if (layer.route.path !== path) return false;
+      return (
+        !!layer.route.methods && !!layer.route.methods[method.toLowerCase()]
+      );
+    });
+  } catch (e) {
+    // if internal inspection fails, be conservative and return false
+    return false;
+  }
+}
+/**
+ * Register a health check endpoint on the provided Express/Kaelum app.
+ * @param {Object} app - Express/Kaelum app instance
+ * @param {HealthOptions|string} [opts] - options or a string path
+ * @returns {Function} the handler function created (useful for tests)
+ */
+function registerHealth(app, opts = {}) {
+  if (!app || typeof app.get !== "function") {
+    throw new Error("Invalid app instance: cannot register health check");
+  }
+  // allow shorthand: passing a string path
+  const options =
+    typeof opts === "string"
+      ? { path: opts }
+      : Object.assign(
+          {
+            path: DEFAULT_PATH,
+            method: "get",
+            replace: false,
+            readinessCheck: null,
+            include: {
+              uptime: true,
+              pid: true,
+              env: true,
+              timestamp: true,
+              metrics: false,
+            },
+          },
+          opts || {}
+        );
+  // normalize path and method
+  let p =
+    options.path && typeof options.path === "string"
+      ? options.path
+      : DEFAULT_PATH;
+  if (!p.startsWith("/")) p = "/" + p;
+  const method = (options.method || "get").toLowerCase();
+  // if route exists and replace is false -> skip registration
+  if (routeExists(app, p, method) && !options.replace) {
+    return null;
+  }
+  // if replace requested, attempt to remove prior Kaelum-installed handler
+  if (options.replace) {
+    try {
+      // remove layers that match exactly the route path and method
+      if (app._router && Array.isArray(app._router.stack)) {
+        app._router.stack = app._router.stack.filter((layer) => {
+          if (!layer || !layer.route) return true; // keep non-route layers
+          if (layer.route.path !== p) return true; // keep other routes
+          // keep only layers that do not match the method we want to replace
+          return !layer.route.methods || !layer.route.methods[method];
+        });
+      }
+    } catch (e) {
+      // ignore removal errors - continue to register anyway
+    }
+  } else {
+    // if route exists and replace === false we already returned above
+  }
+  /**
+   * The handler performs an optional readinessCheck. If readinessCheck returns
+   * { ok: false } then status 503 is sent, otherwise 200.
+   * readinessCheck may be synchronous or asynchronous.
+   */
+  const handler = async (req, res) => {
+    // default payload base
+    const payload = {
+      status: "OK",
+    };
+    // include optional fields
+    const inc = options.include || {};
+    if (inc.uptime) payload.uptime = process.uptime();
+    if (inc.pid) payload.pid = process.pid;
+    if (inc.env) payload.env = process.env.NODE_ENV || "development";
+    if (inc.timestamp) payload.timestamp = Date.now();
+    // readiness check (optional)
+    if (typeof options.readinessCheck === "function") {
+      try {
+        const result = await Promise.resolve(options.readinessCheck(req));
+        // result expected to be { ok: boolean, details?: object } or boolean
+        let ok = true;
+        let details = undefined;
+        if (typeof result === "boolean") {
+          ok = result;
+        } else if (result && typeof result === "object") {
+          ok = !!result.ok;
+          details = result.details;
+        } else {
+          // unrecognized result -> consider as ok
+          ok = true;
+        }
+        if (!ok) {
+          payload.status = "FAIL";
+          if (details) payload.details = details;
+          return res.status(503).json(payload);
+        }
+      } catch (err) {
+        // readiness check threw -> respond 503 with error info (don't expose stack)
+        payload.status = "FAIL";
+        payload.details = {
+          message: err && err.message ? err.message : "readiness check error",
+        };
+        return res.status(503).json(payload);
+      }
+    }
+    // success
+    return res.status(200).json(payload);
+  };
+  // register route on app
+  try {
+    // attach a marker so we can detect Kaelum-installed static handlers if needed
+    app[method](p, handler);
+  } catch (e) {
+    throw new Error(
+      `Failed to register health route ${method.toUpperCase()} ${p}: ${
+        e.message
+      }`
+    );
+  }
+  // store reference in locals for future inspection/removal
+  try {
+    app.locals = app.locals || {};
+    app.locals._kaelum_health = app.locals._kaelum_health || [];
+    app.locals._kaelum_health.push({ path: p, method, handler });
+  } catch (_) {
+    // ignore locals storage errors
+  }
+  return handler;
+}
+module.exports = registerHealth;

package/core/redirect.js ADDED Viewed

@@ -0,0 +1,177 @@
+// core/redirect.js
+// Kaelum - redirect helper
+//
+// This module provides a flexible helper to register one or many redirect routes
+// in a Kaelum/Express app. It stores references to Kaelum-installed redirect
+// handlers so future calls can remove only the handlers Kaelum created (safe removal).
+//
+// Usage examples:
+//   const redirect = require('./core/redirect');
+//   // simple single redirect
+//   redirect(app, '/old', '/new', 301);
+//
+//   // as map (object)
+//   redirect(app, { '/old': '/new', '/a': '/b' });
+//
+//   // as array of objects
+//   redirect(app, [
+//     { from: '/x', to: '/y', status: 302 },
+//     { from: '/a', to: '/b' }
+//   ]);
+//
+//   // returns array of registered entries or null if nothing registered.
+function normalizePath(p) {
+  if (!p) return "/";
+  if (typeof p !== "string") throw new Error("path must be a string");
+  return p.startsWith("/") ? p : "/" + p;
+}
+function normalizeStatus(s) {
+  const n = Number(s);
+  if (!Number.isFinite(n)) return 302;
+  // limit to common redirect codes 300-399
+  if (n < 300 || n >= 400) return 302;
+  return Math.floor(n);
+}
+function ensureLocals(app) {
+  app.locals = app.locals || {};
+  app.locals._kaelum_redirects = app.locals._kaelum_redirects || [];
+}
+/**
+ * Safely remove a previously registered Kaelum redirect handler for a path.
+ * Only removes handlers that we registered (tracked in app.locals._kaelum_redirects).
+ * @param {Object} app
+ * @param {string} path
+ */
+function removeKaelumRedirectsForPath(app, path) {
+  if (!app || !app._router || !Array.isArray(app._router.stack)) return;
+  if (!app.locals || !Array.isArray(app.locals._kaelum_redirects)) return;
+  // find tracked entries for this path
+  const tracked = app.locals._kaelum_redirects.filter((r) => r.path === path);
+  if (tracked.length === 0) return;
+  // remove router layers whose handler matches tracked.handler
+  app._router.stack = app._router.stack.filter((layer) => {
+    // keep everything that is not a route
+    if (!layer || !layer.route) return true;
+    if (layer.route.path !== path) return true;
+    // check if route stack contains a tracked handler
+    const handlers = layer.route.stack || [];
+    for (const entry of tracked) {
+      for (const h of handlers) {
+        if (h && h.handle === entry.handler) {
+          // drop this layer (do not keep)
+          return false;
+        }
+      }
+    }
+    // if none of the tracked handlers matched, keep the layer
+    return true;
+  });
+  // remove tracked entries for that path from locals
+  app.locals._kaelum_redirects = app.locals._kaelum_redirects.filter(
+    (r) => r.path !== path
+  );
+}
+/**
+ * Register a single redirect handler and track it in app.locals.
+ * @param {Object} app
+ * @param {string} from
+ * @param {string} to
+ * @param {number} status
+ * @returns {{ path: string, to: string, status: number }}
+ */
+function registerSingleRedirect(app, from, to, status) {
+  const path = normalizePath(from);
+  const target = to;
+  const code = normalizeStatus(status);
+  // create handler and register GET route
+  const handler = function (req, res) {
+    res.redirect(code, target);
+  };
+  // add to express
+  app.get(path, handler);
+  // track it
+  ensureLocals(app);
+  app.locals._kaelum_redirects.push({
+    path,
+    handler,
+    to: target,
+    status: code,
+  });
+  return { path, to: target, status: code };
+}
+/**
+ * Main redirect export.
+ * Accepts:
+ *  - (app, from, to, status?)
+ *  - (app, mapObject) where mapObject is { from: to, ... }
+ *  - (app, array) where array contains { from, to, status? } entries
+ *
+ * @param {Object} app - Express/Kaelum app
+ * @param {string|Object|Array} fromOrMap - path string or map/object or array of mappings
+ * @param {string|number} [toOrStatus] - when calling with (app, from, to, status) this is the "to" parameter
+ * @param {number} [maybeStatus] - optional status when calling the 4-arg form
+ * @returns {Array|null} list of registered redirect entries or null if none
+ */
+function redirect(app, fromOrMap, toOrStatus, maybeStatus) {
+  if (!app || typeof app.get !== "function") {
+    throw new Error("Invalid app instance: cannot register redirect");
+  }
+  ensureLocals(app);
+  const registered = [];
+  // Helper: register one mapping (and remove previous Kaelum mapping for that path)
+  function applyMapping(from, to, status) {
+    const path = normalizePath(from);
+    // remove previously Kaelum-registered redirects for same path (safe removal)
+    removeKaelumRedirectsForPath(app, path);
+    // register and track
+    const res = registerSingleRedirect(app, path, to, status);
+    registered.push(res);
+  }
+  // Determine input shape
+  if (typeof fromOrMap === "string") {
+    // form: redirect(app, '/old', '/new', 302)
+    const from = fromOrMap;
+    const to = typeof toOrStatus === "string" ? toOrStatus : "/";
+    const status =
+      typeof maybeStatus !== "undefined" ? maybeStatus : toOrStatus;
+    applyMapping(from, to, status);
+  } else if (Array.isArray(fromOrMap)) {
+    // array of objects: [{ from, to, status }]
+    for (const item of fromOrMap) {
+      if (!item) continue;
+      const from = item.from || item.path || null;
+      const to = item.to || item.target || null;
+      const status = item.status || item.code || 302;
+      if (!from || !to) continue;
+      applyMapping(from, to, status);
+    }
+  } else if (fromOrMap && typeof fromOrMap === "object") {
+    // object map: { '/old': '/new', 'a': 'b' }
+    for (const k of Object.keys(fromOrMap)) {
+      applyMapping(k, fromOrMap[k], 302);
+    }
+  } else {
+    throw new Error("Invalid arguments for redirect");
+  }
+  return registered.length ? registered : null;
+}
+module.exports = redirect;