feat: additional jsonutil features (#15)

This change updates the jsonutil package to add functions related to saving and
loading JSON content to and from disk.  It also adjusts the existing funcions
to accomodate the new functions.

The following are added:

* `UnmarshalFromReaderInto`: This function provides functionality that was
  previously `UnmarshalFromReader`.
* `LoadAs`: This function reads the given path from the filesystem and
  unmarshals it into a new instance of the given type.
* `LoadWith`: This function calls the given read function and unmarshals the
  returned content into a new instance of the given type.
* `Save`: This function unmarshals the given instance and writes it to the
  specified path in the filesystem.
* `SaveWith`: this funcion unmarshals the given instance and passes the
  content, specified path, and specified mode to the specified write function.

The following have been updated:

* `PrintJSONOn`: This funtion no longer includes a trailing newline in content
  written to the provided io.Writer. It has been updated to take a type
  parameter.
* `ToJSON`: This function no longer includes a trainling newlint in the
  returned string. It has been updated to take a type parameter.
* `UnmarshalFromReader`: This function has been updated to return a new
  instance of the type being unmarshaled. The previous behavior of updating a
  instance allocated by the caller is now provided by `UnmarshalFromReaderInto`

Signed-off-by: m-d-key <[email protected]>
Co-authored-by: m-d-key <[email protected]>

Author: m-d-key

README.md

@@ -70,8 +70,12 @@ make test-with-coverage
 
 ### Commits
 
-This project uses [semantic versioning](https://semver.org/) and [conventional
-commits](https://www.conventionalcommits.org/en/v1.0.0/).
+This project currently uses loose [semantic versioning](https://semver.org/) and
+[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). The API
+is undergoing rapid evolution until 1.0 is released. An evaluation will be made
+at that time as to how strictly semantic versioning will be followed. Efforts
+will be made to communicate breaking changes but please pin to a specific
+version until then.
 
 ## License
 

pkg/jsonutils/jsonutils.go

@@ -8,63 +8,106 @@ import (
 	"fmt"
 	"io"
 	"os"
-	"strings"
 
 	"github.com/sassoftware/sas-ggdk/pkg/result"
 )
 
+const (
+	prefix = ``
+	indent = `    `
+)
+
 // PrintJSONOn pretty-prints the given data as JSON on the given writer. If the
 // given data is not valid JSON an error is returned.
-func PrintJSONOn(data any, writer io.Writer) error {
-	bites, err := json.MarshalIndent(data, ``, `    `)
-	if err != nil {
+func PrintJSONOn[T any](data T, writer io.Writer) error {
+	bites := result.New(json.MarshalIndent(data, prefix, indent))
+	return result.MapErrorOnly(func(b []byte) error {
+		_, err := fmt.Fprintf(writer, "%s", b)
 		return err
-	}
-	content := string(bites)
-	_, err = fmt.Fprintf(writer, "%s\n", content)
-	return err
+	}, bites)
 }
 
 // ToJSON returns a pretty-printed JSON string for the given data. If the given
 // data is not valid JSON an error is returned. If you are marshaling a large
 // data structure and are concerned about the performance of iteratively growing
 // the destination strings.Builder then create your own builder, grow it to your
-// expected size, and then call PrintJSONOn.
-func ToJSON(data any) result.Result[string] {
-	writer := new(strings.Builder)
-	err := PrintJSONOn(data, writer)
-	if err != nil {
-		return result.Error[string](err)
-	}
-	content := writer.String()
-	return result.Ok(content)
+// expected size, and then call PrintJSONOn. If you want the bytes then call the
+// following.
+//
+//	result.New(json.MarshalIndent(data, ``, `    `))
+func ToJSON[T any](data T) result.Result[string] {
+	bites := result.New(json.MarshalIndent(data, prefix, indent))
+	return result.MapNoError(func(b []byte) string { return string(b) }, bites)
 }
 
-// UnmarshalFromReader inflates the JSON in the given reader and populates the
-// given instance. If the data in the reader is not valid JSON an error is
-// returned.
-func UnmarshalFromReader(reader io.Reader, instance any) error {
-	bites, err := io.ReadAll(reader)
-	if err != nil {
-		return err
-	}
-	err = json.Unmarshal(bites, instance)
-	if err != nil {
-		return err
-	}
-	return nil
+// UnmarshalFromReader unmarshals the JSON from the given reader and populates a
+// new instance of T. The reader will be read fully before returning. If the
+// data in the reader is not valid JSON an error is returned.
+func UnmarshalFromReader[T any](reader io.Reader) result.Result[T] {
+	bites := result.New(io.ReadAll(reader))
+	return result.FlatMap(UnmarshalAs[T], bites)
+}
+
+// UnmarshalAs ummarshals the given content into a result of a new instance of T.
+func UnmarshalAs[T any](content []byte) result.Result[T] {
+	var t T
+	err := json.Unmarshal(content, &t)
+	return result.New(t, err)
+}
+
+// UnmarshalFromReaderInto unmarshals the JSON from the given reader and
+// populates the given instance. The reader will be read fully before returning.
+// If the data in the reader is not valid JSON an error is returned.
+func UnmarshalFromReaderInto[T any](reader io.Reader, value *T) error {
+	bites := result.New(io.ReadAll(reader))
+	return result.MapErrorOnly(func(b []byte) error {
+		return json.Unmarshal(b, value)
+	}, bites)
 }
 
 // LoadAs reads the content from the given path and ummarshals it into a result
 // of a new instance of T.
 func LoadAs[T any](path string) result.Result[T] {
-	content := result.New(os.ReadFile(path))
+	return LoadWith[T](os.ReadFile, path)
+}
+
+// LoadWith passes the given path to the given read function to get the content.
+// That content is then marshaled into a result of a new instance of T. This is
+// useful when using a file system abstraction like
+// https://github.com/spf13/afero.
+//
+//	fs := afero.Afero{Fs: afero.NewMemMapFs()}
+//	err := jsonutils.LoadWith[string](fs.ReadFile, "/tmp/person.json")
+func LoadWith[T any](
+	read func(string) ([]byte, error),
+	path string,
+) result.Result[T] {
+	content := result.New(read(path))
 	return result.FlatMap(UnmarshalAs[T], content)
 }
 
-// UnmarshalAs ummarshals the given content into a result of anew instance of T.
-func UnmarshalAs[T any](content []byte) result.Result[T] {
-	var t T
-	err := json.Unmarshal(content, &t)
-	return result.New(t, err)
+// Save marshals the given T and writes it to a file at the given path with the
+// given permissions. The file is truncated if it exists.
+func Save[T any](value T, path string, perm os.FileMode) error {
+	return SaveWith(os.WriteFile, value, path, perm)
+}
+
+// SaveWith marshals the given T and calls the given writeFunc with the
+// resulting content, given path, and given permissions.This is
+// useful when using a file system abstraction like
+// https://github.com/spf13/afero.
+//
+//	fs := afero.Afero{Fs: afero.NewMemMapFs()}
+//	err := jsonutils.SaveWith(fs.WriteFile, instance, "/tmp/person.json", 0700)
+func SaveWith[T any](
+	writeFunc func(string, []byte, os.FileMode) error,
+	value T,
+	path string,
+	perm os.FileMode,
+) error {
+	content := result.New(json.Marshal(value))
+	writeF := func(b []byte) error {
+		return writeFunc(path, b, perm)
+	}
+	return result.MapErrorOnly(writeF, content)
 }

pkg/jsonutils/jsonutils_test.go

@@ -39,7 +39,7 @@ func Test_PrintJSONOn(t *testing.T) {
 	err = jsonutils.PrintJSONOn(instance, buffer)
 	require.NoError(t, err)
 	actual := buffer.Bytes()
-	require.Equal(t, expected, actual)
+	require.Equal(t, bytes.TrimSpace(expected), actual)
 }
 
 func Test_PrintJSONOn_fail(t *testing.T) {
@@ -65,7 +65,7 @@ func Test_ToJSON(t *testing.T) {
 	require.NoError(t, err)
 	actual := jsonutils.ToJSON(instance)
 	require.NoError(t, actual.Error())
-	require.Equal(t, expected, actual.MustGet())
+	require.Equal(t, strings.TrimSpace(expected), actual.MustGet())
 }
 
 func Test_ToJSON_fail(t *testing.T) {
@@ -81,10 +81,19 @@ func Test_ToJSON_fail(t *testing.T) {
 }
 
 func Test_UnmarshalFromReader(t *testing.T) {
+	reader, err := toTestdataFile(jsonFilename)
+	require.NoError(t, err)
+	r := jsonutils.UnmarshalFromReader[person](reader)
+	require.False(t, r.IsError())
+	require.Equal(t, personName, r.MustGet().Name)
+	require.Equal(t, personAge, r.MustGet().Age)
+}
+
+func Test_UnmarshalFromReaderInto(t *testing.T) {
 	reader, err := toTestdataFile(jsonFilename)
 	require.NoError(t, err)
 	instance := new(person)
-	err = jsonutils.UnmarshalFromReader(reader, instance)
+	err = jsonutils.UnmarshalFromReaderInto(reader, instance)
 	require.NoError(t, err)
 	require.Equal(t, personName, instance.Name)
 	require.Equal(t, personAge, instance.Age)
@@ -98,13 +107,27 @@ func (reader *failingReader) Read(_ []byte) (n int, err error) {
 
 func Test_UnmarshalFromReader_failingReader(t *testing.T) {
 	reader := new(failingReader)
-	err := jsonutils.UnmarshalFromReader(reader, nil)
-	require.Error(t, err)
+	r := jsonutils.UnmarshalFromReader[int](reader)
+	require.True(t, r.IsError())
+	require.Error(t, r.Error())
 }
 
 func Test_UnmarshalFromReader_failingUnmarshal(t *testing.T) {
 	reader := strings.NewReader(`not JSON`)
-	err := jsonutils.UnmarshalFromReader(reader, nil)
+	r := jsonutils.UnmarshalFromReader[int](reader)
+	require.True(t, r.IsError())
+	require.Error(t, r.Error())
+}
+
+func Test_UnmarshalFromReaderInto_failingReader(t *testing.T) {
+	reader := new(failingReader)
+	err := jsonutils.UnmarshalFromReaderInto[int](reader, nil)
+	require.Error(t, err)
+}
+
+func Test_UnmarshalFromReaderInto_failingUnmarshal(t *testing.T) {
+	reader := strings.NewReader(`not JSON`)
+	err := jsonutils.UnmarshalFromReaderInto[int](reader, nil)
 	require.Error(t, err)
 }
 
@@ -133,6 +156,81 @@ func Test_LoadAs_fail(t *testing.T) {
 	require.True(t, actual.IsError())
 }
 
+func Test_LoadWith(t *testing.T) {
+	expected := person{
+		Name: "John Smith",
+		Age:  75,
+	}
+	readF := func(_ string) ([]byte, error) {
+		return []byte(`{"name":"John Smith","age":75}`), nil
+	}
+	actual := jsonutils.LoadWith[person](readF, "/tmp/person.json")
+	require.False(t, actual.IsError())
+	require.Equal(t, expected, actual.MustGet())
+}
+
+func Test_LoadWith_ptr(t *testing.T) {
+	expectedPtr := &person{
+		Name: "John Smith",
+		Age:  75,
+	}
+	readF := func(_ string) ([]byte, error) {
+		return []byte(`{"name":"John Smith","age":75}`), nil
+	}
+	actualPtr := jsonutils.LoadWith[*person](readF, "/tmp/person.json")
+	require.False(t, actualPtr.IsError())
+	require.Equal(t, expectedPtr, actualPtr.MustGet())
+}
+
+func Test_LoadWith_fail(t *testing.T) {
+	readF := func(_ string) ([]byte, error) {
+		return []byte{}, errors.New("failed")
+	}
+	actual := jsonutils.LoadWith[person](readF, "/tmp/missing.json")
+	require.True(t, actual.IsError())
+}
+
+func Test_Save(t *testing.T) {
+	instance := person{
+		Name: "John Smith",
+		Age:  75,
+	}
+	tmpdir := t.TempDir()
+	path := filepath.Join(tmpdir, "person.json")
+	err := jsonutils.Save(instance, path, 0700)
+	require.NoError(t, err)
+	defer func() { require.NoError(t, os.RemoveAll(tmpdir)) }()
+	_, err = os.Stat(path)
+	require.NoError(t, err)
+}
+
+func Test_SaveWith(t *testing.T) {
+	instance := person{
+		Name: "John Smith",
+		Age:  75,
+	}
+	called := false
+	saveF := func(_ string, _ []byte, _ os.FileMode) error {
+		called = true
+		return nil
+	}
+	err := jsonutils.SaveWith(saveF, instance, "/tmp/person.json", 0700)
+	require.NoError(t, err)
+	require.True(t, called)
+}
+
+func Test_SaveWith_failed(t *testing.T) {
+	instance := person{
+		Name: "John Smith",
+		Age:  75,
+	}
+	saveF := func(_ string, _ []byte, _ os.FileMode) error {
+		return errors.New("failed")
+	}
+	err := jsonutils.SaveWith(saveF, instance, "/tmp/person.json", 0700)
+	require.Error(t, err)
+}
+
 func Test_UnmarshalAs(t *testing.T) {
 	expectedPtr := person{
 		Name: "John Smith",