[#189] All commands optionally support a dynamic cache as the first a…

…rgument

.formatter.exs

@@ -1,12 +1,12 @@
 locals_without_parens = [
-  # Nebulex.Helpers
+  # Nebulex.Utils
   unwrap_or_raise: 1,
   wrap_ok: 1,
   wrap_error: 1,
   wrap_error: 2,
 
-  # Nebulex.Cache
-  dynamic_cache: 2,
+  # Nebulex.Cache.Utils
+  defcacheapi: 2,
 
   # Nebulex.Caching
   cache_ref: 1,

guides/creating-new-adapter.md

@@ -256,7 +256,7 @@ defmodule NebulexMemoryAdapter do
   @behaviour Nebulex.Adapter
   @behaviour Nebulex.Adapter.Queryable
 
-  import Nebulex.Helpers
+  import Nebulex.Utils
 
   @impl Nebulex.Adapter
   defmacro __before_compile__(_env), do: :ok
@@ -308,7 +308,7 @@ defmodule NebulexMemoryAdapter do
   @behaviour Nebulex.Adapter.KV
   @behaviour Nebulex.Adapter.Queryable
 
-  import Nebulex.Helpers
+  import Nebulex.Utils
 
   @impl Nebulex.Adapter
   defmacro __before_compile__(_env), do: :ok

lib/nebulex/adapter/persistence.ex

@@ -51,7 +51,7 @@ defmodule Nebulex.Adapter.Persistence do
     quote do
       @behaviour Nebulex.Adapter.Persistence
 
-      import Nebulex.Helpers
+      import Nebulex.Utils, only: [wrap_error: 2]
 
       @impl true
       def dump(%{cache: cache}, path, opts) do

lib/nebulex/adapter/stats.ex

@@ -40,7 +40,7 @@ defmodule Nebulex.Adapter.Stats do
       @behaviour Nebulex.Adapter.Stats
 
       import Nebulex.Adapter.Stats, only: [defspan: 2, defspan: 3]
-      import Nebulex.Helpers
+      import Nebulex.Utils, only: [wrap_error: 2]
 
       @impl true
       def stats(adapter_meta, _opts) do

lib/nebulex/adapter/transaction.ex

@@ -35,39 +35,40 @@ defmodule Nebulex.Adapter.Transaction do
 
   Locking only the involved key (recommended):
 
-      MyCache.transaction [keys: [:counter]], fn ->
-        counter = MyCache.get(:counter)
-        MyCache.set(:counter, counter + 1)
-      end
-
-      MyCache.transaction [keys: [:alice, :bob]], fn ->
-        alice = MyCache.get(:alice)
-        bob = MyCache.get(:bob)
-        MyCache.set(:alice, %{alice | balance: alice.balance + 100})
-        MyCache.set(:bob, %{bob | balance: bob.balance + 100})
-      end
+      MyCache.transaction(
+        fn ->
+          counter = MyCache.get(:counter)
+          MyCache.set(:counter, counter + 1)
+        end,
+        [keys: [:counter]]
+      )
+
+      MyCache.transaction(
+        fn ->
+          alice = MyCache.get(:alice)
+          bob = MyCache.get(:bob)
+          MyCache.set(:alice, %{alice | balance: alice.balance + 100})
+          MyCache.set(:bob, %{bob | balance: bob.balance + 100})
+        end,
+        [keys: [:alice, :bob]]
+      )
 
   """
 
   @doc """
   Runs the given function inside a transaction.
 
-  A successful transaction returns the value returned by the function wrapped
-  in a tuple as `{:ok, value}`.
-
-  In case the transaction cannot be executed, then `{:error, reason}` is
-  returned.
+  If an Elixir exception occurs, the exception will bubble up from the
+  transaction function. If the transaction is aborted,
+  `{:error, Nebulex.Error.t()}` is returned.
 
-  If an unhandled error/exception occurs, the error will bubble up from the
-  transaction function.
-
-  If `transaction/2` is called inside another transaction, the function is
-  simply executed without wrapping the new transaction call in any way.
+  A successful transaction returns the value returned by the function wrapped
+  in a tuple as `{:ok, any()}`.
 
   See `c:Nebulex.Cache.transaction/2`.
   """
-  @callback transaction(Nebulex.Adapter.adapter_meta(), Nebulex.Cache.opts(), (() -> any())) ::
-              any()
+  @callback transaction(Nebulex.Adapter.adapter_meta(), fun(), Nebulex.Cache.opts()) ::
+              Nebulex.Cache.ok_error_tuple(any())
 
   @doc """
   Returns `{:ok, true}` if the current process is inside a transaction,
@@ -85,10 +86,10 @@ defmodule Nebulex.Adapter.Transaction do
     quote do
       @behaviour Nebulex.Adapter.Transaction
 
-      import Nebulex.Helpers
+      import Nebulex.Utils, only: [wrap_ok: 1, wrap_error: 2]
 
       @impl true
-      def transaction(%{cache: cache, pid: pid} = adapter_meta, opts, fun) do
+      def transaction(%{cache: cache, pid: pid} = adapter_meta, fun, opts) do
         adapter_meta
         |> do_in_transaction?()
         |> do_transaction(

lib/nebulex/adapters/nil.ex

@@ -70,7 +70,7 @@ defmodule Nebulex.Adapters.Nil do
   # Inherit default transaction implementation
   use Nebulex.Adapter.Transaction
 
-  import Nebulex.Helpers
+  import Nebulex.Utils, only: [wrap_error: 2]
 
   ## Nebulex.Adapter