nestjs-query-mikro-orm

A NestJS Query adapter for MikroORM.

This package provides a QueryService implementation for MikroORM entities, designed to work with the NestJS Query ecosystem while staying database-agnostic.

What You Get ✨

• 🚀 Full QueryService CRUD support for MikroORM repositories
• 🔍 Filtering, sorting, paging, and count support
• 🔗 Relation operations:
  • queryRelations
  • findRelation
  • countRelations
  • aggregateRelations
  • add/set/remove relation helpers
• 📊 Aggregate queries with groupBy support
• 🧹 Soft delete support
• ⚙️ Configurable relation loading behavior:
  • native-first relation loading
  • MikroORM relation strategy control (select-in, joined, balanced)
  • optional dataloader forwarding for native relation loads
• 🧠 TypeScript-first API
• 📦 ESM and CJS package output

Installation 📥

pnpm add nestjs-query-mikro-orm

# peer dependencies (minimum typical setup)
pnpm add @mikro-orm/core @mikro-orm/decorators @mikro-orm/nestjs
pnpm add @nestjs/common @nestjs/core @ptc-org/nestjs-query-core
pnpm add class-transformer reflect-metadata rxjs

If you plan to enable dataloader-based native relation loading, also install:

pnpm add dataloader

Compatibility ✅

• Node.js: >= 18
• NestJS: 10 or 11
• MikroORM: 7
• @ptc-org/nestjs-query-core: 9.4+

The package supports both ESM and CommonJS consumers.

Quick Start 🚀

1. Define an entity

import { Entity, PrimaryKey, Property } from '@mikro-orm/core';

@Entity()
export class UserEntity {
  @PrimaryKey()
  id!: number;

  @Property()
  name!: string;

  @Property()
  email!: string;
}

2. Register the feature module

import { Module } from '@nestjs/common';
import { NestjsQueryMikroOrmModule } from 'nestjs-query-mikro-orm';
import { UserEntity } from './user.entity';

@Module({
  imports: [NestjsQueryMikroOrmModule.forFeature([UserEntity])],
})
export class UserModule {}

3. Use the service

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@mikro-orm/nestjs';
import { EntityRepository } from '@mikro-orm/core';
import { MikroOrmQueryService } from 'nestjs-query-mikro-orm';
import { UserEntity } from './user.entity';

@Injectable()
export class UserService extends MikroOrmQueryService<UserEntity> {
  constructor(@InjectRepository(UserEntity) readonly repo: EntityRepository<UserEntity>) {
    super(repo);
  }
}

Feature Module Options ⚙️

You can pass options to forFeature to configure generated QueryService providers.

forFeature supports both signatures:

• forFeature([Entity], 'contextName')
• forFeature([Entity], { contextName, queryServiceOpts })

import { NestjsQueryMikroOrmModule } from 'nestjs-query-mikro-orm';

NestjsQueryMikroOrmModule.forFeature([UserEntity], {
  contextName: 'default',
  queryServiceOpts: {
    useSoftDelete: true,
    relationLoading: {
      strategy: 'select-in',
      useDataloader: true,
    },
  },
});

relationLoading options

• strategy:
  • select-in: force MikroORM select-in loading strategy for native relation population
  • joined: force MikroORM joined loading strategy for native relation population
  • balanced: force MikroORM balanced loading strategy for native relation population
  • omitted: use MikroORM default strategy
• useDataloader:
  • when true, native relation load paths forward dataloader: true to MikroORM relation loading

Soft Delete 🧹

Enable soft delete behavior by passing useSoftDelete in service options.

super(repo, { useSoftDelete: true });

When enabled, read operations automatically include deletedAt = null filtering, and restoreOne/restoreMany become available.

Relation Loading Notes 🔄

• Relation reads are native-first and use MikroORM population/identity-map semantics.
• If native extraction cannot resolve a relation shape (common with not-managed/custom hydrator flows), the adapter safely falls back to condition-based relation querying.
• useDataloader is applied to native relation loading paths, including batched relation resolution.
• For best dataloader results, enable MikroORM dataloaders in ORM config and execute relation loads in a batched execution frame.

Integration with NestJS Query GraphQL 🧩

This library focuses on QueryService behavior. You can plug it into your NestJS Query GraphQL setup as your backing service implementation.

Use relation decorators/resolvers from your GraphQL layer as usual; relation methods from this adapter are compatible with request-scoped loader patterns used by NestJS Query GraphQL.

Public API 📚

Main exports include:

• NestjsQueryMikroOrmModule
• MikroOrmQueryService
• RelationQueryService
• Query builder helpers from the query export

Development 🛠️

Prerequisites 📋

• Node.js >= 18
• pnpm >= 9

Setup 🧪

pnpm install
pnpm prepare

Scripts 🏃

pnpm build
pnpm dev
pnpm test
pnpm test:watch
pnpm test:coverage
pnpm lint
pnpm lint:fix
pnpm format
pnpm format:check
pnpm typecheck

Contributing 🤝

Contributions are welcome.

1. Fork the repository
2. Create your branch
3. Commit your changes
4. Push your branch
5. Open a pull request

License 📄

MIT