nodester 0.1.5 → 0.2.0

package/lib/http/{request.js → request/index.js}

@@ -2,17 +2,21 @@
  * /nodester
  * MIT Licensed
  */
+ 
 'use strict';
 
+const { IncomingMessage } = require('http');
+
 const accepts = require('accepts');
 const isIP = require('net').isIP;
 const typeis = require('type-is');
-const { IncomingMessage } = require('http');
 const fresh = require('fresh');
 const parseRange = require('range-parser');
 const parse = require('parseurl');
 const proxyaddr = require('proxy-addr');
 
+const { defineGetter } = require('./utils');
+
 
 const req = IncomingMessage.prototype;
 
@@ -38,8 +42,10 @@ module.exports = req;
  * Aliased as `req.header()`.
  *
  * @param {String} name
+ *
  * @return {String}
- * @public
+ *
+ * @api public
  */
 req.get =
 req.header = function header(name) {
@@ -106,7 +112,8 @@ req.header = function header(name) {
  *
  * @param {String|Array} type(s)
  * @return {String|Array|Boolean}
- * @public
+ *
+ * @api public
  */
 req.accepts = function() {
 	const accept = accepts(this);
@@ -119,7 +126,8 @@ req.accepts = function() {
  *
  * @param {String} ...encoding
  * @return {String|Array}
- * @public
+ *
+ * @api public
  */
 req.acceptsEncodings = function() {
 	const accept = accepts(this);
@@ -133,7 +141,8 @@ req.acceptsEncodings = function() {
  *
  * @param {String} ...charset
  * @return {String|Array}
- * @public
+ *
+ * @api public
  */
 req.acceptsCharsets = function() {
 	const accept = accepts(this);
@@ -147,7 +156,8 @@ req.acceptsCharsets = function() {
  *
  * @param {String} ...lang
  * @return {String|Array}
- * @public
+ *
+ * @api public
  */
 req.acceptsLanguages = function() {
 	const accept = accepts(this);
@@ -176,8 +186,10 @@ req.acceptsLanguages = function() {
  * @param {number} size
  * @param {object} [options]
  * @param {boolean} [options.combine=false]
+ *
  * @return {number|array}
- * @public
+ *
+ * @api public
  */
 req.range = function range(size, options) {
 	const range = this.get('Range');
@@ -211,7 +223,8 @@ req.range = function range(size, options) {
  *
  * @param {String|Array} types...
  * @return {String|false|null}
- * @public
+ *
+ * @api public
  */
 req.is = function is(types) {
 	let arr = types;
@@ -239,7 +252,8 @@ req.is = function is(types) {
  * supplies https for you this may be enabled.
  *
  * @return {String}
- * @public
+ *
+ * @api public
  */
 
 defineGetter(req, 'protocol', function protocol() {
@@ -254,12 +268,13 @@ defineGetter(req, 'protocol', function protocol() {
 
 	// Note: X-Forwarded-Proto is normally only ever a
 	//       single value, but this is to be safe.
-	const header = this.get('X-Forwarded-Proto') || proto
-	const index = header.indexOf(',')
+	const header = this.get('X-Forwarded-Proto') || proto;
+	const index = header.indexOf(',');
 
-	return index !== -1
-		? header.substring(0, index).trim()
-		: header.trim()
+	return index !== -1 ?
+					header.substring(0, index).trim()
+					:
+					header.trim();
 });
 
 
@@ -269,7 +284,8 @@ defineGetter(req, 'protocol', function protocol() {
  *    req.protocol === 'https'
  *
  * @return {Boolean}
- * @public
+ *
+ * @api public
  */
 defineGetter(req, 'secure', function secure() {
 	return this.protocol === 'https';
@@ -283,7 +299,8 @@ defineGetter(req, 'secure', function secure() {
  * "trust proxy" is set.
  *
  * @return {String}
- * @public
+ *
+ * @api public
  */
 defineGetter(req, 'ip', function ip() {
 	const trust = this.app.get('trust proxy fn');
@@ -299,8 +316,9 @@ defineGetter(req, 'ip', function ip() {
  * where "proxy2" is the furthest down-stream and "proxy1" and
  * "proxy2" were trusted.
  *
- * @return {Array}
- * @public
+ * @return {Array} addresses
+ *
+ * @api public
  */
 defineGetter(req, 'ips', function ips() {
 	const trust = this.app.get('trust proxy fn');
@@ -308,37 +326,9 @@ defineGetter(req, 'ips', function ips() {
 
 	// reverse the order (to farthest -> closest)
 	// and remove socket address
-	addrs.reverse().pop()
+	addresses.reverse().pop()
 
-	return addrs
-});
-
-
-/**
- * Return subdomains as an array.
- *
- * Subdomains are the dot-separated parts of the host before the main domain of
- * the app. By default, the domain of the app is assumed to be the last two
- * parts of the host. This can be changed by setting "subdomain offset".
- *
- * For example, if the domain is "tobi.ferrets.example.com":
- * If "subdomain offset" is not set, req.subdomains is `["ferrets", "tobi"]`.
- * If "subdomain offset" is 3, req.subdomains is `["tobi"]`.
- *
- * @return {Array}
- * @public
- */
-defineGetter(req, 'subdomains', function subdomains() {
-	const hostname = this.hostname;
-
-	if (!hostname) return [];
-
-	const offset = this.app.get('subdomain offset');
-	const subdomains = !isIP(hostname)
-		? hostname.split('.').reverse()
-		: [hostname];
-
-	return subdomains.slice(offset);
+	return addresses;
 });
 
 
@@ -346,7 +336,8 @@ defineGetter(req, 'subdomains', function subdomains() {
  * Short-hand for `url.parse(req.url).pathname`.
  *
  * @return {String}
- * @public
+ *
+ * @api public
  */
 defineGetter(req, 'path', function path() {
 	return parse(this).pathname;
@@ -359,7 +350,8 @@ defineGetter(req, 'path', function path() {
  * or "Host" as a fallback.
  *
  * @return {String}
- * @public
+ *
+ * @api public
  */
 defineGetter(req, 'hostname', function hostname() {
 	const host = this.get('X-Forwarded-Host') ?? this.get('Host');
@@ -373,23 +365,24 @@ defineGetter(req, 'hostname', function hostname() {
  * still match.
  *
  * @return {Boolean}
- * @public
+ *
+ * @api public
  */
 defineGetter(req, 'fresh', function() {
 	const method = this.method;
-	const res = this.res
-	const status = res.statusCode
+	const res = this.res;
+	const status = res.statusCode;
 
 	// GET or HEAD for weak freshness validation only
-	if ('GET' !== method && 'HEAD' !== method)
+	if (method !== 'GET' && method !== 'HEAD')
 		return false;
 
 	// 2xx or 304 as per rfc2616 14.26
 	if ((status >= 200 && status < 300) || 304 === status) {
 		return fresh(this.headers, {
-			'etag': res.get('ETag'),
+			'etag': res.get('etag'),
 			'last-modified': res.get('Last-Modified')
-		})
+		});
 	}
 
 	return false;
@@ -402,7 +395,8 @@ defineGetter(req, 'fresh', function() {
  * resource has changed.
  *
  * @return {Boolean}
- * @public
+ *
+ * @api public
  */
 defineGetter(req, 'stale', function stale() {
 	return !this.fresh;
@@ -413,26 +407,10 @@ defineGetter(req, 'stale', function stale() {
  * Check if the request was an _XMLHttpRequest_.
  *
  * @return {Boolean}
- * @public
+ *
+ * @api public
  */
 defineGetter(req, 'xhr', function xhr() {
 	const val = this.get('X-Requested-With') || '';
 	return val.toLowerCase() === 'xmlhttprequest';
 });
-
-
-/**
- * Helper function for creating a getter on an object.
- *
- * @param {Object} obj
- * @param {String} name
- * @param {Function} getter
- * @private
- */
-function defineGetter(obj, name, getter) {
-	Object.defineProperty(obj, name, {
-		configurable: true,
-		enumerable: true,
-		get: getter
-	});
-}

package/lib/http/request/utils.js

@@ -0,0 +1,27 @@
+/*!
+ * /nodester
+ * MIT Licensed
+ */
+ 
+'use strict';
+
+module.exports = {
+	defineGetter: _defineGetter
+}
+
+/**
+ * Helper function for creating a getter on an object.
+ *
+ * @param {Object} obj
+ * @param {String} name
+ * @param {Function} getter
+ *
+ * @api private
+ */
+function _defineGetter(obj, name, getter) {
+	Object.defineProperty(obj, name, {
+		configurable: true,
+		enumerable: true,
+		get: getter
+	});
+}

package/lib/http/response/headers.js

@@ -0,0 +1,138 @@
+/*!
+ * /nodester
+ * MIT Licensed
+ */
+
+'use strict';
+
+// Constants.
+const CHARSET_REGEX = /;\s*charset\s*=/;
+
+// Utils:
+const mime = require('mime');
+
+
+module.exports = {
+	setHeader: _setHeader,
+	appendHeader: _appendHeader,
+	getHeader: _getHeader,
+	removeHeader: _removeHeader,
+}
+
+/**
+ * Set header `field` to `value`, or pass
+ * an object of header fields.
+ *
+ * Examples:
+ *
+ *    res.set('Foo', ['bar', 'baz']);
+ *    res.set('Accept', 'application/json');
+ *    res.set({ Accept: 'text/plain', 'X-API-Key': 'tobi' });
+ *
+ * Aliased as `res.header()`.
+ *
+ * @param {String|Object} keyOrObject
+ * @param {String|Array} value
+ *
+ * @return {ServerResponse} for chaining
+ *
+ * @alias setHeader
+ * @api public
+ */
+function _setHeader(keyOrObject, value) {
+	// As a pair:
+	if (arguments.length === 2) {
+		let _value = Array.isArray(value) ? value.map(String) : String(value);
+
+		// Add charset to content-type:
+		if (keyOrObject.toLowerCase() === 'content-type') {
+			
+			if (Array.isArray(_value)) {
+				throw new TypeError('Content-Type cannot be set to an Array');
+			}
+
+			if (!CHARSET_REGEX.test(_value)) {
+				const charset = mime.charsets.getType(_value.split(';')[0]);
+				
+				if (charset) {
+					_value += '; charset=' + charset.toLowerCase();
+				}
+			}
+		}
+
+		this.setHeader(keyOrObject, _value);
+	}
+	// As an object
+	else if (typeof keyOrObject === 'object') {
+		for (let key in keyOrObject) {
+			this.setHeader(key, keyOrObject[key]);
+		}
+	}
+	else {
+		const err = new TypeError(`'keyOrObject' must be of type String|Object.`);
+		Error.captureStackTrace(err, _setHeader);
+		throw err;
+	}
+
+	return this;
+};
+
+
+/**
+ * Append additional header `field` with value `val`.
+ *
+ * Example:
+ *
+ *    res.append.header('Link', ['<http://localhost/>', '<http://localhost:3000/>']);
+ *    res.append.header('Set-Cookie', 'foo=bar; Path=/; HttpOnly');
+ *    res.append.header('Warning', '199 Miscellaneous warning');
+ *
+ * @param {String} field
+ * @param {String|Array} value
+ * @return {ServerResponse} for chaining
+ *
+ * @alias appendHeader
+ * @api public
+ */
+function _appendHeader(field, value) {
+	const prev = this.get(field);
+	let _value = value;
+
+	if (prev) {
+		// concat the new and prev values:
+		_value = Array.isArray(prev) ? prev.concat(value)
+			: Array.isArray(value) ? [prev].concat(value)
+				: [prev, value]
+	}
+
+	return this.setHeader(field, _value);
+};
+
+
+/**
+ * Get value for header `key`.
+ *
+ * @param {String} key
+ *
+ * @return {String}
+ *
+ * @alias getHeader
+ * @api public
+ */
+function _getHeader(key) {
+	return this.getHeader(key);
+};
+
+/**
+ * Remove value for header `key`.
+ *
+ * @param {String} key
+ *
+ * @return {String}
+ *
+ * @alias removeHeader
+ * @api public
+ */
+function _removeHeader(key) {
+	return this.removeHeader(key);
+};

package/lib/http/response/index.js

@@ -0,0 +1,248 @@
+/*!
+ * /nodester
+ * MIT Licensed
+ */
+
+'use strict';
+
+const { ServerResponse } = require('http');
+
+const {
+	setHeader,
+	appendHeader,
+	getHeader,
+	removeHeader,
+} = require('./headers');
+
+const calculateEtag = require('etag');
+
+// Utils:
+const statuses = require('statuses');
+const mime = require('mime');
+const {
+	setCharset
+} = require('./utils');
+
+
+const response = ServerResponse.prototype;
+
+// Mixin custom methods:
+response.status = _status;
+response.sendStatus = _sendStatus;
+
+response.send = _send;
+response.json = _json;
+
+//	Headers:
+response.set    = setHeader;
+response.append = appendHeader;
+response.get    = getHeader;
+response.remove = removeHeader;
+
+//	ContentType:
+response.setContentType = _setContentType;
+response.getContentType = _getContentType;
+// Mixins\
+
+module.exports = response;
+
+/**
+ * Set status `code`.
+ *
+ * @param {Number} code
+ *
+ * @return {ServerResponse}
+ *
+ * @alias status
+ * @api public
+ */
+function _status(code) {
+	this.statusCode = code;
+	return this;
+};
+
+
+/**
+ * Send given HTTP status code.
+ *
+ * Sets the response status to `statusCode` and the body of the
+ * response to the standard description from node's http.STATUS_CODES
+ * or the statusCode number if no description.
+ *
+ * Examples:
+ *
+ *     res.sendStatus(200);
+ *
+ * @param {number} statusCode
+ *
+ * @alias _sendStatus
+ * @api public
+ */
+function _sendStatus(statusCode) {
+	const body = statuses.message[statusCode] || String(statusCode);
+
+	this.statusCode = statusCode;
+	this.setContentType('txt');
+
+	return this.send(body);
+};
+
+/**
+ * Sends a response.
+ *
+ * Examples:
+ *
+ *     res.send(Buffer.from('wahoo'));
+ *     res.send({ some: 'json' });
+ *     res.send('<p>some html</p>');
+ *
+ * @param {string|number|boolean|object|Buffer} body
+ *
+ * @alias send
+ * @api public
+ */
+function _send(body) {
+	const req = this.req;
+	const app = this.app;
+
+	let chunk = body;
+	let encoding;
+	let type;
+
+	switch (typeof chunk) {
+		// strings defaulting to html:
+		case 'string':
+			if (!this.getContentType()) {
+				this.setContentType('html');
+			}
+			break;
+		case 'boolean':
+		case 'number':
+		case 'object':
+			if (chunk === null) {
+				chunk = '';
+			}
+			else if (Buffer.isBuffer(chunk)) {
+				if (!this.getContentType()) {
+					this.setContentType('bin');
+				}
+			}
+			else {
+				return this.json(chunk);
+			}
+			break;
+	}
+
+	// Write strings in utf-8:
+	if (typeof chunk === 'string') {
+		encoding = 'utf8';
+		type = this.getContentType();
+
+		// reflect this in content-type
+		if (typeof type === 'string') {
+			this.setContentType( setCharset(type, 'utf-8') );
+		}
+	}
+
+	// Freshness of the REQUEST:
+	if (req.fresh) {
+		this.statusCode = 304;
+	}
+
+	// Strip irrelevant headers for:
+	// - 204 (No Content)
+	// - 303 (Not Modified)
+	if (
+		this.statusCode === 204
+		||
+		this.statusCode === 304
+	) {
+		this.remove('Content-Type');
+		this.remove('Content-Length');
+		this.remove('Transfer-Encoding');
+		chunk = '';
+	}
+
+	// Alter headers for 205 (Reset Content):
+	if (this.statusCode === 205) {
+		this.set('Content-Length', '0');
+		this.remove('Transfer-Encoding');
+		chunk = ''
+	}
+
+	if (req.method === 'HEAD') {
+		// skip body for HEAD.
+		this.end();
+	}
+	else {
+		// Calculate etag:
+		const etag = calculateEtag(chunk);
+		this.set('etag', etag);
+
+		// Respond.
+		this.end(chunk, encoding);
+	}
+
+	return this;
+};
+
+
+/**
+ * Send JSON response.
+ *
+ * @param {string|number|boolean|object} obj
+ *
+ * @alias json
+ * @api public
+ */
+function _json(obj) {
+
+	// Ensure content-type:
+	if (!this.getContentType()) {
+		this.setContentType('application/json');
+	}
+
+	const body = JSON.stringify(obj);
+	return this.send(body);
+};
+
+/**
+ * Set _Content-Type_ response header with `type` through `mime.getType()`
+ * when it does not contain "/", or set the Content-Type to `type` otherwise.
+ *
+ * Examples:
+ *
+ *     res.type('.html');
+ *     res.type('html');
+ *     res.type('json');
+ *     res.type('application/json');
+ *     res.type('png');
+ *
+ * @param {String} type
+ *
+ * @return {ServerResponse} for chaining
+ *
+ * @alias setContentType
+ * @api public
+ */
+function _setContentType(type) {
+	const contentType = type.indexOf('/') === -1 ?
+												mime.getType(type)
+												:
+												type;
+
+	this.setHeader('Content-Type', contentType);
+	return this;
+};
+
+/**
+ * Returns _Content-Type_ header.
+ *
+ * @return {String} type
+ *
+ * @alias getContentType
+ * @api public
+ */
+function _getContentType() {
+	return this.getHeader('Content-Type');
+};