feat(EagerLoading): Give entities a way to automatically eager load certain relationships

Using the `variables._with` property on an entity, you can specify
relationships to always eager load.  Be careful with this as it is
easy to over fetch data this way.

Author: elpete

models/BaseEntity.cfc

@@ -65,6 +65,12 @@ component accessors="true" {
 	 */
 	property name="_table" persistent="false";
 
+	/**
+	 * An array of relationships to automatically eager load.
+	 * Use with caution as it is easy to over fetch using this.
+	 */
+	property name="_with" persistent="false";
+
 	/**
 	 * A struct of query options for query executions.
 	 */
@@ -245,7 +251,7 @@ component accessors="true" {
 		param variables._data                     = {};
 		param variables._relationshipsData        = {};
 		param variables._relationshipsLoaded      = {};
-		param variables._eagerLoad                = [];
+		param variables._with                     = [];
 		variables._withoutRelationshipConstraints = createObject( "java", "java.util.HashSet" ).init();
 		variables._applyingGlobalScopes           = false;
 		variables._globalScopesApplied            = false;
@@ -1024,7 +1030,6 @@ component accessors="true" {
 		}
 		variables._relationshipsData   = {};
 		variables._relationshipsLoaded = {};
-		variables._eagerLoad           = [];
 		variables._loaded              = arguments.toNew ? false : variables._loaded;
 
 		return this;
@@ -2104,7 +2109,7 @@ component accessors="true" {
 			return variables._wirebox.getInstance(
 				name          = "PolymorphicBelongsTo@quick",
 				initArguments = {
-					"related"            : this.set_EagerLoad( [] ).resetQuery(),
+					"related"            : this.resetQuery(),
 					"relationName"       : relationName,
 					"relationMethodName" : arguments.relationMethodName,
 					"parent"             : this,
@@ -2241,7 +2246,8 @@ component accessors="true" {
 			.set_lazyLoadingViolationCallback( variables._lazyLoadingViolationCallback )
 			.mergeDefaultOptions( variables._queryOptions )
 			.from( tableName() )
-			.addSelect( retrieveQualifiedColumns() );
+			.addSelect( retrieveQualifiedColumns() )
+			.with( variables._with );
 
 		if ( variables._meta.originalMetadata.keyExists( "grammar" ) ) {
 			newBuilder.setGrammar( variables._wirebox.getInstance( variables._meta.originalMetadata.grammar ) );

models/Relationships/PolymorphicBelongsTo.cfc

@@ -169,7 +169,6 @@ component extends="quick.models.Relationships.BelongsTo" accessors="true" {
 		}
 
 		return arguments.instance
-			.with( variables.related.get_eagerLoad() )
 			.when( arguments.asQuery, function( qb ) {
 				qb.asQuery( withAliases );
 			} )

tests/resources/app/models/EagerLoadedPost.cfc

@@ -0,0 +1,5 @@
+component extends="Post" accessors="true" {
+
+	variables._with = [ "comments" ];
+
+}

tests/specs/integration/BaseEntity/Relationships/EagerLoadingSpec.cfc

@@ -590,6 +590,25 @@ component extends="tests.resources.ModuleIntegrationSpec" {
 					);
 				} );
 			} );
+
+			describe( "automatic eager loading", () => {
+				it( "will automatically eager load specified relationships", () => {
+					var posts = getInstance( "EagerLoadedPost" ).preventLazyLoading().get();
+					expect( posts ).toBeArray();
+					expect( posts ).toHaveLength( 4, "4 posts should have been loaded" );
+					for ( var post in posts ) {
+						expect( () => {
+							post.getComments();
+						} ).notToThrow( type = "QuickLazyLoadingException" );
+					}
+					if ( arrayLen( variables.queries ) != 2 ) {
+						expect( variables.queries ).toHaveLength(
+							2,
+							"Only two queries should have been executed. #arrayLen( variables.queries )# were instead."
+						);
+					}
+				} );
+			} );
 		} );
 	}