mapper

package module
v0.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 1 Imported by: 4

README

mapper

English | 简体中文

A generics-based type mapper for mapping fields between DTOs and database entities, built on top of jinzhu/copier, with support for registering custom type converters (typical use case: protobuf int32 enums ↔ database string enums).

Features

  • Mapper[DTO, ENTITY] generic interface abstraction, handy for dependency injection and swapping implementations
  • CopierMapper: the default copier-based implementation; fields with matching names are copied automatically
  • EnumTypeConverter: bidirectional int32 ↔ string enum mapping
  • Converters can be registered into CopierMapper so enum fields are converted automatically during copy

Installation

go get github.com/tx7do/go-utils/mapper@latest
import "github.com/tx7do/go-utils/mapper"

Quick Start

CopierMapper: field copying
package main

import (
	"fmt"

	"github.com/tx7do/go-utils/mapper"
)

type DtoType struct {
	Name string
	Age  int
}

type EntityType struct {
	Name string
	Age  int
}

func main() {
	// name the variable m to avoid shadowing the mapper package
	m := mapper.NewCopierMapper[DtoType, EntityType]()

	// DTO -> Entity
	dto := &DtoType{Name: "Alice", Age: 25}
	entity := m.ToEntity(dto)
	fmt.Printf("%+v\n", entity) // &{Name:Alice Age:25}

	// nil in, nil out
	fmt.Println(m.ToEntity(nil) == nil) // true

	// Entity -> DTO
	entity = &EntityType{Name: "Bob", Age: 30}
	dtoResult := m.ToDTO(entity)
	fmt.Printf("%+v\n", dtoResult) // &{Name:Bob Age:30}

	// nil in, nil out
	fmt.Println(m.ToDTO(nil) == nil) // true
}
EnumTypeConverter: enum mapping

Useful for converting between ent (string enums) and protobuf (int32 enums):

package main

import (
	"fmt"

	"github.com/tx7do/go-utils/mapper"
)

type DtoType int32
type EntityType string

const (
	DtoTypeOne DtoType = 1
	DtoTypeTwo DtoType = 2
)

const (
	EntityTypeOne EntityType = "One"
	EntityTypeTwo EntityType = "Two"
)

func main() {
	nameMap := map[int32]string{1: "One", 2: "Two"}
	valueMap := map[string]int32{"One": 1, "Two": 2}

	converter := mapper.NewEnumTypeConverter[DtoType, EntityType](nameMap, valueMap)

	// DTO -> Entity
	dto := DtoTypeOne
	entity := converter.ToEntity(&dto)
	fmt.Println(*entity) // One

	// values missing from the maps return nil
	dtoInvalid := DtoType(3)
	fmt.Println(converter.ToEntity(&dtoInvalid) == nil) // true

	// Entity -> DTO
	entityTwo := EntityTypeTwo
	dtoResult := converter.ToDTO(&entityTwo)
	fmt.Println(*dtoResult) // 2

	// values missing from the maps return nil
	entityInvalid := EntityType("Three")
	fmt.Println(converter.ToDTO(&entityInvalid) == nil) // true
}
Combined usage: converting enum fields automatically during copy

Register the converter pair produced by EnumTypeConverter.NewConverterPair into a CopierMapper, and same-named enum fields are converted between int32 and string automatically during copy:

package main

import (
	"fmt"

	"github.com/tx7do/go-utils/mapper"
)

// DTO-side enum: int32 (e.g. protobuf enum)
type Status int32

// Entity-side enum: string (e.g. value stored in the database)
type StatusEntity string

const (
	StatusOff Status = 0
	StatusOn  Status = 1
)

const (
	StatusEntityOff StatusEntity = "OFF"
	StatusEntityOn  StatusEntity = "ON"
)

// Note: the fields must be pointer types (*Status / *StatusEntity),
// because NewConverterPair registers pointer-based SrcType/DstType and
// copier only applies a converter when the source/target field types
// (including pointerness) match exactly.
type TaskDTO struct {
	Title  string
	Status *Status
}

type TaskEntity struct {
	Title  string
	Status *StatusEntity
}

func main() {
	nameMap := map[int32]string{int32(StatusOff): "OFF", int32(StatusOn): "ON"}
	valueMap := map[string]int32{"OFF": int32(StatusOff), "ON": int32(StatusOn)}

	// 1. build the enum converter and its copier converter pair
	converter := mapper.NewEnumTypeConverter[Status, StatusEntity](nameMap, valueMap)

	// 2. register it into CopierMapper: enum fields are converted during copy
	m := mapper.NewCopierMapper[TaskDTO, TaskEntity]()
	m.AppendConverters(converter.NewConverterPair())

	// 3. copy: *Status (int32) is converted to *StatusEntity (string) automatically
	st := StatusOn
	entity := m.ToEntity(&TaskDTO{Title: "write docs", Status: &st})
	fmt.Println(entity.Title, *entity.Status) // write docs ON

	// the reverse direction converts too: *StatusEntity (string) -> *Status (int32)
	dto := m.ToDTO(entity)
	fmt.Println(dto.Title, *dto.Status) // write docs 1
}

You can also register single copier.TypeConverters one by one with AppendConverter, or build a bidirectional converter pair for any type pair with NewGenericTypeConverterPair.

API

Mapper interface
type Mapper[DTO any, ENTITY any] interface {
	// ToEntity converts a DTO to a Database Entity.
	ToEntity(*DTO) *ENTITY
	// ToDTO converts a Database Entity to a DTO.
	ToDTO(*ENTITY) *DTO
}

The core abstraction: business code can depend on this interface alone, regardless of the implementation.

CopierMapper
func NewCopierMapper[DTO any, ENTITY any]() *CopierMapper[DTO, ENTITY]
func (m *CopierMapper[DTO, ENTITY]) ToEntity(dto *DTO) *ENTITY
func (m *CopierMapper[DTO, ENTITY]) ToDTO(entity *ENTITY) *DTO
func (m *CopierMapper[DTO, ENTITY]) AppendConverter(converter copier.TypeConverter)
func (m *CopierMapper[DTO, ENTITY]) AppendConverters(converters []copier.TypeConverter)
  • The copier-based implementation of the Mapper interface: copies by matching field names, applying registered converters during the copy;
  • AppendConverter / AppendConverters: append custom type converters to the copier options.
EnumTypeConverter
func NewEnumTypeConverter[DTO ~int32, ENTITY ~string](
	nameMap map[int32]string,
	valueMap map[string]int32,
) *EnumTypeConverter[DTO, ENTITY]

func (m *EnumTypeConverter[DTO, ENTITY]) ToEntity(dto *DTO) *ENTITY
func (m *EnumTypeConverter[DTO, ENTITY]) ToDTO(entity *ENTITY) *DTO
func (m *EnumTypeConverter[DTO, ENTITY]) NewConverterPair() []copier.TypeConverter
  • nameMap: int32 value → string name (DTO→ENTITY direction);
  • valueMap: string name → int32 value (ENTITY→DTO direction);
  • NewConverterPair: produces a bidirectional converter pair ready to register with copier.
NewGenericTypeConverterPair
func NewGenericTypeConverterPair[A interface{}, B interface{}](
	srcType A,
	dstType B,
	fromFn func(src A) B,
	toFn func(src B) A,
) []copier.TypeConverter

Builds a bidirectional copier converter pair for an arbitrary type pair A ↔ B. EnumTypeConverter.NewConverterPair is implemented on top of it (passing the *ENTITY / *DTO pointer types).

Notes

  • nil safety: both ToEntity(nil) and ToDTO(nil) return nil without panicking.
  • Unknown enums return nil: EnumTypeConverter's ToEntity / ToDTO return nil (not an error) when the value is missing from the maps.
  • copier errors panic: CopierMapper's ToEntity / ToDTO call panic(err) when the copier copy fails, so make sure your types are copyable.
  • Only pointer-typed fields trigger automatic conversion: NewConverterPair registers pointer-based *DTO / *ENTITY src/dst types, and copier matches field types exactly — so enum fields in structs must be declared as pointers (see the combined usage example above).

Acknowledgements

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewGenericTypeConverterPair

func NewGenericTypeConverterPair[A interface{}, B interface{}](
	srcType A,
	dstType B,
	fromFn func(src A) B,
	toFn func(src B) A,
) []copier.TypeConverter

Types

type CopierMapper

type CopierMapper[DTO any, ENTITY any] struct {
	// contains filtered or unexported fields
}

func NewCopierMapper

func NewCopierMapper[DTO any, ENTITY any]() *CopierMapper[DTO, ENTITY]

func (*CopierMapper[DTO, ENTITY]) AppendConverter

func (m *CopierMapper[DTO, ENTITY]) AppendConverter(converter copier.TypeConverter)

func (*CopierMapper[DTO, ENTITY]) AppendConverters

func (m *CopierMapper[DTO, ENTITY]) AppendConverters(converters []copier.TypeConverter)

func (*CopierMapper[DTO, ENTITY]) ToDTO added in v0.0.3

func (m *CopierMapper[DTO, ENTITY]) ToDTO(entity *ENTITY) *DTO

func (*CopierMapper[DTO, ENTITY]) ToEntity added in v0.0.3

func (m *CopierMapper[DTO, ENTITY]) ToEntity(dto *DTO) *ENTITY

type EnumTypeConverter

type EnumTypeConverter[DTO ~int32, ENTITY ~string] struct {
	// contains filtered or unexported fields
}

func NewEnumTypeConverter

func NewEnumTypeConverter[DTO ~int32, ENTITY ~string](
	nameMap map[int32]string,
	valueMap map[string]int32,
) *EnumTypeConverter[DTO, ENTITY]

func (*EnumTypeConverter[DTO, ENTITY]) NewConverterPair

func (m *EnumTypeConverter[DTO, ENTITY]) NewConverterPair() []copier.TypeConverter

func (*EnumTypeConverter[DTO, ENTITY]) ToDTO added in v0.0.3

func (m *EnumTypeConverter[DTO, ENTITY]) ToDTO(entity *ENTITY) *DTO

func (*EnumTypeConverter[DTO, ENTITY]) ToEntity added in v0.0.3

func (m *EnumTypeConverter[DTO, ENTITY]) ToEntity(dto *DTO) *ENTITY

type Mapper

type Mapper[DTO any, ENTITY any] interface {
	// ToEntity converts a DTO to a Database Entity.
	ToEntity(*DTO) *ENTITY

	// ToDTO converts a Database Entity to a DTO.
	ToDTO(*ENTITY) *DTO
}

Mapper defines the interface for converting between Data Transfer Objects (DTOs) and Database Entities.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL