slower 2.1.8 → 2.2.0

package/README.md

@@ -0,0 +1,386 @@
+# Slower
+
+A minimal, dependency-free HTTP framework for Node.js.  
+Slower provides a small subset of Express.js–style routing and middleware with a simpler internal model.
+
+Don't want to download 200 megabytes of modules from Express? Then try Slower 😉.
+
+It's just a couple files and a few KB.
+
+This might not be the most robust library, but it is small and lightweight, and it does the job. (Just don't use this in production, please.)
+
+---
+
+#### A word about this:
+
+Sorry for the (really) poorly written documentation, I need time to re-write it.
+If you would like to help, just email me (email on package.json), and I will be more than happy to talk to you.
+
+---
+
+## Features
+
+- No external dependencies
+- Express-like API and functionality (`get`, `post`, `use`, `all`, etc.)
+- Static file serving
+- Sub-routers and route grouping
+- SMALL!
+
+---
+
+## Installation
+
+```sh
+npm install slower
+```
+
+(Or just download this source code and put on a 'lib/slower' folder, it's what I usually do).
+
+---
+
+## Basic Usage
+
+Check `examples/` for some samples on how to use this library.
+
+The basic is: if works on Express, probably works here too (apart from some minor modifications, there is very little difference in the two public APIs)
+
+```js
+const slower = require('slower');
+
+const app = slower();
+
+app.get('/', (req, res) => {
+    res.send('Hello world');
+});
+
+app.listen(3000);
+```
+
+### Template URLs:
+
+The same basic rules that express.js applied are available here, since JS internalized the URLPattern API, and this library uses the pattern matching from URLPattern.
+
+If you have questions, check this guide on URLPattern:
+[https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API#pattern_syntax](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API#pattern_syntax)
+
+### Routing
+
+#### HTTP Methods
+
+All standard HTTP verbs are supported:
+
+```js
+app.get('/users', handler);
+app.post('/users', handler);
+app.put('/users/:id', handler);
+app.delete('/users/:id', handler);
+```
+
+#### Route Parameters
+
+Routes use URLPattern internally and support named parameters:
+
+```js
+app.get('/users/:id', (req, res) => {
+    res.json({ id: req.params.id });
+});
+```
+
+#### Multiple Handlers / Middleware
+
+Handlers are executed sequentially and receive next():
+
+```js
+app.get('/secure', authMiddleware, (req, res) => {
+    res.send('Authorized');
+});
+```
+
+#### Middleware
+
+`use()`
+Attach middleware for all HTTP methods:
+
+```js
+app.use((req, res, next) => {
+    console.log(req.method, req.url);
+    next();
+});
+```
+
+`all()`
+
+Apply handlers to specific paths or methods:
+
+```js
+app.all('/health', (req, res) => {
+    res.send('OK');
+});
+```
+
+### Request Object (req)
+
+- req.params – route parameters
+- req.query – parsed query string
+- req.body
+- buffer
+- text()
+- json()
+- req.ip – remote IP address
+- req.session
+- host
+- port
+- rhost - remote connected host
+- rport - remote connected port
+
+Example:
+
+```js
+app.post('/data', async (req, res) => {
+    const body = req.body.json();
+    res.json(body);
+});
+```
+
+### Response Object (res)
+
+- res.status(code)
+- res.set(name, value)
+- res.get(name)
+- res.type(mimeOrExtension)
+- res.send(body)
+- res.json(object)
+- res.file(path)
+- res.render(templatePath, data)
+- res.redirect(path)
+
+Example:
+
+```js
+res.status(201).json({ success: true });
+```
+
+### Static Files
+
+Serve a directory of static files:
+
+```js
+app.static('public');
+```
+
+Or mount it at a specific path:
+
+```js
+app.static('public', '/assets');
+```
+
+HTML files are also served without the .html extension automatically.
+
+### Routers
+
+#### Sub-Router
+
+```js
+const router = slower.Router();
+
+router.get('/users', handler);
+router.post('/users', handler);
+
+app.useRouter(router, '/api');
+```
+
+#### Route Groups
+
+```js
+app.route('/users').get(listUsers).post(createUser);
+```
+
+### HTTPS Support
+
+Pass options directly to the underlying server:
+
+```js
+const fs = require('fs');
+
+const app = slower({
+    https: true,
+    key: fs.readFileSync('key.pem'),
+    cert: fs.readFileSync('cert.pem'),
+});
+```
+
+### Fallback page
+
+If no route matches, it returns a default 404 HTML response:
+
+`Cannot {METHOD} /{path}`
+
+Custom fallback behavior can be implemented using middleware.
+
+## Method documentation
+
+### Main Export
+
+```js
+slower(options?: object) : <SlowerRouter>
+```
+
+Creates a new Slower application instance.
+
+- `options` are forwarded to `http.createServer` or `https.createServer`
+- If `options.https === true`, HTTPS is used
+
+---
+
+### Class: \<SlowerRouter\>
+
+Main application router and HTTP server wrapper.
+
+#### Server Control
+
+Start the HTTP/HTTPS server:
+
+```
+<SlowerRouter>.listen(...args) : http.Server
+```
+
+Stops the server:
+
+```
+<SlowerRouter>.close(callback?: function) : void
+```
+
+#### Routing Methods
+
+The following methods share the same signature:
+
+```
+<SlowerRouter>.get(path, ...handlers) : <SlowerRouter>
+
+<SlowerRouter>.post(path, ...handlers) : <SlowerRouter>
+
+<SlowerRouter>.put(path, ...handlers) : <SlowerRouter>
+
+<SlowerRouter>.delete(path, ...handlers) : <SlowerRouter>
+
+<SlowerRouter>.patch(path, ...handlers) : <SlowerRouter>
+
+<SlowerRouter>.options(path, ...handlers) : <SlowerRouter>
+
+<SlowerRouter>.head(path, ...handlers) : <SlowerRouter>
+
+<SlowerRouter>.trace(path, ...handlers) : <SlowerRouter>
+
+<SlowerRouter>.connect(path, ...handlers) : <SlowerRouter>
+```
+
+- `path` may be a string, RegExp, or middleware function
+- Handlers are called sequentially with `(req, res, next)`
+
+#### Middleware
+
+```
+<SlowerRouter>.use(...handlers: function\[\]) : <SlowerRouter>
+```
+
+Registers global middleware for all HTTP methods.
+
+```
+<SlowerRouter>.all(pathOrMethod, ...handlers) : <SlowerRouter>
+```
+
+Registers handlers across multiple HTTP methods depending on the first argument.
+
+#### Static Files
+
+```
+<SlowerRouter>.static(directoryPath: string, mountPath?: string) : <SlowerRouter>
+```
+
+Serves static files from a directory.
+
+#### Routers
+
+```
+<SlowerRouter>.useRouter(router: <SlowerSubRouter>, mountPath?: string) : <SlowerRouter>
+```
+
+Mounts a sub-router at the specified path.
+
+```
+<SlowerRouter>.route(path: string | RegExp) : <SlowerSubRouter>
+```
+
+Creates a route group bound to a single path.
+
+### Class: <\SlowerSubRouter\>
+
+Router container used for grouping routes before mounting.
+
+```
+<SlowerSubRouter>.get(path, ...handlers) : <SlowerSubRouter>
+
+<SlowerSubRouter>.post(path, ...handlers) : <SlowerSubRouter>
+
+<SlowerSubRouter>.put(path, ...handlers) : <SlowerSubRouter>
+
+<SlowerSubRouter>.delete(path, ...handlers) : <SlowerSubRouter>
+
+<SlowerSubRouter>.patch(path, ...handlers) : <SlowerSubRouter>
+
+<SlowerSubRouter>.use(...handlers) : <SlowerSubRouter>
+
+<SlowerSubRouter>.all(pathOrMethod, ...handlers) : <SlowerSubRouter>
+
+<SlowerSubRouter>.static(directoryPath, mountPath?) : <SlowerSubRouter>
+
+<SlowerSubRouter>.route(path) : <SlowerMicroRouter>
+```
+
+### Request Extensions
+
+```
+req.get(headerName: string) : string | undefined
+
+req.body.buffer : Buffer
+
+req.body.text() : string
+
+req.body.json() : any
+
+req.query : object
+
+req.params : object | undefined
+
+req.ip : string
+
+req.session : object
+```
+
+### Response Extensions
+
+```
+res.status(code: number) : res
+
+res.set(name: string | object, value?: string) : res
+
+res.get(name: string) : string | undefined
+
+res.type(type: string) : res
+
+res.send(body: string | Buffer) : void
+
+res.json(data: any) : void
+
+res.file(path: string) : void
+
+res.render(templatePath: string, data?: object) : void
+
+res.redirect(path: string) : void
+```
+
+**License:** MIT
+
+## License
+
+This is MIT-licensed. Just use it.

package/examples/router.js

@@ -0,0 +1,45 @@
+const middlewares = require('./third-party-middlewares');
+const Slower = require('../index');
+
+const app = Slower();
+
+app.use(middlewares.requestTime); // Set timestamp: req.moment
+app.use(middlewares.hashRequest); // Set request ID: req.id
+app.use(middlewares.triageRequest); // Set request validity: req.invalid
+app.use(middlewares.consoleLogger); // Logs to console (according to req.invalid)
+app.use(middlewares.blockMethods); // Blocks request (according to req.invalid)
+app.use(middlewares.nocache); // Prevents cache creation
+
+app.get(
+    '/rea',
+    (req, res, next) => console.log('redirected') || next(),
+    (req, res) => res.status(301).redirect('/admin')
+);
+
+app.get('/admin', (req, res) =>
+    res
+        .status(200)
+        .send(
+            `<h2>${JSON.stringify(req.params)}<br/>${JSON.stringify(req.query)}</h2>`
+        )
+);
+
+app.get('/admins/:id', (req, res) => {
+    res.status(200).send(
+        `<h2>${JSON.stringify(req.params)}<br/>${JSON.stringify(req.query)}<br/></h2>`
+    );
+});
+
+app.get('/headers', (req, res) => res.status(200).json(req.headers));
+
+app.get('/docs/:docname', (req, res) =>
+    res.file(`./${req.params.docname}.html`)
+);
+
+app.all((req, res) => {
+    res.status(404).send('<h2>Error 404 - Page Not Found<h2/>');
+});
+
+app.listen(80, '127.0.0.1', () =>
+    console.log('Listening on http://127.0.0.1:80/')
+);

package/examples/subrouter.js

@@ -0,0 +1,29 @@
+const Slower = require('../index');
+
+(async () => {
+    const appr = Slower.Router();
+    appr.get('/a', (req, res) => res.status(200).end('a'));
+
+    const appf = Slower.Router();
+    appf.get('/c', (req, res) => res.status(200).end('c'));
+    appf.get('/x/:id', (req, res) => res.status(200).end('x=' + req.params.id));
+    appf.all('/d', (req, res) => res.status(200).end('d'));
+
+    const app = Slower();
+    app.useRouter(appr);
+    app.useRouter(appf, '/api');
+    app.get('/b', (req, res) => res.status(200).end('b'));
+    app.all((req, res) => res.status(404).end());
+    app.listen('8000', () => console.log('app started at 8000'));
+})();
+
+/**
+ * TESTING ENDPOINTS:
+ *
+ * /a           Should print 'a'
+ * /b           Should print 'b'
+ * /api/c       Should print 'c'
+ * /api/d       Should print 'd'
+ * /api/x/:id   Should print 'x={ID}'
+ *
+ */

package/examples/third-party-middlewares.js

@@ -0,0 +1,88 @@
+/**
+ * Server middleware to force the client to NOT save any data as cache.
+ * @info This is very useful for development purposes, as browser cache for 
+ *       redirections and scripts is very annoying
+ * @param {http.IncomingMessage} req 
+ * @param {http.ServerResponse} res 
+ * @param {Function} next 
+ * @return {undefined}
+ */
+function nocache (req, res, next) {
+    res.set('Cache-Control', 'no-cache');
+    next();
+}
+
+// Add a timestamp to the request
+function requestTime (req, res, next) {
+    req.moment = Date.now();
+    next();
+}
+
+// Add a hash to the request
+function murmurHash (key, seed = 0) { 
+    const C = { M:0x5bd1e995, R:0x18 };
+    const im32M = (a) => {
+        const c = { o: v => v & 0xffff, i: v => (v >>> 16) & 0xffff };
+        return c.o(a)*59797 + (((c.i(a)*59797 + c.o(a)*23505) << 16) >>> 0);
+    };
+	let len = key.length, h = seed ^ len, i = 0, k = 0;
+	while (len >= 4) {
+		k = key[i++] | (key[i++] << 8) | (key[i++] << 16) | (key[i++] << 24);
+		k = im32M(k);
+		k ^= k >>> C.R;
+		k = im32M(k);
+		h = im32M(h) ^ k;
+		len -= 4;
+	};
+	switch (len) {
+		case 3: h ^= key[i + 2] << 16;
+		case 2: h ^= key[i + 1] << 8;
+		case 1: h ^= key[i];
+			    h = im32M(h);
+	};
+	h ^= h >>> 13;
+	h = im32M(h);
+	h ^= h >>> 15;
+	return h >>> 0;
+}
+function hashRequest (req, res, next) {
+    req.hash = (murmurHash(Date.now().toString() + JSON.stringify(req.session) + req.url)).toString().padStart(10, '0');
+    next();
+}
+
+// Set an 'invalid' property if the request is of a proper method
+// This is used in the 'blockMethods' and 'consoleLogger' middlewares
+function triageRequest (req, res, next) {
+    const allowedMethods = ['GET','POST','PUT','DELETE'];
+    if (!allowedMethods.includes(req.method)) req.invalid = true;
+    next();
+}
+
+// Logs request to console
+const padStringEnd = (str, maxLen) => str.padEnd(maxLen, ' ');
+const colorizeMethod = (req) => (req.invalid ? '\x1b[31m' : '\x1b[32m') + req.method + '\x1b[0m';
+function consoleLogger (req, res, next) {
+    console.log(
+        ' ' +
+        `Hash:${req.hash}    ` +
+        `Time:${new Date(req.moment).toISOString()}    ` + 
+        `${padStringEnd(req.session.rhost + ':' + req.session.rport + '->' + req.session.host + ':' + req.session.port, 32)}    `+
+        `${padStringEnd(colorizeMethod(req), 20)}    ${req.url}`
+    );
+    next();
+}
+
+// Blocks all requests that are not GET, POST, PUT, or DELETE ones
+function blockMethods (req, res, next) {
+    if (req.invalid) res.status(405).end();
+    else next();
+}
+
+module.exports = {
+    nocache,
+    requestTime,
+    hashRequest,
+    consoleLogger,
+    blockMethods,
+    triageRequest
+}

package/package.json

@@ -1,16 +1,12 @@
 {
-	"dependencies": {
-		"path-to-regexp": "^6.2.2"
-	},
-	"name": "slower",
-	"version": "2.1.8",
-	"main": "index.js",
-	"devDependencies": {},
-	"scripts": {
-		"test": "echo \"Error: no test specified\" && exit 1"
-	},
-	"keywords": [],
-	"author": "Tomás Luchesi <no.mad.devtech@gmail.com>",
-	"license": "MIT",
-	"description": "A package for simple HTTP server routing."
-}
+    "name": "slower",
+    "version": "2.2.0",
+    "main": "index.js",
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [],
+    "author": "Tomás Luchesi <no.mad.devtech@gmail.com>",
+    "license": "MIT",
+    "description": "A package for simple HTTP server routing."
+}

package/src/decorators.js

@@ -11,7 +11,7 @@ const utils = require('./utils');
  * @exposes .json()
  * @exposes .file()
  */
-function setupResponse(response) {
+function setupResponse(response, request) {
     /**
      * Sets the response status code
      * @chainable
@@ -67,11 +67,7 @@ function setupResponse(response) {
      * @info And if no type is specified, binary type is used (application/octet-stream)
      */
     response.type = function (mime) {
-        let mimetype =
-            MIME_TABLE[mime] ||
-            mime ||
-            MIME_TABLE[extension] ||
-            MIME_TABLE['default'];
+        let mimetype = MIME_TABLE[mime] || mime || MIME_TABLE['default'];
         response.setHeader('Content-type', mimetype);
         return response;
     };
@@ -193,7 +189,7 @@ function setupRequest(request) {
      * @property
      * Holds the request body data as a buffer
      */
-    return new Promise(resolve => {
+    return new Promise((resolve, reject) => {
         // Set classical socket locals
         request.session = {
             port: request.socket.localPort,