README
¶
🥬 validate. simply.
no reflection. no gencode. hierarchical and extendable. fast. ~100LOC. generics.
This is convenient when you have custom validation and nested structures.
// Employee is example of struct with validatable fields and nested structure
type Employee struct {
Name string
Age int
Color Color // custom func Validate()
Education Education // nested with Validate()
Salary float64
Experience time.Duration
Birthday time.Time
VacationStart time.Time
}
func (s Employee) Validate() error {
return validate.All(
validate.OneOf("name", s.Name, "Zeus", "Hera"),
validate.OneOf("age", s.Age, 35, 55),
validate.Min("age", s.Age, 10), // same field validated again
s.Color.Validate(),
s.Education.Validate(),
validate.Max("salary", s.Salary, 123.456),
validate.Max("duration", s.Experience, time.Duration(1)*time.Hour),
validate.After("birthday", s.Birthday, time.Date(1984, 1, 1, 0, 0, 0, 0, time.UTC)),
validate.Before("vacation_start", s.VacationStart, time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)),
)
}
// Education is another custom struct
type Education struct {
Duration int
SchoolName string
}
func (e Education) Validate() error {
if (e.Duration % 17) == 5 {
return errors.New("my special error")
}
return validate.All(
validate.Min("", e.Duration, 10),
validate.OneOf("", e.SchoolName, "KAIST", "Stanford"),
)
}
// Color is custom enum
type Color string
const (
Red Color = "red"
Green Color = "green"
Blue Color = "blue"
)
func (s Color) Validate() error {
switch s {
case Red, Green, Blue:
return nil
default:
return fmt.Errorf("wrong value(%s), expected(%v)", s, []Color{
"red",
"green",
"blue",
})
}
}
Example error message:
validate: 8 errors: [name(Bob) not in [Zeus Hera]; age(101) not in [35 55]; color wrong value(orange), expected([red green blue]); validate: 1 errors: [(Berkeley) not in [KAIST Stanford]]; salary(256.99) higher than max (123.456); duration(10h0m0s) higher than max (1h0m0s); birthday(1984-01-01 00:00:00 +0000 UTC) is not after (1984-01-01 00:00:00 +0000 UTC); vacation_start(2025-01-01 00:00:00 +0000 UTC) is not before (2024-01-01 00:00:00 +0000 UTC)]
Implementation Details
Printing error takes a lot of time.
Thus, it is good to delay constructor of error message as much as possible.
And sometimes user code does not need to print error at all and only nil check is performed.
This is done by moving construction of error message in Error methods.
It is advisable to avoid memory allocations and creation of structures.
Such in case of success flow, we ideally will not have any memory allocations at all.
This is why we make validators as functions and call them in chain.
We do not delay nor wrap validation function calls.
We use function arguments as storage for validation parameters, they are simple params and likely to be on stack which is fast.
For example, for OneOf we are using variadic arguments.
Other alternative is to use arrays since in Go they are on stack as well.
We also hope Go compiler
- can detect that argument to function is constant and inline it in assembly or stack
- does not use expensive memory for variadic parameters
- can inline functions
Defining custom validators with switch is expected to be even faster.
Benchmarks
$ go test -bench=. -benchtime=10s -benchmem ./...
goos: darwin
goarch: amd64
pkg: github.com/nikolaydubina/validate
cpu: VirtualApple @ 2.50GHz
BenchmarkEmployee_Error_Message-10 3744121 3229 ns/op 2376 B/op 56 allocs/op
BenchmarkEmployee_Error-10 12533948 958 ns/op 904 B/op 23 allocs/op
BenchmarkEmployee_Success-10 100000000 115 ns/op 80 B/op 3 allocs/op
BenchmarkEmployeeSimple_Error_Message-10 9488436 1263 ns/op 840 B/op 25 allocs/op
BenchmarkEmployeeSimple_Error-10 44261380 270 ns/op 344 B/op 9 allocs/op
BenchmarkEmployeeSimple_Success-10 243491635 49 ns/op 48 B/op 2 allocs/op
BenchmarkEmployeeNoContainers_Error_Message-10 28089966 427 ns/op 248 B/op 9 allocs/op
BenchmarkEmployeeNoContainers_Error-10 142881793 85 ns/op 88 B/op 3 allocs/op
BenchmarkEmployeeNoContainers_Success-10 1000000000 4 ns/op 0 B/op 0 allocs/op
PASS
ok github.com/nikolaydubina/validate 120.565s
Appendix A: Comparison to other validators
github.com/go-playground/validator
It uses struct tags and reflection. Binding custom validations require defining validation function with special name and using interface typecast then registering this to validator instance.
It has instance of validator that is reused.
Its speed is mostly few hundred ns and up to 1µs. Its memory allocation can be 0 and reaches up to few dozen.
Appendix B: Wrapping validators into interface
Early version of this library was wrapping each validation operation into a interface { Validate() error }.
In this approach, we already had in validators everything needed to format error message, which is why we were reusing them as error containers.
However, there were few drawbacks.
Code looked more verbose:
func (s Employee) Validate() error {
return validate.All(
validate.OneOf[string]{Name: "name", Value: s.Name, Values: []string{"Zeus", "Hera"}},
validate.OneOf[int]{Name: "age", Value: s.Age, Values: []int{35, 55}},
validate.Min[int]{Name: "age", Value: s.Age, Min: 10}, // same field validated again
s.Color,
s.Education,
validate.Max[float64]{Name: "salary", Value: s.Salary, Max: 123.456},
validate.Max[time.Duration]{Name: "duration", Value: s.Experience, Max: time.Duration(1) * time.Hour},
validate.After{Name: "birthday", Value: s.Birthday, Time: time.Date(1984, 1, 1, 0, 0, 0, 0, time.UTC)},
validate.Before{Name: "vacation_start", Value: s.VacationStart, Time: time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)},
)
}
Performance was slightly worse for error case, and much worse for success case:
$ go test -bench=. -benchtime=10s -benchmem ./...
goos: darwin
goarch: amd64
pkg: github.com/nikolaydubina/validate
cpu: VirtualApple @ 2.50GHz
BenchmarkEmployee_Error_Message-10 3579223 3379 ns/op 2761 B/op 62 allocs/op
BenchmarkEmployee_Error-10 9361948 1277 ns/op 1344 B/op 34 allocs/op
BenchmarkEmployee_Success-10 25418672 474 ns/op 552 B/op 14 allocs/op
BenchmarkEmployeeSimple_Error_Message-10 8757170 1364 ns/op 992 B/op 28 allocs/op
BenchmarkEmployeeSimple_Error-10 30418941 394 ns/op 504 B/op 13 allocs/op
BenchmarkEmployeeSimple_Success-10 65194581 184 ns/op 224 B/op 6 allocs/op
BenchmarkEmployeeNoContainers_Error_Message-10 24971338 483 ns/op 280 B/op 10 allocs/op
BenchmarkEmployeeNoContainers_Error-10 72736639 165 ns/op 136 B/op 5 allocs/op
BenchmarkEmployeeNoContainers_Success-10 143333276 83 ns/op 64 B/op 2 allocs/op
PASS
ok github.com/nikolaydubina/validate 124.950s
Appendix C: Binding validator functions in map to field names
It might appear that it is more efficient not to pass name of field in validator.
Such it is tempting to run slice or map of functions.
However, performance deteriorates with this approach.
Likely this is due to compiler using stack or not efficiently inlining.
Code sample:
func All(vs map[string]error) error {
errs := make(map[string]error, len(vs))
for k, err := range vs {
if err != nil {
errs[k] = err
}
}
if len(errs) > 0 {
return errMultiple(errs)
}
return nil
}
...
func (s Employee) Validate() error {
return validate.All(map[string]error{
"name": validate.OneOf(s.Name, "Zeus", "Hera"),
"age": validate.OneOf(s.Age, 35, 55),
"age_2": validate.Min(s.Age, 10), // same field validated again
"color": s.Color.Validate(),
"education": s.Education.Validate(),
"salary": validate.Max(s.Salary, 123.456),
"duration": validate.Max(s.Experience, time.Duration(1)*time.Hour),
"birthday": validate.After(s.Birthday, time.Date(1984, 1, 1, 0, 0, 0, 0, time.UTC)),
"vacation_start": validate.Before(s.VacationStart, time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)),
})
}
Performance is worse across the board:
goos: darwin
goarch: amd64
pkg: github.com/nikolaydubina/validate
cpu: VirtualApple @ 2.50GHz
BenchmarkEmployee_Error_Message-10 2698065 4359 ns/op 3866 B/op 57 allocs/op
BenchmarkEmployee_Error-10 6993564 1714 ns/op 2058 B/op 21 allocs/op
BenchmarkEmployee_Success-10 14948445 810 ns/op 1329 B/op 7 allocs/op
BenchmarkEmployeeSimple_Error_Message-10 8243392 1460 ns/op 1112 B/op 26 allocs/op
BenchmarkEmployeeSimple_Error-10 33798837 356 ns/op 496 B/op 7 allocs/op
BenchmarkEmployeeSimple_Success-10 66953932 182 ns/op 96 B/op 3 allocs/op
BenchmarkEmployeeNoContainers_Error_Message-10 19754359 600 ns/op 576 B/op 10 allocs/op
BenchmarkEmployeeNoContainers_Error-10 61285670 194 ns/op 368 B/op 3 allocs/op
BenchmarkEmployeeNoContainers_Success-10 123293473 98 ns/op 48 B/op 1 allocs/op
PASS
ok github.com/nikolaydubina/validate 128.263s
Reference
- As of
2022-04-01, Go does not support generic arrays.
Documentation
¶
Index ¶
- func After(name string, t, after time.Time) error
- func All(vs ...error) error
- func Before(name string, t, before time.Time) error
- func Max[T constraints.Ordered](name string, v, max T) error
- func Min[T constraints.Ordered](name string, v, min T) error
- func OneOf[T comparable](name string, v T, options ...T) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func OneOf ¶
func OneOf[T comparable](name string, v T, options ...T) error
Types ¶
This section is empty.
Source Files