nodester 0.7.11 → 0.7.13

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

@@ -64,6 +64,9 @@ const OP_TOKENS = new Enum({
 const FN_TOKENS = new Enum({
 	AVG: 'avg',
 	COUNT: 'count',
+	SUM: 'sum',
+	MIN: 'min',
+	MAX: 'max',
 });
 
 
@@ -157,10 +160,12 @@ module.exports = class QueryLexer {
 				// If end of OP token:
 				if (!!tree.node.op) {
 
-					// If token is empty, error:
+					// If token is empty, treat as a no-op.
+					// e.g. `name=like()` means "no filter on this field"
+					// (common when a frontend search field is cleared).
 					if (token === '') {
-						const err = UnexpectedCharError(i, char);
-						return Promise.reject(err);
+						tree.node.resetOP();
+						continue;
 					}
 
 					// Structure of a value depends on OP:
@@ -315,7 +320,7 @@ module.exports = class QueryLexer {
 			// . can mean:
 			// • vertical include
 			// • or it can be a part of a param for "where"
-			if (char === '.') {
+			if (char === '.' && !tree.node.fn && !tree.node.op) {
 				debug('char', char, { token, node: tree.node });
 
 				// Vertical include:
@@ -344,7 +349,7 @@ module.exports = class QueryLexer {
 			}
 
 			// + can only mean horizontal include:
-			if (char === '+') {
+			if (char === '+' && !tree.node.fn && !tree.node.op) {
 				debug('char', char, { token, node: tree.node });
 
 				// If include of a new model:
@@ -636,7 +641,8 @@ module.exports = class QueryLexer {
 
 			// Clauses:
 			case PARAM_TOKENS.GROUP_BY:
-				treeNode.group_by = token;
+				if (token) value.push(token);
+				treeNode.group_by = value.length > 1 ? value : value[0];
 				break;
 
 			case PARAM_TOKENS.LIMIT:

package/lib/query/traverse/index.js

@@ -14,6 +14,7 @@ const { ensure } = require('nodester/validators/arguments');
 
 // Mappers & parsers:
 const mapCOUNT = require('./mappers/functions/count');
+const mapAGG = require('./mappers/functions/aggregate');
 
 const {
 	parseValue,
@@ -92,10 +93,13 @@ function traverse(queryNode, filter = null, model = null, association = null) {
 	//
 	//	If Filter is not set,
 	//	use every available attribute:
+	const isAggregateQuery = functions.length > 0 && clauses.group_by;
+	const selectAllByDefault = attributes.length === 0 && !isAggregateQuery;
+
 	if (filter === null) {
 		for (let attribute of attributesAvailable) {
 			// If no query filter or attribute is requested:
-			if (attributes.length === 0 || attributes.indexOf(attribute) > -1) {
+			if (selectAllByDefault || attributes.indexOf(attribute) > -1) {
 				newQuery.attributes.push(attribute);
 				continue;
 			}
@@ -120,7 +124,7 @@ function traverse(queryNode, filter = null, model = null, association = null) {
 			// }
 
 			// If no query filter or attribute is requested:
-			if (attributes.length === 0 || attributes.indexOf(attribute) > -1) {
+			if (selectAllByDefault || attributes.indexOf(attribute) > -1) {
 				newQuery.attributes.push(attribute);
 				continue;
 			}
@@ -144,7 +148,9 @@ function traverse(queryNode, filter = null, model = null, association = null) {
 	for (const fnParams of functions) {
 		const fnName = fnParams.fn;
 
-		if (typeof filter.functions[fnName] === 'undefined') {
+		const isAllowed = filter.functions.indexOf(fnName) > -1;
+
+		if (!isAllowed) {
 			const err = new NodesterQueryError(`Function '${fnName}' is not allowed.`);
 			Error.captureStackTrace(err, traverse);
 			throw err;
@@ -162,6 +168,20 @@ function traverse(queryNode, filter = null, model = null, association = null) {
 				);
 				break;
 			}
+			// SQL SUM(), AVG(), MIN(), MAX():
+			case 'sum':
+			case 'avg':
+			case 'min':
+			case 'max': {
+				mapAGG(
+					fnParams,
+					_model,
+					filter?.includes,
+
+					newQuery
+				);
+				break;
+			}
 			// Any other function:
 			default:
 				consl.warn(`function ${fnName}() is not supported`);
@@ -185,15 +205,22 @@ function traverse(queryNode, filter = null, model = null, association = null) {
 
 		switch (clauseName) {
 			case 'group_by': {
-				// Check if this value is a valid attribute:
 				if (typeof value === 'undefined') {
 					continue;
 				}
 
-				if (typeof _model.tableAttributes[value] === 'undefined') {
-					const err = new NodesterQueryError(`group_by '${value}' is not allowed.`);
-					Error.captureStackTrace(err, traverse);
-					throw err;
+				const groupFields = Array.isArray(value) ? value : [value];
+				for (const field of groupFields) {
+					if (typeof _model.tableAttributes[field] === 'undefined') {
+						const err = new NodesterQueryError(`group_by '${field}' is not allowed.`);
+						Error.captureStackTrace(err, traverse);
+						throw err;
+					}
+
+					// For aggregate queries, group_by field MUST be in attributes:
+					if (newQuery.attributes.indexOf(field) === -1) {
+						newQuery.attributes.push(field);
+					}
 				}
 
 				newQuery.group = value;

package/lib/query/traverse/mappers/functions/aggregate.js

@@ -0,0 +1,85 @@
+const { NodesterQueryError } = require('nodester/errors');
+
+module.exports = function mapAggregate(
+    fnParams,
+    rootModel,
+    filterIncludes,
+
+    sequelizeQuery
+) {
+    try {
+        const { sequelize } = rootModel;
+        const rootModelName = rootModel.options.name;
+
+        const { fn: fnName, args } = fnParams;
+        const [target] = args;
+
+        if (!target) {
+            const err = new NodesterQueryError(`Function '${fnName}' requires an attribute.`);
+            Error.captureStackTrace(err, mapAggregate);
+            throw err;
+        }
+
+        const associations = rootModel.associations;
+        let associationName = null;
+        let attributeName = target;
+
+        if (target.includes('.')) {
+            [associationName, attributeName] = target.split('.');
+        } else if (associations[target]) {
+            // If target IS an association name, it might be a mistake for sum/avg/min/max
+            // but we can try to be helpful or error out.
+            // However, count(comments) is valid.
+            const err = new NodesterQueryError(`Function '${fnName}' requires an attribute of '${target}'. Use '${target}.attribute'`);
+            Error.captureStackTrace(err, mapAggregate);
+            throw err;
+        }
+
+        if (associationName) {
+            const association = associations[associationName];
+            if (!association) {
+                const err = new NodesterQueryError(`No include named '${associationName}'`);
+                Error.captureStackTrace(err, mapAggregate);
+                throw err;
+            }
+
+            // Check if it's available in filter:
+            if (!filterIncludes[associationName]) {
+                const err = new NodesterQueryError(`Aggregate for '${associationName}' is not available.`);
+                Error.captureStackTrace(err, mapAggregate);
+                throw err;
+            }
+
+            const {
+                as,
+                target: targetModel,
+                foreignKey,
+                sourceKey
+            } = association;
+            const { tableName } = targetModel;
+
+            // Compile request:
+            const rawSQL = `(SELECT ${fnName.toUpperCase()}(${attributeName}) FROM ${tableName} WHERE ${tableName}.${foreignKey}=${rootModelName.singular}.${sourceKey})`;
+
+            const resultAttributeName = `${as}_${fnName}_${attributeName}`;
+            sequelizeQuery.attributes.push(
+                [sequelize.literal(rawSQL), resultAttributeName]
+            );
+        } else {
+            // Root model attribute:
+            if (typeof rootModel.tableAttributes[attributeName] === 'undefined') {
+                const err = new NodesterQueryError(`Attribute '${attributeName}' is not present in model.`);
+                Error.captureStackTrace(err, mapAggregate);
+                throw err;
+            }
+
+            const resultAttributeName = `${attributeName}_${fnName}`;
+            sequelizeQuery.attributes.push(
+                [sequelize.fn(fnName.toUpperCase(), sequelize.col(attributeName)), resultAttributeName]
+            );
+        }
+    } catch (error) {
+        Error.captureStackTrace(error, mapAggregate);
+        throw error;
+    }
+}

package/lib/query/traverse/parsers.js

@@ -2,7 +2,7 @@
  * nodester
  * MIT Licensed
  */
- 
+
 'use strict';
 
 const { Op } = require('sequelize');
@@ -20,17 +20,39 @@ function _parseValue(value, attribute, model) {
 		// Combine all OPs into one query:
 		const allOPs = {};
 		const entries = Object.entries(value);
-		for (const [ opKey, rawValue ] of entries) {
+		for (const [opKey, rawValue] of entries) {
 			const op = Op[opKey];
 
 			let _value = rawValue;
 
 			// Sequilize does not allow Op comparisons of dates
 			// without converting the value to the Date object:
-			switch(model.tableAttributes[attribute].type.key) {
+			switch (model.tableAttributes[attribute].type.key) {
 				case DataTypes.DATE.key:
 				case DataTypes.DATEONLY.key:
-					_value = new Date(rawValue);
+					const parse = (val) => {
+						if (!val) return null;
+						let d = new Date(val);
+						if (isNaN(d.valueOf()) && typeof val === 'string') {
+							// Try to fix common space/plus-instead-of-T issue:
+							d = new Date(val.trim().replace(/[ +]/g, 'T'));
+						}
+						if (isNaN(d.valueOf())) {
+							const err = new Error(`nodester: Invalid date value '${val}' for attribute '${attribute}'`);
+							throw err;
+						}
+						return d;
+					};
+
+					if (Array.isArray(rawValue)) {
+						if (opKey === 'in' || opKey === 'notIn' || opKey === 'between' || opKey === 'notBetween') {
+							_value = rawValue.map(v => parse(v));
+						} else {
+							_value = parse(rawValue[0]);
+						}
+					} else {
+						_value = parse(rawValue);
+					}
 					break;
 
 				default:

package/lib/query/traverse/utils.js

@@ -24,7 +24,7 @@ function _disassembleQueryNode(queryNode) {
 
 	return {
 		attributes: attributes ?? [],
-		clauses: clauses ?? [],
+		clauses: clauses ?? {},
 		functions: functions ?? [],
 		where: where ?? {},
 		includes: includes ?? [],

package/lib/structures/Filter.js

@@ -2,7 +2,7 @@
  * nodester
  * MIT Licensed
  */
- 
+
 'use strict';
 
 const BOUNDS = require('../constants/Bounds');
@@ -37,9 +37,9 @@ const consl = require('nodester/loggers/console');
  */
 module.exports = class NodesterFilter {
 
-	constructor(model=null, options={}) {
+	constructor(model = null, options = {}) {
 		ensure(options, 'object,required', 'options');
-		
+
 		this._model = model;
 
 		this._attributes = [];
@@ -52,7 +52,7 @@ module.exports = class NodesterFilter {
 			attributes: {},
 			clauses: {}
 		}
-		
+
 		this._statics = {
 			attributes: {},
 			clauses: {}
@@ -72,7 +72,7 @@ module.exports = class NodesterFilter {
 				}
 			}
 		}
-		
+
 		const {
 			attributes,
 			clauses,
@@ -105,12 +105,8 @@ module.exports = class NodesterFilter {
 
 		// If functions are set:
 		if (!!functions) {
-			if (
-				typeof functions !== 'object'
-				||
-				Array.isArray(functions)
-			) {
-				const err = new TypeError(`[NodesterFilter]: 'functions' parameter must be an object.`);
+			if (!Array.isArray(functions)) {
+				const err = new TypeError(`[NodesterFilter]: 'functions' parameter must be an array.`);
 				throw err;
 			}
 
@@ -120,12 +116,12 @@ module.exports = class NodesterFilter {
 		// Includes:
 		if (typeof includes === 'object') {
 			const { associations } = this.model;
-			for (const [ includeName, includeFilter ] of Object.entries(includes)) {
+			for (const [includeName, includeFilter] of Object.entries(includes)) {
 				const association = associations[includeName];
-				
+
 				// Validate association by name:
 				if (association === undefined) {
-					const error = new TypeError(`No include named '${ includeName }'.`);
+					const error = new TypeError(`No include named '${includeName}'.`);
 					Error.captureStackTrace(error, this.constructor);
 					throw error;
 				}
@@ -138,8 +134,8 @@ module.exports = class NodesterFilter {
 					// Empty bounds:
 					if (!!includeFilter.statics.clauses.limit) {
 						const msg = [
-							`include "${ includeName }" has association type of`,
-							`"${ associationType }", but has a filter clause "limit",`,
+							`include "${includeName}" has association type of`,
+							`"${associationType}", but has a filter clause "limit",`,
 							`which is forbidden on any association type except for "HasMany".`,
 							`It was automatically removed from clauses.`,
 							`Consider also removing it from your code.`

package/package.json

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

package/tests/aggregates.test.js

@@ -0,0 +1,225 @@
+// Test utils.
+const {
+	describe,
+	it,
+	expect
+} = require('@jest/globals');
+
+// Parser:
+const { ModelsTree } = require('../lib/middlewares/ql/sequelize/interpreter/ModelsTree');
+const QueryLexer = require('../lib/middlewares/ql/sequelize/interpreter/QueryLexer');
+const traverse = require('../lib/query/traverse');
+
+describe('nodester Aggregates', () => {
+	describe('Lexer', () => {
+		it('Root model: count()', async () => {
+			const lexer = new QueryLexer('fn=count()');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.addFunction({
+				fn: 'count',
+				args: ['']
+			});
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		it('Root model: sum(price)', async () => {
+			const lexer = new QueryLexer('fn=sum(price)');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.addFunction({
+				fn: 'sum',
+				args: ['price']
+			});
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		it('Root model: avg(score)', async () => {
+			const lexer = new QueryLexer('fn=avg(score)');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.addFunction({
+				fn: 'avg',
+				args: ['score']
+			});
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		it('Root model: min(age), max(age)', async () => {
+			const lexer = new QueryLexer('fn=min(age),max(age)');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.addFunction({
+				fn: 'min',
+				args: ['age']
+			});
+			tree.node.addFunction({
+				fn: 'max',
+				args: ['age']
+			});
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		it('Association: count(comments)', async () => {
+			const lexer = new QueryLexer('fn=count(comments)');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.addFunction({
+				fn: 'count',
+				args: ['comments']
+			});
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		it('Association: sum(items.price)', async () => {
+			const lexer = new QueryLexer('fn=sum(items.price)');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.addFunction({
+				fn: 'sum',
+				args: ['items.price']
+			});
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+	});
+
+	describe('Traverse', () => {
+		const mockModel = {
+			options: {
+				name: {
+					singular: 'Post',
+					plural: 'Posts'
+				}
+			},
+			associations: {
+				comments: {
+					as: 'comments',
+					target: { tableName: 'comments' },
+					foreignKey: 'post_id',
+					sourceKey: 'id'
+				}
+			},
+			tableAttributes: {
+				id: {},
+				price: {},
+				score: {},
+				age: {},
+				category_id: {},
+				brand_id: {}
+			},
+			sequelize: {
+				fn: (fn, col) => ({ fn, col }),
+				col: (col) => ({ col }),
+				literal: (sql) => ({ literal: sql })
+			}
+		};
+
+		const mockFilter = {
+			model: mockModel,
+			attributes: ['id', 'price', 'score', 'age', 'category_id', 'brand_id'],
+			functions: ['count', 'sum', 'avg', 'min', 'max'],
+			clauses: ['group_by'],
+			bounds: { clauses: {} },
+			statics: { attributes: {}, clauses: {} },
+			includes: {
+				comments: {
+					model: { options: { name: { singular: 'Comment', plural: 'Comments' } }, tableAttributes: { id: {} } },
+					attributes: ['id'],
+					functions: ['count', 'sum'],
+					clauses: [],
+					bounds: { clauses: {} },
+					statics: { attributes: {}, clauses: {} },
+					includes: {}
+				}
+			}
+		};
+
+		it('maps root sum(price)', () => {
+			const queryNode = {
+				functions: [{ fn: 'sum', args: ['price'] }]
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.attributes).toContainEqual([
+				{ fn: 'SUM', col: { col: 'price' } },
+				'price_sum'
+			]);
+		});
+
+		it('maps association count(comments)', () => {
+			const queryNode = {
+				functions: [{ fn: 'count', args: ['comments'] }]
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.attributes).toContainEqual([
+				{ literal: '(SELECT COUNT(*) FROM comments where comments.post_id=Post.id)' },
+				'comments_count'
+			]);
+		});
+
+		it('maps association sum(comments.votes)', () => {
+			const queryNode = {
+				functions: [{ fn: 'sum', args: ['comments.votes'] }]
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.attributes).toContainEqual([
+				{ literal: '(SELECT SUM(votes) FROM comments WHERE comments.post_id=Post.id)' },
+				'comments_sum_votes'
+			]);
+		});
+
+		it('maps root sum(price) with group_by', () => {
+			const queryNode = {
+				functions: [{ fn: 'sum', args: ['price'] }],
+				group_by: 'category_id'
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.group).toBe('category_id');
+			expect(result.attributes).toContainEqual([
+				{ fn: 'SUM', col: { col: 'price' } },
+				'price_sum'
+			]);
+			// Check if it also includes category_id in attributes
+			expect(result.attributes).toContain('category_id');
+			// Ensure id is NOT there (default attributes should be excluded)
+			expect(result.attributes).not.toContain('id');
+		});
+
+		it('maps root sum(price) with multiple group_by', () => {
+			const queryNode = {
+				functions: [{ fn: 'sum', args: ['price'] }],
+				group_by: ['category_id', 'brand_id']
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.group).toEqual(['category_id', 'brand_id']);
+			expect(result.attributes).toContain('category_id');
+			expect(result.attributes).toContain('brand_id');
+			expect(result.attributes).toContainEqual([
+				{ fn: 'SUM', col: { col: 'price' } },
+				'price_sum'
+			]);
+		});
+	});
+});

package/tests/clauses.test.js

@@ -0,0 +1,171 @@
+// Test utils.
+const {
+	describe,
+	it,
+	expect
+} = require('@jest/globals');
+
+// Parser:
+const { ModelsTree } = require('../lib/middlewares/ql/sequelize/interpreter/ModelsTree');
+const QueryLexer = require('../lib/middlewares/ql/sequelize/interpreter/QueryLexer');
+const traverse = require('../lib/query/traverse');
+
+describe('nodester Clauses', () => {
+	describe('Lexer', () => {
+		it('supports group_by (single)', async () => {
+			const lexer = new QueryLexer('group_by=category_id');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.group_by = 'category_id';
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		it('supports group_by (multiple)', async () => {
+			const lexer = new QueryLexer('group_by=category_id,brand_id');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.group_by = ['category_id', 'brand_id'];
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		it('supports order and order_by', async () => {
+			const lexer = new QueryLexer('order_by=created_at&order=desc');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.order_by = 'created_at';
+			tree.node.order = 'desc';
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+
+		it('supports limit and skip', async () => {
+			const lexer = new QueryLexer('limit=10&skip=20');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.limit = 10;
+			tree.node.skip = 20;
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+		});
+	});
+
+	describe('Traverse', () => {
+		const mockModel = {
+			options: {
+				name: {
+					singular: 'Post',
+					plural: 'Posts'
+				}
+			},
+			associations: {},
+			tableAttributes: {
+				id: {},
+				title: {},
+				price: {},
+				category_id: {},
+				brand_id: {},
+				created_at: {}
+			},
+			sequelize: {
+				col: (col) => ({ col }),
+				fn: (fn, col) => ({ fn, col })
+			}
+		};
+
+		const mockFilter = {
+			model: mockModel,
+			attributes: ['id', 'title', 'category_id', 'brand_id', 'created_at'],
+			functions: ['count', 'sum'],
+			clauses: ['group_by', 'order', 'order_by', 'limit', 'skip'],
+			bounds: {
+				clauses: {
+					limit: { min: 1, max: 100 },
+					skip: { min: 0, max: 1000 }
+				}
+			},
+			statics: { attributes: {}, clauses: {} },
+			includes: {}
+		};
+
+		it('maps group_by to Sequelize group', () => {
+			const queryNode = {
+				group_by: 'category_id'
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.group).toBe('category_id');
+			expect(result.attributes).toContain('category_id');
+		});
+
+		it('maps multiple group_by to Sequelize group array', () => {
+			const queryNode = {
+				group_by: ['category_id', 'brand_id']
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.group).toEqual(['category_id', 'brand_id']);
+			expect(result.attributes).toContain('category_id');
+			expect(result.attributes).toContain('brand_id');
+		});
+
+		it('maps order and order_by to Sequelize order', () => {
+			const queryNode = {
+				order: 'desc',
+				order_by: 'created_at'
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.order).toEqual([['created_at', 'desc']]);
+		});
+
+		it('maps limit and skip to Sequelize limit and offset', () => {
+			const queryNode = {
+				limit: 10,
+				skip: 5
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.limit).toBe(10);
+			expect(result.offset).toBe(5);
+		});
+
+		it('maps group_by with functions (aggregates)', () => {
+			const queryNode = {
+				functions: [{ fn: 'sum', args: ['price'] }],
+				group_by: 'category_id'
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.group).toBe('category_id');
+			expect(result.attributes).toContain('category_id');
+			expect(result.attributes).toContainEqual([
+				{ fn: 'SUM', col: { col: 'price' } },
+				'price_sum'
+			]);
+			// Ensure default attributes are excluded in aggregate+group queries:
+			expect(result.attributes).not.toContain('id');
+			expect(result.attributes).not.toContain('title');
+		});
+
+		it('enforces bounds on limit and skip', () => {
+			const queryNode = {
+				limit: 500, // max is 100
+				skip: -10   // min is 0 (default in _setValueWithBounds)
+			};
+			const result = traverse(queryNode, mockFilter, mockModel);
+
+			expect(result.limit).toBe(100);
+			expect(result.offset).toBeUndefined(); // _value <= 0 returns continue
+		});
+	});
+});

package/tests/dates.test.js

@@ -0,0 +1,104 @@
+// Test utils.
+const {
+	describe,
+	it,
+	expect
+} = require('@jest/globals');
+
+// Component to test:
+const { parseValue } = require('../lib/query/traverse/parsers');
+const { DataTypes } = require('sequelize');
+
+describe('nodester Date Parsing', () => {
+	const mockModel = {
+		tableAttributes: {
+			created_at: {
+				type: { key: DataTypes.DATE.key }
+			},
+			birthday: {
+				type: { key: DataTypes.DATEONLY.key }
+			}
+		}
+	};
+
+	describe('Single value operators (gte, lte, gt, lt)', () => {
+		it('should parse ISO date string', () => {
+			const raw = { gte: ["2026-02-01T12:00:00Z"] };
+			const result = parseValue(raw, 'created_at', mockModel);
+			const op = Object.getOwnPropertySymbols(result)[0];
+
+			expect(result[op]).toBeInstanceOf(Date);
+			expect(result[op].toISOString()).toBe("2026-02-01T12:00:00.000Z");
+		});
+
+		it('should handle space as separator', () => {
+			const raw = { gte: ["2026-02-01 12:00:00"] };
+			const result = parseValue(raw, 'created_at', mockModel);
+			const op = Object.getOwnPropertySymbols(result)[0];
+
+			expect(result[op]).toBeInstanceOf(Date);
+			// Result depends on local timezone if no Z, but we check if it's a valid date
+			expect(isNaN(result[op].getTime())).toBe(false);
+		});
+
+		it('should handle + as separator (URL encoded)', () => {
+			const raw = { lte: ["2026-02-01+12:00:00"] };
+			const result = parseValue(raw, 'created_at', mockModel);
+			const op = Object.getOwnPropertySymbols(result)[0];
+
+			expect(result[op]).toBeInstanceOf(Date);
+			expect(isNaN(result[op].getTime())).toBe(false);
+		});
+
+		it('should unwrap array for gte', () => {
+			const raw = { gte: ["2026-02-01"] };
+			const result = parseValue(raw, 'created_at', mockModel);
+			const op = Object.getOwnPropertySymbols(result)[0];
+
+			expect(Array.isArray(result[op])).toBe(false);
+			expect(result[op]).toBeInstanceOf(Date);
+		});
+	});
+
+	describe('Multi-value operators (in, between)', () => {
+		it('should parse all values in IN operator', () => {
+			const raw = { in: ["2026-02-01", "2026-02-02"] };
+			const result = parseValue(raw, 'created_at', mockModel);
+			const op = Object.getOwnPropertySymbols(result)[0];
+
+			expect(Array.isArray(result[op])).toBe(true);
+			expect(result[op][0]).toBeInstanceOf(Date);
+			expect(result[op][1]).toBeInstanceOf(Date);
+		});
+
+		it('should parse both values in BETWEEN operator', () => {
+			const raw = { between: ["2026-01-01", "2026-01-31"] };
+			const result = parseValue(raw, 'created_at', mockModel);
+			const op = Object.getOwnPropertySymbols(result)[0];
+
+			expect(Array.isArray(result[op])).toBe(true);
+			expect(result[op].length).toBe(2);
+			expect(result[op][0]).toBeInstanceOf(Date);
+		});
+	});
+
+	describe('DATEONLY type', () => {
+		it('should parse simple date string for DATEONLY', () => {
+			const raw = { eq: ["1990-05-15"] };
+			const result = parseValue(raw, 'birthday', mockModel);
+			const op = Object.getOwnPropertySymbols(result)[0];
+
+			expect(result[op]).toBeInstanceOf(Date);
+		});
+	});
+
+	describe('Error handling', () => {
+		it('should throw descriptive error for invalid date', () => {
+			const raw = { gte: ["not-a-date"] };
+
+			expect(() => {
+				parseValue(raw, 'created_at', mockModel);
+			}).toThrow("nodester: Invalid date value 'not-a-date' for attribute 'created_at'");
+		});
+	});
+});

package/tests/nql.test.js

@@ -507,6 +507,32 @@ describe('nodester Query Language', () => {
 
 			expect(result).toMatchObject(expected);
 		});
+
+		test('"Like" with empty argument is a no-op', async () => {
+			// Simulates: GET /api/v3/suggestions?type=COUNTRIES&name=like()
+			// Frontend sends like() when the search field is cleared.
+			const lexer = new QueryLexer('name=like()');
+			const result = await lexer.parse();
+
+			// No where clause should be produced for `name`.
+			const tree = new ModelsTree();
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+			expect(result.where).not.toHaveProperty('name');
+		});
+
+		test('"Like" empty arg mixed with another filter keeps the other filter', async () => {
+			const lexer = new QueryLexer('id=10&name=like()');
+			const result = await lexer.parse();
+
+			const tree = new ModelsTree();
+			tree.node.addWhere({ id: ['10'] });
+			const expected = tree.root.toObject();
+
+			expect(result).toMatchObject(expected);
+			expect(result.where).not.toHaveProperty('name');
+		});
 	});
 
 	describe('operators:in', () => {

package/tests/traverse.test.js

@@ -0,0 +1,468 @@
+/**
+ * nodester
+ * MIT Licensed
+ *
+ * Tests for query/traverse — exercises a realistic 3-model hierarchy:
+ *
+ *   Order  ─HasMany─►  Review
+ *          ─BelongsTo─► Product
+ *
+ * All models are plain mock objects; no DB connection is needed.
+ */
+
+'use strict';
+
+const {
+	describe,
+	it,
+	expect,
+	beforeEach,
+} = require('@jest/globals');
+
+const traverse = require('../lib/query/traverse');
+
+
+// ─── Mock models ────────────────────────────────────────────────────────────
+
+/**
+ * Minimal sequelize-like helper used by traverse for ORDER BY and functions.
+ */
+const mockSequelize = {
+	fn: (fn, col) => ({ fn, col }),
+	col: (col) => ({ col }),
+	literal: (sql) => ({ literal: sql }),
+	random: () => 'RANDOM()',
+};
+
+const ReviewMock = {
+	options: {
+		name: {
+			singular: 'Review',
+			plural: 'Reviews'
+		},
+	},
+	tableAttributes: {
+		id: {
+			type: { key: 'INTEGER' }
+		},
+		order_id: {
+			type: { key: 'INTEGER' }
+		},
+		rating: {
+			type: { key: 'INTEGER' }
+		},
+		body: {
+			type: { key: 'STRING' }
+		},
+		created_at: {
+			type: { key: 'DATE' }
+		},
+	},
+	associations: {},
+	sequelize: mockSequelize,
+};
+
+const ProductMock = {
+	options: {
+		name: { singular: 'Product', plural: 'Products' },
+	},
+	tableAttributes: {
+		id: {
+			type: { key: 'INTEGER' }
+		},
+		title: {
+			type: { key: 'STRING' }
+		},
+		price: {
+			type: { key: 'DECIMAL' }
+		},
+		sku: {
+			type: { key: 'STRING' }
+		},
+	},
+	associations: {},
+	sequelize: mockSequelize,
+};
+
+const OrderMock = {
+	options: {
+		name: { singular: 'Order', plural: 'Orders' },
+	},
+	tableAttributes: {
+		id: {
+			type: { key: 'INTEGER' }
+		},
+		status: {
+			type: { key: 'STRING' }
+		},
+		total: {
+			type: { key: 'DECIMAL' }
+		},
+		product_id: {
+			type: { key: 'INTEGER' }
+		},
+		created_at: {
+			type: { key: 'DATE' }
+		},
+	},
+	associations: {
+		reviews: {
+			as: 'reviews',
+			associationType: 'HasMany',
+			target: ReviewMock,
+			foreignKey: 'order_id',
+			sourceKey: 'id',
+		},
+		product: {
+			as: 'product',
+			associationType: 'BelongsTo',
+			target: ProductMock,
+			foreignKey: 'product_id',
+			sourceKey: 'id',
+		},
+	},
+	sequelize: mockSequelize,
+};
+
+
+// ─── Mock filters ──────────────────────────────────────────────────────────
+
+function makeReviewFilter(overrides = {}) {
+	return {
+		model: ReviewMock,
+		attributes: ['id', 'order_id', 'rating', 'body', 'created_at'],
+		functions: ['avg', 'count'],
+		clauses: ['limit', 'skip', 'order', 'order_by'],
+		bounds: { clauses: {} },
+		statics: { attributes: {}, clauses: {} },
+		includes: {},
+		...overrides,
+	};
+}
+
+function makeProductFilter(overrides = {}) {
+	return {
+		model: ProductMock,
+		attributes: ['id', 'title', 'price', 'sku'],
+		functions: [],
+		clauses: [],
+		bounds: { clauses: {} },
+		statics: { attributes: {}, clauses: {} },
+		includes: {},
+		...overrides,
+	};
+}
+
+function makeOrderFilter(overrides = {}) {
+	return {
+		model: OrderMock,
+		attributes: ['id', 'status', 'total', 'product_id', 'created_at'],
+		functions: ['sum', 'avg', 'count', 'min', 'max'],
+		clauses: ['limit', 'skip', 'order', 'order_by', 'group_by'],
+		bounds: { clauses: { limit: { min: 1, max: 100 } } },
+		statics: { attributes: {}, clauses: {} },
+		includes: {
+			reviews: makeReviewFilter(),
+			product: makeProductFilter(),
+		},
+		...overrides,
+	};
+}
+
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe('traverse', () => {
+
+	describe('attributes', () => {
+
+		it('returns all filter attributes when no query attributes are specified', () => {
+			const result = traverse({ attributes: [], where: {}, includes: [] }, makeOrderFilter());
+
+			expect(result.attributes).toEqual(
+				expect.arrayContaining(['id', 'status', 'total', 'product_id', 'created_at'])
+			);
+		});
+
+		it('returns only the requested attribute subset', () => {
+			const result = traverse(
+				{ attributes: ['id', 'status'], where: {}, includes: [] },
+				makeOrderFilter()
+			);
+
+			expect(result.attributes).toEqual(expect.arrayContaining(['id', 'status']));
+			expect(result.attributes).not.toContain('total');
+		});
+
+		it('throws when a requested attribute is not in the filter whitelist', () => {
+			expect(() =>
+				traverse(
+					{ attributes: ['secret_field'], where: {}, includes: [] },
+					makeOrderFilter()
+				)
+			).toThrow();
+		});
+	});
+
+
+	describe('where', () => {
+
+		it('maps a simple equality condition', () => {
+			const result = traverse(
+				{ attributes: [], where: { status: ['paid'] }, includes: [] },
+				makeOrderFilter()
+			);
+
+			expect(result.where).toMatchObject({ status: ['paid'] });
+		});
+
+		it('maps an equality condition on a string-like field', () => {
+			const result = traverse(
+				{ attributes: [], where: { status: { not: ['cancelled'] } }, includes: [] },
+				makeOrderFilter()
+			);
+
+			// traverse produces a Sequelize Op; just verify the key is present:
+			expect(result.where).toHaveProperty('status');
+		});
+
+		it('skips where entirely when no conditions are set', () => {
+			const result = traverse(
+				{ attributes: [], where: {}, includes: [] },
+				makeOrderFilter()
+			);
+
+			// traverse removes the where key when empty:
+			expect(result).not.toHaveProperty('where');
+		});
+
+		it('applies statics.attributes on top of query where', () => {
+			const filter = makeOrderFilter({
+				statics: { attributes: { status: 'shipped' }, clauses: {} },
+			});
+
+			const result = traverse(
+				{ attributes: [], where: {}, includes: [] },
+				filter
+			);
+
+			expect(result.where).toHaveProperty('status');
+		});
+	});
+
+
+	describe('clauses', () => {
+
+		it('applies limit within bounds', () => {
+			const result = traverse(
+				{ attributes: [], where: {}, includes: [], limit: 10 },
+				makeOrderFilter()
+			);
+
+			expect(result.limit).toBe(10);
+		});
+
+		it('clamps limit to max bound', () => {
+			const result = traverse(
+				{ attributes: [], where: {}, includes: [], limit: 9999 },
+				makeOrderFilter()
+			);
+
+			expect(result.limit).toBe(100); // max is 100
+		});
+
+		it('applies skip (offset)', () => {
+			const result = traverse(
+				{ attributes: [], where: {}, includes: [], skip: 20 },
+				makeOrderFilter()
+			);
+
+			expect(result.offset).toBe(20);
+		});
+
+		it('applies order asc/desc', () => {
+			const result = traverse(
+				{ attributes: [], where: {}, includes: [], order: 'desc', order_by: 'created_at' },
+				makeOrderFilter()
+			);
+
+			expect(result.order).toEqual([['created_at', 'desc']]);
+		});
+
+		it('applies random order', () => {
+			const result = traverse(
+				{ attributes: [], where: {}, includes: [], order: 'rand' },
+				makeOrderFilter()
+			);
+
+			expect(result.order).toBe('RANDOM()');
+		});
+	});
+
+
+	describe('functions', () => {
+
+		it('allows a whitelisted function (sum)', () => {
+			const result = traverse(
+				{ functions: [{ fn: 'sum', args: ['total'] }], attributes: [], where: {}, includes: [] },
+				makeOrderFilter()
+			);
+
+			expect(result.attributes).toContainEqual([
+				{ fn: 'SUM', col: { col: 'total' } },
+				'total_sum',
+			]);
+		});
+
+		it('throws for a function not in the whitelist', () => {
+			expect(() =>
+				traverse(
+					{ functions: [{ fn: 'median', args: ['total'] }], attributes: [], where: {}, includes: [] },
+					makeOrderFilter()
+				)
+			).toThrow(/not allowed/);
+		});
+
+		it('allows functions defined via array in Filter', () => {
+			const filter = makeOrderFilter({
+				functions: ['count', 'avg'],
+			});
+
+			// count and avg should be allowed, sum should not:
+			expect(() =>
+				traverse(
+					{ functions: [{ fn: 'count', args: ['reviews'] }], attributes: [], where: {}, includes: [] },
+					filter
+				)
+			).not.toThrow();
+
+			expect(() =>
+				traverse(
+					{ functions: [{ fn: 'sum', args: ['total'] }], attributes: [], where: {}, includes: [] },
+					filter
+				)
+			).toThrow(/not allowed/);
+		});
+	});
+
+
+	describe('includes', () => {
+
+		it('includes reviews when requested', () => {
+			const result = traverse(
+				{
+					attributes: [],
+					where: {},
+					includes: [
+						{ model: 'reviews', attributes: [], where: {}, includes: [] }
+					]
+				},
+				makeOrderFilter()
+			);
+
+			const reviewInclude = result.include.find(i => i.association === 'reviews');
+			expect(reviewInclude).toBeDefined();
+		});
+
+		it('includes product when requested', () => {
+			const result = traverse(
+				{
+					attributes: [],
+					where: {},
+					includes: [
+						{ model: 'product', attributes: [], where: {}, includes: [] }
+					]
+				},
+				makeOrderFilter()
+			);
+
+			const productInclude = result.include.find(i => i.association === 'product');
+			expect(productInclude).toBeDefined();
+		});
+
+		it('applies sub-filter attributes on the included model', () => {
+			const result = traverse(
+				{
+					attributes: [],
+					where: {},
+					includes: [
+						{ model: 'product', attributes: ['id', 'title'], where: {}, includes: [] }
+					]
+				},
+				makeOrderFilter()
+			);
+
+			const productInclude = result.include.find(i => i.association === 'product');
+			expect(productInclude.attributes).toEqual(expect.arrayContaining(['id', 'title']));
+			expect(productInclude.attributes).not.toContain('sku');
+		});
+
+		it('applies where clause on an included model', () => {
+			const result = traverse(
+				{
+					attributes: [],
+					where: {},
+					includes: [
+						{
+							model: 'reviews',
+							attributes: [],
+							where: { rating: ['5'] },
+							includes: []
+						}
+					]
+				},
+				makeOrderFilter()
+			);
+
+			const reviewInclude = result.include.find(i => i.association === 'reviews');
+			expect(reviewInclude.where).toHaveProperty('rating');
+		});
+
+		it('throws when requesting an include not in the filter whitelist', () => {
+			expect(() =>
+				traverse(
+					{
+						attributes: [],
+						where: {},
+						includes: [
+							{ model: 'unknown_assoc', attributes: [], where: {}, includes: [] }
+						]
+					},
+					makeOrderFilter()
+				)
+			).toThrow();
+		});
+	});
+
+
+	describe('Filter constructor — functions validation', () => {
+		const Filter = require('../lib/structures/Filter');
+
+		// A bare-minimum mock model to satisfy Filter's isModel() check.
+		const bareModel = {
+			tableName: 'orders',
+			_schema: {},
+			options: { name: { singular: 'Order', plural: 'Orders' } },
+			tableAttributes: { id: {} },
+			associations: {},
+			sequelize: mockSequelize,
+		};
+
+		it('accepts an array for functions', () => {
+			expect(() => new Filter(bareModel, { functions: ['sum', 'avg'] })).not.toThrow();
+		});
+
+		it('throws a TypeError when functions is a plain object', () => {
+			expect(() => new Filter(bareModel, { functions: { sum: true } })).toThrow(TypeError);
+		});
+
+		it('throws a TypeError when functions is a string', () => {
+			expect(() => new Filter(bareModel, { functions: 'sum' })).toThrow(TypeError);
+		});
+
+		it('defaults functions to an empty array when not provided', () => {
+			const f = new Filter(bareModel, {});
+			expect(f.functions).toEqual([]);
+		});
+	});
+});