hierarchable 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f108839bd5cf2491856dfdcc1af95e0d50204f32e467c22bb3f4925d0028f5be
-  data.tar.gz: 2379a67ad164232c8efb8c33f8ca6117c6e51387feb39585b4e114ce16542736
+  metadata.gz: 77318268a18001072d590f7ad65524e5f608923cea6c6e757946ad164862518b
+  data.tar.gz: 7740d0be435b42dd701fc626eaa706b58c50688c0bb7639da9caf8b5864d3f3b
 SHA512:
-  metadata.gz: 88822385da9430f6183eafbc4873a7b3009461d733768453212c3abaf615bca2e318da1c36ac3fb9a4d46bdb072fcd07655069a9148a314212915e205f34baa0
-  data.tar.gz: bc9b0a309a1e31d7da843ff2ed5f1e75384f9812f63bde5d759018f72de51ebab45e8ea32d45f79cd7f12451d56b439bb69b32b2af0cbc06ee62eeab17ca7d44
+  metadata.gz: '078378d734ddc00ccfcecf685fdd142e581560af7444a34985172c354eae1aeedb91ea98a2b08fd47a20728ce8d594c5d965a49409e7957236549b34352a852f'
+  data.tar.gz: 4b9192aec201abb47df5be7589a207c46131fb3544bb2b7cb439dd5c4d6a5df4fe09bc98e32aba14b72b2f3aa789295933226793cb282741a90f1dcd442f38ca

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hierarchable (0.2.1)
+    hierarchable (0.3.1)
       activerecord (> 4.2.0)
       activesupport (> 4.2.0)
 
@@ -35,7 +35,7 @@ GEM
     rake (13.0.6)
     regexp_parser (2.6.1)
     rexml (3.2.5)
-    rubocop (1.40.0)
+    rubocop (1.41.1)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.1.2.1)

data/README.md

@@ -134,6 +134,45 @@ sub_task.hierarchy_parent == task
 sub_task.hierarchy_ancestors_path == 'Project|xxxxxx/Task|yyyyyy/Task|zzzzzz'
 ```
 
+### Core functionality
+
+The core methods that are of interest are the following:
+
+```ruby
+project.hierarchy_ancestors
+project.hierarchy_parent
+project.hierarchy_siblings
+project.hierarchy_children
+project.hierarchy_descendants
+```
+
+The major distinction for what is returned is whether you are querying "up the hierarchy" or "down the hierarchy". As there is only 1 path up the hierchy to get to the root, the return values of `hierarchy_ancestors` is a list and `hierarchy_parent` is a single object. However, traversing down the list is a little more tricky as there are various models and potential paths to get all the way do to the leaves. As such, for all methods at the same level or going down the tree (`hierarchy_siblings`, `hierarchy_children`, and `hierarchy_descendants`), the return value is a hash that has the model class as the key, and either a `ActiveRecord::Relation` or a list as the value. For example, for a Project model that has tasks and milestones as descendants, the return value might be something like
+
+```
+{
+  'Task': [all descendant tasks starting at the project]
+  'Milestone': [all descendant milestones starting at the project]
+}
+```
+Given the architecture of this library, this is the most efficient way to return all objects with as few queries as possible.
+
+#### Limiting the objects returned
+
+All of the methods (except `hierarchy_parent`) take a `models` paramter that can be used to limit the results returned. The potential values are 
+
+* `:all` (default): Return all objects regardless of type
+* `:this`: Return only objects of the SAME time as the current object
+* An array of models of interest: Return only the objects of the type(s) that are specified (e.g. [`Project`] or [`Project`, `Task`]). The models can be passed either as class objects or a string that can be turned into a class object via `safe_constantize`.
+
+There are times when we only need to get the siblings/children/descendants of one type and having a hash returned is a little cumbersome. To deal with this case, you can pass `compact: true` as a parameter and it will return just single result not as a hash. For example:
+
+```
+# Returns as a hash of the form `{Task: [..all descendants..]}`
+project.hierarch_descendants(models: ['Task'])
+
+# Returns just the result: `[..all descendants..]`
+project.hierarch_descendants(models: ['Task'], compact: true)
+```
 ### Working with siblings and descendants of an object
 
 Let's continue with our `Project` and `Task` example from above and assume we have the following models:
@@ -199,7 +238,7 @@ However there are times when we need to manually add a child relation to be insp
 
 ```ruby
 class SomeObject
-  include Hierarched
+  include Hierarchable
   hierarched parent_source: :parent,
              additional_descendant_associations: [:some_association]
 end
@@ -209,7 +248,7 @@ There may also be a case when we want exact control over what associations that
 
 ```ruby
 class SomeObject
-  include Hierarched
+  include Hierarchable
   hierarched parent_source: :parent,
              descendant_associations: [:some_association]
 end

data/lib/hierarchable/hierarchable.rb

@@ -240,16 +240,76 @@ module Hierarchable
       end
 
       models = hierarchy_descendant_associations.map do |association|
-        self.association(association)
-            .reflection
-            .class_name
-            .safe_constantize
+        class_for_association(association)
       end
 
       models << self.class if include_self
       models.uniq
     end
 
+    # Get the children of an object.
+    #
+    # For a given object type, return all siblings as a hash such that the key
+    # is the model and the value is the list of siblings of that model.
+    #
+    # If the `models` parameter is `:all` (default), then the result
+    # will contain objects of different types. E.g. if we have a Project,
+    # Task, and a Comment, the siblings of a Task may include both Tasks and
+    # Comments. If you only need this one particular model's data, then
+    # set `models` to `:this`. If you want to specify a specific list of models
+    # then that can be passed as a list (e.g. [MyModel1, MyModel2])
+    #
+    # The `include_self` parameter can be set to decide where to start the
+    # the children search. If set to `false` (default), then it will return
+    # all models found starting with the for all children. If set to
+    # `true`, then it will include the current object's class. Note, this
+    # parameter is added here for consistency, but in the case of children,
+    # it is unlikely that `include_self` would be set to `true`
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
+    def hierarchy_children(include_self: false, models: :all, compact: false)
+      return {} unless respond_to?(:hierarchy_parent_id)
+
+      # Convert all of the models to actual classes if they are passed as
+      # stings.
+      if models.is_a?(Array)
+        models = models.map do |model|
+          model.is_a?(String) ? model.safe_constantize : model
+        end
+      end
+
+      result = {}
+      hierarchy_descendant_associations.each do |association|
+        model = class_for_association(association)
+
+        next unless models == :all ||
+                    (models.is_a?(Array) && models.include?(model)) ||
+                    (models == :this && instance_of?(model))
+
+        result[model.to_s] = public_send(association)
+      end
+
+      # If we want to include self, we need to do some extra work
+      if include_self
+        if result.key?(self.class.to_s)
+          result[self.class.to_s] = \
+            result[self.class.to_s].or(self.class.where(id:))
+        elsif models == :all ||
+              models == :this ||
+              (models.is_a?(Array) && models.include?(self.class))
+          result[self.class.to_s] = [self]
+        end
+      end
+
+      # Compact the results if necessary# Compact the results if necessary
+      _, result = result.first if result.size == 1 && compact
+      result
+    end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
+
     # Get all of the sibling models
     #
     # The `include_self` parameter can be set to decide what to include in the
@@ -265,10 +325,7 @@ module Hierarchable
       models.uniq
     end
 
-    # Get siblings of the same type for an object.
-    #
-    # For a given object type, return all siblings as a hash such that the key
-    # is the model and the value is the list of siblings of that model.
+    # Get siblings of an object.
     #
     # If the `models` parameter is `:all` (default), then the result
     # will contain objects of different types. E.g. if we have a Project,
@@ -276,7 +333,9 @@ module Hierarchable
     # Comments. If you only need this one particular model's data, then
     # set `models` to `:this`. If you want to specify a specific list of models
     # then that can be passed as a list (e.g. [MyModel1, MyModel2])
-    def hierarchy_siblings(include_self: false, models: :all)
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
+    def hierarchy_siblings(include_self: false, models: :all, compact: false)
       return {} unless respond_to?(:hierarchy_parent_id)
 
       models = case models
@@ -290,15 +349,21 @@ module Hierarchable
 
       result = {}
       models.each do |model|
+        model = model.safe_constantize if model.is_a?(String)
         query = model.where(
           hierarchy_parent_type: public_send(:hierarchy_parent_type),
           hierarchy_parent_id: public_send(:hierarchy_parent_id)
         )
         query = query.where.not(id:) if model == self.class && !include_self
-        result[model] = query
+        result[model.to_s] = query
       end
+
+      # Compact the results if necessary
+      _, result = result.first if result.size == 1 && compact
       result
     end
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
 
     # Get all of the descendant models for objects that are descendants of
     # the current one.
@@ -331,6 +396,7 @@ module Hierarchable
       until models_to_analyze.empty?
 
         klass = models_to_analyze.pop
+        next unless klass
         next if models.include?(klass)
 
         obj = klass.new
@@ -360,9 +426,10 @@ module Hierarchable
     # Comments. If you only need this one particular model's data, then
     # set `models` to `:this`. If you want to specify a specific list of models
     # then that can be passed as a list (e.g. [MyModel1, MyModel2])
+    # rubocop:disable Metrics/AbcSize
     # rubocop:disable Metrics/CyclomaticComplexity
     # rubocop:disable Metrics/PerceivedComplexity
-    def hierarchy_descendants(include_self: false, models: :all)
+    def hierarchy_descendants(include_self: false, models: :all, compact: false)
       return {} unless respond_to?(:hierarchy_ancestors_path)
 
       models = case models
@@ -376,7 +443,13 @@ module Hierarchable
 
       result = {}
       models.each do |model|
+        model = model.safe_constantize if model.is_a?(String)
         query = if hierarchy_root?
+                  # If it's the root, we need to base the query based on the
+                  # hierarchy_root attribute since the ancestor_path will be
+                  # empty for a root node. See the README for the explanation
+                  # as to why the root node has values set to nil and the
+                  # path as the empty string.
                   model.where(
                     hierarchy_root_type: self.class.name,
                     hierarchy_root_id: id
@@ -388,6 +461,9 @@ module Hierarchable
                     "#{model.sanitize_sql_like(path)}%"
                   )
                 end
+
+        # Make sure to include/exlude the current object depending on what the
+        # user wants
         if model == self.class
           query = if include_self
                     query.or(model.where(id:))
@@ -395,10 +471,14 @@ module Hierarchable
                     query.where.not(id:)
                   end
         end
-        result[model] = query
+        result[model.to_s] = query
       end
+
+      # Compact the results if necessary
+      _, result = result.first if result.size == 1 && compact
       result
     end
+    # rubocop:enable Metrics/AbcSize
     # rubocop:enable Metrics/CyclomaticComplexity
     # rubocop:enable Metrics/PerceivedComplexity
 
@@ -435,7 +515,7 @@ module Hierarchable
     # also add in the one provided.
     #
     #   class A
-    #     include Hierarched
+    #     include Hierarchable
     #     hierarched parent_source: :parent,
     #                additional_descendant_associations: [:some_association]
     #   end
@@ -444,7 +524,7 @@ module Hierarchable
     # that should be used. In that case, we can specify it like this:
     #
     #   class A
-    #     include Hierarched
+    #     include Hierarchable
     #     hierarched parent_source: :parent,
     #                descendant_associations: [:some_association]
     #   end
@@ -603,11 +683,15 @@ module Hierarchable
     def hierarchy_parent_changed?
       # FIXME: We need to figure out how to deal with updating the
       # object_hierarchy_ancestry_path, object_hierarchy_full_path, etc.,
-      if hierarchy_parent_source.present?
-        public_send("#{hierarchy_parent_source}_id_changed?")
-      else
-        false
-      end
+      return true unless persisted?
+
+      source = hierarchy_parent_source
+      return false if source.blank?
+
+      changed_method = "#{source}_id_changed?"
+      public_send(changed_method) if respond_to?(changed_method)
+
+      send(source).id == hierarchy_parent_id
     end
 
     # Update the hierarchy_ancestors_path if the hierarchy has changed.
@@ -615,4 +699,11 @@ module Hierarchable
       set_hierarchy_ancestors_path
     end
   end
+
+  # Get the class that is associated with a given association
+  def class_for_association(association)
+    self.association(association)
+        .reflection
+        .klass
+  end
 end

data/lib/hierarchable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hierarchable
-  VERSION = '0.2.1'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hierarchable
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Patrick R. Schmid
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-23 00:00:00.000000000 Z
+date: 2023-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler