nodester 0.6.71 → 0.6.72

package/Readme.md

@@ -12,7 +12,24 @@
 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.
+That's why **nodester** was not developed 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.
+
+## Quick Example
+
+With NQL, a single endpoint can handle complex queries:
+
+```http
+GET /api/v1/countries?includes=cities(limit=5&order_by=population&order=desc).areas&name=like(Bel)&fn=count(cities)
+```
+
+This query:
+- Filters countries by name containing "Bel"
+- Includes cities (limited to 5, ordered by population)
+- Includes areas for each city
+- Counts total cities per country
+
+All with proper security through [Filters →](docs/Filter.md) that control what users can query.
+
 Check out [core concepts documentation →](docs/CoreConcepts.md) for more info.
 
 
@@ -25,8 +42,34 @@ npm install -S nodester
 ```
 
 
+## Or kickstart your project with the boilerplate
+
+```shell
+npx degit https://github.com/MarkKhramko/nodester/examples/boilerplate my-app
+
+cd my-app
+
+npm i
+
+npm run bootstrap
+```
+
+## Features
+
+- **🔍 Powerful Query Language (NQL)**: Extend REST with SQL-like querying capabilities
+- **🔒 Security First**: Fine-grained control over what users can query through Filters
+- **🌳 Hierarchical Associations**: Query nested relationships with ease
+- **⚡ Built on Sequelize**: Leverage the power of Sequelize ORM
+- **🎯 Flexible Architecture**: Controller → Facade → Model pattern for clean separation
+- **🛡️ Request Validation**: Automatic validation and bounds checking
+- **📊 Aggregate Functions**: Built-in support for count, avg, and more
+- **🔧 Extensible**: Easy to extend and customize for your needs
+
 ## Table of Contents
 
+- [Quick Example](#quick-example)
+- [Features](#features)
+- [Installation](#installation)
 - [Usage](#usage)
 - [Documentation](#documentation)
 - [Philosophy](#philosophy)
@@ -81,8 +124,13 @@ process.once('SIGTERM', () => {
 ### 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 powerful tool for expressive and efficient data querying.
 
-Read more about it in the documentation:
-[NQL documentaion →](docs/nql/Introduction.md)
+**NQL Documentation:**
+- [Introduction →](docs/nql/Introduction.md) - Get started with NQL
+- [Syntax →](docs/nql/Syntax.md) - Understand query syntax and parsing
+- [Parameters →](docs/nql/Parameters.md) - Complete parameter reference
+- [Subqueries →](docs/nql/Subqueries.md) - Advanced nested queries
+- [Operators →](docs/nql/Operators.md) - Filtering operators (like, in, gt, etc.)
+- [Functions →](docs/nql/Functions.md) - Aggregate functions (count, avg)
 
 
 ### Database
@@ -109,7 +157,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, while laying the foundation for seamless scalability in the future.
+The goal of `nodester` is to be a robust and flexible framework that makes development in iterations easy, while laying the foundation for seamless scalability in the future.
 
 
 ## License

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

@@ -33,9 +33,13 @@ const PARAM_TOKENS = new Enum({
 const OP_TOKENS = new Enum({
 	AND: 'and',
 
+	// NOTE: BETWEEN tokens are defined but not implemented.
+	// They are reserved for future use.
 	BETWEEN: 'between',
+	BETWEEN_SHORT: '~',
 	NOT_BETWEEN: 'notBetween',
-	BETWEEN_MARK: '~',
+	NOT_BETWEEN_SHORT: '!~',
+	// NOTE\
 
 	OR: 'or',
 	OR_SHORT: '|',
@@ -46,11 +50,11 @@ const OP_TOKENS = new Enum({
 
 	IN: 'in',
 	NOT_IN: 'notIn',
-	
+
 	LIKE: 'like',
 	NOT_LIKE: 'notLike',
 	NOT_LIKE_SHORT: '!like',
-	
+
 	GREATER: 'gt',
 	GREATER_OR_EQUAL: 'gte',
 	LOWER: 'lt',
@@ -72,12 +76,12 @@ const FN_TOKENS = new Enum({
  * @access public
  */
 module.exports = class QueryLexer {
-	constructor(queryString='') {
+	constructor(queryString = '') {
 		this.tree = new ModelsTree();
 		this.queryString = queryString;
 	}
 
-	async parse(queryString=this.queryString, tree=this.tree) {
+	async parse(queryString = this.queryString, tree = this.tree) {
 		if (typeof queryString !== 'string') {
 			const err = new TypeError(`Invalid 'queryString'.`);
 			return Promise.reject(err);
@@ -91,7 +95,7 @@ module.exports = class QueryLexer {
 		return Promise.resolve(this.tree.root.toObject());
 	}
 
-	async parseIsolatedQuery(queryString='', startAt=0, tree) {
+	async parseIsolatedQuery(queryString = '', startAt = 0, tree) {
 		const isSubQuery = tree.node.model !== 'root';
 
 		// Token is a String, accumulated char-by-char.
@@ -101,7 +105,7 @@ module.exports = class QueryLexer {
 		// Model, that was active before a cursor went up in the tree.
 		let previousActive = null;
 
-		for (let i=startAt; i < queryString.length; i++) {
+		for (let i = startAt; i < queryString.length; i++) {
 			const char = queryString[i];
 
 			// ( can mean:
@@ -118,7 +122,7 @@ module.exports = class QueryLexer {
 					token = '';
 					continue;
 				}
-				
+
 				// If FN token:
 				if (FN_TOKENS.asArray.indexOf(token) > -1) {
 					// Set function token.
@@ -134,7 +138,7 @@ module.exports = class QueryLexer {
 
 				// Process subquery:
 				i++;
-				const [ charsCount ] = await this.parseIsolatedQuery(queryString, i, tree);
+				const [charsCount] = await this.parseIsolatedQuery(queryString, i, tree);
 				i += charsCount;
 
 				previousActive = model;
@@ -234,7 +238,7 @@ module.exports = class QueryLexer {
 					if (token.length > 0) {
 						this.setNodeParam(tree.node, token, value);
 					}
-					
+
 					// Reset:
 					tree.node.resetActiveParam();
 					tree.node.resetOP();
@@ -243,7 +247,7 @@ module.exports = class QueryLexer {
 					tree.up();
 				}
 				const numberOfProcessedChars = i - startAt;
-				return [ numberOfProcessedChars ];
+				return [numberOfProcessedChars];
 			}
 
 			// , can mean:
@@ -379,15 +383,15 @@ module.exports = class QueryLexer {
 
 				// If any OP at all:
 				if (!!tree.node.op) {
-					const err = MissingCharError(i+1, ')');
+					const err = MissingCharError(i + 1, ')');
 					return Promise.reject(err);
 				}
 
 				// If end of a key=value pair:
 				if (!!tree.node.activeParam
-						&& tree.node.activeParam !== PARAM_TOKENS.FUNCTIONS
-						&& tree.node.activeParam !== PARAM_TOKENS.INCLUDES
-					) {
+					&& tree.node.activeParam !== PARAM_TOKENS.FUNCTIONS
+					&& tree.node.activeParam !== PARAM_TOKENS.INCLUDES
+				) {
 					if (token.length > 0) {
 						// Set value.
 						this.setNodeParam(tree.node, token, value);
@@ -403,7 +407,7 @@ module.exports = class QueryLexer {
 					// 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 }'`);
+						const err = new NodesterQueryError(`unrecognized char at position ${i}: Unknown token '${token}'`);
 						return Promise.reject(err);
 					}
 
@@ -433,7 +437,7 @@ module.exports = class QueryLexer {
 					// Reset:
 					token = '';
 					value = [];
-					continue;	
+					continue;
 				}
 
 				// If end of subquery:
@@ -454,7 +458,7 @@ module.exports = class QueryLexer {
 				const err = UnexpectedCharError(i, char);
 				return Promise.reject(err);
 			}
-			
+
 			// [ can mean:
 			// • start of 'in' / 'notIn'
 			if (char === '[') {
@@ -505,13 +509,13 @@ module.exports = class QueryLexer {
 				token = '';
 				continue;
 			}
-			
+
 			// = can only mean the end of a param name:
 			if (char === '=') {
 				const param = this.parseParamFromToken(token);
 
 				if (isSubQuery === true && param === PARAM_TOKENS.INCLUDES) {
-					const err = new NodesterQueryError(`'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'.`);
 					return Promise.reject(err);
 				}
 
@@ -522,45 +526,45 @@ module.exports = class QueryLexer {
 
 			// Continue accumulating token.
 			token += char;
-			
+
 			// If last char:
-			if (i === queryString.length-1) {
+			if (i === queryString.length - 1) {
 				debug('last char', { token, node: tree.node });
-				
+
 				// haven't up from 'in':
 				if (tree.node.op === 'in') {
-					const err = MissingCharError(i+1, ']');
+					const err = MissingCharError(i + 1, ']');
 					return Promise.reject(err);
 				}
 
 				// If any Function:
 				if (!!tree.node.fn) {
-					const err = MissingCharError(i+1, ')');
+					const err = MissingCharError(i + 1, ')');
 					return Promise.reject(err);
 				}
 
 				// If any OP at all:
 				if (!!tree.node.op) {
-					const err = MissingCharError(i+1, ')');
+					const err = MissingCharError(i + 1, ')');
 					return Promise.reject(err);
 				}
-				
+
 				this.setNodeParam(tree.node, token, value);
 
 				// If end of subquery:
 				if (isSubQuery === true) {
-					const numberOfProcessedChars = i+1 - startAt;
-					return [ numberOfProcessedChars ];
+					const numberOfProcessedChars = i + 1 - startAt;
+					return [numberOfProcessedChars];
 				}
 			}
 		}
 
 		// Must return it's portion of chars.
-		return Promise.resolve([ queryString.length - startAt ]);
+		return Promise.resolve([queryString.length - startAt]);
 	}
 
 	parseParamFromToken(token) {
-		switch(token) {
+		switch (token) {
 			case 'attributes':
 			case 'a':
 				return PARAM_TOKENS.ATTRIBUTES;
@@ -570,6 +574,7 @@ module.exports = class QueryLexer {
 				return PARAM_TOKENS.FUNCTIONS;
 
 			case 'includes':
+			case 'include':
 			case 'in':
 				return PARAM_TOKENS.INCLUDES;
 
@@ -604,7 +609,7 @@ module.exports = class QueryLexer {
 
 		debug(`set param`, { param, token, value });
 
-		switch(param) {
+		switch (param) {
 			case PARAM_TOKENS.ATTRIBUTES:
 				if (token) value.push(token);
 				treeNode.attributes = value;
@@ -649,7 +654,7 @@ module.exports = class QueryLexer {
 	}
 
 	parseOP(opToken) {
-		switch(opToken) {
+		switch (opToken) {
 			case '|':
 			case 'or':
 				return OP_TOKENS.OR;
@@ -674,11 +679,11 @@ module.exports = class QueryLexer {
 
 
 function UnexpectedCharError(index, char) {
-	const err = new NodesterQueryError(`Unexpected '${ char }' at position ${ index }`);
+	const err = new NodesterQueryError(`Unexpected '${char}' at position ${index}`);
 	return err;
 }
 
 function MissingCharError(index, char) {
-	const err = new NodesterQueryError(`Missing '${ char }' at position ${ index }`);
+	const err = new NodesterQueryError(`Missing '${char}' at position ${index}`);
 	return err;
 }

package/package.json

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