nodester 0.5.1 → 0.6.1

package/Readme.md

@@ -5,11 +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.
+Check out [core concepts documentation →](docs/CoreConcepts.md) for more info.
 
 
 ## Installation
@@ -39,36 +39,55 @@ const db = require('#db');
 const app = new nodester();
 app.set.database(db);
 
+// Optional beforeStart hook:
+app.beforeStart(async ()=>{
+  // Do any asynchronous initializations
+  // before app.listen
+  // ...
+});
+
+// Start the http server:
 app.listen(8080, function() {
   console.log('listening on port', app.port);
 });
+
+// Gracefully shut down:
+process.once('SIGTERM', () => {
+  app.stop(() => {
+    const pid = process.pid;
+    console.info('Process', pid, 'terminated\n');
+    process.exit(0);
+  });
+});
+
 ```
-[How to setup "db" ➡️](docs/App.md#with-database)
 
 
 ## Documentation
 
 
 ### Core concepts
-[Core concepts documentation ➡️](docs/CoreConcepts.md)
+[Core concepts documentation →](docs/CoreConcepts.md)
 
 
-### Queries & Querying - nodester Query Language (NQL)
+### 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.
 
 Read more about it in the documentation:
-[NQL documentaion ➡️](docs/nql/Introduction.md)
+[NQL documentaion →](docs/nql/Introduction.md)
 
 
 ### Database
-Nodester is built upon a powerful [Sequelize](https://sequelize.org/).
+Nodester is built upon a powerful [Sequelize](https://sequelize.org/).<br/>
 Supported drivers:
 - MySQL
 - PostgreSQL
 
+[How to setup a database →](docs/App.md#with-database)
+
 
 ### Application
-[Application documentation ➡️](docs/App.md)
+[Application documentation →](docs/App.md)
 
 
 ### Comments

package/lib/errors/NodesterQueryError.js

@@ -5,15 +5,10 @@
 
 'use strict';
 
-const {
-	NODESTER_QUERY_ERROR,
-} = require('nodester/constants/ErrorCodes');
 const {
 	NOT_ACCEPTABLE
 } = require('nodester/http/codes');
 
-const NodesterError = require('./NodesterError');
-
 
 /**
  * @class
@@ -22,11 +17,12 @@ const NodesterError = require('./NodesterError');
  *
  * @access public
  */
-module.exports = class NodesterQueryError extends NodesterError {
-	constructor(message) {
+module.exports = class NodesterQueryError extends Error {
+	constructor(message, status) {
 		super(message);
 
-		this.status = NOT_ACCEPTABLE;
+		this.name = this.constructor.name;
+		this.status = status ?? NOT_ACCEPTABLE;
 
 		Error.captureStackTrace(this, this.constructor);
 	}

package/lib/middlewares/ql/sequelize/interpreter/ModelsTree.js

@@ -17,21 +17,25 @@ class ModelsTreeNode {
 	constructor(model, parent=null, opts={}) {
 		this.model = model;
 		this.parent = parent;
+
 		this.activeParam = null;
 		this.op = null;
 		this.fn = null;
 
-		// for override:
 		this._attributes = [];
 		this._where = {};
 		this._functions = [];
+
+		// Clauses:
+		this.group_by = opts.group_by ?? undefined;
 		this.skip = 0;
 		this.limit = -1; // No limit
-
-		this._includes = opts.includes ?? [];
-
+		
 		this.order = opts.order ?? undefined;
 		this.order_by = opts.order_by ?? undefined;
+		// Clauses\
+
+		this._includes = opts.includes ?? [];
 	}
 
 	// Getters:
@@ -107,6 +111,7 @@ class ModelsTreeNode {
 
 			where: this.where,
 
+			group_by: this.group_by,
 			skip: this.skip,
 			limit: this.limit,
 			order: this.order,

package/lib/middlewares/ql/sequelize/interpreter/QueryLexer.js

@@ -8,18 +8,26 @@
 const Enum = require('nodester/enum');
 
 const { ModelsTree, ModelsTreeNode } = require('./ModelsTree');
+
+const { NodesterQueryError } = require('nodester/errors');
+
 const util = require('util');
 const debug = require('debug')('nodester:interpreter:QueryLexer');
 
 const PARAM_TOKENS = new Enum({
 	ATTRIBUTES: Symbol('attributes'),
-	
+
+	FUNCTIONS: Symbol('functions'),
+
+	INCLUDES: Symbol('includes'),
+
+	// Clauses:
+	GROUP_BY: Symbol('group_by'),
 	LIMIT: Symbol('limit'),
 	ORDER: Symbol('order'),
 	ORDER_BY: Symbol('order_by'),
 	SKIP: Symbol('skip'),
-
-	INCLUDES: Symbol('includes'),
+	// Clauses\
 });
 
 const OP_TOKENS = new Enum({
@@ -50,6 +58,7 @@ const OP_TOKENS = new Enum({
 });
 
 const FN_TOKENS = new Enum({
+	AVG: 'avg',
 	COUNT: 'count',
 });
 
@@ -179,25 +188,15 @@ module.exports = class QueryLexer {
 
 				// If end of FN token:
 				if (!!tree.node.fn) {
-					// If token is empty, error:
-					if (token === '') {
-						const err = UnexpectedCharError(i, char);
-						throw err;
-					}
-
-					let fnParams = {};
+					// Token is the param of this fn:
+					const fnParams = {
+						fn: tree.node.fn
+					};
 					switch (tree.node.fn) {
-						case 'count':
-							fnParams = {
-								fn: 'count',
-								args: [token]
-							};
-							break;
+						// ToDo: cases with multiple args.
+
 						default:
-							fnParams = {
-								fn: [tree.node.fn],
-								args: [token]
-							};
+							fnParams.args = [token];
 							break;
 					}
 
@@ -205,7 +204,6 @@ module.exports = class QueryLexer {
 
 					// Reset:
 					tree.node.resetFN();
-					tree.node.activeParam = PARAM_TOKENS.INCLUDES;
 					token = '';
 					value = [];
 					continue;
@@ -251,6 +249,13 @@ module.exports = class QueryLexer {
 					continue;
 				}
 
+				// If new function:
+				if (tree.node.activeParam === PARAM_TOKENS.FUNCTIONS) {
+					// Prepare for new function:
+					tree.node.resetFN();
+					continue;
+				}
+
 				// If param value:
 				if (tree.node.activeParam !== PARAM_TOKENS.INCLUDES) {
 					value.push(token);
@@ -354,7 +359,10 @@ module.exports = class QueryLexer {
 				}
 
 				// If end of key=value pair:
-				if (!!tree.node.activeParam && tree.node.activeParam !== PARAM_TOKENS.INCLUDES) {
+				if (!!tree.node.activeParam
+						&& tree.node.activeParam !== PARAM_TOKENS.FUNCTIONS
+						&& tree.node.activeParam !== PARAM_TOKENS.INCLUDES
+					) {
 					// Set value.
 					this.setNodeParam(tree.node, token, value);
 					// Reset:
@@ -363,6 +371,20 @@ module.exports = class QueryLexer {
 					value = [];
 					continue;
 				}
+				else if (tree.node.activeParam === PARAM_TOKENS.FUNCTIONS) {
+					// If token has some chars,
+					// then it's a syntactic error:
+					if (token.length > 0) {
+						const err = new NodesterQueryError(`unrecognized char at position ${ i }: Unknown token '${ token }'`);
+						throw err;
+					}
+
+					// Reset:
+					tree.node.resetActiveParam();
+					token = '';
+					value = [];
+					continue;
+				}
 				else if (tree.node.activeParam === PARAM_TOKENS.INCLUDES) {
 					// If token has some chars,
 					//	then it's include of a new model:
@@ -460,7 +482,7 @@ module.exports = class QueryLexer {
 				const param = this.parseParamFromToken(token);
 
 				if (isSubQuery === true && param === PARAM_TOKENS.INCLUDES) {
-					const err = new TypeError(`'include' is forbidden inside subquery (position ${ i }). Use: 'model.submodel' or 'model.submodel1+submodel2'.`);
+					const err = new NodesterQueryError(`'include' is forbidden inside subquery (position ${ i }). Use: 'model.submodel' or 'model.submodel1+submodel2'.`);
 					throw err;
 				}
 
@@ -482,6 +504,12 @@ module.exports = class QueryLexer {
 					throw err;
 				}
 
+				// If any Function:
+				if (!!tree.node.fn) {
+					const err = MissingCharError(i+1, ')');
+					throw err;
+				}
+
 				// If any OP at all:
 				if (!!tree.node.op) {
 					const err = MissingCharError(i+1, ')');
@@ -507,14 +535,22 @@ module.exports = class QueryLexer {
 			case 'a':
 				return PARAM_TOKENS.ATTRIBUTES;
 
+			case 'functions':
+			case 'fn':
+				return PARAM_TOKENS.FUNCTIONS;
+
+			case 'includes':
+			case 'in':
+				return PARAM_TOKENS.INCLUDES;
+
+			// Clauses:
+			case 'group_by':
+				return PARAM_TOKENS.GROUP_BY;
+
 			case 'limit':
 			case 'l':
 				return PARAM_TOKENS.LIMIT;
 
-			case 'skip':
-			case 's':
-				return PARAM_TOKENS.SKIP;
-
 			case 'order':
 			case 'o':
 				return PARAM_TOKENS.ORDER;
@@ -523,9 +559,10 @@ module.exports = class QueryLexer {
 			case 'oby':
 				return PARAM_TOKENS.ORDER_BY;
 
-			case 'includes':
-			case 'in':
-				return PARAM_TOKENS.INCLUDES;
+			case 'skip':
+			case 's':
+				return PARAM_TOKENS.SKIP;
+			// Clauses\
 
 			default:
 				return token;
@@ -543,6 +580,20 @@ module.exports = class QueryLexer {
 				treeNode.attributes = value;
 				break;
 
+			case PARAM_TOKENS.FUNCTIONS:
+				treeNode.addFunction(value);
+				break;
+
+			case PARAM_TOKENS.INCLUDES:
+				const node = new ModelsTreeNode(token);
+				treeNode.include(node);
+				break;
+
+			// Clauses:
+			case PARAM_TOKENS.GROUP_BY:
+				treeNode.group_by = token;
+				break;
+
 			case PARAM_TOKENS.LIMIT:
 				treeNode.limit = parseInt(token);
 				break;
@@ -558,11 +609,7 @@ module.exports = class QueryLexer {
 			case PARAM_TOKENS.ORDER_BY:
 				treeNode.order_by = token;
 				break;
-
-			case PARAM_TOKENS.INCLUDES:
-				const node = new ModelsTreeNode(token);
-				treeNode.include(node);
-				break;
+			// Clauses\
 
 			default:
 				if (token) value.push(token);
@@ -597,11 +644,11 @@ module.exports = class QueryLexer {
 
 
 function UnexpectedCharError(index, char) {
-	const err = new TypeError(`Unexpected ${ char } at position ${ index }`);
+	const err = new NodesterQueryError(`Unexpected '${ char }' at position ${ index }`);
 	return err;
 }
 
 function MissingCharError(index, char) {
-	const err = new TypeError(`Missing ${ char } at position ${ index }`);
+	const err = new NodesterQueryError(`Missing '${ char }' at position ${ index }`);
 	return err;
 }

package/lib/query/traverse/index.js

@@ -12,10 +12,14 @@ const httpCodes = require('nodester/http/codes');
 
 const { ensure } = require('nodester/validators/arguments');
 
+// Mappers & parsers:
+const mapCOUNT = require('./mappers/functions/count');
+
 const {
 	parseValue,
 	parseWhereEntry,
 } = require('./parsers');
+// Mappers & parsers\
 
 const {
 	disassembleQueryNode,
@@ -26,6 +30,8 @@ const {
 	getModelAssociationProps
 } = require('../../utils/modelAssociations.util');
 
+const consl = require('nodester/loggers/console');
+
 
 module.exports = traverse;
 
@@ -114,8 +120,13 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 		}
 	}
 	
-	//	At least 1 attribute is mandatory:
-	if (newQuery.attributes.length === 0) {
+	// At least 1 attribute is mandatory
+	// or "functions" must be set:
+	if (
+		functions.length === 0
+		&&
+		newQuery.attributes.length === 0
+	) {
 		const err = new NodesterQueryError(`No attributes were selected.`);
 		Error.captureStackTrace(err, traverse);
 		throw err;
@@ -124,57 +135,28 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 
 	// Functions:
 	for (const fnParams of functions) {
+		const fnName = fnParams.fn;
+
+		if (typeof filter.functions[fnName] === 'undefined') {
+			const err = new NodesterQueryError(`Function '${ fnName }' is not allowed.`);
+			Error.captureStackTrace(err, traverse);
+			throw err;
+		}
 
-		switch(fnParams.fn) {
+		switch(fnName) {
 			// SQL COUNT():
 			case 'count': {
-				const countParams = fnParams.args;
-
-				const [ countTarget ] = countParams;
-				// Count can be requested for this model,
-				// or for any of the available uncludes.
-				const isForRootModel = countTarget === rootModelName.plural.toLowerCase();
-
-				// Compile request:
-				//	Example of desired SQL:
-				//	`(SELECT COUNT(*) FROM comments WHERE comments.post_id=Post.id)`
-				//
-				let rawSQL = '(SELECT COUNT(*) FROM ';
-				let countAttribute = 'count';
-
-				// If request to count one of the includes:
-				if (!isForRootModel) {
-					// Check if it's available:
-					if (
-						!filter
-						||
-						!filter?.includes[countTarget]
-						||
-						rootModelAssociations[countTarget] === undefined
-					) {
-						const err = new NodesterQueryError(`Count for '${ countTarget }' is not available.`);
-						Error.captureStackTrace(err, traverse);
-						throw err;
-					}
-
-					const {
-						as,
-						target,
-						foreignKey,
-						sourceKey
-					} = rootModelAssociations[countTarget];
-					const { tableName } = target;
-
-					rawSQL += `${ tableName } where ${ tableName }.${ foreignKey }=${ rootModelName.singular }.${ sourceKey })`;
-					countAttribute = `${ as }_count`;
-				}
+				mapCOUNT(
+					fnParams,
+					_model,
+					filter?.includes,
 
-				newQuery.attributes.push(
-					[sequelize.literal(rawSQL), countAttribute]
+					newQuery
 				);
 			}
-			// Unknow function:
+			// Any other function:
 			default:
+				consl.warn(`function ${ fnName }() is not supported`);
 				break;
 		}
 	}
@@ -194,6 +176,22 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 		}
 
 		switch(clauseName) {
+			case 'group_by': {
+				// Check if this value is a valid attribute:
+				if (typeof value === 'undefined') {
+					continue;
+				}
+
+				if (typeof _model.tableAttributes[value] === 'undefined') {
+					const err = new NodesterQueryError(`group_by '${ value }' is not allowed.`);
+					Error.captureStackTrace(err, traverse);
+					throw err;
+				}
+
+				newQuery.group = value;
+				continue;
+			}
+
 			case 'limit': {
 				const _value = _setValueWithBounds(value, 'number', filter.bounds.clauses.limit);
 
@@ -241,6 +239,10 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 			const [ clauseName, staticClauseValue ] = entry;
 
 			switch(clauseName) {
+				case 'group_by':
+					newQuery.group = staticClauseValue;
+					continue;
+
 				case 'limit':
 					newQuery.limit = staticClauseValue;
 					continue;

package/lib/query/traverse/mappers/functions/count.js

@@ -0,0 +1,76 @@
+const { NodesterQueryError } = require('nodester/errors');
+
+
+module.exports = function mapCOUNT(
+	fnParams,
+	rootModel,
+	filterIncludes,
+
+	sequelizeQuery
+) {
+	try {
+
+		const { sequelize } = rootModel;
+		const rootModelName = rootModel.options.name;
+
+		const countParams = fnParams.args;
+		const [ countTarget ] = countParams;
+
+		// COUNT can be requested for this model,
+		// or for any of the available includes.
+		const associations = rootModel.associations;
+
+		const isForAssociation = typeof associations[countTarget] !== 'undefined';
+		const isForRootModel = countTarget === '';
+
+		// If request to count one of the includes:
+		if (isForAssociation) {
+			// Check if it's available:
+			if (!filterIncludes[countTarget]) {
+				const err = new NodesterQueryError(`Count for '${ countTarget }' is not available.`);
+				Error.captureStackTrace(err, mapCOUNT);
+				throw err;
+			}
+
+			// Unwrap desired association info:
+			const {
+				as,
+				target,
+				foreignKey,
+				sourceKey
+			} = associations[countTarget];
+			const { tableName } = target;
+
+			// Compile request:
+			//	Example of desired SQL:
+			//	`(SELECT COUNT(*) FROM comments WHERE comments.post_id=Post.id)`
+			const rawSQL = `(SELECT COUNT(*) FROM ${ tableName } where ${ tableName }.${ foreignKey }=${ rootModelName.singular }.${ sourceKey })`;
+			
+			const countAttributeName = `${ as }_count`;
+			sequelizeQuery.attributes.push(
+				[sequelize.literal(rawSQL), countAttributeName]
+			);
+		}
+
+		// If request to COUNT root model:
+		else if (isForRootModel) {
+			const firstAttribute = Object.keys(rootModel.tableAttributes)[0];
+
+			const countAttributeName = `${ rootModelName.plural.toLowerCase() }_count`;
+			sequelizeQuery.attributes.push(
+				[sequelize.fn('COUNT', firstAttribute), countAttributeName]
+			);
+		}
+
+		// Unknown attribute:
+		else {
+			const err = new NodesterQueryError(`Count for '${ countTarget }' is not available.`);
+			Error.captureStackTrace(err, mapCOUNT);
+			throw err;
+		}
+	}
+	catch(error) {
+		Error.captureStackTrace(error, mapCOUNT);
+		throw error;
+	}
+}

package/lib/structures/Filter.js

@@ -44,6 +44,8 @@ module.exports = class NodesterFilter {
 
 		this._attributes = [];
 		this._clauses = [];
+		this._functions = [];
+
 		this._includes = {};
 
 		this._bounds = {
@@ -74,21 +76,47 @@ module.exports = class NodesterFilter {
 		const {
 			attributes,
 			clauses,
+			functions,
 			includes,
 			bounds,
 			statics,
 		} = options;
 
 
-		// If attributes are array:
-		if (Array.isArray(attributes)) {
+		// Check attributes type:
+		if (!!attributes) {
+			if (!Array.isArray(attributes)) {
+				const err = new TypeError(`[NodesterFilter]: 'attributes' parameter must be an array.`);
+				throw err;
+			}
+
 			this._attributes = attributes;
 		}
 
-		if (Array.isArray(clauses)) {
+		// Check clauses type:
+		if (!!clauses) {
+			if (!Array.isArray(clauses)) {
+				const err = new TypeError(`[NodesterFilter]: 'clauses' parameter must be an array.`);
+				throw err;
+			}
+
 			this._clauses = clauses;
 		}
 
+		// If functions are set:
+		if (!!functions) {
+			if (
+				typeof functions !== 'object'
+				||
+				Array.isArray(functions)
+			) {
+				const err = new TypeError(`[NodesterFilter]: 'functions' parameter must be an object.`);
+				throw err;
+			}
+
+			this._functions = functions;
+		}
+
 		// Includes:
 		if (typeof includes === 'object') {
 			const { associations } = this.model;
@@ -152,6 +180,10 @@ module.exports = class NodesterFilter {
 		return this._clauses;
 	}
 
+	get functions() {
+		return this._functions;
+	}
+
 	get includes() {
 		return this._includes;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodester",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "A versatile REST framework for Node.js",
   "directories": {
     "docs": "docs",

package/tests/nql.test.js

@@ -575,4 +575,60 @@ describe('nodester Query Language', () => {
 			expect(result).toMatchObject(expected);
 		});
 	});
+
+
+	describe('functions', () => {
+		const queryStrings = {
+			count_long: '?functions=count(comments)',
+			count_short: '?fn=count(comments)',
+
+			count_and_includes: '?fn=count(comments)&in=comments',
+		}
+
+		test('Count (full key name)', () => {
+			const lexer = new QueryLexer( queryStrings.count_long );
+			const result = lexer.query;
+
+
+			const tree = new ModelsTree();
+			tree.node.addFunction({
+				fn: 'count',
+				args: ['comments']
+			})
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		test('Count (short key name)', () => {
+			const lexer = new QueryLexer( queryStrings.count_long );
+			const result = lexer.query;
+
+
+			const tree = new ModelsTree();
+			tree.node.addFunction({
+				fn: 'count',
+				args: ['comments']
+			})
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		test('Count and includes', () => {
+			const lexer = new QueryLexer( queryStrings.count_and_includes );
+			const result = lexer.query;
+
+
+			const tree = new ModelsTree();
+			tree.node.addFunction({
+				fn: 'count',
+				args: ['comments']
+			})
+			tree.include('comments');
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+	});
 });