qp reads URL query parameters into typed Go values — with optional defaulting
and validation, and without panicking on malformed input.
Instead of the manual r.URL.Query().Get("age") + strconv.Atoi +
bounds-check dance, you read a parameter into the right type in one call. A
Query holder decodes the raw query once and serves every read; a bad value
falls back to the default and is reported via an error, never silently masked.
- Read into
int,float64,string,bool,time.Duration,time.Time, and their slices. - Defaulting and validation via composable options —
Default,Min,Max,Between,OneOf, plus per-elementEachfor slices. - Both
?ids=1,2,3and?ids=1&ids=2&ids=3(and mixtures) handled the same way. - Boolean forms:
true/false,yes/no,on/off,1/0(case-insensitive). - Custom types via
GetAs/PullAsand a parse function. - nil-safe: a
nilURL never panics. Zero dependencies.
go get github.com/goloop/qp/v2import "github.com/goloop/qp/v2"Requires Go 1.24 or newer. The package has no third-party dependencies.
q := qp.New(r.URL) // nil-safe; decodes r.URL.Query() exactly once
page := q.Int("page", qp.Default(1), qp.Min(1))
limit := q.Int("limit", qp.Default(20), qp.Between(1, 100))
sort := q.String("sort", qp.Default("created_at"), qp.OneOf("created_at", "name"))
tags := q.StringSlice("tag")For a single read, top-level shortcuts build a throwaway holder:
age, ok := qp.GetInt(r.URL, "age", qp.Between(18, 65))Every type (and its slice form) offers four ways to read a parameter, differing only in the return shape:
| Family | Example | Returns |
|---|---|---|
| Bare | q.Int("age", qp.Default(18)) |
the value (default on absent/invalid) |
| Get | q.GetInt("age") |
(value, ok) |
| Pull | q.PullInt("age") |
*value (nil if absent) |
| Parse | q.ParseInt("age") |
full *Result with flags and error |
Value is always safe to use. When a present, non-empty value fails to parse or
violates a constraint, it falls back to the default and the error explains why:
r := qp.ParseInt(u, "age", qp.Default(18), qp.Between(18, 65))
// "?age=99": r.Value == 18, r.Error != nil (wraps qp.ErrNotAllowed)- Full reference and recipes: DOC.md · DOC.UK.md
- Package API: pkg.go.dev/github.com/goloop/qp/v2
- Changes between versions: CHANGELOG.md
Contributions are welcome. Please run go test ./..., go vet ./... and
gofmt -l . before submitting a pull request.
qp is released under the MIT License. See LICENSE.
Apply slice clamps and avoid copying fallback values twice.