Refactoring for the future

The existing OnSuccess methods conflate a mix of “map” and “tap” behaviours. With @golavr’s addition of useful new Tap methods, several problems with the library are starting to coalesce:

• New users may find it harder to know when to use OnSuccess vs Tap. Some of the signatures overlap, with duplicate logic (i.e. the existing tap-like OnSuccess signatures).
• Map might seem redundant to a new user - it just passes through to OnSuccess. But semantically it is perhaps more useful.
• It can be hard to infer intent/behaviour, because OnSuccess is trying to do two things: Map to new results, and Tap that feeds forward the starting result unchanged, having executed a side Action.

(See also discussion on #134.)

I propose the following solutions:

1. Refactor OnSuccess into Map and Tap. Map methods always return new results (or whatever the user chooses to return from the Func parameters that receive the current value/result). Conversely, Tap methods return the starting result unchanged, the action that gets called therefore having no side effects in the chain itself.

2. Mark OnSuccess as [Obsolete] to encourage uptake of Map and Tap instead. (If and when there is appetite for a version bump to v2, OnSuccess could be removed to keep the codebase lean, but this is not pressing.)

3. With a move away from OnSuccess, OnBoth makes a lot less sense semantically. I propose refactoring it to Finally. This encapsulates the sense that these actions occur “no matter what”. Also, as this method doesn’t return a Result, it can only ever appear last in the chain. 😃

I have created a PR which incorporates these changes, plus some other fairly significant refactoring that hopefully will make the library easier to maintain going forward (e.g. breaking up the code into separate files).

This incorporates @golavr’s Tap PR, and other than the [Obsolete] attributes and some improvements to the Match signatures, I tried to avoid any other potentially breaking changes.

The examples are updated with the new semantics swapped in to give an idea.

Look forward to your thoughts.

[space-alien]

All done.

[space-alien]

Have a look at the home page of this repo, the Examples project, the notes on issue #152 (needs a bit of updating), and also if you have existing code that uses OnSuccess, I believe you should get warnings telling you which new methods to use when you upgrade the package.