parameters

README

go-parameters

Parameter multi-tool that parses json, msg pack, or multipart form data into a parameter object.

CI / CD	Quality & Security	Docs & Meta	Community

Table of Contents

• Installation
• Documentation
• Examples & Tests
• Benchmarks
• Code Standards
• AI Compliance
• Maintainers
• Contributing
• License

Installation

go-parameters requires a supported release of Go.

go get -u github.com/mrz1836/go-parameters

Documentation

View the generated documentation

Features

• This package uses the fastest router: Julien Schmidt's httprouter
• Works with json, msgpack, and multi-part forms
• Handles all standard types for GetParams
• Handler methods like MakeParsedReq() for httprouter use
• Imbue and Permit helper methods
• GetParams() parses parameters only once

Development Setup (Getting Started)

Install MAGE-X build tool for development:

# Install MAGE-X for development and building
go install github.com/mrz1836/mage-x/cmd/magex@latest
magex update:install

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump bump=patch push

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Build Commands

View all build commands

magex help

GitHub Workflows

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by configuration files: .env.base (default configuration) and optionally .env.custom (project-specific overrides) – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

Configuration Files:

• .env.base – Default configuration that works for most Go projects
• .env.custom – Optional project-specific overrides

This magical file controls everything from:

• 🚀 Go version matrix (test on multiple versions or just one)
• 🏃 Runner selection (Ubuntu or macOS, your wallet decides)
• 🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
• 🛡️ Security tool versions (gitleaks, nancy, govulncheck)
• 🤖 Auto-merge behaviors (how aggressive should the bots be?)
• 🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Pro tip: Want to disable code coverage? Just add ENABLE_CODE_COVERAGE=false to your .env.custom to override the default in .env.base and push. No YAML archaeology required!

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml	Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml	Automatically merges Dependabot PRs that meet all requirements.
fortress.yml	Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml	Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml	Runs OpenSSF Scorecard to assess supply chain security.
stale.yml	Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml	Keeps GitHub labels in sync with the declarative manifest at .github/labels.yml.

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any managed tools. It is the recommended way to keep your development environment and CI in sync with the latest versions.

Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.24.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

Benchmarks

The following benchmarks were conducted to measure the performance of various functions in the github.com/mrz1836/go-parameters package. All tests were run on a machine with the following specifications:

• Operating System: macOS (Darwin)
• Architecture: ARM64
• CPU: Apple M1 Max

Benchmark Results

View the latest benchmark results

Benchmark	Iterations	ns/op	B/op	allocs/op
UniqueUint64	13,989,841	84.49 ns	64 B	1
GetParams_ParseJSONBody	209,700,817	5.721 ns	0 B	0
GetParams	209,668,894	5.719 ns	0 B	0
Params_GetStringOk	37,573,434	31.96 ns	16 B	1
Params_GetBoolOk	36,349,316	33.15 ns	16 B	1
Params_GetBytesOk	38,539,616	31.52 ns	16 B	1
Params_GetBool	35,637,433	32.57 ns	16 B	1
Params_GetFloatOk	22,064,586	54.69 ns	16 B	1
Params_GetIntOk	28,992,304	41.78 ns	16 B	1
Params_GetInt64Ok	28,752,844	41.77 ns	16 B	1
Params_GetIntSliceOk	38,099,671	31.59 ns	16 B	1
Params_GetUint64Ok	29,921,580	39.68 ns	16 B	1

Benchmark Details

• UniqueUint64: Measures the performance of generating unique uint64 values.
• GetParams_ParseJSONBody: Benchmarks parsing a JSON body into parameters.
• GetParams: Tests retrieving parameters without parsing.
• Params_GetStringOk: Evaluates fetching a string parameter with success indication.
• Params_GetBoolOk: Assesses fetching a boolean parameter with success indication.
• Params_GetBytesOk: Measures retrieving a byte slice parameter with success indication.
• Params_GetBool: Benchmarks fetching a boolean parameter without success indication.
• Params_GetFloatOk: Tests fetching a float parameter with success indication.
• Params_GetIntOk: Evaluates fetching an integer parameter with success indication.
• Params_GetInt64Ok: Measures fetching a 64-bit integer parameter with success indication.
• Params_GetIntSliceOk: Benchmarks retrieving a slice of integers with success indication.
• Params_GetUint64Ok: Tests fetching an unsigned 64-bit integer parameter with success indication.

Benchmark Notes

• Iterations: The number of times the benchmark function was executed.
• ns/op: Nanoseconds per operation, indicating the average time taken for each operation.
• B/op: Bytes allocated per operation, showing the memory usage.
• allocs/op: Allocations per operation, indicating how many memory allocations occurred per operation.

How to Run Benchmarks

Run the Go benchmarks:

magex bench

Code Standards

Read more about this Go project's code standards.

AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

• AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
• CLAUDE.md — quick checklist for the Claude agent.
• .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
• sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

Maintainers

MrZ	kayleg

Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

License

Documentation

Overview

Package parameters parses json, msg pack, or multi-part form data into a parameters object

Index

• Constants
• Variables
• func CORSHeaders(fn http.HandlerFunc) httprouter.Handle
• func CamelToSnakeCase(str string) string
• func EnableGZIP(fn httprouter.Handle) httprouter.Handle
• func GeneralJSONResponse(fn http.HandlerFunc) httprouter.Handle
• func GeneralResponse(fn http.HandlerFunc) httprouter.Handle
• func JSONResp(fn httprouter.Handle) httprouter.Handle
• func MakeFirstUpperCase(s string) string
• func MakeHTTPRouterParsedReq(fn httprouter.Handle) httprouter.Handle
• func MakeParsedReq(fn http.HandlerFunc) http.HandlerFunc
• func SendCORS(w http.ResponseWriter, req *http.Request)
• func SnakeToCamelCase(str string, ucFirst bool) string
• func UniqueUint64(in []uint64) []uint64
• type CustomTypeHandler
• type Params
  • func FilterMap(params *Params) *Params
  • func GetParams(req *http.Request) *Params
  • func ParseParams(req *http.Request) *Params
  • func (p *Params) Clone() *Params
  • func (p *Params) Get(key string) (val interface{}, ok bool)
  • func (p *Params) GetBool(key string) bool
  • func (p *Params) GetBoolOk(key string) (bool, bool)
  • func (p *Params) GetBytes(key string) []byte
  • func (p *Params) GetBytesOk(key string) ([]byte, bool)
  • func (p *Params) GetFileOk(key string) (*multipart.FileHeader, bool)
  • func (p *Params) GetFloat(key string) float64
  • func (p *Params) GetFloatOk(key string) (float64, bool)
  • func (p *Params) GetFloatSlice(key string) []float64
  • func (p *Params) GetFloatSliceOk(key string) ([]float64, bool)
  • func (p *Params) GetInt(key string) int
  • func (p *Params) GetInt16(key string) int16
  • func (p *Params) GetInt16Ok(key string) (int16, bool)
  • func (p *Params) GetInt32(key string) int32
  • func (p *Params) GetInt32Ok(key string) (int32, bool)
  • func (p *Params) GetInt64(key string) int64
  • func (p *Params) GetInt64Ok(key string) (int64, bool)
  • func (p *Params) GetInt8(key string) int8
  • func (p *Params) GetInt8Ok(key string) (int8, bool)
  • func (p *Params) GetIntOk(key string) (int, bool)
  • func (p *Params) GetIntSlice(key string) []int
  • func (p *Params) GetIntSliceOk(key string) ([]int, bool)
  • func (p *Params) GetJSON(key string) map[string]interface{}
  • func (p *Params) GetJSONOk(key string) (map[string]interface{}, bool)
  • func (p *Params) GetString(key string) string
  • func (p *Params) GetStringOk(key string) (string, bool)
  • func (p *Params) GetStringSlice(key string) []string
  • func (p *Params) GetStringSliceOk(key string) ([]string, bool)
  • func (p *Params) GetTime(key string) time.Time
  • func (p *Params) GetTimeInLocation(key string, loc *time.Location) time.Time
  • func (p *Params) GetTimeInLocationOk(key string, loc *time.Location) (time.Time, bool)
  • func (p *Params) GetTimeOk(key string) (time.Time, bool)
  • func (p *Params) GetUint64(key string) uint64
  • func (p *Params) GetUint64Ok(key string) (uint64, bool)
  • func (p *Params) GetUint64Slice(key string) []uint64
  • func (p *Params) GetUint64SliceOk(key string) ([]uint64, bool)
  • func (p *Params) HasAll(keys ...string) (bool, []string)
  • func (p *Params) Imbue(obj interface{})
  • func (p *Params) Permit(allowedKeys []string)

Examples

• UniqueUint64

Constants

const (
	// ParamsKeyName standard key name for parameter data
	ParamsKeyName paramKey = "params"

	// DateOnly is only the date
	DateOnly = "2006-01-02"

	// DateTime is not recommended, rather use time.RFC3339
	DateTime = "2006-01-02 15:04:05"

	// HTMLDateTimeLocal is the format used by the input type datetime-local
	HTMLDateTimeLocal = "2006-01-02T15:04"

	// MaxSafeInt is the maximum safe integer value
	MaxSafeInt = 1 << 53 // 9007199254740992
)

Constants for parameters package

const FilteredValue = "FILTERED"

FilteredValue is the value to replace filtered keys with

const Origin = "Origin"

Origin is the header key for the origin

Variables

var FilteredKeys []string

FilteredKeys is a lower case array of keys to filter when logging

var KnownAbbreviations = []string{"id", "json", "html", "xml"}

KnownAbbreviations contains lower case versions of abbreviations to match. Any entry in this list will become full upper case when converting from snake_case to camelCase

user_id -> UserID

Functions

func CORSHeaders

func CORSHeaders(fn http.HandlerFunc) httprouter.Handle

CORSHeaders adds cross-origin resource sharing headers to a response

func CamelToSnakeCase

func CamelToSnakeCase(str string) string

CamelToSnakeCase converts CamelCase to snake_case Consecutive capital letters will be treated as one word:

HTML -> html

func EnableGZIP

func EnableGZIP(fn httprouter.Handle) httprouter.Handle

EnableGZIP will attempt to compress the response if the client has passed a header value for Accept-Encoding which allows gzip

func GeneralJSONResponse

func GeneralJSONResponse(fn http.HandlerFunc) httprouter.Handle

GeneralJSONResponse calls the default wrappers for a json response: EnableGZIP, JSONResp, MakeHTTPRouterParsedReq, CORSHeaders

func GeneralResponse

func GeneralResponse(fn http.HandlerFunc) httprouter.Handle

GeneralResponse calls the default wrappers: EnableGZIP, MakeHTTPRouterParsedReq, CORSHeaders

func JSONResp

func JSONResp(fn httprouter.Handle) httprouter.Handle

JSONResp will set the content-type to application/json

func MakeFirstUpperCase

func MakeFirstUpperCase(s string) string

MakeFirstUpperCase upper cases the first letter of the string

func MakeHTTPRouterParsedReq

func MakeHTTPRouterParsedReq(fn httprouter.Handle) httprouter.Handle

MakeHTTPRouterParsedReq make http router parsed request

func MakeParsedReq

func MakeParsedReq(fn http.HandlerFunc) http.HandlerFunc

MakeParsedReq make parsed request

func SendCORS

func SendCORS(w http.ResponseWriter, req *http.Request)

SendCORS sends a cross-origin resource sharing header only

func SnakeToCamelCase

func SnakeToCamelCase(str string, ucFirst bool) string

SnakeToCamelCase converts snake_case to CamelCase. When:

ucFirst = false - snake_case -> snakeCase
ucFirst = true  - snake_case -> SnakeCase

func UniqueUint64

func UniqueUint64(in []uint64) []uint64

UniqueUint64 removes duplicates from uint64 arrays

Example

ExampleUniqueUint64 shows an example using the method

one := []uint64{3, 2, 1, 3, 3, 3, 3}
unique := UniqueUint64(one)

fmt.Println(unique)

Output:

[3 2 1]

Types

type CustomTypeHandler

type CustomTypeHandler func(field *reflect.Value, value interface{}) error

CustomTypeHandler custom type handler

var CustomTypeSetter CustomTypeHandler

CustomTypeSetter is used when Imbue is called on an object to handle unknown types

type Params

type Params struct {
	Values map[string]interface{}
	// contains filtered or unexported fields
}

Params is the parameter values

func FilterMap

func FilterMap(params *Params) *Params

FilterMap will filter the parameters and not log parameters with sensitive data. To add more parameters to filter, add the key to the FilteredKeys array

func GetParams

func GetParams(req *http.Request) *Params

GetParams get parameters

func ParseParams

func ParseParams(req *http.Request) *Params

ParseParams parse parameters

func (*Params) Clone

func (p *Params) Clone() *Params

Clone makes a copy of this params object

func (*Params) Get

func (p *Params) Get(key string) (val interface{}, ok bool)

Get the param by key, return interface

func (*Params) GetBool

func (p *Params) GetBool(key string) bool

GetBool get param by key, return boolean

func (*Params) GetBoolOk

func (p *Params) GetBoolOk(key string) (bool, bool)

GetBoolOk get param by key, return boolean

func (*Params) GetBytes

func (p *Params) GetBytes(key string) []byte

GetBytes get param by key, return slice of bytes

func (*Params) GetBytesOk

func (p *Params) GetBytesOk(key string) ([]byte, bool)

GetBytesOk get param by key, return slice of bytes

func (*Params) GetFileOk

func (p *Params) GetFileOk(key string) (*multipart.FileHeader, bool)

GetFileOk get param by key, return file

func (*Params) GetFloat

func (p *Params) GetFloat(key string) float64

GetFloat get param by key, return float

func (*Params) GetFloatOk

func (p *Params) GetFloatOk(key string) (float64, bool)

GetFloatOk get param by key, return float

func (*Params) GetFloatSlice

func (p *Params) GetFloatSlice(key string) []float64

GetFloatSlice get param by key, return slice of floats

func (*Params) GetFloatSliceOk

func (p *Params) GetFloatSliceOk(key string) ([]float64, bool)

GetFloatSliceOk get param by key, return slice of floats

func (*Params) GetInt

func (p *Params) GetInt(key string) int

GetInt get param by key, return integer

func (*Params) GetInt16

func (p *Params) GetInt16(key string) int16

GetInt16 get param by key, return integer

func (*Params) GetInt16Ok

func (p *Params) GetInt16Ok(key string) (int16, bool)

GetInt16Ok get param by key, return integer

func (*Params) GetInt32

func (p *Params) GetInt32(key string) int32

GetInt32 get param by key, return integer

func (*Params) GetInt32Ok

func (p *Params) GetInt32Ok(key string) (int32, bool)

GetInt32Ok get param by key, return integer

func (*Params) GetInt64

func (p *Params) GetInt64(key string) int64

GetInt64 get param by key, return integer

func (*Params) GetInt64Ok

func (p *Params) GetInt64Ok(key string) (int64, bool)

GetInt64Ok get param by key, return integer

func (*Params) GetInt8

func (p *Params) GetInt8(key string) int8

GetInt8 get param by key, return integer

func (*Params) GetInt8Ok

func (p *Params) GetInt8Ok(key string) (int8, bool)

GetInt8Ok get param by key, return integer

func (*Params) GetIntOk

func (p *Params) GetIntOk(key string) (int, bool)

GetIntOk get param by key, return integer

func (*Params) GetIntSlice

func (p *Params) GetIntSlice(key string) []int

GetIntSlice get param by key, return slice of integers

func (*Params) GetIntSliceOk

func (p *Params) GetIntSliceOk(key string) ([]int, bool)

GetIntSliceOk get param by key, return slice of integers

func (*Params) GetJSON

func (p *Params) GetJSON(key string) map[string]interface{}

GetJSON get param by key, return map of string interface

func (*Params) GetJSONOk

func (p *Params) GetJSONOk(key string) (map[string]interface{}, bool)

GetJSONOk get param by key, return map of string interface

func (*Params) GetString

func (p *Params) GetString(key string) string

GetString get param by key, return string

func (*Params) GetStringOk

func (p *Params) GetStringOk(key string) (string, bool)

GetStringOk get param by key, return string

func (*Params) GetStringSlice

func (p *Params) GetStringSlice(key string) []string

GetStringSlice get param by key, return slice of strings

func (*Params) GetStringSliceOk

func (p *Params) GetStringSliceOk(key string) ([]string, bool)

GetStringSliceOk get param by key, return slice of strings

func (*Params) GetTime

func (p *Params) GetTime(key string) time.Time

GetTime get param by key, return time

func (*Params) GetTimeInLocation

func (p *Params) GetTimeInLocation(key string, loc *time.Location) time.Time

GetTimeInLocation get param by key, return time

func (*Params) GetTimeInLocationOk

func (p *Params) GetTimeInLocationOk(key string, loc *time.Location) (time.Time, bool)

GetTimeInLocationOk get param by key, return time

func (*Params) GetTimeOk

func (p *Params) GetTimeOk(key string) (time.Time, bool)

GetTimeOk get param by key, return time

func (*Params) GetUint64

func (p *Params) GetUint64(key string) uint64

GetUint64 get param by key, return unsigned integer

func (*Params) GetUint64Ok

func (p *Params) GetUint64Ok(key string) (uint64, bool)

GetUint64Ok get param by key, return unsigned integer

func (*Params) GetUint64Slice

func (p *Params) GetUint64Slice(key string) []uint64

GetUint64Slice get param by key, return slice of unsigned integers

func (*Params) GetUint64SliceOk

func (p *Params) GetUint64SliceOk(key string) ([]uint64, bool)

GetUint64SliceOk get param by key, return slice of unsigned integers

func (*Params) HasAll

func (p *Params) HasAll(keys ...string) (bool, []string)

HasAll will return if all specified keys are found in the params object

func (*Params) Imbue

func (p *Params) Imbue(obj interface{})

Imbue sets the parameters to the object by type; does not handle nested parameters

func (*Params) Permit

func (p *Params) Permit(allowedKeys []string)

Permit permits only the allowed fields given by allowedKeys