feat: introduce nullable types

Author: ctrombley

Diff for: go.mod

@@ -1 +1,3 @@
 module github.com/hashicorp/jsonapi
+
+go 1.18

Diff for: models_test.go

@@ -35,6 +35,15 @@ type TimestampModel struct {
 	RFC3339P *time.Time `jsonapi:"attr,rfc3339p,rfc3339"`
 }
 
+type WithNullables struct {
+	ID          int                 `jsonapi:"primary,with-nullables"`
+	Name        string              `jsonapi:"attr,name"`
+	IntTime     Nullable[time.Time] `jsonapi:"attr,int_time,omitempty"`
+	RFC3339Time Nullable[time.Time] `jsonapi:"attr,rfc3339_time,rfc3339,omitempty"`
+	ISO8601Time Nullable[time.Time] `jsonapi:"attr,iso8601_time,iso8601,omitempty"`
+	Bool        Nullable[bool]      `jsonapi:"attr,bool,omitempty"`
+}
+
 type Car struct {
 	ID    *string `jsonapi:"primary,cars"`
 	Make  *string `jsonapi:"attr,make,omitempty"`

Diff for: nullable.go

@@ -0,0 +1,113 @@
+package jsonapi
+
+import (
+	"errors"
+	"reflect"
+	"time"
+)
+
+var supportedNullableTypes = map[string]reflect.Value{
+	"bool":      reflect.ValueOf(false),
+	"time.Time": reflect.ValueOf(time.Time{}),
+}
+
+// Nullable is a generic type, which implements a field that can be one of three states:
+//
+// - field is not set in the request
+// - field is explicitly set to `null` in the request
+// - field is explicitly set to a valid value in the request
+//
+// Nullable is intended to be used with JSON marshalling and unmarshalling.
+// This is generally useful for PATCH requests, where attributes with zero
+// values are intentionally not marshaled into the request payload so that
+// existing attribute values are not overwritten.
+//
+// Internal implementation details:
+//
+// - map[true]T means a value was provided
+// - map[false]T means an explicit null was provided
+// - nil or zero map means the field was not provided
+//
+// If the field is expected to be optional, add the `omitempty` JSON tags. Do NOT use `*Nullable`!
+//
+// Adapted from https://www.jvt.me/posts/2024/01/09/go-json-nullable/
+
+type Nullable[T any] map[bool]T
+
+// NewNullableWithValue is a convenience helper to allow constructing a
+// Nullable with a given value, for instance to construct a field inside a
+// struct without introducing an intermediate variable.
+func NewNullableWithValue[T any](t T) Nullable[T] {
+	var n Nullable[T]
+	n.Set(t)
+	return n
+}
+
+// NewNullNullable is a convenience helper to allow constructing a Nullable with
+// an explicit `null`, for instance to construct a field inside a struct
+// without introducing an intermediate variable
+func NewNullNullable[T any]() Nullable[T] {
+	var n Nullable[T]
+	n.SetNull()
+	return n
+}
+
+// Get retrieves the underlying value, if present, and returns an error if the value was not present
+func (t Nullable[T]) Get() (T, error) {
+	var empty T
+	if t.IsNull() {
+		return empty, errors.New("value is null")
+	}
+	if !t.IsSpecified() {
+		return empty, errors.New("value is not specified")
+	}
+	return t[true], nil
+}
+
+// Set sets the underlying value to a given value
+func (t *Nullable[T]) Set(value T) {
+	*t = map[bool]T{true: value}
+}
+
+// Set sets the underlying value to a given value
+func (t *Nullable[T]) SetInterface(value interface{}) {
+	t.Set(value.(T))
+}
+
+// IsNull indicate whether the field was sent, and had a value of `null`
+func (t Nullable[T]) IsNull() bool {
+	_, foundNull := t[false]
+	return foundNull
+}
+
+// SetNull indicate that the field was sent, and had a value of `null`
+func (t *Nullable[T]) SetNull() {
+	var empty T
+	*t = map[bool]T{false: empty}
+}
+
+// IsSpecified indicates whether the field was sent
+func (t Nullable[T]) IsSpecified() bool {
+	return len(t) != 0
+}
+
+// SetUnspecified indicate whether the field was sent
+func (t *Nullable[T]) SetUnspecified() {
+	*t = map[bool]T{}
+}
+
+func NullableBool(v bool) Nullable[bool] {
+	return NewNullableWithValue[bool](v)
+}
+
+func NullBool() Nullable[bool] {
+	return NewNullNullable[bool]()
+}
+
+func NullableTime(v time.Time) Nullable[time.Time] {
+	return NewNullableWithValue[time.Time](v)
+}
+
+func NullTime() Nullable[time.Time] {
+	return NewNullNullable[time.Time]()
+}

Diff for: request.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"reflect"
+	"regexp"
 	"strconv"
 	"strings"
 	"time"
@@ -589,6 +590,12 @@ func unmarshalAttribute(
 	value = reflect.ValueOf(attribute)
 	fieldType := structField.Type
 
+	// Handle Nullable[T]
+	if strings.HasPrefix(fieldValue.Type().Name(), "Nullable[") {
+		value, err = handleNullable(attribute, args, structField, fieldValue)
+		return
+	}
+
 	// Handle field of type []string
 	if fieldValue.Type() == reflect.TypeOf([]string{}) {
 		value, err = handleStringSlice(attribute)
@@ -656,6 +663,32 @@ func handleStringSlice(attribute interface{}) (reflect.Value, error) {
 	return reflect.ValueOf(values), nil
 }
 
+func handleNullable(
+	attribute interface{},
+	args []string,
+	structField reflect.StructField,
+	fieldValue reflect.Value) (reflect.Value, error) {
+
+	if a, ok := attribute.(string); ok {
+		if bytes.Equal([]byte(a), []byte("null")) {
+			return reflect.ValueOf(nil), nil
+		}
+	}
+
+	var rgx = regexp.MustCompile(`\[(.*)\]`)
+	rs := rgx.FindStringSubmatch(fieldValue.Type().Name())
+
+	attrVal, err := unmarshalAttribute(attribute, args, structField, supportedNullableTypes[rs[1]])
+	if err != nil {
+		return reflect.ValueOf(nil), err
+	}
+
+	fieldValue.Set(reflect.MakeMap(fieldValue.Type()))
+	fieldValue.SetMapIndex(reflect.ValueOf(true), attrVal)
+
+	return fieldValue, nil
+}
+
 func handleTime(attribute interface{}, args []string, fieldValue reflect.Value) (reflect.Value, error) {
 	var isISO8601, isRFC3339 bool
 	v := reflect.ValueOf(attribute)
@@ -714,7 +747,7 @@ func handleTime(attribute interface{}, args []string, fieldValue reflect.Value)
 		return reflect.ValueOf(time.Now()), ErrInvalidTime
 	}
 
-	t := time.Unix(at, 0)
+	t := time.Unix(at, 0).UTC()
 
 	return reflect.ValueOf(t), nil
 }

Diff for: request_test.go

@@ -300,6 +300,88 @@ func TestStringPointerField(t *testing.T) {
 	}
 }
 
+func TestUnmarshalNullableTime(t *testing.T) {
+	aTime := time.Date(2016, 8, 17, 8, 27, 12, 23849, time.UTC)
+
+	out := new(WithNullables)
+
+	attrs := map[string]interface{}{
+		"name":         "Name",
+		"int_time":     aTime.Unix(),
+		"rfc3339_time": aTime.Format(time.RFC3339),
+		"iso8601_time": aTime.Format(iso8601TimeFormat),
+	}
+
+	if err := UnmarshalPayload(samplePayloadWithNullables(attrs), out); err != nil {
+		t.Fatal(err)
+	}
+
+	if out.IntTime == nil {
+		t.Fatal("Was not expecting a nil pointer for out.IntTime")
+	}
+
+	timeVal, err := out.IntTime.Get()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if expected, actual := aTime, timeVal; expected.Equal(actual) {
+		t.Fatalf("Was expecting int_time to be `%s`, got `%s`", expected, actual)
+	}
+
+	timeVal, err = out.IntTime.Get()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if out.RFC3339Time == nil {
+		t.Fatal("Was not expecting a nil pointer for out.RFC3339Time")
+	}
+	if expected, actual := aTime, timeVal; expected.Equal(actual) {
+		t.Fatalf("Was expecting descript to be `%s`, got `%s`", expected, actual)
+	}
+
+	timeVal, err = out.IntTime.Get()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if out.ISO8601Time == nil {
+		t.Fatal("Was not expecting a nil pointer for out.ISO8601Time")
+	}
+	if expected, actual := aTime, timeVal; expected.Equal(actual) {
+		t.Fatalf("Was expecting descript to be `%s`, got `%s`", expected, actual)
+	}
+}
+
+func TestUnmarshalNullableBool(t *testing.T) {
+	out := new(WithNullables)
+
+	aBool := false
+
+	attrs := map[string]interface{}{
+		"name": "Name",
+		"bool": aBool,
+	}
+
+	if err := UnmarshalPayload(samplePayloadWithNullables(attrs), out); err != nil {
+		t.Fatal(err)
+	}
+
+	if out.Bool == nil {
+		t.Fatal("Was not expecting a nil pointer for out.Bool")
+	}
+
+	boolVal, err := out.Bool.Get()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if expected, actual := aBool, boolVal; expected != actual {
+		t.Fatalf("Was expecting bool to be `%t`, got `%t`", expected, actual)
+	}
+}
+
 func TestMalformedTag(t *testing.T) {
 	out := new(BadModel)
 	err := UnmarshalPayload(samplePayload(), out)
@@ -1426,6 +1508,21 @@ func sampleWithPointerPayload(m map[string]interface{}) io.Reader {
 	return out
 }
 
+func samplePayloadWithNullables(m map[string]interface{}) io.Reader {
+	payload := &OnePayload{
+		Data: &Node{
+			ID:         "5",
+			Type:       "with-nullables",
+			Attributes: m,
+		},
+	}
+
+	out := bytes.NewBuffer(nil)
+	json.NewEncoder(out).Encode(payload)
+
+	return out
+}
+
 func testModel() *Blog {
 	return &Blog{
 		ID:        5,

Diff for: response.go

@@ -331,6 +331,22 @@ func visitModelNode(model interface{}, included *map[string]*Node,
 				node.Attributes = make(map[string]interface{})
 			}
 
+			// Handle Nullable[T]
+			if strings.HasPrefix(fieldValue.Type().Name(), "Nullable[") {
+				// handle unspecified
+				if fieldValue.IsNil() {
+					continue
+				}
+
+				// handle null
+				if fieldValue.MapIndex(reflect.ValueOf(false)).IsValid() {
+					continue
+				}
+
+				// handle value
+				fieldValue = fieldValue.MapIndex(reflect.ValueOf(true))
+			}
+
 			if fieldValue.Type() == reflect.TypeOf(time.Time{}) {
 				t := fieldValue.Interface().(time.Time)