Add NullableRelationship support

models_test.go

@@ -36,12 +36,13 @@ type TimestampModel struct {
 }
 
 type WithNullableAttrs struct {
-	ID          int                     `jsonapi:"primary,with-nullables"`
-	Name        string                  `jsonapi:"attr,name"`
-	IntTime     NullableAttr[time.Time] `jsonapi:"attr,int_time,omitempty"`
-	RFC3339Time NullableAttr[time.Time] `jsonapi:"attr,rfc3339_time,rfc3339,omitempty"`
-	ISO8601Time NullableAttr[time.Time] `jsonapi:"attr,iso8601_time,iso8601,omitempty"`
-	Bool        NullableAttr[bool]      `jsonapi:"attr,bool,omitempty"`
+	ID              int                            `jsonapi:"primary,with-nullables"`
+	Name            string                         `jsonapi:"attr,name"`
+	IntTime         NullableAttr[time.Time]        `jsonapi:"attr,int_time,omitempty"`
+	RFC3339Time     NullableAttr[time.Time]        `jsonapi:"attr,rfc3339_time,rfc3339,omitempty"`
+	ISO8601Time     NullableAttr[time.Time]        `jsonapi:"attr,iso8601_time,iso8601,omitempty"`
+	Bool            NullableAttr[bool]             `jsonapi:"attr,bool,omitempty"`
+	NullableComment NullableRelationship[*Comment] `jsonapi:"relation,nullable_comment,omitempty"`
 }
 
 type Car struct {

nullable.go

@@ -26,6 +26,35 @@ import (
 // Adapted from https://www.jvt.me/posts/2024/01/09/go-json-nullable/
 type NullableAttr[T any] map[bool]T
 
+// NullableRelationship is a generic type, which implements a field that can be one of three states:
+//
+// - relationship is not set in the request
+// - relationship is explicitly set to `null` in the request
+// - relationship is explicitly set to a valid relationship value in the request
+//
+// NullableRelationship is intended to be used with JSON marshalling and unmarshalling.
+// This is generally useful for PATCH requests, where relationships 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 relationship is expected to be optional, add the `omitempty` JSON tags. Do NOT use `*NullableRelationship`!
+//
+// Slice types are not currently supported for NullableRelationships as the nullable nature can be expressed via empty array
+// `polyrelation` JSON tags are NOT currently supported.
+//
+// NullableRelationships must have an inner type of pointer:
+//
+// - NullableRelationship[*Comment] - valid
+// - NullableRelationship[[]*Comment] - invalid
+// - NullableRelationship[Comment] - invalid
+type NullableRelationship[T any] map[bool]T
+
 // NewNullableAttrWithValue is a convenience helper to allow constructing a
 // NullableAttr with a given value, for instance to construct a field inside a
 // struct without introducing an intermediate variable.
@@ -87,3 +116,66 @@ func (t NullableAttr[T]) IsSpecified() bool {
 func (t *NullableAttr[T]) SetUnspecified() {
 	*t = map[bool]T{}
 }
+
+// NewNullableRelationshipWithValue is a convenience helper to allow constructing a
+// NullableRelationship with a given value, for instance to construct a field inside a
+// struct without introducing an intermediate variable.
+func NewNullableRelationshipWithValue[T any](t T) NullableRelationship[T] {
+	var n NullableRelationship[T]
+	n.Set(t)
+	return n
+}
+
+// NewNullNullableRelationship is a convenience helper to allow constructing a NullableRelationship with
+// an explicit `null`, for instance to construct a field inside a struct
+// without introducing an intermediate variable
+func NewNullNullableRelationship[T any]() NullableRelationship[T] {
+	var n NullableRelationship[T]
+	n.SetNull()
+	return n
+}
+
+// Get retrieves the underlying value, if present, and returns an error if the value was not present
+func (t NullableRelationship[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 *NullableRelationship[T]) Set(value T) {
+	*t = map[bool]T{true: value}
+}
+
+// SetInterface sets the underlying value from an empty interface,
+// performing a type assertion to T.
+func (t *NullableRelationship[T]) SetInterface(value interface{}) {
+	t.Set(value.(T))
+}
+
+// IsNull indicates whether the field was sent, and had a value of `null`
+func (t NullableRelationship[T]) IsNull() bool {
+	_, foundNull := t[false]
+	return foundNull
+}
+
+// SetNull sets the value to an explicit `null`
+func (t *NullableRelationship[T]) SetNull() {
+	var empty T
+	*t = map[bool]T{false: empty}
+}
+
+// IsSpecified indicates whether the field was sent
+func (t NullableRelationship[T]) IsSpecified() bool {
+	return len(t) != 0
+}
+
+// SetUnspecified sets the value to be absent from the serialized payload
+func (t *NullableRelationship[T]) SetUnspecified() {
+	*t = map[bool]T{}
+}

request.go

@@ -487,19 +487,43 @@ func unmarshalNode(data *Node, model reflect.Value, included *map[string]*includ
 				relationship := new(RelationshipOneNode)
 
 				buf := bytes.NewBuffer(nil)
+				relDataStr := data.Relationships[args[1]]
+				json.NewEncoder(buf).Encode(relDataStr)
+
+				isExplicitNull := false
+				relationshipDecodeErr := json.NewDecoder(buf).Decode(relationship)
+				if relationshipDecodeErr == nil && relationship.Data == nil {
+					// If the relationship was a valid node and relationship data was null
+					// this indicates disassociating the relationship
+					isExplicitNull = true
+				} else if relationshipDecodeErr != nil {
+					er = fmt.Errorf("Could not unmarshal json: %w", relationshipDecodeErr)
+				}
 
-				json.NewEncoder(buf).Encode(
-					data.Relationships[args[1]],
-				)
-				json.NewDecoder(buf).Decode(relationship)
+				// This will hold either the value of the choice type model or the actual
+				// model, depending on annotation
+				m := reflect.New(fieldValue.Type().Elem())
 
+				// Nullable relationships have an extra pointer indirection
+				// unwind that here
+				if strings.HasPrefix(fieldType.Type.Name(), "NullableRelationship[") {
+					if m.Kind() == reflect.Ptr {
+						m = reflect.New(fieldValue.Type().Elem().Elem())
+					}
+				}
 				/*
 					http://jsonapi.org/format/#document-resource-object-relationships
 					http://jsonapi.org/format/#document-resource-object-linkage
 					relationship can have a data node set to null (e.g. to disassociate the relationship)
 					so unmarshal and set fieldValue only if data obj is not null
 				*/
 				if relationship.Data == nil {
+					// Explicit null supplied for the field value
+					// If a nullable relationship we set the field value to a map with a single entry
+					if isExplicitNull && strings.HasPrefix(fieldType.Type.Name(), "NullableRelationship[") {
+						fieldValue.Set(reflect.MakeMapWithSize(fieldValue.Type(), 1))
+						fieldValue.SetMapIndex(reflect.ValueOf(false), m)
+					}
 					continue
 				}
 
@@ -510,10 +534,6 @@ func unmarshalNode(data *Node, model reflect.Value, included *map[string]*includ
 					continue
 				}
 
-				// This will hold either the value of the choice type model or the actual
-				// model, depending on annotation
-				m := reflect.New(fieldValue.Type().Elem())
-
 				// Check if the item in the relationship was already processed elsewhere. Avoids potential infinite recursive loops
 				// caused by circular references between included relationships (two included items include one another)
 				includedKey := fmt.Sprintf("%s,%s", relationship.Data.Type, relationship.Data.ID)
@@ -537,7 +557,12 @@ func unmarshalNode(data *Node, model reflect.Value, included *map[string]*includ
 					break
 				}
 
-				fieldValue.Set(m)
+				if strings.HasPrefix(fieldType.Type.Name(), "NullableRelationship[") {
+					fieldValue.Set(reflect.MakeMapWithSize(fieldValue.Type(), 1))
+					fieldValue.SetMapIndex(reflect.ValueOf(true), m)
+				} else {
+					fieldValue.Set(m)
+				}
 			}
 		} else if annotation == annotationLinks {
 			if data.Links == nil {

request_test.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"reflect"
 	"sort"
+	"strconv"
 	"strings"
 	"testing"
 	"time"
@@ -382,6 +383,127 @@ func TestUnmarshalNullableBool(t *testing.T) {
 	}
 }
 
+func TestUnmarshalNullableRelationshipsNonNullValue(t *testing.T) {
+	comment := &Comment{
+		ID:   5,
+		Body: "Hello World",
+	}
+
+	payload := &OnePayload{
+		Data: &Node{
+			ID:   "10",
+			Type: "with-nullables",
+			Relationships: map[string]interface{}{
+				"nullable_comment": &RelationshipOneNode{
+					Data: &Node{
+						Type: "comments",
+						ID:   strconv.Itoa(comment.ID),
+					},
+				},
+			},
+		},
+	}
+
+	outBuf := bytes.NewBuffer(nil)
+	json.NewEncoder(outBuf).Encode(payload)
+
+	out := new(WithNullableAttrs)
+
+	if err := UnmarshalPayload(outBuf, out); err != nil {
+		t.Fatal(err)
+	}
+
+	nullableCommentOpt := out.NullableComment
+	if !nullableCommentOpt.IsSpecified() {
+		t.Fatal("Expected NullableComment to be specified")
+	}
+
+	nullableComment, err := nullableCommentOpt.Get()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if expected, actual := comment.ID, nullableComment.ID; expected != actual {
+		t.Fatalf("Was expecting NullableComment to be `%d`, got `%d`", expected, actual)
+	}
+}
+
+func TestUnmarshalNullableRelationshipsExplicitNullValue(t *testing.T) {
+	payload := &OnePayload{
+		Data: &Node{
+			ID:   "10",
+			Type: "with-nullables",
+			Relationships: map[string]interface{}{
+				"nullable_comment": &RelationshipOneNode{
+					Data: nil,
+				},
+			},
+		},
+	}
+
+	outBuf := bytes.NewBuffer(nil)
+	json.NewEncoder(outBuf).Encode(payload)
+
+	out := new(WithNullableAttrs)
+
+	if err := UnmarshalPayload(outBuf, out); err != nil {
+		t.Fatal(err)
+	}
+
+	nullableCommentOpt := out.NullableComment
+	if !nullableCommentOpt.IsSpecified() || !nullableCommentOpt.IsNull() {
+		t.Fatal("Expected NullableComment to be specified and explicit null")
+	}
+
+}
+
+func TestUnmarshalNullableRelationshipsNonExistentValue(t *testing.T) {
+	payload := &OnePayload{
+		Data: &Node{
+			ID:            "10",
+			Type:          "with-nullables",
+			Relationships: map[string]interface{}{},
+		},
+	}
+
+	outBuf := bytes.NewBuffer(nil)
+	json.NewEncoder(outBuf).Encode(payload)
+
+	out := new(WithNullableAttrs)
+
+	if err := UnmarshalPayload(outBuf, out); err != nil {
+		t.Fatal(err)
+	}
+
+	nullableCommentOpt := out.NullableComment
+	if nullableCommentOpt.IsSpecified() || nullableCommentOpt.IsNull() {
+		t.Fatal("Expected NullableComment to NOT be specified and NOT be explicit null")
+	}
+}
+
+func TestUnmarshalNullableRelationshipsNoRelationships(t *testing.T) {
+	payload := &OnePayload{
+		Data: &Node{
+			ID:   "10",
+			Type: "with-nullables",
+		},
+	}
+
+	outBuf := bytes.NewBuffer(nil)
+	json.NewEncoder(outBuf).Encode(payload)
+
+	out := new(WithNullableAttrs)
+
+	if err := UnmarshalPayload(outBuf, out); err != nil {
+		t.Fatal(err)
+	}
+
+	nullableCommentOpt := out.NullableComment
+	if nullableCommentOpt.IsSpecified() || nullableCommentOpt.IsNull() {
+		t.Fatal("Expected NullableComment to NOT be specified and NOT be explicit null")
+	}
+}
+
 func TestMalformedTag(t *testing.T) {
 	out := new(BadModel)
 	err := UnmarshalPayload(samplePayload(), out)

response.go

@@ -253,7 +253,7 @@ func visitModelNodeAttribute(args []string, node *Node, fieldValue reflect.Value
 		node.Attributes = make(map[string]interface{})
 	}
 
-	// Handle Nullable[T]
+	// Handle NullableAttr[T]
 	if strings.HasPrefix(fieldValue.Type().Name(), "NullableAttr[") {
 		// handle unspecified
 		if fieldValue.IsNil() {
@@ -390,6 +390,28 @@ func visitModelNodeRelation(model any, annotation string, args []string, node *N
 		omitEmpty = args[2] == annotationOmitEmpty
 	}
 
+	if node.Relationships == nil {
+		node.Relationships = make(map[string]interface{})
+	}
+
+	// Handle NullableRelationship[T]
+	if strings.HasPrefix(fieldValue.Type().Name(), "NullableRelationship[") {
+
+		if fieldValue.MapIndex(reflect.ValueOf(false)).IsValid() {
+			innerTypeIsSlice := fieldValue.MapIndex(reflect.ValueOf(false)).Type().Kind() == reflect.Slice
+			// handle explicit null
+			if innerTypeIsSlice {
+				node.Relationships[args[1]] = json.RawMessage("[]")
+			} else {
+				node.Relationships[args[1]] = json.RawMessage("{\"data\":null}")
+			}
+			return nil
+		} else if fieldValue.MapIndex(reflect.ValueOf(true)).IsValid() {
+			// handle value
+			fieldValue = fieldValue.MapIndex(reflect.ValueOf(true))
+		}
+	}
+
 	isSlice := fieldValue.Type().Kind() == reflect.Slice
 	if omitEmpty &&
 		(isSlice && fieldValue.Len() < 1 ||
@@ -454,10 +476,6 @@ func visitModelNodeRelation(model any, annotation string, args []string, node *N
 		}
 	}
 
-	if node.Relationships == nil {
-		node.Relationships = make(map[string]interface{})
-	}
-
 	var relLinks *Links
 	if linkableModel, ok := model.(RelationshipLinkable); ok {
 		relLinks = linkableModel.JSONAPIRelationshipLinks(args[1])