Error conventions

[GeoffreyPS]

Many functions in the library as they exist now can raise exception with bad information. However, this isn't obvious from the function names and this behavior also conflicts with a broader convention in the Elixir/Erlang world.

The typical convention is to have public/exported functions return {:ok, value} or {:error, reason} tuples instead of raising errors, and only raise errors with function names that have a bang (!) appended to the name. This lets the library user then choose when errors should be raised, and what cases are actually exceptional.

I am happy to update the library's current functions (and tests) to have these responses.

I wanted to bring this up because it can change how these functions should be composed together (a breaking change for others who might be using this library). The with macro was added in Elixir v1.2 to help with this issue. I only bring this up because I understand that we may leave this {:ok, response} convention down the road to favor more composable/chainable functions. I would want to wait until we are hitting use cases where it makes sense to start returning streams, and of course leave that up to discussion.

Let me know if you have other thoughts on this, but I have a free morning and would be pretty content to spend it on this issue.

[GeoffreyPS]

Working through some of this on the library, I think that this convention should be employed only at times where we would throw an error -- not necessarily for basic functions where employing guard clauses could suffice.

This might be entirely over-wrought, now that I'm thinking about it. Should match errors simply be enough or do we feel like we should give (ideally helpful) error messages and incur the extra cost to maintain that?

[GeoffreyPS]

Alright. after moving cross country and getting majorly distracted, I think I've completed the task of revising the codebase to return {:ok, result} or {:error, reason}, and including bang(!) versions of functions for direct returns.

I will file a PR shortly, but I'm sure there will be some extra things we might want to do, including bumping the version number (not sure if you want to do that or have me do it), and possibly other things.