nodester 0.6.76 → 0.7.1

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

@@ -14,7 +14,7 @@ const debug = require('debug')('nodester:interpreter:ModelsTree');
  * @access public
  */
 class ModelsTreeNode {
-	constructor(model, parent=null, opts={}) {
+	constructor(model, parent = null, opts = {}) {
 		this.model = model;
 		this.parent = parent;
 
@@ -30,11 +30,13 @@ class ModelsTreeNode {
 		this.group_by = opts.group_by ?? undefined;
 		this.skip = 0;
 		this.limit = -1; // No limit
-		
+
 		this.order = opts.order ?? undefined;
 		this.order_by = opts.order_by ?? undefined;
 		// Clauses\
 
+		this.required = false; // For root filtering via ^
+
 		this._includes = opts.includes ?? [];
 	}
 
@@ -85,14 +87,14 @@ class ModelsTreeNode {
 		this.fn = null;
 	}
 
-	addWhere(condition={}) {
+	addWhere(condition = {}) {
 		this._where = {
 			...this.where,
 			...condition
 		}
 	}
 
-	addFunction(fnParams={}) {
+	addFunction(fnParams = {}) {
 		this._functions.push(fnParams);
 	}
 
@@ -102,6 +104,14 @@ class ModelsTreeNode {
 		return modelTreeNode;
 	}
 
+	markAsRequired() {
+		this.required = true;
+		// Propagate up the tree (except for root)
+		if (this.parent && this.parent.model !== 'root') {
+			this.parent.markAsRequired();
+		}
+	}
+
 	toObject() {
 		return {
 			model: this.model,
@@ -116,7 +126,8 @@ class ModelsTreeNode {
 			limit: this.limit,
 			order: this.order,
 			order_by: this.order_by,
-			
+
+			required: this.required,
 
 			includes: this.includes.map(i => i.toObject())
 		}
@@ -134,7 +145,7 @@ class ModelsTree {
 		this.node = this.root;
 	}
 
-	include(model, opts={}) {
+	include(model, opts = {}) {
 		debug('include', model);
 
 		const node = new ModelsTreeNode(model, this.node, opts);
@@ -153,7 +164,7 @@ class ModelsTree {
 		}
 
 		debug('use', model, !!foundOne ? '' : '-> failed.');
-		
+
 		return foundOne;
 	}
 

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

@@ -242,9 +242,6 @@ module.exports = class QueryLexer {
 					// Reset:
 					tree.node.resetActiveParam();
 					tree.node.resetOP();
-
-					// Lift from subquery.
-					tree.up();
 				}
 				const numberOfProcessedChars = i - startAt;
 				return [numberOfProcessedChars];
@@ -259,7 +256,7 @@ module.exports = class QueryLexer {
 
 				// If OP token:
 				if (!!tree.node.op) {
-					switch(tree.node.op) {
+					switch (tree.node.op) {
 						case OP_TOKENS.NOT_IN:
 						case OP_TOKENS.IN:
 							value.push(token);
@@ -510,6 +507,19 @@ module.exports = class QueryLexer {
 				continue;
 			}
 
+
+			// ^ can mean:
+			// • root filtering (INNER JOIN) - attribute in subquery that filters root
+			if (char === '^') {
+				debug('char', char, { token, node: tree.node });
+
+				// Mark current node as required (will propagate up)
+				tree.node.markAsRequired();
+
+				// Continue to next char (don't add ^ to token)
+				continue;
+			}
+
 			// = can only mean the end of a param name:
 			if (char === '=') {
 				const param = this.parseParamFromToken(token);

package/lib/query/traverse/index.js

@@ -2,7 +2,7 @@
  * nodester
  * MIT Licensed
  */
- 
+
 'use strict';
 
 const BOUNDS = require('../../constants/Bounds');
@@ -44,7 +44,7 @@ module.exports = traverse;
  *
  * @access public
  */
-function traverse(queryNode, filter=null, model=null, association=null) {
+function traverse(queryNode, filter = null, model = null, association = null) {
 	const _model = model ?? filter.model;
 
 	try {
@@ -55,7 +55,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 			throw err;
 		}
 	}
-	catch(error) {
+	catch (error) {
 		Error.captureStackTrace(error, traverse);
 		throw error;
 	}
@@ -78,8 +78,15 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 		where,
 
 		includes,
+		required,
 	} = disassembleQueryNode(queryNode);
 
+	// If this include is marked as required (root filtering via ^),
+	// set it on the query:
+	if (required) {
+		newQuery.required = true;
+	}
+
 
 	// Attribute:
 	//
@@ -102,7 +109,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 		//	put them through Filter:
 		for (let attribute of filter.attributes) {
 			if (attributesAvailable.indexOf(attribute) === -1) {
-				const err = new NodesterQueryError(`Field '${ attribute }' is not present in model.`);
+				const err = new NodesterQueryError(`Field '${attribute}' is not present in model.`);
 				Error.captureStackTrace(err, traverse);
 				throw err;
 			}
@@ -119,7 +126,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 			}
 		}
 	}
-	
+
 	// At least 1 attribute is mandatory
 	// or "functions" must be set:
 	if (
@@ -138,12 +145,12 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 		const fnName = fnParams.fn;
 
 		if (typeof filter.functions[fnName] === 'undefined') {
-			const err = new NodesterQueryError(`Function '${ fnName }' is not allowed.`);
+			const err = new NodesterQueryError(`Function '${fnName}' is not allowed.`);
 			Error.captureStackTrace(err, traverse);
 			throw err;
 		}
 
-		switch(fnName) {
+		switch (fnName) {
 			// SQL COUNT():
 			case 'count': {
 				mapCOUNT(
@@ -157,7 +164,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 			}
 			// Any other function:
 			default:
-				consl.warn(`function ${ fnName }() is not supported`);
+				consl.warn(`function ${fnName}() is not supported`);
 				break;
 		}
 	}
@@ -167,7 +174,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 	const order = {};
 
 	const clausesEntries = Object.entries(clauses);
-	for (const [ clauseName, value ] of clausesEntries) {
+	for (const [clauseName, value] of clausesEntries) {
 
 		// If clause is not available:
 		if (filter != null) {
@@ -176,7 +183,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 			}
 		}
 
-		switch(clauseName) {
+		switch (clauseName) {
 			case 'group_by': {
 				// Check if this value is a valid attribute:
 				if (typeof value === 'undefined') {
@@ -184,7 +191,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 				}
 
 				if (typeof _model.tableAttributes[value] === 'undefined') {
-					const err = new NodesterQueryError(`group_by '${ value }' is not allowed.`);
+					const err = new NodesterQueryError(`group_by '${value}' is not allowed.`);
 					Error.captureStackTrace(err, traverse);
 					throw err;
 				}
@@ -197,7 +204,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 				const _value = _setValueWithBounds(value, 'number', filter.bounds.clauses.limit);
 
 				// Do not set if negative:
-				if (_value < 0) 
+				if (_value < 0)
 					continue;
 
 				newQuery.limit = _value;
@@ -237,9 +244,9 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 		const staticClausesEntries = Object.entries(filter.statics.clauses);
 
 		for (let entry of staticClausesEntries) {
-			const [ clauseName, staticClauseValue ] = entry;
+			const [clauseName, staticClauseValue] = entry;
 
-			switch(clauseName) {
+			switch (clauseName) {
 				case 'group_by':
 					newQuery.group = staticClauseValue;
 					continue;
@@ -282,7 +289,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 		newQuery.order = sequelize.random();
 	}
 	else {
-		const column = sequelize.col( order.by );
+		const column = sequelize.col(order.by);
 		switch (order.order) {
 			// MAX/MIN:
 			case 'max-asc':
@@ -293,7 +300,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 			case 'min':
 			case 'min-asc':
 			case 'max-desc':
-				newQuery.order = [ sequelize.fn('max', column), 'DESC' ];
+				newQuery.order = [sequelize.fn('max', column), 'DESC'];
 				break;
 			// MAX/MIN\
 
@@ -303,7 +310,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 				break;
 
 			default:
-				newQuery.order = [ [order.by, order.order] ];
+				newQuery.order = [[order.by, order.order]];
 				break;
 		}
 	}
@@ -316,7 +323,7 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 		const includeName = include.model;
 
 		if (rootModelAssociations[includeName] === undefined) {
-			const err = new NodesterQueryError(`No include named '${ includeName }'`);			
+			const err = new NodesterQueryError(`No include named '${includeName}'`);
 			Error.captureStackTrace(err, traverse);
 			throw err;
 		}
@@ -330,13 +337,13 @@ function traverse(queryNode, filter=null, model=null, association=null) {
 
 	//	Set aatributes from Query:
 	const whereEntries = Object.entries(where);
-	for (const [ attribute, value ] of whereEntries) {
+	for (const [attribute, value] of whereEntries) {
 		parseWhereEntry(attribute, value, newQuery.where, _model);
 	}
 
 	//	Static attributes override previously set attributes:
 	const staticAttributesEntries = Object.entries(filter.statics.attributes);
-	for (const [ attribute, staticValue ] of staticAttributesEntries) {
+	for (const [attribute, staticValue] of staticAttributesEntries) {
 		newQuery.where[attribute] = parseValue(staticValue, attribute, _model);
 	}
 
@@ -369,13 +376,13 @@ function traverse(queryNode, filter=null, model=null, association=null) {
  */
 function _traverseIncludes(includes, rootModel, filter, resultQuery) {
 	const filterIncludesEntries = Object.entries(filter.includes);
-	for (let [ includeName, includeFilter ] of filterIncludesEntries) {
+	for (let [includeName, includeFilter] of filterIncludesEntries) {
 
 		const association = rootModel.associations[includeName];
 
 		// If no such association:
 		if (!association) {
-			const err = new NodesterQueryError(`No include named '${ includeName }'`);			
+			const err = new NodesterQueryError(`No include named '${includeName}'`);
 			Error.captureStackTrace(err, _traverseIncludes);
 			throw err;
 		}
@@ -394,7 +401,7 @@ function _traverseIncludes(includes, rootModel, filter, resultQuery) {
 }
 
 function _traverseIncludedOrders(resultQuery, rootModel) {
-	for (let i=0; i < resultQuery.include.length; i++) {
+	for (let i = 0; i < resultQuery.include.length; i++) {
 		const include = resultQuery.include[i];
 
 		if (!include?.order) {
@@ -411,7 +418,7 @@ function _traverseIncludedOrders(resultQuery, rootModel) {
 			associationType
 		} = getModelAssociationProps(rootModel.associations[association]);
 
-		switch(associationType) {
+		switch (associationType) {
 			case 'HasMany': {
 				include.separate = true;
 				// resultQuery.order.push([
@@ -434,7 +441,7 @@ function _traverseIncludedOrders(resultQuery, rootModel) {
 function _setValueWithBounds(value, type, bounds) {
 	if (typeof bounds === 'object') {
 
-		switch(type) {
+		switch (type) {
 			case 'number': {
 				let _value = value;
 

package/lib/query/traverse/utils.js

@@ -2,7 +2,7 @@
  * nodester
  * MIT Licensed
  */
- 
+
 'use strict';
 
 
@@ -18,6 +18,7 @@ function _disassembleQueryNode(queryNode) {
 		functions,
 		where,
 		includes,
+		required,
 		...clauses
 	} = queryNode;
 
@@ -27,6 +28,7 @@ function _disassembleQueryNode(queryNode) {
 		functions: functions ?? [],
 		where: where ?? {},
 		includes: includes ?? [],
+		required: required ?? false,
 	};
 }
 

package/package.json

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

package/tests/nql.test.js

@@ -24,7 +24,7 @@ describe('nodester Query Language', () => {
 		];
 
 		it('Simple where', async () => {
-			const lexer = new QueryLexer( queryStrings[0] );
+			const lexer = new QueryLexer(queryStrings[0]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -35,24 +35,24 @@ describe('nodester Query Language', () => {
 		});
 
 		it('Only certain attributes', async () => {
-			const lexer = new QueryLexer( queryStrings[1] );
+			const lexer = new QueryLexer(queryStrings[1]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
-			tree.node.attributes = [ 'id', 'text' ];
+			tree.node.attributes = ['id', 'text'];
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('All possible params', async () => {
-			const lexer = new QueryLexer( queryStrings[2] );
+			const lexer = new QueryLexer(queryStrings[2]);
 			const result = await lexer.parse();
 
 
 			const tree = new ModelsTree();
 			tree.node.addWhere({ id: ['10'], position: ['4'] });
-			tree.node.attributes = [ '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';
@@ -74,20 +74,20 @@ describe('nodester Query Language', () => {
 			'2-horizontals': 'includes=comments,users&id=1000',
 			// 4 horizontals with subquery.
 			'4-horizontals': 'in=categories,replies.users,comments(order_by=position&order=desc),users.avatars',
-			
+
 			// Horizontals queried.
 			'horizontals-queried': 'includes=comments(order=desc),users,likes(order=rand),reposts&id=1000',
 			// Horizontals queried №2.
 			'horizontals-queried-2': 'in=comments(order_by=index&order=asc).users.karma',
 			// Horizontals queried №3.
 			'horizontals-queried-3': 'in=reactions,comments(user_id=gte(4)&skip=10&limit=2).users,likes,reposts',
-			
+
 			// Separated includes.
 			'separated-includes': 'includes=comments(order=rand)&id=7&limit=3&includes=users(a=id,content)',
 		};
 
 		test('Simple includes', async () => {
-			const lexer = new QueryLexer( queryStrings['simple-includes'] );
+			const lexer = new QueryLexer(queryStrings['simple-includes']);
 			const result = await lexer.parse();
 
 
@@ -100,13 +100,13 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Include with all possible params', async () => {
-			const lexer = new QueryLexer( queryStrings['include-with-params'] );
+			const lexer = new QueryLexer(queryStrings['include-with-params']);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
 			tree.include('comments').use('comments');
 			tree.node.addWhere({ id: ['10'], position: ['4'] });
-			tree.node.attributes = [ 'id', 'content', 'position' ];
+			tree.node.attributes = ['id', 'content', 'position'];
 			tree.node.limit = 3;
 			tree.node.skip = 10;
 			tree.node.order = 'desc';
@@ -117,7 +117,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('2 horizontals', async () => {
-			const lexer = new QueryLexer( queryStrings['2-horizontals'] );
+			const lexer = new QueryLexer(queryStrings['2-horizontals']);
 			const result = await lexer.parse();
 
 
@@ -133,7 +133,7 @@ describe('nodester Query Language', () => {
 		test('4 horizontals', async () => {
 			// in=categories,replies.users,comments(order_by=position&order=desc),users.avatars
 
-			const lexer = new QueryLexer( queryStrings['4-horizontals'] );
+			const lexer = new QueryLexer(queryStrings['4-horizontals']);
 			const result = await lexer.parse();
 
 
@@ -162,7 +162,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Horizontals queried', async () => {
-			const lexer = new QueryLexer( queryStrings['horizontals-queried'] );
+			const lexer = new QueryLexer(queryStrings['horizontals-queried']);
 			const result = await lexer.parse();
 
 
@@ -182,7 +182,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Horizontals queried №2', async () => {
-			const lexer = new QueryLexer( queryStrings['horizontals-queried-2'] );
+			const lexer = new QueryLexer(queryStrings['horizontals-queried-2']);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -200,7 +200,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Horizontals queried №3', async () => {
-			const lexer = new QueryLexer( queryStrings['horizontals-queried-3'] );
+			const lexer = new QueryLexer(queryStrings['horizontals-queried-3']);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -208,9 +208,9 @@ describe('nodester Query Language', () => {
 
 			tree.include('comments').use('comments');
 			tree.node.addWhere({
-					user_id: {
-						gte: ['4']
-					}
+				user_id: {
+					gte: ['4']
+				}
 			});
 			tree.node.skip = 10;
 			tree.node.limit = 2;
@@ -227,7 +227,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Separated includes"', async () => {
-			const lexer = new QueryLexer( queryStrings['separated-includes'] );
+			const lexer = new QueryLexer(queryStrings['separated-includes']);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -237,7 +237,7 @@ describe('nodester Query Language', () => {
 			tree.node.order = 'rand';
 			tree.up();
 			tree.include('users').use('users');
-			tree.node.attributes = [ 'id', 'content' ];
+			tree.node.attributes = ['id', 'content'];
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
@@ -260,10 +260,16 @@ describe('nodester Query Language', () => {
 
 			// Complex subincludes query, "+" syntaxis.
 			'includes=comments(order=desc).users+likes(order=rand&order_by=position)&id=1000',
+
+			// Complex subincludes query, "+" syntaxis with include.
+			'includes=comments(order=desc).users+likes(order=rand&order_by=position).reviews&id=1000',
+
+			// Complex subincludes query, "+" syntaxis with double include.
+			'includes=comments(order=desc).users+likes(order=rand&order_by=position).reviews.admin&id=1000',
 		];
 
 		test('Simple subinclude', async () => {
-			const lexer = new QueryLexer( queryStrings[0] );
+			const lexer = new QueryLexer(queryStrings[0]);
 			const result = await lexer.parse();
 
 
@@ -276,7 +282,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Deep subincludes', async () => {
-			const lexer = new QueryLexer( queryStrings[1] );
+			const lexer = new QueryLexer(queryStrings[1]);
 			const result = await lexer.parse();
 
 
@@ -292,7 +298,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Simple horizontal subinclude, "+" syntaxis"', async () => {
-			const lexer = new QueryLexer( queryStrings[2] );
+			const lexer = new QueryLexer(queryStrings[2]);
 			const result = await lexer.parse();
 
 
@@ -306,7 +312,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Subinclude query', async () => {
-			const lexer = new QueryLexer( queryStrings[3] );
+			const lexer = new QueryLexer(queryStrings[3]);
 			const result = await lexer.parse();
 
 
@@ -321,7 +327,45 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Complex subincludes query, "+" syntaxis', async () => {
-			const lexer = new QueryLexer( queryStrings[4] );
+			const lexer = new QueryLexer(queryStrings[4]);
+			const result = await lexer.parse();
+
+
+			const tree = new ModelsTree();
+			tree.include('comments').use('comments');
+			tree.node.addWhere({ id: ['1000'] });
+			tree.node.order = 'desc';
+			tree.include('users');
+			tree.include('likes') && tree.use('likes');
+			tree.node.order = 'rand';
+			tree.node.order_by = 'position';
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		test('Complex subincludes query, "+" syntaxis with include', async () => {
+			const lexer = new QueryLexer(queryStrings[5]);
+			const result = await lexer.parse();
+
+
+			const tree = new ModelsTree();
+			tree.node.addWhere({ id: ['1000'] });
+			tree.include('comments').use('comments');
+			tree.node.order = 'desc';
+			tree.include('users');
+			tree.include('likes') && tree.use('likes');
+			tree.node.order = 'rand';
+			tree.node.order_by = 'position';
+			tree.include('reviews');
+			tree.up();
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		test('Complex subincludes query, "+" syntaxis with double include', async () => {
+			const lexer = new QueryLexer(queryStrings[6]);
 			const result = await lexer.parse();
 
 
@@ -333,6 +377,9 @@ describe('nodester Query Language', () => {
 			tree.include('likes') && tree.use('likes');
 			tree.node.order = 'rand';
 			tree.node.order_by = 'position';
+			tree.include('reviews') && tree.use('reviews');
+			tree.include('admin')
+			tree.up();
 			tree.up();
 			const expected = tree.root.toObject();
 
@@ -349,22 +396,22 @@ describe('nodester Query Language', () => {
 		];
 
 		test('"OR" simple', async () => {
-			const lexer = new QueryLexer( queryStrings[0] );
+			const lexer = new QueryLexer(queryStrings[0]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ or: [ { index: ['2'] }, { position: ['5'] } ] });
+			tree.node.addWhere({ or: [{ index: ['2'] }, { position: ['5'] }] });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('"OR" short', async () => {
-			const lexer = new QueryLexer( queryStrings[1] );
+			const lexer = new QueryLexer(queryStrings[1]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ or: [ { index: ['2'] }, { position: ['5'] } ] });
+			tree.node.addWhere({ or: [{ index: ['2'] }, { position: ['5'] }] });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
@@ -382,7 +429,7 @@ describe('nodester Query Language', () => {
 		];
 
 		test('"NOT" simple', async () => {
-			const lexer = new QueryLexer( queryStrings[0] );
+			const lexer = new QueryLexer(queryStrings[0]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -393,7 +440,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('"NOT" short', async () => {
-			const lexer = new QueryLexer( queryStrings[1] );
+			const lexer = new QueryLexer(queryStrings[1]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -404,12 +451,12 @@ describe('nodester Query Language', () => {
 		});
 
 		test('"NOT" inside includes', async () => {
-			const lexer = new QueryLexer( queryStrings[2] );
+			const lexer = new QueryLexer(queryStrings[2]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
 			tree.include('comments').use('comments');
-			tree.node.addWhere({ id: { not: ['7'] }});
+			tree.node.addWhere({ id: { not: ['7'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
@@ -429,33 +476,33 @@ describe('nodester Query Language', () => {
 		];
 
 		test('"Like" simple', async () => {
-			const lexer = new QueryLexer( queryStrings[0] );
+			const lexer = new QueryLexer(queryStrings[0]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ title: { like: ['some_text'] }});
+			tree.node.addWhere({ title: { like: ['some_text'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('"NotLike" simple', async () => {
-			const lexer = new QueryLexer( queryStrings[1] );
+			const lexer = new QueryLexer(queryStrings[1]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ title: { notLike: ['some_text'] }});
+			tree.node.addWhere({ title: { notLike: ['some_text'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('"NotLike" short', async () => {
-			const lexer = new QueryLexer( queryStrings[2] );
+			const lexer = new QueryLexer(queryStrings[2]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ title: { notLike: ['some_text'] }});
+			tree.node.addWhere({ title: { notLike: ['some_text'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
@@ -472,23 +519,23 @@ describe('nodester Query Language', () => {
 		];
 
 		test('"IN" simple', async () => {
-			const lexer = new QueryLexer( queryStrings[0] );
+			const lexer = new QueryLexer(queryStrings[0]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ status: { in: ['REVIEWED', 'ANSWERED'] }});
+			tree.node.addWhere({ status: { in: ['REVIEWED', 'ANSWERED'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('"IN" and "limit" clause', async () => {
-			const lexer = new QueryLexer( queryStrings[1] );
+			const lexer = new QueryLexer(queryStrings[1]);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
 			tree.node.limit = 3;
-			tree.node.addWhere({ status: { in: ['REVIEWED', 'ANSWERED'] }});
+			tree.node.addWhere({ status: { in: ['REVIEWED', 'ANSWERED'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
@@ -514,62 +561,62 @@ describe('nodester Query Language', () => {
 		];
 
 		test('Greater than', async () => {
-			const lexer = new QueryLexer( queryStrings[0] );
+			const lexer = new QueryLexer(queryStrings[0]);
 			const result = await lexer.parse();
 
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ created_at: { gt: ['2022'] }});
+			tree.node.addWhere({ created_at: { gt: ['2022'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('Greater than or equal to', async () => {
-			const lexer = new QueryLexer( queryStrings[1] );
+			const lexer = new QueryLexer(queryStrings[1]);
 			const result = await lexer.parse();
 
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ created_at: { gte: ['2023-12-08'] }});
+			tree.node.addWhere({ created_at: { gte: ['2023-12-08'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('Lower than', async () => {
-			const lexer = new QueryLexer( queryStrings[2] );
+			const lexer = new QueryLexer(queryStrings[2]);
 			const result = await lexer.parse();
 
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ index: { lt: ['10'] }});
+			tree.node.addWhere({ index: { lt: ['10'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('Lower than or equal to', async () => {
-			const lexer = new QueryLexer( queryStrings[3] );
+			const lexer = new QueryLexer(queryStrings[3]);
 			const result = await lexer.parse();
 
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ index: { lte: ['9'] }});
+			tree.node.addWhere({ index: { lte: ['9'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('Greater than in subinclude', async () => {
-			const lexer = new QueryLexer( queryStrings[4] );
+			const lexer = new QueryLexer(queryStrings[4]);
 			const result = await lexer.parse();
 
 
 			const tree = new ModelsTree();
 			tree.include('comments').use('comments');
 			tree.include('likes').use('likes');
-			tree.node.addWhere({ index: { gt: ['60'] }});
+			tree.node.addWhere({ index: { gt: ['60'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
@@ -587,18 +634,18 @@ describe('nodester Query Language', () => {
 		}
 
 		test('AND (simple)', async () => {
-			const lexer = new QueryLexer( queryStrings.and_simple );
+			const lexer = new QueryLexer(queryStrings.and_simple);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
-			tree.node.addWhere({ id: { gte: ['2'], lt: ['5'] }});
+			tree.node.addWhere({ id: { gte: ['2'], lt: ['5'] } });
 			const expected = tree.root.toObject();
 
 			expect(result).toMatchObject(expected);
 		});
 
 		test('AND (more OP)', async () => {
-			const lexer = new QueryLexer( queryStrings.and_more_op );
+			const lexer = new QueryLexer(queryStrings.and_more_op);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -611,7 +658,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('AND (in subincludes #0)', async () => {
-			const lexer = new QueryLexer( queryStrings.and_in_subincludes_0 );
+			const lexer = new QueryLexer(queryStrings.and_in_subincludes_0);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -625,7 +672,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('AND (in subincludes #1)', async () => {
-			const lexer = new QueryLexer( queryStrings.and_in_subincludes_1 );
+			const lexer = new QueryLexer(queryStrings.and_in_subincludes_1);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -642,7 +689,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('AND (in subincludes #2)', async () => {
-			const lexer = new QueryLexer( queryStrings.and_in_subincludes_2 );
+			const lexer = new QueryLexer(queryStrings.and_in_subincludes_2);
 			const result = await lexer.parse();
 
 			const tree = new ModelsTree();
@@ -669,7 +716,7 @@ describe('nodester Query Language', () => {
 		}
 
 		test('Count (full key name)', async () => {
-			const lexer = new QueryLexer( queryStrings.count_long );
+			const lexer = new QueryLexer(queryStrings.count_long);
 			const result = await lexer.parse();
 
 
@@ -684,7 +731,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Count (short key name)', async () => {
-			const lexer = new QueryLexer( queryStrings.count_long );
+			const lexer = new QueryLexer(queryStrings.count_long);
 			const result = await lexer.parse();
 
 
@@ -699,7 +746,7 @@ describe('nodester Query Language', () => {
 		});
 
 		test('Count and includes', async () => {
-			const lexer = new QueryLexer( queryStrings.count_and_includes );
+			const lexer = new QueryLexer(queryStrings.count_and_includes);
 			const result = await lexer.parse();
 
 
@@ -714,4 +761,46 @@ describe('nodester Query Language', () => {
 			expect(result).toMatchObject(expected);
 		});
 	});
+
+	describe('root-filtering', () => {
+		const queryStrings = {
+			simple: 'includes=order(^is_filled=1)',
+			complex: 'includes=product.order(^is_filled=1)+photos(limit=5)',
+		}
+
+		test('Simple root filtering with ^', async () => {
+			const lexer = new QueryLexer(queryStrings.simple);
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.include('order').use('order');
+			tree.node.addWhere({ is_filled: ['1'] });
+			tree.node.markAsRequired();
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+			expect(result.includes[0].required).toBe(true);
+		});
+
+		test('Complex nested root filtering with ^', async () => {
+			const lexer = new QueryLexer(queryStrings.complex);
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.include('product').use('product');
+			tree.include('order').use('order');
+			tree.node.addWhere({ is_filled: ['1'] });
+			tree.node.markAsRequired();
+			tree.up();
+			tree.up();
+			tree.include('photos').use('photos');
+			tree.node.limit = 5;
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+			expect(result.includes[0].required).toBe(true);
+			expect(result.includes[0].includes[0].required).toBe(true);
+			expect(result.includes[1].required).toBe(false);
+		});
+	});
 });