# Bond [![CI](https://github.com/jvoegele/bond/actions/workflows/ci.yml/badge.svg)](https://github.com/jvoegele/bond/actions/workflows/ci.yml) Design by Contract for Elixir. A contract is a plain Elixir expression attached to a function and checked at runtime. Here is one that says money is neither created nor destroyed: ```elixir defmodule Account do defstruct [:owner, :balance] end defmodule Ledger do use Bond @pre sufficient_funds: amount <= from.balance @post conserved: result.from.balance + result.to.balance == from.balance + to.balance def transfer(%Account{} = from, %Account{} = to, amount) do %{ from: %{from | balance: from.balance - amount}, to: %{to | balance: to.balance + amount} } end end ``` `@pre` declares a **precondition** — what the caller must satisfy for the call to be valid. `@post` declares a **postcondition** — what the function promises in return, provided the precondition held. A postcondition can mention `result`, the function's return value, which a `when` guard cannot do at all. (Guards keep the jobs only they can do — dispatch, and standing in for types — see [Should I remove guards when I add contracts?](guides/faq.md#should-i-remove-guards-and-pattern-matches-when-i-add-contracts).) Note what `conserved` is *not*: a restatement of the body. The body moves money; the contract states the law the movement must obey. So when someone later adds a transfer fee and takes it out of the sender only, the arithmetic still looks plausible — and the contract fails: ``` # Ledger.transfer(ana, bo, 200) # after a 1% fee is deducted from the sender ** (Bond.PostconditionError) postcondition failed in Ledger.transfer/3 | at: lib/ledger.ex:9 | label: :conserved | assertion: result.from.balance + result.to.balance == from.balance + to.balance | binding: [ amount: 200, from: %Account{owner: "ana", balance: 1000}, result: %{ to: %Account{owner: "bo", balance: 250}, from: %Account{owner: "ana", balance: 798} }, to: %Account{owner: "bo", balance: 50} ] ``` The failure names the property that broke, and hands you both states to compare. ## Beyond preconditions and postconditions `@pre` and `@post` constrain one call at a time. The rest of Bond is about getting more out of the same statements — enforcing them across a whole module, across every implementation of a behaviour, and against inputs you never wrote down. **Checked at every entrance and exit of a module.** An `@invariant` is a property of the struct rather than of any one call, so Bond checks it around every public function — including the ones a colleague adds next year: ```elixir defmodule Cart do use Bond defstruct items: [], total_cents: 0 @invariant total_matches_items: subject.total_cents == Enum.sum(Enum.map(subject.items, & &1.cents)) @post added_one: length(result.items) == length(cart.items) + 1 def add_item(%Cart{} = cart, item) do %{cart | items: [item | cart.items]} end end ``` `add_item/2` forgot to update `total_cents`. Nothing in the function is wrong on its own terms, and no guard, typespec, or pattern would object — but the invariant is checked on the way out: ``` # Cart.add_item(%Cart{}, %{sku: "A", cents: 500}) ** (Bond.InvariantError) invariant violated around Cart.add_item/2 | at: lib/cart.ex:6 | label: :total_matches_items | assertion: subject.total_cents == Enum.sum(Enum.map(subject.items, & &1.cents)) | binding: [subject: %Cart{items: [%{cents: 500, sku: "A"}], total_cents: 0}] ``` **Checked in every implementation of a behaviour.** Declare the contract once, on the callback, and every implementing module enforces it — without a line of contract code in any of them: ```elixir defmodule Paginator do use Bond.Behaviour @post never_over_limit: length(result) <= limit @callback fetch(page :: pos_integer(), limit :: pos_integer()) :: list() end defmodule LegacyPages do use Bond, behaviours: [Paginator] @impl true def fetch(page, _limit), do: Enum.map(1..50, &{page, &1}) # ignores limit end ``` ``` ** (Bond.PostconditionError) postcondition (inherited from Paginator) failed in LegacyPages.fetch/2 | at: lib/paginator.ex:4 | label: :never_over_limit ``` The violation is attributed to the behaviour that declared it, and points at the line in *that* file. A promise made by an interface, kept by everything that implements it. **Checked against inputs you never thought of.** The contracts you have already written are a specification, so they can serve as the oracle for property-based testing. You supply generators; Bond supplies the expected behaviour: ```elixir defmodule Roots do use Bond @pre non_negative: x >= 0.0 @post never_negative: result >= 0.0 @post shrinks_above_one: (x > 1.0) ~> (result < x) def sqrt(x), do: :math.sqrt(x) end ``` ```elixir # in test/roots_test.exs use Bond.PropertyTest contract_holds &Roots.sqrt/1, args: [StreamData.float(min: 0.0)] ``` That runs `sqrt/1` against a stream of generated floats and fails if any precondition, postcondition, or `check` is violated, with StreamData shrinking to a minimal counterexample. Those two postconditions are the whole oracle — there is no separate model of "expected output" to write or keep in step, because the contract already said it. (`~>` is implication: `shrinks_above_one` asserts nothing unless `x > 1.0`.) See [Testing Contracts](guides/testing-contracts.md) for `probe_contract/2`, which reads the boundaries out of your `@pre` and aims generators at them, and `invariants_hold/2`, which throws random *sequences* of operations at a struct. ## You choose what they cost Contracts are checked at runtime, so they are not free — the [Overhead](guides/overhead.md) guide publishes measured per-call figures. What makes that affordable is that the decision is yours, per environment and per contract kind: ```elixir # config/prod.exs config :bond, preconditions: :purge, postconditions: :purge, invariants: :purge ``` Purged contracts are not compiled in at all — there is no check to skip, and the function runs exactly as if the contract had never been written. Your published documentation still shows it, because `mix docs` runs in `:dev` where contracts are enabled: the contract stays part of the module's stated interface even in builds that do not check it. Between "on" and "purged" there is a third setting that compiles the check in but leaves it switched off, so a release can run with contracts inert and have them enabled from a remote console while a problem is being diagnosed. See [Configuring Contracts](guides/configuration.md). Contracts are normally on in dev and test. What you keep in production is a separate decision — often nothing, often just the preconditions, which are the cheapest kind and the only one that tells you a *caller* is at fault. Either way, that is why it is worth writing the expensive, interesting ones. ## Installation Add `bond` to your dependencies in `mix.exs`: ```elixir def deps do [ {:bond, "~> 1.14"} ] end ``` Then run `mix deps.get`. Bond's only dependency is `:telemetry`; `:stream_data` is optional and needed solely for the property-testing macros. Bond starts no processes and adds nothing to your supervision tree — `use Bond` is compile-time machinery, and the runtime side is plain function calls. ## Where to go from here Bond does more than the examples above. The rest of the documentation is organised around the questions that tend to arrive in this order: * **Still evaluating?** The examples above are the argument. The [FAQ](guides/faq.md) answers the comparisons that usually decide it — ["What does Bond do that typespecs don't?"](guides/faq.md#what-does-bond-do-that-typespecs-don-t) and ["Should I remove guards when I add contracts?"](guides/faq.md#should-i-remove-guards-and-pattern-matches-when-i-add-contracts). * **[Getting Started](guides/getting-started.md)** — a walkthrough that builds one example at a time. The place to go next. * **[Writing Contracts](guides/writing-contracts.md)** — the full reference for `@pre`, `@post`, `check/1`, `old/1`, the assertion language, and how contracts appear in your generated docs. * **[Writing sound assertions](guides/writing-sound-assertions.md)** — the mistakes that make a contract silently vacuous, and how to avoid them. * **[Invariants](guides/invariants.md)** — properties of a struct, checked at every boundary of its module. * **[Reusable contracts](guides/reusable-contracts.md)** — naming a contract once and applying it in several places. * **[Contract inheritance](guides/contract-inheritance.md)** — contracts declared on a `Bond.Behaviour` callback or a `Bond.Protocol` function, enforced in every implementation. * **[Contracts in a concurrent world](guides/contracts-and-concurrency.md)** — process state, `Bond.Server`, and what contracts can and cannot promise across processes. * **[Testing contracts](guides/testing-contracts.md)** — asserting violations, and using contracts as property-test oracles. * **[Configuring Contracts](guides/configuration.md)** — turning kinds on and off per environment and per module, and removing them entirely. * **[Overhead](guides/overhead.md)** — what contracts cost, measured per call. * **[Telemetry](guides/telemetry.md)** — the assertion-failure event. * **[Stability](guides/stability.md)** and **[Public API surface](guides/public-api.md)** — what semver covers. * **[About](guides/about.md)** and **[History](guides/history.md)** — Design by Contract as Bertrand Meyer introduced it with Eiffel, what Bond keeps and drops from it, and the Elixir libraries that came before. ## Documentation Documentation is generated with [ExDoc](https://github.com/elixir-lang/ex_doc) and published on HexDocs at .