Map-Factory: Mapeo de Objetos Simplificado

En el desarrollo de software, especialmente en el ecosistema de JavaScript, una de las tareas más comunes y repetitivas es la transformación de datos. Ya sea que estemos adaptando la respuesta de una API para que se ajuste a nuestro modelo de datos, preparando un objeto para ser enviado a un servicio externo, o simplemente reestructurando información para una vista, el mapeo de objetos es una operación fundamental. Aquí es donde entra en juego map-factory, una potente y sencilla utilidad que nos permite mapear datos de un objeto a otro de manera declarativa y elegante.

Esta librería se destaca por ofrecer una interfaz fluida y encadenable, soporte para referencias profundas mediante notación de puntos, transformaciones personalizadas y la capacidad de fusionar objetos. A lo largo de este artículo, exploraremos en profundidad todas sus características, desde la instalación básica hasta los casos de uso más avanzados, para que puedas dominar esta herramienta y hacer tu código más limpio, legible y mantenible.

¿Qué es Exactamente Map-Factory?

Map-Factory es una utilidad de mapeo de objetos para JavaScript que facilita la transferencia y transformación de datos entre diferentes estructuras. Su diseño se centra en la simplicidad y la potencia, proporcionando una API intuitiva que resuelve problemas complejos con muy poco código. En lugar de escribir manualmente bucles y asignaciones condicionales para mover datos de un objeto fuente a un objeto destino, map-factory te permite definir reglas de mapeo de forma clara y concisa.

Sus características principales incluyen:

• Interfaz Fluida (Fluent Interface): Permite encadenar múltiples llamadas a métodos, lo que resulta en un código más legible y expresivo.
• Referencias Profundas: Utiliza la notación de puntos (ej. usuario.direccion.calle) para acceder y asignar valores en objetos anidados sin esfuerzo.
• Transformaciones Personalizadas: Ofrece la posibilidad de pasar funciones para manipular los datos durante el proceso de mapeo, permitiendo lógica de negocio compleja.
• Selección Múltiple: Puedes seleccionar datos de múltiples campos de origen y combinarlos en un solo campo de destino.
• Manejo de Arrays: Proporciona una sintaxis especial para trabajar con arrays, permitiendo iterar, seleccionar elementos específicos o extraer propiedades de todos los objetos de una lista.

Instalación y Primeros Pasos

Para comenzar a utilizar map-factory en tu proyecto Node.js, solo necesitas instalarlo a través de npm:

npm install map-factory -S

Una vez instalado, puedes importarlo y empezar a crear tus mapeadores. La librería ofrece dos interfaces muy similares, cuya elección dependerá de tu preferencia personal o del caso de uso específico.

Sintaxis Básica

Este enfoque es ideal para mapeos simples donde no necesitas mantener una referencia al mapeador para encadenar más operaciones.

const createMapper = require("map-factory"); const fuente = { nombre: "Alice", idUsuario: 123 }; // Se crea una instancia del mapeador const map = createMapper(); // Se definen las reglas de mapeo map("nombre").to("usuario.nombreCompleto"); map("idUsuario").to("usuario.id"); // Se ejecuta el mapeo sobre el objeto fuente const resultado = map.execute(fuente); console.log(resultado); // Salida: { usuario: { nombreCompleto: 'Alice', id: 123 } }

Sintaxis Fluida o Encadenable

Esta es la forma más común y recomendada de usar la librería, ya que produce un código más compacto y fácil de leer, especialmente cuando se definen múltiples reglas.

const createMapper = require("map-factory"); const fuente = { nombre: "Alice", idUsuario: 123 }; const mapper = createMapper(); const resultado = mapper .map("nombre").to("usuario.nombreCompleto") .map("idUsuario").to("usuario.id") .execute(fuente); console.log(resultado); // Salida: { usuario: { nombreCompleto: 'Alice', id: 123 } }

Sintaxis de Consulta y Referencias Profundas

Una de las características más poderosas de map-factory es su capacidad para navegar por estructuras de objetos complejas utilizando una sintaxis de consulta simple basada en la notación de puntos. Esto es increíblemente útil cuando se trabaja con respuestas de API anidadas.

Consideremos el siguiente objeto fuente:

const source = { my: { deep: { object: { name: "john" }, value: "abc", array: [{ value: 1 }, { value: 2 }, { value: 3 }] }, other: { array: [4, 5, 6] } } };

Podemos extraer datos de él de la siguiente manera:

Transformaciones de Datos: Más Allá del Mapeo Simple

Rara vez los datos que recibimos tienen exactamente el formato que necesitamos. A menudo, es necesario combinarlos, formatearlos o realizar cálculos. Map-factory brilla en este aspecto al permitirnos usar funciones para realizar transformaciones personalizadas.

Transformaciones con Funciones

Puedes proporcionar una función como segundo argumento al método .to(). Esta función recibirá el valor extraído del objeto fuente y su valor de retorno será el que se asigne al objeto destino.

const createMapper = require("map-factory"); const fuente = { nombre: "Jane", apellido: "Doe" }; const mapper = createMapper(); mapper .map(["nombre", "apellido"]) .to("nombreCompleto", (nombre, apellido) => { return `${nombre} ${apellido}`.toUpperCase(); }); const resultado = mapper.execute(fuente); console.log(resultado); // Salida: { nombreCompleto: 'JANE DOE' }

Manejo de Valores por Defecto

¿Qué sucede si un campo fuente no existe? Por defecto, no se creará la propiedad en el destino. Sin embargo, podemos manejar esto elegantemente proporcionando un tercer argumento a .to(), que puede ser un valor estático o una función que se ejecutará si el valor fuente es null o undefined.

const mapper = createMapper(); const fuente = { producto: "Laptop", precio: null }; mapper .map("precio") .to("precioFinal", precio => `USD ${precio.toFixed(2)}`, // Transformación si se encuentra el valor "Precio no disponible" // Valor por defecto si no se encuentra ); const resultado = mapper.execute(fuente); console.log(resultado); // Salida: { precioFinal: 'Precio no disponible' }

Transformaciones de Tubería (Pipeline Transformations)

Map-factory también ofrece una serie de métodos encadenables que se aplican después de seleccionar el campo fuente, permitiendo filtrar o modificar los datos de manera declarativa. Estos métodos actúan como un pipeline o tubería.

• removing(['field1', 'field2']): Mapea un objeto pero excluye los campos especificados.
• keep(['field1', 'field2']): El inverso de removing, mapea un objeto incluyendo únicamente los campos especificados.
• acceptIf('otroCampo', valor): Realiza el mapeo solo si otroCampo en el objeto fuente es igual a valor.
• rejectIf('otroCampo', valor): Realiza el mapeo solo si otroCampo en el objeto fuente NO es igual a valor.
• first() / last(): Si el valor mapeado es un array, selecciona el primer o el último elemento.
• compact(): Si el valor es un array, elimina todos los elementos "falsy" (null, undefined, false, 0, "").
• sort() / reverseSort(): Ordena un array de forma ascendente o descendente.

Veamos un ejemplo práctico con acceptIf:

const fuente = [ { tipo: "factura", monto: 100, detalles: "..." }, { tipo: "nota_credito", monto: -50 }, { tipo: "factura", monto: 200, detalles: "..." } ]; const mapper = createMapper(); mapper .map("monto").to("monto") .map("detalles") .acceptIf("tipo", "factura") // Solo mapear 'detalles' si el tipo es 'factura' .to("detallesFactura"); // Usamos .each() para aplicar el mapeador a cada elemento del array const resultado = mapper.each(fuente); console.log(resultado); /* Salida: [ { monto: 100, detallesFactura: "..." }, { monto: -50 }, // 'detallesFactura' no se mapea aquí { monto: 200, detallesFactura: "..." } ] */

Manejo de Múltiples Fuentes y Fusión de Objetos

En aplicaciones reales, a menudo necesitamos combinar datos de diferentes fuentes. Map-factory nos da dos maneras de abordar esto.

1. Combinar Datos Primero (Recomendado): La estrategia más limpia es crear un único objeto fuente que contenga todos los datos y luego aplicar un solo mapeador.
2. Fusionar con Múltiples Mapeadores: Puedes ejecutar un mapeador y pasar su resultado como el objeto de destino para el siguiente. Esto es útil cuando la lógica de mapeo está distribuida en diferentes partes de tu aplicación.

Ejemplo de fusión con múltiples mapeadores:

// Asumimos que estos datos vienen de diferentes llamadas a API const usuario = { id: 1, nombre: "John Doe" }; const post = { idPost: 101, titulo: "Mi Artículo", idAutor: 1 }; // Mapeador para el post const postMapper = createMapper(); postMapper.map("titulo").to("articulo.titulo"); // Mapeador para el autor const autorMapper = createMapper(); autorMapper.map("nombre").to("articulo.autor"); // 1. Ejecutamos el primer mapeo let resultado = postMapper.execute(post); // 2. Ejecutamos el segundo mapeo, pasando el resultado anterior como destino resultado = autorMapper.execute(usuario, resultado); console.log(resultado); // Salida: { articulo: { titulo: 'Mi Artículo', autor: 'John Doe' } }

Preguntas Frecuentes (FAQ)

¿Cuál es la diferencia entre la sintaxis básica y la fluida?

Funcionalmente, no hay ninguna diferencia. La sintaxis fluida (encadenable) es generalmente preferida porque resulta en un código más legible y conciso al definir múltiples mapeos, mientras que la sintaxis básica puede ser útil para agregar reglas dinámicamente.

¿Cómo puedo manejar un valor por defecto si la fuente no existe?

Puedes usar el tercer parámetro opcional en el método .to(destino, transformacion, valorPorDefecto). Este valor se usará si el campo fuente es null o undefined.

¿Map-Factory funciona con promesas y código asíncrono?

Sí. Si tus transformaciones involucran operaciones asíncronas, puedes usar el método .executeAsync(source), que devuelve una promesa que se resuelve con el objeto mapeado.

¿Puedo usar map-factory en el navegador?

Absolutamente. Aunque es un paquete de npm, está escrito en JavaScript puro y puede ser incluido en proyectos de front-end utilizando herramientas de empaquetado como Webpack, Vite, Rollup o Parcel.

Conclusión

Map-factory es más que una simple utilidad de mapeo; es una herramienta que promueve un código más limpio, declarativo y fácil de mantener. Al abstraer la lógica de transformación de datos en mapeadores reutilizables, nos permite separar las preocupaciones y enfocarnos en la lógica de negocio. Su sintaxis fluida, el manejo de estructuras complejas y las potentes capacidades de transformación lo convierten en un aliado indispensable en cualquier proyecto de JavaScript que requiera una manipulación de datos significativa. La próxima vez que te enfrentes a la tarea de adaptar un objeto JSON, considera darle una oportunidad a map-factory y experimenta la simplicidad de un buen mapeo.