feat: add belongs-to-many pivot models

Author: elpete

models/BaseEntity.cfc

@@ -2602,10 +2602,14 @@ component accessors="true" {
 
 		var relationshipName = variables._str.slice( arguments.missingMethodName, 4 );
 
-		if ( !hasRelationship( relationshipName ) ) {
+		if ( !hasRelationship( relationshipName ) && !isRelationshipLoaded( relationshipName ) ) {
 			return;
 		}
 
+		if ( isRelationshipLoaded( relationshipName ) ) {
+			return retrieveRelationship( relationshipName );
+		}
+
 		if ( !isRelationshipLoaded( relationshipName ) && variables._preventLazyLoading ) {
 			variables._lazyLoadingViolationCallback( this, relationshipName );
 		}

models/QuickBuilder.cfc

@@ -75,6 +75,11 @@ component accessors="true" transientCache="false" {
 	property name="_asMemento" default="false";
 	property name="_asMementoSettings";
 
+	/**
+	 * Callbacks applied to each hydrated entity before return transformations.
+	 */
+	property name="_entityTransformers";
+
 	/**
 	 * Used to quickly identify QueryBuilder instances
 	 * instead of resorting to `isInstanceOf` which is slow.
@@ -94,6 +99,7 @@ component accessors="true" transientCache="false" {
 		variables._asMemento                = false;
 		variables._asQuery                  = false;
 		variables._withAliases              = false;
+		variables._entityTransformers       = [];
 		param variables._preventLazyLoading = false;
 		if ( !variables.keyExists( "_lazyLoadingViolationCallback" ) || isNull( variables._lazyLoadingViolationCallback ) ) {
 			variables._lazyLoadingViolationCallback = ( entity, relationName ) => {
@@ -109,6 +115,18 @@ component accessors="true" transientCache="false" {
 		return this;
 	}
 
+	/**
+	 * Adds a callback that transforms each hydrated entity before it is returned.
+	 *
+	 * @transformer  The callback accepting and returning an entity.
+	 *
+	 * @return       quick.models.QuickBuilder
+	 */
+	public QuickBuilder function addEntityTransformer( required any transformer ) {
+		variables._entityTransformers.append( arguments.transformer );
+		return this;
+	}
+
 	function onDIComplete() {
 		variables.qb.setQuickBuilder( this );
 		variables.qb.setColumnFormatter( function( column ) {
@@ -1489,6 +1507,16 @@ component accessors="true" transientCache="false" {
 	 * @return any
 	 */
 	private any function handleTransformations( entity ) {
+		if ( !variables._asQuery ) {
+			if ( isArray( arguments.entity ) ) {
+				arguments.entity = arguments.entity.map( function( item ) {
+					return applyEntityTransformers( arguments.item );
+				} );
+			} else if ( !isNull( arguments.entity ) ) {
+				arguments.entity = applyEntityTransformers( arguments.entity );
+			}
+		}
+
 		if ( !variables._asMemento ) {
 			return arguments.entity;
 		}
@@ -1502,6 +1530,15 @@ component accessors="true" transientCache="false" {
 		} );
 	}
 
+	/**
+	 * Applies all configured entity transformers to one hydrated entity.
+	 */
+	private any function applyEntityTransformers( required any entity ) {
+		return variables._entityTransformers.reduce( function( transformed, transformer ) {
+			return arguments.transformer( arguments.transformed );
+		}, arguments.entity );
+	}
+
 	/**
 	 * Activates the global scopes while checking for excluded global scopes.
 	 *
@@ -1741,6 +1778,7 @@ component accessors="true" transientCache="false" {
 		newBuilder.set_withAliases( this.get_withAliases() );
 		newBuilder.set_asMemento( this.get_asMemento() );
 		newBuilder.set_asMementoSettings( this.get_asMementoSettings() );
+		newBuilder.set_entityTransformers( this.get_entityTransformers() );
 		return newBuilder;
 	}