hierarchable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c927f016abf308f6c0128f2162908afccb89f55b95495b3499ecfa6a6acdec56
+  data.tar.gz: 85724a8ec5e256a5251241f7dc5ef8539c2a041bf683834a6ac0081f02efd922
+SHA512:
+  metadata.gz: 28f8b977db00b49eba24c634bcd19381fa631b519c1c371a4b8fdba15b9ac7475ce638a8e0f87c46f28caf1247abc783de1359d999f6f8343bd1d181f48548f4
+  data.tar.gz: 7515ea80776d9b60856f91374cedf3d50bfec3f32d572e06bdada94a72a64d64f940ce52b7fd56b1e625ab467885553d6b077d612ad49862f51106e27a6ea4de

data/.circleci/config.yml

@@ -0,0 +1,116 @@
+version: 2.1
+
+# ----------------------------------------------------------------------------
+#
+# REUSABLE CUSTOM DEFINITIONS & COMMANDS
+#
+# ----------------------------------------------------------------------------
+
+commands:
+  attach-dependencies:
+    steps:
+      - checkout
+      - run:
+          name: Set up bundler
+          command: |
+            gem install bundler:2.3.26
+      - run:
+          name: Bundle Install
+          command: |
+            bundle config set --local clean 'true'
+            bundle config set --local deployment 'true'
+            bundle check || bundle install --jobs=4 --retry=3
+      - attach_workspace:
+          at: .
+  
+  save-results:
+    steps:
+      - store_test_results:
+          path: test/reports
+      - store_artifacts:
+          name: "Store artifacts: test reports"
+          path: reports
+          destination: reports
+
+# ----------------------------------------------------------------------------
+#
+# JOB DEFINITIONS
+#
+# ----------------------------------------------------------------------------
+
+jobs:
+  #
+  # QUALITY: Make sure that the code is safe, secure, and clean.
+  #
+  quality:
+    resource_class: small
+
+    docker:
+      - image: cimg/ruby:3.1.3
+
+    steps:
+      # --------- SETUP ---------
+
+      - attach-dependencies
+
+      # --------- QUALITY CHECKS ---------
+
+      - run:
+          name: Ruby Audit
+          command: bundle exec ruby-audit check
+      - run:
+          name: Bundle Audit
+          command: bundle exec bundle-audit check --update
+      - run:
+          name: Rubocop
+          command: bundle exec rubocop
+
+      # --------- SAVE RESULTS ---------
+
+      - save-results
+
+  test:
+    resource_class: small
+
+    docker:
+      - image: cimg/ruby:3.1.3
+
+    steps:
+      # --------- SETUP ---------
+
+      - attach-dependencies
+
+      # --------- RUN TESTS ---------
+
+      - run:
+          name: Run tests
+          command: bundle exec rake test
+
+      # --------- SAVE RESULTS ---------
+
+      - save-results
+
+
+# ----------------------------------------------------------------------------
+#
+# WORKFLOW DEFINITIONS
+#
+# ----------------------------------------------------------------------------
+
+workflows:
+  version: 2
+  commit:
+    jobs:
+      - quality
+      - test
+  nightly:
+    jobs:
+      - quality
+      - test
+    triggers:
+      - schedule:
+          cron: "0 2 * * *"
+          filters:
+            branches:
+              only:
+                - main

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -0,0 +1,58 @@
+require:
+  - 'rubocop-performance'
+  - 'rubocop-rails'
+  - 'rubocop-minitest'
+  - 'rubocop-rake'
+
+AllCops:
+  NewCops: enable
+  # Don't run rubocop on these files/directories
+  Exclude:
+    - '**/templates/**/*'
+    - '**/vendor/**/*'
+    - 'actionpack/lib/action_dispatch/journey/parser.rb'
+    - 'lib/templates/**/*'
+    - 'db/**/*'
+    - 'config/**/*'
+    - 'vendor/**/*'
+    - 'bin/**/*'
+    - 'node_modules/**/*'
+
+Layout/LineLength:
+  Max: 80
+  Exclude:
+    - 'lib/hierarchable/hierarchable.rb'
+
+Metrics/AbcSize:
+  Max: 30
+  Exclude:
+    - 'test/**/*'
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'hierarchable.gemspec'
+    - 'lib/hierarchable/hierarchable.rb'
+    - 'test/**/*'
+
+Metrics/ClassLength:
+  Max: 150
+  Exclude:
+    - 'test/**/*'
+
+Metrics/MethodLength:
+  Max: 35
+  Exclude:
+    - 'test/**/*'
+
+Metrics/ModuleLength:
+  Max: 100
+  Exclude:
+    - 'lib/hierarchable/hierarchable.rb'
+
+Minitest/MultipleAssertions:
+  Max: 10
+
+Rails/RefuteMethods:
+  Exclude:
+    - 'test/**/*'

data/.ruby-gemset

@@ -0,0 +1 @@
+hierarchable

data/.ruby-version

@@ -0,0 +1 @@
+ruby-3.1.3

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hierarchable.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+
+gem 'minitest', '~> 5.0'
+
+gem 'rubocop', '~> 1.21'

data/Gemfile.lock

@@ -0,0 +1,94 @@
+PATH
+  remote: .
+  specs:
+    hierarchable (0.1.0)
+      activerecord (> 4.2.0)
+      activesupport (> 4.2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (7.0.4)
+      activesupport (= 7.0.4)
+    activerecord (7.0.4)
+      activemodel (= 7.0.4)
+      activesupport (= 7.0.4)
+    activesupport (7.0.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    ast (2.4.2)
+    bundler-audit (0.9.1)
+      bundler (>= 1.2.0, < 3)
+      thor (~> 1.0)
+    concurrent-ruby (1.1.10)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    json (2.6.3)
+    minitest (5.16.3)
+    parallel (1.22.1)
+    parser (3.1.3.0)
+      ast (~> 2.4.1)
+    rack (3.0.2)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.1)
+    rexml (3.2.5)
+    rubocop (1.40.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.2.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.24.0)
+      parser (>= 3.1.1.0)
+    rubocop-minitest (0.25.0)
+      rubocop (>= 0.90, < 2.0)
+    rubocop-performance (1.15.1)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rails (2.17.3)
+      activesupport (>= 4.2.0)
+      rack (>= 1.1)
+      rubocop (>= 1.33.0, < 2.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    ruby-progressbar (1.11.0)
+    ruby_audit (2.1.0)
+      bundler-audit (~> 0.9.0)
+    sqlite3 (1.5.4-x86_64-darwin)
+    sqlite3 (1.5.4-x86_64-linux)
+    temping (4.0.0)
+      activerecord (>= 5.2, < 7.1)
+      activesupport (>= 5.2, < 7.1)
+    thor (1.2.1)
+    tzinfo (2.0.5)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.3.0)
+
+PLATFORMS
+  x86_64-darwin-22
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (~> 2.3)
+  bundler-audit
+  hierarchable!
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  rubocop (~> 1.21)
+  rubocop-minitest
+  rubocop-performance
+  rubocop-rails
+  rubocop-rake
+  ruby_audit
+  sqlite3
+  temping (~> 4.0)
+
+BUNDLED WITH
+   2.3.26

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,176 @@
+# Hierarchable
+
+[![CircleCI](https://dl.circleci.com/status-badge/img/gh/prschmid/hierarchable/tree/main.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/prschmid/hierarchable/tree/main)
+
+Cross model hierarchical (parent, child, sibling) relationship between ActiveRecord models.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hierarchable'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hierarchable
+
+Once the gem is installed, you will need to make sure that your models have the correct columns.
+
+* hierarchy_root: The root node in the hierarchy hierarchy (polymorphic)
+* hierarchy_parent: The parent of the current object (polymorphic)
+* hierarchy_ancestors_path: The string representation of all ancestors of
+                            the current object (string).
+
+Assuming that you are using UUIDs for your IDs, this can be done by adding the following to the model(s) for which you wish to have hierarchy information:
+
+```
+t.references :hierarchy_root,
+             polymorphic: true,
+             null: true,
+             type: :uuid,
+             index: true
+t.references :hierarchy_parent,
+             polymorphic: true,
+             null: true,
+             type: :uuid,
+             index: true
+t.string :hierarchy_ancestors_path, index: true
+```
+
+The `hierarchy_ancestors_path` column does contain all of the information that is in the `hierarchy_root` and `hierarchy_parent` columns, but those two columns are created for more efficient querying as the direct parent and the root are the most frequent parts of the hierarchy that are needed.
+
+## Usage
+
+We will describe the usage using a simplistic Project and Task analogy where we assume that a Project can have many tasks. Given a class `Project` we can set it up as follows
+
+```ruby
+class Project
+  include Hierarchable
+  hierarchable
+end
+```
+
+This will set up the `Project` as the root of the hierarchy. This means that when we query for its root or parent, it will return "self". I.e.
+
+```ruby
+project = Project.create!
+
+# These will be true (assuming the the ID of the project is the UUID xxxxxxxx-...)
+project.hierarchy_root == project
+project.hierarchy_parent == project
+project.hierarchy_ancestors_path == 'Project|xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+```
+
+Now that we have a project configured, we can add tasks that have projects as a parent.
+
+```ruby
+class Task
+  include Hierarchable
+  hierarchable parent_source: :project
+
+  belongs_to :project
+end
+```
+
+This will configure the hierarchy to look at the project association and use that to compute the parent. So now when we instantiate a task, the parent and root of that task will be the project.
+
+```ruby
+project = Project.create!
+task = Task.create!(project: project)
+
+# These will be true
+task.hierarchy_root == project
+task.hierarchy_parent == project
+project.hierarchy_ancestors_path == 'Project|xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+task.hierarchy_root == project
+task.hierarchy_parent == project
+task.hierarchy_ancestors_path == 'Project|xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/Task|yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy'
+```
+
+Now, let's assume that our tasks can also have other Tasks as subtasks. Once we do that, we need to ensure that the parent of a subtask is the task and not the project. For this we, can do something like the following:
+
+```ruby
+class Task
+  include Hierarchable
+  hierarchable parent_source: ->(object) {
+    obj.parent_task.present? ? :parent_task : :project
+  }
+
+  belongs_to :project
+  belongs_to :parent_task,
+             class_name: 'Task',
+             optional: true
+  has_many :sub_tasks,
+           class_name: 'Task',
+           foreign_key: :parent_task
+           inverse_of: :parent_task,
+           dependent: :destroy
+end
+```
+
+What we have done here is configured the source attribute for the hierarchy computation to be `:parent_task` if the task has a `parent_task` set (i.e. it's a subtask), or use `:project` if one is not set (i.e. it's a top level task).
+
+```ruby
+project = Project.create!
+task = Task.create!(project: project)
+sub_task = Task.create!(project: project, parent_task: task)
+
+# These will be true
+task.hierarchy_root == project
+task.hierarchy_parent == project
+project.hierarchy_ancestors_path == 'Project|xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+task.hierarchy_root == project
+task.hierarchy_parent == project
+task.hierarchy_ancestors_path == 'Project|xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/Task|yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy'
+sub_task.hierarchy_root == project
+sub_task.hierarchy_parent == task
+sub_task.hierarchy_ancestors_path == 'Project|xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/Task|yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy/Task|zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz'
+```
+
+### Configuring the separators
+
+By default the separators to use for the path and records are `/` and `|` respectively. This means that a hierarchy path will look something like
+
+```
+<record1_type>|<record1_id>/<record2_type>|<record2_id>
+```
+
+In the event you need to modify the separators used to build the path, you can pass in your desired separators:
+
+```ruby
+class SomeObject
+  include Hierarchable
+  hierarchable parent_source: :parent_object,
+               path_separator: '@@',
+               record_separator: '++'
+  
+  belongs_to :parent_object
+end
+```
+
+Assuming that you set the separators like that for all models, then your path will look something like
+```
+<record1_type>++<record1_id>@@<record2_type>++<record2_id>
+```
+
+CAUTION: When setting custom path and/or record separators, do not use any characters that are likely to be in class/module names such as -, _, :, etc. Otherwise it will not be possible to determine the objects in the path.
+
+# Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/prschmid/hierarchable.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "hierarchable"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/hierarchable.gemspec

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hierarchable/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'hierarchable'
+  spec.version       = Hierarchable::VERSION
+  spec.authors       = ['Patrick R. Schmid']
+  spec.email         = ['prschmid@gmail.com']
+
+  spec.summary       = 'Cross model hierarchical (parent, child, sibling) ' \
+                       'relationship between ActiveRecord models.'
+  spec.description   = 'Cross model hierarchical (parent, child, sibling) ' \
+                       'relationship between ActiveRecord models.'
+  spec.homepage      = 'https://github.com/prschmid/hierarchable'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the
+  # 'allowed_push_host' to allow pushing to a single host or delete this
+  # section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['homepage_uri'] = spec.homepage
+    spec.metadata['source_code_uri'] = 'https://github.com/prschmid/hierarchable'
+    spec.metadata['changelog_uri'] = 'https://github.com/prschmid/hierarchable'
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+          'public gem pushes.'
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added
+  # into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.1'
+
+  spec.add_development_dependency('bundler', '~> 2.3')
+  spec.add_development_dependency('bundler-audit', '>= 0')
+  spec.add_development_dependency('minitest', '~> 5.0')
+  spec.add_development_dependency('rake', '~> 12.3')
+  spec.add_development_dependency('rubocop', '>= 0')
+  spec.add_development_dependency('rubocop-minitest', '>= 0')
+  spec.add_development_dependency('rubocop-performance', '>= 0')
+  spec.add_development_dependency('rubocop-rails', '>= 0')
+  spec.add_development_dependency('rubocop-rake', '>= 0')
+  spec.add_development_dependency('ruby_audit', '>= 0')
+  spec.add_development_dependency('sqlite3', '>= 0')
+  spec.add_development_dependency('temping', '~> 4.0')
+  spec.add_runtime_dependency('activerecord', '> 4.2.0')
+  spec.add_runtime_dependency('activesupport', '> 4.2.0')
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/hierarchable/hierarchable.rb

@@ -0,0 +1,405 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+# All objects that want to make use of this concern must have three columns
+# defined:
+#   hierarchy_root: The root node in the hierarchy hierarchy (polymorphic)
+#   hierarchy_parent: The parent of the current object (polymorphic)
+#   hierarchy_ancestors_path: The string representation of all ancestors of
+#                             the current object (string).
+# The `hierarchy_ancestors_path` column does contain all of the information
+# that is in the `hierarchy_root` and `hierarchy_parent` columns, but those two
+# columns are created for more efficient querying as the direct parent and the
+# root are the most frequent parts of the hierarchy that are needed.
+#
+# To set the attribute that should be used as the parent, one needs to set the
+# `parent_source` value when including this in a model.
+#
+#   class A
+#     include Hierarchable
+#     hierarchable parent_source: :some_column
+#   end
+#
+# If some model doesn't have a parent (e.g. it's the root of the hierarchy)
+# then the `parent_source` can be ommited or explicitly set to `nil`
+#
+#   class B
+#     include Hierarchable
+#     hierarchable parent_source: nil
+#   end
+#
+#   class AlternateB
+#     include Hierarchable
+#     hierarchable
+#   end
+#
+# There are times when the parent is dependent on the state of an object. For
+# example, let's assume that a Project can have tasks, and that tasks can also
+# have tasks (sub tasks). Assuming that the Task model has both `project`
+# and `parent_task` attributes, we could define the parent source dynamically
+# as follows:
+#
+#   class Task
+#     include Hierarchable
+#     hierarchable parent_source: ->(obj) {
+#       obj.parent_task.present ? :parent_task : :project
+#     }
+#   end
+#
+# By default the separators to use for the path and records are / and |
+# respectively. This means that a hierarchy path will look something like
+#
+#   <record1_type>|<record1_id>/<record2_type>|<record2_id>
+#
+# A user can change this default behavior by setting the `path_separator` and/or
+# `record_seprator` option when including this in a class. For example:
+#
+#   class Foo
+#     include Hierarchable
+#     hierachable path_separator: '##', record_separator: '@@'
+#   end
+#
+# CAUTION: When setting custom path and/or record separators, do not use any
+# characters that are likely to be in class/module names such as -, _, :, etc.
+module Hierarchable
+  extend ActiveSupport::Concern
+
+  HIERARCHABLE_DEFAULT_PATH_SEPARATOR = '/'
+  HIERARCHABLE_DEFAULT_RECORD_SEPARATOR = '|'
+
+  class_methods do
+    def hierarchable(opts = {})
+      class_attribute :hierarchable_config
+
+      # Save the configuration
+      self.hierarchable_config = {
+        parent_source: opts.fetch(:parent_source, nil),
+        path_separator: opts.fetch(
+          :path_separator, HIERARCHABLE_DEFAULT_PATH_SEPARATOR
+        ),
+        record_separator: opts.fetch(
+          :record_separator, HIERARCHABLE_DEFAULT_RECORD_SEPARATOR
+        )
+      }
+
+      belongs_to :hierarchy_root, polymorphic: true, optional: true
+
+      belongs_to :hierarchy_parent, polymorphic: true, optional: true
+      alias_method :hierarchy_parent_relationship, :hierarchy_parent
+
+      # Set the parent of the current object. This needs to happen first as
+      # setting the hierarchy_root and the hierarchy_ancestors_path depends on
+      # having the hierarchy_parent set first.
+      before_save :set_hierarchy_parent
+
+      # Based on the hierarchy_parent that is set, set the root. This will take
+      # the hierarchy_root of the hierarchy_parent.
+      before_save :set_hierarchy_root
+
+      # If an object gets moved, we need to ensure that then
+      # hierarchy_ancestors_path is updated to ensure that it stays accurate
+      before_save :update_dirty_hierarchy_ancestors_path,
+                  unless: :new_record?,
+                  if: :hierarchy_parent_changed?
+
+      before_create :set_hierarchy_ancestors_path
+
+      scope :descendants_of,
+            lambda { |object|
+              where(
+                'hierarchy_ancestors_path LIKE :hierarchy_ancestors_path',
+                hierarchy_ancestors_path: "#{object.hierarchy_full_path}%"
+              )
+            }
+
+      scope :siblings_of,
+            lambda { |object|
+              where(
+                'hierarchy_parent_type=:parent_type AND hierarchy_parent_id=:parent_id',
+                parent_type: object.hierarchy_parent.class.name,
+                parent_id: object.hierarchy_parent.id
+              )
+            }
+
+      include InstanceMethods
+    end
+  end
+
+  # Instance methods to include
+  module InstanceMethods
+    def hierarchy_parent(raw: false)
+      return hierarchy_parent_relationship if raw
+
+      # Depending on whether or not the object has been saved or not, we need
+      # to be smart as to how we try to get the parent. If it's saved, then
+      # the `hierarchy_parent` attribute in the model will be set and so we
+      # can use the `belongs_to` relationship to get the parent. However,
+      # if the parent has changed or the object has yet to be saved, we can't
+      # use the relationship to get the parent as the value will not have been
+      # set properly yet in the model (since it's a `before_save` hook).
+      use_relationship = if persisted?
+                           !hierarchy_parent_changed?
+                         else
+                           false
+                         end
+
+      if use_relationship
+        hierarchy_parent_relationship
+      else
+        source = hierarchy_parent_source
+        source.nil? ? nil : send(source)
+      end
+    end
+
+    # Return the attribute name that links this object to its parent.
+    #
+    # This should return the name of the attribute/relation/etc either as a
+    # string or symbol.
+    #
+    # For example, if this is a Task, then the hierarchy_parent_source is
+    # likely the attribute that references the Project this task belongs to.
+    # If the method returns nil (the default behavior), the assumption is that
+    # this object is the root of the hierarchy.
+    def hierarchy_parent_source
+      source = hierarchable_config[:parent_source]
+      return nil unless source
+
+      source.respond_to?(:call) ? source.call(self) : source
+    end
+
+    # Return the string representation of the current object in the format when
+    # used as part of a hierarchy.
+    #
+    # If this is a new record (i.e. not saved yet), this will return "", and
+    # will return the string representation of the format once it is saved.
+    def to_hierarchy_ancestors_path_format
+      return '' if new_record?
+
+      to_hierarchy_format(self)
+    end
+
+    # Return the full hierarchy path from the root to this object.
+    #
+    # Unlike the hierarchy_ancestors_path which DOES NOT include the current
+    # object in the path, this path contains both the ancestors path AND
+    # the current object.
+    def hierarchy_full_path
+      return '' if new_record? ||
+                   !respond_to?(:hierarchy_ancestors_path)
+
+      if hierarchy_ancestors_path.present?
+        format('%<path>s%<sep>s%<current>s',
+               path: hierarchy_ancestors_path,
+               sep: hierarchable_config[:path_separator],
+               current: to_hierarchy_ancestors_path_format)
+      else
+        to_hierarchy_ancestors_path_format
+      end
+    end
+
+    # Return hierarchy path for given list of objects
+
+    def hierarchy_path_for(objects)
+      return '' if objects.blank?
+
+      objects.map do |obj|
+        to_hierarchy_format(obj)
+      end.join(hierarchable_config[:path_separator])
+    end
+
+    def to_hierarchy_format(object)
+      "#{object.class}#{hierarchable_config[:record_separator]}#{object.id}"
+    end
+
+    # Return the full hierarchy path from the root to this object as objects.
+    #
+    # Unlike the hierarchy_full_path that returns a string of the path,
+    # this returns a list of items. The pattern of the returned list will be
+    #
+    #   [Class, Object, Class, Object, ...]
+    #
+    # Where the Class is the class of the object coming right after it. This
+    # representation is useful when creating a breadcrumb and we want to
+    # have both all the ancestors (like in the ancestors method), but also
+    # the collections (classes), so that we can build up a nice path with
+    # links.
+    def hierarchy_full_path_reified
+      return '' if new_record? ||
+                   !respond_to?(:hierarchy_ancestors_path)
+
+      path = []
+      hierarchy_full_path.split(hierarchable_config[:path_separator])
+                         .each do |record|
+        ancestor_class_name, ancestor_id = record.split(
+          hierarchable_config[:record_separator]
+        )
+        ancestor_class = ancestor_class_name.safe_constantize
+        path << ancestor_class
+        path << ancestor_class.find(ancestor_id)
+      end
+      path
+    end
+
+    # Get ancestors of the same type for an object.
+    #
+    # For a given object type, return all ancestors that have the same type.
+    # Note, since ancestors may be of different types, this may skip parts
+    # of the hierarchy if the particular ancestor happens to be of a different
+    # type.
+    def ancestors
+      return [] if !respond_to?(:hierarchy_ancestors_path) ||
+                   hierarchy_ancestors_path.blank?
+
+      a = hierarchy_ancestors_path.split(
+        hierarchable_config[:path_separator]
+      ).map do |ancestor|
+        ancestor_class, ancestor_id = ancestor.split(
+          hierarchable_config[:record_separator]
+        )
+
+        if ancestor_class == self.class.name
+          ancestor_class.safe_constantize.find(ancestor_id)
+        end
+      end
+      a.compact
+    end
+
+    # Return the list of all ancestor objects for the current object
+    #
+    # Using the `hierarchy_ancestors_path`, this will iteratively get all
+    # ancestor objects and return them as a list.
+    #
+    # As there may be ancestors of different types, this is not a single query
+    # and may return things of many different types. E.g. if we have a Project,
+    # Task, and a Comment, the ancestors of a coment may be the Task and the
+    # Project.
+    def all_ancestors
+      return [] if !respond_to?(:hierarchy_ancestors_path) ||
+                   hierarchy_ancestors_path.blank?
+
+      hierarchy_ancestors_path.split(
+        hierarchable_config[:path_separator]
+      ).map do |ancestor|
+        ancestor_class, ancestor_id = ancestor.split(
+          hierarchable_config[:record_separator]
+        )
+        ancestor_class.safe_constantize.find(ancestor_id)
+      end
+    end
+
+    # Get siblings of the same type for an object.
+    #
+    # For a given object type, return all siblings. Note, this DOES NOT return
+    # siblings of different types and those need to be queried separetly.
+    # equivalent to c.hierarchy_parent.children
+    #
+    # Params:
+    # +include_self+:: Whether or not to include self in the list.
+    #                  Default is true
+    def siblings(include_self: true)
+      # The method should always return relation, not an Array sometimes and
+      # Relation the other
+      return self.class.none unless respond_to?(:hierarchy_parent_id)
+
+      query = self.class.where(
+        hierarchy_parent_type: public_send(:hierarchy_parent_type),
+        hierarchy_parent_id: public_send(:hierarchy_parent_id)
+      )
+      query = query.where.not(id:) unless include_self
+      query
+    end
+
+    # Get all siblings of this object regardless of object type.
+    #
+    # This has yet to be implemented and would likely require a separate join
+    # table that has all of the data across all tables linked to the particular
+    # parent. I.e. a simple table that has parent, child in it that we could
+    # use to query.
+    #
+    # Params:
+    # +include_self+:: Whether or not to include self in the list.
+    #                  Default is true
+    def all_siblings
+      raise NotImplementedError
+    end
+
+    protected
+
+    # Set the hierarchy_parent of the current object.
+    #
+    # This will look at the `hierarchy_parent_source` and take the value that
+    # is returned by that method and use it to set the parent. If the parent
+    # is set to `nil`, the assumption is that this object is then the root of
+    # the hierarchy.
+    def set_hierarchy_parent
+      return unless respond_to?(:hierarchy_parent_id)
+      return if hierarchy_parent_source.blank?
+
+      self.hierarchy_parent = public_send(hierarchy_parent_source)
+    end
+
+    # Set the hierarchy_root of the current object.
+    #
+    # This will look at the `hierarchy_parent` and take the `hierarchy_root` of
+    # that object. Since this looks at the `hierarchy_parent`, it is imperative
+    # that the `hierarchy_parent` is set before this method is called.
+    def set_hierarchy_root
+      return unless respond_to?(:hierarchy_root_id) &&
+                    respond_to?(:hierarchy_parent_id)
+
+      parent = hierarchy_parent
+      self.hierarchy_root = if parent.respond_to?(:hierarchy_root)
+                              if parent.hierarchy_root.nil?
+                                parent
+                              else
+                                parent.hierarchy_root
+                              end
+                            else
+                              parent
+                            end
+    end
+
+    # Set the hierarchy_ancestors_path of the current object.
+    #
+    # Based on the hierarchy_parent, this will append the necessary information
+    # to update the hierarchy_ancestors_path
+    def set_hierarchy_ancestors_path
+      return unless respond_to?(:hierarchy_ancestors_path)
+      return unless respond_to?(:hierarchy_parent)
+
+      parent = hierarchy_parent
+      self.hierarchy_ancestors_path = \
+        if parent.nil? || !parent.respond_to?(:hierarchy_ancestors_path)
+          nil
+        elsif parent.hierarchy_ancestors_path.blank?
+          parent.to_hierarchy_ancestors_path_format
+        else
+          format('%<path>s%<sep>s%<current>s',
+                 path: parent.hierarchy_ancestors_path,
+                 sep: hierarchable_config[:path_separator],
+                 current: parent.to_hierarchy_ancestors_path_format)
+        end
+    end
+
+    # Check to see if the hierarchy_parent has changed
+    #
+    # This will take the `hierarchy_parent_source` and check to see if the
+    # current objects's value for the ID corresponding to the
+    # `hierarchy_parent_source` has been updated.
+    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
+    end
+
+    # Update the hierarchy_ancestors_path if the hierarchy has changed.
+    def update_dirty_hierarchy_ancestors_path
+      set_hierarchy_ancestors_path
+    end
+  end
+end

data/lib/hierarchable/version.rb

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

data/lib/hierarchable.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'hierarchable/version'
+require File.join(File.dirname(__FILE__), 'hierarchable', 'hierarchable')
+
+ActiveRecord::Base.instance_eval { include Hierarchable }
+if defined?(Rails) && Rails.version.to_i < 4
+  raise 'This version of hierarchable requires Rails 4 or higher'
+end

metadata

@@ -0,0 +1,261 @@
+--- !ruby/object:Gem::Specification
+name: hierarchable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patrick R. Schmid
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-12-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby_audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: temping
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+description: Cross model hierarchical (parent, child, sibling) relationship between
+  ActiveRecord models.
+email:
+- prschmid@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".circleci/config.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- ".ruby-gemset"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- hierarchable.gemspec
+- lib/hierarchable.rb
+- lib/hierarchable/hierarchable.rb
+- lib/hierarchable/version.rb
+homepage: https://github.com/prschmid/hierarchable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/prschmid/hierarchable
+  source_code_uri: https://github.com/prschmid/hierarchable
+  changelog_uri: https://github.com/prschmid/hierarchable
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Cross model hierarchical (parent, child, sibling) relationship between ActiveRecord
+  models.
+test_files: []