@mkgabri18/mini-serve 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# mini-serve
+
+`mini-serve` è un micro-framework HTTP ultra-leggero e **zero-dependency** per Node.js. È nato come alternativa minimale e nativa a Express per creare API REST, CRUD e server web veloci, mantenendo il pieno controllo sulle performance e sulla configurazione dei middleware.
+
+---
+
+## Indice
+1. [Caratteristiche principali](#caratteristiche-principali)
+2. [Guida: Come usarlo in un nuovo progetto da zero](#guida-come-usarlo-in-un-nuovo-progetto-da-zero)
+3. [Guida all'API](#guida-allapi)
+4. [Gestione dei Middleware](#gestione-dei-middleware)
+5. [Licenza](#licenza)
+
+---
+
+## Caratteristiche principali
+
+* 🚀 **Zero dipendenze esterne**: Utilizza esclusivamente i moduli nativi di Node.js (es. `node:http`, `node:fs`).
+* 🛣️ **Router Express-like**: Supporto nativo per rotte HTTP (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`) e parametri dinamici nell'URL (es. `/api/users/:id`).
+* ⚙️ **Modularità Opt-In**: I middleware built-in (body parser, request/response enhancers, logging) sono disattivati o attivabili a piacimento.
+* 🛡️ **Leggero e Sicuro**: Include un body parser con limite integrato di 1MB sui payload per prevenire attacchi di tipo DOS.
+
+---
+
+## Guida: Come usarlo in un nuovo progetto da zero
+
+Ecco i passaggi da seguire per creare un nuovo progetto ed utilizzare `mini-serve`.
+
+### Step 1: Inizializza il progetto Node.js
+Crea una nuova cartella per il tuo progetto e inizializzala tramite il terminale:
+```bash
+mkdir mio-nuovo-progetto
+cd mio-nuovo-progetto
+npm init -y
+```
+
+### Step 2: Abilita i moduli ES (ESM)
+Apri il file `package.json` appena generato e aggiungi la riga `"type": "module"`. Questo passaggio è fondamentale in quanto `mini-serve` utilizza la sintassi moderna degli import di ES6:
+```json
+{
+  "name": "mio-nuovo-progetto",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  }
+}
+```
+
+### Step 3: Installa `mini-serve`
+Installa il pacchetto tramite npm (puoi installarlo localmente o puntare al percorso se lo stai testando localmente):
+```bash
+npm install mini-serve
+```
+
+### Step 4: Crea il file del Server (`index.js`)
+Crea un file chiamato `index.js` nella root del tuo progetto e scrivi il seguente codice di esempio:
+
+```javascript
+import http from 'node:http';
+import { createServer } from 'mini-serve';
+import { notFoundHandler, globalErrorHandler } from 'mini-serve/middlewares';
+
+// 1. Inizializza il server con le opzioni desiderate
+const app = createServer({
+  useEnhancers: true,  // Abilita res.json(), res.status() e req.query
+  useBodyParser: true, // Parsa automaticamente il JSON per POST/PUT/PATCH
+  useLogger: true      // Mostra i log delle richieste in console
+});
+
+// 2. Definisci le tue rotte
+app.get('/', (req, res) => {
+  res.status(200).json({ message: 'Benvenuto nel mio nuovo server agnostico!' });
+});
+
+// Rotta con parametri dinamici
+app.get('/items/:id', (req, res) => {
+  const { id } = req.params;
+  res.status(200).json({ itemId: id, queryString: req.query });
+});
+
+// Rotta POST con gestione del body parificato
+app.post('/items', (req, res) => {
+  const payload = req.body;
+  res.status(201).json({ created: payload });
+});
+
+// 3. Registra i middleware di fallback per errori
+app.use(notFoundHandler);
+app.use(globalErrorHandler);
+
+// 4. Avvia il server tramite il modulo nativo http di Node.js
+const server = http.createServer(app.handler);
+
+server.listen(3000, () => {
+  console.log('Server avviato con successo su http://localhost:3000');
+});
+```
+
+### Step 5: Avvia il server
+Esegui il server tramite il terminale:
+```bash
+npm start
+```
+
+---
+
+## Guida all'API
+
+### `createServer(options)`
+Crea un'istanza dell'applicazione. Riceve un oggetto di configurazione per i middleware built-in:
+
+| Opzione | Tipo | Default | Descrizione |
+|---|---|---|---|
+| `useEnhancers` | `boolean` | `true` | Aggiunge `req.query`, `req.path`, `res.status(code)` e `res.json(data)`. |
+| `useBodyParser` | `boolean` | `true` | Parsa automaticamente i payload JSON in `req.body` (limite max: 1MB). Ritorna `413 Payload Too Large` se superato o `400 Bad Request` in caso di JSON malformato. |
+| `useLogger` | `boolean` | `false` | Stampa a console le richieste ricevute, lo status code e il tempo di elaborazione in ms (es: `[GET] /api/users - 200 (12ms)`). |
+
+L'oggetto `app` restituito espone i seguenti metodi:
+- `app.use(middleware)`: Registra un middleware globale o un gestore errori.
+- `app.get(path, ...handlers)`: Registra una rotta GET.
+- `app.post(path, ...handlers)`: Registra una rotta POST.
+- `app.put(path, ...handlers)`: Registra una rotta PUT.
+- `app.delete(path, ...handlers)`: Registra una rotta DELETE.
+- `app.patch(path, ...handlers)`: Registra una rotta PATCH.
+- `app.handler`: Il delegato nativo `(req, res)` da passare a `http.createServer()`.
+
+---
+
+## Gestione dei Middleware
+
+I middleware seguono il classico pattern `(req, res, next)`:
+
+```javascript
+app.use((req, res, next) => {
+  console.log('Richiesta in transito...');
+  next(); // Passa al middleware successivo
+});
+```
+
+### Gestione degli Errori globali
+Se passi un errore a `next(err)`, lo stack salterà tutti i middleware standard fino a raggiungere un middleware di errore, identificato dall'avere 4 parametri `(err, req, res, next)`:
+
+```javascript
+app.use((err, req, res, next) => {
+  console.error(err.stack);
+  res.writeHead(500, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ error: 'Errore generico del server' }));
+});
+```
+
+Puoi anche usare gli handler predefiniti importandoli da sottomodulo:
+```javascript
+import { notFoundHandler, globalErrorHandler } from 'mini-serve/middlewares';
+
+app.use(notFoundHandler);     // Gestisce i 404 per rotte non registrate
+app.use(globalErrorHandler);  // Cattura ed elabora in sicurezza gli errori generici
+```
+
+---
+
+## Licenza
+
+Questo progetto è rilasciato sotto licenza [MIT](LICENSE).

package/lib/index.js

@@ -0,0 +1,3 @@
+export { createServer } from './server.js';
+export { route } from './router.js';
+export * from './middlewares/index.js';

package/lib/middlewareRunner.js

@@ -0,0 +1,41 @@
+export function runMiddlewares(middlewares, req, res) {
+  function dispatch(i, err) {
+    if (i >= middlewares.length) return;
+
+    const middleware = middlewares[i];
+    let called = false;
+
+    function next(nextErr) {
+      if (called) {
+        console.error("next() called multiple times");
+        return;
+      }
+      called = true;
+      dispatch(i + 1, nextErr);
+    }
+
+    try {
+      if (err) {
+        // Stiamo gestendo un errore: invochiamo solo gli errori middleware (4 parametri)
+        if (middleware.length === 4) {
+          Promise.resolve(middleware(err, req, res, next)).catch(next);
+        } else {
+          // Salta il middleware normale e vai avanti trascinando l'errore
+          dispatch(i + 1, err);
+        }
+      } else {
+        // Funzionamento normale: invochiamo solo i middleware regolari (< 4 parametri)
+        if (middleware.length < 4) {
+          Promise.resolve(middleware(req, res, next)).catch(next);
+        } else {
+          // Salta l'error middleware
+          dispatch(i + 1, err);
+        }
+      }
+    } catch (caughtErr) {
+      next(caughtErr);
+    }
+  }
+
+  dispatch(0);
+}

package/lib/middlewares/bodyParser.js

@@ -0,0 +1,52 @@
+export function jsonBodyParser(req, res, next) {
+  // Parsiamo il body solo per le richieste che solitamente lo prevedono
+  if (["POST", "PUT", "PATCH"].includes(req.method)) {
+    let body = "";
+    const MAX_SIZE = 1 * 1024 * 1024; // 1 Megabyte
+    let limitExceeded = false;
+    
+    req.on("data", chunk => {
+      if (limitExceeded) return;
+
+      body += chunk;
+      if (body.length > MAX_SIZE) {
+        limitExceeded = true;
+        req.pause();
+
+        // Send 413 Payload Too Large response gracefully
+        res.status(413).json({ error: "Payload Too Large" });
+
+        // Destroy the socket on the next tick so Node has time to flush the response
+        setImmediate(() => {
+          req.destroy();
+        });
+      }
+    });
+
+    req.on("end", () => {
+      if (limitExceeded || req.destroyed) return;
+      
+      if (!body) {
+        req.body = {};
+        return next();
+      }
+      
+      try {
+        req.body = JSON.parse(body);
+        next();
+      } catch (err) {
+        const error = new Error("Invalid JSON Payload");
+        error.status = 400; // Bad Request
+        next(error);
+      }
+    });
+
+    req.on("error", (err) => {
+      if (limitExceeded) return;
+      next(err);
+    });
+  } else {
+    // Per le richieste come GET o DELETE, proseguiamo oltre ignorando il body
+    next();
+  }
+}

package/lib/middlewares/enhancers.js

@@ -0,0 +1,28 @@
+export function requestResponseEnhancer(req, res, next) {
+  // --- ENHANCE REQUEST ---
+  // Analizza l'URL includendo anche le query string (es. ?sort=asc)
+  const parsedUrl = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+  
+  // Salva il path "pulito" da eventuali query string (es. /notes invece di /notes?sort=asc)
+  req.path = parsedUrl.pathname; 
+  
+  // Salva i parametri estratti (es. { sort: 'asc' })
+  req.query = Object.fromEntries(parsedUrl.searchParams);   
+
+  // --- ENHANCE RESPONSE ---
+  // Aggiunge la scorciatoia per impostare lo status code a catena
+  res.status = function(code) {
+    res.statusCode = code;
+    return res;
+  };
+
+  // Aggiunge la scorciatoia per inviare JSON con i corretti Headers
+  res.json = function(data) {
+    if (!res.hasHeader("Content-Type")) {
+      res.setHeader("Content-Type", "application/json");
+    }
+    res.end(JSON.stringify(data));
+  };
+
+  next();
+}

package/lib/middlewares/errorHandlers.js

@@ -0,0 +1,16 @@
+export function notFoundHandler(req, res, next) {
+  res.writeHead(404, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ error: "Not Found" }));
+}
+
+export function globalErrorHandler(err, req, res, next) {
+  console.error("Global Error Caught:", err.message || err);
+
+  if (res.headersSent) {
+    return next(err); // Lascia che sia Node a gestire la chiusura forzata
+  }
+  
+  const statusCode = err.status || 500;
+  res.writeHead(statusCode, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ error: err.message || "Internal Server Error" }));
+}

package/lib/middlewares/index.js

@@ -0,0 +1,4 @@
+export { requestResponseEnhancer } from './enhancers.js';
+export { jsonBodyParser } from './bodyParser.js';
+export { logger } from './logger.js';
+export { notFoundHandler, globalErrorHandler } from './errorHandlers.js';

package/lib/middlewares/logger.js

@@ -0,0 +1,8 @@
+export function logger(req, res, next) {
+  const start = Date.now();
+  res.on("finish", () => {
+    const duration = Date.now() - start;
+    console.log(`[${req.method}] ${req.url} - ${res.statusCode} (${duration}ms)`);
+  });
+  next();
+}

package/lib/router.js

@@ -0,0 +1,56 @@
+export function route(method, pathDefinition, ...handlers) {
+  // Split the path definition into dynamic parameters and static parts,
+  // escaping regex special characters in static parts while extracting parameter names.
+  const paramNames = [];
+  const parts = pathDefinition.split(/(:[a-zA-Z0-9_]+)/);
+  const regexParts = parts.map(part => {
+    if (part.startsWith(":")) {
+      const paramName = part.slice(1);
+      paramNames.push(paramName);
+      return "([^/]+)";
+    }
+    // Escape regex characters in static path parts to avoid weak matches (like '.' matching any character)
+    return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  });
+  const pathRegex = new RegExp(`^${regexParts.join("")}/?$`);
+
+  return (req, res, next) => {
+    if (req.method === method) {
+      // Usiamo req.path (pulito dalle query) se disponibile, altrimenti req.url depurato
+      const urlToMatch = req.path || req.url.split('?')[0];
+      const match = urlToMatch.match(pathRegex);
+
+      if (match) {
+        // Estraiamo i valori dinamici (es. /notes/15 -> req.params.id = "15")
+        req.params = {};
+        paramNames.forEach((name, index) => {
+          req.params[name] = match[index + 1];
+        });
+
+        // Run route-specific handlers in sequence
+        let i = 0;
+        const runNext = (err) => {
+          if (err) {
+            return next(err); // Forward errors directly to global error handler
+          }
+          if (i < handlers.length) {
+            const handler = handlers[i++];
+            try {
+              Promise.resolve(handler(req, res, runNext)).catch(runNext);
+            } catch (caughtErr) {
+              runNext(caughtErr);
+            }
+          } else {
+            next(); // Handlers completed without sending a response, fallback to next outer middleware
+          }
+        };
+
+        runNext();
+        return; // Interrompiamo qui, la route è stata gestita
+      }
+    }
+    
+    // Se non c'è match, passiamo al prossimo middleware della catena
+    next();
+  };
+}

package/lib/server.js

@@ -0,0 +1,88 @@
+import { route } from "./router.js";
+import { runMiddlewares } from "./middlewareRunner.js";
+import { requestResponseEnhancer } from "./middlewares/enhancers.js";
+import { jsonBodyParser } from "./middlewares/bodyParser.js";
+import { logger } from "./middlewares/logger.js";
+
+/**
+ * Factory che crea l'istanza del server mini-serve.
+ * 
+ * @param {Object} [options] - Opzioni di configurazione dei middleware built-in.
+ * @param {boolean} [options.useEnhancers=true] - Se registrare il middleware che arricchisce req e res.
+ * @param {boolean} [options.useBodyParser=true] - Se registrare il parser JSON del body per POST/PUT/PATCH.
+ * @param {boolean} [options.useLogger=false] - Se abilitare il logger delle richieste in console.
+ * @returns {Object} Istanza dell'applicazione con i metodi per definire le rotte e registrare middleware.
+ */
+export function createServer(options = {}) {
+  const {
+    useEnhancers = true,
+    useBodyParser = true,
+    useLogger = false,
+  } = options;
+
+  const middlewares = [];
+
+  // Registrazione dei middleware built-in in base alle opzioni
+  if (useEnhancers) {
+    middlewares.push(requestResponseEnhancer);
+  }
+  if (useBodyParser) {
+    middlewares.push(jsonBodyParser);
+  }
+  if (useLogger) {
+    middlewares.push(logger);
+  }
+
+  const app = {
+    /**
+     * Registra un middleware generico nello stack.
+     */
+    use(fn) {
+      middlewares.push(fn);
+    },
+
+    /**
+     * Registra una rotta GET.
+     */
+    get(path, ...handler) {
+      middlewares.push(route("GET", path, ...handler));
+    },
+
+    /**
+     * Registra una rotta POST.
+     */
+    post(path, ...handler) {
+      middlewares.push(route("POST", path, ...handler));
+    },
+
+    /**
+     * Registra una rotta PUT.
+     */
+    put(path, ...handler) {
+      middlewares.push(route("PUT", path, ...handler));
+    },
+
+    /**
+     * Registra una rotta DELETE.
+     */
+    delete(path, ...handler) {
+      middlewares.push(route("DELETE", path, ...handler));
+    },
+
+    /**
+     * Registra una rotta PATCH.
+     */
+    patch(path, ...handler) {
+      middlewares.push(route("PATCH", path, ...handler));
+    },
+
+    /**
+     * Il delegato (req, res) da passare a http.createServer().
+     */
+    handler(req, res) {
+      runMiddlewares(middlewares, req, res);
+    },
+  };
+
+  return app;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mkgabri18/mini-serve",
+  "version": "0.1.0",
+  "description": "A tiny, zero-dependency HTTP framework for Node.js",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./middlewares": "./lib/middlewares/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mkgabri18/mini-serve.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mkgabri18/mini-serve/issues"
+  },
+  "homepage": "https://github.com/Mkgabri18/mini-serve#readme",
+  "files": [
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "node src/server.js",
+    "test": "node --test notes/notes.test.js"
+  },
+  "keywords": [
+    "http",
+    "framework",
+    "server",
+    "middleware",
+    "router",
+    "zero-dependency"
+  ],
+  "author": "",
+  "license": "MIT"
+}