mapper

func Clear ¶

func Clear()

Clear removes all registered mappers from the global registry.

This function is primarily intended for testing to ensure test isolation. Each test can start with a clean mapper registry without interference from other tests or global registrations.

WARNING: This affects the global mapper registry. Use with caution in production code as it will remove ALL registered converters.

Example test usage:

func TestMapper(t *testing.T) {
    // Ensure clean state
    mapper.Clear()
    defer mapper.Clear() // Clean up after test

    // Register test-specific mappers
    mapper.MustRegister(func(ctx context.Context, src TestType) (TargetType, error) {
        return TargetType{Value: src.Value}, nil
    })

    // Run test...
}

func Convert ¶

func Convert(src any, dst any) error

Convert performs type conversion using the default mapper with background context.

This is a convenience function for simple conversions that don't require context propagation (e.g., environment variable resolution).

The destination must be a pointer to the target type. The mapper uses reflection to set the pointed-to value with the conversion result.

Returns:

• NoMapperError if no converter is registered for src→dst types
• ConversionError if the converter function returns an error
• nil on successful conversion

Example:

var target *UserProto
if err := mapper.Convert(user, &target); err != nil {
    var noMapper *NoMapperError
    if noMapper, ok := errors.AsType[*NoMapperError](err); ok {
        log.Printf("No converter from %v to %v", noMapper.SrcType, noMapper.DstType)
    }
    return err
}
// target now points to converted UserProto

For conversions that need context (e.g., environment resolution), use:

mapper.WithResolver(envResolver).Convert(src, &dst)

func IsConversionError ¶

func IsConversionError(err error) bool

IsConversionError returns true if the error is a ConversionError

func IsNoMapperError ¶

func IsNoMapperError(err error) bool

IsNoMapperError returns true if the error is a NoMapperError

func MustRegister ¶

func MustRegister[S, T any](fn func(context.Context, S) (T, error))

MustRegister a type converter function, panicking on any registration error.

This is the preferred method for registering converters in init() functions where registration failures should halt application startup rather than being handled at runtime.

Panics if:

• fn is nil (ErrInvalidRegistration)
• A mapper is already registered for S→T (ErrDuplicateRegistration)

Example:

func init() {
    // Register bidirectional conversions
    mapper.MustRegister(func(ctx context.Context, src *Artifact) (*azdext.Artifact, error) {
        return &azdext.Artifact{
            Kind:     convertKind(src.Kind),
            Location: src.Location,
        }, nil
    })

    mapper.MustRegister(func(ctx context.Context, src *azdext.Artifact) (Artifact, error) {
        return Artifact{
            Kind:     convertKindFromProto(src.Kind),
            Location: src.Location,
        }, nil
    })
}

func Register ¶

func Register[S, T any](fn func(context.Context, S) (T, error)) error

Register a type converter function that transforms type S to type T.

The mapper framework uses reflection to automatically route conversion requests to the appropriate registered function based on source and target types.

Registration is type-safe at compile time and thread-safe at runtime. Each S→T type pair can only have one registered converter.

Parameters:

• fn: Conversion function that takes (context, source) and returns (target, error)

Returns an error if:

• fn is nil (ErrInvalidRegistration)
• A mapper is already registered for S→T (ErrDuplicateRegistration)

Example:

// Register a converter from *User to *UserProto
err := mapper.Register(func(ctx context.Context, src *User) (*UserProto, error) {
    return &UserProto{
        Id:   src.ID,
        Name: src.Name,
    }, nil
})
if err != nil {
    // Handle registration error
}

Use this when you need to handle registration errors programmatically. For init() functions where errors should halt startup, use MustRegister instead.