nodester 0.2.5 → 0.2.6

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 which set of technologies enabling you to fully customize the request-response flow down to the specific user to only give them access to the data you intended.
+Check out [core concepts documentation ➡️](docs/CoreConcepts.md) for more info.
 
 
 ## Installation

package/lib/body/extract.js

@@ -25,7 +25,7 @@ module.exports = extract;
 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/middlewares/ql/sequelize/interpreter/ModelsTree.js

@@ -17,7 +17,7 @@ class ModelsTreeNode {
 		this.fn = null;
 
 		// for override:
-		this.fields = [];
+		this._attributes = [];
 		this._where = {};
 		this._functions = [];
 		this.skip = 0;
@@ -28,6 +28,11 @@ class ModelsTreeNode {
 		this.order_by = opts.order_by ?? 'id';
 	}
 
+	// Getters:
+	get attributes() {
+		return this._attributes;
+	}
+
 	get where() {
 		return this._where;
 	}
@@ -51,6 +56,12 @@ class ModelsTreeNode {
 	get hasIncludes() {
 		return this.includesCount > 0;
 	}
+	// Getters\
+
+	// Setters:
+	set attributes(array) {
+		this._attributes = array;
+	}
 
 	resetActiveParam() {
 		this.activeParam = null;
@@ -85,7 +96,7 @@ class ModelsTreeNode {
 		return {
 			model: this.model,
 
-			fields: this.fields,
+			attributes: this.attributes,
 			functions: this.functions,
 
 			where: this.where,

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

@@ -12,24 +12,29 @@ const util = require('util');
 const debug = require('debug')('nodester:interpreter:QueryLexer');
 
 const PARAM_TOKENS = new Enum({
-	FIELDS: Symbol('fields'),
-	INCLUDES: Symbol('includes'),
+	ATTRIBUTES: Symbol('attributes'),
+	
 	LIMIT: Symbol('limit'),
 	ORDER: Symbol('order'),
 	ORDER_BY: Symbol('order_by'),
 	SKIP: Symbol('skip'),
+
+	INCLUDES: Symbol('includes'),
 });
 
 const OP_TOKENS = new Enum({
 	AND: 'and',
+
 	BETWEEN: 'between',
 	NOT_BETWEEN: 'notBetween',
 	BETWEEN_MARK: '~',
+
 	OR: 'or',
-	OR_MARK: '|',
+	OR_SHORT: '|',
 	XOR: 'xor',
+
 	NOT: 'not',
-	NOT_MARK: '!',
+	NOT_SHORT: '!',
 
 	IN: 'in',
 	NOT_IN: 'notIn',
@@ -77,7 +82,7 @@ module.exports = class QueryLexer {
 
 		// Token is a String, accumulated char-by-char.
 		let token = '';
-		// Value of param ('id=10' OR 'fields=id,text').
+		// Value of param ('id=10' OR 'attributes=id,text').
 		let value = [];
 		// Model, that was active before a cursor went up in the tree.
 		let previousActive = null;
@@ -489,13 +494,16 @@ module.exports = class QueryLexer {
 
 	parseParamFromToken(token) {
 		switch(token) {
+			case 'attributes':
+			case 'a':
+				return PARAM_TOKENS.ATTRIBUTES;
+
 			case 'limit':
 			case 'l':
 				return PARAM_TOKENS.LIMIT;
 
 			case 'skip':
 			case 's':
-			case 'offset':
 				return PARAM_TOKENS.SKIP;
 
 			case 'order':
@@ -503,13 +511,9 @@ module.exports = class QueryLexer {
 				return PARAM_TOKENS.ORDER;
 
 			case 'order_by':
-			case 'o_by':
+			case 'oby':
 				return PARAM_TOKENS.ORDER_BY;
 
-			case 'fields':
-			case 'f':
-				return PARAM_TOKENS.FIELDS;
-
 			case 'includes':
 			case 'in':
 				return PARAM_TOKENS.INCLUDES;
@@ -525,6 +529,11 @@ module.exports = class QueryLexer {
 		debug(`set param`, { param, token, value });
 
 		switch(param) {
+			case PARAM_TOKENS.ATTRIBUTES:
+				if (token) value.push(token);
+				treeNode.attributes = value;
+				break;
+
 			case PARAM_TOKENS.LIMIT:
 				treeNode.limit = parseInt(token);
 				break;
@@ -541,11 +550,6 @@ module.exports = class QueryLexer {
 				treeNode.order_by = token;
 				break;
 
-			case PARAM_TOKENS.FIELDS:
-				if (token) value.push(token);
-				treeNode.fields = value;
-				break;
-
 			case PARAM_TOKENS.INCLUDES:
 				const node = new ModelsTreeNode(token);
 				treeNode.include(node);

package/lib/query/traverse.js

@@ -35,7 +35,7 @@ function traverse(queryNode, filter=null, model=null) {
 	const rootModelName = _model.options.name;
 	const rootModelAssociations = _model.associations;
 	const { sequelize } = _model;
-	const fieldsAvailable = Object.keys(_model.tableAttributes);
+	const attributesAvailable = Object.keys(_model.tableAttributes);
 
 	const newQuery = {
 		attributes: [],
@@ -44,60 +44,61 @@ function traverse(queryNode, filter=null, model=null) {
 	};
 	
 	const {
+		attributes,
+		clauses,
+		functions,
 		where,
+
 		includes,
-		fields,
-		functions,
-		clauses,
 	} = _disassembleQueryNode(queryNode);
 
 
-	// Fields:
+	// Attribute:
 	//
 	//	If Filter is not set,
-	//	use every available field:
+	//	use every available attribute:
 	if (filter === null) {
-		for (let field of fieldsAvailable) {
-			// If no query filter or field is requested:
-			if (fields.length === 0 || fields.indexOf(field) > -1) {
-				newQuery.attributes.push(field);
+		for (let attribute of attributesAvailable) {
+			// If no query filter or attribute is requested:
+			if (attributes.length === 0 || attributes.indexOf(attribute) > -1) {
+				newQuery.attributes.push(attribute);
 				continue;
 			}
 		}
 	}
 	//	Filter is present:
 	else {
-		// If no query fields were set,
+		// If no query attributes were set,
 		//	use the ones from Filter,
-		// If query fields were set,
+		// If query attributes were set,
 		//	put them through Filter:
-		for (let field of filter.fields) {
-			if (fieldsAvailable.indexOf(field) === -1) {
-				const err = new NodesterQueryError(`Field '${ field }' is not present in model.`);
+		for (let attribute of filter.attributes) {
+			if (attributesAvailable.indexOf(attribute) === -1) {
+				const err = new NodesterQueryError(`Field '${ attribute }' is not present in model.`);
 				Error.captureStackTrace(err, traverse);
 				throw err;
 			}
 
-			// If field is not in available set:
-			// if (filter.fields.indexOf(field) === -1) {
+			// If attribute is not in available set:
+			// if (filter.attributes.indexOf(attribute) === -1) {
 			// 	continue;
 			// }
 
-			// If no query filter or field is requested:
-			if (fields.length === 0 || fields.indexOf(field) > -1) {
-				newQuery.attributes.push(field);
+			// If no query filter or attribute is requested:
+			if (attributes.length === 0 || attributes.indexOf(attribute) > -1) {
+				newQuery.attributes.push(attribute);
 				continue;
 			}
 		}
 	}
 	
-	//	At least 1 field is mandatory:
+	//	At least 1 attribute is mandatory:
 	if (newQuery.attributes.length === 0) {
-		const err = new NodesterQueryError(`No fields were selected.`);
+		const err = new NodesterQueryError(`No attributes were selected.`);
 		Error.captureStackTrace(err, traverse);
 		throw err;
 	}
-	// Fields\
+	// Attribute\
 
 	// Functions:
 	for (const fnParams of functions) {
@@ -377,20 +378,19 @@ function _parseWhereEntry(attribute, value, whereHolder, staticAttributes) {
 function _disassembleQueryNode(queryNode) {
 	// Disassemble current query node:
 	const {
+		attributes,
+		functions,
 		where,
 		includes,
-		fields,
-		functions,
 		...clauses
 	} = queryNode;
-	// delete queryNode.model;
 
 	return {
+		attributes: attributes ?? [],
+		clauses: clauses ?? [],
+		functions: functions ?? [],
 		where: where ?? {},
 		includes: includes ?? [],
-		fields: fields ?? [],
-		functions: functions ?? [],
-		clauses: clauses ?? []
 	};
 }
 

package/lib/structures/Filter.js

@@ -18,12 +18,12 @@ module.exports = class NodesterFilter {
 	 *
 	 * @param {Model} model
 	 * @param {Object} options
-	 * @param {Array}  options.fields
+	 * @param {Array}  options.attributes
 	 * @param {Array}  options.clauses
 	 * @param {Object} options.includes
 	 *
 	 * @param {Object} options.bounds
-	 * @param {Object} options.bounds.fields
+	 * @param {Object} options.bounds.attributes
 	 * @param {Object} options.bounds.clauses
 	 *
 	 * @param {Object} options.statics
@@ -37,12 +37,12 @@ module.exports = class NodesterFilter {
 		
 		this._model = model;
 
-		this._fields = [];
+		this._attributes = [];
 		this._clauses = [];
 		this._includes = {};
 
 		this._bounds = {
-			fields: {},
+			attributes: {},
 			clauses: {}
 		}
 		
@@ -53,7 +53,7 @@ module.exports = class NodesterFilter {
 
 		// If model is present:
 		if (isModel(this.model)) {
-			this._fields = Object.keys(this.model.tableAttributes);
+			this._attributes = Object.keys(this.model.tableAttributes);
 			this._clauses = CLAUSES.asArray;
 
 			// ...and no 'bounds' and 'statics' are provided,
@@ -67,7 +67,7 @@ module.exports = class NodesterFilter {
 		}
 		
 		const {
-			fields,
+			attributes,
 			clauses,
 			includes,
 			bounds,
@@ -75,9 +75,9 @@ module.exports = class NodesterFilter {
 		} = options;
 
 
-		// If fields are array:
-		if (Array.isArray(fields)) {
-			this._fields = fields;
+		// If attributes are array:
+		if (Array.isArray(attributes)) {
+			this._attributes = attributes;
 		}
 
 		if (Array.isArray(clauses)) {
@@ -124,8 +124,8 @@ module.exports = class NodesterFilter {
 	}
 
 	// Getters:
-	get fields() {
-		return this._fields;
+	get attributes() {
+		return this._attributes;
 	}
 
 	get clauses() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodester",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "A versatile REST framework for Node.js",
   "exports": {
     ".": "./lib/application/index.js",

package/tests/nql.test.js

@@ -17,8 +17,10 @@ describe('nodester Query Language', () => {
 		const queryStrings = [
 			// Simple where.
 			'id=10',
+			// Only certain attributes.
+			'a=id,text',
 			// All possible params.
-			'id=10&position=4&limit=3&skip=10&order=desc&order_by=index&fields=id,content,position,created_at',
+			'id=10&position=4&limit=3&skip=10&order=desc&order_by=index&a=id,content,position,created_at',
 		];
 
 		it('Simple where', () => {
@@ -32,14 +34,25 @@ describe('nodester Query Language', () => {
 			expect(result).toMatchObject(expected);
 		});
 
-		test('All possible params', () => {
+		it('Only certain attributes', () => {
 			const lexer = new QueryLexer( queryStrings[1] );
 			const result = lexer.query;
 
+			const tree = new ModelsTree();
+			tree.node.attributes = [ 'id', 'text' ];
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		test('All possible params', () => {
+			const lexer = new QueryLexer( queryStrings[2] );
+			const result = lexer.query;
+
 
 			const tree = new ModelsTree();
 			tree.node.addWhere({ id: ['10'], position: ['4'] });
-			tree.node.fields = [ 'id', 'content', 'position', 'created_at' ];
+			tree.node.attributes = [ 'id', 'content', 'position', 'created_at' ];
 			tree.node.limit = 3;
 			tree.node.skip = 10;
 			tree.node.order = 'desc';
@@ -55,7 +68,7 @@ describe('nodester Query Language', () => {
 			// Simple includes.
 			'includes=comments&id=7',
 			// Include with All possible params.
-			'includes=comments(id=10&position=4&limit=3&skip=10&order=desc&order_by=index&fields=id,content,position)',
+			'includes=comments(id=10&position=4&limit=3&skip=10&order=desc&order_by=index&a=id,content,position)',
 
 			// 2 horizontals
 			'includes=comments,users&id=1000',
@@ -66,7 +79,7 @@ describe('nodester Query Language', () => {
 			'in=reactions,comments(user_id=gte(4)&skip=10&limit=2).users,likes,reposts',
 
 			// Separated includes.
-			'includes=comments(order=rand)&id=7&limit=3&includes=users(fields=id,content)',
+			'includes=comments(order=rand)&id=7&limit=3&includes=users(a=id,content)',
 		];
 
 		test('Simple includes', () => {
@@ -89,7 +102,7 @@ describe('nodester Query Language', () => {
 			const tree = new ModelsTree();
 			tree.include('comments').use('comments');
 			tree.node.addWhere({ id: ['10'], position: ['4'] });
-			tree.node.fields = [ 'id', 'content', 'position' ];
+			tree.node.attributes = [ 'id', 'content', 'position' ];
 			tree.node.limit = 3;
 			tree.node.skip = 10;
 			tree.node.order = 'desc';
@@ -171,7 +184,7 @@ describe('nodester Query Language', () => {
 			tree.node.order = 'rand';
 			tree.up();
 			tree.include('users').use('users');
-			tree.node.fields = [ 'id', 'content' ];
+			tree.node.attributes = [ 'id', 'content' ];
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);