@jysperu/load-mongodb

Paquete de JYS Perú para inicializar y gestionar conexiones a MongoDB con configuración lista para producción, junto con utilidades para manejo de errores, modelos y schemas de Mongoose.

Instalación

npm install @jysperu/load-mongodb

Requiere Node.js >=18. Incluye mongoose como dependencia directa.

Uso básico

import { connect, getInstance, disconnect } from "@jysperu/load-mongodb";

// Conectar usando la variable de entorno MONGODB_URI
await connect();

// Forma abreviada: pasar solo el callback de éxito
await connect((instance) => console.log("Conectado"));

// O con opciones explícitas
await connect({
  uri: "mongodb://localhost:27017/midb",
  onSuccess: (instance) => console.log("Conectado"),
  onError: (error) => console.error("Error:", error.message),
});

// También compatible con la firma de mongoose: connect(uri, options)
await connect("mongodb://localhost:27017/midb", {
  serverSelectionTimeoutMS: 3000,
  enableAutoDisconnect: { signals: ["SIGINT", "SIGTERM"], onBeforeExit: true },
});

// Obtener la instancia por defecto en cualquier parte del código
const mongoose = await getInstance();

// Cerrar todas las conexiones (ideal en graceful shutdown)
await disconnect();

Por defecto, connect() habilita auto-disconnect para ejecutar cierre limpio en señales de proceso.

Importaciones recomendadas

Para bundles más pequeños en aplicaciones consumidoras, importa por subpath cuando solo necesites utilidades:

import { TheMongoError, CloneSchemaOf } from "@jysperu/load-mongodb/helpers";
import { connect, getInstance } from "@jysperu/load-mongodb/mongodb";

El import raíz (@jysperu/load-mongodb) sigue disponible por compatibilidad.

Variables de entorno

| Variable | Descripción | | ------------- | --------------------------------------------------- | | MONGODB_URI | URI de conexión. Sobreescribe el valor por defecto. | | MONGO_URI | URI alternativa usada como fallback. |

API

Conexión

connect(uri?, options?): Promise<Mongoose | false>

Inicializa una conexión a MongoDB. Acepta:

• Sin argumentos — usa ConnectOptionsDefaults y MONGODB_URI del entorno.
• OnSuccessCallback — forma abreviada; el callback se ejecuta al conectar.
• Objeto de opciones — fusionado con ConnectOptionsDefaults y las variables de entorno.
• uri como primer parámetro — compatible con la firma de mongoose.connect(uri, options).

// Sin argumentos
await connect();

// Forma abreviada
await connect((instance) => console.log("Listo"));

// Con opciones
await connect({ uri: "mongodb://localhost:27017/app", serverSelectionTimeoutMS: 3000 });

// Con URI explícita + opciones
await connect("mongodb://localhost:27017/app", { serverSelectionTimeoutMS: 3000 });

Precedencia de URI: uri del primer parámetro > options.uri > MONGODB_URI > MONGO_URI > default interno.

Retorna la instancia de Mongoose conectada, o false si falló.

getInstance(): Promise<Mongoose>

Devuelve la primera instancia conectada. Si no hay ninguna, intenta conectar con los valores por defecto.

getInstances(): Promise<Mongoose[]>

Devuelve todas las instancias registradas (útil en arquitecturas multi-DB).

disconnect(): Promise<void>

Cierra todas las conexiones y limpia el estado interno.

Auto-disconnect

enableAutoDisconnect(options?): void

Registra listeners para cerrar conexiones automáticamente al finalizar el proceso:

• Señales por defecto: SIGINT (Ctrl+C) y SIGTERM.
• También ejecuta en beforeExit por defecto.

import { enableAutoDisconnect } from "@jysperu/load-mongodb";

enableAutoDisconnect({
  signals: ["SIGINT", "SIGTERM"],
  onBeforeExit: true,
});

autoDisconnect(): void

Alias de enableAutoDisconnect().

disableAutoDisconnect(): void

Desactiva solo los listeners de auto-disconnect registrados por este paquete, sin tocar listeners externos del proceso.

Alias exportados

Por compatibilidad con distintos estilos de importación, se exportan los siguientes alias:

| Alias | Original | | ------------------- | -------------- | | connectMongoDB | connect | | disconnectMongoDB | disconnect | | getMongoInstance | getInstance | | getMongoInstances | getInstances |

El export por defecto apunta a connectMongoDB:

import connectMongoDB from "@jysperu/load-mongodb";

getEnvDefaults()

Devuelve las opciones extraídas de variables de entorno. Actualmente lee MONGODB_URI.

ConnectOptionsDefaults

Valores por defecto aplicados a cada conexión:

| Opción | Valor | | -------------------------- | ----------------------------------- | | uri | mongodb://localhost:27017/default | | timeoutMS | 2000 | | autoCreate | true | | autoIndex | true | | maxPoolSize | 50 | | minPoolSize | 5 | | serverSelectionTimeoutMS | 5000 | | socketTimeoutMS | 45000 | | connectTimeoutMS | 10000 | | family | 4 (solo IPv4) | | enableAutoDisconnect | true |

enableAutoDisconnect también puede configurarse por conexión:

await connect({
  uri: "mongodb://localhost:27017/app",
  enableAutoDisconnect: false,
});

await connect({
  uri: "mongodb://localhost:27017/app",
  enableAutoDisconnect: { signals: ["SIGINT"], onBeforeExit: false },
});

Manejo de errores

TheMongoError(error, fallback?): string

Interpreta un error de Mongoose y devuelve un mensaje legible para el usuario. Cubre:

| Error | Mensaje | | ----------------------------------- | ------------------------------------------------------------------ | | ValidationError (campo requerido) | No se ha establecido el valor de X. | | ValidationError (user defined) | El mensaje personalizado del validador | | CastError | El valor "X" no es válido para el campo "Y" (se esperaba Z). | | DocumentNotFoundError | No se encontró el registro solicitado. | | VersionError | El registro fue modificado por otra operación... | | ParallelSaveError | El registro está siendo guardado por otra operación... | | 11000 / 11001 (duplicado) | Ya hay un registro con campo = "valor" | | 121 (JSON Schema servidor) | El registro no cumple con las reglas de validación del servidor. | | 112 (write conflict) | Conflicto al guardar el registro... | | 50 (maxTimeMS) | La operación tardó demasiado y fue cancelada... | | 13 (sin autorización) | No tienes permisos para realizar esta operación. |

import { TheMongoError } from "@jysperu/load-mongodb";

try {
  await doc.save();
} catch (ex) {
  const mensaje = TheMongoError(ex, "Error al guardar el usuario");
  res.status(400).json({ error: mensaje });
}

Utilidades de modelos

CreateMongoSaver(MongoModel, nombre?)

Fábrica que devuelve una función guardar(doc, fallback?) lista para persistir documentos. Ejecuta validate() antes de save() e interpreta los errores automáticamente.

import { CreateMongoSaver } from "@jysperu/load-mongodb";
import { Usuario } from "./models/usuario.js";

const guardarUsuario = CreateMongoSaver(Usuario, "usuario");

const result = await guardarUsuario({ nombre: "Juan", email: "[email protected]" });

if (result.success) {
  console.log(result.usuario); // instancia guardada
} else {
  console.error(result.error); // mensaje legible
}

CloneSchemaOf(BaseSchema, clears?)

Clona un Schema de Mongoose eliminando selectivamente required, default, unique e index de sus paths. Útil para schemas parciales en formularios de edición.

import { CloneSchemaOf } from "@jysperu/load-mongodb";
import { UsuarioSchema } from "./schemas/usuario.js";

// Clonar sin required ni defaults (para un formulario de actualización parcial)
const UsuarioParcialSchema = CloneSchemaOf(UsuarioSchema, { requireds: true, defaults: true });

generateObjectFromSchema(schema, extra?)

Genera un objeto plano con los valores default estáticos del schema. Omite _id, __v y defaults que sean funciones.

import { generateObjectFromSchema } from "@jysperu/load-mongodb";
import { UsuarioSchema } from "./schemas/usuario.js";

const defaults = generateObjectFromSchema(UsuarioSchema, { rol: "invitado" });
// { activo: true, rol: "invitado" }

Tipos re-exportados

Para comodidad, el paquete re-exporta los tipos y utilidades más usados de Mongoose:

import {
  Document,
  Model,
  Schema,
  HydratedDocument,
  InferSchemaType,
  InferDocument, // HydratedDocument<InferSchemaType<TSchema>>
  connect,
  model,
} from "@jysperu/load-mongodb";

Scripts

npm test            # Ejecuta los tests una sola vez (vitest run)
npm run test:watch  # Modo watch
npm run build       # Compila ESM + CJS + tipos (vite build)

Los tests están divididos en tres suites:

• connection.test.ts — integración real con MongoDB usando mongodb-memory-server (connect, getInstance, getInstances, disconnect).
• helpers.test.ts — tests unitarios de TheMongoError, CreateMongoSaver, CloneSchemaOf y generateObjectFromSchema.
• mongodb.test.ts — tests unitarios de ConnectOptionsDefaults y getEnvDefaults.

Licencia

MIT © JYS Perú