@mkgabri18/mini-serve 0.1.0 → 0.1.2

package/README.md

@@ -1,44 +1,44 @@
 # 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.
+`mini-serve` is an ultra-lightweight, **zero-dependency** HTTP framework for Node.js. It is designed as a minimal, native alternative to Express for building REST APIs, CRUD services, and web servers while maintaining full control over performance and middleware configuration.
 
 ---
 
-## 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)
+## Table of Contents
+1. [Key Features](#key-features)
+2. [Guide: How to Use It in a New Project from Scratch](#guide-how-to-use-it-in-a-new-project-from-scratch)
+3. [API Guide](#api-guide)
+4. [Middleware Management](#middleware-management)
+5. [License](#license)
 
 ---
 
-## Caratteristiche principali
+## Key Features
 
-* 🚀 **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.
+* 🚀 **Zero external dependencies**: Built entirely on top of Node.js native modules (e.g. `node:http`, `node:fs`).
+* 🛣️ **Express-like Router**: Native support for HTTP methods (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`) and dynamic path parameters (e.g. `/api/users/:id`).
+* ⚙️ **Opt-In Modularity**: Built-in middlewares (body parser, request/response enhancers, logger) are configurable and can be enabled or disabled at will.
+* 🛡️ **Lightweight & Secure**: Includes a built-in JSON body parser with a default 1MB size limit to prevent potential DOS attacks.
 
 ---
 
-## Guida: Come usarlo in un nuovo progetto da zero
+## Guide: How to Use It in a New Project from Scratch
 
-Ecco i passaggi da seguire per creare un nuovo progetto ed utilizzare `mini-serve`.
+Follow these steps to create a new project and use `mini-serve`.
 
-### Step 1: Inizializza il progetto Node.js
-Crea una nuova cartella per il tuo progetto e inizializzala tramite il terminale:
+### Step 1: Initialize the Node.js project
+Create a new directory for your project and initialize it via terminal:
 ```bash
-mkdir mio-nuovo-progetto
-cd mio-nuovo-progetto
+mkdir my-new-project
+cd my-new-project
 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:
+### Step 2: Enable ES Modules (ESM)
+Open the newly generated `package.json` file and add the `"type": "module"` property. This step is critical since `mini-serve` uses modern ES6 import syntax:
 ```json
 {
-  "name": "mio-nuovo-progetto",
+  "name": "my-new-project",
   "version": "1.0.0",
   "type": "module",
   "scripts": {
@@ -47,118 +47,118 @@ Apri il file `package.json` appena generato e aggiungi la riga `"type": "module"
 }
 ```
 
-### Step 3: Installa `mini-serve`
-Installa il pacchetto tramite npm (puoi installarlo localmente o puntare al percorso se lo stai testando localmente):
+### Step 3: Install `@mkgabri18/mini-serve`
+Install the package using npm:
 ```bash
-npm install mini-serve
+npm install @mkgabri18/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:
+### Step 4: Create the Server File (`index.js`)
+Create a file named `index.js` in the root of your project and add the following sample code:
 
 ```javascript
 import http from 'node:http';
-import { createServer } from 'mini-serve';
-import { notFoundHandler, globalErrorHandler } from 'mini-serve/middlewares';
+import { createServer } from '@mkgabri18/mini-serve';
+import { notFoundHandler, globalErrorHandler } from '@mkgabri18/mini-serve/middlewares';
 
-// 1. Inizializza il server con le opzioni desiderate
+// 1. Initialize the server with the desired options
 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
+  useEnhancers: true,  // Enables res.json(), res.status(), and req.query
+  useBodyParser: true, // Automatically parses JSON body for POST/PUT/PATCH
+  useLogger: true      // Logs requests to the console
 });
 
-// 2. Definisci le tue rotte
+// 2. Define your routes
 app.get('/', (req, res) => {
-  res.status(200).json({ message: 'Benvenuto nel mio nuovo server agnostico!' });
+  res.status(200).json({ message: 'Welcome to my new agnostic server!' });
 });
 
-// Rotta con parametri dinamici
+// Route with dynamic path parameters
 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
+// POST route with body parser support
 app.post('/items', (req, res) => {
   const payload = req.body;
   res.status(201).json({ created: payload });
 });
 
-// 3. Registra i middleware di fallback per errori
+// 3. Register fallback and error handling middlewares
 app.use(notFoundHandler);
 app.use(globalErrorHandler);
 
-// 4. Avvia il server tramite il modulo nativo http di Node.js
+// 4. Start the server using Node.js native http module
 const server = http.createServer(app.handler);
 
 server.listen(3000, () => {
-  console.log('Server avviato con successo su http://localhost:3000');
+  console.log('Server successfully started at http://localhost:3000');
 });
 ```
 
-### Step 5: Avvia il server
-Esegui il server tramite il terminale:
+### Step 5: Start the server
+Run the server using your terminal:
 ```bash
 npm start
 ```
 
 ---
 
-## Guida all'API
+## API Guide
 
 ### `createServer(options)`
-Crea un'istanza dell'applicazione. Riceve un oggetto di configurazione per i middleware built-in:
+Creates an application instance. Accepts a configuration object for built-in middlewares:
 
-| Opzione | Tipo | Default | Descrizione |
+| Option | Type | Default | Description |
 |---|---|---|---|
-| `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()`.
+| `useEnhancers` | `boolean` | `true` | Injects `req.query`, `req.path`, `res.status(code)`, and `res.json(data)`. |
+| `useBodyParser` | `boolean` | `true` | Automatically parses JSON payloads into `req.body` (max limit: 1MB). Returns `413 Payload Too Large` if exceeded, or `400 Bad Request` if JSON is malformed. |
+| `useLogger` | `boolean` | `false` | Logs incoming requests, status code, and execution time in ms (e.g.: `[GET] /api/users - 200 (12ms)`). |
+
+The returned `app` object exposes the following methods:
+- `app.use(middleware)`: Registers a global middleware or an error-handling middleware.
+- `app.get(path, ...handlers)`: Registers a GET route.
+- `app.post(path, ...handlers)`: Registers a POST route.
+- `app.put(path, ...handlers)`: Registers a PUT route.
+- `app.delete(path, ...handlers)`: Registers a DELETE route.
+- `app.patch(path, ...handlers)`: Registers a PATCH route.
+- `app.handler`: The native callback `(req, res)` to pass to `http.createServer()`.
 
 ---
 
-## Gestione dei Middleware
+## Middleware Management
 
-I middleware seguono il classico pattern `(req, res, next)`:
+Middlewares follow the standard `(req, res, next)` pattern:
 
 ```javascript
 app.use((req, res, next) => {
-  console.log('Richiesta in transito...');
-  next(); // Passa al middleware successivo
+  console.log('Request received...');
+  next(); // Pass control to the next middleware
 });
 ```
 
-### 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)`:
+### Global Error Handling
+If you pass an error to `next(err)`, the middleware runner skips all standard middlewares to execute error-handling middlewares, which are identified by having 4 arguments `(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' }));
+  res.end(JSON.stringify({ error: 'Internal Server Error' }));
 });
 ```
 
-Puoi anche usare gli handler predefiniti importandoli da sottomodulo:
+You can also import and use the pre-built error handlers from their submodule:
 ```javascript
-import { notFoundHandler, globalErrorHandler } from 'mini-serve/middlewares';
+import { notFoundHandler, globalErrorHandler } from '@mkgabri18/mini-serve/middlewares';
 
-app.use(notFoundHandler);     // Gestisce i 404 per rotte non registrate
-app.use(globalErrorHandler);  // Cattura ed elabora in sicurezza gli errori generici
+app.use(notFoundHandler);     // Handles 404 for unregistered routes
+app.use(globalErrorHandler);  // Safely catches and processes uncaught errors
 ```
 
 ---
 
-## Licenza
+## License
 
-Questo progetto è rilasciato sotto licenza [MIT](LICENSE).
+This project is licensed under the [MIT](LICENSE) License.

package/lib/middlewareRunner.js

@@ -16,19 +16,19 @@ export function runMiddlewares(middlewares, req, res) {
 
     try {
       if (err) {
-        // Stiamo gestendo un errore: invochiamo solo gli errori middleware (4 parametri)
+        // We are handling an error: invoke error-handling middlewares only (4 arguments)
         if (middleware.length === 4) {
           Promise.resolve(middleware(err, req, res, next)).catch(next);
         } else {
-          // Salta il middleware normale e vai avanti trascinando l'errore
+          // Skip normal middleware and continue passing down the error
           dispatch(i + 1, err);
         }
       } else {
-        // Funzionamento normale: invochiamo solo i middleware regolari (< 4 parametri)
+        // Normal flow: invoke regular middlewares only (< 4 arguments)
         if (middleware.length < 4) {
           Promise.resolve(middleware(req, res, next)).catch(next);
         } else {
-          // Salta l'error middleware
+          // Skip error-handling middleware
           dispatch(i + 1, err);
         }
       }

package/lib/middlewares/bodyParser.js

@@ -1,5 +1,5 @@
 export function jsonBodyParser(req, res, next) {
-  // Parsiamo il body solo per le richieste che solitamente lo prevedono
+  // Parse the body only for requests that are expected to contain it
   if (["POST", "PUT", "PATCH"].includes(req.method)) {
     let body = "";
     const MAX_SIZE = 1 * 1024 * 1024; // 1 Megabyte
@@ -46,7 +46,7 @@ export function jsonBodyParser(req, res, next) {
       next(err);
     });
   } else {
-    // Per le richieste come GET o DELETE, proseguiamo oltre ignorando il body
+    // For requests like GET or DELETE, proceed ignoring the body
     next();
   }
 }

package/lib/middlewares/enhancers.js

@@ -1,22 +1,22 @@
 export function requestResponseEnhancer(req, res, next) {
   // --- ENHANCE REQUEST ---
-  // Analizza l'URL includendo anche le query string (es. ?sort=asc)
+  // Parse URL including query parameters (e.g. ?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)
+  // Save pathname stripped of query strings (e.g. /notes instead of /notes?sort=asc)
   req.path = parsedUrl.pathname; 
   
-  // Salva i parametri estratti (es. { sort: 'asc' })
+  // Save query parameters as an object (e.g. { sort: 'asc' })
   req.query = Object.fromEntries(parsedUrl.searchParams);   
 
   // --- ENHANCE RESPONSE ---
-  // Aggiunge la scorciatoia per impostare lo status code a catena
+  // Adds chainable status code shortcut
   res.status = function(code) {
     res.statusCode = code;
     return res;
   };
 
-  // Aggiunge la scorciatoia per inviare JSON con i corretti Headers
+  // Adds json helper method to send responses with appropriate Headers
   res.json = function(data) {
     if (!res.hasHeader("Content-Type")) {
       res.setHeader("Content-Type", "application/json");

package/lib/middlewares/errorHandlers.js

@@ -7,7 +7,7 @@ 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
+    return next(err); // Let Node handle the connection termination
   }
   
   const statusCode = err.status || 500;

package/lib/router.js

@@ -16,12 +16,12 @@ export function route(method, pathDefinition, ...handlers) {
 
   return (req, res, next) => {
     if (req.method === method) {
-      // Usiamo req.path (pulito dalle query) se disponibile, altrimenti req.url depurato
+      // Use req.path (cleaned of query params) if available, otherwise sanitized req.url
       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")
+        // Extract dynamic parameters (e.g., /notes/15 -> req.params.id = "15")
         req.params = {};
         paramNames.forEach((name, index) => {
           req.params[name] = match[index + 1];
@@ -46,11 +46,11 @@ export function route(method, pathDefinition, ...handlers) {
         };
 
         runNext();
-        return; // Interrompiamo qui, la route è stata gestita
+        return; // Stop here, route has been matched and handled
       }
     }
     
-    // Se non c'è match, passiamo al prossimo middleware della catena
+    // If no match is found, proceed to the next middleware in the chain
     next();
   };
 }

package/lib/server.js

@@ -5,13 +5,13 @@ import { jsonBodyParser } from "./middlewares/bodyParser.js";
 import { logger } from "./middlewares/logger.js";
 
 /**
- * Factory che crea l'istanza del server mini-serve.
+ * Factory that creates the mini-serve server instance.
  * 
- * @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.
+ * @param {Object} [options] - Configuration options for built-in middlewares.
+ * @param {boolean} [options.useEnhancers=true] - Whether to register the middleware that enhances req and res.
+ * @param {boolean} [options.useBodyParser=true] - Whether to register the JSON body parser for POST/PUT/PATCH.
+ * @param {boolean} [options.useLogger=false] - Whether to enable the request logger in console.
+ * @returns {Object} Application instance with methods to define routes and register middlewares.
  */
 export function createServer(options = {}) {
   const {
@@ -22,7 +22,7 @@ export function createServer(options = {}) {
 
   const middlewares = [];
 
-  // Registrazione dei middleware built-in in base alle opzioni
+  // Register built-in middlewares based on options
   if (useEnhancers) {
     middlewares.push(requestResponseEnhancer);
   }
@@ -35,49 +35,49 @@ export function createServer(options = {}) {
 
   const app = {
     /**
-     * Registra un middleware generico nello stack.
+     * Registers a generic middleware in the stack.
      */
     use(fn) {
       middlewares.push(fn);
     },
 
     /**
-     * Registra una rotta GET.
+     * Registers a GET route.
      */
     get(path, ...handler) {
       middlewares.push(route("GET", path, ...handler));
     },
 
     /**
-     * Registra una rotta POST.
+     * Registers a POST route.
      */
     post(path, ...handler) {
       middlewares.push(route("POST", path, ...handler));
     },
 
     /**
-     * Registra una rotta PUT.
+     * Registers a PUT route.
      */
     put(path, ...handler) {
       middlewares.push(route("PUT", path, ...handler));
     },
 
     /**
-     * Registra una rotta DELETE.
+     * Registers a DELETE route.
      */
     delete(path, ...handler) {
       middlewares.push(route("DELETE", path, ...handler));
     },
 
     /**
-     * Registra una rotta PATCH.
+     * Registers a PATCH route.
      */
     patch(path, ...handler) {
       middlewares.push(route("PATCH", path, ...handler));
     },
 
     /**
-     * Il delegato (req, res) da passare a http.createServer().
+     * The delegate (req, res) to pass to http.createServer().
      */
     handler(req, res) {
       runMiddlewares(middlewares, req, res);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkgabri18/mini-serve",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A tiny, zero-dependency HTTP framework for Node.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -36,4 +36,4 @@
   ],
   "author": "",
   "license": "MIT"
-}
+}