Bond (Design by Contract for Elixir) - 1.0.0 released

This looks really great Thank you for creating it.

Question: how could the predicates be abstracted? Meaning, If I have a predicate that applies to a certain function argument that is accepted across 3 different functions in a module, I’d like to declare the predicate only once for the argument and reuse it.

Hi @Petr, thank you for the kind words!

The idiomatic way to do this is to define the predicate once as an ordinary function in your module and then call it from the @pre (or @post) of each function that needs it. Contract expressions are just plain Elixir, so any function in scope — including your own — can be called inside them:

defmodule Mailer do
  use Bond

  @pre valid_recipient: valid_email?(to)
  def send_welcome(to, name) do
    # ...
  end

  @pre valid_recipient: valid_email?(to),
       nonempty_subject: subject != ""
  def send_notification(to, subject, body) do
    # ...
  end

  @pre valid_recipient: valid_email?(to)
  def unsubscribe(to) do
    # ...
  end

  # The reusable predicate — declared once, called from any contract.
  def valid_email?(address) do
    is_binary(address) and String.contains?(address, "@")
  end
end

The validation logic lives in one place; each function just references it. The label (valid_recipient:) is what shows up in the error message and generated docs, so you can keep it consistent or vary it per call site, or even omit it entirely. The predicate can be a private defp if you’d rather not export it — it still resolves inside contracts since the generated checks run in the same module.

If the argument in question happens to be a struct defined in that same module, there’s an even more automatic option: @invariant. Invariants encode predicates on the struct itself and are checked on entry to and exit from every public function in the module that takes or returns the struct — so you don’t repeat them per-function at all. The trade-off is that they apply module-wide (to every public function touching the struct), not to a hand-picked subset, and they’re struct-only. For the general “reuse across a few specific functions” case, the predicate-function pattern above is the way to go.

There’s a worked @invariant example — BoundedStack, with non_negative_capacity and size_within_capacity invariants — in the @invariant section of the docs if you’d like to see it in action.

Ah right, thanks, this is obvious when I see it now I’ve missed it and I was attempting to do it on a different level.

Let’ me describe how I was thinking about it, it might still be useful to explore. I wanted to abstract in a such a way that:

• the label is abstracted as well, def valied_email?(address), do: [valid_recepient: is_binary(address) and String.contains?(address, "@")] (just to demonstrate, this does not work, the body of the predicate function is evaluated not processed by bond macros)
  • It would also allow to abstract over a group of labeled predicates.
• the predicate documentation and error messages will not print the call to valied_email? but rather it’s source code.
  • Justification: in the documentation and error I would like to see the full explicit contract, unless I decide to name the predicate. The given valid_email is actually a great example where giving it a name is better than printing out the full real email format validation.

Something in the direction of

  @email_predicate quote do: is_binary(var!(email)) and String.contains?(var!(email), "@")
  @pre unquote(@email_predicate)
  def send_email(email), do: email

or better with a macro to avoid var!

defmodule Predicates do
  defmacro email_predicate(email) do
    quote do: is_binary(unquote(email)) and String.contains?(unquote(email), "@")
  end
end

#...

  require Predicates
  @pre Predicates.email_predicate(email)
  def send_email2(email), do: email

but the assertion in error message

iex(8)> CronicleBackup.Image.send_email "asd"
** (Bond.PreconditionError) precondition failed for call to CronicleBackup.Image.send_email/1
|   at: /Users/petr/Development/personal/my_tooling/lib/cronicle_backup/image.ex:6
|   label: nil
|   assertion: unquote(@email_predicate)
|   binding: [email: "asd"]

    (my_tooling 0.1.0) lib/cronicle_backup/image.ex:1: CronicleBackup.Image.send_email/1
    iex:8: (file)

does not print it anyway. I’ve assumed it takes the AST and prints it, but I guess it takes the source as String?

Ah, now I see what you were reaching for: abstracting the label along with the assertion, and choosing whether the error/docs show a name or the full expanded contract. Good news: Bond can do both. Let me first answer your AST-vs-string question, since it explains everything else.

When you write @pre <expr>, Bond captures the surface AST of <expr> and renders it for errors and docs with Macro.to_string/1 — and it does not macro-expand it first. So @pre unquote(@email_predicate) prints literally as unquote(@email_predicate) because that is the surface AST (unquote outside a quote is just an inert node at that layer). That’s why your attribute approach didn’t expand the way you hoped.

The way to get the expansion to happen is to let a macro produce the assertion, because the expression Bond captures is then whatever the macro expands to. There are two flavours, and they map exactly onto your two goals:

1. Name it (hide a gnarly predicate behind a label)

Put a macro (or plain function) call directly in @pre:

@pre Predicates.email_ok(email)
def send(email), do: email

This enforces correctly — the macro expands at the point Bond splices the check into the generated function — but the error shows the call, not its body:

label: nil
assertion: Predicates.email_ok(email)

Perfect for your real-email-validation case, where the name reads better than the regex.

2. Inline the full contract and abstract the label

Write a macro that emits the whole labelled @pre:

defmodule Contracts do
  use Bond  # <-- important, see the caveat below

  defmacro require_email(name) do
    var = Macro.var(name, nil)

    quote do
      @pre valid_recipient:
             is_binary(unquote(var)) and String.contains?(unquote(var), "@")
    end
  end
end

defmodule Mailer do
  use Bond
  require Contracts

  Contracts.require_email(:email)   # one line per function
  def send(email), do: email
end

Now the label is abstracted and the error/docs show the fully expanded expression:

label: :valid_recipient
assertion: is_binary(email) and String.contains?(email, "@")
binding: [email: "nope"]

You can emit several @pre/@post lines from one macro too, which covers your “abstract over a group of labelled predicates” idea.

The one caveat

The predicate-defining module must itself use Bond. This is macro hygiene: the @ inside Contracts’s quote resolves in Contracts’s context, so if that module doesn’t use Bond, its @pre is Kernel.@ — an attribute assignment that eagerly evaluates the right-hand side, which is the undefined variable "email" error your experiments would have hit. With use Bond in that module, @pre is Bond’s override and everything resolves. (And you don’t need var! — Macro.var(name, nil) unifies fine with the parameter.)

Thanks for pushing on this. It’s a genuinely nice idiom, and you’ve convinced me it deserves a spot in the docs. I’ll add a FAQ entry.

this is brilliant, great job!

I have one question, I see that you setup a way to toggle the functionality in prod. Do you think the checks should be turned off in prod? What use case do you have in mind?

Thank you, @nicflower, I appreciate the kind words.

Bertrand Meyer has written a lot about whether contracts should be enabled in production environments, especially in his book Object-Oriented Software Construction. Meyer’s recommendation is to leave contracts enabled; only disable them when you’ve measured a performance impact you can’t accept. The Bond docs include an Overhead guide that gives some indication of how much overhead contract evaluation adds at runtime.

Bond offers pretty flexible configuration options so you can tune precisely to your environment. The :purge option completely eliminates contracts at compile-time so there is zero runtime overhead. You can also use the :overrides configuration option to tune specific modules, such as hotspots where performance is critical.

The main use case for disabling or purging contracts is performance-sensitive code: high-throughput data pipelines, financial systems where individual function calls are on the critical path, or any hot loop where you’ve profiled and confirmed that contract evaluation is a meaningful contributor to latency. In those cases, :overrides lets you surgically purge just the affected modules while leaving contracts active everywhere else.

Note that it is important to write your code and your contracts such that there is no behavior change whether contracts are enabled, disabled, or purged. For example, don’t use preconditions for user input validation — if preconditions are disabled, then the user input validation would never occur and bad user input could potentially corrupt your system.

That said, my default is to leave all contracts enabled in production and only disable or purge when performance demands it.