Go Map

A high-performance, feature-rich Go library for mapping data between structs with deep copy support, customizable field mapping, and comprehensive type handling.

Features

• 🚀 High Performance - Optimized with object pooling and minimal allocations
• 🔒 Thread-Safe - Safe for concurrent use
• 🔄 Deep Copy - Full recursive copying with circular reference detection
• 🎯 Type Conversion - Intelligent type conversion and custom converters
• 🏷️ Tag Support - Custom struct tags and JSON tag support
• 🔍 Flexible Matching - Case-sensitive and case-insensitive field matching
• 🛡️ Error Handling - Comprehensive error reporting with custom handlers
• 📦 Zero Dependencies - Pure Go implementation

Installation

go get github.com/fbarikzehi/gomap

Quick Start

package main

import (
    "fmt"
    "github.com/fbarikzehi/gomap"
)

type Source struct {
    Name  string
    Age   int
    Email string
}

type Destination struct {
    Name  string
    Age   int
    Email string
}

func main() {
    src := Source{
        Name:  "Foo Bar",
        Age:   30,
        Email: "foo@example.com",
    }

    var dst Destination
    if err := mapper.Copy(&dst, src); err != nil {
        panic(err)
    }

    fmt.Printf("%+v\n", dst)
    // Output: {Name:Foo Bar Age:30 Email:foo@example.com}
}

Documentation

• Examples - Comprehensive usage examples
• Benchmarks - Performance benchmarks and optimization tips
• API Reference - Complete API documentation

Usage

Basic Mapping

var dst Destination
err := mapper.Copy(&dst, src)

Reusable Mapper

m := mapper.NewMapper(
    mapper.WithMaxDepth(10),
    mapper.WithIgnoreUnexported(true),
)

var dst Destination
err := m.Map(&dst, src)

Tag-Based Mapping

type Source struct {
    FullName string `mapper:"name"`
    Years    int    `mapper:"age"`
}

type Destination struct {
    Name string
    Age  int
}

mapper.Copy(&dst, src, mapper.WithTagName("mapper"))

Custom Converters

import "time"

timeConverter := func(v reflect.Value) (reflect.Value, error) {
    if t, ok := v.Interface().(time.Time); ok {
        formatted := t.Format("2006-01-02")
        return reflect.ValueOf(formatted), nil
    }
    return v, nil
}

mapper.Copy(&dst, src,
    mapper.WithCustomConverter(reflect.TypeOf(time.Time{}), timeConverter),
)

Case-Insensitive Mapping

type Source struct {
    USERNAME string
    USERID   int
}

type Destination struct {
    Username string
    UserId   int
}

mapper.Copy(&dst, src, mapper.WithCaseSensitive(false))

Configuration Options

Option	Description	Default
WithMaxDepth(int)	Maximum depth for nested structures	32
WithTagName(string)	Custom struct tag name	"mapper"
WithIgnoreUnexported(bool)	Skip unexported fields	true
WithDeepCopy(bool)	Enable deep copying	true
WithZeroFields(bool)	Zero destination on source zero	false
WithIgnoreNilFields(bool)	Skip nil pointer fields	false
WithCaseSensitive(bool)	Case-sensitive field matching	true
WithJSONTag(bool)	Use JSON tags for mapping	false
WithSkipCircularCheck(bool)	Skip circular reference check	false

Performance

BenchmarkSimpleMapping-8       5000000    250 ns/op    64 B/op    2 allocs/op
BenchmarkNestedMapping-8       2000000    650 ns/op   192 B/op    6 allocs/op
BenchmarkSliceMapping-8         500000   3200 ns/op  2048 B/op   52 allocs/op

For a more detailed performance analysis, see benchmarks for detailed performance analysis.

We welcome contributions that add new benchmarks, optimize existing ones, or explore different usage scenarios. Your contributions help improve performance and provide valuable reference points for the community.

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by popular mapping libraries in other languages
• Built with performance and developer experience in mind
• Community-driven development

Support

• 📫 Open an issue
• 💬 Start a discussion
• ⭐ Star the project if you find it useful!