hierarchable 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cbb9e575443a02be4dff5614306785def4eecb5a7738af39261a9001de4739c
-  data.tar.gz: fb740c37795bafefbb095ce5e0bf1a0cf42b80771976f79dda4919b87bd4b3da
+  metadata.gz: ac67b8aa97065b5917fe0a13e8016d14047cac537bcbb74f8d2910614d86d0da
+  data.tar.gz: effb465602763db73be3f247daf54fe523eb3fad1ac489fe75df26f08fd4df0b
 SHA512:
-  metadata.gz: b63216b7d4c1887f8787f3775ab4f4781be9103723db3c132a1c5b87ed504ebe97129cec288662aff04e9d7755a5f567e6eb3a54b8a4a29d88fd5fb9f521582f
-  data.tar.gz: 71dee24abbeced1a0b5f13d0f8f8b0aa8bc6863f77a3f3c47e6286d7dfd77a1a4fbf8e8bb68c8dab95e9d17be3d28ddbcaa6d9ee55d34d658f6fba9db0ef97c5
+  metadata.gz: f873a3c653dd0eff928657715c49e71eead1080a9798ef7fb97b6d9df296fa4eb686f1335b2e2ba8d1f44af16065246a2918dd864e2b60b29542dcb0772361cc
+  data.tar.gz: 0be6318e611e86efec91acb95fb4225c653d43b519dece0444c15eeddd3b58b3aff9815dfaebd013f1aec9d1da64befac6fc23fe30fdc00a85b37abd3fc9ddb2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hierarchable (0.2.0)
+    hierarchable (0.3.0)
       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:
@@ -183,15 +222,25 @@ project.hierarchy_descendants(models: :this)
 task.hierarchy_siblings
 ```
 
-In order to figure out the potential descendants of an object we need to inspect the object and query all relations to to see if any of those have this object as an ancestor. In most cases these relations can be inferred correctly by getting all of the `has_many` relationships that a model has defined. However there are times when we need to manually add a child relation to be inspected. This can be done in one of two ways.
+In order to figure out the potential descendants of an object we need to inspect the object and query all relations to to see if any of those have this object as an ancestor. In many cases these relations can be inferred correctly by getting all of the `has_many` relationships that a model has defined. To be safe and not return potential duplicate associations, the only associations that are automatically detected are the ones that are the pluralized form of the model name. 
+
+```ruby
+class Project
+  has_many :tasks
+  has_many :completed_tasks, -> { completed }, class_name: 'Task'
+  has_many :timestamps, class_name: 'MetricLibrary::Timestamp`
+end
+```
+
+In the `Project` model defined above, only the `:tasks` association will be used for finding descendants.
 
-The most common case is if we want to specify additional associations. This will take all of the associations that can be auto-detected and also add in the one provided.
+However there are times when we need to manually add a child relation to be inspected. This can be done in one of two ways. The most common case is if we want to specify additional associations. This will take all of the associations that can be auto-detected and also add in the one provided.
 
 ```ruby
 class SomeObject
   include Hierarched
   hierarched parent_source: :parent,
-              additional_descendant_associations: [:some_association]
+             additional_descendant_associations: [:some_association]
 end
 ```
 
@@ -201,7 +250,7 @@ There may also be a case when we want exact control over what associations that
 class SomeObject
   include Hierarched
   hierarched parent_source: :parent,
-              descendant_associations: [:some_association]
+             descendant_associations: [:some_association]
 end
 ```
 

data/lib/hierarchable/hierarchable.rb

@@ -77,7 +77,7 @@ module Hierarchable
       self.hierarchable_config = {
         parent_source: opts.fetch(:parent_source, nil),
         additional_descendant_associations: opts.fetch(
-          :descendant_associations, []
+          :additional_descendant_associations, []
         ),
         descendant_associations: opts.fetch(:descendant_associations, nil),
         path_separator: opts.fetch(
@@ -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.
@@ -360,9 +425,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,18 +442,27 @@ 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
                   )
                 else
-                  path = public_send(:hierarchy_ancestors_path)
+                  path = public_send(:hierarchy_full_path)
                   model.where(
                     'hierarchy_ancestors_path LIKE ?',
-                    "#{model.sanitize_sql_like(path)}_%"
+                    "#{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 +470,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
 
@@ -421,10 +500,14 @@ module Hierarchable
     # Return all of the `has_many` association names this class class has as a
     # list of symbols.
     #
-    # The assumption is that all of the associations we care about for
-    # getting descendants can easily be obtained directly from inspecting
-    # the class. If there are some associations that need to be manually
-    # added, one simply specify them when setting up the model.
+    # In order to be safe and not return potential duplicate associations,
+    # the only associations that are automatically
+    # detected are the ones that are the pluralized form of the model name.
+    # For example, if a model as the association `has_many :tasks`, there
+    # will need to be a Task model for this association to be kept.
+    #
+    # If there are some associations that need to be manually
+    # added, one simply needs to specify them when setting up the model.
     #
     # The most common case is if we want to specify additional associations.
     # This will take all of the associations that can be auto-detected and
@@ -458,7 +541,7 @@ module Hierarchable
             .reject(&:through_reflection?)
             .map(&:name)
       associations += hierarchable_config[:additional_descendant_associations]
-      associations
+      associations.uniq
     end
 
     # Return the string representation of the current object in the format when
@@ -611,4 +694,12 @@ 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
+        .class_name
+        .safe_constantize
+  end
 end

data/lib/hierarchable/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hierarchable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrick R. Schmid
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-22 00:00:00.000000000 Z
+date: 2022-12-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler