kaelum 1.8.1 → 1.8.3

package/README.md

@@ -84,11 +84,14 @@ app.start();
 ## ⚡ Quick Start
 
 ```bash
-# Scaffold a new project
-npx kaelum create my-app --template web
+# Scaffold a new project (interactive — picks language + template)
+npx kaelum create my-app
 
-# Or an API project
-npx kaelum create my-api --template api
+# Or non-interactive with a specific template
+npx kaelum create my-app --template js-web
+npx kaelum create my-api --template js-api
+npx kaelum create my-app --template ts-web
+npx kaelum create my-api --template ts-api
 
 # Run it
 cd my-app && npm install && npm start
@@ -96,21 +99,35 @@ cd my-app && npm install && npm start
 
 > No global install needed — `npx` handles everything.
 
+### Available Templates
+
+| Template | Language   | Description                               |
+| -------- | ---------- | ----------------------------------------- |
+| `js-web` | JavaScript | MVC with views & static files             |
+| `js-api` | JavaScript | REST API ready                            |
+| `ts-web` | TypeScript | MVC with views & static files (tsx + tsc) |
+| `ts-api` | TypeScript | REST API ready (tsx + tsc)                |
+
+> Legacy aliases `web` and `api` map to `js-web` and `js-api`.
+
 ---
 
 ## ✨ Features
 
-| Feature | Description |
-|---------|-------------|
-| 🚀 **Zero-Config Start** | JSON parsing, static files, EJS views — all pre-configured |
-| 🌳 **Tree Routing** | Recursive nested routes with `addRoute` and `apiRoute` |
-| 🔒 **Security Built-in** | One-toggle CORS, Helmet, and XSS protection |
-| 🛠️ **CLI Scaffolding** | `npx kaelum create` with Web and API templates |
-| 📦 **Dual Module** | Works with both `require()` and `import` |
-| 🏥 **Health Checks** | Built-in `/health` endpoint with readiness probes |
-| ⚡ **Middleware Manager** | Track, add, and remove middleware programmatically |
-| 🔄 **Redirects** | Declarative redirect maps with single, array, or object syntax |
-| 🛡️ **Error Handler** | Standardized JSON/HTML error responses with hooks |
+| Feature                  | Description                                                    |
+| ------------------------ | -------------------------------------------------------------- |
+| 🚀 **Zero-Config Start**  | JSON parsing, static files, EJS views — all pre-configured     |
+| 🌳 **Tree Routing**       | Recursive nested routes with `addRoute` and `apiRoute`         |
+| 🔒 **Security Built-in**  | One-toggle CORS, Helmet, and XSS protection                    |
+| 🛠️ **CLI Scaffolding**    | `npx kaelum create` with JS and TS templates (web + API)       |
+| 📦 **Dual Module**        | Works with both `require()` and `import`                       |
+| 🏥 **Health Checks**      | Built-in `/health` endpoint with readiness probes              |
+| ⚡ **Middleware Manager** | Track, add, and remove middleware programmatically             |
+| 🔄 **Redirects**          | Declarative redirect maps with single, array, or object syntax |
+| 🛡️ **Error Handler**      | Standardized JSON/HTML error responses with hooks              |
+| ⏱️ **Rate Limiting**      | Built-in zero-dependency in-memory rate limiter                |
+| 🧩 **Plugin System**      | Register and manage plugins with dedup guard                   |
+| 🔌 **Graceful Shutdown**  | Signal handling, connection draining, and cleanup hooks        |
 
 ---
 
@@ -145,6 +162,8 @@ app.setConfig({
   bodyParser: true,     // JSON + urlencoded (default: on)
   port: 3000,           // preferred port
   views: { engine: "ejs", path: "./views" },
+  rateLimit: true,      // enable rate limiting (default: 100 req/15 min)
+  gracefulShutdown: { timeout: 10000 }, // signal handling + cleanup
 });
 ```
 
@@ -185,20 +204,32 @@ app.apiRoute("products", {
 app.start(3000);                              // start server
 app.setMiddleware("/admin", authMiddleware);   // scoped middleware
 app.redirect("/old", "/new", 301);            // redirects
-app.healthCheck("/health");                   // health endpoint
-app.useErrorHandler({ exposeStack: false });  // error handling
+app.healthCheck("/health");                    // health endpoint
+app.useErrorHandler({ exposeStack: false });   // error handling
+app.plugin(myPlugin, { key: "value" });        // register plugin
+app.onShutdown(() => cleanup());               // shutdown hook
+app.close();                                   // graceful close
+```
+
+### CLI Commands
+
+```bash
+kaelum create              # interactive project scaffolding
+kaelum --version           # show installed version
+kaelum info                # show environment details
+kaelum help                # show all commands
 ```
 
 ---
 
 ## 📁 Project Templates
 
-### Web Template
+### JavaScript Web (`js-web`)
 
 ```
 my-web-app/
 ├── public/            # Static assets
-├── views/             # EJS templates
+├── views/             # HTML templates
 ├── controllers/       # Route logic (MVC)
 ├── middlewares/        # Custom middleware
 ├── routes.js          # Route definitions
@@ -206,7 +237,7 @@ my-web-app/
 └── package.json
 ```
 
-### API Template
+### JavaScript API (`js-api`)
 
 ```
 my-api/
@@ -217,6 +248,34 @@ my-api/
 └── package.json
 ```
 
+### TypeScript Web (`ts-web`)
+
+```
+my-web-app/
+├── public/            # Static assets
+├── views/             # HTML templates
+├── src/
+│   ├── controllers/   # Route logic (MVC)
+│   ├── middlewares/    # Custom middleware
+│   ├── routes.ts      # Route definitions
+│   └── app.ts         # Entry point
+├── tsconfig.json
+└── package.json
+```
+
+### TypeScript API (`ts-api`)
+
+```
+my-api/
+├── src/
+│   ├── controllers/   # Business logic
+│   ├── middlewares/    # Auth, validation
+│   ├── routes.ts      # API routes
+│   └── app.ts         # Entry point
+├── tsconfig.json
+└── package.json
+```
+
 ---
 
 ## 🧪 Testing
@@ -239,10 +298,10 @@ See also: [Code of Conduct](https://github.com/kaelumjs/.github/blob/main/CODE_O
 
 ## 🌐 Ecosystem
 
-| Package | Description |
-|---------|-------------|
-| [kaelum](https://www.npmjs.com/package/kaelum) | Core framework |
-| [kaelumjs/docs](https://github.com/kaelumjs/docs) | Documentation site |
+| Package                                                 | Description                |
+| ------------------------------------------------------- | -------------------------- |
+| [kaelum](https://www.npmjs.com/package/kaelum)          | Core framework             |
+| [kaelumjs/docs](https://github.com/kaelumjs/docs)       | Documentation site         |
 | [kaelumjs/.github](https://github.com/kaelumjs/.github) | Shared community standards |
 
 ---

package/cli/templates/js/api/controllers/usersController.js

@@ -2,8 +2,8 @@
 // Simple in-memory controller for Kaelum API demonstration
 
 const users = [
-  { id: 1, name: "Maria", role: "admin" },
-  { id: 2, name: "Joao", role: "user" },
+  { id: 1, name: "Alice", role: "admin" },
+  { id: 2, name: "Bob", role: "user" },
 ];
 
 exports.list = (req, res) => res.json(users);
@@ -15,7 +15,7 @@ exports.create = (req, res) => {
 };
 
 exports.get = (req, res) => {
-  const user = users.find((u) => u.id == req.params.id);
+  const user = users.find((u) => u.id === Number(req.params.id));
   return user ? res.json(user) : res.status(404).json({ error: "User not found" });
 };
 

package/cli/templates/js/api/routes.js

@@ -1,6 +1,7 @@
 // routes.js
 const users = require("./controllers/usersController");
 const auth = require("./middlewares/authMock");
+const { version } = require("./package.json");
 
 module.exports = (app) => {
   // Global middleware for /users path
@@ -28,6 +29,6 @@ module.exports = (app) => {
 
   // Metadata endpoint
   app.addRoute("/meta", {
-    get: (req, res) => res.json({ version: "1.8.0", framework: "Kaelum" }),
+    get: (req, res) => res.json({ version, framework: "Kaelum" }),
   });
 };

package/cli/templates/js/web/views/index.html

@@ -1,49 +1,52 @@
 <!DOCTYPE html>
 <html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width,initial-scale=1" />
-    <title>Kaelum — Hello</title>
-    <link rel="stylesheet" href="/style.css" />
-  </head>
-  <body>
-    <main class="container">
-      <header>
-        <h1>Kaelum.js</h1>
-        <p class="subtitle">
-          Minimalist framework for Web Apps &amp; APIs — Demo Template
-        </p>
-      </header>
 
-      <section class="content">
-        <h2>Welcome 👋</h2>
-        <p>
-          This template was automatically generated by the
-          <strong>Kaelum</strong> CLI.
-        </p>
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <title>Kaelum — Hello</title>
+  <link rel="stylesheet" href="/style.css" />
+</head>
 
-        <div class="cards">
-          <div class="card">
-            <h3>Routes</h3>
-            <p>
-              Available routes: <code>/</code>, <code>/about</code>, <code>/about/team</code>,
-              <code>/dashboard</code>, <code>/dashboard/settings</code>.
-            </p>
-          </div>
-          <div class="card">
-            <h3>Security</h3>
-            <p>CORS and Helmet are enabled via <code>app.setConfig</code>.</p>
-          </div>
-          <div class="card">
-            <h3>Health Check</h3>
-            <p>Built-in health endpoint at <code>/health</code>.</p>
-          </div>
+<body>
+  <main class="container">
+    <header>
+      <h1>Kaelum.js</h1>
+      <p class="subtitle">
+        Minimalist framework for Web Apps &amp; APIs — Demo Template
+      </p>
+    </header>
+
+    <section class="content">
+      <h2>Welcome 👋</h2>
+      <p>
+        This template was automatically generated by the
+        <strong>Kaelum</strong> CLI.
+      </p>
+
+      <div class="cards">
+        <div class="card">
+          <h3>Routes</h3>
+          <p>
+            Available routes: <code>/</code>, <code>/about</code>, <code>/about/team</code>,
+            <code>/dashboard</code>, <code>/dashboard/settings</code>.
+          </p>
+        </div>
+        <div class="card">
+          <h3>Security</h3>
+          <p>CORS and Helmet are enabled via <code>app.setConfig</code>.</p>
         </div>
+        <div class="card">
+          <h3>Health Check</h3>
+          <p>Built-in health endpoint at <code>/health</code>.</p>
+        </div>
+      </div>
+
+      <p class="small">
+        Generated by Kaelum CLI
+      </p>
+    </section>
+  </main>
+</body>
 
-        <p class="small">
-          Generated by Kaelum CLI &bull; Kaelum v1.8.0
-        </p>
-      </section>
-    </main>
-  </body>
-</html>
+</html>

package/cli/templates/ts/api/src/controllers/usersController.ts

@@ -8,8 +8,8 @@ interface User {
 }
 
 const users: User[] = [
-  { id: 1, name: "Maria", role: "admin" },
-  { id: 2, name: "Joao", role: "user" },
+  { id: 1, name: "Alice", role: "admin" },
+  { id: 2, name: "Bob", role: "user" },
 ];
 
 const list = (req: any, res: any): void => {

package/cli/templates/ts/api/src/routes.ts

@@ -1,5 +1,6 @@
 const users = require("./controllers/usersController");
 const { authMock } = require("./middlewares/authMock");
+const { version } = require("../../package.json");
 
 const routes = (app: any): void => {
   // Global middleware for /users path
@@ -28,7 +29,7 @@ const routes = (app: any): void => {
   // Metadata endpoint
   app.addRoute("/meta", {
     get: (req: any, res: any) =>
-      res.json({ version: "1.8.0", framework: "Kaelum" }),
+      res.json({ version, framework: "Kaelum" }),
   });
 };
 

package/cli/templates/ts/web/src/controllers/pagesController.ts

@@ -1,6 +1,9 @@
 // controllers/pagesController.ts
 const path = require("path");
 
+// Uses process.cwd() so it resolves from the project root in both
+// development (tsx) and production (compiled dist/), since views/
+// lives at the project root alongside src/.
 const view = (file: string): string => path.join(process.cwd(), "views", file);
 
 const home = (req: any, res: any): void => {

package/cli/templates/ts/web/views/index.html

@@ -1,49 +1,52 @@
 <!DOCTYPE html>
 <html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width,initial-scale=1" />
-    <title>Kaelum — Hello</title>
-    <link rel="stylesheet" href="/style.css" />
-  </head>
-  <body>
-    <main class="container">
-      <header>
-        <h1>Kaelum.js</h1>
-        <p class="subtitle">
-          Minimalist framework for Web Apps &amp; APIs — TypeScript Template
-        </p>
-      </header>
 
-      <section class="content">
-        <h2>Welcome 👋</h2>
-        <p>
-          This TypeScript template was automatically generated by the
-          <strong>Kaelum</strong> CLI.
-        </p>
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <title>Kaelum — Hello</title>
+  <link rel="stylesheet" href="/style.css" />
+</head>
 
-        <div class="cards">
-          <div class="card">
-            <h3>Routes</h3>
-            <p>
-              Available routes: <code>/</code>, <code>/about</code>, <code>/about/team</code>,
-              <code>/dashboard</code>, <code>/dashboard/settings</code>.
-            </p>
-          </div>
-          <div class="card">
-            <h3>TypeScript</h3>
-            <p>Run <code>npm run dev</code> for hot-reload via <code>tsx</code>.</p>
-          </div>
-          <div class="card">
-            <h3>Health Check</h3>
-            <p>Built-in health endpoint at <code>/health</code>.</p>
-          </div>
+<body>
+  <main class="container">
+    <header>
+      <h1>Kaelum.js</h1>
+      <p class="subtitle">
+        Minimalist framework for Web Apps &amp; APIs — TypeScript Template
+      </p>
+    </header>
+
+    <section class="content">
+      <h2>Welcome 👋</h2>
+      <p>
+        This TypeScript template was automatically generated by the
+        <strong>Kaelum</strong> CLI.
+      </p>
+
+      <div class="cards">
+        <div class="card">
+          <h3>Routes</h3>
+          <p>
+            Available routes: <code>/</code>, <code>/about</code>, <code>/about/team</code>,
+            <code>/dashboard</code>, <code>/dashboard/settings</code>.
+          </p>
+        </div>
+        <div class="card">
+          <h3>TypeScript</h3>
+          <p>Run <code>npm run dev</code> for hot-reload via <code>tsx</code>.</p>
         </div>
+        <div class="card">
+          <h3>Health Check</h3>
+          <p>Built-in health endpoint at <code>/health</code>.</p>
+        </div>
+      </div>
+
+      <p class="small">
+        Generated by Kaelum CLI
+      </p>
+    </section>
+  </main>
+</body>
 
-        <p class="small">
-          Generated by Kaelum CLI &bull; Kaelum v1.8.0
-        </p>
-      </section>
-    </main>
-  </body>
-</html>
+</html>

package/package.json

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