goverter

goverter is a code generator for creating type-safe Go converters. Unlike tools like jinzhu/copier that rely on runtime reflection, goverter generates explicit conversion code at compile time. This results in faster execution and better type safety.

Key features include:

• Fast execution: No reflection is used at runtime.
• Automatic conversion: Handles slices, maps, named types, primitive types, pointers, and structs with matching fields.
• Deep copies: Performs deep copies by default, with support for shallow copying.
• Enum support: Handles enum-like types.
• Customizable: Allows implementing custom converter methods to extend functionality.
• Error reporting: Provides clear errors during generation if target structs have unmapped fields or if types cannot be converted without information loss.

Goverter is a tool designed for creating type-safe converters in Go. It serves as a high-performance alternative to reflection-based tools like jinzhu/copier.

To use Goverter, you define an interface representing the conversion logic and then execute the tool to generate the implementation. Because it avoids reflection at runtime, it offers fast execution.

This is the default mode when using the goverter:converter command. In this mode, you define an interface, and Goverter generates a struct that implements that interface.

Pros:

• Full support for all Goverter features.
• The interface is usable before code generation, which reduces compile errors caused by missing or outdated implementations and allows using generated methods within custom methods.

Cons:

• You must initialize the generated struct implementation.
• You must call methods on the struct instance to execute the conversions.

The ignoreUnexported setting can be applied using several different methods:

• CLI argument: Pass it directly when running the Goverter CLI.
• Conversion comment: Define it within the source code using conversion comments.
• Method comment: Define it within the source code using method comments.

This setting is inheritable, meaning settings applied at a higher level will propagate down to nested conversions.

This is the default mode when using the goverter:variables command. It generates variables that can be used to perform conversions.

Pros:

• Full support for all Goverter features.
• Variables are usable before code generation, reducing compile errors and allowing the use of generated functions in custom methods.
• Conversions can be executed directly without initializing a struct.

Cons:

• Potential runtime overhead if the Go compiler cannot optimize variables as effectively as functions. Benchmark your specific use case if performance is critical.

To prevent compile errors in your project while goverter is generating new implementations, goverter uses Go build constraints (build tags).

By default, goverter considers the build tag goverter to be satisfied during its scanning and generation phase. However, all generated files are automatically prefixed with the following build constraint:

//go:build !goverter

Because the !goverter constraint is not satisfied during the goverter generation process, the generated files are excluded and ignored by the Go compiler during that specific run. This allows goverter to generate code that might temporarily cause errors in your existing build, which goverter will then resolve by providing the newly generated implementation.

Goverter provides several core capabilities for type conversion:

• Fast execution: No reflection is used at runtime.
• Automatic conversion: Handles builtin types including slices, maps, named types, primitive types, pointers, and structs with matching fields.
• Enum support: Specialized handling for enums.
• Copying modes: Performs deep copies by default, with support for shallow copying.
• Customizable: Allows implementation of custom converter methods to handle complex logic.
• Early error detection: Generates clear errors during the code generation phase if:
  • The target struct contains unmapped fields.
  • Types cannot be converted without losing information.