@birdbrain/typeorm-seeder v1.11.1

@birdbrain/typeorm-seeder

Seed TypeORM entities using decorators.

Be aware

This project is very much in development. Expect breaking changes between minor versions.

Table of contents

• Prerequisites
• Installation
• Quick start
• Usage
  • Create
  • Create and persist
• Advanced usage
  • Relations
• Seeders
• Builders
  • EntityBuilder
  • SeederBuilder

Prerequisites

Enable decorators in tsconfig.json.

{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true
  }
}

Installation

npm install @birdbrain/typeorm-seeder

TypeORM is required.

Quick start

Use the @Seed() property decorator to generate property values. Relations are seeded the same way.

import { Entity, PrimaryGeneratedColumn } from 'typeorm';
import { Seed } from '@birdbrain/typeorm-seeder';
import * as faker from 'faker';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  public id: number;

  @Column()
  @Seed(() => faker.name.firstName())
  public name: string;
}

Create a connection and seed the entity using the forEntity() builder.

import { createConnection } from 'typeorm';
import { forEntity } from '@birdbrain/typeorm-seeder';

await createConnection();

const user = forEntity(User).create();

// User {
//   name: 'Jack'
// }

Usage

Create

Entities are simply created, seeded and returned.

import { createConnection, getRepository } from 'typeorm';
import { forEntity } from '@birdbrain/typeorm-seeder';

await createConnection();

const user = forEntity(User).create();

// User {
//   name: 'Jack'
// }

const users = forEntity(User).createMany(2);

// [
//   User {
//     name: 'Jack'
//   },
//   User {
//     name: 'Matt'
//   }
// ]

await getRepository(User).save(user);

Create and persist

Entities are created, seeded and persisted in the database. Returns the persisted entities.

import { createConnection } from 'typeorm';
import { forEntity } from '@birdbrain/typeorm-seeder';

await createConnection();

const user = await forEntity(User).persist();

// User {
//   id: 1,
//   name: 'Jack'
// }

const users = await forEntity(User).persistMany(2);

// [
//   User {
//     id: 1,
//     name: 'Jack'
//   },
//   User {
//     id: 2,
//     name: 'Matt'
//   }
// ]

Advanced usage

Relations

Relations are seeded like any other property. No callback is needed, the related entity is automatically resolved from the relation.

Seeding both sides of a relation is optional. It's only required on the entity passed to forEntity().

One-to-one

import { Entity, PrimaryGeneratedColumn, Column, OneToOne, JoinColumn } from 'typeorm';
import { Seed } from '@birdbrain/typeorm-seeder';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  public id: number;

  @Column()
  @Seed(() => faker.name.firstName())
  public name: string;

  @OneToOne(() => House, (house) => post.owner)
  @JoinColumn()
  @Seed()
  public house: House;
}

import { Entity, Column, OneToOne } from 'typeorm';
import { Seed } from '@birdbrain/typeorm-seeder';

@Entity()
export class House {
  @PrimaryGeneratedColumn()
  public id: number;

  @Column()
  @Seed(() => faker.address.streetName())
  public streetName: string;

  @OneToOne(() => User, (user) => user.house)
  @Seed()
  public owner: User;
}

import { createConnection } from 'typeorm';
import { forEntity } from '@birdbrain/typeorm-seeder';

await createConnection();

const users = await forEntity(User).persistMany(2);

// [
//   User {
//     id: 1,
//     name: 'Jack',
//     house: House { id: 1, streetName: 'Willow Avenue' }
//   },
//   User {
//     id: 2,
//     name: 'Bob',
//     house: House { id: 2, streetName: 'Elm Street' }
//   }
// ]

Relations where the join column is on the opposite side of the entry entity will also be seeded.

One-to-many, many-to-one, many-to-many

import { Entity, Column, OneToMany } from 'typeorm';
import { Seed } from '@birdbrain/typeorm-seeder';

@Entity()
export class User {
  @Column()
  @Seed(() => faker.name.firstName())
  public name: string;

  @OneToMany(() => House, (house) => post.owner)
  @Seed({ amount: 2 })
  public houses: House[];
}

import { Entity, Column, ManyToOne } from 'typeorm';
import { Seed } from '@birdbrain/typeorm-seeder';

@Entity()
export class House {
  @Column()
  @Seed(() => faker.address.streetName())
  public streetName: string;

  @ManyToOne(() => User, (user) => user.houses)
  @Seed()
  public owner: User;
}

import { createConnection } from 'typeorm';
import { forEntity } from '@birdbrain/typeorm-seeder';

await createConnection();

const users = await forEntity(User).persist();

// [
//   User {
//     id: 1,
//     name: 'Jack',
//     houses: [
//       House { id: 1, streetName: 'Willow Avenue' }
//       House { id: 2, streetName: 'Elm Street' }
//     ]
//   },
// ]

Seeders

Use seeders to easily organize seeding and separate concerns. A seeder is a class decorated with @Seeder(). Use the BaseSeeder interface to construct seeders appropriately.

import { Seeder, BaseSeeder } from '@birdbrain/typeorm-seeder';

@Seeder()
export class UserSeeder implements BaseSeeder {
  constructor() {}

  public seed(): Promise<User[]> {
    return forEntity(User).persistMany(5);
  }
}

Use options to control the order in which seeders are executed.

import { Seeder, BaseSeeder } from '@birdbrain/typeorm-seeder';

@Seeder({ runsBefore: [SomeOtherSeeder] })
export class UserSeeder implements BaseSeeder {
  public seed(): Promise<User[]> {
    return forEntity(User).persistMany(5);
  }
}

Use the forSeeders() builder to run the seeders.

import { createConnection } from 'typeorm';
import { forSeeders } from '@birdbrain/typeorm-seeder';

await createConnection();

await forSeeders([UserSeeder, SomeOtherSeeder]).run();

As in TypeORM, seeders can be loaded by providing paths to the seeder files relative to project root.

import { createConnection } from 'typeorm';
import { forSeeders } from '@birdbrain/typeorm-seeder';

await createConnection();

await forSeeders(['seeders/*.ts']).run();

Builders

The forEntity() and forSeeders() methods are factories instantiating respectively EntityBuilder and SeederBuilder. Use the builders directly for a more fine-tuned seeding.

EntityBuilder

import { createConnection } from 'typeorm';
import { EntityBuilder } from '@birdbrain/typeorm-seeder';

const connection = await createConnection();

const users = await new EntityBuilder()
  .connection(connection)
  .entity(User)
  .options({ skipProperties: ['posts'] })
  .persistMany(2);

SeederBuilder

import { createConnection } from 'typeorm';
import { SeederBuilder } from '@birdbrain/typeorm-seeder';

await createConnection();

await new SeederBuilder().seeders([UserSeeder, 'seeders/*.ts']).run();