Solution has had quite some time during which it seems like the interface as it currently stands works well.

Therefore, a stable 1.0 version will probably be released soon .

Stable version 1.0.0 has now been released!

There are no API changes, although there have been a few cleanups to the README and the documentation.

Did you try to look at hex.pm before you wrote your library? It seems to me that your lib has a lot of common with a few others, e.g. result or ok.

An excellent question. I most certainly did!

Solution is meant to be more general and more lightweight/idiomatic in its approach.
Let’s compare it with the six other commonly mentioned libraries that work with ok/error tuples:

Comparing it to the ok library:

• OK requires ok/error tuples to always exactly have two elements (the first being :ok or :error, the second being a value). This means that plain :ok or :error are not handled, nor are results like {:ok, value, meta} which are relatively common in production Elixir (c.f. Ecto Multi).
• OK introduces a new ‘keyword’ called OK.for which sort of takes the place of Elixir’s with but not completely (I think?), which is also subject to above caveat.
• OK has a wrapper called OK.try which is sort of like OK.for but wraps it in an extra try/rescue block (I think?).
• OK contains a couple of custom operators to allow ‘monadic piping’.

Solution’s swith and scase statements on the other hand work 1:1 like the built-in counterparts, except that you can add the ok(...) and error(...) macros at the LHS of the matches to match any ok/error tuple that has at least the required length. I believe that the library therefore has much less of a learning curve and much less mental overhead.

Comparing it to the result library:

• Result has a bunch of monad-inspired functions, but no overloaded case or with statements.
• Just like OK, Result only accepts exactly the format {:ok, value}/{:error, problem}.

Comparing it to the exceptional library:

• Exceptional has features to declaw exceptions and turn them into plain structs or possibly ok/error tuples, and reraise them later. Handling exceptions is not a design goal of Solution, so it does not have this functionality.
• Exceptional also has custom ‘monadic piping’ operators.
• Handling different kinds of tagged tuples is not a design goal of Exceptional, so it does not have functionality to work with these datatypes (other than a basic ‘normalization’ conversion, which also does not handle ok/error tuples with more than one value inside). EDIT: It’s slightly more nuanced than that. see this follow-up.

Comparing it to the towel library:

• Towel also takes the approach of a ‘monadic pipeline’. Not with special syntax this time, but using a couple of functions (that are probably part of your global namespace since it advocates to use Towel).
• Towel does not have support for values of the type :ok/:error nor for {:ok, multiple, things}`.
• Towel’s last commit was more than two years ago.

Comparing it to the ok_jose library:

• OkJose overloads |> to work differently for ok/error tuples.
• OkJose allows you to create other overloaded versions of |>.
• OkJose does not have support for values of the type :ok/:error nor for {:ok, multiple, things}`.
• OkJose’s last commit was more than two years ago, and the README mentions that it was made before with was available in Elixir.

So the Tl;Dr is that Solution has a slightly different approach to these libraries:

• It strives to support all possible ok/error values that are used in practice: Not only the two-element tuple versions, but also the single atoms :ok and :error, as well as the versions with more than two elements like {:ok, data, metadata}.
• It strives to be lightweight by using the existing case and with syntax, rather than adding variants of the pipe-operator and/or require an understanding of monads to be used successfully.
• It is focused on working with ok/error tuples. It does not deal with exceptions or other kind of failure indications.

I hope that answers your question!

Yes it does, thank you for the comprehensive answer. I think, it would be useful if you added your reply to library repo.

I only have an experience with a result library. Therefore I can’t speak to the rest libs of the list which you’ve mentioned.

Result only accepts exactly the format {:ok, value}/{:error, problem}
That’s right. You can catch situations where we have :ok/:error by pattern matching. For example:

def do_something(:ok) do
  Result.ok("result is ok")
end

def do_something(_) do
  Result.error("result is error")
end

And these functions you can use further in your pipes with combination Result.map, Result.and_then, etc.. For {:ok, data, metadata} is appropriate to put data, metadata into e.g. Map and then use Result functions again in pipes.

Result has a bunch of monad-inspired functions, but no overloaded case or with statements.
Because Result doesn’t need it. Check following examples how Result is used for these cases. For case: functions save and below write/close, for with: fold

Great idea

It seems to me like you are attempting to ‘defend’ the result library. I would like to clarify that my intention with the comparison was not to attack the other libraries, but only to point out what the differences between them are.

I think it is great that a diverse number of libraries that handle dealing with failure circumstances in different ways. I personally like the way Solution does it the best (for failure circumstances related to ok/error tuples) because I created it myself so it matches my needs perfectly (No pun intended ).
Other people might like other libraries more, and other situations might call for other libraries. And that’s great!

Any defend wasn’t and isn’t my purpose (and also I didn’t perceive that the comparison would have be attack) and I apology if it would sound this way. I just wanted to point out how to Result can be used.

Yes I agree with that.

Huh?

iex> {:error, :an_error, :meta} |> normalize()
%ErlangError{original: :an_error}

It handles them fine, there’s just no place to put the ‘meta’ field into the ErlangError struct (this is an :"Elixir.ErlangError" struct, not an exceptional thing).

Ok tuples with extra fields are passed through unchanged, as otherwise it wouldn’t know how to process the extra data or in what form you want it, these are by design.

However, if you do know how you want something like {:ok, :a_value, :meta} to be processed, say as a map, you can pass in a transformation function to the normalize call (great for handling lots of possibilities to normalize them all!).

So I’m not really sure what this is referencing for exceptional, it handles all of these variants both with a default style handling and a way to override as well?

Never seen towel, lol. ^.^

I tend to use exceptional, mostly because I have a lot of stuff built around it anymore and its pervasive through my work project. It would be interesting to see handling differences between Solution and Exceptional, if you can think of both basic and unique cases that Solution handles well? Would be a good comparison for people to read.

A quick conversion of the cases of Solution to Exceptional from the OP would be:

SCase

 scase {:ok, 10} do
  ok() -> "Yay!"
  _ -> "Failure"
  end
#=> "Yay!"

Exceptional branch (not my style):

iex> branch {:ok, 10},                
...>   value_do: fn _ -> "Yay!" end.(),
...>   exception_do: fn _ -> "Failure" end.()
"Yay!"

My wrapper('ish) around branch that I use at work (I have a lot of things wrapping exceptional, I could easily release it as a separate library now ^.^; ):

iex(6)> xbranch {:ok, 10} do
...(6)>   _ -> "Yay!"
...(6)> else
...(6)>   _ -> "Failure"
...(6)> end
"Yay!"

Exceptional if_exception style, exceptional pipes into things for these and it’s normal branch blocks, I prefer the above style of whatever_matcher -> ... personally, so I have a lot of wrappers around these for that, but this is exceptional’s normal one too, not really a fan of the names either…:

iex(7)> if_exception {:ok, 10} do
...(7)>   case do
...(7)>     _ -> "Failure"
...(7)>   end
...(7)> else
...(7)>   case do
...(7)>     _ -> "Yay!"
...(7)>   end
...(7)> end
"Yay!"

Exceptional as a tagged tuple:

iex(3)> case to_tagged_status({:ok, 10}) do
...(3)>   {:ok, _} -> "Yay!"
...(3)>   _ -> "Failure"
...(3)> end
"Yay!"

Solution’s:

 scase {:ok, "foo", 42} do
   ok(res, extra) ->
      "result: \#{res}, extra: \#{extra}"
   _ -> 
      "Failure"
    end
#=> "result: foo, extra: 42"

Exceptional in my project:

iex(6)> branch {:ok, "foo", 42} do
...(6)>   {:ok, res, extra} -> "result: #{res}, extra: #{extra}"
...(6)> else
...(6)>   _ -> "Failure"
...(6)> end
"result: foo, extra: 42"

Though with a normalize helper:

iex> h = fn
...>   {:ok, value, meta} -> {value, meta}
...>   otherwise -> otherwise
...> end
#Function<6.128620087/1 in :erl_eval.expr/5>
iex> {:ok, "foo", 42} |>
...> normalize(h) |>
...> branch do
...>   {res, extra} -> "result: #{res}, extra: #{extra}
...> else
...>   _ -> "Failure"
...> end
"result: foo, extra: 42"

SWith

 x = {:ok, 10}
 y = {:ok, 33, 44, %{a: "other stuff"}}
 swith ok(res)  <- x,
       ok(res2) <- y do
         "We have: \#{res} \#{res2}"
    else
      _ -> "Failure"
  end
#=> "We have: 10 33"

Eh, not exceptional, but one of my helpers:

iex> x = {:ok, 10}                          
{:ok, 10}
iex> y = {:ok, 33, 44, %{a: "other stuff"}}
{:ok, 33, 44, %{a: "other stuff"}}
iex> {x, y} |>
...> xnormalize() |> # This 'essentially' just recursively runs `normalize` and returns first failure if found
...> xbranch do # I could just write a transformer to pass to `xnormalize`
...>   {res, {:ok, res2, _, _} -> "We have: #{res} #{res2}
...> else
...>   _ -> "Failure"
...> end
"We have: 10 33"

Now I do like Solution a lot better, it’s more composable and such, though exceptional would work very well with it via to_tagged_tuple.

Optimally :ok/{:ok, data} and :error/{:error, data} would be used everywhere, there’s very little consistency in the ecosystem around this, Solution would work very well with all this!

Apologies; I did not attempt to execute the code but only read the implementation of Exceptional.Normalize.normalize/{1,2,3}, and mis-read line 80, thinking that it was still part of the case-statement body that starts at line 78.

So, after experimentation, I now know that:

• Exceptional does handle the case of ‘having a stack trace’ as third element of an {:error, problem, trace} tuple.
• Other kinds of ok and error tuples, like for instance {:error, problem, explanation, trace} and as you mentioned {:ok, value, meta} are not handled by the library (although you can indeed pass in a custom function to handle them).

Interestingly, for instance the new Mint HTTP client library frequently (a) uses more than two elements in its return values (because, amongst other things, it has to pass the altered conn object back to you) and (b) uses return types like {:error, conn, reason} and {:error, conn, reason, [responses]} in some places, which would not be handled by Exceptionals method of operation either. (For these two examples it would create an %ErlangError{original: conn})

Explicit pattern matching is a solution, but I would argue that you have more freedom if, for these ok/error tuples you match on the fields you need rather than also restricting the size of the tuple.

Please do! (and thanks for all your comparison examples by the way). It looks interesting, and I think that having more different flavours of error-handling libraries would help people.

Yes, facilitating this is exactly the goal of the library .

Does Solution have the equivalent of OK’s pipe operators (~> and ~>>)?

I’m looking for something that simply returns out of a pipeline as soon as a function in the pipeline returns {:error, …}

I don’t like nested case (ugly) and I’m not a fan of with (not as neat as pipe).