Middleware de Mongoose: hooks pre y post

El middleware de Mongoose (también llamado hooks) está formado por funciones que se ejecutan antes o después de operaciones específicas como save, find, updateOne, deleteOne y otras. Permite insertar lógica personalizada en el ciclo de vida de las operaciones de documentos y consultas sin sobrecargar los manejadores de rutas. Entre sus usos habituales se incluyen aplicar hash a contraseñas antes de guardarlas, registrar los tiempos de las consultas, aplicar eliminaciones lógicas y completar datos relacionados después de find.

Mongoose tiene dos categorías distintas de middleware: el middleware de documentos se enlaza a operaciones sobre una instancia específica de Document (save, validate, remove, init). El middleware de consultas se enlaza a operaciones de consulta invocadas sobre el Model (find, findOne, updateOne, deleteOne, etc.). La diferencia clave es a qué hace referencia this: en el middleware de documentos, this es el documento; en el middleware de consultas, this es el objeto Query.

El hook pre-save es el middleware de documentos más habitual. Se ejecuta antes de guardar un documento en MongoDB. El caso de uso canónico es aplicar hash a las contraseñas: cuando se guarda un documento de usuario con una contraseña nueva o modificada, aplíquele bcrypt antes de almacenarla. La comprobación this.isModified('password') evita volver a aplicar hash a una contraseña que ya tiene hash durante guardados no relacionados.

El middleware de documentos tiene acceso a ayudantes de seguimiento: this.isNew es true cuando el documento se inserta por primera vez (no cuando se actualiza). this.isModified(path) devuelve true si el campo especificado ha cambiado desde la última vez que se guardó o se obtuvo el documento. Estos ayudantes permiten ejecutar hooks de forma condicional: solo durante la creación o solo cuando cambia un campo específico.

Los hooks post-save se ejecutan después de que un documento se haya guardado correctamente. Reciben el documento guardado como primer argumento y, en versiones antiguas de Mongoose, un callback next. Los hooks post son ideales para efectos secundarios que deben producirse después de un guardado correcto: enviar un correo electrónico de bienvenida, actualizar un índice de búsqueda, publicar un evento en una cola de mensajes o borrar una caché. Los errores en los hooks post no revierten el guardado.

Un patrón clásico de middleware de consultas es implementar eliminaciones lógicas. En lugar de eliminar los documentos, establezca un campo deletedAt. Después, añada un hook pre('find') que agregue automáticamente { deletedAt: null } a cada consulta find, para garantizar que los documentos eliminados nunca se devuelvan de forma predeterminada. Esto proporciona un registro de auditoría y, al mismo tiempo, hace que la lógica de eliminación lógica sea transparente para el resto de la aplicación.

Puede usar middleware de consultas para completar automáticamente un campo de referencia en cada find. Esto garantiza que un documento referenciado siempre se resuelva sin exigir a quienes llaman que añadan .populate() a cada consulta. Aunque resulta práctico, tenga cuidado: la cumplimentación automática añade una segunda consulta por cada find y puede degradar el rendimiento si la referencia es grande o no siempre se necesita.

Mongoose no aplica automáticamente las eliminaciones en cascada (eliminar documentos relacionados cuando se elimina un documento principal). Puede implementar el comportamiento en cascada mediante middleware de documentos. Un hook pre-deleteOne en un modelo User puede eliminar todas las publicaciones, comentarios y sesiones pertenecientes a ese usuario antes de eliminar el propio documento de usuario. Esto mantiene la integridad referencial sin restricciones de claves foráneas.

Si una función pre-hook lanza un error o rechaza una Promise, se aborta la operación a la que precede. Esto permite realizar comprobaciones de validación o autorización en el middleware y abortar guardados o consultas lanzando un error. Por ejemplo, un hook pre-save que valide la lógica de negocio (no solo la validación del esquema) puede lanzar un error que llegue hasta el bloque catch de la llamada a .save() en el código de la aplicación.

Mongoose también admite middleware para pipelines de agregación. Un hook pre-aggregate proporciona acceso al array del pipeline antes de enviarlo a MongoDB, lo que permite anteponer etapas (como filtrar documentos eliminados lógicamente) o añadir etapas al final (como insertar un límite predeterminado). Acceda al pipeline mediante this.pipeline() dentro de la función del hook.

No todas las operaciones de escritura activan el middleware de documentos. updateMany(), findOneAndUpdate() y replaceOne() llamados sobre el Model (no sobre una instancia) omiten los hooks de save de documentos; son middleware de consultas y necesitan hooks independientes si desea interceptarlos. Por ejemplo, un hook de hash de contraseñas previo a save NO se ejecuta al llamar a User.updateOne({}, { $set: { password: plain } }). Realice siempre el hash en el código de la aplicación para las actualizaciones basadas en consultas.

En esta lección aprendió que: los hooks previos se ejecutan antes de una operación y pueden cancelarla al lanzar un error; los hooks posteriores se ejecutan después y reciben el resultado como argumento, el middleware de documentos (pre-save, pre-deleteOne) usa 'this' como el documento, mientras que el middleware de consultas usa 'this' como el objeto Query, y los métodos de escritura a nivel de consulta (updateOne, updateMany, findOneAndUpdate) omiten el middleware de documentos; tenga siempre en cuenta qué hooks se activan para cada tipo de operación. ¡Con esto termina el itinerario del curso de MongoDB y bases de datos NoSQL!