mongoose-monk-compat

Una biblioteca ligera que proporciona una API compatible con Mongoose pero usando Monk como backend para MongoDB. Diseñada especialmente para aplicaciones NestJS que buscan una alternativa más sencilla a Mongoose sin tener que reescribir todo el código que depende de su API.

Características

• 🔄 API familiar: Interfaz similar a Mongoose para una migración gradual
• 🚀 Rendimiento: Aprovecha la velocidad y simplicidad de Monk
• 🔌 Fácil integración: Módulo personalizado para NestJS con inyección de dependencias
• 📦 Ligero: Sin las complejidades innecesarias del ORM completo
• 🔒 TypeScript: Tipado completo para mejor desarrollo
• 🛠️ Flexible: Múltiples opciones de configuración y conexión

Instalación

npm install mongoose-monk-compat --save

Guía rápida

Configuración básica en NestJS

// app.module.ts
import { Module } from '@nestjs/common';
import { MongooseCompatModule } from 'mongoose-monk-compat';

@Module({
  imports: [
    MongooseCompatModule.forRoot({
      uri: 'mongodb://localhost:27017/mydatabase'
    }),
    // ... otros módulos
  ],
})
export class AppModule {}

Definir un modelo

// user.model.ts
import { Injectable } from '@nestjs/common';
import { InjectMonkCompatService, Model, createModel, createSchema, Types, Schema } from 'mongoose-monk-compat';
import { MonkCompatService } from 'mongoose-monk-compat';

// Definir la interfaz del documento
export interface User {
  _id?: string;
  username: string;
  email: string;
  active: boolean;
  createdAt?: Date;
}

// Definir el esquema
export const userSchema: Schema<User> = {
  username: { type: Types.String, required: true },
  email: { type: Types.String, required: true },
  active: { type: Types.Boolean, default: true },
  createdAt: { type: Types.Date, default: () => new Date() },
};

// Crear el modelo usando la clase
@Injectable()
export class UserModel {
  private model: Model<User>;

  constructor(@InjectMonkCompatService() private monkService: MonkCompatService) {
    this.model = createModel<User>(this.monkService, 'users', createSchema<User>(userSchema));
  }

  async findAll(): Promise<User[]> {
    return this.model.find();
  }

  async findById(id: string): Promise<User | null> {
    return this.model.findById(id);
  }

  async create(user: Partial<User>): Promise<User> {
    return this.model.create(user);
  }

  async update(id: string, user: Partial<User>): Promise<User | null> {
    return this.model.findByIdAndUpdate(id, { $set: user }, { new: true });
  }

  async delete(id: string): Promise<User | null> {
    return this.model.findByIdAndDelete(id);
  }
}

Usar el modelo en un servicio

// user.service.ts
import { Injectable } from '@nestjs/common';
import { User, UserModel } from './user.model';

@Injectable()
export class UserService {
  constructor(private userModel: UserModel) {}

  async getAllUsers(): Promise<User[]> {
    return this.userModel.findAll();
  }

  async getUserById(id: string): Promise<User | null> {
    return this.userModel.findById(id);
  }

  async createUser(userData: Partial<User>): Promise<User> {
    return this.userModel.create(userData);
  }
}

Registrar el modelo en el módulo

// users.module.ts
import { Module } from '@nestjs/common';
import { UserModel } from './user.model';
import { UserService } from './user.service';
import { UserController } from './user.controller';

@Module({
  providers: [UserModel, UserService],
  controllers: [UserController],
  exports: [UserService],
})
export class UsersModule {}

Opciones de configuración

forRoot

El método forRoot acepta varias opciones para configurar la conexión a MongoDB:

MongooseCompatModule.forRoot({
  // URI directa de MongoDB (prioridad más alta)
  uri: 'mongodb://username:password@localhost:27017/mydatabase',
  
  // O ruta al archivo secreto que contiene la URI (usado si no se provee uri)
  secretPath: '/path/to/mongodb-secret',
  
  // O nombre de variable de entorno (usado si no se encuentra secretPath)
  envName: 'MONGODB_URI',
  
  // Opciones adicionales para monk
  connectionOptions: {
    useUnifiedTopology: true
  }
});

Orden de prioridad para la conexión

1. uri explícitamente proporcionada
2. Variable de entorno especificada en envName
3. Archivo de secreto en secretPath
4. Archivo en /run/secrets/mongodb-connection-string (para Docker Swarm)
5. Fallback a mongodb://localhost:27017/mydatabase

API completa

MongooseCompatModule

• forRoot(options): Configura el módulo con una conexión a MongoDB
• forFeature(collections): Registra colecciones específicas para un módulo

Model

Proporciona una API similar a Mongoose para interactuar con MongoDB:

• find(filter?, options?): Busca documentos que cumplen con el filtro
• findOne(filter?, options?): Busca un único documento
• findById(id): Busca un documento por ID
• create(doc): Crea un nuevo documento
• createMany(docs): Crea múltiples documentos
• findOneAndUpdate(filter, update, options?): Actualiza un documento
• findByIdAndUpdate(id, update, options?): Actualiza por ID
• updateMany(filter, update, options?): Actualiza múltiples documentos
• findOneAndDelete(filter): Elimina un documento
• findByIdAndDelete(id): Elimina por ID
• deleteMany(filter): Elimina múltiples documentos
• countDocuments(filter?): Cuenta documentos
• aggregate(pipeline): Realiza una agregación

SchemaBuilder

Define esquemas similares a los de Mongoose:

• getSchema(): Obtiene el esquema definido

Decoradores

• @InjectMonkCompatService(): Inyecta el servicio MonkCompatService

Comparación con Mongoose

| Característica | mongoose-monk-compat | Mongoose | |---------------|---------------------|----------| | Modelos | ✅ Simplificados | ✅ Completos | | Esquemas | ✅ Básicos | ✅ Avanzados | | Middlewares | ❌ No soportados | ✅ Soportados | | Validación | ✅ Básica | ✅ Avanzada | | Hooks | ❌ No soportados | ✅ Soportados | | Virtualización | ❌ No soportada | ✅ Soportada | | Rendimiento | ✅✅ Mejor | ✅ Bueno | | Footprint | ✅✅ Ligero | ❌ Pesado |

Mejores prácticas

1. Separa modelos y esquemas: Mantén tus definiciones de esquema y modelos en carpetas dedicadas
2. Usa clases para los modelos: Implementa lógica de negocio en clases de modelo
3. Encapsula queries complejas: Crea métodos específicos para consultas frecuentes
4. Evita manipulación directa de colecciones: Usa siempre la API de Model

Migración desde Mongoose

Para migrar una aplicación desde Mongoose:

1. Reemplaza importaciones:

   // De esto:
   import { Model, Schema } from 'mongoose';
      
   // A esto:
   import { Model, Schema } from 'mongoose-monk-compat';

2. Reemplaza decoradores:

   // De esto:
   import { InjectModel } from '@nestjs/mongoose';
      
   // A esto:
   import { InjectMonkCompatService } from 'mongoose-monk-compat';

3. Ajusta la inicialización:

   // De esto:
   constructor(@InjectModel('User') private userModel: Model<User>) {}
      
   // A esto:
   constructor(@InjectMonkCompatService() private monkService: MonkCompatService) {
     this.userModel = createModel<User>(this.monkService, 'users', userSchema);
   }

Limitaciones conocidas

• No soporta todas las características avanzadas de Mongoose (middlewares, virtualización)
• Las validaciones son más básicas que en Mongoose
• No hay soporte para relaciones/poblados automatizados tipo populate()
• Los hooks de pre/post operación no están implementados

Contribuir

¡Las contribuciones son bienvenidas! Por favor, sigue estos pasos:

1. Haz fork del repositorio
2. Crea una rama para tu característica (git checkout -b feature/amazing-feature)
3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
4. Haz push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.