MongoDB
Explica cómo tipar documentos, colecciones, filtros, updates y resultados del driver sin confundir tipos de TypeScript con validación real de datos.
TypeScript mejora autocomplete y detecta incompatibilidades durante desarrollo, pero no valida JSON recibido ni documentos existentes. Un tipo es una promesa del código; el dato BSON sigue siendo runtime.
input HTTP
→ validación runtime
→ modelo de dominio
→ documento BSON
→ DTO públicoSeparar estas representaciones evita assertions, fugas de campos y conversiones incorrectas.
type OrderDocument = {
_id: ObjectId;
businessId: ObjectId;
status: 'pending' | 'confirmed' | 'cancelled';
total: Decimal128;
createdAt: Date;
schemaVersion: number;
};Este tipo describe cómo esperas encontrar el documento. No demuestra que todos los registros cumplan. Usa schema validation, migraciones y lectura defensiva.
type CreateOrderInput = {
items: Array<{
productId: string;
quantity: number;
}>;
};Valídalo con Zod, Valibot u otra librería:
const input = createOrderSchema.parse(req.body);Después convierte IDs y tipos. No aceptes businessId, total calculado o estados internos desde el cliente.
El dominio puede usar tipos más cómodos o value objects:
type Money = {
amount: string;
currency: 'COP';
};La capa de persistencia transforma a Decimal128. Así la decisión de BSON no contamina toda la aplicación.
type OrderDto = {
id: string;
status: string;
total: string;
createdAt: string;
};Nunca serialices documentos directamente. ObjectId, Decimal128 y Date requieren representación explícita, y campos internos como businessId, version o secretos pueden no pertenecer a la API.
El driver ofrece Filter<T>, UpdateFilter<T>, OptionalUnlessRequiredId<T> y otros helpers. Son útiles dentro de la capa de datos:
const filter: Filter<OrderDocument> = {
businessId,
status: 'pending'
};No los expongas como contratos de controller. Permitir que una request construya Filter<T> es inseguro aunque compile.
Modela según persistencia real. Si MongoDB genera ObjectId:
type ProductDocument = {
_id: ObjectId;
};Para inserts, utiliza un tipo separado o helper del driver. No hagas _id?: ObjectId en todo el dominio si después de persistir siempre existe.
JavaScript number no representa todos los enteros de 64 bits ni decimales monetarios exactos.
const price = Decimal128.fromString('18.50');Convierte a string para DTO. Evita parseFloat si la precisión es contractual.
Usa Long o BigInt con una estrategia de serialización cuando los valores superen Number.MAX_SAFE_INTEGER.
El servidor distingue tipos; schema drift puede afectar sort, comparación y índices aunque TypeScript declare solo number.
Persistencia:
createdAt: new Date()API:
createdAt: document.createdAt.toISOString()Valida que runtime sea Date. Un documento viejo puede contener string y romper .toISOString().
Estos estados son distintos:
middleName?: string | null;Define semántica y queries. Partial<T> no expresa automáticamente cómo MongoDB trata $unset o null.
Una projection devuelve un subtipo. No declares que retorna OrderDocument completo:
type OrderListItem = Pick<
OrderDocument,
'_id' | 'status' | 'total' | 'createdAt'
>;const rows = await orders.find<OrderListItem>(filter, {
projection: {
status: 1,
total: 1,
createdAt: 1
}
}).toArray();Confirma la API del driver actual y evita casts para silenciar incompatibilidades.
El driver no puede inferir siempre la salida de pipelines complejos. Define el tipo final:
type DailySales = {
day: Date;
total: Decimal128;
orders: number;
};
const result = orders.aggregate<DailySales>(pipeline);Esto tampoco valida runtime. Añade tests y validación en boundaries críticos.
Para documentos polimórficos:
type PaymentDocument =
| {
type: 'cash';
received: Decimal128;
}
| {
type: 'card';
providerReference: string;
};Schema validation debe reflejar variantes. Maneja un type desconocido porque datos y código pueden evolucionar desincronizados.
Evita:
const order = raw as OrderDocument;Una assertion elimina la advertencia sin convertir ni validar. Prefiere parseo:
const order = orderDocumentSchema.parse(raw);o lectura tolerante por schemaVersion.
Puedes diferenciar IDs en compile time:
type OrderId = ObjectId & { readonly __brand: 'OrderId' };
type UserId = ObjectId & { readonly __brand: 'UserId' };Ayuda a evitar mezclas accidentales, pero no existe en runtime. La autorización y validación siguen siendo necesarias.
Modela resultados de dominio, no todos los errores del driver como un union imposible. En la capa de infraestructura traduce:
Conserva cause para observabilidad sin exponer detalles.
Durante una transición, el tipo real puede ser union de versiones:
type UserStored = UserV1 | UserV2;El lector normaliza a un modelo actual. No declares UserV2 mientras todavía existen V1 sin fallback.
any en pipelines;_id optional siempre;TypeScript documenta y restringe el código, no la base. Separa input, dominio, documento y DTO; modela BSON explícitamente y valida runtime. Las assertions ocultan schema drift, mientras una frontera de transformación permite evolución, seguridad y contratos claros.
as OrderDocument?Mongoose.