feat: add extend params feature

src/factory.ts

@@ -274,6 +274,39 @@ export class Factory<Model, Attributes, Params = any, ReturnType = Model> {
     );
   }
 
+  /**
+   * Extends the current factory passing specific transient parameters. This is useful if you have a factory
+   * with transient parameters that defines the type of returned model, and you want to easily create variants of it.
+   * @param newParams The new transient parameters.
+   * @returns A new factory with the extended transient parameters.
+   * @example
+   * const userWithRolesFactory = userFactory.extend<{ roles: string[] }>(({ transientParams }) => {
+   *  return {
+   *    roles: transientParams.roles ?? [],
+   *  }
+   * })
+   *
+   * const userWithAdminRoleFactory = userWithRolesFactory.extendParams({ roles: ['admin'] });
+   * const userWithAdminRole = await userWithAdminRoleFactory.build();
+   * // userWithAdminRole.roles === ['admin']
+   */
+  extendParams<ExtendedParams extends Params = Params>(
+    newParams: ExtendedParams,
+  ): Factory<Model, Attributes, ExtendedParams, ReturnType> {
+    const newDefaultAttributesFactory = async () => {
+      return await this.defaultAttributesFactory({
+        transientParams: newParams,
+      });
+    };
+    return new Factory(
+      newDefaultAttributesFactory,
+      this.model,
+      this._adapter,
+      this.afterCreateHooks,
+      this.afterBuildHooks,
+    );
+  }
+
   /**
    * Adds a hook that is called after the model is created.
    * @param afterCreateHook A function that is called after the model is created.

test/factory.spec.ts

@@ -661,6 +661,34 @@ describe('Factory', () => {
         email: 'user@company.com',
       });
     });
+
+    it('extends the factory and pass custom parameters', async () => {
+      // Arrange
+      type UserTransientParams = {
+        prefix: 'Mr.' | 'Mrs.';
+      };
+      const userFactoryWithTransientParams = FactoryGirl.define<
+        User,
+        User,
+        UserTransientParams
+      >(plainObject<User>(), ({ transientParams }) => ({
+        ...buildUserAttributes(),
+        name: `${transientParams?.prefix} ${buildUserAttributes().name}`,
+      }));
+
+      const mrUserFactory = userFactoryWithTransientParams.extendParams({
+        prefix: 'Mr.',
+      });
+
+      // Act
+      const mrUser = await mrUserFactory.build();
+
+      // Assert
+      expect(mrUser).toEqual({
+        ...buildUserAttributes(),
+        name: 'Mr. John Doe',
+      });
+    });
   });
 
   describe('associate', () => {