🔗 When the shape is the contract: tuples, tagged tuples, and keywords

Before we talk about data structures, it helps to name a problem you’ve likely encountered in other languages. You call a function that tries to find a user in a database. If the user exists, you get a User object. If they don’t, you get null or nil.

This feels fine until you need to know why something failed. Did the user not exist, or did the database connection time out? Suddenly you’re returning magic strings, throwing exceptions, or checking boolean flags. The code becomes a minefield of if statements checking for special cases.

In Elixir, we solve this by treating data structures as contracts. We don’t just return a value. We return a structure that explicitly declares what happened.