Object-Oriented Approach for Lucid Model Factories

[HasanAshab]

Dear AdonisJS Team,

I hope this message finds you well. I've been using AdonisJS for quite some time, and I appreciate the elegance and power it brings to web development. Today, I'd like to propose an enhancement to the existing Lucid model factories by adopting an object-oriented approach.

Currently, Lucid model factories are functional, and while they serve their purpose, I believe embracing an OOP paradigm could lead to cleaner, more maintainable, and extensible code. To demonstrate this, I've created a base factory class that introduces features like state customizers, external callbacks, and configuration options:

// Base Factory Class
import { BaseModel } from '@ioc:Adonis/Lucid/Orm';
import { merge } from 'lodash';
import { faker } from '@faker-js/faker';


export type StateCustomizer<Attributes> = (state: Attributes) => Attributes;

export type ExternalCallback<Model> = (model: Model) => Promise<void> | void;

export default abstract class Factory<
	Model extends BaseModel,
	Attributes extends object = Record<string, any>
> {
  
	/**
	 * Fake data generator
	 */
	protected faker = faker;

	/**
	 * Number of records to be generated
	 */
	private total = 1;

	/**
	 * Callbacks that customizes record's state
	 */
	private stateCustomizers: StateCustomizer<Attributes>[] = [];

	/**
	 * Callbacks to perform external async operations
	 * such as creating relational records.
	 */
	private externalCallbacks: ExternalCallback<Model>[] = [];

	/**
	 * Create factory instance
	 */
	constructor(
		private Model: typeof Model,
		protected options: Record<string, unknown> = {},
	) {
		this.Model = Model;
		// this options will be available everywhere
		this.options = options;
	}
  
  /**
   * Configure the factory.
   */
  public configure() {
    //
  }
    

	/**
	 * Return the initial state of records
	 */
	protected abstract definition(): Attributes;

	/**
	 * Specify the number of records to be generated
	 */
	public count(total: number) {
		this.total = total;
		return this;
	}

	/**
	 * Adds state customizer
	 */
	public state(cb: StateCustomizer<Attributes>) {
		this.stateCustomizers.push(cb);
		return this;
	}

	/** 
	 * Adds external operations callback
	 */
	public external(cb: ExternalCallback<Model>) {
		this.externalCallbacks.push(cb);
		return this;
	}

	/**
	 * Generate all records stub data
	 */
	public make(data?: Partial<Attributes>) {
		if(this.total === 1) {
			return this.generateData(data);
		}
		
		return Array.from({ length: this.total }, () => {
			return this.generateDocumentData(data);
		});
	}

	/**
	 * generate and persists all records to database
	 */
	public async create(data: Partial<Attributes>) {
		const stubModels = this.make(data);
		
		const records = Array.isArray(stubModels)
		  ? await this.Model.createMany(stubModels)
		  : await this.Model.create(stubModels);

		await this.runExternalCallbacks(records);
		return records;
	}

	/**
	 * Generates single record data
	 */
	private generateData(data?: Partial<Attributes>) {
		let recordData = this.customizeState(this.definition());
		if (data) {
			recordData = merge(recordData, data);
		}
		return recordData;
	}

	/**
	 * Runs all state customizers
	 */
	private customizeState(recordData: Attributes) {
		this.stateCustomizers.forEach((customizer) => {
			recordData = customizer(recordData);
		});
		return recordData;
	}

	/**
	 * Runs all external callbacks
	 */
	private runExternalCallbacks(models: Model | Model[]) {
	  if(!Array.isArray(models)) {
	    return Promise.all(
	      this.externalCallbacks.map(cb => cb(models))
	    );
	  }
	  
	  const promises = models.map(model => {
	    return this.externalCallbacks.map(cb => cb(model));
	  });
	  
		return Promise.all(promises.flat());
	}
}


  // Additional methods...
}

To illustrate the new factory design, I've extended it with the UserFactory:

// User Factory Example
import Factory from 'App/Models/Traits/HasFactory/Factory';
import User from 'App/Models/User';

export default class UserFactory extends Factory<User> {
	definition() {
		return {
			name: this.faker.person.firstName(),
			username: this.faker.person.firstName(),
			email: this.faker.internet.email(),
			phoneNumber: null,
			password: 'password',
			verified: true,
			role: 'novice' as const,
			profile: null,
			recoveryCodes: [],
			socialId: {},
		};
	}

	unverified() {
		return this.state(user => {
			user.verified = false;
			return user;
		});
	}

	social(provider = 'google', id = '100020') {
		return this.state(user => {
			user.password = null;
			user.socialId[provider] = id;
			return user;
		});
	}

	withRole(name: User['role']) {
		return this.state(user => {
			user.role = name;
			return user;
		});
	}

	withProfile(url = this.faker.internet.avatar()) {
		return this.state(user => {
			user.profile = url;
			return user;
		});
	}

	withPhoneNumber(phoneNumber = '+15005550006') {
		return this.state(user => {
			user.phoneNumber = phoneNumber;
			return user;
		});
	}
	
	hasSettings(
	  enableTwoFactorAuth = false,
	  method: TwoFactorAuthMethod = 'sms'
	) {
		return this.external((user: User) => {
		  return user.related('settings').create({ 
		    twoFactorAuth: { 
		      enabled: enableTwoFactorAuth,
		      method,
		      secret: null
		    }
		  });
		});
	}

}

Now the User model can extend HasFactory Trait

import type { NormalizeConstructor } from '@ioc:Adonis/Core/Helpers'
import { BaseModel } from '@ioc:Adonis/Lucid/Orm'

export default function HasFactory(Superclass: NormalizeConstructor<typeof BaseModel>) {
  return class HasFactoryModel extends Superclass {
    static get factoryClass() {
      if(!this._factoryClass) {
        this._factoryClass = require(`Database/factories/${this.name}Factory`).default;
      }
      return this._factoryClass;
    }
    
    static factory(options?: object) {
  		const factory = new this.factoryClass(this, options);
  		factory.configure();
  		return factory;
  	}
  }
}

Useage

await User.factory().create()
await User.factory().count(5).create()
...

By adopting this OOP approach, we can easily extend and customize factories for specific models. I believe this change would enhance the readability, maintainability, and extensibility of the existing factory system.

Thank you for considering this proposal. I'm open to discussions and feedback.

Best regards,
Hasan Ashab