validation

Documentation

Overview

Package validation checks a submitted form against a set of rules.

The surface is string rules, so that a rule set reads without explanation:

var Register = validation.MustCompile(validation.Rules{
	"name":     "required|max:255",
	"email":    "required|email",
	"password": "required|min:12|confirmed",
})

in, err := ctx.Validate(requests.Register)
if err != nil {
	return err
}

A rule set is compiled ONCE, in a package-level variable, and every rule string is parsed and checked there: an unknown rule, a missing or unparseable argument, a pattern that does not compile, a cross-field reference naming a field that does not exist -- each of those fails at boot, naming the field, the rule and the file, and all of them are reported together. A rule set that boots is a rule set whose names are all real.

This package is a bridge. It is removed in v1.0.0; import github.com/arandu-io/hesape/validation directly.

The component moved to github.com/arandu-io/hesape under new names, and this package is now the old names pointing at it. Every symbol here answers to hesape/validation, with one exception: Humanize answers to hesape/str.Headline, because naming a field the way a sentence does is a string question and not a validation one.

The death date above is what keeps this from being a second way to import one type. Nothing here holds an implementation: where the name and the signature survived the move it is a Go alias, and where the design diverged it is a call through and nothing more.

The three divergences, and what each one is:

WithMessages   is WithMessageOverrides there, because hesape spends the
               name WithMessages on another symbol
Compile        is a function VALUE rather than a wrapper, and so is
               MustCompile: both read runtime.Caller to name the source of
               a boot failure, and a wrapper would name this file
Humanize       reaches hesape/str.Headline, which title cases every word
               where this package sentence cased the first -- the one
               behaviour the move changes

The rule table grew on the way: 59 rules shipped here and 106 ship there, and no rule name was dropped, so a set that compiled against this package compiles against hesape unchanged.

The embedded time zone database that the `timezone` rule needs is hesape/validation's now, and arrives through the import below.

Index

• Variables
• func Confirmed(e Errors, field, value, confirmation string)
• func Email(e Errors, field, value string)
• func Humanize(field string) string
• func MaxLen(e Errors, field, value string, n int)
• func MinLen(e Errors, field, value string, n int)
• func NotZero[T comparable](e Errors, field string, value T)
• func Required(e Errors, field, value string)
• type CompileError
• type CompileErrors
• type Errors
• type Input
• type Messages
• type Option
  • func WithMessages(m Messages) Option
• type Rules
• type Set
• type Validatable

Variables

var Compile = hvalidation.Compile

Compile parses and checks a rule set, and reports everything wrong with it.

Use it where a rule set is built from something that is not a literal. Everywhere else the rule set belongs in a package-level variable, which is what MustCompile is for.

It is a function VALUE and not the one-line wrapper every other function in this bridge is, and the reason is the file and line a failure names. hesape/validation reads runtime.Caller to find the application source that asked for the rule set; a wrapper is one more frame, so every boot failure would name this file instead of the application's -- which is precisely the promise CompileError.File makes. A value adds no frame. See the gap noted in the report: hesape has no CompileAt to hand the caller through to.

var MustCompile = hvalidation.MustCompile

MustCompile is Compile for a package-level variable, which is where a rule set belongs: the check then runs before main does.

var StorePost = validation.MustCompile(validation.Rules{
	"title": "required|max:255",
})

It panics, for the reason view.Register panics: finding out at boot beats finding out from the one request that first exercises the rule.

A function value, for the reason given on Compile.

Functions

func Confirmed

func Confirmed(e Errors, field, value, confirmation string)

Confirmed rejects a value its confirmation field does not repeat.

It is what a "confirm your password" box is for, and the message goes on the confirmation rather than on the field itself: a form that reports "password does not match" next to the first box tells the person to change the one they meant, and they change it, and the form fails again.

func Email

func Email(e Errors, field, value string)

Email checks the shape only. Deliverability is proven by sending mail, never by a regular expression.

Whitespace is rejected rather than trimmed: an address with a space in it is almost always a paste accident, and silently trimming input hides the mistake from the person who made it.

func Humanize

func Humanize(field string) string

Humanize turns a form field name into what a sentence calls it: "password_confirmation" becomes "Password Confirmation".

It is exported because the messages in this package are written to be drawn WITHOUT a field name -- components.Field puts "must be at least 12 characters" under a labelled input -- and a banner needs one in front: view.Page.ErrorSummary renders "Password must be at least 12 characters".

It answers to str.Headline, and that CHANGES what it returns: "password_confirmation" was "Password confirmation" here and is "Password Confirmation" there. A one-word field reads identically, which is most of them. This is the one behaviour the move changes, and it changes the text of an error summary, never whether a form passes.

func MaxLen

func MaxLen(e Errors, field, value string, n int)

MaxLen counts runes, not bytes.

func MinLen

func MinLen(e Errors, field, value string, n int)

MinLen counts runes, not bytes: a limit measured in bytes rejects valid input in any language that needs more than one byte per character.

func NotZero

func NotZero[T comparable](e Errors, field string, value T)

NotZero reports a value that was never filled in.

It is Required for everything that is not text. A time.Time is asked rather than compared: a parsed "0001-01-01T00:00:00Z" carries a location the zero value does not, so == says they differ when they do not.

Bool has no meaningful zero to reject -- false is an answer, not an absence.

A wrapper and not an alias: Go has no alias form for a generic function.

func Required

func Required(e Errors, field, value string)

Required rejects an empty or blank value.

Types

type CompileError

type CompileError = hvalidation.CompileError

CompileError is one thing wrong with a rule set, named precisely enough to fix without opening the framework.

type CompileErrors

type CompileErrors = hvalidation.CompileErrors

CompileErrors is everything wrong with a rule set, not the first thing.

A set with three typos reports three. Reporting one at a time turns a boot check into three restarts, which is how a boot check gets a reputation for being slower than finding out on the request.

type Errors

type Errors = hvalidation.Errors

Errors maps a field to its messages. It serializes straight into the HTMX partial that re-renders the form with inline errors.

The alias carries the whole message bag with it: the four methods this package declared -- Add, Any, Error and First -- are still there, alongside the rest of what hesape added. First took no argument here and takes an optional key there, so e.First() reads as it always did and e.First("email") is new.

type Input

type Input = hvalidation.Input

Input is what passed the rules. It is the only way to read a submitted value out of a validated request: a field the set does not declare is not in here, so a value nobody wrote a rule for cannot reach a repository by accident.

type Messages

type Messages = hvalidation.Messages

Messages overrides the sentence one rule puts on one field, keyed "field.rule":

validation.MustCompile(rules, validation.WithMessages(validation.Messages{
	"email.required": "we need an address to send the receipt to",
}))

A key naming a field or a rule the set does not declare is a boot failure: a typo in an override is otherwise invisible, because the default sentence is still there and still reads correctly.

type Option

type Option = hvalidation.Option

Option adjusts a compilation.

func WithMessages

func WithMessages(m Messages) Option

WithMessages replaces the default sentence for the named field and rule.

Renamed on the way to hesape: it is WithMessageOverrides there, because that package also carries ValidationException::withMessages and two functions called WithMessages in one package is one name too few.

type Rules

type Rules = hvalidation.Rules

Rules is the rule set of one request, keyed by the name of the form input -- the same name components.FieldProps.Name carries.

A whole set reads at once, without explanation:

var Register = validation.MustCompile(validation.Rules{
	"name":     "required|max:255",
	"email":    "required|email",
	"password": "required|min:12|confirmed",
})

What a string costs is that a typo in "requried" is not a compiler error. What Compile buys back is that it is a BOOT error, naming the field, the rule and the file.

type Set

type Set = hvalidation.Set

Set is a compiled, checked rule set.

Build one in a package-level variable with MustCompile: the rules are then parsed once, at boot, and a set that boots is a set whose names are all real. A Set is read-only once compiled, so one is shared by every request.

type Validatable

type Validatable = hvalidation.Validatable

Validatable is implemented by every request type.