nestjs-query-mikro-orm 0.1.3 → 0.1.5

package/README.md

@@ -1,56 +1,59 @@
 # nestjs-query-mikro-orm
 
-A [NestJS Query](https://github.com/tripss/nestjs-query) adapter for [MikroORM](https://mikro-orm.io/).
+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 📥
 
-This library provides a seamless integration between NestJS Query and MikroORM, allowing you to build powerful GraphQL APIs with minimal boilerplate.
-
-## Features
-
-- 🚀 Full NestJS Query support with MikroORM
-- 📦 Type-safe query building
-- 🔍 Advanced filtering and sorting
-- 🔗 Relation query support
-- 📊 Aggregation queries
-- 🎯 Soft delete support
-- ✨ Built with TypeScript
-- 📦 Dual-format support (ESM & CommonJS)
-
-## Compatibility
-
-This package supports both **ES Modules (ESM)** and **CommonJS (CJS)** for maximum compatibility across different Node.js environments and bundlers.
-
-- **ESM**: `import { MikroOrmQueryService } from 'nestjs-query-mikro-orm'`
-- **CommonJS**: `const { MikroOrmQueryService } = require('nestjs-query-mikro-orm')`
+```bash
+pnpm add nestjs-query-mikro-orm
 
-The package automatically detects the import method and serves the appropriate format.
+# 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
+```
 
-## Installation
+If you plan to enable dataloader-based native relation loading, also install:
 
 ```bash
-pnpm add nestjs-query-mikro-orm
-
-# Install peer dependencies if you haven't already
-pnpm add @mikro-orm/core @nestjs/common @nestjs/core @ptc-org/nestjs-query-core reflect-metadata rxjs
+pnpm add dataloader
 ```
 
-## Quick Start
+## Compatibility ✅
 
-### 1. Setup MikroORM Module
+- Node.js: >= 18
+- NestJS: 10 or 11
+- MikroORM: 7
+- @ptc-org/nestjs-query-core: 9.4+
 
-```typescript
-import { NestQueryMikroOrmModule } from 'nestjs-query-mikro-orm';
-import { Module } from '@nestjs/common';
-import { UserEntity } from './user.entity';
+The package supports both ESM and CommonJS consumers.
 
-@Module({
-  imports: [NestQueryMikroOrmModule.forFeature([UserEntity])],
-})
-export class UserModule {}
-```
+## Quick Start 🚀
 
-### 2. Create Your Entity
+### 1. Define an entity
 
-```typescript
+```ts
 import { Entity, PrimaryKey, Property } from '@mikro-orm/core';
 
 @Entity()
@@ -63,112 +66,144 @@ export class UserEntity {
 
   @Property()
   email!: string;
-
-  @Property()
-  createdAt: Date = new Date();
 }
 ```
 
-### 3. Use the Query Service
+### 2. Register the feature module
+
+```ts
+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 {}
+```
 
-```typescript
+### 3. Use the service
+
+```ts
 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> {
-  // Your custom methods here
+  constructor(@InjectRepository(UserEntity) readonly repo: EntityRepository<UserEntity>) {
+    super(repo);
+  }
 }
 ```
 
-## Development
+## Feature Module Options ⚙️
 
-### Prerequisites
+You can pass options to forFeature to configure generated QueryService providers.
 
-- Node.js >= 18
-- pnpm >= 9
+`forFeature` supports both signatures:
 
-### Setup
+- `forFeature([Entity], 'contextName')`
+- `forFeature([Entity], { contextName, queryServiceOpts })`
 
-```bash
-# Install dependencies
-pnpm install
+```ts
+import { NestjsQueryMikroOrmModule } from 'nestjs-query-mikro-orm';
 
-# Setup git hooks
-pnpm prepare
+NestjsQueryMikroOrmModule.forFeature([UserEntity], {
+  contextName: 'default',
+  queryServiceOpts: {
+    useSoftDelete: true,
+    relationLoading: {
+      strategy: 'select-in',
+      useDataloader: true,
+    },
+  },
+});
 ```
 
-### Available Scripts
+### relationLoading options
 
-```bash
-# Build the library
-pnpm build
+- 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
 
-# Build in watch mode
-pnpm dev
+## Soft Delete 🧹
 
-# Run tests
-pnpm test
+Enable soft delete behavior by passing useSoftDelete in service options.
 
-# Run tests in watch mode
-pnpm test:watch
+```ts
+super(repo, { useSoftDelete: true });
+```
 
-# Run tests with coverage
-pnpm test:coverage
+When enabled, read operations automatically include deletedAt = null filtering, and restoreOne/restoreMany become available.
 
-# Lint code
-pnpm lint
+## Relation Loading Notes 🔄
 
-# Fix lint issues
-pnpm lint:fix
+- 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.
 
-# Format code
-pnpm format
+## Integration with NestJS Query GraphQL 🧩
 
-# Check formatting
-pnpm format:check
+This library focuses on QueryService behavior. You can plug it into your NestJS Query GraphQL setup as your backing service implementation.
 
-# Type check
-pnpm typecheck
-```
+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:
 
-### Git Hooks
+- NestjsQueryMikroOrmModule
+- MikroOrmQueryService
+- RelationQueryService
+- Query builder helpers from the query export
 
-This project uses Husky for git hooks:
+## Development 🛠️
 
-- **pre-commit**: Runs lint-staged to format and lint staged files
-- **pre-push**: Runs lint, typecheck, and tests before pushing
-- **commit-msg**: Validates commit messages using commitlint
+### Prerequisites 📋
 
-### Commit Convention
+- Node.js >= 18
+- pnpm >= 9
 
-This project follows [Conventional Commits](https://www.conventionalcommits.org/):
+### Setup 🧪
 
 ```bash
-feat: add new feature
-fix: fix bug
-docs: update documentation
-style: format code
-refactor: refactor code
-test: add tests
-chore: update dependencies
+pnpm install
+pnpm prepare
 ```
 
-## License
+### Scripts 🏃
 
-MIT
+```bash
+pnpm build
+pnpm dev
+pnpm test
+pnpm test:watch
+pnpm test:coverage
+pnpm lint
+pnpm lint:fix
+pnpm format
+pnpm format:check
+pnpm typecheck
+```
 
-## Author
+## Contributing 🤝
 
-Manuel Antunes
+Contributions are welcome.
 
-## Contributing
+1. Fork the repository
+2. Create your branch
+3. Commit your changes
+4. Push your branch
+5. Open a pull request
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+## License 📄
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+MIT