feat: create belongs-to-many related entities

models/Relationships/BelongsToMany.cfc

@@ -320,15 +320,41 @@ component
 		} );
 	}
 
+	/**
+	 * Creates a new related entity and attaches it to the parent through the pivot table.
+	 *
+	 * @attributes                   Attributes for the related entity.
+	 * @pivotAttributes              Additional attributes for the pivot row.
+	 * @ignoreNonExistentAttributes  Whether to ignore attributes not defined on the related entity.
+	 * @options                      Options passed to the related entity save query.
+	 *
+	 * @return  quick.models.BaseEntity
+	 */
+	public any function create(
+		struct attributes                   = {},
+		struct pivotAttributes              = {},
+		boolean ignoreNonExistentAttributes = false,
+		struct options                      = {}
+	) {
+		var entity = variables.related.create(
+			arguments.attributes,
+			arguments.ignoreNonExistentAttributes,
+			arguments.options
+		);
+		attach( entity, arguments.pivotAttributes );
+		return entity;
+	}
+
 	/**
 	 * Associates one or more ids of the related entity to the parent entity.
 	 *
-	 * @id      The id or array of ids of the related entity.
+	 * @id               The id or array of ids of the related entity.
+	 * @pivotAttributes  Additional attributes for each inserted pivot row.
 	 *
 	 * @return  quick.models.BaseEntity
 	 */
-	public any function attach( required any id ) {
-		variables.newPivotStatement().insert( parseIdsForInsert( arguments.id ) );
+	public any function attach( required any id, struct pivotAttributes = {} ) {
+		variables.newPivotStatement().insert( parseIdsForInsert( arguments.id, arguments.pivotAttributes ) );
 		return variables.parent;
 	}
 
@@ -430,7 +456,8 @@ component
 	 * Normalizes a single id or entity or an array of ids and/or entities
 	 * in to an array of ids.
 	 *
-	 * @value        An id, entity, or combination of either in an array.
+	 * @value            An id, entity, or combination of either in an array.
+	 * @pivotAttributes  Additional attributes for each inserted pivot row.
 	 *
 	 * @doc_generic  any
 	 * @return       [any]
@@ -455,10 +482,11 @@ component
 	 * @doc_generic  any,any
 	 * @return       [{any: any}]
 	 */
-	public array function parseIdsForInsert( required any value ) {
+	public array function parseIdsForInsert( required any value, struct pivotAttributes = {} ) {
 		var foreignPivotKeyValues = variables.parentKeys.map( function( parentKey ) {
 			return variables.parent.retrieveAttribute( parentKey );
 		} );
+		var additionalPivotAttributes = arguments.pivotAttributes;
 		return arrayWrap( arguments.value ).map( function( values ) {
 			// If the value is not a simple value, we will assume
 			// it is an entity and return its key value.
@@ -485,6 +513,7 @@ component
 					insertRecord[ relatedPivotKey ] = val;
 				}
 			);
+			insertRecord.append( additionalPivotAttributes, false );
 			return insertRecord;
 		} );
 	}

tests/resources/database/migrations/2020_08_11_102625_create_my_posts_tags_table.cfc

@@ -1,10 +1,11 @@
 component {
 
 	function up( schema, qb ) {
-		schema.create( "my_posts_tags", function( t ) {
-			t.unsignedInteger( "custom_post_pk" );
-			t.unsignedInteger( "tag_id" );
-			t.primaryKey( [ "custom_post_pk", "tag_id" ] );
+			schema.create( "my_posts_tags", function( t ) {
+				t.unsignedInteger( "custom_post_pk" );
+				t.unsignedInteger( "tag_id" );
+				t.string( "context" ).nullable();
+				t.primaryKey( [ "custom_post_pk", "tag_id" ] );
 		} );
 
 		qb.table( "my_posts_tags" )

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

@@ -19,6 +19,26 @@ component extends="tests.resources.ModuleIntegrationSpec" {
 				expect( posts ).toBeArray();
 				expect( posts ).toHaveLength( 2 );
 			} );
+
+			it( "creates and attaches a related entity", function() {
+				var post = getInstance( "Post" ).findOrFail( 1245 );
+				var tag  = post.tags().create( { "name" : "testing" }, { "context" : "created through relationship" } );
+
+				expect( tag ).toBeInstanceOf( "Tag" );
+				expect( tag.isLoaded() ).toBeTrue();
+				expect(
+					post.tags()
+						.where( "id", tag.getId() )
+						.exists()
+				).toBeTrue();
+				expect(
+					post.tags()
+						.newPivotStatement()
+						.where( "custom_post_pk", post.getPost_Pk() )
+						.where( "tag_id", tag.getId() )
+						.value( "context" )
+				).toBe( "created through relationship" );
+			} );
 		} );
 	}