feat: improved error UX

[pgautier404]

Update error handing to conform to client SDK spec. Uses isXXX() methods such as asHit, asError, etc. to provide type-safe instances and informative IDE code completion.

[cprice404]

looks great, just one minor question to consider. it's something we can punt until later though if we don't come to an immediate consensus.

[cprice404]

question: did you consider the tradeoffs between null vs throwing an exception here?

On the one hand, if someone calls this incorrectly, if we throw an exception then we can give a nice clear message about what went wrong, vs. the null pointer exception that they are likely to get otherwise.

On the other hand, doing it this way probably allows people to write code like this if they want to:

if ($foo = client.Get('blah', 'blah')) {
  // handle happy path
} else {
  // handle sad path
}

without any try/catch shenanigans.

I don't want to hold up your progress so we should definitely timebox any consideration on this and just keep moving, but floating it because I expect that python/JS/PHP are going to end up looking pretty similar for this stuff since they don't have algebraic data types.

[cprice404]

@malandis I'm curious if you have any strong opinions on this.

[pgautier404]

My thinking was that we have made a contract with the user that our cache client will always return and not throw exceptions. I would be upset as a user if I had to jump through a relatively exotic syntax and wrap the whole thing in a try/catch. As you pointed out, this also allows a pseudo-pattern matching scheme using assignments in if statements. The null pointer exception should be pretty easy to diagnose since the return type signature of these methods is explicitly "response class or null". We'll obviously want to demonstrate the patterns we end up deeming best practices in the docs.

[cprice404]

That seems pretty compelling. Thanks for laying it out. 🚢