Enhance API to support string and custom types for JSON Patch operations

Author: robertjndw

README.md

@@ -12,6 +12,7 @@ go get github.com/robertjndw/go-json-patch
 
 - **Apply** a JSON Patch document to a target JSON document
 - **Create** a JSON Patch by diffing two JSON documents
+- **Generic API** — all public functions accept `[]byte`, `string`, or custom types with those underlying types
 - Full support for all six RFC 6902 operations: `add`, `remove`, `replace`, `move`, `copy`, `test`
 - Strict JSON Pointer (RFC 6901) parsing with `~` and `/` escaping and escape validation
 - Atomic patch application — if any operation fails, the entire patch is rejected
@@ -94,6 +95,33 @@ if err != nil {
 }
 ```
 
+### Using Strings Instead of []byte
+
+All public functions accept `string` as well as `[]byte` — no manual conversion needed:
+
+```go
+result, err := jsonpatch.Apply(
+    `{"foo": "bar"}`,
+    `[{"op": "add", "path": "/baz", "value": "qux"}]`,
+)
+// result is a string: {"baz":"qux","foo":"bar"}
+
+patch, err := jsonpatch.CreatePatch(
+    `{"name": "Alice"}`,
+    `{"name": "Bob"}`,
+)
+```
+
+Custom types with an underlying `[]byte` or `string` type also work thanks to the `~` approximation constraint:
+
+```go
+type JSONDoc string
+
+doc := JSONDoc(`{"foo": "bar"}`)
+patch := JSONDoc(`[{"op": "add", "path": "/baz", "value": 1}]`)
+result, err := jsonpatch.Apply(doc, patch)  // result is JSONDoc
+```
+
 ### Build Operations Programmatically
 
 ```go

apply.go

@@ -6,40 +6,43 @@ import (
 	"reflect"
 )
 
-// Apply applies a JSON Patch document (as raw JSON bytes) to a target JSON
-// document (as raw JSON bytes). It returns the patched document as raw JSON
-// bytes. Operations are applied sequentially; if any operation fails, the
-// entire patch is aborted and an error is returned (atomic semantics per
-// RFC 5789).
-func Apply(docJSON, patchJSON []byte) ([]byte, error) {
+// Apply applies a JSON Patch document to a target JSON document.
+// Both arguments must be valid JSON encoded as []byte or string (or any type
+// with one of those underlying types). The return type matches the input type.
+// Operations are applied sequentially; if any operation fails, the entire
+// patch is aborted and an error is returned (atomic semantics per RFC 5789).
+func Apply[D Document](docJSON, patchJSON D) (D, error) {
+	var zero D
 	patch, err := DecodePatch(patchJSON)
 	if err != nil {
-		return nil, err
+		return zero, err
 	}
 	return ApplyPatch(docJSON, patch)
 }
 
-// ApplyPatch applies a decoded Patch to a target JSON document (as raw JSON bytes).
-// It returns the patched document as raw JSON bytes.
-func ApplyPatch(docJSON []byte, patch Patch) ([]byte, error) {
+// ApplyPatch applies a decoded Patch to a target JSON document.
+// The document can be []byte or string (or any type with one of those
+// underlying types). The return type matches the input type.
+func ApplyPatch[D Document](docJSON D, patch Patch) (D, error) {
+	var zero D
 	var doc interface{}
-	if err := json.Unmarshal(docJSON, &doc); err != nil {
-		return nil, fmt.Errorf("failed to decode target document: %w", err)
+	if err := json.Unmarshal(toBytes(docJSON), &doc); err != nil {
+		return zero, fmt.Errorf("failed to decode target document: %w", err)
 	}
 
 	var err error
 	for i, op := range patch {
 		doc, err = applyOperation(doc, op)
 		if err != nil {
-			return nil, fmt.Errorf("operation %d (%s %s) failed: %w", i, op.Op, op.Path, err)
+			return zero, fmt.Errorf("operation %d (%s %s) failed: %w", i, op.Op, op.Path, err)
 		}
 	}
 
 	result, err := json.Marshal(doc)
 	if err != nil {
-		return nil, fmt.Errorf("failed to marshal result: %w", err)
+		return zero, fmt.Errorf("failed to marshal result: %w", err)
 	}
-	return result, nil
+	return fromBytes[D](result), nil
 }
 
 // applyOperation applies a single operation to the document.

create.go

@@ -9,14 +9,15 @@ import (
 
 // CreatePatch generates a JSON Patch document (RFC 6902) that transforms
 // the original JSON document into the modified JSON document.
-// Both arguments must be valid JSON bytes.
-func CreatePatch(original, modified []byte) (Patch, error) {
+// Both arguments must be valid JSON encoded as []byte or string (or any type
+// with one of those underlying types).
+func CreatePatch[D Document](original, modified D) (Patch, error) {
 	var origDoc, modDoc interface{}
 
-	if err := json.Unmarshal(original, &origDoc); err != nil {
+	if err := json.Unmarshal(toBytes(original), &origDoc); err != nil {
 		return nil, fmt.Errorf("failed to decode original document: %w", err)
 	}
-	if err := json.Unmarshal(modified, &modDoc); err != nil {
+	if err := json.Unmarshal(toBytes(modified), &modDoc); err != nil {
 		return nil, fmt.Errorf("failed to decode modified document: %w", err)
 	}
 

generics_test.go

@@ -0,0 +1,274 @@
+package jsonpatch
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// customBytes is a custom type with underlying type []byte, used to test the
+// ~[]byte part of the Document constraint.
+type customBytes []byte
+
+// customString is a custom type with underlying type string, used to test the
+// ~string part of the Document constraint.
+type customString string
+
+// ---------------------------------------------------------------------------
+// Apply – string inputs
+// ---------------------------------------------------------------------------
+
+func TestApply_StringInputs(t *testing.T) {
+	doc := `{"foo": "bar"}`
+	patch := `[{"op": "add", "path": "/baz", "value": "qux"}]`
+
+	result, err := Apply(doc, patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// result should be a string
+	assertJSONEqual(t, `{"baz": "qux", "foo": "bar"}`, result)
+}
+
+func TestApply_StringInputs_Replace(t *testing.T) {
+	doc := `{"name": "Alice", "age": 30}`
+	patch := `[{"op": "replace", "path": "/name", "value": "Bob"}]`
+
+	result, err := Apply(doc, patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assertJSONEqual(t, `{"name": "Bob", "age": 30}`, result)
+}
+
+func TestApply_StringInputs_Remove(t *testing.T) {
+	doc := `{"foo": "bar", "baz": "qux"}`
+	patch := `[{"op": "remove", "path": "/baz"}]`
+
+	result, err := Apply(doc, patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assertJSONEqual(t, `{"foo": "bar"}`, result)
+}
+
+func TestApply_StringInputs_MultipleOps(t *testing.T) {
+	doc := `{"name": "Alice", "email": "alice@example.com"}`
+	patch := `[
+		{"op": "replace", "path": "/name", "value": "Bob"},
+		{"op": "add", "path": "/phone", "value": "+1-555-0100"},
+		{"op": "remove", "path": "/email"}
+	]`
+
+	result, err := Apply(doc, patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assertJSONEqual(t, `{"name": "Bob", "phone": "+1-555-0100"}`, result)
+}
+
+func TestApply_StringInputs_Array(t *testing.T) {
+	doc := `{"tags": ["go", "json"]}`
+	patch := `[{"op": "add", "path": "/tags/-", "value": "patch"}]`
+
+	result, err := Apply(doc, patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assertJSONEqual(t, `{"tags": ["go", "json", "patch"]}`, result)
+}
+
+// ---------------------------------------------------------------------------
+// ApplyPatch – string inputs
+// ---------------------------------------------------------------------------
+
+func TestApplyPatch_StringInput(t *testing.T) {
+	patchOps, err := DecodePatch(`[{"op": "add", "path": "/baz", "value": "qux"}]`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := ApplyPatch(`{"foo": "bar"}`, patchOps)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assertJSONEqual(t, `{"baz": "qux", "foo": "bar"}`, result)
+}
+
+// ---------------------------------------------------------------------------
+// DecodePatch – string input
+// ---------------------------------------------------------------------------
+
+func TestDecodePatch_StringInput(t *testing.T) {
+	patch, err := DecodePatch(`[
+		{"op": "add",     "path": "/foo", "value": 1},
+		{"op": "remove",  "path": "/bar"},
+		{"op": "replace", "path": "/baz", "value": "qux"}
+	]`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if len(patch) != 3 {
+		t.Fatalf("expected 3 operations, got %d", len(patch))
+	}
+	if patch[0].Op != OpAdd {
+		t.Errorf("expected first op to be %q, got %q", OpAdd, patch[0].Op)
+	}
+	if patch[1].Op != OpRemove {
+		t.Errorf("expected second op to be %q, got %q", OpRemove, patch[1].Op)
+	}
+	if patch[2].Op != OpReplace {
+		t.Errorf("expected third op to be %q, got %q", OpReplace, patch[2].Op)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// CreatePatch – string inputs
+// ---------------------------------------------------------------------------
+
+func TestCreatePatch_StringInputs(t *testing.T) {
+	original := `{"foo": "bar"}`
+	modified := `{"foo": "bar", "baz": "qux"}`
+
+	patch, err := CreatePatch(original, modified)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Verify the patch can be applied (using string ApplyPatch)
+	result, err := ApplyPatch(original, patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertJSONEqual(t, modified, result)
+}
+
+func TestCreatePatch_StringInputs_Nested(t *testing.T) {
+	original := `{"user": {"name": "Alice", "role": "viewer"}}`
+	modified := `{"user": {"name": "Alice", "role": "admin"}}`
+
+	patch, err := CreatePatch(original, modified)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := ApplyPatch(original, patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertJSONEqual(t, modified, result)
+}
+
+// ---------------------------------------------------------------------------
+// Custom types (testing the ~ approximation constraint)
+// ---------------------------------------------------------------------------
+
+func TestApply_CustomBytesType(t *testing.T) {
+	doc := customBytes(`{"foo": "bar"}`)
+	patch := customBytes(`[{"op": "add", "path": "/baz", "value": "qux"}]`)
+
+	result, err := Apply(doc, patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// result is customBytes
+	assertJSONEqual(t, `{"baz": "qux", "foo": "bar"}`, string(result))
+}
+
+func TestApply_CustomStringType(t *testing.T) {
+	doc := customString(`{"foo": "bar"}`)
+	patch := customString(`[{"op": "add", "path": "/baz", "value": "qux"}]`)
+
+	result, err := Apply(doc, patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// result is customString
+	assertJSONEqual(t, `{"baz": "qux", "foo": "bar"}`, string(result))
+}
+
+func TestCreatePatch_CustomStringType(t *testing.T) {
+	original := customString(`{"foo": "bar"}`)
+	modified := customString(`{"foo": "baz"}`)
+
+	patch, err := CreatePatch(original, modified)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if len(patch) != 1 {
+		t.Fatalf("expected 1 operation, got %d", len(patch))
+	}
+	if patch[0].Op != OpReplace {
+		t.Errorf("expected replace op, got %q", patch[0].Op)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Round-trip: string → patch → string
+// ---------------------------------------------------------------------------
+
+func TestRoundTrip_StringWorkflow(t *testing.T) {
+	// A complete workflow using only strings — no []byte anywhere
+	original := `{"items": [1, 2, 3], "count": 3}`
+	modified := `{"items": [1, 2, 3, 4], "count": 4}`
+
+	// Create patch from string documents
+	patch, err := CreatePatch(original, modified)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Marshal the patch to JSON (for transport/storage)
+	patchJSON, err := json.Marshal(patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Decode from string
+	decoded, err := DecodePatch(string(patchJSON))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Apply to string document
+	result, err := ApplyPatch(original, decoded)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assertJSONEqual(t, modified, result)
+}
+
+// ---------------------------------------------------------------------------
+// Error cases with string inputs
+// ---------------------------------------------------------------------------
+
+func TestApply_StringInputs_InvalidJSON(t *testing.T) {
+	_, err := Apply(`not valid json`, `[{"op": "add", "path": "/foo", "value": 1}]`)
+	if err == nil {
+		t.Fatal("expected error for invalid JSON document")
+	}
+}
+
+func TestApply_StringInputs_InvalidPatch(t *testing.T) {
+	_, err := Apply(`{"foo": "bar"}`, `not a patch`)
+	if err == nil {
+		t.Fatal("expected error for invalid patch JSON")
+	}
+}
+
+func TestCreatePatch_StringInputs_InvalidOriginal(t *testing.T) {
+	_, err := CreatePatch(`not json`, `{"foo": "bar"}`)
+	if err == nil {
+		t.Fatal("expected error for invalid original JSON")
+	}
+}