fishery

Fishery provides hooks to execute code during the object lifecycle:

• afterBuild: Executed after an object is built. Useful for setting up relationships or modifying the object.
• afterCreate: Executed after the onCreate logic is finished. Multiple afterCreate hooks can be defined.
• onCreate: Defines or replaces the behavior of .create(). Only one can be defined.

// afterBuild example
const userFactory = Factory.define<User>(({ sequence, afterBuild }) => {
  afterBuild(user => {
    // perform side effects or setup relationships
  });
  return { id: sequence, name: 'Bob' };
});

// afterCreate example
const userFactory = Factory.define<User, {}, SavedUser>(({ onCreate, afterCreate }) => {
  onCreate(user => apiService.create(user));
  afterCreate(savedUser => doMoreStuff(savedUser));

  return { id: 1, name: 'Bob' };
});

For complex or frequently used configurations, subclass Factory to add custom, named builder methods (often called 'traits'). This allows for a fluent API like userFactory.admin().registered().build().

class UserFactory extends Factory<User, UserTransientParams> {
  admin(adminId?: string) {
    return this.params({
      admin: true,
      adminId: adminId || `admin-${this.sequence()}`,
    });
  }
}

const userFactory = UserFactory.define(() => ({ ... }));
const user = userFactory.admin().build();

To perform asynchronous operations (like saving to a database) when building objects, use the .create() method. You must first define the behavior of create using the onCreate hook inside the Factory.define callback. Note that .create() returns a Promise of the object.

const userFactory = Factory.define<User>(({ onCreate }) => {
  onCreate(user => User.create(user)); // Define the async behavior

  return {
    id: 1,
    name: 'Maria',
    // ...
  };
});

const user = await userFactory.create({ name: 'Maria' });
user.name; // Maria

A factory is a function that returns an object. Use Factory.define<T> to create a factory. You can then call .build() to generate an object. The .build() method accepts an object of properties to override the defaults. Fishery provides a sequence helper to generate unique values.

import { Factory } from 'fishery';
import { User } from '../my-types';

const userFactory = Factory.define<User>(({ sequence }) => ({
  id: sequence,
  name: 'Rosa',
  address: { city: 'Austin', state: 'TX', country: 'USA' },
}));

const user = userFactory.build({
  name: 'Susan',
  address: { city: 'El Paso' },
});

user.name; // Susan
user.address.city; // El Paso
user.address.state; // TX (from factory)

Install Fishery as a development dependency using npm or yarn.

npm install --save-dev fishery
# or
yarn add --dev fishery

Fishery factories support several hooks to manipulate objects during their lifecycle. These hooks can be defined within the factory configuration to handle logic after an object is built or after it is created.

• afterBuild: A hook that receives a HookFn to run after the object is constructed.
• onCreate: A hook that receives an OnCreateFn, allowing you to transform the object or perform async operations to return a new version of the object.
• afterCreate: A hook that receives an AfterCreateFn, typically used for post-creation logic that returns the object (or a promise of it).

If you are using sequences within a factory, you can reset the sequence counter to its original starting value by calling rewindSequence() on the factory instance.

factory.rewindSequence();

You can create new factory instances with pre-set attributes using extension methods. These methods return a new factory and do not modify the original.

Available extension methods:

• .params(attrs): Sets default attributes to be overlaid on the result.
• .transient(attrs): Sets default transient parameters.
• .associations(attrs): Sets default associations.
• .afterBuild(callback): Adds an afterBuild hook.
• .afterCreate(callback): Adds an afterCreate hook.
• .onCreate(callback): Defines the create behavior.

const userFactory = Factory.define<User>(() => ({ admin: false }));

// Returns a new factory instance
const adminFactory = userFactory.params({ admin: true });

adminFactory.build().admin; // true
userFactory.build().admin; // false

When using .create(), the return type might differ from the type returned by .build(). You can specify these types using the following generic signature in Factory.define:

Factory.define<ReturnTypeOfBuild, TransientParamsType, ReturnTypeOfCreate>