docs: document NullableAttr and provide example usage

Author: ctrombley

README.md

@@ -409,6 +409,72 @@ func (post Post) JSONAPIRelationshipMeta(relation string) *Meta {
 }
 ```
 
+### Nullable attributes
+
+Certain APIs may interpret the meaning of `null` attribute values as significantly
+different from unspecified values (those that do not show up in the request).
+The default use of the `omitempty` struct tag does not allow for sending
+significant `null`s.
+
+A type is provided for this purpose if needed: `NullableAttr[T]`. This type
+provides an API for sending and receiving significant `null` values for
+attribute values of any type.
+
+In the example below, a payload is presented for a fictitious API that makes use
+of significant `null` values. Once enabled, the `UnsettableTime` setting can
+only be disabled by updating it to a `null` value. 
+
+The payload struct below makes use of a `NullableAttr` with an inner `time.Time`
+to allow this behavior:
+
+```go
+type Settings struct {
+	ID             int                              `jsonapi:"primary,videos"`
+	UnsettableTime jsonapi.NullableAttr[time.Time]  `jsonapi:"attr,unsettable_time,rfc3339,omitempty"`
+}
+```
+
+To enable the setting as described above, an non-null `time.Time` value is
+sent to the API.  This is done by using the exported
+`NewNullableAttrWithValue[T]()` method:
+
+```go
+s := Settings{
+    ID: 1,
+    UnsettableTime: jsonapi.NewNullableAttrWithValue[time.Time](time.Now()),
+}
+```
+
+To disable the setting, a `null` value needs to be sent to the API. This is done
+by using the exported `NewNullNullableAttr[T]()` method:
+
+```go
+s := Settings{
+    ID: 1,
+    UnsettableTime: jsonapi.NewNullNullableAttr[time.Time](),
+}
+```
+
+Once a payload has been marshaled, the attribute value is flattened to a
+primitive value:
+```
+    "unsettable_time": "2021-01-01T02:07:14Z",
+```
+
+Significant nulls are also included and flattened, even when specifying `omitempty`:
+```
+    "unsettable_time": null,
+```
+
+Once a payload is unmarshaled, the target attribute field is hydrated with
+the value in the payload and can be retrieved with the `Get()` method:
+```go
+t, err := s.UnsettableTime.Get()
+```
+
+All other struct tags used in the attribute definition will be honored when
+marshaling and unmarshaling non-null values for the inner type.
+
 ### Custom types
 
 Custom types are supported for primitive types, only, as attributes.  Examples,

examples/app.go

@@ -96,6 +96,28 @@ func exerciseHandler() {
 	fmt.Println(buf.String())
 	fmt.Println("============== end raw jsonapi response =============")
 
+	// update
+	blog.UnsettableTime = jsonapi.NewNullableAttrWithValue[time.Time](time.Now())
+	in = bytes.NewBuffer(nil)
+	jsonapi.MarshalOnePayloadEmbedded(in, blog)
+
+	req, _ = http.NewRequest(http.MethodPatch, "/blogs", in)
+
+	req.Header.Set(headerAccept, jsonapi.MediaType)
+
+	w = httptest.NewRecorder()
+
+	fmt.Println("============ start update ===========")
+	http.DefaultServeMux.ServeHTTP(w, req)
+	fmt.Println("============ stop update ===========")
+
+	buf = bytes.NewBuffer(nil)
+	io.Copy(buf, w.Body)
+
+	fmt.Println("============ jsonapi response from update ===========")
+	fmt.Println(buf.String())
+	fmt.Println("============== end raw jsonapi response =============")
+
 	// echo
 	blogs := []interface{}{
 		fixtureBlogCreate(1),

examples/fixtures.go

@@ -1,6 +1,8 @@
 package main
 
-import "time"
+import (
+	"time"
+)
 
 func fixtureBlogCreate(i int) *Blog {
 	return &Blog{

examples/handler.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"fmt"
 	"net/http"
 	"strconv"
 
@@ -25,6 +26,8 @@ func (h *ExampleHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	switch r.Method {
 	case http.MethodPost:
 		methodHandler = h.createBlog
+	case http.MethodPatch:
+		methodHandler = h.updateBlog
 	case http.MethodPut:
 		methodHandler = h.echoBlogs
 	case http.MethodGet:
@@ -61,6 +64,28 @@ func (h *ExampleHandler) createBlog(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+func (h *ExampleHandler) updateBlog(w http.ResponseWriter, r *http.Request) {
+	jsonapiRuntime := jsonapi.NewRuntime().Instrument("blogs.update")
+
+	blog := new(Blog)
+
+	if err := jsonapiRuntime.UnmarshalPayload(r.Body, blog); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	fmt.Println(blog)
+
+	// ...do stuff with your blog...
+
+	w.WriteHeader(http.StatusCreated)
+	w.Header().Set(headerContentType, jsonapi.MediaType)
+
+	if err := jsonapiRuntime.MarshalPayload(w, blog); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+	}
+}
+
 func (h *ExampleHandler) echoBlogs(w http.ResponseWriter, r *http.Request) {
 	jsonapiRuntime := jsonapi.NewRuntime().Instrument("blogs.list")
 	// ...fetch your blogs, filter, offset, limit, etc...

examples/models.go

@@ -9,13 +9,14 @@ import (
 
 // Blog is a model representing a blog site
 type Blog struct {
-	ID            int       `jsonapi:"primary,blogs"`
-	Title         string    `jsonapi:"attr,title"`
-	Posts         []*Post   `jsonapi:"relation,posts"`
-	CurrentPost   *Post     `jsonapi:"relation,current_post"`
-	CurrentPostID int       `jsonapi:"attr,current_post_id"`
-	CreatedAt     time.Time `jsonapi:"attr,created_at"`
-	ViewCount     int       `jsonapi:"attr,view_count"`
+	ID             int                             `jsonapi:"primary,blogs"`
+	Title          string                          `jsonapi:"attr,title"`
+	Posts          []*Post                         `jsonapi:"relation,posts"`
+	CurrentPost    *Post                           `jsonapi:"relation,current_post"`
+	CurrentPostID  int                             `jsonapi:"attr,current_post_id"`
+	CreatedAt      time.Time                       `jsonapi:"attr,created_at"`
+	UnsettableTime jsonapi.NullableAttr[time.Time] `jsonapi:"attr,unsettable_time,rfc3339,omitempty"`
+	ViewCount      int                             `jsonapi:"attr,view_count"`
 }
 
 // Post is a model representing a post on a blog