diff --git a/models/BaseEntity.cfc b/models/BaseEntity.cfc index a3f7a943..bd3db70a 100644 --- a/models/BaseEntity.cfc +++ b/models/BaseEntity.cfc @@ -1317,6 +1317,16 @@ component accessors="true" { /** * Creates a new entity with the given attributes and then saves the entity. * + * This method always creates and returns a separate entity instance. It does + * not fill, save, or otherwise mutate the entity on which it was called. + * Assign the returned entity when it needs to be used after creation: + * + * ``` + * var user = getInstance( "User" ).newEntity(); + * user = user.create( { "firstName" : "Dave" } ); + * user.isLoaded(); // true + * ``` + * * @attributes A struct of key / value pairs. * @ignoreNonExistentAttributes If true, does not throw an exception if an * attribute does not exist. Instead, it skips diff --git a/tests/specs/integration/BaseEntity/CreateSpec.cfc b/tests/specs/integration/BaseEntity/CreateSpec.cfc index 5b1c7b32..e707b920 100644 --- a/tests/specs/integration/BaseEntity/CreateSpec.cfc +++ b/tests/specs/integration/BaseEntity/CreateSpec.cfc @@ -17,6 +17,21 @@ component extends="tests.resources.ModuleIntegrationSpec" { ).notToBeNull(); } ); + it( "returns a separate loaded entity without mutating the original entity", function() { + var originalUser = getInstance( "User" ).newEntity(); + var createdUser = originalUser.create( { + "username" : "Dave", + "first_name" : "Dave", + "last_name" : "Create", + "password" : hash( "password" ) + } ); + + expect( originalUser.isLoaded() ).toBeFalse(); + expect( originalUser.isNullAttribute( "username" ) ).toBeTrue(); + expect( createdUser.isLoaded() ).toBeTrue(); + expect( createdUser.getUsername() ).toBe( "Dave" ); + } ); + it( "can ignore non-existant properties", function() { var user = getInstance( "User" ).create( {