nodester 0.7.12 → 0.7.14

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

@@ -160,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:

package/lib/models/mixins.js

@@ -2,13 +2,13 @@
  * nodester
  * MIT Licensed
  */
- 
+
 'use strict';
 
 /**
  *	CRUD mixins for any model:
  */
- 
+
 // Utils:
 const {
 	modelHasAssociations,
@@ -59,7 +59,7 @@ function _implementsCRUD(modelDefinition) {
 
 /** Main mixinis: */
 async function _createWithIncludes(
-	data={}
+	data = {}
 ) {
 	try {
 		const instance = await this.create(data);
@@ -77,7 +77,7 @@ async function _createWithIncludes(
 		if (modelHasAssociations(this)) {
 			const allModelAssociations = Object.entries(this.associations);
 
-			for (const [ associationName, associationDefinition ] of allModelAssociations) {
+			for (const [associationName, associationDefinition] of allModelAssociations) {
 
 				// If data of this association is present:
 				if (!!data[associationName]) {
@@ -85,10 +85,11 @@ async function _createWithIncludes(
 					const {
 						associatedModel,
 						foreignKey,
-						associationType
+						associationType,
+						accessors
 					} = getModelAssociationProps(associationDefinition);
 
-					// If association type is HasMany or HasOne (We don't work with any other):
+					// If association type is HasMany or HasOne:
 					if (associationType === 'HasMany' || associationType === 'HasOne') {
 
 						// Process current instance.
@@ -99,11 +100,35 @@ async function _createWithIncludes(
 							parentForeignKey: foreignKey,
 						});
 
-						fullInstanceData[associationName] =_unwrapUpdateOrCreateOrDeleteOperationsResults(
+						fullInstanceData[associationName] = _unwrapUpdateOrCreateOrDeleteOperationsResults(
 							operationsResults,
 							associationType
 						);
 					}
+					// BelongsToMany: link existing records via junction table.
+					else if (associationType === 'BelongsToMany') {
+						const associationData = Array.isArray(data[associationName])
+							? data[associationName]
+							: [data[associationName]];
+
+						const pkField = associatedModel.primaryKeyField;
+						const ids = [];
+
+						for (const item of associationData) {
+							const exists = await associatedModel.findByPk(item[pkField]);
+							if (!exists) {
+								const err = new Error(
+									`Before you can associate ${associationName} with ${this.name}, ${associationName} must be created separately.`
+								);
+								err.status = 406;
+								throw err;
+							}
+							ids.push(item[pkField]);
+						}
+
+						await instance[accessors.set](ids);
+						fullInstanceData[associationName] = associationData;
+					}
 
 					fullInstanceData[associationName] = fullInstanceData[associationName] ?? data[associationName];
 				}
@@ -114,16 +139,16 @@ async function _createWithIncludes(
 		// Variable, that is used by _updateById,
 		// but we will also put it here to make API consistent.
 		const isNewRecord = true;
-		return Promise.resolve([ isNewRecord, fullInstanceData ]);
+		return Promise.resolve([isNewRecord, fullInstanceData]);
 	}
-	catch(error) {
+	catch (error) {
 		return Promise.reject(error);
 	}
 }
 
 function _findById(
-	id=null,
-	opts={}
+	id = null,
+	opts = {}
 ) {
 	const { query } = opts;
 
@@ -154,7 +179,7 @@ function _findById(
 	return this.findOne(_query);
 }
 
-function _findMany(opts={}) {
+function _findMany(opts = {}) {
 	const { query } = opts;
 
 	let _query = {};
@@ -189,7 +214,7 @@ function _findMany(opts={}) {
 async function _updateOne(
 	where,
 	data,
-	opts={}
+	opts = {}
 ) {
 	try {
 		const include = opts.include ?? [];
@@ -226,11 +251,11 @@ async function _updateOne(
 
 			const associationDefinition = this.associations[association];
 			const includeData = data[association];
-			
+
 			const {
 				associatedModel,
 				associationType,
-				
+
 				foreignKey,
 				sourceKey
 			} = getModelAssociationProps(associationDefinition);
@@ -242,13 +267,12 @@ async function _updateOne(
 
 			const pkField = associatedModel.primaryKeyField;
 
-			// If association type is HasMany or HasOne (We don't work with any other):
-			switch(associationType) {
+			switch (associationType) {
 				case 'HasMany': {
 					// Handle empty array (remove all old associations):
 					if (Array.isArray(includeData) && includeData.length === 0) {
 						const where = {
-							[foreignKey]: instance.id 
+							[foreignKey]: instance.id
 						}
 						await associatedModel.destroy({ where });
 						fullInstanceData[association] = [];
@@ -260,10 +284,10 @@ async function _updateOne(
 							[pkField]: singleData[pkField]
 						}
 						return associatedModel.updateOne(
-										where,
-										singleData,
-										associationUpdateOpts
-									)
+							where,
+							singleData,
+							associationUpdateOpts
+						)
 					});
 					fullInstanceData[association] = await Promise.all(promises);
 
@@ -285,14 +309,39 @@ async function _updateOne(
 							[pkField]: includeData[pkField]
 						}
 						fullInstanceData[association] = await associatedModel.updateOne(
-																							where,
-																							includeData,
-																							associationUpdateOpts
-																						);
+							where,
+							includeData,
+							associationUpdateOpts
+						);
 					}
 					continue;
 				}
 
+				case 'BelongsToMany': {
+					const associationItems = Array.isArray(includeData) ? includeData : [includeData];
+					const ids = [];
+
+					for (const item of associationItems) {
+						const exists = await associatedModel.findByPk(item[pkField]);
+						if (!exists) {
+							const err = new Error(
+								`Before you can associate ${association} with ${this.name}, ${association} must be created separately.`
+							);
+							err.status = 406;
+							throw err;
+						}
+						ids.push(item[pkField]);
+					}
+
+					// Replaces the full set of associations via the junction table.
+					// Sending an empty array removes all associations.
+					const { accessors: btmAccessors } = getModelAssociationProps(associationDefinition);
+					await instance[btmAccessors.set](ids);
+					fullInstanceData[association] = associationItems;
+
+					continue;
+				}
+
 				default:
 					continue;
 			}
@@ -309,15 +358,15 @@ async function _updateOne(
 			...fullInstanceData
 		});
 	}
-	catch(error) {
+	catch (error) {
 		return Promise.reject(error);
 	}
 }
 
 async function _updateById(
-	id=null,
-	data={},
-	opts={}
+	id = null,
+	data = {},
+	opts = {}
 ) {
 	const where = { id };
 	return this.updateOne(
@@ -328,7 +377,7 @@ async function _updateById(
 }
 
 
-function _deleteOne(query={}) {
+function _deleteOne(query = {}) {
 	const _query = {
 		...query,
 		limit: 1
@@ -337,7 +386,7 @@ function _deleteOne(query={}) {
 }
 
 function _deleteById(
-	id=null
+	id = null
 ) {
 	const query = {
 		where: { id }
@@ -378,7 +427,7 @@ async function _updateOrCreateOrDelete(
 			operation,
 		});
 	}
-	catch(error) {
+	catch (error) {
 		return Promise.reject(error);
 	}
 }
@@ -398,7 +447,7 @@ async function _updateOrCreateOrDeleteBasedOnAssociationData({
 		// If single instance of associated model:
 		if (isSingleInstance) {
 			const operationResult = await _updateOrCreateOrDelete(
-				associatedModel, 
+				associatedModel,
 				compileModelAssociationData({
 					dataOfAssociation,
 					parentForeignKey,
@@ -406,14 +455,14 @@ async function _updateOrCreateOrDeleteBasedOnAssociationData({
 				})
 			);
 
-			result = [ operationResult ];
+			result = [operationResult];
 		}
 		// If multiple instances of associated model:
 		else {
 			// Update or create each:
 			const promises = dataOfAssociation.map(
 				(data) => _updateOrCreateOrDelete(
-					associatedModel, 
+					associatedModel,
 					compileModelAssociationData({
 						dataOfAssociation: data,
 						parentForeignKey: parentForeignKey,
@@ -428,7 +477,7 @@ async function _updateOrCreateOrDeleteBasedOnAssociationData({
 
 		return Promise.resolve(result);
 	}
-	catch(error) {
+	catch (error) {
 		return Promise.reject(error);
 	}
 }
@@ -439,7 +488,7 @@ function _unwrapUpdateOrCreateOrDeleteOperationsResults(
 ) {
 	// If instance was not deleted, add it to final array.
 	const result = operationsResults.filter(({ operation }) => operation !== 'deleted')
-																	.map(({ newInstance }) => newInstance[1]);
+		.map(({ newInstance }) => newInstance[1]);
 
 	// If this association referenced only certain record,
 	// unwrap "result" array and send first element:

package/lib/query/traverse/index.js

@@ -148,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;

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.12",
+  "version": "0.7.14",
   "description": "A versatile REST framework for Node.js",
   "directories": {
     "docs": "docs",

package/tests/aggregates.test.js

@@ -135,13 +135,7 @@ describe('nodester Aggregates', () => {
 		const mockFilter = {
 			model: mockModel,
 			attributes: ['id', 'price', 'score', 'age', 'category_id', 'brand_id'],
-			functions: {
-				count: { target: 'comments' }, // Just to satisfy ensure calls if any
-				sum: true,
-				avg: true,
-				min: true,
-				max: true
-			},
+			functions: ['count', 'sum', 'avg', 'min', 'max'],
 			clauses: ['group_by'],
 			bounds: { clauses: {} },
 			statics: { attributes: {}, clauses: {} },
@@ -149,7 +143,7 @@ describe('nodester Aggregates', () => {
 				comments: {
 					model: { options: { name: { singular: 'Comment', plural: 'Comments' } }, tableAttributes: { id: {} } },
 					attributes: ['id'],
-					functions: { count: true, sum: true },
+					functions: ['count', 'sum'],
 					clauses: [],
 					bounds: { clauses: {} },
 					statics: { attributes: {}, clauses: {} },

package/tests/clauses.test.js

@@ -85,10 +85,7 @@ describe('nodester Clauses', () => {
 		const mockFilter = {
 			model: mockModel,
 			attributes: ['id', 'title', 'category_id', 'brand_id', 'created_at'],
-			functions: {
-				count: true,
-				sum: true
-			},
+			functions: ['count', 'sum'],
 			clauses: ['group_by', 'order', 'order_by', 'limit', 'skip'],
 			bounds: {
 				clauses: {

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([]);
+		});
+	});
+});