prisma-fabbrica
Prisma generator for model factories.
ToC
Getting started
npm i @quramy/prisma-fabbrica -D
Then, edit your prisma/schema.prisma
and append the prisma-fabbrica generator configuration:
generator client {
provider = "prisma-client-js"
}
generator fabbrica {
provider = "prisma-fabbrica"
}
And run generate command.
npx prisma generate
The above command generates JavaScript and TypeScript type definition files under src/__generated__/fabbrica
directory. You can define your model factory importing them.
For example, if schema.prisma
has the following User
model, you can import defineUserFactory
and define UserFactory
using this function.
model User {
id String @id
name String
posts Post[]
}
import { PrismaClient } from "@prisma/client";
import { initialize, defineUserFactory } from "./__generated__/fabbrica";
const prisma = new PrismaClient();
initialize({ prisma });
async function seed() {
const UserFactory = defineUserFactory();
await UserFactory.create();
await UserFactory.create({ name: "Alice" });
await UserFactory.create({ id: "user002", name: "Bob" });
console.log(await prisma.user.count());
}
seed();
[!NOTE]
The factories use Prisma client instance passed by initialize
function.
If you want to use factories in your test code see Works with jest-prisma section below.
Usage of factories
Field default values
Factory by defined with defineUserFactory
automatically fills required scalar fields.
For example, the following User
model has some required field, id
, email
, firstName
and lastName
.
model User {
id Int @id
email String @unique
firstName String
lastName String
middleName String?
createdAt DateTime @default(now())
}
const UserFactory = defineUserFactory();
await UserFactory.create();
See https://github.com/Quramy/prisma-fabbrica/blob/main/packages/prisma-fabbrica/src/scalar/gen.ts if you want auto filling rule details.
[!NOTE]
prisma-fabbrica auto filling does not generate values of fields with @default()
function because these fields are not required and values of them are generated by Prisma engine.
Default filling rule also can be overwritten.
const UserFactory = defineUserFactory({
defaultData: async () => ({
email: await generateRandomEmailAddress(),
}),
});
await UserFactory.create();
Use sequence for scalar fields
seq
parameter provides sequential number which increments when called .create()
.
const UserFactory = defineUserFactory({
defaultData: async ({ seq }) => ({
id: `user${seq.toString().padStart(3, "0")}`,
}),
});
await UserFactory.create();
await UserFactory.create();
await UserFactory.create();
And the sequential number can be reset via resetSequence
.
import { resetSequence } from "./__generated__/fabbrica";
beforeEach(() => resetSequence());
Shorthand for create list
Each factory provides .createList
method to insert multiple records.
await UserFactory.createList(3);
await Promise.all([0, 1, 2].map(() => UserFactory.create()));
The 2nd argument(optional) accepts an object which is assignable to Partial<Prisma.UserCreateInput>
:
await UserFactory.createList(3, { name: "Bob" });
You can also pass list data assignable to Partial<Prisma.UserCreateInput>[]
:
await UserFactory.createList([{ id: "user01" }, { id: "user02" }]);
Required relation
Sometimes, creating a model requires other model existence. For example, the following model Post
belongs to other model User
.
model User {
id String @id
name String
posts Post[]
}
model Post {
id String @id
title String
author User @relation(fields: [authorId], references: [id])
authorId String
}
You should tell how to connect author
field when define Post factory.
Using related model factory (recommended)
The easiest way is to give UserFactory
when definePostFactory
like this:
const UserFactory = defineUserFactory();
const PostFactory = definePostFactory({
defaultData: {
author: UserFactory,
},
});
The above PostFactory
creates User
model for each PostFactory.create()
calling,
Manual create or connect
Similar to using prisma.post.create
, you can also use connect
/ create
/ createOrConnect
options.
const PostFactory = definePostFactory({
defaultData: async () => ({
author: {
connect: {
id: (await prisma.user.findFirst()!).id,
},
},
}),
});
Connection helper
Required relation rules can be overwritten when .create
method. createForConnect
can be used to connect.
const UserFactory = defineUserFactory();
const PostFactory = definePostFactory({
defaultData: {
author: UserFactory,
},
});
const author = await UserFactory.createForConnect();
await PostFactory.create({ author: { connect: author } });
await PostFactory.create({ author: { connect: author } });
const { posts } = await prisma.user.findUnique({ where: author, include: { posts: true } });
console.log(posts.length);
Build input data only
.build
method in factories provides data set to create the model, but never insert.
await UserFactory.create();
const data = await UserFactory.build();
await prisma.user.create({ data });
For example, you can use .build
method in other model's factory definition:
const UserFactory = defineUserFactory();
const PostFactory = definePostFactory({
defaultData: async () => ({
author: {
connectOrCreate: {
where: {
id: "user001",
},
create: await UserFactory.build({
id: "user001",
}),
},
},
}),
});
await PostFactory.create();
await PostFactory.create();
console.log(await prisma.user.count());
Like createList
, buildList
is also available.
has-many / has-one relation
Sometimes, you may want a user data whose has post record. You can use PostFactory.build
or PostFactory.buildList
.
await UserFactory.create({
posts: {
create: await PostFactory.buildList(2),
},
});
console.log(await prisma.post.count());
[!NOTE]
In the above example, PostFactory.build()
resolves JSON data such as:
{
id: "...",
title: "...",
author: { ... }
}
The author
field is not allowed in prisma.user.create
context. So UserFactory
automatically filters the author
field out in .create
method.
Custom scalar field generation
prisma-fabbrica provides function to complete scalar fields( https://github.com/Quramy/prisma-fabbrica/blob/main/packages/prisma-fabbrica/src/scalar/gen.ts ).
registerScalarFieldValueGenerator
allows to custom this rule. For example:
import { registerScalarFieldValueGenerator } from "./__generated__/fabbrica";
registerScalarFieldValueGenerator({
String: ({ modelName, fieldName, seq }) => `${modelName}_${fieldName}_${seq}`,
});
registerScalarFieldValueGenerator
accepts an object Record<FiledType, FieldGenerateFunction>
.
Field type is one of Boolean
, String
, Int
, Float
, BigInt
, Decimal
, DateTime
, Bytes
, and Json
.
FieldGenerateFunction
is a function to return corresponding fieled type.
See also https://github.com/Quramy/prisma-fabbrica/blob/main/packages/prisma-fabbrica/src/scalar/types.ts .
Traits
Traits allow you to group fields together and apply them to factory.
const UserFactory = defineUserFactory({
defaultData: {
name: "sample user",
},
traits: {
withdrawal: {
data: {
name: "****",
status: "WITHDRAWAL",
},
},
},
});
traits
option accepts an object and the option object's keys are treated as the trait's name. And you can set data
option to the each trait key. The data
option accepts value of the same types as the defaultData
(i.e. plain object, function, async function)
And you can pass the trait's name to UserFactory.use
function:
const deactivatedUser = await UserFactory.use("withdrawal").create();
Multiple traits are also available:
await UserFactory.use("someTrait", "anotherTrait").create();
Callbacks
You can set callback function before or after factory execution.
const UserFactory = defineUserFactory({
onAfterCreate: async user => {
await PostFactory.create({
author: { connect: uesr },
});
},
});
await UserFactory.create();
Callback functions are also available within trait definition.
const UserFactory = defineUserFactory({
traits: {
withComment: {
onAfterCreate: async user => {
await PostFactory.create({
author: { connect: uesr },
});
},
},
},
});
await UserFactory.create();
await UserFactory.use("withComment").create();
[!NOTE]
The above code is to explain the callback. If you want to create association, first consider to use defaultData
and trait.data
option as in has-many / has-one relation.
The following three types are available as callback function:
const UserFactory = defineUserFactory({
onAfterBuild: async createInput => {
},
onBeforeCreate: async createInput => {
},
onAfterCreate: async createdData => {
},
});
And here, the parameter types are:
createInput
is assignable to model create function parameter (e.g. Prsima.UserCreateInput
).createdData
is resolved object by model create function (e.g. User
model type)
Transient fields
Transient fields allow to define arbitrary parameters to factory and to pass them when calling create
or build
.
const UserFactory = defineUserFactory.withTransientFields({
loginCount: 0,
})({
defaultData: async ({ loginCount }) => {
},
});
await UserFactory.create({ name: "Bob", loginCount: 10 });
Transient fields passed from factories' create
method don't affect Prisma's create
result.
[!NOTE]
You can't use model field names defined in your schema.prisma as transient parameters because they're not passed to prisma.user.create
method.
Transient fields also can be accessed from traits or callbacks.
const UserFactory = defineUserFactory.withTransientFields({
loginCount: 0,
})({
onAfterCreate: async (createdUser, { loginCount }) => {
for (let i = 0; i < loginCount; i++) {
await writeLoginLog(createdUser.id);
}
},
traits: {
data: async ({ loginCount }) => {
},
},
});
Field value precedence
Each field is determined in the following priority order(lower numbers have higher priority):
- Factory's
.create
or .build
function's argument - The applied trait's
data
entry - Factories
defaultData
entry - Value derived from
registerScalarFieldValueGenerator
if the field is required scalar(or enum)
More examples
There are more example codes in https://github.com/Quramy/prisma-fabbrica/tree/main/examples/example-prj/src .
Generator configuration
The following options are available:
generator fabbrica {
provider = "prisma-fabbrica"
output = "../src/__generated__/fabbrica"
tsconfig = "../tsconfig.json"
noTranspile = false
}
output
: Directory path to generate files.tsconfig
: TypeScript configuration file path. prisma-fabbrica uses it's compilerOptions
when generating .js
and .d.ts
files. If missing tsconfig json file, fallback to --target es2020 --module commonjs
.noTranspile
: If set true
, this generator only generates raw .ts
file and stop to transpile to .js
and .d.ts
.
Tips
Works with jest-prisma
If you use @quramy/jest-prisma or @quramy/jest-prisma-node, you can pass @quramy/prisma-fabbrica/scripts/jest-prisma
to setupFilesAfterEnv
in your Jest configuration file.
export default {
preset: "ts-jest",
transform: {
"^.+\\.tsx?$": "ts-jest",
},
testEnvironment: "@quramy/jest-prisma/environment",
setupFilesAfterEnv: ["@quramy/prisma-fabbrica/scripts/jest-prisma"],
};
This script calls prisma-fabbrica's initialize
function and configures Prisma client used from each factory to integrate to join to transaction managed by jest-prisma.
Suppress TS circular dependencies error
Sometimes, factories need each other factory as the following, however TypeScript compiler emits errors via circular dependencies.
export const UserFactory = defineUserFactory({
defaultData: async () => ({
posts: {
connect: await PostFactory.buildList(1),
},
}),
});
const PostFactory = definePostFactory({
defaultData: {
author: UserFactory,
},
});
FactoryInterface
types are available to avoid this error. See Factory interface with types section if you want usage of factory interface.
import { defineUserFactory, definePostFactory, type UserFactoryInterface } from "./__generated__/fabbrica";
const UserFactory = defineUserFactory({
defaultData: async () => ({
posts: {
connect: await PostFactory.buildList(1),
},
}),
});
function getUserFactory(): UserFactoryInterface {
return UserFactory;
}
const PostFactory = definePostFactory({
defaultData: {
author: getUserFactory(),
},
});
Factory interface with types
[!WARNING]
Factory interface type parameters may change in future versions without notice.
Factory interface (e.g. UserFactory
) takes 2 optional type parameters:
TTransientFields
: Type of transient fields object. By default, Record<string, unknown>
.TTraitName
: Names of available traits. By default, string | symbol
.
For example:
declare function getUserFactory(): UserFactoryInterface<{ loginCount: number }>;
await getUserFactory().create({ loginCount: 10 });
await getUserFactory().create({ hoge: 10 });
declare function getUserFactory(): UserFactoryInterface<{}, "someTrait" | "anotherTrait">;
await getUserFactory().use("someTrait").create();
await getUserFactory().use("anotherTrait").create();
await getUserFactory().use("hoge").create();
Version compatibility
- If your @prisma/client's version >= 5.0.0, install
@quramy/prisma-fabbrica@2.x.x
. - If your @prisma/client's version < 5.0.0, install
@quramy/prisma-fabbrica@1.x.x
.
License
MIT