nodester 0.1.5 → 0.2.1

package/Readme.md

@@ -1,11 +1,26 @@
 # nodester
->  A robust and flexible boilerplate framework that makes iterative development easy.
+
+[![NPM version](https://img.shields.io/npm/v/nodester)](https://www.npmjs.com/package/nodester)
+[![License](https://img.shields.io/npm/l/nodester)](https://www.npmjs.com/package/nodester)
+
+> **nodester** is a modern and versatile Node.js framework designed to streamline the development of robust and scalable web applications.
+
+**nodester Query Language (NQL):** The main reason of nodester's existence is the [nodester Query Language (NQL)](docs/Queries.md), an extension of standard REST API syntax, it lets you craft complex queries with hierarchical associations.
+
+
+## Installation
+
+Install with NPM
+
+```shell
+npm install -S nodester
+```
+
 
 ## Table of Contents
 
 - [Usage](#usage)
 - [Documentation](#documentation)
-- [Extending App](#extending-application-functionality)
 - [Philosophy](#philosophy)
 - [License](#license)
 - [Copyright](#copyright)
@@ -24,6 +39,7 @@ app.listen(8080, function() {
   console.log('listening on port', app.port);
 });
 ```
+[How to setup "db" ➡️](docs/App.md#with-database)
 
 
 ## Documentation
@@ -33,10 +49,11 @@ app.listen(8080, function() {
 [Core concepts documentation ➡️](docs/CoreConcepts.md)
 
 
-### Queries & Querying - Nodester Query Language (NQR)
-One of the main power points of nodester is it's query language. It's an extension of a REST API syntaxis for a broader integration with a database SQL. Read more about it in the documentation:
+### Queries & Querying - Nodester Query Language (NQL)
+The true strength of nodester lies in its query language. Serving as an extension of standard REST API syntax, it brings many aspects of SQL into REST requests, providing developers with a simple yet potent tool for expressive and efficient data querying.
 
-[NQR documentaion ➡️](docs/Queries.md)
+Read more about it in the documentation:
+[NQL documentaion ➡️](docs/Queries.md)
 
 
 ### Database
@@ -46,61 +63,8 @@ Supported drivers:
 - PostgreSQL
 
 
-### Extending Application functionality
-
-
-#### Extending instance (safe way):
-
-```js
-const serveStatic = require('serve-static');
-
-const nodester = require('nodester');
-
-const app = new nodester();
-app.extend('static', serveStatic);
-app.static(<path_to_static_directory/>);
-```
-
-Short:
-```js
-const serveStatic = require('serve-static');
-
-const nodester = require('nodester');
-
-const app = new nodester();
-app.extend('static', serveStatic)(<path_to_static_directory/>);
-```
-
-Of course you might just do this:
-```js
-const serveStatic = require('serve-static');
-
-const nodester = require('nodester');
-
-const app = new nodester();
-app.static = serveStatic;
-````
-But you'll never know if you did override any of the app's properties or did not.
-
-
-#### Extending class:
-
-If you really want to override properties or use `nodester` as a boilerplate, you should extend default Application class:
-
-```js
-const NodesterApp = require('nodester');
-
-class MyApp extends NodesterApp {
-  constructor(opts) {
-    super(opts)
-  }
-
-  // Override everything you want here...
-}
-
-// Don't forget to expose.
-module.exports = MyApp;
-```
+### Application
+[Application documentation ➡️](docs/App.md)
 
 
 ## Philosophy
@@ -109,7 +73,7 @@ The Philosophy of `nodester` is to provide a developer with a tool that can buil
 
 ### Goal
 
-The goal of `nodester` is to be a robust and flexible framework that makes development in iteratations easy, and further scale possible.
+The goal of `nodester` is to be a robust and flexible framework that makes development in iteratations easy, while laying the foundation for seamless scalability in the future.
 
 
 ## LICENSE

package/lib/application/index.js

@@ -6,7 +6,7 @@
 'use strict';
 
 const Emitter = require('events');
-const DefaultRouter = require('../router');
+const NodesterRouter = require('../router');
 
 // Server:
 const http = require('http');
@@ -14,45 +14,70 @@ const request = require('../http/request');
 const response = require('../http/response');
 
 // Middlewares:
-const nodesterQL = require('../middlewares/ql/sequelize');
 const bodyParser = require('body-parser');
+const cookies = require('nodester/middlewares/cookies');
+const nodesterQL = require('nodester/ql/sequelize');
+
+// DB setup.
+const { associateModels } = require('nodester/models/associate');
 
 // Utils:
+const Params = require('nodester/params');
 const {
 	typeOf,
 	isConstructor
 } = require('../utils/types.util');
-const {
-	associateModels
-} = require('../database/utils');
-
 const { merge } = require('../utils/objects.util');
+
+// Arguments validator.
+const { ensure } = require('../validators/arguments');
+
+// Console:
 const consl = require('nodester/loggers/console');
 const debug = require('debug')('nodester:application');
 
 
-module.exports = class Application extends Emitter {
+module.exports = class NodesterApplication extends Emitter {
 	
 	/**
-	 * Initialize a new `Application`.
+	 * Initialize new `NodesterApplication`.
+	 *
+	 * @param {Object}     [options]
+	 * @param {String|Int} options.port
+	 * @param {String}     options.title
+	 * @param {Boolean}    options.finalhandlerEnabled
+	 * @param {Object}     options.middlewares
 	 *
 	 * @api public
 	 */
-	constructor(opts={}) {
+	constructor(options={}) {
 		super();
 
+		ensure(options, 'object', 'options');
+
+		// Unwrap options:
+		const {
+			port,
+			title,
+			finalhandlerEnabled,
+			middlewares
+		} = Params((options ?? {}), {
+			port: 8080,
+			title: null,
+			finalhandlerEnabled: true,
+			middlewares: {}
+		});
+
+
 		// Fallback port.
-		this.port = opts?.port ?? 8080;
+		this.port = port;
 
-		// Reference to router.
-		this._router = new DefaultRouter({ finalhandlerEnabled: true });
+		// Router acts as a MiddlewareStack for the application.
+		this._router = new NodesterRouter({ finalhandlerEnabled });
 
 		// Reference to the database connection.
 		this._database = null;
 
-		// Reference to the Query parser.
-		this._queryParser = nodesterQL;
-
 		// Reference to the http(s) server,
 		this.server = null;
 
@@ -61,16 +86,67 @@ module.exports = class Application extends Emitter {
 		};
 
 		// Default middlewares:
-		const _withoutMiddlewares = opts?.middlewares?.without ?? [];
+		const _withoutMiddlewares = middlewares?.without ?? [];
+
+		// !WARNING: Order of middlewares is important:
+
+		if (_withoutMiddlewares.indexOf('nodester-ql') === -1) {
+			this.use(nodesterQL());
+		}
 
 		if (_withoutMiddlewares.indexOf('body-parser') === -1) {
 			this.use(bodyParser.json());
 		}
 
+		if (_withoutMiddlewares.indexOf('cookies') === -1) {
+			this.use(cookies());
+		}
+
+		// User can title their application:
+		if (!!title) {
+			// Rename CLI process.
+			process.title = title;
+		}
+
 		// Indicatorors.
-		this.isListening = false;
+		this._isListening = false;
+	}
+
+	// Getters:
+
+	/**
+	 * @return {MiddlewaresStack}
+	 *
+	 * @api public
+	 */
+	get middlewaresStack() {
+		return this._router.middlewaresStack;
+	}
+
+	/**
+	 * Indicates whether user can add more middlewares or not.
+	 *
+	 * @return {Boolean} isLocked
+	 *
+	 * @api public
+	 */
+	get isLocked() {
+		return this._router.isLocked;
+	}
+
+	/**
+	 * Indicates whether app is awaiting requests.
+	 *
+	 * @return {Boolean} isListening
+	 *
+	 * @api public
+	 */
+	get isListening() {
+		return this._isListening;
 	}
 
+	// Getters\
+
 	/*
 	 * Expose the prototype that will get set on requests.
 	 *
@@ -98,7 +174,7 @@ module.exports = class Application extends Emitter {
 	/*
 	 * Sets (or overrides):
 	 * - (database) main database of the application and tries to make connection
-	 * - (router) default Router
+	 * - (router) default NodesterRouter
 	 *
 	 * @api public
 	 */
@@ -114,34 +190,42 @@ module.exports = class Application extends Emitter {
 	 * Sets (or overrides) main database of the application and tries to make connection.
 	 *
 	 * @param {Sequilize} sequilizeConnection
-	 * @param {Boolean} crashOnError
+	 * @param {Object}  [options]
+	 * @param {Boolean} options.associateModels
+	 * @param {Boolean} options.crashOnError
+	 *
 	 * @return {sequilizeConnection.authenticate}
 	 *
-	 * @public
+	 * @api public
 	 */
-	async setDatabase(sequilizeConnection, crashOnError=true) {
+	async setDatabase(sequilizeConnection, options={}) {
 		try {
 			if (!sequilizeConnection) {
-				const err = new TypeError('Connection to database (Sequilize) can not be null or undefined.');
+				const err = new TypeError('Connection to a database (Sequilize) can not be null or undefined.');
 				throw err;
 			}
 
-			if (this.isListening === true) {
-				const err = new Error(`Can't set database after application start.`);
+			if (this._isListening === true) {
+				const err = new Error(`Can't set database after an application start.`);
 				throw err;
 			}
 
 			// Test connection.
 			const result = await sequilizeConnection.authenticate();
-			// Associate models.
-			await associateModels(sequilizeConnection.models);
+
+			if (options?.associateModels === true) {
+				// Associate models between each other.
+				await associateModels(sequilizeConnection);	
+			}
+			
 			// Set database.
 			this._database = sequilizeConnection;
 
 			return Promise.resolve(result);
 		}
 		catch(error) {
-			if (crashOnError === true) {
+			if (options?.crashOnError === true) {
+				Error.captureStackTrace(error, this.setDatabase);
 				throw error;
 			}
 			else {
@@ -156,9 +240,9 @@ module.exports = class Application extends Emitter {
 	/*
 	 * Returns main database of the application.
 	 *
-	 * @return {SequilizeConnection}
+	 * @return {SequilizeConnection} database
 	 *
-	 * @public
+	 * @api public
 	 */
 	get database() {
 		return this._database;
@@ -168,7 +252,9 @@ module.exports = class Application extends Emitter {
 	/**
 	 * Overrides default Router.
 	 *
-	 * @public
+	 * @param {NodesterRouter} newRouter
+	 *
+	 * @api public
 	 */
 	setRouter(newRouter) {
 		if (isConstructor(newRouter)) {
@@ -185,7 +271,7 @@ module.exports = class Application extends Emitter {
 	 *
 	 * @return {NodesterRouter}
 	 *
-	 * @public
+	 * @api public
 	 */
 	get router() {
 		return this._router;
@@ -216,7 +302,15 @@ module.exports = class Application extends Emitter {
 	 * @api public
 	 */
 	use(fnOrRouter) {
-		return this._router.use(fnOrRouter);
+		try {
+			ensure(fnOrRouter, 'object|function,required', 'fnOrRouter');
+		
+			return this._router.use(fnOrRouter);
+		}
+		catch(error) {
+			Error.captureStackTrace(error, this.use);
+			throw error;
+		}
 	}
 
 
@@ -227,7 +321,15 @@ module.exports = class Application extends Emitter {
 	 * @api public
 	 */
 	only(markerName='') {
-		return this._router.only(markerName);
+		try {
+			ensure(markerName, 'string,required', 'markerName');
+
+			return this._router.only(markerName);
+		}
+		catch(error) {
+			Error.captureStackTrace(error, this.only);
+			throw error;
+		}
 	}
 
 
@@ -237,13 +339,16 @@ module.exports = class Application extends Emitter {
 	 * @api public
 	 */
 	beforeStart(fn) {
-		if (typeOf(fn) !== 'function') {
-			const err = new TypeError('"fn" argument must be a function');
-			throw err;
-		}
-		this._hooks.beforeStart = fn;
+		try {
+			ensure(fn, 'function,required', 'fn');
 
-		return this._hooks.beforeStart;
+			this._hooks.beforeStart = fn;
+			return this._hooks.beforeStart;
+		}
+		catch(error) {
+			Error.captureStackTrace(error, this.beforeStart);
+			throw error;
+		}
 	}
 
 
@@ -260,19 +365,25 @@ module.exports = class Application extends Emitter {
 			await this._hooks.beforeStart.call(this);
 		}
 		catch(error) {
-			console.error('Application did not start due to error.');
+			console.error('NodesterApplication did not start due to error.');
 			consl.error(error);
+
+			Error.captureStackTrace(error, this.start);
 			return Promise.reject(error);
 		}
 
-		// Add query parser.
-		this._router.add.middleware(this._queryParser, 0);
 
-		// Prepare router for processing.
-		this._router.lock();
+		try {
+			// Prepare router for processing.
+			this._router.lock();
 
-		const handler = this.handle.bind(this);
-		return handler;
+			const handler = this.handle.bind(this);
+			return handler;
+		}
+		catch(error) {
+			Error.captureStackTrace(error, this.start);
+			return Promise.reject(error);
+		}
 	}
 
 
@@ -281,26 +392,35 @@ module.exports = class Application extends Emitter {
 	 *
 	 *    http.createServer(app.start()).listen(...)
 	 *
-	 * @param {Int} port
+	 * @param {Integer|String} port
 	 * @param {Mixed} ...
+	 *
 	 * @return {import('http').Server}
 	 *
 	 * @api public
 	 */
 	async listen(port, ...args) {
-		// Remember port:
-		const _port = port ?? this.port;
-		this.port = _port;
+		try {
+			ensure(port, 'number|string,required', 'port');
 
-		debug(`listen on port ${ this.port }`);
+			// Remember port:
+			const _port = port ?? this.port;
+			this.port = _port;
 
-		if (!this.server) {
-			const handler = await this.start();
-			this.server = http.createServer(handler);
-		}
+			debug(`listen on port ${ this.port }`);
+
+			if (!this.server) {
+				const handler = await this.start();
+				this.server = http.createServer(handler);
+			}
 
-		this.isListening = true;
-		return this.server.listen(_port, ...args);
+			this._isListening = true;
+			return this.server.listen(_port, ...args);
+		}
+		catch(error) {
+			Error.captureStackTrace(error, this.listen);
+			throw error;
+		}
 	}
 
 
@@ -324,15 +444,19 @@ module.exports = class Application extends Emitter {
 
 	/**
 	 * Extends Application & makes sure, that "key" param is not present already.
+	 *
 	 * @param {String} key
 	 * @param {Any} fnOrProperty
+	 *
 	 * @return {Any} fnOrProperty in Application
 	 *
 	 * @api public
 	 */
 	extend(key='', fnOrProperty) {
-		const keys = Object.keys(this);
-		if (keys.indexOf(key) > -1) {
+		ensure(key, 'string,required', 'key');
+		ensure(fnOrProperty, 'required', 'fnOrProperty');
+
+		if (typeof this[key] !== 'undefined') {
 			const err = new TypeError(`Key ${ key } is already present in Application instance`);
 			throw err;
 		}
@@ -349,16 +473,14 @@ module.exports = class Application extends Emitter {
 	 * @api public
 	 */
 	stop() {
-		if (this.isListening !== true) {
+		if (this._isListening !== true) {
 			console.warn('Nothing to stop. Server is not listening.');
 			return;
 		}
 
 		this.server.close();
-		this.isListening = false;
+		this._isListening = false;
 
 		this._router.unlock();
-		// Remove query parser.
-		this._router.remove.middleware(0);
 	}
 }

package/lib/body/extract.js

@@ -2,6 +2,7 @@
  * /nodester
  * MIT Licensed
  */
+
 'use strict';
 
 const httpCodes = require('nodester/http/codes');
@@ -11,6 +12,16 @@ const Sanitizations = require('nodester/utils/sanitizations');
 
 module.exports = extract;
 
+/*
+ * Extracts data from the body, based on the rules in "filter".
+ *
+ * @param {Object} body
+ * @param {NodesterFilter} filter
+ * @param {SequilizeModel} model
+ *
+ * @api public
+ * @return {Object} filteredBody
+ */
 function extract(body, filter=null, model) {
 
 	const sequelize = model.sequelize;
@@ -23,7 +34,7 @@ function extract(body, filter=null, model) {
 
 
 	// Result object.
-	const newBody = {};
+	const filteredBody = {};
 
 	for (const [key, value] of bodyEntries) {
 		const isInclude = availableIncludes.indexOf(key) > -1;
@@ -48,7 +59,7 @@ function extract(body, filter=null, model) {
 			}
 			const sanitized = Sanitizations[typeName](value, sanitizationOptions);
 
-			newBody[key] = sanitized;
+			filteredBody[key] = sanitized;
 
 			continue;
 		}
@@ -64,7 +75,7 @@ function extract(body, filter=null, model) {
 
 			const association = model.associations[key];
 	
-			newBody[key] = extract(value[0], filter.includes[key], association.target);
+			filteredBody[key] = extract(value[0], filter.includes[key], association.target);
 
 			continue;
 		}
@@ -74,5 +85,5 @@ function extract(body, filter=null, model) {
 		throw err;
 	}
 	
-	return newBody;
+	return filteredBody;
 }

package/lib/constants/Bounds.js

@@ -0,0 +1,15 @@
+const Enum = require('nodester/enum');
+
+const limit = {
+	min: 1,
+	max: 3,
+}
+
+const skip = {
+	min: 0
+}
+
+module.exports = new Enum({
+	limit,
+	skip
+});

package/lib/constants/Clauses.js

@@ -0,0 +1,13 @@
+const Enum = require('nodester/enum');
+
+const LIMIT = 'limit';
+const SKIP = 'skip';
+const ORDER = 'order';
+const ORDER_BY = 'order_by';
+
+module.exports = new Enum({
+	LIMIT,
+	SKIP,
+	ORDER,
+	ORDER_BY,
+});

package/lib/constants/ResponseFormats.js

@@ -1,7 +1,7 @@
-const ConstantsEnum = require('nodester/constants/ConstantsEnum');
+const Enum = require('nodester/enum');
 
 
-module.exports = new ConstantsEnum({
+module.exports = new Enum({
 	JSON: 'JSON',
 	XML: 'XML',
 });

package/lib/controllers/methods/index.js

@@ -1,3 +1,10 @@
+/*!
+ * /nodester
+ * MIT Licensed
+ */
+ 
+'use strict';
+
 
 module.exports = {
 	getOne: _getOne,