Add deprecation warnings and documentation

CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.29.0] - 2024-03-24
+### Added
+- `asciiext` package for ASCII related functions.
+- `errorsext.Retrier` configurable retry helper for any fallible operation.
+- `httpext.Retrier` configurable retry helper for HTTP requests and parsing of responses.
+
 ## [5.28.1] - 2024-02-14
 ### Fixed
 - Additional supported types, cast to `sql.Valuer` supported types, they need to be returned to the driver for evaluation.
@@ -120,7 +126,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Added `timext.NanoTime` for fast low level monotonic time with nanosecond precision.
 
-[Unreleased]: https://github.com/go-playground/pkg/compare/v5.28.1...HEAD
+[Unreleased]: https://github.com/go-playground/pkg/compare/v5.29.0...HEAD
+[5.29.0]: https://github.com/go-playground/pkg/compare/v5.28.1..v5.29.0
 [5.28.1]: https://github.com/go-playground/pkg/compare/v5.28.0..v5.28.1
 [5.28.0]: https://github.com/go-playground/pkg/compare/v5.27.0..v5.28.0
 [5.27.0]: https://github.com/go-playground/pkg/compare/v5.26.0..v5.27.0

README.md

@@ -1,6 +1,6 @@
 # pkg
 
-![Project status](https://img.shields.io/badge/version-5.28.0-green.svg)
+![Project status](https://img.shields.io/badge/version-5.29.0-green.svg)
 [![Lint & Test](https://github.com/go-playground/pkg/actions/workflows/go.yml/badge.svg)](https://github.com/go-playground/pkg/actions/workflows/go.yml)
 [![Coverage Status](https://coveralls.io/repos/github/go-playground/pkg/badge.svg?branch=master)](https://coveralls.io/github/go-playground/pkg?branch=master)
 [![GoDoc](https://godoc.org/github.com/go-playground/pkg?status.svg)](https://pkg.go.dev/mod/github.com/go-playground/pkg/v5)
@@ -23,7 +23,7 @@ This is a place to put common reusable code that is not quite a library but exte
 - Generic Mutex and RWMutex.
 - Bytes helper placeholders units eg. MB, MiB, GB, ...
 - Detachable context.
-- Error retryable helper functions.
+- Retrier for helping with any fallible operation.
 - Proper RFC3339Nano definition.
 - unsafe []byte->string & string->[]byte helper functions.
 - HTTP helper functions and constant placeholders.

errors/do.go

@@ -5,6 +5,7 @@ package errorsext
 
 import (
 	"context"
+
 	optionext "github.com/go-playground/pkg/v5/values/option"
 	resultext "github.com/go-playground/pkg/v5/values/result"
 )
@@ -21,6 +22,8 @@ type IsRetryableFn[E any] func(err E) (reason string, isRetryable bool)
 type OnRetryFn[E any] func(ctx context.Context, originalErr E, reason string, attempt int) optionext.Option[E]
 
 // DoRetryable will execute the provided functions code and automatically retry using the provided retry function.
+//
+// Deprecated: use `errorsext.Retrier` instead which corrects design issues with the current implementation.
 func DoRetryable[T, E any](ctx context.Context, isRetryFn IsRetryableFn[E], onRetryFn OnRetryFn[E], fn RetryableFn[T, E]) resultext.Result[T, E] {
 	var attempt int
 	for {

net/http/retryable.go

@@ -93,6 +93,8 @@ type BuildRequestFn func(ctx context.Context) (*http.Request, error)
 type IsRetryableStatusCodeFn func(code int) bool
 
 // DoRetryableResponse will execute the provided functions code and automatically retry before returning the *http.Response.
+//
+// Deprecated: use `httpext.Retrier` instead which corrects design issues with the current implementation.
 func DoRetryableResponse(ctx context.Context, onRetryFn errorsext.OnRetryFn[error], isRetryableStatusCode IsRetryableStatusCodeFn, client *http.Client, buildFn BuildRequestFn) Result[*http.Response, error] {
 	if client == nil {
 		client = http.DefaultClient
@@ -135,6 +137,8 @@ func DoRetryableResponse(ctx context.Context, onRetryFn errorsext.OnRetryFn[erro
 // Gzip supported:
 // - JSON
 // - XML
+//
+// Deprecated: use `httpext.Retrier` instead which corrects design issues with the current implementation.
 func DoRetryable[T any](ctx context.Context, isRetryableFn errorsext.IsRetryableFn[error], onRetryFn errorsext.OnRetryFn[error], isRetryableStatusCode IsRetryableStatusCodeFn, client *http.Client, expectedResponseCode int, maxMemory bytesext.Bytes, buildFn BuildRequestFn) Result[T, error] {
 
 	return errorsext.DoRetryable(ctx, isRetryableFn, onRetryFn, func(ctx context.Context) Result[T, error] {