{"id":16155429,"url":"https://github.com/keathley/oath","last_synced_at":"2026-03-16T22:03:29.702Z","repository":{"id":53055801,"uuid":"175004361","full_name":"keathley/oath","owner":"keathley","description":"Design by contract in elixir","archived":false,"fork":false,"pushed_at":"2021-04-25T19:42:33.000Z","size":38,"stargazers_count":46,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-10T14:43:33.458Z","etag":null,"topics":["design-by-contract","elixir"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keathley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-11T13:19:22.000Z","updated_at":"2024-11-07T22:19:56.000Z","dependencies_parsed_at":"2022-08-24T00:10:17.620Z","dependency_job_id":null,"html_url":"https://github.com/keathley/oath","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keathley%2Foath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keathley%2Foath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keathley%2Foath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keathley%2Foath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keathley","download_url":"https://codeload.github.com/keathley/oath/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243809888,"owners_count":20351407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design-by-contract","elixir"],"created_at":"2024-10-10T01:20:48.441Z","updated_at":"2026-03-16T22:03:29.645Z","avatar_url":"https://github.com/keathley.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Oath\n\n## Names\n\nThis project was originally called \"Vow\", but it looks like someone snagged that on hex. So, I had to change it to Oath.\n\n## Description\n\nOath provides a system for design by contract in elixir. It uses the excellent,\n`:decorator` library by @arjan.\n\n## Usage\n\nYou will first need to enable contracts in whichever envs you want to use them.\nTypically this will be development and test only.\n\n```elixir\n# config/dev.exs\nconfig :oath,\n  enable_contracts: true\n```\n\nIf you want to ensure contracts are compiled for any dependencies you may need\nto force a recompilation of your dependencies like so:\n\n```\nmix deps.compile --all --force\nMIX_ENV=test mix deps.compile --all --force\n```\n\nAfter enabling contracts, you can add `pre` and `post` conditions to your functions.\nPreconditions are always run before your function body. Postconditions are run after\nyour function body executes and will be provided the result from your function\ncall. You can have any number of pre and post conditions for each function clause.\n\nWe'll use an example function with a broken implementation as a demonstration:\n\n```elixir\ndefmodule Mod do\n  use Oath\n\n  @decorate pre(\"a is an integer\", fn(a, _) -\u003e is_integer(a) end)\n  @decorate pre(\"b is an integer\", fn(_, b) -\u003e is_integer(b) end)\n  @decorate post(\"the result must be greater than a or b\", fn(a, b, result) -\u003e\n    result \u003e= a \u0026\u0026 result \u003e= b\n  end)\n  def add(a, b) do\n    if a == 7 do\n      (a * -1) + b\n    else\n      a + b\n    end\n  end\nend\n```\n\nCalling this function with contracts enabled will cause an exception to be raised.\n\n```elixir\nMod.add(7, 2)\n ** (Oath.ContractError) Mod.add/2 postcondition: 'the result must be greater than a or b' failed with input:\n  Arguments:\n\n  a\n  =\u003e 7\n\n  b\n  =\u003e 2\n\n  result\n  =\u003e -5\n```\n\nContract predicates don't have to be pure. Its often useful to use contracts\nas a way of validating the functions environment and any of the functions side-effects.\n\n```elixir\n@doc \"\"\"\nStores a name in the database.\n\"\"\"\n@decorate pre(\"name must be a string\", \u0026 is_binary(\u00261))\n@decorate pre(\"name must not be in db\", fn name -\u003e !in_database?(name) end)\n@decorate post(\"Name must be normalized in the db\", fn name, _result -\u003e\n  fetch_from_db(name) == String.capitalize(name)\nend)\ndef store_in_db(name) do\n  #...\nend\n```\n\n## When to enable contracts?\n\nClassically, you should only enable contracts in dev and test modes. You want\nto avoid enabling contracts in production as this will lower your production\nperformance due to additional checking. It also means that you won't be able\nto write side-effecting contracts, which you'll want to be able to do in testing\nmodes.\n\nBy default, contracts are disabled and will be compiled away so you won't need\nto do anything for production builds.\n\n## Installation\n\n```elixir\ndef deps do\n  [\n    {:oath, \"~\u003e 0.1\"},\n  ]\nend\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeathley%2Foath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeathley%2Foath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeathley%2Foath/lists"}