🐛 Support nested populate via dot notation

Author: skerit

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.4.1 (WIP)
+
+* Support nested populate via dot notation (e.g., `populate('Project.Client')`) - falls back to N+1 when `$lookup` can't handle nested associations
+
 ## 1.4.0 (2026-01-21)
 
 * Add permission checks to Linkup routes

lib/app/helper_datasource/00-nosql_datasource.js

@@ -706,7 +706,7 @@ function addLookupForAssociation(aggregate, assoc, assoc_model, options = {}) {
  *
  * @author   Jelle De Loecker <[email protected]>
  * @since    1.1.0
- * @version  1.4.0
+ * @version  1.4.1
  *
  * @param    {Criteria}   criteria   The criteria to convert
  * @param    {Group}      group      The current group
@@ -1210,6 +1210,14 @@ function convertCriteriaGroupToConditions(criteria, group, config, context) {
 				}
 			}
 
+			// Skip $lookup when there are nested associations (e.g., 'Parent.Parent')
+			// because $lookup only handles one level - let the N+1 code path handle nested
+			let assoc_select = associations_to_select[alias];
+			if (assoc_select?.associations && Object.keys(assoc_select.associations).length > 0) {
+				// This association has nested associations, skip $lookup
+				continue;
+			}
+
 			// Only create aggregate when we actually need it
 			getAggregate();
 
@@ -1228,8 +1236,6 @@ function convertCriteriaGroupToConditions(criteria, group, config, context) {
 			};
 
 			// Add projection if specific fields are selected (not just the whole association)
-			let assoc_select = associations_to_select[alias];
-
 			if (assoc_select && assoc_select.fields && assoc_select.fields.length > 0) {
 				let projection = { _id: 1 };  // Always include _id
 				for (let field of assoc_select.fields) {

lib/app/helper_model/10-model_criteria.js

@@ -398,7 +398,7 @@ Criteria.setMethod(function getAssociationConfiguration(alias) {
  *
  * @author   Jelle De Loecker <[email protected]>
  * @since    1.1.0
- * @version  1.4.0
+ * @version  1.4.1
  *
  * @param    {string}   name
  * @param    {Object}   item
@@ -426,14 +426,20 @@ Criteria.setMethod(function getCriteriaForAssociation(name, item) {
 	    options = this.options;
 
 	// For self-referencing associations (e.g., Person.Parent → Person),
-	// only allow if we have recursive depth remaining.
+	// only allow if we have recursive depth remaining OR explicit nested associations.
 	// This prevents infinite loops while still supporting hierarchical data.
 	if (assoc_model.name == options.init_model) {
 		// Check if we have recursive depth available
 		let recursive = options.recursive;
 
-		if (!Number.isSafeInteger(recursive) || recursive <= 0) {
-			// No recursive depth - block to prevent potential infinite loops
+		// Also check for explicit nested associations via dot notation (e.g., 'Parent.Parent')
+		// If there's an explicit Select for this association with nested associations,
+		// we should allow it even without recursive depth
+		let has_explicit_nested = options.select?.associations?.[name]?.associations;
+		let has_nested_associations = has_explicit_nested && Object.keys(has_explicit_nested).length > 0;
+
+		if (!has_nested_associations && (!Number.isSafeInteger(recursive) || recursive <= 0)) {
+			// No recursive depth and no explicit nested associations - block to prevent infinite loops
 			return;
 		}
 	}
@@ -985,20 +991,44 @@ Select.setMethod(Blast.checksumSymbol, function toChecksum() {
 	return result;
 });
 
+/**
+ * Get the model to use for association lookups.
+ * For nested Selects (e.g., when populating 'Project.Client'),
+ * this returns the associated model, not the criteria's root model.
+ *
+ * @author   Jelle De Loecker <[email protected]>
+ * @since    1.4.1
+ * @version  1.4.1
+ *
+ * @return   {Model}
+ */
+Select.setMethod(function getModelForAssociations() {
+
+	// If this Select has an associated model set (for nested associations),
+	// use that instead of the criteria's model
+	if (this.associated_model) {
+		return this.associated_model;
+	}
+
+	return this.criteria?.model;
+});
+
 /**
  * Add an association
  *
  * @author   Jelle De Loecker <[email protected]>
  * @since    1.1.0
- * @version  1.3.4
+ * @version  1.4.1
  *
  * @param    {string}   name
  *
  * @return   {Select}   This creates a new Select instance
  */
 Select.setMethod(function addAssociation(name) {
 
-	if (!this.criteria?.model) {
+	let model = this.getModelForAssociations();
+
+	if (!model) {
 		throw new Error('Unable to select an association: this Criteria has no model info');
 	}
 
@@ -1032,14 +1062,23 @@ Select.setMethod(function addAssociation(name) {
 
 	// Get the association data
 	try {
-		let info = this.criteria.model.getAssociation(name);
+		let info = model.getAssociation(name);
 
 		if (info) {
 			// Make sure the localkey is added to the resultset
 			this.requireFieldForQuery(info.options.localKey);
+
+			// Store the associated model on the nested Select so it can
+			// resolve its own nested associations correctly
+			// (e.g., for 'Project.Client', the Project Select needs to know
+			// to look up 'Client' on the Project model, not the root model)
+			let associated_model = this.getModel(info.modelName);
+			if (associated_model) {
+				this.associations[name].associated_model = associated_model;
+			}
 		}
 	} catch (err) {
-		console.warn('Failed to find "' + name + '" association for ' + this.criteria.model.model_name);
+		console.warn('Failed to find "' + name + '" association for ' + model.model_name);
 	}
 
 	return this.associations[name];

lib/app/helper_model/model.js

@@ -1362,7 +1362,7 @@ Model.setMethod(function afterFindCount(options, records, callback) {
  *
  * @author   Jelle De Loecker <[email protected]>
  * @since    0.1.0
- * @version  1.1.5
+ * @version  1.4.1
  *
  * @param    {Criteria}  criteria
  * @param    {Object}    item
@@ -1404,13 +1404,16 @@ Model.setMethod(function addAssociatedDataToRecord(criteria, item, callback) {
 					if (Object.isPlainObject(item[alias])) {
 						let assoc_crit = criteria.getCriteriaForAssociation(alias, item);
 
-						if (!(item[alias] instanceof assoc_crit.model.constructor.Document)) {
+						// assoc_crit can be undefined for self-referencing without recursive depth
+						if (assoc_crit && !(item[alias] instanceof assoc_crit.model.constructor.Document)) {
 							item[alias] = assoc_crit.model.createDocument(item[alias]);
 						}
 					}
 				} else if (Array.isArray(item[alias])) {
 					let assoc_crit = criteria.getCriteriaForAssociation(alias, item);
-					item[alias] = assoc_crit.model.createDocumentList(item[alias]);
+					if (assoc_crit) {
+						item[alias] = assoc_crit.model.createDocumentList(item[alias]);
+					}
 				}
 			}
 

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "alchemymvc",
 	"description": "MVC framework for Node.js",
-	"version": "1.4.0",
+	"version": "1.4.1-alpha",
 	"author": "Jelle De Loecker <[email protected]>",
 	"keywords": [
 		"alchemy",

test/09-datasource.js

@@ -579,6 +579,29 @@ describe('FieldConfig', function() {
 			}
 			// If no pipeline at all, that's also acceptable (means no $lookup)
 		});
+
+		it('should populate nested associations using dot notation (Parent.Parent)', async function() {
+			// This tests that nested populate paths like 'Project.Client' work correctly
+			// by using the self-referencing Person model as a proxy
+			let Person = Model.get('Person');
+			let criteria = Person.find();
+			criteria.where('firstname').equals('ChildPerson');
+			
+			// Use dot notation to populate Parent and Parent's Parent
+			criteria.populate('Parent.Parent');
+
+			let records = await Person.find('all', criteria);
+
+			assert.strictEqual(records.length, 1, 'Should find ChildPerson');
+			assert.strictEqual(!!records[0].Parent, true, 'Parent should be populated');
+			assert.strictEqual(records[0].Parent.firstname, 'ParentPerson', 'Parent should be ParentPerson');
+			
+			// The key test - Parent.Parent should be populated via dot notation
+			assert.strictEqual(!!records[0].Parent.Parent, true, 
+				'Parent.Parent (grandparent) should be populated via dot notation');
+			assert.strictEqual(records[0].Parent.Parent.firstname, 'Grandparent', 
+				'Grandparent should be correct');
+		});
 	});
 
 	describe('Nested OR/AND groups with associations', function() {