nodester 0.2.6 → 0.2.8

package/lib/router/index.js

@@ -1,5 +1,5 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
 
@@ -13,7 +13,7 @@ const MarkersStack = require('../stacks/MarkersStack');
 const MarkerMethods = require('./markers');
 
 // Utils:
-const { typeOf } = require('../utils/types.util');
+const { typeOf } = require('nodester/utils/types');
 const {
 	validateParsedRouteMethood,
 	wrapRouteHandler
@@ -32,25 +32,26 @@ const consl = require('nodester/loggers/console');
 const debug = require('debug')('nodester:router');
 
 
+/**
+ * @class
+ * @classdesc Main routing middleware
+ *
+ * @param {Object}  [options]
+ * @param {Array} 	[options.codeFileExtensions]
+ * @param {string} 	[options.controllersPath]
+ * @param {Object} 	[options.controllers]
+ * @param {boolean} [options.finalhandlerEnabled]
+ *
+ * @access public
+ */
 module.exports = class NodesterRouter {
 	
-	/**
-	 * Initialize a new `NodesterRouter`.
-	 *
-	 * @param {Object}  [opts]
-	 * @param {Array} 	opts.codeFileExtensions
-	 * @param {String} 	opts.controllersPath
-	 * @param {Object} 	opts.controllers
-	 * @param {Boolean} opts.finalhandlerEnabled
-	 *
-	 * @api public
-	 */
-	constructor(opts={}) {
+	constructor(options={}) {
 		// Reference to the controllers stack.
 		this._controllers = new Map();
 
 		// Reference to middlewares stack.
-		this._middlewares = new MiddlewaresStack({ finalhandlerEnabled: !!opts.finalhandlerEnabled });
+		this._middlewares = new MiddlewaresStack({ finalhandlerEnabled: !!options.finalhandlerEnabled });
 
 		// Reference to the markers stack.
 		this._markers = new MarkersStack();
@@ -63,19 +64,30 @@ module.exports = class NodesterRouter {
 
 		// Options:
 		//	if "codeFileExtensions" was set:
-		if (!!opts.codeFileExtensions && Array.isArray(opts.codeFileExtensions)) {
-			this.codeFileExtensions = [...opts.codeFileExtensions];
+		if (!!options.codeFileExtensions) {
+			ensure(options.codeFileExtensions, 'array', 'options.codeFileExtensions');
+			this.codeFileExtensions = [...options.codeFileExtensions];
 		}
 
 		//	If "controllersPath" was set,
 		//	cache all controllers in directory:
-		if (!!opts.controllersPath) {
+		if (!!options.controllersPath) {
+			ensure(options.controllersPath, 'string', 'options.controllersPath');
+
 			// Save path.
-			this.paths.controllers = opts.controllersPath;
+			this.paths.controllers = options.controllersPath;
 
 			// Only get files, which have available file extensions:
 			const availableFileExtensions = this.codeFileExtensions;
-			const fileNames = fs.readdirSync(this.paths.controllers);
+
+			let fileNames;
+			try {
+				fileNames = fs.readdirSync(this.paths.controllers);
+			}
+			catch(error) {
+				Error.captureStackTrace(error, this.constructor);
+				throw error;
+			}
 
 			const controllersNames = parseProviderFileNames(fileNames, availableFileExtensions, 'controller');
 
@@ -86,10 +98,10 @@ module.exports = class NodesterRouter {
 		}
 
 		//	If "controllers" were provided as an Object:
-		if (!!opts.controllers) {
-			ensure(opts.controllers, 'object,required', 'opts.controllers');
+		if (!!options.controllers) {
+			ensure(options.controllers, 'object', 'options.controllers');
 
-			const entities = Object.entities(opts.controllers);
+			const entities = Object.entities(options.controllers);
 			for (const [controllerName, controllerDefinition] of entities) {
 				this.addController(controllerDefinition, controllerName);
 			}
@@ -97,9 +109,11 @@ module.exports = class NodesterRouter {
 
 		//	If "providersPath" was set,
 		//	cache all providers in directory:
-		if (!!opts.providersPath) {
+		if (!!options.providersPath) {
+			ensure(options.providersPath, 'string', 'options.providersPath');
+
 			// Save path.
-			this.paths.providers = opts.providersPath;
+			this.paths.providers = options.providersPath;
 
 			// Only get files, which have available file extensions:
 			const availableFileExtensions = this.codeFileExtensions;
@@ -114,10 +128,10 @@ module.exports = class NodesterRouter {
 		}
 
 		//	If "providers" were provided as an Object:
-		if (!!opts.providers) {
-			ensure(opts.providers, 'object,required', 'opts.providers');
+		if (!!options.providers) {
+			ensure(options.providers, 'object', 'options.providers');
 
-			const entities = Object.entities(opts.providers);
+			const entities = Object.entities(options.providers);
 			for (const [providerName, providerDefinition] of entities) {
 				this.addProvider(providerDefinition, providerName);
 			}
@@ -129,7 +143,7 @@ module.exports = class NodesterRouter {
 	/**
 	 * @return {MiddlewaresStack}
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get middlewaresStack() {
 		return this._middlewares;
@@ -138,9 +152,9 @@ module.exports = class NodesterRouter {
 	/**
 	 * Indicates whether user can add more middlewares or not.
 	 *
-	 * @return {Boolean} isLocked
+	 * @return {boolean} isLocked
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get isLocked() {
 		return this._middlewares.isLocked;
@@ -148,7 +162,7 @@ module.exports = class NodesterRouter {
 
 	// Getters\
 
-	/*
+	/**
 	 * Adds:
 	 * - (controller) new Controller to the stack;
 	 * - (middleware) new Middleware to the stack;
@@ -157,7 +171,7 @@ module.exports = class NodesterRouter {
 	 * - (route) new Route to the stack;
 	 * - (routes) array[Route] to the stack;
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get add() {
 		return {
@@ -171,13 +185,13 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Adds new controller to the controllers stack.
 	 *
 	 * @param {Function|Object} controller
-	 * @param {String} controllerName
+	 * @param {string} controllerName
 	 *
-	 * @api public
+	 * @access public
 	 */
 	addController(controller, controllerName=null) {
 		try {
@@ -206,15 +220,15 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Adds new middleware to the stack.
 	 *
 	 * @param {Function} fn
-	 * @param {Integer} index (0 or undefined)
+	 * @param {Int} index (0 or undefined)
 	 *
-	 * @return {Integer} index of the new middleware
+	 * @return {Int} index of the new middleware
 	 *
-	 * @api public
+	 * @access public
 	 */
 	addMiddleware(fn, index) {
 		try {
@@ -230,13 +244,13 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Adds new marker to the stack.
 	 *
-	 * @param {String} markerName
+	 * @param {string} markerName
 	 * @param {Function} fn
 	 *
-	 * @api public
+	 * @access public
 	 */
 	addMarker(markerName='', fn) {
 		try {
@@ -262,13 +276,13 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Adds new provider to the providers stack.
 	 *
 	 * @param {Function|Object} provider
-	 * @param {String} providerName
+	 * @param {string} providerName
 	 *
-	 * @api public
+	 * @access public
 	 */
 	addProvider(provider, providerName=null) {
 		try {
@@ -298,13 +312,13 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Creates route middleware and adds it to the stack.
 	 *
-	 * @param {String} route
+	 * @param {string} route
 	 * @param {Object|Function} handler
 	 *
-	 * @api public
+	 * @access public
 	 */
 	addRoute(route='', handler) {
 		try {
@@ -333,13 +347,13 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Loops through provided "routes" object
 	 * and adds them throught "addRoute".
 	 *
 	 * @param {Object} routes
 	 *
-	 * @api public
+	 * @access public
 	 */
 	addRoutes(routes={}) {
 		try {
@@ -356,12 +370,12 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Proxy to .add.middleware()
 	 *
 	 * @param {Function|NodesterRouter} fnOrRouter
 	 *
-	 * @api public
+	 * @access public
 	 */
 	use(fnOrRouter) {
 		try {
@@ -383,12 +397,12 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Adds middlewares, which only fires for set marker.
 	 *
-	 * @param {String} markerName
+	 * @param {string} markerName
 	 *
-	 * @api public
+	 * @access public
 	 */
 	only(markerName='') {
 		try {
@@ -412,17 +426,17 @@ module.exports = class NodesterRouter {
 	/**
 	 * Handles server request.
 	 *
-	 * @api public
+	 * @access public
 	 */
 	handle(req, res, next) {
 		return this._middlewares.process(req, res, next)
 	}
 
 
-	/*
+	/**
 	 * Prepare router for processing.
 	 *
-	 * @api public
+	 * @access public
 	 */
 	lock() {
 		// Stack is ready.
@@ -431,10 +445,10 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Unlocks router.
 	 *
-	 * @api public
+	 * @access public
 	 */
 	unlock() {
 		this._middlewares.unlock();
@@ -442,7 +456,7 @@ module.exports = class NodesterRouter {
 	}
 
 
-	/*
+	/**
 	 * Removes something
 	 */
 	get remove() {
@@ -455,11 +469,11 @@ module.exports = class NodesterRouter {
 	/**
 	 * Removes middleware at index.
 	 *
-	 * @param {Integer} index
+	 * @param {Int} index
 	 *
-	 * @return {Integer} middlewares stack length
+	 * @return {Int} middlewares stack length
 	 *
-	 * @api public
+	 * @access public
 	 */
 	removeMiddleware(index=-1) {
 		try {
@@ -479,12 +493,12 @@ module.exports = class NodesterRouter {
 	/**
 	 * Extends Router & makes sure, that "key" param is not present already.
 	 *
-	 * @param {String} key
-	 * @param {Any} fnOrProperty
+	 * @param {string} key
+	 * @param {any} fnOrProperty
 	 *
-	 * @return {Any} fnOrProperty in Router
+	 * @return {any} fnOrProperty in Router
 	 *
-	 * @api public
+	 * @access public
 	 */
 	extend(key='', fnOrProperty) {
 		ensure(key, 'string,required', 'key');

package/lib/router/markers.js

@@ -1,5 +1,5 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
  
@@ -18,9 +18,9 @@ module.exports = {
 	onlyUse: _onlyUse
 }
 
-/*
+/**
  * 
- * @param {String} route
+ * @param {string} route
  * @param {Function} fn
  * @param {Function} markerFn
  *
@@ -51,7 +51,7 @@ function _onlyRoute(route, fn, markerFn) {
 }
 
 
-/*
+/**
  * 
  * @param {Function} fnOrRouter
  * @param {Function} markerFn

package/lib/router/route.js

@@ -1,30 +1,30 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
 
 'use strict';
 
 // Utils.
-const { typeOf } = require('../utils/types.util');
+const { typeOf } = require('nodester/utils/types');
 
 // Arguments validator.
 const { ensure } = require('nodester/validators/arguments');
 
 
+/**
+ * Initialize a new `NodesterRoute`.
+ *
+ * @param {Object|String} routeStringOrOpts
+ * @param {string}        [routeStringOrOpts.method]
+ * @param {string}        [routeStringOrOpts.route]
+ * @param {Array}         [routeStringOrOpts.parts]
+ * @param {Object}        [routeStringOrOpts.params]
+ *
+ * @access public
+ */
 module.exports = class NodesterRoute {
-	
-	/**
-	 * Initialize a new `NodesterRoute`.
-	 *
-	 * @param {Object|String} routeStringOrOpts
-	 * - {String} method
-	 * - {String} route
-	 * - {Array} parts
-	 * - {Object} params
-	 *
-	 * @api public
-	 */
+
 	constructor(routeStringOrOpts={}) {
 		ensure(routeStringOrOpts, 'object|string,required', 'routeStringOrOpts');
 		
@@ -67,12 +67,11 @@ module.exports = class NodesterRoute {
 
 
 	/**
-	 * @param {String} routeToTest
+	 * @param {string} routeToTest
 	 *
-	 * @return {Boolean}
+	 * @return {boolean}
 	 *
-	 * @alias matches
-	 * @private
+	 * @access private
 	 */
 	matches(routeToTest='') {
 		const {

package/lib/router/routes.util.js

@@ -1,12 +1,12 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
 
 'use strict';
 
 // Utils:
-const { typeOf } = require('../utils/types.util');
+const { typeOf } = require('nodester/utils/types');
 const { parseRouteHandler } = require('./handlers.util');
 
 
@@ -33,7 +33,7 @@ function _validateParsedRouteMethood(parsedRoute) {
  * @param {Function} handler
  *
  * @alias wrapRouteHandler
- * @api public
+ * @access public
  */
 function _wrapRouteHandler(routeInstance, handler) {
 	const handlerType = typeOf(handler);

package/lib/router/utils.js

@@ -1,5 +1,5 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
 

package/lib/stacks/MarkersStack.js

@@ -1,5 +1,5 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
 
@@ -13,11 +13,11 @@ const consl = require('nodester/loggers/console');
 const debug = require('debug')('nodester:MiddlewareStack');
 
 
-/*
+/**
  * Creates new MarkersStack.
+ * @class
  *
  * @return {MarkersStack}
- *
  */
 module.exports = class MarkersStack {
 	constructor() {
@@ -31,12 +31,12 @@ module.exports = class MarkersStack {
 	/**
 	 * Add the given middleware `fn` to the stack.
 	 *
-	 * @param {String} markerName
+	 * @param {string} markerName
 	 * @param {Function} fn
 	 *
-	 * @return {Integer} index of new middleware
+	 * @return {Int} index - of the new middleware
 	 *
-	 * @api public
+	 * @access public
 	 */
 	add(markerName='', fn) {
 		try {
@@ -55,9 +55,11 @@ module.exports = class MarkersStack {
 	/**
 	 * Get middleware function by marker name.
 	 *
-	 * @param {String} markerName
+	 * @param {string} markerName
+	 *
+	 * @return {Function} marker
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get(markerName='') {
 		try {

package/lib/stacks/MiddlewaresStack.js

@@ -1,5 +1,5 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
 
@@ -15,14 +15,13 @@ const consl = require('nodester/loggers/console');
 const debug = require('debug')('nodester:MiddlewaresStack');
 
 
-/*
+/**
  * Creates new MiddlewaresStack.
- *
+ * @class
  * @param {Object}  [opts]
- * @param {Boolean} opts.finalhandlerEnabled
+ * @param {boolean} opts.finalhandlerEnabled
  *
  * @return {MiddlewaresStack}
- *
  */
 module.exports = class MiddlewaresStack {
 	constructor(opts={}) {
@@ -56,9 +55,9 @@ module.exports = class MiddlewaresStack {
 	/**
 	 * Indicates whether user can add more middlewares or not.
 	 *
-	 * @return {Boolean} isLocked
+	 * @return {boolean} isLocked
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get isLocked() {
 		return this._isLocked === true;
@@ -70,11 +69,11 @@ module.exports = class MiddlewaresStack {
 	 * Add the given middleware `fn` to the stack.
 	 *
 	 * @param {Function} fn
-	 * @param {Integer} index (0 or undefined)
+	 * @param {Int} index (0 or undefined)
 	 *
-	 * @return {Integer} index of the new middleware
+	 * @return {Int} index of the new middleware
 	 *
-	 * @api public
+	 * @access public
 	 */
 	add(fn, index) {
 		try {
@@ -109,11 +108,11 @@ module.exports = class MiddlewaresStack {
 	/**
 	 * Removes middleware at index.
 	 *
-	 * @param {Integer} index
+	 * @param {Int} index
 	 *
 	 * @return {MiddlewaresStack} self
 	 *
-	 * @api public
+	 * @access public
 	 */
 	remove(index=-1) {
 		try {
@@ -135,10 +134,10 @@ module.exports = class MiddlewaresStack {
 	}
 
 
-	/*
+	/**
 	 * Prepare stack for processing.
 	 *
-	 * @api public
+	 * @access public
 	 */
 	lock() {
 		if (this._finalhandlerEnabled) {
@@ -153,14 +152,14 @@ module.exports = class MiddlewaresStack {
 	}
 
 
-	/*
+	/**
 	 * Unlocks stack.
 	 *
-	 * @api public
+	 * @access public
 	 */
 	unlock() {
 		this._isLocked = false;
-		
+
 		if (this._finalhandlerEnabled) {
 			this._middlewares.pop();
 		}
@@ -169,10 +168,15 @@ module.exports = class MiddlewaresStack {
 	}
 
 
-	/*
-	 * Start chain.
+	/**
+	 * Call the first middleware in the stack.
+	 * Every N-th middleware will be called by the previous one in the stack by invoking next().
+	 *
+	 * @param {IncomingMessage} req
+	 * @param {ServerResponse} res
+	 * @param {Function} next
 	 *
-	 * @api public
+	 * @access public
 	 */
 	process(req, res, next) {
 		let middlewareOffset = -1;

package/lib/structures/Enum.js

@@ -1,11 +1,17 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
  
 'use strict';
 
 
+/**
+ * @class
+ * @classdesc Convinient structure to describe a set of constants.
+ * 
+ * @param {Object} constantsList
+ */
 module.exports = function Enum(constantsList={}) {
 	_setGetters(this, constantsList);