@jorgebodega/typeorm-seeding 4.0.0-next.2 → 5.0.0-next.1

package/.commitlintrc

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "@commitlint/config-conventional"
+  ]
+}

package/CHANGELOG.md

@@ -1,3 +1,46 @@
+# [5.0.0-next.1](https://github.com/jorgebodega/typeorm-seeding/compare/v4.0.0...v5.0.0-next.1) (2022-07-13)
+
+
+### Bug Fixes
+
+* update dependency glob to v8 ([2d3c996](https://github.com/jorgebodega/typeorm-seeding/commit/2d3c99635fcfdd667b38a4bed60d663145dd619b))
+
+
+### Features
+
+* removed unused command and add some more tests ([ea6649e](https://github.com/jorgebodega/typeorm-seeding/commit/ea6649e98261d62907118448b047987cbebcd2c7))
+* use typeorm 0.3 ([aa0153b](https://github.com/jorgebodega/typeorm-seeding/commit/aa0153bd050c60ab94f9979eff4e5ab9bec81645))
+
+
+### BREAKING CHANGES
+
+* Removed config command
+* Connection API is deprecated and removed.
+
+# [4.0.0](https://github.com/jorgebodega/typeorm-seeding/compare/v3.2.0...v4.0.0) (2022-03-23)
+
+
+### Bug Fixes
+
+* add type check on subfactories creation ([2b2883b](https://github.com/jorgebodega/typeorm-seeding/commit/2b2883b48ea08173a032b219266b1fece937e753))
+* attrs failing with lazy instances ([c8ddda8](https://github.com/jorgebodega/typeorm-seeding/commit/c8ddda841f9e65d7081e419d2d2e662c6d6a78df))
+* update dependency yargs to v17.4.0 ([b64c224](https://github.com/jorgebodega/typeorm-seeding/commit/b64c2245ebb086d891c503972f74cdcca0e2ddab))
+
+
+### Features
+
+* add factorized attrs ([4a2ce08](https://github.com/jorgebodega/typeorm-seeding/commit/4a2ce08e1be1d79df8f1c0450ba4b315ebca8c46))
+* add lazyattribute and subfactory as options in attribs ([48a3630](https://github.com/jorgebodega/typeorm-seeding/commit/48a3630b8c606ff5189c05dc51908dc09f142184))
+* add subfactory as valid factorized attr ([0f4b37e](https://github.com/jorgebodega/typeorm-seeding/commit/0f4b37e0f8c3e93aedbd109ddb8f33ac0127a2dc))
+* separate different types of lazy attributes ([3efe94e](https://github.com/jorgebodega/typeorm-seeding/commit/3efe94ea140643ccb12dbf8858968a5866fd7577))
+
+
+### BREAKING CHANGES
+
+* definition function has been substituted with attrs
+
+# [4.0.0-next.3](https://github.com/jorgebodega/typeorm-seeding/compare/v4.0.0-next.2...v4.0.0-next.3) (2022-03-03)
+
 # [4.0.0-next.2](https://github.com/jorgebodega/typeorm-seeding/compare/v4.0.0-next.1...v4.0.0-next.2) (2022-02-12)
 
 # [4.0.0-next.1](https://github.com/jorgebodega/typeorm-seeding/compare/v3.2.0...v4.0.0-next.1) (2022-02-12)

package/README.md

@@ -13,7 +13,7 @@
   </a>
   <a href="https://github.com/semantic-release/semantic-release">
     <img src="https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release&style=for-the-badge" alt="Semantic release" />
-  </a> 
+  </a>
 </p>
 
 <p align="center">
@@ -43,14 +43,27 @@
 
 <br />
 
-## Additional contents
+# Contents
 
 - [Factory](#factory-1)
+  - [attrs](#attrs)
+    - [Simple value](#simple-value)
+    - [Function](#function)
+    - [InstanceAttribute](#instanceattribute)
+    - [LazyInstanceAttribute](#lazyinstanceattribute)
+    - [Subfactory](#subfactory)
+  - [make & makeMany](#make--makemany)
+  - [create & createMany](#create--createmany)
+  - [faker](#faker)
 - [Seeder](#seeder-1)
+  - [run](#run)
+  - [call](#call)
 - [CLI](#cli-configuration)
+  - [config](#config)
+  - [seed](#seed)
 - [Testing features](#testing-features)
 
-## Installation
+# Installation
 
 Before using this TypeORM extension please read the [TypeORM Getting Started](https://typeorm.io/#/) documentation. This explains how to setup a TypeORM project.
 
@@ -61,9 +74,9 @@ npm i [-D] @jorgebodega/typeorm-seeding
 yarn add [-D] @jorgebodega/typeorm-seeding
 ```
 
-### Configuration
+## Configuration
 
-To configure the path to your seeders change the TypeORM config file or use environment variables like TypeORM. If both are used the environment variables will be prioritized.
+To configure the path to your seeders extends the TypeORM config file or use environment variables like TypeORM. If both are used the environment variables will be prioritized.
 
 **ormconfig.js**
 
@@ -83,7 +96,7 @@ TYPEORM_SEEDING_SEEDERS=src/seeds/**/*{.ts,.js}
 TYPEORM_SEEDING_DEFAULT_SEEDER=RootSeeder
 ```
 
-## Introduction
+# Introduction
 
 Isn't it exhausting to create some sample data for your database, well this time is over!
 
@@ -94,11 +107,24 @@ How does it work? Just create a entity factory and/or seed script.
 ```typescript
 @Entity()
 class User {
-  @PrimaryGeneratedColumn('uuid') id: string
+  @PrimaryGeneratedColumn('increment')
+  id!: number
+
+  @Column()
+  name!: string
+
+  @Column()
+  lastName!: string
 
-  @Column() name: string
+  @Column()
+  email!: string
 
-  @Column() lastname: string
+  @OneToMany(() => Pet, (pet) => pet.owner)
+  pets?: Pet[]
+
+  @ManyToOne(() => Country, (country) => country.users, { nullable: false })
+  @JoinColumn()
+  country!: Country
 }
 ```
 
@@ -106,13 +132,14 @@ class User {
 
 ```typescript
 class UserFactory extends Factory<User> {
-  protected definition(): User {
-    const user = new User()
-
-    user.name = 'John'
-    user.lastname = 'Doe'
-
-    return user
+  protected entity = User
+  protected attrs: FactorizedAttrs<User> = {
+    name: faker.name.firstName(),
+    lastName: async () => faker.name.lastName(),
+    email: new InstanceAttribute((instance) =>
+      [instance.name.toLowerCase(), instance.lastName.toLowerCase(), '@email.com'].join(''),
+    ),
+    country: new Subfactory(CountryFactory),
   }
 }
 ```
@@ -120,67 +147,164 @@ class UserFactory extends Factory<User> {
 ### Seeder
 
 ```typescript
-export class UserExampleSeeder extends Seeder {
-  async run() {
-    await new UserFactory().create({
-      name: 'Jane',
-    })
+class UserSeeder extends Seeder {
+  async run(connection: Connection) {
+    await new UserFactory().createMany(10)
+
+    await this.call(connection, [PetSeeder])
   }
 }
 ```
 
-## Factory
+# Factory
 
 Factory is how we provide a way to simplify entities creation, implementing a [factory creational pattern](https://refactoring.guru/design-patterns/factory-method). It is defined as an abstract class with generic typing, so you have to extend over it.
 
 ```typescript
 class UserFactory extends Factory<User> {
-  protected definition(): User {
+  protected entity = User
+  protected attrs: FactorizedAttrs<User> = {
     ...
   }
 }
 ```
 
-### `definition`
+## `attrs`
+
+Attributes objects are superset from the original entity attributes.
+
+```typescript
+protected attrs: FactorizedAttrs<User> = {
+  name: faker.name.firstName(),
+  lastName: async () => faker.name.lastName(),
+  email: new InstanceAttribute((instance) =>
+    [instance.name.toLowerCase(), instance.lastName.toLowerCase(), '@email.com'].join(''),
+  ),
+  country: new Subfactory(CountryFactory),
+}
+```
+
+Those factorized attributes resolves to the value of the original attribute, and could be one of the following types:
+
+- [Simple value](#simple-value)
+- [Function](#function)
+- [InstanceAttribute](#instanceattribute)
+- [LazyInstanceAttribute](#lazyinstanceattribute)
+- [Subfactory](#subfactory)
+
+### Simple value
+
+Nothing special, just a value with same type.
+
+```typescript
+protected attrs: FactorizedAttrs<User> = {
+  name: faker.name.firstName(),
+}
+```
+
+### Function
+
+Function that could be sync or async, and return a value of the same type. This function will be executed once per entity.
+
+```typescript
+protected attrs: FactorizedAttrs<User> = {
+  lastName: async () => faker.name.lastName(),
+}
+```
+
+### `InstanceAttribute`
+
+```typescript
+class InstanceAttribute<T, V> {
+  constructor(private callback: (entity: T) => V) {}
+
+  ...
+}
+```
+
+Class with a function that receive the current instance and returns a value of the same type. It is ideal for attributes that could depend on some others to be computed.
 
-This function is the one that needs to be defined when extending the class. It is called to instantiate the entity and the result will be used on the rest of factory lifecycle.
+Will be executed after the entity has been created and the rest of the attributes have been calculated, but before persistance (in case of `create` or `createMany`).
 
 ```typescript
-protected definition(): User {
-    const user = new User()
+protected attrs: FactorizedAttrs<User> = {
+  name: faker.name.firstName(),
+  lastName: async () => faker.name.lastName(),
+  email: new InstanceAttribute((instance) =>
+    [instance.name.toLowerCase(), instance.lastName.toLowerCase(), '@email.com'].join(''),
+  ),
+}
+```
+
+In this simple case, if `name` or `lastName` override the value in any way, the `email` attribute will be affected too.
+
+### `LazyInstanceAttribute`
 
-    user.name = 'John'
-    user.lastname = 'Doe'
+```typescript
+class LazyInstanceAttribute<T, V> {
+  constructor(private callback: (entity: T) => V) {}
 
-    return user
+  ...
 }
 ```
 
-It is possible to create more than one factory related to a single entity, with different definition functions.
+Class with similar functionality than `InstanceAttribute`, but it will be executed only after persistance. This is useful for attributes that depends on the database id, like relations.
 
-### `map`
+Just remember that, if you use `make` or `makeMany`, the only difference between `InstanceAttribute` and `LazyInstanceAttribute` is that `LazyInstanceAttribute` will be processed the last.
 
-Use the `.map()` function to alter the generated value before they get processed.
+```typescript
+protected attrs: FactorizedAttrs<User> = {
+  name: faker.name.firstName(),
+  email: new LazyInstanceAttribute((instance) =>
+    [instance.name.toLowerCase(), instance.id, '@email.com'].join(''),
+  ),
+}
+```
+
+### `Subfactory`
 
 ```typescript
-map(mapFunction: (entity: Entity) => void): Factory
+export class Subfactory<T> {
+  constructor(factory: Constructable<Factory<T>>)
+  constructor(factory: Constructable<Factory<T>>, values?: Partial<FactorizedAttrs<T>>)
+  constructor(factory: Constructable<Factory<T>>, count?: number)
+  constructor(factory: Constructable<Factory<T>>, values?: Partial<FactorizedAttrs<T>>, count?: number)
+
+  ...
+}
 ```
 
+Subfactories are just a wrapper of another factory, to avoid explicit operations that could lead to unexpected results over that factory, like
+
 ```typescript
-new UserFactory().map((user) => {
-  user.name = 'Jane'
-})
+protected attrs: FactorizedAttrs<User> = {
+  country: async () => new CountryFactory().create({
+    name: faker.address.country(),
+  }),
+}
 ```
 
-### `make` & `makeMany`
+instead of
+
+```typescript
+protected attrs: FactorizedAttrs<User> = {
+  country: new Subfactory(CountryFactory, {
+    name: faker.address.country(),
+  }),
+}
+```
+
+Subfactory just execute the same kind of operation (`make` or `create`) over the factory. If `count` param is provided, it will execute `makeMany`/`createMany` instead of `make`/`create`, and returns an array.
+
+## `make` & `makeMany`
 
 Make and makeMany executes the factory functions and return a new instance of the given entity. The instance is filled with the generated values from the factory function, but not saved in the database.
 
 - **overrideParams** - Override some of the attributes of the entity.
 
 ```typescript
-make(overrideParams: Partial<Entity> = {}): Promise<Entity>
-makeMany(amount: number, overrideParams: Partial<Entity> = {}): Promise<Entity>
+make(overrideParams: Partial<FactorizedAttrs<T>> = {}): Promise<T>
+makeMany(amount: number, overrideParams: Partial<FactorizedAttrs<T>> = {}): Promise<T[]>
 ```
 
 ```typescript
@@ -192,7 +316,7 @@ new UserFactory().make({ email: 'other@mail.com' })
 new UserFactory().makeMany(10, { email: 'other@mail.com' })
 ```
 
-### `create` & `createMany`
+## `create` & `createMany`
 
 the create and createMany method is similar to the make and makeMany method, but at the end the created entity instance gets persisted in the database using TypeORM entity manager.
 
@@ -200,8 +324,8 @@ the create and createMany method is similar to the make and makeMany method, but
 - **saveOptions** - [Save options](https://github.com/typeorm/typeorm/blob/master/src/repository/SaveOptions.ts) from TypeORM
 
 ```typescript
-create(overrideParams: Partial<Entity> = {}, saveOptions?: SaveOptions): Promise<Entity>
-createMany(amount: number, overrideParams: Partial<Entity> = {}, saveOptions?: SaveOptions): Promise<Entity>
+create(overrideParams: Partial<FactorizedAttrs<T>> = {}, saveOptions?: SaveOptions): Promise<T>
+createMany(amount: number, overrideParams: Partial<FactorizedAttrs<T>> = {}, saveOptions?: SaveOptions): Promise<T[]>
 ```
 
 ```typescript
@@ -217,50 +341,24 @@ new UserFactory().create({ email: 'other@mail.com' }, { listeners: false })
 new UserFactory().createMany(10, { email: 'other@mail.com' }, { listeners: false })
 ```
 
-### Execution order
-
-As the order of execution can be complex, you can check it here:
-
-2. **Map function**: Map function alters the already existing entity.
-3. **Override params**: Alters the already existing entity.
-4. **Promises**: If some attribute is a promise, the promise will be resolved before the entity is created.
-5. **Factories**: If some attribute is a factory, the factory will be executed with `make`/`create` like the previous one.
+## faker
 
-### Faker
-
-[Faker](https://github.com/marak/Faker.js/) package was previously a dependency of the project, but now it is optional due to its size. If you want to use faker, you may need to install it and import it.
-
-Instead of the previous example:
-
-```typescript
-define(User, (faker: typeof Faker) => {
-  const firstName = faker.name.firstName()
-  const lastName = faker.name.lastName()
+[Faker](https://github.com/faker-js/faker) package has been removed from `dependencies`. If you want to use it, please install it manually and just import when needed.
 
-  const user = new User()
-  user.name = `${firstName} ${lastName}`
-  return user
-})
+```bash
+npm i [-D] @faker-js/faker
+yarn add [-D] @faker-js/faker
 ```
 
-You can do:
-
 ```typescript
-import faker from '@faker-js/faker'
+import { faker } from '@faker-js/faker'
 
 class UserFactory extends Factory<User> {
-  protected definition(): User {
-    const user = new User()
-
-    user.name = faker.name.firstName()
-    user.lastname = faker.name.lastName()
-
-    return user
-  }
+  ...
 }
 ```
 
-## Seeder
+# Seeder
 
 Seeder class is how we provide a way to insert data into databases, and could be executed by the command line or by helper method. Is an abstract class with one method to be implemented, and a helper function to run some more seeder sequentially.
 
@@ -272,7 +370,7 @@ class UserSeeder extends Seeder {
 }
 ```
 
-### `run`
+## `run`
 
 This function is the one that needs to be defined when extending the class. Could use `call` to run some other seeders.
 
@@ -288,7 +386,7 @@ async run(connection: Connection) {
 }
 ```
 
-### `call`
+## `call`
 
 This function allow to run some other seeders in a sequential way.
 
@@ -298,7 +396,7 @@ In order to use seeders from cli command, a default seeder class must be provide
   <img src="./seeders.png" alt="logo" />
 </p>
 
-## CLI Configuration
+# CLI Configuration
 
 There are two possible commands to execute, one to see the current configuration and one to run a seeder.
 
@@ -312,7 +410,7 @@ Add the following scripts to your `package.json` file to configure them.
 }
 ```
 
-### `config`
+## `config`
 
 This command just print the connection configuration.
 
@@ -342,7 +440,7 @@ Example result
 | `--configName` or `-n` | TypeORM default value | Name to the TypeORM config file.                                             |
 | `--root` or `-r`       | TypeORM default value | Path to the TypeORM config file.                                             |
 
-### `seed`
+## `seed`
 
 This command execute a seeder, that could be specified as a parameter.
 
@@ -350,6 +448,8 @@ This command execute a seeder, that could be specified as a parameter.
 typeorm-seeding seed
 ```
 
+The name of the seeder to execute (either set with the `--seed` option or with default in [configs](#configuration)) must be the seeder's class name, and thus, the seeder must be exported with a named export. Please avoid default export for seeders: it may imply unwanted behavior. (See [\#75](https://github.com/jorgebodega/typeorm-seeding/issues/75)).
+
 ##### Options
 
 | Option                 | Default                              | Description                                                                 |
@@ -359,12 +459,12 @@ typeorm-seeding seed
 | `--configName` or `-n` | TypeORM default value                | Name to the TypeORM config file.                                            |
 | `--root` or `-r`       | TypeORM default value                | Path to the TypeORM config file.                                            |
 
-## Testing features
+# Testing features
 
 We provide some testing features that we already use to test this package, like connection configuration.
 The entity factories can also be used in testing. To do so call the `useFactories` or `useSeeders` function.
 
-### `useSeeders`
+## `useSeeders`
 
 Execute one or more seeders.
 
@@ -375,7 +475,3 @@ useSeeders(
   customOptions: Partial<ConnectionConfiguration>,
 ): Promise<void>
 ```
-
-### Factories
-
-If factories are being used to create entities, just remember to clean up fake data after every execution.

package/dist/cli.js

@@ -4,12 +4,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 /* istanbul ignore file */
 require("reflect-metadata");
-const yargs = (0, tslib_1.__importStar)(require("yargs"));
+const yargs_1 = tslib_1.__importDefault(require("yargs"));
 const seed_command_1 = require("./commands/seed.command");
-const config_command_1 = require("./commands/config.command");
-yargs
+yargs_1.default
     .usage('Usage: $0 <command> [options]')
-    .command(new config_command_1.ConfigCommand())
     .command(new seed_command_1.SeedCommand())
     .recommendCommands()
     .demandCommand(1)

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;AACA,0BAA0B;AAC1B,4BAAyB;AACzB,0DAA8B;AAC9B,0DAAqD;AACrD,8DAAyD;AAEzD,KAAK;KACF,KAAK,CAAC,+BAA+B,CAAC;KACtC,OAAO,CAAC,IAAI,8BAAa,EAAE,CAAC;KAC5B,OAAO,CAAC,IAAI,0BAAW,EAAE,CAAC;KAC1B,iBAAiB,EAAE;KACnB,aAAa,CAAC,CAAC,CAAC;KAChB,MAAM,EAAE;KACR,IAAI,CAAC,GAAG,CAAC;KACT,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,IAAI,CAAA"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;AACA,0BAA0B;AAC1B,4BAAyB;AACzB,0DAAyB;AACzB,0DAAqD;AAErD,eAAK;KACF,KAAK,CAAC,+BAA+B,CAAC;KACtC,OAAO,CAAC,IAAI,0BAAW,EAAE,CAAC;KAC1B,iBAAiB,EAAE;KACnB,aAAa,CAAC,CAAC,CAAC;KAChB,MAAM,EAAE;KACR,IAAI,CAAC,GAAG,CAAC;KACT,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,IAAI,CAAA"}

package/dist/commands/seed.command.d.ts

@@ -1,9 +1,10 @@
+import { DataSource } from 'typeorm';
 import { Arguments, Argv, CommandModule } from 'yargs';
+import { Seeder } from '../seeder';
+import type { Constructable } from '../types';
 interface SeedCommandArguments extends Arguments {
-    root?: string;
-    configName?: string;
-    connection?: string;
-    seed?: string;
+    dataSource?: string;
+    path?: string;
 }
 export declare class SeedCommand implements CommandModule {
     command: string;
@@ -12,17 +13,13 @@ export declare class SeedCommand implements CommandModule {
      * @inheritdoc
      */
     builder(args: Argv): Argv<{
-        n: string | undefined;
-    } & {
-        c: string;
-    } & {
-        r: string | undefined;
-    } & {
-        s: string | undefined;
+        d: string;
     }>;
     /**
      * @inheritdoc
      */
     handler(args: SeedCommandArguments): Promise<void>;
+    static loadDataSource(dataSourceFilePath: string): Promise<DataSource>;
+    static loadSeeders(seederPaths: string[]): Promise<Constructable<Seeder>[]>;
 }
 export {};