nodester 0.2.3 → 0.2.5

package/Readme.md

@@ -3,9 +3,9 @@
 [![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** 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/Queries.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.
 
 
 ## Installation
@@ -49,11 +49,11 @@ app.listen(8080, function() {
 [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/Queries.md)
+[NQL documentaion ➡️](docs/nql/Introduction.md)
 
 
 ### Database

package/lib/factories/responses/rest.js

@@ -62,29 +62,27 @@ function _createGenericResponse(res, options) {
 
 			switch(error.name) {
 				case 'Unauthorized': {
-					statusCode = 401;
+					status = 401;
 					break;
 				}
 				case 'NotFound': {
-					statusCode = 404;
+					status = 404;
 					break;
 				}
 				case 'ValidationError': {
-					statusCode = 422;
+					status = 422;
 					break;
 				}
 				case 'ConflictError': {
-					statusCode = 409;
+					status = 409;
 					break;
 				}
 				case 'SequelizeUniqueConstraintError': {
-					statusCode = 409;
+					status = 409;
 					details.errors = error?.errors;
 					break;
 				}
 				default:
-					statusCode = status;
-
 					if (!!error?.errors) {
 						details.errors = error?.errors;
 					}
@@ -121,8 +119,7 @@ function _createGenericResponse(res, options) {
  * @api public
  */
 function _createOKResponse(res, options={}) {
-
-	return this.createGenericResponse(res, { 
+	return _createGenericResponse(res, { 
 		...options,
 		status: options?.status ?? 200,
 	});
@@ -143,8 +140,7 @@ function _createOKResponse(res, options={}) {
  * @api public
  */
 function _createErrorResponse(res, options) {
-
-	return this.createGenericResponse(res, {
+	return _createGenericResponse(res, {
 		...options,
 		status: options?.status ?? 500,
 	});

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

@@ -11,6 +11,15 @@ const { ModelsTree, ModelsTreeNode } = require('./ModelsTree');
 const util = require('util');
 const debug = require('debug')('nodester:interpreter:QueryLexer');
 
+const PARAM_TOKENS = new Enum({
+	FIELDS: Symbol('fields'),
+	INCLUDES: Symbol('includes'),
+	LIMIT: Symbol('limit'),
+	ORDER: Symbol('order'),
+	ORDER_BY: Symbol('order_by'),
+	SKIP: Symbol('skip'),
+});
+
 const OP_TOKENS = new Enum({
 	AND: 'and',
 	BETWEEN: 'between',
@@ -21,8 +30,14 @@ const OP_TOKENS = new Enum({
 	XOR: 'xor',
 	NOT: 'not',
 	NOT_MARK: '!',
+
+	IN: 'in',
 	NOT_IN: 'notIn',
+	
 	LIKE: 'like',
+	NOT_LIKE: 'notLike',
+	NOT_LIKE_SHORT: '!like',
+	
 	GREATER: 'gt',
 	GREATER_OR_EQUAL: 'gte',
 	LOWER: 'lt',
@@ -59,13 +74,12 @@ module.exports = class QueryLexer {
 
 	parseIsolatedQuery(queryString='', startAt=0, tree) {
 		const isSubQuery = tree.node.model !== 'root';
-		debug({ isSubQuery, startAt });
 
-		// Token is String, accumulated char-by-char.
+		// Token is a String, accumulated char-by-char.
 		let token = '';
 		// Value of param ('id=10' OR 'fields=id,text').
 		let value = [];
-		// Model, that was active before cursor went up in the tree.
+		// Model, that was active before a cursor went up in the tree.
 		let previousActive = null;
 
 		for (let i=startAt; i < queryString.length; i++) {
@@ -78,7 +92,7 @@ module.exports = class QueryLexer {
 
 				// If OP token:
 				if (OP_TOKENS.asArray.indexOf(token) > -1) {
-					// Set operation token.
+					// Set operator token.
 					tree.node.op = this.parseOP(token);
 					token = '';
 					continue;
@@ -127,6 +141,7 @@ module.exports = class QueryLexer {
 					switch (tree.node.op) {
 						case OP_TOKENS.NOT:
 						case OP_TOKENS.LIKE:
+						case OP_TOKENS.NOT_LIKE:
 						case OP_TOKENS.GREATER:
 						case OP_TOKENS.GREATER_OR_EQUAL:
 						case OP_TOKENS.LOWER:
@@ -143,7 +158,7 @@ module.exports = class QueryLexer {
 
 					// Reset:
 					tree.node.resetOP();
-					tree.node.activeParam = 'includes';
+					tree.node.activeParam = PARAM_TOKENS.INCLUDES;
 					token = '';
 					value = [];
 					continue;
@@ -177,41 +192,54 @@ module.exports = class QueryLexer {
 
 					// Reset:
 					tree.node.resetFN();
-					tree.node.activeParam = 'includes';
+					tree.node.activeParam = PARAM_TOKENS.INCLUDES;
 					token = '';
 					value = [];
 					continue;
 				}
 
 				// If end of subquery:
-				if (!!tree.node.activeParam && tree.node.activeParam !== 'includes') {
+				if (!!tree.node.activeParam && tree.node.activeParam !== PARAM_TOKENS.INCLUDES) {
 					// Set value.
 					this.setNodeParam(tree.node, token, value);
+					
 					// Reset:
 					tree.node.resetActiveParam();
 					tree.node.resetOP();
+
+					// Lift from subquery.
+					tree.up();
 				}
 				const numberOfProcessedChars = i - startAt;
 				return [ numberOfProcessedChars ];
 			}
 
 			// , can mean n-th value in value array,
-			// or it can be n-th key-value pair in subquery,
 			// or horizontal include:
 			if (char === ',') {
 				debug('char', char, { token, node: tree.node });
 
 				// If OP token:
 				if (!!tree.node.op) {
-					value.push({
-						[tree.node.activeParam]: [token]
-					});
+					switch(tree.node.op) {
+						case OP_TOKENS.NOT_IN:
+						case OP_TOKENS.IN:
+							value.push(token);
+							break;
+						default:
+							value.push({
+								[tree.node.activeParam]: [token]
+							});
+							break;
+					}
+
+					// Reset.
 					token = '';
 					continue;
 				}
 
 				// If param value:
-				if (tree.node.activeParam !== 'includes') {
+				if (tree.node.activeParam !== PARAM_TOKENS.INCLUDES) {
 					value.push(token);
 					token = '';
 					continue;
@@ -223,7 +251,7 @@ module.exports = class QueryLexer {
 				}
 
 				// Horizontal include:
-				if (tree.node.activeParam === 'includes') {
+				if (tree.node.activeParam === PARAM_TOKENS.INCLUDES) {
 					const model = token;
 					tree.use(model) ?? tree.include(model);
 
@@ -232,7 +260,7 @@ module.exports = class QueryLexer {
 					tree.node.resetActiveParam();
 					tree.upToRoot();
 
-					tree.node.activeParam = 'includes';
+					tree.node.activeParam = PARAM_TOKENS.INCLUDES;
 
 					token = '';
 					continue;
@@ -250,7 +278,7 @@ module.exports = class QueryLexer {
 				// Vertical include:
 				if (!!previousActive) {
 					tree.use(previousActive);
-					tree.node.activeParam = 'includes';
+					tree.node.activeParam = PARAM_TOKENS.INCLUDES;
 					token = '';
 					continue;
 				}
@@ -261,7 +289,7 @@ module.exports = class QueryLexer {
 					tree.use(model) ?? tree.include(model).use(model);
 
 					// Prepare for more includes:
-					tree.node.activeParam = 'includes';
+					tree.node.activeParam = PARAM_TOKENS.INCLUDES;
 
 					token = '';
 					continue;
@@ -283,7 +311,7 @@ module.exports = class QueryLexer {
 					tree.up();
 
 					// Prepare for more includes:
-					tree.node.activeParam = 'includes';
+					tree.node.activeParam = PARAM_TOKENS.INCLUDES;
 
 					token = '';
 					continue;
@@ -295,12 +323,12 @@ module.exports = class QueryLexer {
 				}
 
 				tree.up();
-				tree.node.activeParam = 'includes';
+				tree.node.activeParam = PARAM_TOKENS.INCLUDES;
 
 				continue;
 			}
 
-			// & can mean the end of key=value pair,
+			// & can mean the end of key=value pair in root and sub query,
 			// or the end of subincludes:
 			if (char === '&') {
 				debug('char', char, { token, node: tree.node });
@@ -312,7 +340,7 @@ module.exports = class QueryLexer {
 				}
 
 				// If end of key=value pair:
-				if (!!tree.node.activeParam && tree.node.activeParam !== 'includes') {
+				if (!!tree.node.activeParam && tree.node.activeParam !== PARAM_TOKENS.INCLUDES) {
 					// Set value.
 					this.setNodeParam(tree.node, token, value);
 					// Reset:
@@ -321,13 +349,19 @@ module.exports = class QueryLexer {
 					value = [];
 					continue;
 				}
-				else if (tree.node.activeParam === 'includes') {
-					// If include of new model:
+				else if (tree.node.activeParam === PARAM_TOKENS.INCLUDES) {
+					// If token has some chars,
+					//	then it's include of a new model:
 					if (token.length > 0) {
 						const model = token;
 						// Just include, no use.
 						tree.include(model);
 					}
+					// If token is empty,
+					//	it's most possibly a subquery
+					else {
+						continue;
+					}
 
 					// Then jump to root.
 					tree.upToRoot();
@@ -357,27 +391,51 @@ module.exports = class QueryLexer {
 				throw err;
 			}
 			
-			// [ can only mean start of 'in':
+			// [ can mean start of 'in'/'notIn',
+			// or 'notIn':
 			if (char === '[') {
-				tree.node.op = 'in';
+				tree.node.op = OP_TOKENS.IN;
+				if (token.length > 0) {
+					if (token === '!' || token === 'not') {
+						tree.node.op = OP_TOKENS.NOT_IN;
+					}
+					else {
+						const err = UnexpectedCharError(i - token.length, token);
+						throw err;
+					}
+				}
+
+				// Reset:
+				token = '';
 				continue;
 			}
 
-			// ] can only mean end if 'in':
+			// ] can mean end of 'in'/'notIn':
 			if (char === ']') {
 				// User missed first '[' :
-				if (tree.node.op !== 'in') {
+				if (
+					tree.node.op !== OP_TOKENS.IN
+					&&
+					tree.node.op !== OP_TOKENS.NOT_IN
+				) {
 					const err = UnexpectedCharError(i, char);
 					throw err;
 				}
 
+				// Token is the last element in this array:
+				if (token.length > 0) {
+					value.push(token);
+				}
+
 				tree.node.addWhere({
 					[tree.node.activeParam]: {
 						[tree.node.op]: value
 					}
 				});
+
 				// Reset:
 				tree.node.resetOP();
+				tree.node.resetActiveParam();
 				value = [];
 				token = '';
 				continue;
@@ -387,7 +445,7 @@ module.exports = class QueryLexer {
 			if (char === '=') {
 				const param = this.parseParamFromToken(token);
 
-				if (isSubQuery === true && param === 'includes') {
+				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'.`);
 					throw err;
 				}
@@ -433,23 +491,29 @@ module.exports = class QueryLexer {
 		switch(token) {
 			case 'limit':
 			case 'l':
-				return 'limit';
+				return PARAM_TOKENS.LIMIT;
+
 			case 'skip':
 			case 's':
 			case 'offset':
-				return 'skip';
+				return PARAM_TOKENS.SKIP;
+
 			case 'order':
 			case 'o':
-				return 'order';
+				return PARAM_TOKENS.ORDER;
+
 			case 'order_by':
 			case 'o_by':
-				return 'order_by';
+				return PARAM_TOKENS.ORDER_BY;
+
 			case 'fields':
 			case 'f':
-				return 'fields';
+				return PARAM_TOKENS.FIELDS;
+
 			case 'includes':
 			case 'in':
-				return 'includes';
+				return PARAM_TOKENS.INCLUDES;
+
 			default:
 				return token;
 		}
@@ -458,30 +522,35 @@ module.exports = class QueryLexer {
 	setNodeParam(treeNode, token, value) {
 		const param = treeNode.activeParam;
 
-		debug(`set param ${ param }`, { token, value });
+		debug(`set param`, { param, token, value });
 
 		switch(param) {
-			case 'limit':
+			case PARAM_TOKENS.LIMIT:
 				treeNode.limit = parseInt(token);
 				break;
-			case 'skip':
-			case 'offset':
+
+			case PARAM_TOKENS.SKIP:
 				treeNode.skip = parseInt(token);
 				break;
-			case 'order':
+
+			case PARAM_TOKENS.ORDER:
 				treeNode.order = token;
 				break;
-			case 'order_by':
+
+			case PARAM_TOKENS.ORDER_BY:
 				treeNode.order_by = token;
 				break;
-			case 'fields':
+
+			case PARAM_TOKENS.FIELDS:
 				if (token) value.push(token);
 				treeNode.fields = value;
 				break;
-			case 'includes':
+
+			case PARAM_TOKENS.INCLUDES:
 				const node = new ModelsTreeNode(token);
 				treeNode.include(node);
 				break;
+
 			default:
 				if (token) value.push(token);
 				treeNode.addWhere({ [param]: value });
@@ -493,10 +562,16 @@ module.exports = class QueryLexer {
 		switch(opToken) {
 			case '|':
 			case 'or':
-				return 'or';
+				return OP_TOKENS.OR;
+
+			case '!like':
+			case 'notLike':
+				return OP_TOKENS.NOT_LIKE;
+
 			case 'not':
 			case '!':
-				return 'not';
+				return OP_TOKENS.NOT;
+
 			default:
 				return opToken;
 		}

package/lib/query/traverse.js

@@ -102,49 +102,57 @@ function traverse(queryNode, filter=null, model=null) {
 	// Functions:
 	for (const fnParams of functions) {
 
-		// If COUNT() is requested:
-		if (fnParams.fn === '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:
-			// `(SELECT COUNT(*) FROM comments WHERE comments.morph_id=Morph.id)`
-
-			// Params for attribute:
-			let rawSQL = '(SELECT COUNT(*) FROM ';
-			let countAttribute = '_count';
-
-			// If request to count one of the includes:
-			if (!isForRootModel) {
-				// Check if it's available:
-				if (
+		switch(fnParams.fn) {
+			// 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 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`;
 				}
 
-				const {
-					foreignKey,
-					sourceKey
-				} = rootModelAssociations[countTarget];
-				rawSQL += `${ countTarget } where ${ countTarget }.${ foreignKey }=${ rootModelName.singular }.${ sourceKey })`;
-				countAttribute = `${ countTarget }_count`;
+				newQuery.attributes.push(
+					[sequelize.literal(rawSQL), countAttribute]
+				);
 			}
-
-			newQuery.attributes.push(
-				[sequelize.literal(rawSQL), countAttribute]
-			);
+			// Unknow function:
+			default:
+				break;
 		}
 	}
 	// Functions\
@@ -194,7 +202,7 @@ function traverse(queryNode, filter=null, model=null) {
 		}
 	}
 
-	//	"statics" override or set any query in clauses:
+	//	Override clauses with "statics":
 	if (filter !== null) {
 		const staticClausesEntries = Object.entries(filter.statics.clauses);
 
@@ -228,7 +236,11 @@ function traverse(queryNode, filter=null, model=null) {
 
 
 	// Order:
-	if ( ['rand', 'random'].indexOf(order.order) > -1) {
+	if (
+		order.order === 'rand'
+		||
+		order.order === 'random'
+	) {
 		newQuery.order = sequelize.random();
 	}
 	else {
@@ -292,11 +304,21 @@ function traverse(queryNode, filter=null, model=null) {
 }
 
 
-function _traverseIncludes(includes, model, filter, resultQuery) {
+/**
+ * Traverses each include in the array.
+ *
+ * @param {Array} includes
+ * @param {Model} rootModel
+ * @param {NodesterFilter} filter
+ * @param {Object} resultQuery
+ *
+ * @api private
+ */
+function _traverseIncludes(includes, rootModel, filter, resultQuery) {
 	const filterIncludesEntries = Object.entries(filter.includes);
 	for (let [ includeName, includeFilter ] of filterIncludesEntries) {
 
-		const association = model.associations[includeName];
+		const association = rootModel.associations[includeName];
 
 		// If no such association:
 		if (!association) {
@@ -375,17 +397,10 @@ function _disassembleQueryNode(queryNode) {
 function _parseValue(value, attribute) {
 	// If value is Object:
 	if (typeof value === 'object' && Array.isArray(value) === false) {
-		const [opKey, rawValue] = (Object.entries(value))[0];
+		const [ opKey, rawValue ] = (Object.entries(value))[0];
 
-		// If operation is "in":
-		if (opKey === 'in') {
-			// Unwrap rawValue.
-			return rawValue[0][attribute];
-		}
-		else {
-			const op = Op[opKey];
-			return { [op]: rawValue };
-		}
+		const op = Op[opKey];
+		return { [op]: rawValue };
 	}
 
 	return value;