mongino

Driver con API estilo MongoDB/Mongoose que guarda toda la base de datos en un único fichero .db, con motor B-Tree en memoria y persistencia binaria cifrada. Sin servidor, sin dependencias nativas.

📖 Documentación completa de la API →

bun install
bun test
bun examples/demo.ts

Uso rápido

import { MongoLite, SchemaTypes, type Document } from "mongino";

interface User extends Document {
  nombre: string;
  email: string;
  edad: number;
}

const db = new MongoLite("data/app.db", {
  degree: 16,                        // grado del B-Tree
  encryptionKey: process.env.DB_KEY, // opcional, pero recomendado
});

const User = db.model<User>("User", {
  nombre: { type: SchemaTypes.String, required: true, trim: true },
  email:  { type: SchemaTypes.String, required: true, unique: true, lowercase: true },
  edad:   { type: SchemaTypes.Number, required: true, min: 0, max: 130 },
}, { timestamps: true });

await User.create({ nombre: "Ada", email: "[email protected]", edad: 36 });

const adultos = await User.find({ edad: { $gte: 18 } })
  .sort("-edad")
  .limit(10)
  .select({ nombre: 1, edad: 1 });

db.close(); // vuelca los cambios y libera el bloqueo

Qué trae

• API familiar: create, find, findOne, findById, updateOne, updateMany, deleteMany, populate, sort, skip, limit, select…
• Operadores de MongoDB: $gt $gte $lt $lte $in $nin $ne $regex $exists $type $all $size $elemMatch $mod $not $or $and $nor y rutas anidadas.
• Operadores de actualización: $set $unset $inc $mul $min $max $push $addToSet $pull $pop $rename $currentDate $setOnInsert.
• Schemas con validación: required, default, unique, min/max, enum, match, immutable, trim/lowercase, cast, validadores propios (sync o async), timestamps y modo strict.
• Índices en memoria para los campos unique e index: true: igualdad, $in y rangos ($gt/$lt/…) sin recorrer la colección.
• Transacciones con rollback: db.transaction(async () => { ... }).
• Copias y volcados: db.backup(ruta), db.exportJSON(), db.importJSON().

El fichero .db

El contenido no es JSON ni texto legible: se serializa por bloques, se comprime con deflate y se cifra con AES-256-GCM (clave derivada con scrypt). Abrirlo con un editor solo muestra bytes opacos y cualquier manipulación se detecta al abrirlo.

Sin encryptionKey el fichero queda ofuscado pero no es confidencial (la clave interna está en el código). Para confidencialidad real pasa tu propia encryptionKey; sin ella el fichero no se puede abrir.

Garantías de durabilidad (detalle):

• Escritura atómica: temporal → fsync → rename → fsync del directorio.
• Recuperación: si el proceso muere a mitad de un guardado, al abrir se recupera el temporal.
• Nunca se descarta un fichero ilegible en silencio: se conserva una copia .corrupt-<timestamp> y se lanza StorageError.
• Bloqueo entre procesos: dos instancias sobre el mismo fichero fallan al abrir en vez de pisarse las escrituras (los bloqueos huérfanos se reciclan).
• Validación previa: un documento no almacenable se rechaza antes de entrar en memoria, así que nunca deja la base de datos sin poder persistir.
• Reversión: si un batch o una transaction lanza, se revierte entero; no se persiste a medias.
• Escrituras serializadas: dos operaciones simultáneas sobre el mismo documento no se pisan, y los campos unique se respetan bajo concurrencia.
• Aislamiento: lo almacenado es una copia propia, así que modificar un documento que te devolvió una consulta no altera la base de datos.

Rendimiento

Medido con 20.000 documentos de ~150 bytes:

| Operación | Coste | | --- | --- | | findById o campo indexado | < 1 ms | | Rango selectivo sobre campo indexado | ~1 ms | | find por campo sin índice | ~20 ms | | create / update individual | ~11 ms | | insertMany de 20.000 | ~310 ms | | Abrir y cargar el fichero | ~108 ms |

Cada escritura solo reserializa el fragmento del fichero al que pertenece el documento, no la base entera. Aun así, la base vive en memoria y el fichero se reescribe en disco en cada guardado: agrupa las escrituras masivas con insertMany, batchAsync o transaction. Máximo 16 MB por documento.

Desarrollo

bun test              # 164 tests
bun run typecheck
bun run build         # genera dist/ (ESM + tipos)