Introduce toResult to lift task errors into a Result (#37)

Author: mpizenberg

src/ConcurrentTask.elm

@@ -5,7 +5,7 @@ module ConcurrentTask exposing
     , onResponseDecoderFailure, onJsException
     , mapError, onError
     , succeed, fail, andThen
-    , fromResult, andThenDo, return, debug
+    , fromResult, toResult, andThenDo, return, debug
     , batch, sequence
     , map, andMap, map2, map3, map4, map5
     , attempt, attemptEach, Response(..), UnexpectedError(..), onProgress, Pool, pool
@@ -68,7 +68,7 @@ Lift `UnexpectedError`s into regular task flow.
 
 These are some general helpers that can make chaining, combining and debugging tasks more convenient.
 
-@docs fromResult, andThenDo, return, debug
+@docs fromResult, toResult, andThenDo, return, debug
 
 
 # Batch Helpers
@@ -621,6 +621,56 @@ fromResult =
     Internal.fromResult
 
 
+{-| Lift a failed task into a successful one reporting the error with a `Result` type.
+
+The main use case for this function is to get more localised errors.
+Typically, your `Msg` type will only contain a single pair of `OnProgress` and `OnComplete` variants.
+
+    type Msg
+        = ...
+        | OnProgress ( ConcurrentTask.Pool Msg, Cmd Msg )
+        | OnComplete (ConcurrentTask.Response TaskError TaskCompleted)
+
+    type TaskCompleted
+        = GotThingOne ThingOne
+        | GotThingTwo ThingTwo
+
+In the above situation, you would handle all errors in the same branch of your update function:
+
+    case response of
+        ConcurrentTask.Error error -> ... -- handle all errors
+        ConcurrentTask.Success ... -> ... -- handle successes
+
+However, if instead of running `myTask`, you run `ConcurrentTask.toResult myTask`
+and adjust your `TaskCompleted` type to handle results, you obtain errors that are local to the task.
+
+    type TaskCompleted
+        = GotThingOne (Result ErrorOne ThingOne)
+        | GotThingTwo (Result ErrorTwo ThingTwo)
+
+This pattern makes it easier to handle potential failures at the same place where you would handle correct answers.
+It also mirrors the behavior of the elm/http library where each message variant handles its own errors.
+
+    -- Example from elm/http
+    type Msg
+        = GotBook (Result Http.Error String)
+        | GotItems (Result Http.Error (List String))
+
+    -- ConcurrentTask example of handling errors lifted to a task Result.
+    case response of
+        ConcurrentTask.Error error -> ... -- handle non-lifted errors
+        ConcurrentTask.Success (GotThingOne result) ->
+            -- deal with the first task result
+        ConcurrentTask.Success (GotThingTwo result) ->
+            -- deal with the second task result
+
+-}
+toResult : ConcurrentTask err a -> ConcurrentTask x (Result err a)
+toResult task =
+    map Ok task
+        |> onError (Err >> succeed)
+
+
 {-| Similar to `andThen` but ignores the successful result of the previous Task.
 
 Maybe you want to save a file then log a message to the console: