Add bang functions

Author: Igor Barchenkov

CHANGELOG.md

@@ -0,0 +1,10 @@
+## v0.2.0 (2021-04-24)
+
+### Enhancements
+
+  * Add `build!/2`
+  * Add `build_list!/3`
+  * Add `insert!/3`
+  * Add `insert_list!/4`
+
+All the new functions raise `EctoStreamFactory.MissingKeyError` error if a generated struct, map or keyword list cannot be fully merged with the provided attributes.

README.md

@@ -126,9 +126,12 @@ iex> build(:post, text: "Hello world")
 iex> build_list(2, :user, name: fn n -> "user#{n}" end)
 [%User{id: nil, name: "user1", age: 51, email: "n5@gmail.com"}, %User{id: nil, name: "user2", age: 40, email: "O6@yandex.com"}]
 
-iex> insert(:user)
+iex> insert!(:user)
 %User{id: 1, name: "b", age: 23, email: "az7@gmail.com"}
 
+iex> insert!(:user, gender: "female")
+** (EctoStreamFactory.MissingKeyError) MyApp.Factory.user_generator does not generate :gender field.
+
 iex> insert(:user, [email: "az7@gmail.com"], on_conflict: :nothing)
 %User{id: nil, name: "c", age: 44, email: "az7@gmail.com"}
 

lib/ecto_stream_factory/ecto_stream_factory.ex

@@ -32,27 +32,48 @@ defmodule EctoStreamFactory do
 
       @repo Factory.get_repo(__MODULE__, opts)
 
-      def build(generator_name, attrs \\ [])
-          when is_atom(generator_name) or is_binary(generator_name) do
+      defguardp is_valid_generator_name(value) when is_atom(value) or is_binary(value)
+      defguardp is_valid_amount(value) when is_integer(value) and value > 0
+
+      def build(generator_name, attrs \\ []) when is_valid_generator_name(generator_name) do
         Factory.build(__MODULE__, generator_name, attrs)
       end
 
+      def build!(generator_name, attrs \\ []) when is_valid_generator_name(generator_name) do
+        Factory.build!(__MODULE__, generator_name, attrs)
+      end
+
       def build_list(amount, generator_name, attrs \\ [])
-          when (is_atom(generator_name) or is_binary(generator_name)) and
-                 (is_integer(amount) and amount > 0) do
+          when is_valid_generator_name(generator_name) and
+                 is_valid_amount(amount) do
         Factory.build_list(__MODULE__, amount, generator_name, attrs)
       end
 
+      def build_list!(amount, generator_name, attrs \\ [])
+          when is_valid_generator_name(generator_name) and
+                 is_valid_amount(amount) do
+        Factory.build_list!(__MODULE__, amount, generator_name, attrs)
+      end
+
       def insert(generator_name, attrs \\ [], opts \\ [])
-          when is_atom(generator_name) or is_binary(generator_name) do
+          when is_valid_generator_name(generator_name) do
         Factory.insert(__MODULE__, @repo, generator_name, attrs, opts)
       end
 
+      def insert!(generator_name, attrs \\ [], opts \\ [])
+          when is_valid_generator_name(generator_name) do
+        Factory.insert!(__MODULE__, @repo, generator_name, attrs, opts)
+      end
+
       def insert_list(amount, generator_name, attrs \\ [], opts \\ [])
-          when (is_atom(generator_name) or is_binary(generator_name)) and
-                 (is_integer(amount) and amount > 0) do
+          when is_valid_generator_name(generator_name) and is_valid_amount(amount) do
         Factory.insert_list(__MODULE__, @repo, amount, generator_name, attrs, opts)
       end
+
+      def insert_list!(amount, generator_name, attrs \\ [], opts \\ [])
+          when is_valid_generator_name(generator_name) and is_valid_amount(amount) do
+        Factory.insert_list!(__MODULE__, @repo, amount, generator_name, attrs, opts)
+      end
     end
   end
 
@@ -73,9 +94,9 @@ defmodule EctoStreamFactory do
   @type insert_opts() :: Keyword.t()
 
   @doc """
-  Takes a signle instance from a StreamData [gen/1](`ExUnitProperties.gen/1`) generator.
+  Takes a single instance from a StreamData [gen/1](`ExUnitProperties.gen/1`) generator.
 
-  If the generator returs a struct, map or keyword list, it also merges the result with the provided overwrites.
+  If the generator returs a struct, map or keyword list, it also merges the result with `overwrites`.
 
   ## Examples
 
@@ -87,6 +108,19 @@ defmodule EctoStreamFactory do
   """
   @callback build(generator_name(), overwrites()) :: term()
 
+  @doc """
+  Same as `c:build/2`, but raises an error if some key in `overwrites` does not exist in the generated struct, map or keyword list.
+
+  ## Examples
+
+      iex> Factory.build!(:user)
+      %User{id: nil, name: "b", age: 28}
+
+      iex> Factory.build!(:user, name: "foo", weight: 101)
+      ** (EctoStreamFactory.MissingKeyError) MyApp.Factory.user_generator does not generate :weight field.
+  """
+  @callback build!(generator_name(), overwrites()) :: term()
+
   @doc ~S"""
   Same as `c:build/2`, but instantiates a list of structs.
 
@@ -97,6 +131,11 @@ defmodule EctoStreamFactory do
   """
   @callback build_list(amount(), generator_name(), overwrites) :: nonempty_list(term())
 
+  @doc ~S"""
+  Same as `c:build_list/3`, but raises an error if some key in `overwites` does not exist in the generated entities.
+  """
+  @callback build_list!(amount(), generator_name(), overwrites) :: nonempty_list(term())
+
   @doc """
   Similar to `c:build/2`, but expects a generator to return an Ecto.Schema struct to insert it into the database.
 
@@ -107,6 +146,11 @@ defmodule EctoStreamFactory do
   """
   @callback insert(generator_name(), overwrites(), insert_opts()) :: Schema.t()
 
+  @doc """
+  Same as `c:insert/3`, but raises an error if some key in `overwites` does not exist in the generated struct.
+  """
+  @callback insert!(generator_name(), overwrites(), insert_opts()) :: Schema.t()
+
   @doc """
   Same as `c:insert/3`, but inserts a list of structs.
 
@@ -117,4 +161,10 @@ defmodule EctoStreamFactory do
   """
   @callback insert_list(amount(), generator_name(), overwrites(), insert_opts()) ::
               nonempty_list(Schema.t())
+
+  @doc ~S"""
+  Same as `c:insert_list/4`, but raises an error if some key in `overwites` does not exist in the generated structs.
+  """
+  @callback insert_list!(amount(), generator_name(), overwrites(), insert_opts()) ::
+              nonempty_list(Schema.t())
 end

lib/ecto_stream_factory/exceptions.ex

@@ -1,6 +1,4 @@
 defmodule EctoStreamFactory.UndefinedGeneratorError do
-  @moduledoc false
-
   defexception [:module, :generator_name]
 
   @impl true
@@ -9,7 +7,7 @@ defmodule EctoStreamFactory.UndefinedGeneratorError do
     No generator defined for #{inspect(gen_name)}.
     Please check for typos or define your generator:
 
-        defmodule #{module} do
+        defmodule #{inspect(module)} do
           def #{EctoStreamFactory.Factory.function_from_generator_name(gen_name)} do
             ...
           end
@@ -19,8 +17,6 @@ defmodule EctoStreamFactory.UndefinedGeneratorError do
 end
 
 defmodule EctoStreamFactory.RepoNotSpecifiedError do
-  @moduledoc false
-
   defexception [:module]
 
   @impl true
@@ -30,10 +26,21 @@ defmodule EctoStreamFactory.RepoNotSpecifiedError do
     """
     :repo option is missing. Please configure the factory:
 
-        defmodule #{module} do
+        defmodule #{inspect(module)} do
           use EctoStreamFactory, repo: #{repo_module}.Repo
           ...
         end
     """
   end
 end
+
+defmodule EctoStreamFactory.MissingKeyError do
+  defexception [:module, :generator_name, :key]
+
+  @impl true
+  def message(%{module: module, generator_name: gen_name, key: key}) do
+    """
+    #{inspect(module)}.#{EctoStreamFactory.Factory.function_from_generator_name(gen_name)} does not generate #{inspect(key)} field.
+    """
+  end
+end

lib/ecto_stream_factory/factory.ex

@@ -2,54 +2,140 @@ defmodule EctoStreamFactory.Factory do
   @moduledoc false
 
   def build(module, generator_name, attrs) do
+    do_build(module, generator_name, attrs, &build_list/4)
+  end
+
+  def build!(module, generator_name, attrs) do
+    do_build(module, generator_name, attrs, &build_list!/4)
+  end
+
+  defp do_build(module, generator_name, attrs, build_list_fun) do
     module
-    |> build_list(1, generator_name, attrs)
+    |> build_list_fun.(1, generator_name, attrs)
     |> hd()
   end
 
   def build_list(module, count, generator_name, attrs) do
+    do_build_list(module, count, generator_name, attrs, &create_records_stream/3)
+  end
+
+  def build_list!(module, count, generator_name, attrs) do
+    do_build_list(module, count, generator_name, attrs, &create_records_stream!/3)
+  end
+
+  defp do_build_list(module, count, generator_name, attrs, create_records_stream_fun) do
     module
-    |> create_records_stream(generator_name, attrs)
+    |> create_records_stream_fun.(generator_name, attrs)
     |> Enum.take(count)
   end
 
   def insert(module, repo, generator_name, attrs, opts) do
+    do_insert(module, repo, generator_name, attrs, opts, &insert_list/6)
+  end
+
+  def insert!(module, repo, generator_name, attrs, opts) do
+    do_insert(module, repo, generator_name, attrs, opts, &insert_list!/6)
+  end
+
+  def do_insert(module, repo, generator_name, attrs, opts, insert_list_fun) do
     module
-    |> insert_list(repo, 1, generator_name, attrs, opts)
+    |> insert_list_fun.(repo, 1, generator_name, attrs, opts)
     |> hd()
   end
 
   def insert_list(module, repo, count, generator_name, attrs, opts) do
+    do_insert_list(module, repo, count, generator_name, attrs, opts, &create_records_stream/3)
+  end
+
+  def insert_list!(module, repo, count, generator_name, attrs, opts) do
+    do_insert_list(module, repo, count, generator_name, attrs, opts, &create_records_stream!/3)
+  end
+
+  def do_insert_list(module, repo, count, generator_name, attrs, opts, create_records_stream_fun) do
     module
-    |> create_records_stream(generator_name, attrs)
+    |> create_records_stream_fun.(generator_name, attrs)
     |> Stream.map(&insert_record(&1, repo, opts))
     |> Enum.take(count)
   end
 
   defp create_records_stream(module, generator_name, attrs) do
+    do_create_records_stream(module, generator_name, attrs, &merge_attributes/4)
+  end
+
+  defp create_records_stream!(module, generator_name, attrs) do
+    do_create_records_stream(module, generator_name, attrs, &merge_attributes!/4)
+  end
+
+  defp do_create_records_stream(module, generator_name, attrs, merge_attrs_fun) do
     module
     |> create_stream(generator_name)
     |> Stream.with_index(1)
-    |> Stream.map(&merge_attributes(&1, attrs))
+    |> Stream.map(&merge_attrs_fun.(&1, attrs, module, generator_name))
   end
 
-  defp merge_attributes({record, index}, attrs) when is_struct(record) do
+  defp merge_attributes({record, index}, attrs, _, _) when is_struct(record) do
     struct(record, prepare_attributes(attrs, index))
   end
 
-  defp merge_attributes({map, index}, attrs) when is_map(map) do
+  defp merge_attributes({map, index}, attrs, _, _) when is_map(map) do
     attrs = attrs |> prepare_attributes(index) |> Map.new()
     Map.merge(map, attrs)
   end
 
-  defp merge_attributes({maybe_keyword, index}, attrs) do
+  defp merge_attributes({maybe_keyword, index}, attrs, _, _) do
     if Keyword.keyword?(maybe_keyword) do
       Keyword.merge(maybe_keyword, prepare_attributes(attrs, index))
     else
       maybe_keyword
     end
   end
 
+  defp merge_attributes!({record, index}, attrs, module, generator_name) when is_struct(record) do
+    try do
+      struct!(record, prepare_attributes(attrs, index))
+    rescue
+      err in KeyError ->
+        raise EctoStreamFactory.MissingKeyError,
+          module: module,
+          generator_name: generator_name,
+          key: err.key
+    end
+  end
+
+  defp merge_attributes!({map, index}, attrs, module, generator_name) when is_map(map) do
+    check_missing_key(map, attrs, &Map.has_key?/2, module, generator_name)
+
+    merge_attributes({map, index}, attrs, module, generator_name)
+  end
+
+  defp merge_attributes!({maybe_keyword, index}, attrs, module, generator_name) do
+    if Keyword.keyword?(maybe_keyword) do
+      check_missing_key(maybe_keyword, attrs, &Keyword.has_key?/2, module, generator_name)
+    end
+
+    merge_attributes({maybe_keyword, index}, attrs, module, generator_name)
+  end
+
+  defp check_missing_key(map_or_keyword, attrs, has_key_fun, module, generator_name) do
+    missing_key =
+      attrs
+      |> Keyword.keys()
+      |> Enum.find_value(fn key ->
+        if has_key_fun.(map_or_keyword, key) do
+          false
+        else
+          key
+        end
+      end)
+
+    if missing_key do
+      raise EctoStreamFactory.MissingKeyError,
+        module: module,
+        generator_name: generator_name,
+        key: missing_key
+    end
+  end
+
   defp prepare_attributes(attrs, index) do
     Enum.map(attrs, fn
       {key, fun} when is_function(fun, 1) ->
@@ -71,7 +157,7 @@ defmodule EctoStreamFactory.Factory do
       apply(module, function_name, [])
     else
       raise EctoStreamFactory.UndefinedGeneratorError,
-        module: module_to_string(module),
+        module: module,
         generator_name: generator_name
     end
   end
@@ -87,11 +173,7 @@ defmodule EctoStreamFactory.Factory do
   def get_repo(module, opts) do
     case Keyword.fetch(opts, :repo) do
       {:ok, repo} -> repo
-      _ -> raise EctoStreamFactory.RepoNotSpecifiedError, module: module_to_string(module)
+      _ -> raise EctoStreamFactory.RepoNotSpecifiedError, module: module
     end
   end
-
-  defp module_to_string(module) do
-    module |> to_string() |> String.replace_prefix("Elixir.", "")
-  end
 end

mix.exs

@@ -6,7 +6,7 @@ defmodule EctoStreamFactory.MixProject do
   def project do
     [
       app: :ecto_stream_factory,
-      version: "0.1.0",
+      version: "0.2.0",
       elixir: ">= 1.10.0",
       start_permanent: Mix.env() == :prod,
       deps: deps(),