MikroORM

Cette recette est ici pour aider les utilisateurs à démarrer avec MikroORM dans Nest. MikroORM est l’ORM TypeScript pour Node.js basé sur les modèles Data Mapper, Unit of Work et Identity Map. C’est une excellente alternative à TypeORM et la migration depuis TypeORM devrait être assez facile. La documentation complète sur MikroORM peut être trouvée ici.

Astuce

@mikro-orm/nestjs est un package tiers et n’est pas géré par l’équipe de base de NestJS. Veuillez signaler tout problème trouvé avec la bibliothèque dans le dépôt approprié.

Installation

La manière la plus simple d’intégrer MikroORM à Nest est via le module @mikro-orm/nestjs. Installez-le simplement à côté de Nest, MikroORM et du pilote sous-jacent :

$ npm i @mikro-orm/core @mikro-orm/nestjs @mikro-orm/sqlite

MikroORM prend également en charge postgres, sqlite et mongo. Consultez la documentation officielle pour tous les pilotes.

Une fois le processus d’installation terminé, nous pouvons importer le MikroOrmModule dans le module racine AppModule.

Importation de MikroORM dans le module racine

import { SqliteDriver } from '@mikro-orm/sqlite';

@Module({
  imports: [
    MikroOrmModule.forRoot({
      entities: ['./dist/entities'],
      entitiesTs: ['./src/entities'],
      dbName: 'my-db-name.sqlite3',
      driver: SqliteDriver,
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

La méthode forRoot() accepte le même objet de configuration que init() du package MikroORM. Consultez cette page pour toute la documentation de configuration.

Alternativement, nous pouvons configurer la CLI en créant un fichier de configuration mikro-orm.config.ts et ensuite appeler le forRoot() sans aucun argument.

Configuration de MikroORM

@Module({
  imports: [
    MikroOrmModule.forRoot({}),
  ],
  ...
})
export class AppModule {}

Cependant, cela ne fonctionnera pas lorsque vous utilisez des outils de build qui utilisent le tree shaking, pour cela, il est préférable de fournir la config explicitement :

Configuration explicite de MikroORM

import config from './mikro-orm.config'; // votre config ORM

@Module({
  imports: [
    MikroOrmModule.forRoot(config),
  ],
  ...
})
export class AppModule {}

Ensuite, le EntityManager sera disponible pour être injecté dans tout le projet (sans importer aucun module ailleurs).

Injection de EntityManager

import { EntityManager, MikroORM } from '@mikro-orm/sqlite';

@Injectable()
export class MyService {
  constructor(
    private readonly orm: MikroORM,
    private readonly em: EntityManager,
  ) {}
}

Astuce

Remarquez que le EntityManager est importé depuis le package @mikro-orm/driver, où le driver est mysql, sqlite, postgres ou n’importe quel driver que vous utilisez. Dans le cas où vous avez @mikro-orm/knex installé comme dépendance, vous pouvez également importer le EntityManager de là.

Repositories

MikroORM prend en charge le modèle de conception repository. Pour chaque entité, nous pouvons créer un repository. Lisez la documentation complète sur les repositories ici. Pour définir quels repositories doivent être enregistrés dans le contexte actuel, vous pouvez utiliser la méthode forFeature(). Par exemple, de cette manière :

Astuce

Vous ne devez pas enregistrer vos entités de base via forFeature(), car il n’y a pas de repositories pour celles-ci. D’un autre côté, les entités de base doivent faire partie de la liste dans forRoot() (ou dans la configuration ORM en général).

Exemple de module de photo

@Module({
  imports: [
    MikroOrmModule.forFeature([Photo]),
  ],
  providers: [PhotoService],
  controllers: [PhotoController],
})
export class PhotoModule {}

et l’importer dans le module racine AppModule :

Importation de PhotoModule dans le module racine

@Module({
  imports: [
    MikroOrmModule.forRoot({ ... }),
    PhotoModule,
  ],
})
export class AppModule {}

De cette manière, nous pouvons injecter le PhotoRepository dans le PhotoService en utilisant le décorateur @InjectRepository() :

Injection de PhotoRepository

@Injectable()
export class PhotoService {
  constructor(
    @InjectRepository(Photo)
    private readonly photoRepository: EntityRepository<Photo>,
  ) {}
}

Utilisation de repositories personnalisés

Lorsque vous utilisez des repositories personnalisés, nous n’avons plus besoin du décorateur @InjectRepository(), car Nest DI résout basé sur les références de classe.

Définition d'une entité personnalisée

@Entity({ repository: () => AuthorRepository })
export class Author {
  // pour permettre l'inférence dans `em.getRepository()`
  [EntityRepositoryType]?: AuthorRepository;
}

Définition d'un repository personnalisé

export class AuthorRepository extends EntityRepository<Author> {
  // vos méthodes personnalisées...
}

Étant donné que le nom du repository personnalisé est le même que ce que getRepositoryToken() renverrait, nous n’avons plus besoin du décorateur @InjectRepository() :

Injection de repository personnalisé

@Injectable()
export class MyService {
  constructor(private readonly repo: AuthorRepository) {}
}

Chargement automatique des entités

Ajouter manuellement des entités au tableau d’entités des options de connexion peut être fastidieux. De plus, référencer des entités depuis le module racine enfreint les frontières de domaine de l’application et entraîne des fuites de détails d’implémentation vers d’autres parties de l’application. Pour résoudre ce problème, des chemins glob statiques peuvent être utilisés.

Notez cependant que les chemins glob ne sont pas pris en charge par webpack, donc si vous construisez votre application dans un monorepo, vous ne pourrez pas les utiliser. Pour résoudre ce problème, une solution alternative est fournie. Pour charger automatiquement les entités, définissez la propriété autoLoadEntities de l’objet de configuration (passé à la méthode forRoot()) sur true, comme indiqué ci-dessous :

Chargement automatique des entités

@Module({
  imports: [
    MikroOrmModule.forRoot({
      ...
      autoLoadEntities: true,
    }),
  ],
})
export class AppModule {}

Avec cette option spécifiée, chaque entité enregistrée via la méthode forFeature() sera automatiquement ajoutée au tableau d’entités de l’objet de configuration.

Astuce

Notez que les entités qui ne sont pas enregistrées via la méthode forFeature(), mais qui ne sont que référencées depuis l’entité (via une relation), ne seront pas incluses par le paramètre autoLoadEntities.

Astuce

L’utilisation de autoLoadEntities n’a également aucun effet sur la CLI de MikroORM - pour cela, nous avons toujours besoin d’une configuration CLI avec la liste complète des entités. En revanche, nous pouvons utiliser des globes là-bas, car la CLI ne passe pas par webpack.

Sérialisation

Attention

Notez que MikroORM enveloppe chaque relation d’entité unique dans un objet Reference<T> ou Collection<T>, afin de fournir une meilleure sécurité de type. Cela rendra la sérialisation intégrée de Nest insensible à toute relation enveloppée. En d’autres termes, si vous renvoyez des entités MikroORM depuis vos gestionnaires HTTP ou WebSocket, toutes leurs relations NE seront PAS sérialisées.

Heureusement, MikroORM fournit une API de sérialisation qui peut être utilisée à la place du ClassSerializerInterceptor.

Définition d'une classe d'entité avec sérialisation

@Entity()
export class Book {
  @Property({ hidden: true }) // Équivalent de `@Exclude` de class-transformer
  hiddenField = Date.now();

  @Property({ persist: false }) // Similaire à `@Expose() de class-transformer`. N'existera qu'en mémoire, et sera sérialisé.
  count?: number;

  @ManyToOne({
    serializer: (value) => value.name,
    serializedName: 'authorName',
  }) // Équivalent de `@Transform()` de class-transformer
  author: Author;
}

Gestionnaires de portée de requête dans les files d’attente

Comme mentionné dans la documentation, nous avons besoin d’un état propre pour chaque requête. Cela est géré automatiquement grâce à l’assistant RequestContext enregistré via middleware.

Mais les middlewares ne sont exécutés que pour des gestionnaires de requêtes HTTP réguliers, que faire si nous avons besoin d’une méthode de portée de requête en dehors de cela ? Un exemple de cela est les gestionnaires de files d’attente ou les tâches programmées.

Nous pouvons utiliser le décorateur @CreateRequestContext(). Il nécessite d’abord d’injecter l’instance MikroORM dans le contexte actuel, qui sera ensuite utilisée pour créer le contexte pour vous. En coulisses, le décorateur enregistrera un nouveau contexte de requête pour votre méthode et l’exécutera à l’intérieur du contexte.

Exécution dans un contexte de requête

@Injectable()
export class MyService {
  constructor(private readonly orm: MikroORM) {}

  @CreateRequestContext()
  async doSomething() {
    // cela sera exécuté dans un contexte séparé
  }
}

Attention

Comme le nom l’indique, ce décorateur crée toujours un nouveau contexte, contrairement à son alternative @EnsureRequestContext qui ne le crée que s’il n’est pas déjà à l’intérieur d’un autre.

Tests

Le package @mikro-orm/nestjs expose la fonction getRepositoryToken() qui renvoie un token préparé basé sur une entité donnée pour permettre le mocking du repository.

Test d'un module de photo

@Module({
  providers: [
    PhotoService,
    {
      // ou lorsque vous avez un repository personnalisé : `provide: PhotoRepository`
      provide: getRepositoryToken(Photo),
      useValue: mockedRepository,
    },
  ],
})
export class PhotoModule {}

Exemple

Un exemple concret de NestJS avec MikroORM peut être trouvé ici.