RMapper 2.0.0

RMapper 🚀

RMapper es un mapeador de objetos para .NET: ligero, de alto rendimiento (delegados compilados), fácil de usar y con una única dependencia ultraligera (Microsoft.Extensions.DependencyInjection.Abstractions, para AddRMapper). Resuelve el problema de copiar datos entre objetos (p. ej., DTOs ⇄ Entidades) sin repetir código ni añadir librerías pesadas.

Incluye dos motores:

📑 Contenido

• Características
• Instalación
• Inicio rápido
• Guía completa
  • 1. Mapeo por convención
  • 2. Mapear sobre una instancia existente
  • 3. Mapeo no genérico
  • 4. Objetos anidados
  • 5. Colecciones
  • 5.1 Flattening (aplanado de nombres)
  • 6. Conversiones de tipo
  • 7. Ignorar propiedades con [IgnoreMap]
  • 8. Configuración: MapperConfiguration
  • 9. ForMember, MapFrom, Ignore
  • 10. Perfiles (Profile)
  • 11. ReverseMap
  • 12. Validar la configuración
  • 13. Inyección de dependencias
• Cómo funciona
• Rendimiento
• Buenas prácticas
• Compatibilidad
• Limitaciones actuales
• Roadmap
• Licencia

✨ Características

• Delegados compilados por par de tipos: cero reflexión en caliente.
• Mapeo por convención (nombre de propiedad), sin configuración necesaria.
• Objetos anidados y colecciones (List<>, arreglos, IEnumerable<>) en profundidad.
• Mapeo a instancia existente: Map(origen, destino).
• Configuración opcional estilo AutoMapper: MapperConfiguration, Profile, ForMember / MapFrom / Ignore, ReverseMap, AssertConfigurationIsValid.
• Conversiones integradas: numéricas, número ⇄ string, nullables, enums.
• Ignora propiedades con [IgnoreMap] (en origen o destino).
• Tolerante a errores: una conversión imposible deja el valor por defecto en lugar de lanzar.
• Thread-safe: una sola instancia de Mapper se puede compartir entre hilos.
• Integración con DI lista (AddRMapper); única dependencia: Microsoft.Extensions.DependencyInjection.Abstractions (ultraligera y omnipresente en .NET).
• Compilado para .NET Standard 2.0 (.NET Framework 4.6.1+, .NET Core 2.0+) y .NET 8.0.

📦 Instalación

.NET CLI

dotnet add package RMapper

Package Manager

Install-Package RMapper

PackageReference

<ItemGroup>
  <PackageReference Include="RMapper" Version="2.*" />
</ItemGroup>

⚡ Inicio rápido

using RMapper.Core.Interfaces;
using RMapper.Execution;

public class UsuarioDto
{
    public string Nombre { get; set; }
    public int Edad { get; set; }
}

public class Usuario
{
    public string Nombre { get; set; }
    public int Edad { get; set; }
}

// Crea el mapper UNA vez y reutilízalo (idealmente como singleton).
IRMapper mapper = new Mapper();

var dto = new UsuarioDto { Nombre = "Carlos", Edad = 30 };
var usuario = mapper.Map<UsuarioDto, Usuario>(dto);

Console.WriteLine(usuario.Nombre); // Carlos
Console.WriteLine(usuario.Edad);   // 30

Sin configuración, RMapper mapea por convención: empareja las propiedades por nombre (sensible a mayúsculas) y copia/convierte el valor.

📘 Guía completa

1. Mapeo por convención

IRMapper mapper = new Mapper();
Destino d = mapper.Map<Origen, Destino>(origen);

• Empareja por nombre exacto de propiedad.
• Requiere que el destino tenga constructor público sin parámetros.
• Si origen es null, devuelve default (es decir, null para tipos de referencia).

2. Mapear sobre una instancia existente

Útil para actualizar una entidad ya cargada (p. ej., desde la base de datos) sin crear una nueva:

var entidad = repositorio.Get(id);     // instancia existente
mapper.Map(dtoEntrante, entidad);      // copia los valores sobre 'entidad'
repositorio.Update(entidad);

Map(source, destination) devuelve la misma instancia de destino que recibió.

3. Mapeo no genérico (tipos en runtime)

Cuando los tipos solo se conocen en tiempo de ejecución:

object? resultado = mapper.Map(origen, typeof(Origen), typeof(Destino));

4. Objetos anidados

Las propiedades de tipo complejo se mapean en profundidad (instancias nuevas e independientes):

public class OrdenDto
{
    public int Id { get; set; }
    public ClienteDto Cliente { get; set; }
}

public class Orden
{
    public int Id { get; set; }
    public Cliente Cliente { get; set; }
}

Orden orden = mapper.Map<OrdenDto, Orden>(dto);
// orden.Cliente es un Cliente NUEVO, no la misma referencia que dto.Cliente.

Si la propiedad anidada de origen es null, en el destino queda null.

5. Colecciones

Soporta List<T>, arreglos T[] y los interfaces que List<T> implementa (IEnumerable<T>, ICollection<T>, IList<T>, IReadOnlyList<T>, etc.). Cada elemento se mapea individualmente:

public class EquipoDto
{
    public List<ClienteDto> Miembros { get; set; }
    public ClienteDto[] Suplentes { get; set; }
    public List<int> Numeros { get; set; }
}

public class Equipo
{
    public List<Cliente> Miembros { get; set; }
    public Cliente[] Suplentes { get; set; }
    public List<int> Numeros { get; set; }
}

Equipo equipo = mapper.Map<EquipoDto, Equipo>(dto);

También puedes mapear una colección de nivel superior directamente:

List<Cliente> clientes = mapper.Map<List<ClienteDto>, List<Cliente>>(listaDto);

Se genera siempre una colección nueva (no se comparte la referencia del origen).

5.1 Flattening (aplanado de nombres)

Cuando un miembro de destino no existe por nombre en el origen, RMapper intenta aplanar una ruta anidada combinando nombres en PascalCase. P. ej., ClienteNombre se resuelve desde Cliente.Nombre:

public class Orden
{
    public int Id { get; set; }
    public Cliente Cliente { get; set; }   // Cliente { Nombre, Direccion { Ciudad } }
}

public class OrdenPlanaDto
{
    public int Id { get; set; }
    public string ClienteNombre { get; set; }          // <- Cliente.Nombre
    public string ClienteDireccionCiudad { get; set; } // <- Cliente.Direccion.Ciudad
}

var dto = mapper.Map<Orden, OrdenPlanaDto>(orden);

• Funciona a cualquier profundidad (A.B.C…).
• Es null-safe: si algún eslabón intermedio es null, el destino queda con su valor por defecto (no lanza).
• Si prefieres una ruta explícita, usa ForMember + MapFrom.

6. Conversiones de tipo

Cuando los tipos de origen y destino no coinciden exactamente, RMapper intenta convertir:

public class A { public int Edad { get; set; } public string Estado { get; set; } }
public class B { public string Edad { get; set; } public Estado Estado { get; set; } }

var b = mapper.Map<A, B>(new A { Edad = 30, Estado = "Activo" });
// b.Edad == "30"   ·   b.Estado == Estado.Activo

7. Ignorar propiedades con [IgnoreMap]

Marca una propiedad para que nunca participe en el mapeo (funciona en origen o destino):

using RMapper.Core.Attributes;

public class ProductoDto
{
    public string Nombre { get; set; }

    [IgnoreMap]
    public decimal PrecioInterno { get; set; } // no se mapea
}

En el destino, esa propiedad queda con su valor por defecto.

8. Configuración: MapperConfiguration

Para mapeos personalizados, declara la configuración una vez y crea el mapper a partir de ella:

using RMapper.Configuration;
using RMapper.Core.Interfaces;

var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Origen, Destino>();
    cfg.CreateMap<ClienteDto, Cliente>();
});

IRMapper mapper = config.CreateMapper();

Los pares que no declares igualmente funcionan por convención (creación bajo demanda). Declararlos te permite personalizarlos y validarlos.

9. ForMember, MapFrom, Ignore

Personaliza miembros concretos:

var config = new MapperConfiguration(cfg =>
    cfg.CreateMap<Usuario, UsuarioDto>()
       // mapear de un nombre/forma distinta:
       .ForMember(d => d.NombreCompleto, o => o.MapFrom(s => s.Nombre + " " + s.Apellido))
       // transformar el valor:
       .ForMember(d => d.NombreMayus,    o => o.MapFrom(s => s.Nombre.ToUpper()))
       // ignorar un miembro:
       .ForMember(d => d.Token,          o => o.Ignore()));

var mapper = config.CreateMapper();

• MapFrom(s => ...) acepta cualquier expresión sobre el origen (propiedad, cálculo, concatenación…).
• Si el tipo del resultado de MapFrom no coincide con el del miembro destino, se aplica la conversión.
• Lo no configurado sigue resolviéndose por convención.

10. Perfiles (Profile)

Agrupa mapeos relacionados en una clase reutilizable:

using RMapper.Configuration;

public class VentasProfile : Profile
{
    public VentasProfile()
    {
        CreateMap<Orden, OrdenDto>()
            .ForMember(d => d.Total, o => o.MapFrom(s => s.Lineas.Sum(l => l.Importe)));

        CreateMap<LineaDto, Linea>();
    }
}

var config = new MapperConfiguration(cfg =>
{
    cfg.AddProfile<VentasProfile>();     // por tipo
    cfg.AddProfile(new VentasProfile()); // o por instancia
});

11. ReverseMap

Registra también el mapeo inverso (por convención):

cfg.CreateMap<Usuario, UsuarioDto>().ReverseMap();

var dto = mapper.Map<Usuario, UsuarioDto>(usuario);
var usuario2 = mapper.Map<UsuarioDto, Usuario>(dto); // funciona en ambos sentidos

12. Validar la configuración

Comprueba que todos los miembros de destino de cada mapeo declarado tengan origen (por convención, por MapFrom o explícitamente ignorados). Ideal en tests/arranque:

var config = new MapperConfiguration(cfg => cfg.CreateMap<Origen, Destino>());
config.AssertConfigurationIsValid(); // lanza InvalidOperationException si algo queda sin mapear

13. Inyección de dependencias

AddRMapper viene incluido en el paquete (en el namespace Microsoft.Extensions.DependencyInjection, así que no necesitas using extra donde ya configuras servicios):

using Microsoft.Extensions.DependencyInjection;

// Escanea los Profile del ensamblado y registra IRMapper como singleton:
services.AddRMapper(typeof(Program).Assembly);

// …o sin argumentos, escanea el ensamblado que llama:
services.AddRMapper();

// …o con configuración explícita:
services.AddRMapper(cfg =>
{
    cfg.CreateMap<Origen, Destino>();
    cfg.AddProfile<VentasProfile>();
});

Luego inyecta IRMapper donde lo necesites:

public class MiServicio
{
    private readonly IRMapper _mapper;
    public MiServicio(IRMapper mapper) => _mapper = mapper;
}

Registra IRMapper y MapperConfiguration como singletons.

🔍 Cómo funciona

La primera vez que mapeas un par (Origen, Destino), RMapper:

1. Lee las propiedades públicas de ambos tipos (vía reflexión, una sola vez).
2. Construye un árbol de expresión que asigna cada miembro de destino: asignación directa, conversión escalar, mapeo anidado o de colección, según el caso.
3. Compila ese árbol a un delegado (Func<...>) y lo cachea.

A partir de ahí, cada mapeo ejecuta el delegado compilado: es prácticamente código escrito a mano (dest.A = src.A; dest.B = src.B; ...), sin reflexión.

🏎️ Rendimiento

Gracias a los delegados compilados, RMapper rinde casi como código escrito a mano. Medido con BenchmarkDotNet (.NET 8, i7-11370H), con AutoMapper como referencia:

• En mapeos planos asigna solo el objeto destino (sin desperdicio de memoria), muy cerca del costo manual.
• En grafos (anidados + colecciones) el rendimiento es del mismo orden que soluciones consolidadas.
• El SimpleMapper por reflexión es órdenes de magnitud más lento; úsalo solo en rutas no críticas.

Cifras aproximadas con un job corto (3 iteraciones); varían según el hardware y la corrida.

El proyecto de benchmarks vive en un repositorio aparte para no arrastrar dependencias de desarrollo (AutoMapper, BenchmarkDotNet) al paquete.

✅ Buenas prácticas

• Reutiliza una sola instancia de Mapper (o IRMapper) como singleton. Compila/cachea los delegados una vez; crear uno nuevo por operación desperdicia ese trabajo.

• Con DI usa AddRMapper: services.AddRMapper(...) ya lo registra como singleton.

• Llama a AssertConfigurationIsValid() en un test para detectar miembros sin mapear.

• Es thread-safe: una instancia compartida puede usarse desde múltiples hilos.

🧩 Compatibilidad

El paquete incluye netstandard2.0 y net8.0.

🚧 Limitaciones actuales

• Emparejamiento por nombre exacto (sensible a mayúsculas), con flattening por convención.
• Mapeo por tipo declarado (sin polimorfismo en tiempo de ejecución).
• Sin resolución de referencias circulares (un grafo cíclico provoca recursión infinita).
• Colecciones destino soportadas: List<T>, arreglos y los interfaces que List<T> implementa. (No HashSet<>, diccionarios u otras colecciones concretas… aún.)
• El destino requiere constructor sin parámetros (sin mapeo por constructor / record posicional aún).

🛣️ Roadmap

• Delegados compilados (motor Mapper).
• Objetos anidados y colecciones (List<>, arreglos).
• Map(source, destinoExistente).
• Profiles, ForMember / MapFrom / Ignore, ReverseMap.
• Conversiones (numéricas, string, nullables, enums) y validación.
• Flattening de nombres (Cliente.Nombre → ClienteNombre).
• Integración con DI (AddRMapper, escaneo de perfiles) — incluida en el paquete.
• Unflattening (ClienteNombre → Cliente.Nombre).
• Mapeo polimórfico e IncludeBase.
• Convertidores y value resolvers personalizados.
• Mapeo a record / por constructor (tipos inmutables).
• Más colecciones destino (HashSet<>, diccionarios).
• Resolución opcional de referencias circulares.

💬 Feedback & Soporte

• Contacto: @RafaDev19 · rafael09.develop@gmail.com

⚖️ Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.