maputils

Documentation

Overview

Package maputils provides utilities for deep binding and merging of maps into Go data structures. It supports recursive binding of map[string]any into structs with handling for nested types: structs, slices, arrays, maps and pointers. Field matching uses json tags (if present) then case-insensitive field names.

The package includes:

• Bind: converts map[string]any to struct handling nested types
• Unbind: converts struct to map[string]any handling nested types
• Merge: deep merges maps while normalizing and filtering keys

Key features:

• Type conversion between common Go types
• Support for json struct tags
• Case-insensitive field matching
• Handling of nested types (structs, slices, arrays, maps)
• Pointer auto-initialization
• Detailed error reporting

Index

• Variables
• func Bind(src map[string]any, dest any) error
• func FindNestedMap(m map[string]any, pathParts []string, create bool) map[string]any
• func Merge(dst, src map[string]any)
• func MergeWithoutOverride(dst, src map[string]any)
• func NormalizeKeys(m map[string]any) map[string]any
• func Unbind(src any, dest map[string]any) error

Variables

var (

	// ErrDestIsNil indicates that the destination value is nil.
	ErrDestIsNil = errors.New("dest is nil")
	// ErrDestMustBePointer indicates that the destination must be a non-nil pointer to a struct.
	ErrDestMustBePointer = errors.New("dest must be a non-nil pointer to a struct")
	// ErrDestMustPointToStruct indicates that the destination pointer must point to a struct.
	ErrDestMustPointToStruct = errors.New("dest must point to a struct")
	// ErrDestinationNotSettable indicates that the destination value cannot be set.
	ErrDestinationNotSettable = errors.New("destination not settable")
	// ErrSrcIsNil indicates that the source value is nil.
	ErrSrcIsNil = errors.New("src is nil")
	// ErrSrcMustBeStruct indicates that the source must be a struct or pointer to struct.
	ErrSrcMustBeStruct = errors.New("src must be a struct or pointer to struct")

	// ErrCannotSetStructFrom indicates cannot set struct from the given value type.
	ErrCannotSetStructFrom = errors.New("cannot set struct from")
	// ErrCannotSetMapFrom indicates cannot set map from the given value type.
	ErrCannotSetMapFrom = errors.New("cannot set map from")
	// ErrCannotSetSliceFrom indicates cannot set slice from the given value type.
	ErrCannotSetSliceFrom = errors.New("cannot set slice from")
	// ErrCannotSetArrayFrom indicates cannot set array from the given value type.
	ErrCannotSetArrayFrom = errors.New("cannot set array from")
	// ErrUnsupportedKind indicates unsupported destination value kind.
	ErrUnsupportedKind = errors.New("unsupported kind")
	// ErrUnsupportedKeyType indicates unsupported map key type during conversion.
	ErrUnsupportedKeyType = errors.New("unsupported key type")

	// ErrCannotConvertToBool indicates type cannot be converted to bool.
	ErrCannotConvertToBool = errors.New("cannot convert to bool")
	// ErrCannotConvertToInt64 indicates type cannot be converted to int64.
	ErrCannotConvertToInt64 = errors.New("cannot convert to int64")
	// ErrCannotConvertToUint64 indicates type cannot be converted to uint64.
	ErrCannotConvertToUint64 = errors.New("cannot convert to uint64")
	// ErrCannotConvertToFloat64 indicates type cannot be converted to float64.
	ErrCannotConvertToFloat64 = errors.New("cannot convert to float64")

	// ErrIntegerOverflow indicates when an integer value would overflow the target integer type.
	ErrIntegerOverflow = errors.New("integer overflows")
	// ErrUnsignedIntegerOverflow indicates when an unsigned integer value would overflow the target unsigned integer type.
	ErrUnsignedIntegerOverflow = errors.New("unsigned integer overflows")
	// ErrUint64Overflow indicates when a uint64 value is too large to fit in an int64.
	ErrUint64Overflow = errors.New("uint64 overflows int64")
	// ErrNegativeIntCannotConvert indicates when a negative int value cannot be converted to uint64.
	ErrNegativeIntCannotConvert = errors.New("negative int cannot convert to uint64")
	// ErrNegativeInt8CannotConvert indicates when a negative int8 value cannot be converted to uint64.
	ErrNegativeInt8CannotConvert = errors.New("negative int8 cannot convert to uint64")
	// ErrNegativeInt16CannotConvert indicates when a negative int16 value cannot be converted to uint64.
	ErrNegativeInt16CannotConvert = errors.New("negative int16 cannot convert to uint64")
	// ErrNegativeInt32CannotConvert indicates when a negative int32 value cannot be converted to uint64.
	ErrNegativeInt32CannotConvert = errors.New("negative int32 cannot convert to uint64")
	// ErrNegativeInt64CannotConvert indicates when a negative int64 value cannot be converted to uint64.
	ErrNegativeInt64CannotConvert = errors.New("negative int64 cannot convert to uint64")
	// ErrNegativeFloatCannotConvert indicates when a negative float value cannot be converted to uint64.
	ErrNegativeFloatCannotConvert = errors.New("negative float cannot convert to uint64")

	// ErrMapKeyConversion indicates an error during conversion of a map key.
	ErrMapKeyConversion = errors.New("map key conversion error")
)

Functions

func Bind

func Bind(src map[string]any, dest any) error

Bind binds src (map[string]any) into dest which must be a pointer to struct. It recursively assigns values handling nested structs, slices, arrays, maps and pointers. Field matching: `json` tag (if present) then case-insensitive field name.

func FindNestedMap

func FindNestedMap(m map[string]any, pathParts []string, create bool) map[string]any

FindNestedMap traverses a nested map based on the provided pathParts and returns the target map at the end of the path. If the path does not exist and create is true, intermediate maps are created. Returns nil if not found or not a map.

func Merge

func Merge(dst, src map[string]any)

Merge deep merges src into dst while ignoring empty keys and normalizing keys to lower-case.

func MergeWithoutOverride

func MergeWithoutOverride(dst, src map[string]any)

MergeWithoutOverride deep merges src into dst without overriding existing values, while ignoring empty keys and normalizing keys to lower-case.

func NormalizeKeys

func NormalizeKeys(m map[string]any) map[string]any

NormalizeKeys recursively converts all keys in the map to lowercase and return the new normalized map

func Unbind

func Unbind(src any, dest map[string]any) error

Unbind converts src (struct or pointer to struct) into dest (map[string]any). It recursively assigns values from the struct to the map, handling nested structs, slices, arrays, maps and pointers. Field keys use json tag (if present) then field name.