api improvement, transact consistency

Author: AlexGx

README.md

@@ -1,5 +1,5 @@
 
-# NestedSets
+# NestedSets for Ecto
 
 ![NestedSets](https://raw.githubusercontent.com/AlexGx/nested_sets/master/artwork/banner.png)
 
@@ -15,7 +15,7 @@
   </a>
 </p>
 
-Battle-tested NestedSets behavior for Ecto that supports PostgreSQL, SQLite, and MySQL.
+Battle-tested NestedSets for Ecto that supports PostgreSQL, SQLite, and MySQL.
 
 TODO: about Ecto 3.12+, add to doc `depth` is also a `level`
 

lib/nested_sets.ex

@@ -106,7 +106,7 @@ defmodule NestedSets do
 
   defp validate_single_root(repo, node, cfg) do
     exists? = repo.exists?(from n in node.__struct__, where: field(n, ^cfg.lft) == 1)
-    if exists?, do: repo.rollback(:root_already_exists), else: :ok
+    if exists?, do: {:error, :root_already_exists}, else: :ok
   end
 
   defp insert_root_node(repo, node, cfg) do
@@ -303,13 +303,13 @@ defmodule NestedSets do
   @doc """
   Checks if node is a child/descendant of the potential parent.
   """
-  @spec child_of?(ns_node(), ns_node()) :: boolean()
-  def child_of?(node, potential_parent) do
+  @spec descendant_of?(ns_node(), ns_node()) :: boolean()
+  def descendant_of?(node, potential_parent) do
     cfg = config(node)
 
     if node.__struct__ != potential_parent.__struct__ do
       raise ArgumentError,
-            "child_of?/2 expects both arguments to be structs of the same Schema, " <>
+            "descendant_of?/2 expects both arguments to be structs of the same Schema, " <>
               "got #{inspect(node.__struct__)} and #{inspect(potential_parent.__struct__)}"
     end
 
@@ -318,25 +318,25 @@ defmodule NestedSets do
     parent_lft = Map.get(potential_parent, cfg.lft)
     parent_rgt = Map.get(potential_parent, cfg.rgt)
 
-    is_descendant = node_lft > parent_lft && node_rgt < parent_rgt
+    descendant? = node_lft > parent_lft && node_rgt < parent_rgt
 
-    if is_descendant && cfg.tree != false do
+    if descendant? && cfg.tree != false do
       Map.get(node, cfg.tree) == Map.get(potential_parent, cfg.tree)
     else
-      is_descendant
+      descendant?
     end
   end
 
   @doc """
-  Checks if node is a direct child/descendant of the potential parent.
+  Checks if node is a direct child of the potential parent.
   """
-  @spec direct_child_of?(ns_node(), ns_node()) :: boolean()
-  def direct_child_of?(node, potential_parent) do
+  @spec child_of?(ns_node(), ns_node()) :: boolean()
+  def child_of?(node, potential_parent) do
     cfg = config(node)
 
     if node.__struct__ != potential_parent.__struct__ do
       raise ArgumentError,
-            "direct_child_of?/2 expects both arguments to be structs of the same Schema, " <>
+            "child_of?/2 expects both arguments to be structs of the same Schema, " <>
               "got #{inspect(node.__struct__)} and #{inspect(potential_parent.__struct__)}"
     end
 
@@ -352,11 +352,11 @@ defmodule NestedSets do
     parent_lft = Map.get(potential_parent, cfg.lft)
     parent_rgt = Map.get(potential_parent, cfg.rgt)
 
-    is_descendant? = node_lft > parent_lft && node_rgt < parent_rgt
+    descendant? = node_lft > parent_lft && node_rgt < parent_rgt
 
-    has_correct_depth? = Map.get(node, cfg.depth) == Map.get(potential_parent, cfg.depth) + 1
+    correct_depth? = Map.get(node, cfg.depth) == Map.get(potential_parent, cfg.depth) + 1
 
-    same_scope? && is_descendant? && has_correct_depth?
+    same_scope? && descendant? && correct_depth?
   end
 
   @doc """
@@ -644,7 +644,7 @@ defmodule NestedSets do
       get_primary_key(node) == get_primary_key(target) ->
         {:error, :cannot_move_to_itself}
 
-      child_of?(target, node) ->
+      descendant_of?(target, node) ->
         {:error, :cannot_move_to_descendant}
 
       position in [:before, :after] && root?(target) ->

lib/nested_sets/query.ex

@@ -24,6 +24,8 @@ defmodule NestedSets.Query do
 
   import Ecto.Query
 
+  @type ns_node :: struct()
+
   defp config(schema), do: NestedSets.config(schema)
 
   defp get_schema(queryable) do
@@ -39,7 +41,7 @@ defmodule NestedSets.Query do
   ## Options
     * `:depth` - limit to ancestors within N levels (optional)
   """
-  @spec ancestors(Ecto.Queryable.t(), struct(), keyword()) :: Ecto.Query.t() | nil
+  @spec ancestors(Ecto.Queryable.t(), ns_node(), keyword()) :: Ecto.Query.t() | nil
   def ancestors(queryable, node, opts \\ []) do
     schema = get_schema(queryable)
     cfg = config(schema)
@@ -73,7 +75,7 @@ defmodule NestedSets.Query do
   @doc """
   Alias for `ancestors/3`.
   """
-  @spec parents(Ecto.Queryable.t(), struct(), keyword()) :: Ecto.Query.t() | nil
+  @spec parents(Ecto.Queryable.t(), ns_node(), keyword()) :: Ecto.Query.t() | nil
   def parents(queryable, node, opts \\ []), do: ancestors(queryable, node, opts)
 
   @doc """
@@ -82,7 +84,7 @@ defmodule NestedSets.Query do
   ## Options
     * `:depth` - limit to descendants within N levels (optional)
   """
-  @spec descendants(Ecto.Queryable.t(), struct(), keyword()) :: Ecto.Query.t() | nil
+  @spec descendants(Ecto.Queryable.t(), ns_node(), keyword()) :: Ecto.Query.t() | nil
   def descendants(queryable, node, opts \\ []) do
     schema = get_schema(queryable)
     cfg = config(schema)
@@ -116,7 +118,7 @@ defmodule NestedSets.Query do
   @doc """
   Alias for `descendants/3`.
   """
-  @spec children(Ecto.Queryable.t(), struct(), keyword()) :: Ecto.Query.t() | nil
+  @spec children(Ecto.Queryable.t(), ns_node(), keyword()) :: Ecto.Query.t() | nil
   def children(queryable, node, opts \\ []), do: descendants(queryable, node, opts)
 
   @doc """
@@ -128,7 +130,7 @@ defmodule NestedSets.Query do
   @doc """
   Finds all leaf nodes (nodes without children) under a node.
   """
-  @spec leaves(Ecto.Queryable.t(), struct()) :: Ecto.Query.t() | nil
+  @spec leaves(Ecto.Queryable.t(), ns_node()) :: Ecto.Query.t() | nil
   def leaves(queryable, node) do
     schema = get_schema(queryable)
     cfg = config(schema)
@@ -150,7 +152,7 @@ defmodule NestedSets.Query do
   @doc """
   Finds the previous sibling of a node.
   """
-  @spec prev_sibling(Ecto.Queryable.t(), struct()) :: Ecto.Query.t() | nil
+  @spec prev_sibling(Ecto.Queryable.t(), ns_node()) :: Ecto.Query.t() | nil
   def prev_sibling(queryable, node) do
     schema = get_schema(queryable)
     cfg = config(schema)
@@ -168,13 +170,13 @@ defmodule NestedSets.Query do
   @doc """
   Alias for `prev_sibling/2`.
   """
-  @spec prev(Ecto.Queryable.t(), struct()) :: Ecto.Query.t() | nil
+  @spec prev(Ecto.Queryable.t(), ns_node()) :: Ecto.Query.t() | nil
   def prev(queryable, node), do: prev_sibling(queryable, node)
 
   @doc """
   Finds the next sibling of a node.
   """
-  @spec next_sibling(Ecto.Queryable.t(), struct()) :: Ecto.Query.t() | nil
+  @spec next_sibling(Ecto.Queryable.t(), ns_node()) :: Ecto.Query.t() | nil
   def next_sibling(queryable, node) do
     schema = get_schema(queryable)
     cfg = config(schema)
@@ -192,13 +194,13 @@ defmodule NestedSets.Query do
   @doc """
   Alias for `next_sibling/2`.
   """
-  @spec next(Ecto.Queryable.t(), struct()) :: Ecto.Query.t() | nil
+  @spec next(Ecto.Queryable.t(), ns_node()) :: Ecto.Query.t() | nil
   def next(queryable, node), do: next_sibling(queryable, node)
 
   @doc """
   Finds all siblings of a node (nodes with the same parent).
   """
-  @spec siblings(Ecto.Queryable.t(), struct()) :: Ecto.Query.t() | nil
+  @spec siblings(Ecto.Queryable.t(), ns_node()) :: Ecto.Query.t() | nil
   def siblings(queryable, node) do
     schema = get_schema(queryable)
     cfg = config(schema)
@@ -245,7 +247,7 @@ defmodule NestedSets.Query do
   @doc """
   Finds the root node for a specific tree (when using tree).
   """
-  @spec root(Ecto.Queryable.t(), struct()) :: Ecto.Query.t() | nil
+  @spec root(Ecto.Queryable.t(), ns_node()) :: Ecto.Query.t() | nil
   def root(queryable, node) do
     schema = get_schema(queryable)
     cfg = config(schema)
@@ -262,7 +264,7 @@ defmodule NestedSets.Query do
   @doc """
   Gets a node and all its descendants (the full subtree including the node itself).
   """
-  @spec subtree(Ecto.Queryable.t(), struct()) :: Ecto.Query.t() | nil
+  @spec subtree(Ecto.Queryable.t(), ns_node()) :: Ecto.Query.t() | nil
   def subtree(queryable, node) do
     schema = get_schema(queryable)
     cfg = config(schema)
@@ -283,7 +285,7 @@ defmodule NestedSets.Query do
   @doc """
   Finds nodes at a specific depth level.
   """
-  @spec at_depth(Ecto.Queryable.t(), integer()) :: Ecto.Query.t()
+  @spec at_depth(Ecto.Queryable.t(), non_neg_integer()) :: Ecto.Query.t()
   def at_depth(queryable, depth) do
     schema = get_schema(queryable)
     cfg = config(schema)
@@ -295,11 +297,10 @@ defmodule NestedSets.Query do
   end
 
   @doc """
-  @review: not only :integer
   Filters by a specific tree (when using tree).
-  Accepts either a tree_id integer or a node struct.
+  Accepts either a tree_id integer or a node.
   """
-  @spec in_tree(Ecto.Queryable.t(), integer() | struct()) :: Ecto.Query.t() | nil
+  @spec in_tree(Ecto.Queryable.t(), pos_integer() | ns_node()) :: Ecto.Query.t() | nil
   def in_tree(queryable, tree_id) when is_integer(tree_id) do
     schema = get_schema(queryable)
     cfg = config(schema)