nodester 0.5.0 → 0.6.0

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/body/extract.js

@@ -30,13 +30,14 @@ function extract(body, filter=null, model) {
 
 	const bodyEntries = Object.entries(body);
 
+	// Unwrap statics:
 	const { statics } = filter;
-
+	const staticAttributes = statics?.attributes ?? {};
 
 	// Result object.
 	const filteredBody = {};
 
-	for (const [key, value] of bodyEntries) {
+	for (const [ key, value ] of bodyEntries) {
 		const isInclude = availableIncludes.indexOf(key) > -1;
 		const isAttribute = modelAttributes.indexOf(key) > -1;
 
@@ -47,6 +48,14 @@ function extract(body, filter=null, model) {
 		}
 
 		if (isAttribute) {
+			// If this attribute must have a static value,
+			// skip it.
+			// The static value will be set later:
+			if (typeof staticAttributes[key] !== 'undefined') {
+				continue;
+			}
+
+			// Sanitize value from the body:
 			const column = model.rawAttributes[key];
 			const typeName = column.type.constructor.name;
 			// Optional validation.
@@ -99,6 +108,12 @@ function extract(body, filter=null, model) {
 		err.status = httpCodes.NOT_ACCEPTABLE;
 		throw err;
 	}
+
+	// Set all static attributes:
+	const staticAttributeEntries = Object.entries(staticAttributes);
+	for (const [ key, value ] of staticAttributeEntries) {
+		filteredBody[key] = staticAttributes[key];
+	}
 	
 	return filteredBody;
 }

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

@@ -0,0 +1,9 @@
+
+class NodesterQueryError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = 'NodesterQueryError';
+	}
+}
+
+module.exports = NodesterQueryError;

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

@@ -8,18 +8,25 @@
 const Enum = require('nodester/enum');
 
 const { ModelsTree, ModelsTreeNode } = require('./ModelsTree');
+
+const NodesterQueryError = require('./NodesterQueryError');
+
 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:
 	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 +57,7 @@ const OP_TOKENS = new Enum({
 });
 
 const FN_TOKENS = new Enum({
+	AVG: 'avg',
 	COUNT: 'count',
 });
 
@@ -185,19 +193,14 @@ module.exports = class QueryLexer {
 						throw err;
 					}
 
-					let fnParams = {};
+					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 +208,6 @@ module.exports = class QueryLexer {
 
 					// Reset:
 					tree.node.resetFN();
-					tree.node.activeParam = PARAM_TOKENS.INCLUDES;
 					token = '';
 					value = [];
 					continue;
@@ -251,6 +253,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 +363,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 +375,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 +486,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 +508,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 +539,18 @@ 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;
+
 			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,9 @@ 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;
 
 			default:
 				return token;
@@ -543,6 +579,16 @@ 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.LIMIT:
 				treeNode.limit = parseInt(token);
 				break;
@@ -558,11 +604,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 +639,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

@@ -64,7 +64,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 		where: {},
 		include: []
 	};
-	
+
 	const {
 		attributes,
 		clauses,
@@ -184,18 +184,19 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 	const order = {};
 
 	const clausesEntries = Object.entries(clauses);
-	for (let [clauseName, value] of clausesEntries) {
+	for (const [ clauseName, value ] of clausesEntries) {
 
 		// If clause is not available:
 		if (filter != null) {
-			if (filter.clauses.indexOf(clauseName) === -1)
+			if (filter.clauses.indexOf(clauseName) === -1) {
 				continue;
+			}
 		}
 
 		switch(clauseName) {
 			case 'limit': {
 				const _value = _setValueWithBounds(value, 'number', filter.bounds.clauses.limit);
-				
+
 				// Do not set if -1:
 				if (_value === -1) 
 					continue;
@@ -226,7 +227,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 
 				order.by = value;
 				continue;
-				
+
 			default:
 				continue;
 		}
@@ -243,7 +244,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 				case 'limit':
 					newQuery.limit = staticClauseValue;
 					continue;
-				
+
 				case 'skip':
 					newQuery.offset = staticClauseValue;
 					continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodester",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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);
+		});
+	});
 });