feat: add ApplyPatch function for applying SCIM patch operations

Add a generic ApplyPatch function that applies a sequence of patch
operations (add, replace, remove) to resource attributes, resolving
attribute paths against the provided schema and extensions.

This avoids every consumer having to independently implement the
RFC 7644 Section 3.5.2 patch semantics, which is error-prone and
duplicative.

Author: q-uint

examples_test.go

@@ -1,10 +1,76 @@
 package scim
 
 import (
+	"fmt"
 	logger "log"
 	"net/http"
+
+	"github.com/elimity-com/scim/schema"
+	filter "github.com/scim2/filter-parser/v2"
 )
 
+func ExampleApplyPatch() {
+	// Define the schema for the resource.
+	userSchema := schema.Schema{
+		ID: schema.UserSchema,
+		Attributes: schema.Attributes{
+			schema.SimpleCoreAttribute(schema.SimpleStringParams(schema.StringParams{
+				Name: "userName",
+			})),
+			schema.SimpleCoreAttribute(schema.SimpleStringParams(schema.StringParams{
+				Name: "displayName",
+			})),
+			schema.ComplexCoreAttribute(schema.ComplexParams{
+				Name:        "emails",
+				MultiValued: true,
+				SubAttributes: []schema.SimpleParams{
+					schema.SimpleStringParams(schema.StringParams{Name: "value"}),
+					schema.SimpleStringParams(schema.StringParams{Name: "type"}),
+				},
+			}),
+		},
+	}
+
+	// The resource to patch, typically fetched from a data store.
+	attrs := ResourceAttributes{
+		"userName":    "john",
+		"displayName": "John Doe",
+		"emails": []interface{}{
+			map[string]interface{}{
+				"value": "john@work.com",
+				"type":  "work",
+			},
+		},
+	}
+
+	// Parse paths for the operations.
+	emailsPath, _ := filter.ParsePath([]byte("emails"))
+	workEmailValuePath, _ := filter.ParsePath([]byte(`emails[type eq "work"].value`))
+
+	// Apply a sequence of patch operations.
+	result, err := ApplyPatch(attrs, []PatchOperation{
+		{Op: PatchOperationAdd, Path: &emailsPath, Value: []interface{}{
+			map[string]interface{}{"value": "john@home.com", "type": "home"},
+		}},
+		{Op: PatchOperationReplace, Path: &workEmailValuePath, Value: "john@newwork.com"},
+	}, userSchema)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(result["userName"])
+	emails := result["emails"].([]interface{})
+	fmt.Println(len(emails))
+	fmt.Println(emails[0].(map[string]interface{})["value"])
+	fmt.Println(emails[1].(map[string]interface{})["value"])
+
+	// Output:
+	// john
+	// 2
+	// john@newwork.com
+	// john@home.com
+}
+
 func ExampleNewServer() {
 	args := &ServerArgs{
 		ServiceProviderConfig: &ServiceProviderConfig{},