edjson

README

EDJSON: Echo DTO JSON ✨

EDJSON is a small, utility-focused Go library that simplifies data mapping and JSON response generation within the Echo web framework. It builds upon robust deep-copy functionality to ensure clean, reliable data transfer from backend models to public-facing Data Transfer Objects (DTOs).

Its primary goal is to provide a single, clean function for mapping complex data structures into a defined response format before delivery.

---

🚀 Main Feature: The JSON Helper

The core of EDJSON is the generic JSON function. It is designed to eliminate boilerplate code in your HTTP handlers by combining error checking, deep-copying, DTO instantiation, and JSON response delivery into one clean call.

How It Works

The JSON function handles three essential steps for you:

1. Error Check: Immediately returns if a previous error (e.g., from a data service call) is passed to it.
2. DTO Mapping: Deep-copies the data from your source object into a newly created instance of the specified DTO type T.
3. JSON Response: Sends the resulting DTO as a JSON response using the Echo context with the provided HTTP status.

Usage Example

// T is the DTO type (e.g., UserResponseDTO)
// source is the internal data structure (e.g., *User)
func GetUser(c echo.Context) error {
    user, dataServiceErr := service.Users.Get(c.Param("id"))
    
    // Maps 'user' to UserResponseDTO, handles dataServiceErr, and sends the JSON response.
    return edjson.JSON[UserResponseDTO](c, http.StatusOK, user, dataServiceErr)
}

---

🛠️ Data Copying & Custom Conversion

EDJSON ensures all data copying is performed as a deep copy, meaning nested structs, maps, and slices are copied by value, preventing unexpected side effects or mutation of your source data.

Custom Converters

EDJSON manages a global list of Type Converters which allow you to define custom logic for copying between fields of different types. This is essential for:

• Custom Types: Handling conversions between library-specific types and standard Go structs.
• Encoding/Decoding: Automatic encoding/decoding during the copy process (e.g., converting a []byte field to a Base64-encoded string).

You can easily register your custom converters during application startup:

func init() {
    // Add built-in converters for []byte -> Base64 string
    edjson.Converters.Add(edjson.BytesToBase64Converter()...)
}

---

Documentation

Index

• func BytesToBase64Converter() []copier.TypeConverter
• func Copy(target any, source any) error
• func JSON[T any](ctx echo.Context, status int, source any, err error) error
• func MustCopy[T any](source any) T
• type TypeConverters
  • func (t *TypeConverters) Add(converters ...copier.TypeConverter)

Functions

func BytesToBase64Converter

func BytesToBase64Converter() []copier.TypeConverter

BytesToBase64Converter creates and returns a slice of custom type converters for the `copier` library. These converters handle the automatic conversion of byte slices ([]byte or []uint8) to their Base64-encoded string representation during a copy operation.

Returns: A slice of `copier.TypeConverter` structs.

func Copy

func Copy(target any, source any) error

Copy performs a **deep copy** of fields from the 'source' object to the 'target' object. It uses the 'copier' library with specific options for deep copying and custom conversions.

target: A pointer to the destination (struct, map, etc.) where data will be copied into. source: The source object (struct, map, slice, etc.) to copy data from. Returns: An error if the copy operation fails.

func JSON

func JSON[T any](ctx echo.Context, status int, source any, err error) error

JSON is a helper function that performs a deep copy of a 'source' object into a new instance of type 'T', then sends the result as a JSON response using the Echo web framework. T: The desired type of the final JSON output struct. status: The HTTP status code to be returned (e.g., 200, 201). source: The initial data object to be copied from (e.g., a database model). err: An existing error that should immediately trigger a return if non-nil.

func MustCopy

func MustCopy[T any](source any) T

MustCopy is a generic helper that performs a **deep copy** into a **newly created** instance of the specified type 'T', ignoring any potential errors.

T: The value type of the destination object to be created and returned. source: The object to copy data from. Returns: A new instance of type 'T' containing the copied data. NOTE: Use with caution, as ignoring the error means a failed copy will result in an uninitialized or partially-initialized object.

Types

type TypeConverters

type TypeConverters []copier.TypeConverter

TypeConverters is a custom type definition, essentially a slice of 'copier.TypeConverter' functions. Each TypeConverter function defines how to copy data between two fields of different types (e.g., converting a string field to a time.Time field).

var Converters TypeConverters

Converters is the package-level variable that holds all registered custom type converters. This variable is typically used by the Copy and MustCopy functions in this package.

func (*TypeConverters) Add

func (t *TypeConverters) Add(converters ...copier.TypeConverter)

Add is a method on the TypeConverters type used to register one or more custom conversion functions to the collection.

converters: A variadic argument of one or more 'copier.TypeConverter' functions.