test: supply example tests for custom encoder and decoder

encoder.go

@@ -19,11 +19,11 @@ func DoStrict[S Base64Encoding, T Stricter[S]](x T) Base64Encoding {
 	return x.Strict()
 }
 
-// JSONMarshalFunc is an function type that allows to implement custom JSON
+// JSONMarshalFunc is a function type that allows to implement custom JSON
 // encoding algorithms.
 type JSONMarshalFunc func(v any) ([]byte, error)
 
-// JSONUnmarshalFunc is an function type that allows to implement custom JSON
+// JSONUnmarshalFunc is a function type that allows to implement custom JSON
 // unmarshal algorithms.
 type JSONUnmarshalFunc func(data []byte, v any) error
 

example_test.go

@@ -1,6 +1,8 @@
 package jwt_test
 
 import (
+	"encoding/base64"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"log"
@@ -9,6 +11,21 @@ import (
 	"github.com/golang-jwt/jwt/v5"
 )
 
+// Example creating a token by passing jwt.WithJSONEncoder or jwt.WithBase64Encoder to
+// options to specify the custom encoders when sign the token to string.
+// You can try other encoders when you get tired of the standard library.
+func ExampleNew_customEncoder() {
+	mySigningKey := []byte("AllYourBase")
+
+	customJSONEncoderFunc := json.Marshal
+	customBase64Encoder := base64.RawURLEncoding
+	token := jwt.New(jwt.SigningMethodHS256, jwt.WithJSONEncoder(customJSONEncoderFunc), jwt.WithBase64Encoder(customBase64Encoder))
+
+	ss, err := token.SignedString(mySigningKey)
+	fmt.Println(ss, err)
+	// Output: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.E9f4bo8SFbMyEfLEOEXEO2RGcO9cQhznYfSKqTjWwrM <nil>
+}
+
 // Example (atypical) using the RegisteredClaims type by itself to parse a token.
 // The RegisteredClaims type is designed to be embedded into your custom types
 // to provide standard validation features.  You can use it alone, but there's
@@ -161,6 +178,35 @@ func ExampleParseWithClaims_customValidation() {
 	// Output: bar test
 }
 
+// Example parsing a string to a token with using a custom decoders.
+// It's convenient to use the jwt.WithJSONDecoder or jwt.WithBase64Decoder options when create a parser
+// to parse string to token by using your favorite JSON or Base64 decoders.
+func ExampleParseWithClaims_customDecoder() {
+	tokenString := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIiLCJpc3MiOiJ0ZXN0IiwiYXVkIjoic2luZ2xlIn0.QAWg1vGvnqRuCFTMcPkjZljXHh8U3L_qUjszOtQbeaA"
+
+	customJSONUnmarshalFunc := json.Unmarshal
+	customNewJSONDecoderFunc := json.NewDecoder
+
+	customBase64RawUrlEncoder := base64.RawURLEncoding
+	customBase64UrlEncoder := base64.URLEncoding
+
+	jwtParser := jwt.NewParser(jwt.WithJSONDecoder(customJSONUnmarshalFunc, customNewJSONDecoderFunc), jwt.WithBase64Decoder(customBase64RawUrlEncoder, customBase64UrlEncoder))
+
+	token, err := jwtParser.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
+		return []byte("AllYourBase"), nil
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	if !token.Valid {
+		log.Fatal("invalid")
+	} else {
+		fmt.Println("valid")
+	}
+
+	// Output: valid
+}
+
 // An example of parsing the error types using errors.Is.
 func ExampleParse_errorChecking() {
 	// Token from another example.  This token is expired

token_test.go

@@ -41,7 +41,7 @@ func TestToken_SigningString(t1 *testing.T) {
 			wantErr: false,
 		},
 		{
-			name: "",
+			name: "encode with custom json and base64 encoder",
 			fields: fields{
 				Raw:    "",
 				Method: jwt.SigningMethodHS256,