Skip to content
tapp-aiPublic

About

Three-state optional values for Go: unset, null, or set. JSON (v1 and v2) and database/sql aware.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

optional

Go Reference CI

Package optional provides Field[T], a value that is unset, null, or set. It works with encoding/json, encoding/json/v2, and database/sql, and has no dependencies.

go get github.com/tapp-ai/optional

Requires Go 1.24 or later.

Why

A JSON key or a database column can be in three states. A partial update (an HTTP PATCH, a JSON Merge Patch, a SQL UPDATE of some columns) has to tell them apart:

Request body Meaning Field[string]
{} Leave the nickname alone unset
{"nickname": null} Clear the nickname null
{"nickname": ""} Set the nickname to "" set to ""

Common Go types lose one of these states:

Type {} null ""
string "" "" ""
*string nil nil &""
optional.Field[string] unset null set to ""

Usage

Declare request fields as Field[T] and tag them with omitzero:

type UpdateUser struct {
	Name     optional.Field[string] `json:"name,omitzero"`
	Nickname optional.Field[string] `json:"nickname,omitzero"`
	Age      optional.Field[int]    `json:"age,omitzero"`
}

Decode, then apply each field according to its state:

var req UpdateUser
err := json.Unmarshal([]byte(`{"nickname":null,"age":41}`), &req)

if name, ok := req.Name.Get(); ok {
	user.Name = name
}

switch req.Nickname.State() {
case optional.StateNull:
	user.Nickname = nil
case optional.StateSet:
	user.Nickname = req.Nickname.Ptr()
}

Encoding gives back the same body, {"nickname":null,"age":41}. The unset Name field is left out because of omitzero.

Build values with Of, Null, or the zero value:

optional.Of("Ann")              // set to "Ann"
optional.Of(0)                  // set to 0, not null
optional.Null[string]()         // null
optional.Field[string]{}        // unset
optional.FromPtr(user.Nickname) // set to *p, or null when p is nil

API

Unset Null Set to v
State() StateUnset StateNull StateSet
IsUnset() / IsZero() true false false
IsNull() false true false
IsSet() false false true
Get() zero, false zero, false v, true
GetOr(fallback) fallback fallback v
Ptr() nil nil pointer to a copy of v
String() "unset" "null" v formatted with %v
Map(f, fn) unset null Of(fn(v))

Field[T] is a small value type. Copying it copies the value, and two fields compare with == when T is comparable.

When you switch on State(), the exhaustive linter reports a missing case.

Field is meant for data that crosses a boundary: request and response bodies, database rows, messages. For a function result that may be missing, return (T, bool) or *T.

JSON

Field Encoded with omitzero Encoded without it
unset key left out null
null null null
set to v v v
Input Decoded Field
key absent unset (the decoder never touches it)
null null
any other value set, or an error if the value doesn't decode into T

A set field whose value is a nil pointer, slice, map, or interface encodes as null, so it decodes as null. JSON can't tell the two apart. To mean "clear this", use Null[T]() rather than Of[*T](nil).

Use omitzero, not omitempty

omitzero calls IsZero(), which is true only for an unset field. Use it on every Field. omitempty is wrong in both JSON packages:

  • encoding/json never omits a struct, so an unset field is written as null.
  • encoding/json/v2 omits any value that encodes as null, so an explicit null disappears.

encoding/json/v2

On Go 1.27 and later, Field also implements MarshalJSONTo and UnmarshalJSONFrom. encoding/json/v2 uses them, and so does encoding/json, which runs on v2 from Go 1.27. On earlier versions, or with GOEXPERIMENT=nojsonv2, both packages use MarshalJSON and UnmarshalJSON. The two pairs behave the same, and CI tests every combination.

database/sql

Field[T] implements sql.Scanner and driver.Valuer.

Operation Result
Scan SQL NULL null
Scan a value set. Values convert the way database/sql converts into a plain T (for example int64 to int); one that can't convert returns an error.
Value of a set field its value. A T that implements driver.Valuer is used as is.
Value of a null field SQL NULL
Value of an unset field error ErrUnset

Value returns ErrUnset for an unset field because SQL can't say "not given". Writing NULL would silently clear a column the caller never meant to touch. To build a partial UPDATE, leave out columns whose field IsUnset(). Query builders that skip zero values by reflection, such as goqu's omitempty tag, skip unset fields automatically.

As with JSON, a set field holding a nil pointer writes NULL and scans back as null.

Development

go test -race ./...
GOEXPERIMENT=nojsonv2 go test -race ./...
go test -run='^$' -fuzz=FuzzJSON -fuzztime=1m

FuzzJSON checks that every JSON codec round-trips what it decodes, and that encoding/json and encoding/json/v2 decode a Field the same way.

License

MIT

About

Three-state optional values for Go: unset, null, or set. JSON (v1 and v2) and database/sql aware.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages