feat(core): add generic value-returning retry functions

[kriscoleman]

GoRetry currently provides excellent retry functionality for operations that return only an error (func() error), but many real-world scenarios require retrying operations that return values alongside potential errors (func() (T, error)).

Use Cases:

• Database queries that return data
• API calls that fetch resources
• File operations that read content
• Any operation where the return value is needed on success

Current Workaround:
Users must capture values outside the retry function using closures, which is verbose and not type-safe:

var result SomeType
err := goretry.IfNeeded(func() error {
    var err error
    result, err = someOperation()
    return err
})
// Use 'result' here

Proposed Solution:
Add generic versions of the core retry functions that support value-returning operations:

func IfNeededWithValue[T any](fn func() (T, error), options ...Option) (T, error)
func IfNeededWithPolicyAndValue[T any](policy RetryPolicy, fn func() (T, error), options ...Option) (T, error)
func IfNeededWithContextAndValue[T any](ctx context.Context, fn func(context.Context) (T, error), options ...Option) (T, error)
func IfNeededWithPolicyContextAndValue[T any](ctx context.Context, policy RetryPolicy, fn func(context.Context) (T, error), options ...Option) (T, error)

Benefits:

• Type-safe value handling
• Cleaner, more readable code
• Eliminates error-prone closure patterns
• Maintains the same retry policies and error strategies
• Zero breaking changes to existing API

Acceptance Criteria

• Add generic IfNeededWithValue[T any](fn func() (T, error), options ...Option) (T, error)
• Add generic IfNeededWithPolicyAndValue[T any](policy RetryPolicy, fn func() (T, error), options ...Option) (T, error)
• Add generic IfNeededWithContextAndValue[T any](ctx context.Context, fn func(context.Context) (T, error), options ...Option) (T, error)
• Add generic IfNeededWithPolicyContextAndValue[T any](ctx context.Context, policy RetryPolicy, fn func(context.Context) (T, error), options ...Option) (T, error)
• Ensure all existing retry policies and options work with new functions
• Add comprehensive tests for type safety and error handling
• Update documentation with examples
• Maintain backward compatibility with existing API

Notes

This enhancement would make GoRetry more comprehensive for real-world applications while preserving the excellent design patterns already established. The naming follows the existing convention with "WithValue" suffix to clearly distinguish from error-only variants.

[Adityasinghvats]

Hey @kriscoleman , got to know about your project from LinkedIn, I would like to work on this issue