README.md

Binding

High-performance request data binding for Go web applications. Maps values from various sources (query parameters, form data, JSON bodies, headers, cookies, path parameters) into Go structs using struct tags.

📚 Complete Documentation →

Documentation

This README provides a quick overview. For comprehensive guides, tutorials, and API reference:

• Installation Guide - Get started
• User Guide - Learn the features
• API Reference - Complete API docs
• Examples - Real-world patterns
• Troubleshooting - FAQs and solutions

Features

• Multiple Sources - Query, path, form, header, cookie, JSON, XML, YAML, TOML, MessagePack, Protocol Buffers
• Type Safe - Generic API for compile-time type safety
• Zero Allocation - Struct reflection info cached for performance
• Flexible - Nested structs, slices, maps, pointers, custom types
• Error Context - Detailed field-level error information with contextual hints
• Converter Factories - Built-in factories for common patterns (time, duration, enum, bool)
• Extensible - Custom type converters and value getters

Note: For validation (required fields, enum constraints, etc.), use the rivaas.dev/validation package separately after binding.

Installation

go get rivaas.dev/binding

Requires Go 1.25+

Quick Start

JSON Binding

import "rivaas.dev/binding"

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Age   int    `json:"age"`
}

user, err := binding.JSON[CreateUserRequest](body)
if err != nil {
    // Handle error
}

Query Parameters

type ListParams struct {
    Page   int      `query:"page" default:"1"`
    Limit  int      `query:"limit" default:"20"`
    Tags   []string `query:"tags"`
}

params, err := binding.Query[ListParams](r.URL.Query())

Multi-Source Binding

type CreateOrderRequest struct {
    UserID int    `path:"user_id"`
    Coupon string `query:"coupon"`
    Auth   string `header:"Authorization"`
    Items  []OrderItem `json:"items"`
}

req, err := binding.Bind[CreateOrderRequest](
    binding.FromPath(pathParams),
    binding.FromQuery(r.URL.Query()),
    binding.FromHeader(r.Header),
    binding.FromJSON(body),
)

Custom Type Converters

import "github.com/google/uuid"

type Request struct {
    ID       uuid.UUID `query:"id"`
    Status   Status    `query:"status"`
    Deadline time.Time `query:"deadline"`
}

binder := binding.MustNew(
    binding.WithConverter[uuid.UUID](uuid.Parse),
    binding.WithConverter(binding.TimeConverter("01/02/2006")),
    binding.WithConverter(binding.EnumConverter("active", "pending", "disabled")),
)

req, err := binder.Query[Request](r.URL.Query())

See more examples →

Learn More

• Basic Usage - Request binding fundamentals
• Query Parameters – URL query binding
• JSON Binding - Request body binding
• Multi-Source - Combine multiple sources
• Struct Tags – Tag syntax reference
• Type Support – All supported types
• Error Handling - Error patterns
• Advanced Usage – Custom converters and binders

Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

License

Apache License 2.0 – see LICENSE for details.

---

Part of the Rivaas web framework ecosystem.