nodester 0.2.5 → 0.2.8

package/.eslintrc.js

@@ -0,0 +1,13 @@
+module.exports = {
+	parserOptions: {
+		ecmaVersion: 2023, // or the latest version supported by ESLint
+	},
+	plugins: ['jsdoc'],
+	rules: {
+		'jsdoc/check-alignment': 'warn',
+		'jsdoc/check-indentation': 'warn',
+		'jsdoc/check-syntax': 'warn',
+		'jsdoc/require-param-type': 'warn',
+		'jsdoc/valid-types': 'warn',
+	},
+};

package/Readme.md

@@ -5,7 +5,11 @@
 
 > **nodester** is a Node.js framework designed to solve the problem of a complex data querying over HTTP.
 
-The main reason of nodester's existence is the [nodester Query Language (NQL)](docs/nql/Introduction.md), an extension of standard REST API syntax, it lets you craft complex queries with hierarchical associations.
+The main reason of nodester's existence is the [nodester Query Language (NQL) ➡️](docs/nql/Introduction.md), an extension of standard REST API syntax, it lets you craft complex queries with hierarchical associations.
+
+Building an application which allows users to build their own REST queries raises huge security concerns.
+That's why **nodester** was not developped as a middleware. It's a framework equipped with a set of technologies enabling you to fully customize the request-response flow down to the specific user and a database column.
+Check out [core concepts documentation ➡️](docs/CoreConcepts.md) for more info.
 
 
 ## Installation
@@ -67,6 +71,11 @@ Supported drivers:
 [Application documentation ➡️](docs/App.md)
 
 
+### Comments
+
+We (contributors) use [JSDoc](https://jsdoc.app/) to describe the actual code.
+
+
 ## Philosophy
 
 The Philosophy of `nodester` is to provide a developer with a tool that can build an app (or feature) in hours and scale it with ease for years.
@@ -76,9 +85,8 @@ The Philosophy of `nodester` is to provide a developer with a tool that can buil
 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
-
-MIT
+## License
+[MIT](LICENSE)
 
 ## Copyright
 Copyright 2021-present [Mark Khramko](https://github.com/MarkKhramko)

package/lib/application/index.js

@@ -1,5 +1,5 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
 
@@ -26,7 +26,7 @@ const Params = require('nodester/params');
 const {
 	typeOf,
 	isConstructor
-} = require('../utils/types.util');
+} = require('nodester/utils/types');
 const { merge } = require('../utils/objects.util');
 
 // Arguments validator.
@@ -37,23 +37,32 @@ const consl = require('nodester/loggers/console');
 const debug = require('debug')('nodester:application');
 
 
+/**
+ * Initialize new `NodesterApplication`.
+ *
+ * @class
+ *
+ * @param {Object}     [options]
+ * @param {string|Int} options.port
+ * @param {string}     options.title
+ * @param {boolean}    options.finalhandlerEnabled
+ * @param {Object}     [options.middlewares={}]
+ * @param {Object}     [options.middlewares.without=[]]
+ *
+ * @access public
+ */
 module.exports = class NodesterApplication extends Emitter {
-	
-	/**
-	 * 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(options={}) {
 		super();
 
-		ensure(options, 'object', 'options');
+		try {
+			ensure(options, 'object', 'options');
+		}
+		catch(error) {
+			Error.captureStackTrace(error, this.constructor);
+			throw error;
+		}
 
 		// Unwrap options:
 		const {
@@ -117,7 +126,7 @@ module.exports = class NodesterApplication extends Emitter {
 	/**
 	 * @return {MiddlewaresStack}
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get middlewaresStack() {
 		return this._router.middlewaresStack;
@@ -126,9 +135,9 @@ module.exports = class NodesterApplication extends Emitter {
 	/**
 	 * Indicates whether user can add more middlewares or not.
 	 *
-	 * @return {Boolean} isLocked
+	 * @return {boolean} isLocked
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get isLocked() {
 		return this._router.isLocked;
@@ -137,9 +146,9 @@ module.exports = class NodesterApplication extends Emitter {
 	/**
 	 * Indicates whether app is awaiting requests.
 	 *
-	 * @return {Boolean} isListening
+	 * @return {boolean} isListening
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get isListening() {
 		return this._isListening;
@@ -147,10 +156,10 @@ module.exports = class NodesterApplication extends Emitter {
 
 	// Getters\
 
-	/*
+	/**
 	 * Expose the prototype that will get set on requests.
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get request() {
 		return Object.create(request, {
@@ -159,10 +168,10 @@ module.exports = class NodesterApplication extends Emitter {
 	}
 
 
-	/*
+	/**
 	 * Expose the prototype that will get set on responses.
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get response() {
 		return Object.create(response, {
@@ -171,12 +180,12 @@ module.exports = class NodesterApplication extends Emitter {
 	}
 
 
-	/*
+	/**
 	 * Sets (or overrides):
 	 * - (database) main database of the application and tries to make connection
 	 * - (router) default NodesterRouter
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get set() {
 		return {
@@ -191,12 +200,12 @@ module.exports = class NodesterApplication extends Emitter {
 	 *
 	 * @param {Sequilize} sequilizeConnection
 	 * @param {Object}  [options]
-	 * @param {Boolean} options.associateModels
-	 * @param {Boolean} options.crashOnError
+	 * @param {boolean} options.associateModels
+	 * @param {boolean} options.crashOnError
 	 *
 	 * @return {sequilizeConnection.authenticate}
 	 *
-	 * @api public
+	 * @access public
 	 */
 	async setDatabase(sequilizeConnection, options={}) {
 		try {
@@ -237,12 +246,12 @@ module.exports = class NodesterApplication extends Emitter {
 	}
 
 
-	/*
+	/**
 	 * Returns main database of the application.
 	 *
 	 * @return {SequilizeConnection} database
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get database() {
 		return this._database;
@@ -254,7 +263,7 @@ module.exports = class NodesterApplication extends Emitter {
 	 *
 	 * @param {NodesterRouter} newRouter
 	 *
-	 * @api public
+	 * @access public
 	 */
 	setRouter(newRouter) {
 		if (isConstructor(newRouter)) {
@@ -266,23 +275,23 @@ module.exports = class NodesterApplication extends Emitter {
 	}
 
 
-	/*
+	/**
 	 * Returns NodesterRouter object.
 	 *
 	 * @return {NodesterRouter}
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get router() {
 		return this._router;
 	}
 
 
-	/*
+	/**
 	 * Adds:
 	 * - (middleware) new middleware to the stack;
 	 *
-	 * @api public
+	 * @access public
 	 */
 	get add() {
 		return {
@@ -294,12 +303,12 @@ module.exports = class NodesterApplication extends Emitter {
 	}
 
 
-	/*
+	/**
 	 * Proxy to router.use()
 	 *
 	 * @param {Function|NodesterRouter} fnOrRouter
 	 *
-	 * @api public
+	 * @access public
 	 */
 	use(fnOrRouter) {
 		try {
@@ -314,11 +323,11 @@ module.exports = class NodesterApplication extends Emitter {
 	}
 
 
-	/*
+	/**
 	 *
-	 * @param {String} markerName
+	 * @param {string} markerName
 	 *
-	 * @api public
+	 * @access public
 	 */
 	only(markerName='') {
 		try {
@@ -336,7 +345,7 @@ module.exports = class NodesterApplication extends Emitter {
 	/**
 	 * Sets beforeStart hook.
 	 *
-	 * @api public
+	 * @access public
 	 */
 	beforeStart(fn) {
 		try {
@@ -358,7 +367,7 @@ module.exports = class NodesterApplication extends Emitter {
 	 *
 	 * @return {Function}
 	 *
-	 * @api public
+	 * @access public
 	 */
 	async start() {
 		try {
@@ -389,15 +398,14 @@ module.exports = class NodesterApplication extends Emitter {
 
 	/**
 	 * Shorthand for:
-	 *
-	 *    http.createServer(app.start()).listen(...)
+	 * http.createServer(app.start()).listen(...)
 	 *
 	 * @param {Integer|String} port
 	 * @param {Mixed} ...
 	 *
 	 * @return {import('http').Server}
 	 *
-	 * @api public
+	 * @access public
 	 */
 	async listen(port, ...args) {
 		try {
@@ -427,7 +435,7 @@ module.exports = class NodesterApplication extends Emitter {
 	/**
 	 * Handles server request.
 	 *
-	 * @api public
+	 * @access public
 	 */
 	handle(req, res) {
 		// Req & res with mixins:
@@ -445,12 +453,12 @@ module.exports = class NodesterApplication extends Emitter {
 	/**
 	 * Extends Application & 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 Application
+	 * @return {any} fnOrProperty in Application
 	 *
-	 * @api public
+	 * @access public
 	 */
 	extend(key='', fnOrProperty) {
 		ensure(key, 'string,required', 'key');
@@ -470,7 +478,7 @@ module.exports = class NodesterApplication extends Emitter {
 	/**
 	 * Stops server
 	 *
-	 * @api public
+	 * @access public
 	 */
 	stop() {
 		if (this._isListening !== true) {

package/lib/body/extract.js

@@ -1,5 +1,5 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
 
@@ -12,20 +12,20 @@ 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
+ * @access public
  * @return {Object} filteredBody
  */
 function extract(body, filter=null, model) {
 
 	const sequelize = model.sequelize;
-	const modelFields = Object.keys(model.tableAttributes);
+	const modelAttributes = Object.keys(model.tableAttributes);
 	const availableIncludes = Object.keys(model.associations);
 
 	const bodyEntries = Object.entries(body);
@@ -38,15 +38,15 @@ function extract(body, filter=null, model) {
 
 	for (const [key, value] of bodyEntries) {
 		const isInclude = availableIncludes.indexOf(key) > -1;
-		const isField = modelFields.indexOf(key) > -1;
+		const isAttribute = modelAttributes.indexOf(key) > -1;
 
-		if ((!isField || filter.fields.indexOf(key) === -1) && !isInclude) {
-			const err = new Error(`Field '${ key }' is not available.`);
+		if ((!isAttribute || filter.attributes.indexOf(key) === -1) && !isInclude) {
+			const err = new Error(`Attribute '${ key }' is not available.`);
 			err.status = httpCodes.NOT_ACCEPTABLE;
 			throw err;
 		}
 
-		if (isField) {
+		if (isAttribute) {
 			const column = model.rawAttributes[key];
 			const typeName = column.type.constructor.name;
 			// Optional validation.
@@ -80,7 +80,7 @@ function extract(body, filter=null, model) {
 			continue;
 		}
 
-		const err = new Error(`Unknown field '${ key }'.`);
+		const err = new Error(`Unknown attribute '${ key }'.`);
 		err.status = httpCodes.NOT_ACCEPTABLE;
 		throw err;
 	}

package/lib/controllers/methods/index.js

@@ -1,5 +1,5 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
  
@@ -7,17 +7,20 @@
 
 
 module.exports = {
-	getOne: _getOne,
-	getMany: _getMany,
+	getOne:    _getOne,
+	getMany:   _getMany,
 	createOne: _createOne,
 	updateOne: _updateOne,
 	deleteOne: _deleteOne
 }
 
 
-/*
+/**
+ * @param {IncomingMessage} req
+ * @param {ServerResponse} res
+ * 
  * @alias getOne
- * @api public
+ * @access public
  */
 async function _getOne(req, res) {
 	try {
@@ -52,9 +55,12 @@ async function _getOne(req, res) {
 }
 
 
-/*
+/**
+ * @param {IncomingMessage} req
+ * @param {ServerResponse} res
+ * 
  * @alias getMany
- * @api public
+ * @access public
  */
 async function _getMany(req, res) {
 	try {
@@ -86,9 +92,12 @@ async function _getMany(req, res) {
 }
 
 
-/*
+/**
+ * @param {IncomingMessage} req
+ * @param {ServerResponse} res
+ * 
  * @alias createOne
- * @api public
+ * @access public
  */
 async function _createOne(req, res) {
 	try {
@@ -124,9 +133,12 @@ async function _createOne(req, res) {
 }
 
 
-/*
+/**
+ * @param {IncomingMessage} req
+ * @param {ServerResponse} res
+ * 
  * @alias updateOne
- * @api public
+ * @access public
  */
 async function _updateOne(req, res) {
 	try {
@@ -162,9 +174,12 @@ async function _updateOne(req, res) {
 }
 
 
-/*
+/**
+ * @param {IncomingMessage} req
+ * @param {ServerResponse} res
+ * 
  * @alias deleteOne
- * @api public
+ * @access public
  */
 async function _deleteOne(req, res) {
 	try {

package/lib/controllers/mixins/index.js

@@ -1,5 +1,5 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
  
@@ -40,14 +40,14 @@ module.exports = {
  * Sets one of or all of CRUD methods to Controller.
  *
  * @param {Function|Object} controller
- * @param {Object} options
- * @param {Function|Object} options.facade
- * @param {String}					options.name
+ * @param {Object}          options
+ * @param {NodesterFacade}  options.facade
+ * @param {string}					options.name
  * @param {Array}						options.only
  *
  * @return {Function|Object} controller
  *
- * @api public
+ * @access public
  * @alias withDefaultCRUD
  */
 function _withDefaultCRUD(controller, options={}) {
@@ -132,7 +132,7 @@ function _withDefaultCRUD(controller, options={}) {
  *
  * @return {Function|Object} controller
  *
- * @api public
+ * @access public
  * @alias withDefaultErrorProcessing
  */
 function _withDefaultErrorProcessing(controller, options={}) {
@@ -216,12 +216,12 @@ function _withDefaultErrorProcessing(controller, options={}) {
  * Sets one of or all of CRUD methods to Controller.
  *
  * @param {Function|Object} controller
- * @param {Function|Object} facade
- * @param {String} facadeName
+ * @param {NodesterFacade} facade
+ * @param {string} facadeName
  *
  * @return {Function|Object} controller
  *
- * @api public
+ * @access public
  * @alias setFacade
  */
 function _setFacade(controller, facade, facadeName=null) {
@@ -243,12 +243,12 @@ function _setFacade(controller, facade, facadeName=null) {
 /**
  * Sets one of CRUD methods to Controller.
  *
- * @param {Controller} controller
+ * @param {Function|Object} controller
  * @param {Function} fn
  *
- * @return {Controller} controller
+ * @return {Function|Object} controller
  *
- * @api public
+ * @access public
  * @alias setMethod
  */
 function _setMethod(controller, fn) {

package/lib/database/connection.js

@@ -1,10 +1,11 @@
-/*!
- * /nodester
+/**
+ * nodester
  * MIT Licensed
  */
+
 'use strict';
 
-// ORM.
+// The one and only!
 const Sequelize = require('sequelize');
 
 
@@ -12,27 +13,87 @@ module.exports = {
 	buildConnection: _buildConnection
 };
 
-function _buildConnection(opts={}) {
+/**
+ * @param {object}   [options={}] An object with options.
+ * @param {string}   [options.name] The name of the database
+ * @param {string}   [options.username=null] The username which is used to authenticate against the database.
+ * @param {string}   [options.password=null] The password which is used to authenticate against the database. Supports SQLCipher encryption for SQLite.
+ * @param {string}   [options.host='localhost'] The host of the relational database.
+ * @param {number}   [options.port] The port of the relational database.
+ * @param {string}   [options.username=null] The username which is used to authenticate against the database.
+ * @param {string}   [options.password=null] The password which is used to authenticate against the database.
+ * @param {string}   [options.database=null] The name of the database.
+ * @param {string}   [options.dialect] The dialect of the database you are connecting to. One of mysql, postgres, sqlite, db2, mariadb and mssql.
+ * @param {string}   [options.dialectModule=null] If specified, use this dialect library. For example, if you want to use pg.js instead of pg when connecting to a pg database, you should specify 'require("pg.js")' here
+ * @param {string}   [options.dialectModulePath=null] If specified, load the dialect library from this path. For example, if you want to use pg.js instead of pg when connecting to a pg database, you should specify '/path/to/pg.js' here
+ * @param {object}   [options.dialectOptions] An object of additional options, which are passed directly to the connection library
+ * @param {string}   [options.storage] Only used by sqlite. Defaults to ':memory:'
+ * @param {string}   [options.protocol='tcp'] The protocol of the relational database.
+ * @param {object}   [options.define={}] Default options for model definitions. See {@link Model.init}.
+ * @param {object}   [options.query={}] Default options for sequelize.query
+ * @param {string}   [options.schema=null] A schema to use
+ * @param {object}   [options.set={}] Default options for sequelize.set
+ * @param {object}   [options.sync={}] Default options for sequelize.sync
+ * @param {string}   [options.timezone='+00:00'] The timezone used when converting a date from the database into a JavaScript date. The timezone is also used to SET TIMEZONE when connecting to the server, to ensure that the result of NOW, CURRENT_TIMESTAMP and other time related functions have in the right timezone. For best cross platform performance use the format +/-HH:MM. Will also accept string versions of timezones supported by Intl.Locale (e.g. 'America/Los_Angeles'); this is useful to capture daylight savings time changes.
+ * @param {boolean}  [options.keepDefaultTimezone=false] A flag that defines if the default timezone is used to convert dates from the database.
+ * @param {number|null} [options.defaultTimestampPrecision] The precision for the `createdAt`/`updatedAt`/`deletedAt` DATETIME columns that Sequelize adds to models. Can be a number between 0 and 6, or null to use the default precision of the database. Defaults to 6.
+ * @param {string|boolean} [options.clientMinMessages='warning'] (Deprecated) The PostgreSQL `client_min_messages` session parameter. Set to `false` to not override the database's default.
+ * @param {boolean}  [options.standardConformingStrings=true] The PostgreSQL `standard_conforming_strings` session parameter. Set to `false` to not set the option. WARNING: Setting this to false may expose vulnerabilities and is not recommended!
+ * @param {Function} [options.logging=console.log] A function that gets executed every time Sequelize would log something. Function may receive multiple parameters but only first one is printed by `console.log`. To print all values use `(...msg) => console.log(msg)`
+ * @param {boolean}  [options.benchmark=false] Pass query execution time in milliseconds as second argument to logging function (options.logging).
+ * @param {string}   [options.queryLabel] A label to annotate queries in log output.
+ * @param {boolean}  [options.omitNull=false] A flag that defines if null values should be passed as values to CREATE/UPDATE SQL queries or not.
+ * @param {boolean}  [options.native=false] A flag that defines if native library shall be used or not. Currently only has an effect for postgres
+ * @param {boolean}  [options.ssl=undefined] A flag that defines if connection should be over ssl or not
+ * @param {boolean}  [options.replication=false] Use read / write replication. To enable replication, pass an object, with two properties, read and write. Write should be an object (a single server for handling writes), and read an array of object (several servers to handle reads). Each read/write server can have the following properties: `host`, `port`, `username`, `password`, `database`.  Connection strings can be used instead of objects.
+ * @param {object}   [options.pool] sequelize connection pool configuration
+ * @param {number}   [options.pool.max=5] Maximum number of connection in pool
+ * @param {number}   [options.pool.min=0] Minimum number of connection in pool
+ * @param {number}   [options.pool.idle=10000] The maximum time, in milliseconds, that a connection can be idle before being released.
+ * @param {number}   [options.pool.acquire=60000] The maximum time, in milliseconds, that pool will try to get connection before throwing error
+ * @param {number}   [options.pool.evict=1000] The time interval, in milliseconds, after which sequelize-pool will remove idle connections.
+ * @param {Function} [options.pool.validate] A function that validates a connection. Called with client. The default function checks that client is an object, and that its state is not disconnected
+ * @param {number}   [options.pool.maxUses=Infinity] The number of times a connection can be used before discarding it for a replacement, [`used for eventual cluster rebalancing`](https://github.com/sequelize/sequelize-pool).
+ * @param {boolean}  [options.quoteIdentifiers=true] Set to `false` to make table names and attributes case-insensitive on Postgres and skip double quoting of them.  WARNING: Setting this to false may expose vulnerabilities and is not recommended!
+ * @param {string}   [options.transactionType='DEFERRED'] Set the default transaction type. See `Sequelize.Transaction.TYPES` for possible options. Sqlite only.
+ * @param {string}   [options.isolationLevel] Set the default transaction isolation level. See `Sequelize.Transaction.ISOLATION_LEVELS` for possible options.
+ * @param {object}   [options.retry] Set of flags that control when a query is automatically retried. Accepts all options for [`retry-as-promised`](https://github.com/mickhansen/retry-as-promised).
+ * @param {Array}    [options.retry.match] Only retry a query if the error matches one of these strings.
+ * @param {number}   [options.retry.max] How many times a failing query is automatically retried.  Set to 0 to disable retrying on SQL_BUSY error.
+ * @param {number}   [options.retry.timeout] Maximum duration, in milliseconds, to retry until an error is thrown.
+ * @param {number}   [options.retry.backoffBase=100] Initial backoff duration, in milliseconds.
+ * @param {number}   [options.retry.backoffExponent=1.1] Exponent to increase backoff duration after each retry.
+ * @param {Function} [options.retry.report] Function that is executed after each retry, called with a message and the current retry options.
+ * @param {string}   [options.retry.name='unknown'] Name used when composing error/reporting messages.
+ * @param {boolean}  [options.noTypeValidation=false] Run built-in type validators on insert and update, and select with where clause, e.g. validate that arguments passed to integer fields are integer-like.
+ * @param {object}   [options.hooks] An object of global hook functions that are called before and after certain lifecycle events. Global hooks will run after any model-specific hooks defined for the same event (See `Sequelize.Model.init()` for a list).  Additionally, `beforeConnect()`, `afterConnect()`, `beforeDisconnect()`, and `afterDisconnect()` hooks may be defined here.
+ * @param {boolean}  [options.minifyAliases=false] A flag that defines if aliases should be minified (mostly useful to avoid Postgres alias character limit of 64)
+ * @param {boolean}  [options.logQueryParameters=false] A flag that defines if show bind parameters in log.
+ *
+ * @return {Sequelize} connection - Connection to the database.
+ *
+ * @alias buildConnection
+ * @access public
+ */
+function _buildConnection(options={}) {
 	
-
-	const dbName = opts.name;
-	const username = opts.username;
-	const password = opts.password;
-
+	const dbName = options.name;
+	const username = options.username;
+	const password = options.password;
 
 	const connection = new Sequelize(
 		dbName,
 		username,
 		password,
 		{
-			host: opts.host,
-			port: opts.port,
-			dialect: opts.dialect,
-			pool: opts.pool,
-			charset: opts.charset,
-			collate: opts.collate, 
-			timestamps: opts.timestamps,
-			logging: opts.logging
+			host: options.host,
+			port: options.port,
+			dialect: options.dialect,
+			pool: options.pool,
+			charset: options.charset,
+			collate: options.collate, 
+			timestamps: options.timestamps,
+			logging: options.logging
 		}
 	);