Added the Typed Contract Behaviour to guarantee data correcteness at runtime.

Signed-off-by: Exadra37 <exadra37@gmail.com>

Author: Exadra37

lib/docs/modules/behaviours/persona.ex

@@ -0,0 +1,21 @@
+defmodule Persona do
+  @moduledoc false
+
+  require PersonaValidator
+
+  @keys %{
+    required: [:name, :email],
+    optional: [role: nil]
+  }
+
+  use ElixirScribe.Behaviour.TypedContract, keys: @keys
+
+  @impl true
+  def type_spec() do
+    schema(%__MODULE__{
+      name: is_binary() |> spec(),
+      email: PersonaValidator.corporate_email?() |> spec(),
+      role: PersonaValidator.role?() |> spec()
+    })
+  end
+end

lib/docs/modules/behaviours/persona_validator.ex

@@ -0,0 +1,31 @@
+defmodule PersonaValidator do
+  @moduledoc false
+
+  # A very simplistic set o validations used by the docs usage examples.
+
+  @email_providers ["gmail.com", "yahoo.com", "hotmail.com"]
+  def corporate_email?(email) when is_binary(email) do
+    case String.split(email, "@", trim: true) do
+      [_one_part] ->
+        false
+
+      [_, email_provider] when email_provider not in @email_providers ->
+        true
+
+      _ ->
+        false
+    end
+  end
+
+  def corporate_email?(_email), do: false
+
+  # The role is optional, thus we return true
+  def role?(role) when is_nil(role), do: true
+
+  def role?(role) when is_binary(role) do
+    role = role |> String.trim()
+    String.length(role) >= 3
+  end
+
+  def role?(_age), do: false
+end

lib/elixir_scribe/behaviour_typed_contract.ex

@@ -0,0 +1,281 @@
+defmodule ElixirScribe.Behaviour.TypedContract do
+  @moduledoc """
+  The Elixir Scribe Typed Contract guarantees the shape of your data throughout your codebase.
+
+  Use it as a contract for your data shape to eliminate potential bugs that may be caused by creating the data with the wrong type. This leads to more robust code and fewer tests needed to guarantee data correctness, compared to when a struct or a plain map was previously used.
+
+
+  ## Typed Contract
+
+  Let's imagine that the Business requested a new feature, a Marketing funnel where they only want to allow personas who have a company email to enter the funnel, and they require them to provide a name, email and optionally their role in the company.
+
+  We can use a Typed Contract to translate these business rules into a contract that guarantees data correctness across all our code base.
+
+  For example:
+
+  ```
+  #{File.read!("lib/docs/modules/behaviours/persona.ex")}
+  ```
+  > ### Specs {: .info}
+  > - When defining the `type_spec/0` the schema can use the built-in specs from [Norm](https://hexdocs.pm/norm/Norm.html#module-validation-and-conforming-values) or your own ones.
+  > - All specs defined with `PersonaValidator.*` are custom ones.
+
+
+  > ### Required and Optional Keys {: .warning}
+  > - A typed contract needs to declare the required and optional keys, plus a type spec for them.
+  > - The optional keys **MUST** have a default value.
+
+  > ### Contract Guarantees {: .error}
+  > - To take advantage of the safety guarantees offered by the Elixir Scribe Typed Contract, you **MUST** not create or update it directly, as allowed by Elixir. Instead, you need to use the built-in functions `new/1`, `new!/1`, `update/3`, or `update!/3` that will guarantee it conforms with the type specs when one is created or updated.
+  > - Use the `conforms?/1` function at the place you use the typed contract to ensure that you still have a struct that conforms with the type spec, because it may have been manipulated directly between the point it was created and where you are using it.
+  > - For introspection, the `fields/0` and `type_spec/0` functions are provided.
+
+
+  ## Usage Examples
+
+  To run the usage examples:
+
+  ```
+  iex -S mix
+  ```
+
+  ### With Valid Data Types
+
+  To create a new Person:
+
+  ```
+  iex> Persona.new! %{name: "Paulo", email: "exadra37@company.com"}
+  %Persona{name: "Paulo", email: "exadra37@company.com", role: nil, self: Persona}
+  ```
+
+  To update the Person:
+
+  ```
+  iex> persona = Persona.new! %{name: "Paulo", email: "exadra37@company.com"}
+  %Persona{name: "Paulo", email: "exadra37@company.com", role: nil, self: Persona}
+  iex> persona.self.update! persona, :role, "Elixir Scribe Engineer"
+  %Persona{
+    name: "Paulo",
+    email: "exadra37@company.com",
+    role: "Elixir Scribe Engineer",
+    self: Persona
+  }
+  ```
+
+  Later, some layers deep in the code we can confirm that the Persona still conforms with the type spec defined in the contract:
+
+  ```
+  iex> persona = Persona.new! %{name: "Paulo", email: "exadra37@company.com"}
+  %Persona{name: "Paulo", email: "exadra37@company.com", role: nil, self: Persona}
+  iex> persona.self.conforms? persona
+  true
+  ```
+
+  Alternatively, you can use `new/1` and `update/3` which will return a `{:ok, result}` or `{:error, reason}` tuple.
+
+
+  ### With Invalid Data Types
+
+  Passing the role as an atom, instead of the expected string:
+
+  ```
+  iex> Persona.new %{name: "Paulo", email: "exadra37@company.com", role: :cto}
+  {:error, [%{input: :cto, path: [:role], spec: "PersonaValidator.role?()"}]}
+  ```
+
+  The same as above, but using `new!/1` which will raise:
+
+  ```
+  Persona.new! %{name: "Paulo", email: "exadra37@company.com", role: :cto}
+  ```
+
+  It will raise the following:
+
+  ```
+  ** (Norm.MismatchError) Could not conform input:
+  val: :cto in: :role fails: PersonaValidator.role?()
+      (norm 0.13.0) lib/norm.ex:65: Norm.conform!/2
+      iex:6: (file)
+  ```
+
+  Invoking `update/3` and `update!/3` will output similar results.
+
+  > ### Less Tests and Fewer Bugs {: .tip}
+  > - The Elixir Scribe typed contract acts as a contract for the businesse rules to guarantee data correctness at anypoint it's used in the code base.
+  > - Now the developer only needs to test that a Persona complies with this business rules in the test for this contract, because everywhere the Persona contract is used it's guaranteed that the data is in the expected shape.
+  > - This translates to fewer bugs, less technical debt creeping in and a more robust code base.
+
+  ### Introspection
+
+  To introspect the fields used to define the typed contract at compile time:
+
+  ```
+  iex> Persona.fields
+  %{
+    config: %{
+      extra: [self: Persona],
+      required: [:name, :email],
+      optional: [role: nil]
+    },
+    defstruct: [:name, :email, {:role, nil}, {:self, Persona}]
+  }
+  ```
+
+  To introspect the Norm type spec:
+
+  ```
+  iex> Persona.type_spec
+  ```
+
+  The output:
+
+  ```
+  #Norm.Schema<%Persona{
+    name: #Norm.Spec<is_binary()>,
+    email: #Norm.Spec<PersonaValidator.corporate_email?()>,
+    role: #Norm.Spec<PersonaValidator.role?()>,
+    self: Persona
+  }>
+  ```
+
+  The `:self` field is an extra added at compile time by the typed contract macro to allow you to self reference the typed contract like you already noticed in the above examples.
+  """
+
+  alias ElixirScribe.Behaviour.TypedContract
+
+  @doc """
+  Returns the type specification for the Elixir Scribe Typed Contract.
+
+  Used internally by all this behaviour callbacks, but may also be useful in the case more advanced usage of Norm is required outside this struct.
+  """
+  @callback type_spec() :: struct()
+
+  @doc """
+  Returns the fields definition used to define the struct for the Elixir Scribe Typed Contract at compile time.
+  """
+  @callback fields() :: map()
+
+  @doc """
+  Accepts a map with the attributes to create an Elixir Scribe Typed Contract.
+
+  Returns `{:ok, struct}` on successful creation, otherwise returns `{:error, reason}`.
+  """
+  @callback new(map()) :: {:ok, struct()} | {:error, list(map())}
+
+  @doc """
+  Accepts a map with the attributes to create an ELixir Scribe Typed Contract.
+
+  Returns the typed contract on successful creation, otherwise raises an error.
+  """
+  @callback new!(map()) :: struct()
+
+  @doc """
+  Updates the Elixir Scribe Typed Contract for the given key and value.
+
+  Returns `{:ok, struct}` on successful update, otherwise returns `{:error, reason}`.
+  """
+  @callback update(struct(), atom(), any()) :: {:ok, struct()} | {:error, list(map())}
+
+  @doc """
+  Updates the Elixir Scribe Typed Contract for the given key and value.
+
+  Returns the typed contract on successful update, otherwise raises an error.
+  """
+  @callback update!(struct(), atom(), any()) :: struct()
+
+  @doc """
+  Accepts the Elixir Scribe Typed Contract itself to check it still conforms with the specs.
+
+  Creating or modifying the struct directly can cause it to not be conformant anymore with the specs.
+
+  Useful to use by modules operating on the Typed Contract to ensure it wasn't directly modified after being created with `new/1` or `new!/1`.
+  """
+  @callback conforms?(struct()) :: boolean()
+
+  def __optional_fields__(%{optional: optional, extra: extra}, module) do
+    Keyword.keyword?(optional) ||
+      raise """
+      #{module}
+
+          All optional fields in the Typed Contract MUST have a default value:
+
+            * Incorrect: [:a, :b] or [:a, b: :default]
+
+            * Correct: [a: :default, b: :default]
+
+          Your fields:
+
+          #{inspect(optional)}
+      """
+
+    optional ++ extra
+  end
+
+  def __optional_fields__(%{extra: extra}, _module), do: extra
+
+  defmacro __using__(opts) do
+    moduledocs = @moduledoc
+
+    quote location: :keep, bind_quoted: [opts: opts, moduledocs: moduledocs] do
+      unless Module.get_attribute(__MODULE__, :moduledoc, false) do
+        @moduledoc """
+        Module visible without docs.
+
+        > #### INFO {: .info}
+        > This module doesn't have docs, but you can read instead the docs for the behaviour it implements: `ElixirScribe.Behaviour.TypedContract`
+        """
+      end
+
+      import Norm
+
+      @behaviour ElixirScribe.Behaviour.TypedContract
+
+      @struct_keys Keyword.get(opts, :keys, %{}) |> Map.put(:extra, self: __MODULE__)
+
+      @enforce_keys @struct_keys.required
+
+      @optional_keys TypedContract.__optional_fields__(@struct_keys, __MODULE__)
+
+      @all_keys @enforce_keys ++ @optional_keys
+
+      @fields %{defstruct: @all_keys, config: @struct_keys}
+
+      defstruct @all_keys
+
+      @impl true
+      def fields(), do: @fields
+
+      @impl true
+      def new(attrs) when is_map(attrs) do
+        struct(__MODULE__, attrs)
+        |> conform(type_spec())
+      end
+
+      @impl true
+      def new!(attrs) when is_map(attrs) do
+        struct(__MODULE__, attrs)
+        |> conform!(type_spec())
+      end
+
+      @impl true
+      def update(%__MODULE__{} = typed_contract, key, value) do
+        typed_contract
+        |> Map.put(key, value)
+        |> conform(type_spec())
+      end
+
+      @impl true
+      def update!(%__MODULE__{} = typed_contract, key, value) do
+        typed_contract
+        |> Map.put(key, value)
+        |> conform!(type_spec())
+      end
+
+      @impl true
+      def conforms?(%__MODULE__{} = typed_contract), do: typed_contract |> valid?(type_spec())
+      def conforms?(_), do: false
+
+      defoverridable new: 1, new!: 1, update: 3, update!: 3, conforms?: 1
+    end
+  end
+end

mix.exs

@@ -59,7 +59,8 @@ defmodule ElixirScribe.MixProject do
     [
       # {:dep_from_hexpm, "~> 0.3.0"},
       # {:dep_from_git, git: "https://github.com/elixir-lang/my_dep.git", tag: "0.1.0"}
-      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false}
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false},
+      {:norm, "~> 0.13"}
     ]
   end
 end

mix.lock

@@ -5,4 +5,5 @@
   "makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"},
   "makeup_erlang": {:hex, :makeup_erlang, "1.0.0", "6f0eff9c9c489f26b69b61440bf1b238d95badae49adac77973cbacae87e3c2e", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "ea7a9307de9d1548d2a72d299058d1fd2339e3d398560a0e46c27dab4891e4d2"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
+  "norm": {:hex, :norm, "0.13.0", "2c562113f3205e3f195ee288d3bd1ab903743e7e9f3282562c56c61c4d95dec4", [:mix], [{:stream_data, "~> 0.5", [hex: :stream_data, repo: "hexpm", optional: true]}], "hexpm", "447cc96dd2d0e19dcb37c84b5fc0d6842aad69386e846af048046f95561d46d7"},
 }

test/elixir_scribe/behaviour_typed_contract_test.exs

@@ -0,0 +1,4 @@
+defmodule ElixirScribe.Behaviour.TypedContractTest do
+  use ExUnit.Case, async: true
+  doctest ElixirScribe.Behaviour.TypedContract
+end