kaelum 1.4.8 → 1.5.0

package/core/plugin.js

@@ -0,0 +1,82 @@
+// core/plugin.js
+// Kaelum plugin registration system.
+// Plugins are functions that receive (app, options) and can add routes,
+// middleware, and config to the Kaelum app instance.
+
+/**
+ * Resolve the display name and dedup key for a plugin function.
+ * Checks fn.pluginName first, then fn.name, falls back to null (anonymous).
+ * @param {Function} fn
+ * @returns {string|null}
+ */
+function resolvePluginName(fn) {
+  if (typeof fn.pluginName === "string" && fn.pluginName) {
+    return fn.pluginName;
+  }
+  if (typeof fn.name === "string" && fn.name) {
+    return fn.name;
+  }
+  return null;
+}
+
+/**
+ * Register a plugin on the Kaelum app.
+ *
+ * @param {Object} app - Kaelum/Express app instance
+ * @param {Function} fn - Plugin function with signature (app, options) => void
+ * @param {Object} [options={}] - Options passed to the plugin
+ * @returns {Object} app - for chaining
+ * @throws {Error} if fn is not a function
+ * @throws {Error} if a named plugin with the same name is already registered
+ */
+function registerPlugin(app, fn, options = {}) {
+  if (typeof fn !== "function") {
+    throw new Error(
+      `Kaelum plugin: expected a function, got ${typeof fn}`
+    );
+  }
+
+  // ensure registry exists
+  if (!app.locals) app.locals = {};
+  if (!Array.isArray(app.locals._kaelum_plugins)) {
+    app.locals._kaelum_plugins = [];
+  }
+
+  const name = resolvePluginName(fn);
+
+  // duplicate guard for named plugins
+  if (name) {
+    const already = app.locals._kaelum_plugins.find((p) => p.name === name);
+    if (already) {
+      throw new Error(
+        `Kaelum plugin: "${name}" is already registered. ` +
+          `Each named plugin can only be registered once.`
+      );
+    }
+  }
+
+  // execute the plugin
+  fn(app, options);
+
+  // record in registry
+  app.locals._kaelum_plugins.push({
+    name: name || `anonymous_${app.locals._kaelum_plugins.length}`,
+    options,
+  });
+
+  return app;
+}
+
+/**
+ * Return the list of registered plugin names.
+ * @param {Object} app
+ * @returns {string[]}
+ */
+function getPlugins(app) {
+  if (!app.locals || !Array.isArray(app.locals._kaelum_plugins)) {
+    return [];
+  }
+  return app.locals._kaelum_plugins.map((p) => p.name);
+}
+
+module.exports = { registerPlugin, getPlugins };

package/createApp.js

@@ -19,6 +19,7 @@ const { errorHandler } = require("./core/errorHandler");
 const registerHealth = require("./core/healthCheck");
 const redirect = require("./core/redirect");
 const { removeMiddlewareByFn } = require("./core/utils");
+const { registerPlugin, getPlugins } = require("./core/plugin");
 
 function createApp() {
   const app = express();
@@ -29,6 +30,7 @@ function createApp() {
   // ensure locals object and initial persisted config
   app.locals = app.locals || {};
   app.locals.kaelumConfig = app.locals.kaelumConfig || {};
+  app.locals._kaelum_plugins = [];
   // persist baseline config so app.get("kaelum:config") is always available
   app.set("kaelum:config", app.locals.kaelumConfig);
 
@@ -169,6 +171,17 @@ function createApp() {
   // alias for convenience
   app.errorHandler = app.useErrorHandler;
 
+  // ---------------------------
+  // Plugin system
+  // ---------------------------
+  app.plugin = function (fn, options) {
+    return registerPlugin(app, fn, options);
+  };
+
+  app.getPlugins = function () {
+    return getPlugins(app);
+  };
+
   return app;
 }
 

package/index.d.ts

@@ -53,6 +53,9 @@ interface RouteHandlers {
   [subpath: string]: any;
 }
 
+/** Plugin function signature */
+type KaelumPlugin = (app: KaelumApp, options?: Record<string, any>) => void;
+
 interface KaelumApp extends Express {
   /** Configure Kaelum features (cors, helmet, static, logs, etc.) */
   setConfig(options: KaelumConfig): KaelumConfig;
@@ -93,6 +96,12 @@ interface KaelumApp extends Express {
 
   /** Remove static file serving */
   removeStatic(): KaelumConfig;
+
+  /** Register a plugin */
+  plugin(fn: KaelumPlugin, options?: Record<string, any>): KaelumApp;
+
+  /** List registered plugin names */
+  getPlugins(): string[];
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaelum",
-  "version": "1.4.8",
+  "version": "1.5.0",
   "description": "A minimalist Node.js framework for building web pages and APIs with simplicity and speed.",
   "main": "index.js",
   "types": "index.d.ts",