mongoid-sleeping_king_studios 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9872d41d59ce51e97ead17d8219802dd80df2069
-  data.tar.gz: 008ca4394448aa380c101d1aad7b719ca80d7416
+  metadata.gz: cc9bfc29b8eaf26a12fdf6e8779468794c67d352
+  data.tar.gz: a927885e26c3aa375696654acc8d412b96ecc5b6
 SHA512:
-  metadata.gz: 3a8324ecbcdc29f818bf8e2b83b82b48b1df78e1c0ad45938000acf86b388e35fb0eefb8816dfe956b6f63ae8af482aad997f61e352e1a27842060a1c1032c2c
-  data.tar.gz: 67391ada74283759fd019872dbcb2ca97817c72f2e39c35ff52f226fd157529c4917bf436b0165f2b87bd4eabd80ebb90a6a0a5e8904c793d06494f25424e86a
+  metadata.gz: c2913f5069f689cbeedf2d8257096fb88a90755971ea45924771a1e8d3f09c1ed9af2acfd97e57a9e816bceb08b5a083245af455860f6888899d45f9f57b401d
+  data.tar.gz: a0216507421c39e39548b138cb9277a185a0fbd1db69594975e6ecf256fc3e78e4aab7655db2eb45b11584b260354f3e24b588743eb80470accb118ca044da8b

data/README.md

@@ -5,77 +5,87 @@ documents and collections.
 
 ## The Mixins
 
-### Sluggable
+### HasTree
 
-    require 'mongoid/sleeping_king_studios/sluggable'
+    require 'mongoid/sleeping_king_studios/has_tree'
 
-Adds a slug field that automatically tracks a base attribute and stores a
-short, url-friendly version.
+Sets up a basic tree structure by adding belongs_to :parent and has_many
+:children relations, as well as some helper methods.
+
+From 0.2.0 to 0.3.1, was Mongoid::SleepingKingStudios::Tree
 
 **How To Use:**
 
-    class SluggableDocument
+    class TreeDocument
       include Mongoid::Document
-      include Mongoid::SleepingKingStudios::Sluggable
-
-      field :title, :type => String
+      include Mongoid::SleepingKingStudios::HasTree
 
-      slugify :title
+      has_tree
     end # class
 
 #### Options
 
-##### Lockable
+You can pass customisation options for the generated relations into the
+::has\_tree method.
 
-    slugify :title, :lockable => true
-
-Allows the slug to be specified manually. Adds an additional slug_lock field
-that is automatically set to true when #slug= is called. To resume tracking the
-base attribute, set :slug_lock to false.
+    class EvilEmployee
+      include Mongoid::Document
+      include Mongoid::SleepingKingStudios::HasTree
 
-### Tree
+      has_tree :parent => { :relation_name => :overlord },
+        :children => { :relation_name => :minions, :dependent => :destroy }
+    end # class
 
-    require 'mongoid/sleeping_king_studios/tree'
+Available options include the standard Mongoid options for a :belongs_to and a
+:has_many relationship, respectively. In addition, you can set a :relation_name
+option to change the name of the created relation (see example above). The
+concern will automatically update the respective :inverse_of options to match
+the updated relation names.
 
-Sets up a basic tree structure by adding belongs_to :parent and has_many
-:children relations, as well as some helper methods.
+#### Cache Ancestry
 
-**How To Use:**
+Stores the chain of ancestors in an :ancestor_ids array field, and adds the
+\#ancestors and #descendents scopes.
 
-    class TreeDocument
+    class AncestryTree
       include Mongoid::Document
-      include Mongoid::SleepingKingStudios::Tree
+      include Mongoid::SleepingKingStudios::HasTree
+
+      has_tree :cache_ancestry => true
     end # class
 
-#### Options
+**Warning:** using this option will make many write operations much, much
+slower and more resource-intensive. Do not use this option outside of
+read-heavy applications with very specific requirements, e.g. a directory
+structure where you must access all parent directories on each page view.
 
-To customise the created #parent and #children relations, you can define
-::options_for_parent and ::options_for_children class methods before including
-the Tree concern. These methods must return a hash if defined.
+### Sluggable
 
-As of 0.3.1, you can change the name of the class methods used to find the
-customised options by setting Tree.options_for_parent_name and
-Tree.options_for_children_name.
+    require 'mongoid/sleeping_king_studios/sluggable'
 
-    class EvilEmployee
-      include Mongoid::Document
+Adds a slug field that automatically tracks a base attribute and stores a
+short, url-friendly version.
 
-      def self.options_for_parent
-        { :relation_name => :overlord }
-      end # class method options_for_parent
+**How To Use:**
 
-      def self.options_for_children
-        { :relation_name => :minions, :dependent => :destroy }
-      end # class method options_for_children
+    class SluggableDocument
+      include Mongoid::Document
+      include Mongoid::SleepingKingStudios::Sluggable
+
+      field :title, :type => String
 
-      include Mongoid::SleepingKingStudios::Tree
+      slugify :title
     end # class
 
-Available options include the default Mongoid options for a :belongs_to and a
-:has_many relationship, respectively. In addition, you can set a :relation_name
-option to change the name of the created relation (see example above). The
-concern will automatically update the respective :inverse_of options to match
-the updated relation names.
+#### Options
+
+##### Lockable
+
+    slugify :title, :lockable => true
+
+Allows the slug to be specified manually. Adds an additional slug_lock field
+that is automatically set to true when #slug= is called. To resume tracking the
+base attribute, set :slug_lock to false.
 
 ## License
 

data/lib/mongoid/sleeping_king_studios/error.rb

@@ -0,0 +1,9 @@
+# lib/mongoid/sleeping_king_studios/error.rb
+
+require 'mongoid/sleeping_king_studios'
+
+module Mongoid::SleepingKingStudios
+  # Base class for errors thrown by extensions in the
+  # Mongoid::SleepingKingStudios namespace.
+  class Error < StandardError; end
+end # module

data/lib/mongoid/sleeping_king_studios/has_tree.rb

@@ -0,0 +1,169 @@
+# lib/mongoid/sleeping_king_studios/tree.rb
+
+require 'mongoid/sleeping_king_studios'
+require 'mongoid/sleeping_king_studios/has_tree/cache_ancestry'
+
+module Mongoid::SleepingKingStudios
+  # Adds a belongs_to parent relation and a has_many children relation to set
+  # up a basic tree structure, as well as several helper methods.
+  # 
+  # @note From 0.2.0 to 0.3.1, was Mongoid::SleepingKingStudios::Tree.
+  # 
+  # @example Setting up the tree:
+  #   class SluggableDocument
+  #     include Mongoid::Document
+  #     include Mongoid::SleepingKingStudios::Tree
+  # 
+  #     has_tree
+  #   end # class
+  # 
+  # Since 0.4.1, you must call the class method ::has_tree in order to set up
+  # the parent and children relations. You can pass optional parameters into
+  # this method to customise the created relations, including the names of the
+  # relations.
+  # 
+  # @example Setting up the tree with alternate relation names:
+  #   class EvilEmployee
+  #     include Mongoid::Document
+  #     include Mongoid::SleepingKingStudios::Tree
+  #     
+  #     has_tree :parent => { :relation_name => 'overlord' },
+  #       :children => { :relation_name => 'minions', :dependent => :destroy }
+  #   end # class
+  # 
+  # @since 0.2.0
+  module HasTree
+    extend ActiveSupport::Concern
+
+    # Get the valid options allowed with this concern.
+    # 
+    # @return [ Array<Symbol> ] The valid options.
+    #
+    # @since 0.4.1
+    def self.valid_options
+      %i(
+        cache_ancestry
+        children
+        parent
+      ) # end Array
+    end # class method valid_options
+
+    # @!method parent
+    #   Returns the parent object, or nil if the object is a root.
+    # 
+    #   @return [Tree, nil]
+
+    # @!method children
+    #   Returns the list of child objects.
+    # 
+    #   @return [Array<Tree>]
+
+    # Class methods added to the base class via #extend.
+    module ClassMethods
+      # @overload has_tree(options = {})
+      #   Sets up the relations necessary for the tree structure.
+      # 
+      #   @param [Hash] options The options for the relation and the concern as a
+      #     whole.
+      #   @option options [Hash] :parent ({}) The options for the parent
+      #     relation. Supports the :relation_name option, which sets the name of
+      #     the tree's :belongs_to relation, as well as any options normally
+      #     supported by a :belongs_to relation.
+      #   @option options [Hash] :children ({}) The options for the children
+      #     relation. Supports the :relation_name options, which sets the name of
+      #     the tree's :has_many relation, as well as any options normally
+      #     supported by a :has_many relation.
+      #   @option options [Boolean] :cache_ancestry (false) Stores the chain of
+      #     ancestors in an :ancestor_ids array field. Adds the #ancestors and
+      #     #descendents scopes.
+      #
+      #     Warning: using this option will make many write operations much,
+      #     much slower and more resource-intensive. Do not use this option
+      #     outside of read-heavy applications with very specific requirements,
+      #     e.g. a directory structure where you must access all parent
+      #     directories on each page view.
+      # 
+      #   @see Mongoid::SleepingKingStudios::HasTree::CacheAncestry
+      # 
+      #   @raise [ Mongoid::Errors::InvalidOptions ] If the options are invalid.
+      #
+      # @since 0.4.0
+      def has_tree **options
+        validate_options options
+
+        # Create Relations
+        p_opts  = { :relation_name => :parent,   :class_name => self.name }
+        c_opts  = { :relation_name => :children, :class_name => self.name }
+        
+        p_opts.update(options[:parent])   if Hash === options[:parent]
+        c_opts.update(options[:children]) if Hash === options[:children]
+
+        p_opts.update :inverse_of => c_opts[:relation_name]
+        c_opts.update :inverse_of => p_opts[:relation_name]
+        
+        belongs_to p_opts.delete(:relation_name), p_opts
+        has_many   c_opts.delete(:relation_name), c_opts
+
+        options[:parent]   = p_opts
+        options[:children] = c_opts
+
+        # Set Up Ancestry Cache
+        if options.has_key? :cache_ancestry
+          self.send :include, Mongoid::SleepingKingStudios::HasTree::CacheAncestry
+          self.send :cache_ancestry, **options
+        end # if
+
+        self
+      end # class method has_tree
+
+      # Returns a Criteria specifying all root objects, e.g. objects with no
+      # parent object.
+      # 
+      # @return [Mongoid::Criteria]
+      def roots
+        where({ :parent_id => nil })
+      end # scope routes
+
+      private
+
+      # Determine if the provided options are valid for the concern.
+      #
+      # @param [ Hash ] options The options to check.
+      #
+      # @raise [ Mongoid::Errors::InvalidOptions ] If the options are invalid.
+      def validate_options options
+        valid_options = Mongoid::SleepingKingStudios::HasTree.valid_options
+        options.keys.each do |key|
+          if !valid_options.include?(key)
+            raise Mongoid::Errors::InvalidOptions.new(
+              :has_tree,
+              key,
+              valid_options
+            ) # end InvalidOptions
+          end # if
+        end # each
+      end # class method validate_options
+    end # module
+
+    # Returns the root object of the current object's tree.
+    # 
+    # @return [Tree]
+    def root
+      parent ? parent.root : self
+    end # method root
+
+    # Returns true if the object is a leaf object, e.g. has no child objects.
+    # 
+    # @return [Boolean] True if the object has no children; otherwise false.
+    def leaf?
+      children.empty?
+    end # method leaf?
+
+    # Returns true if the object is a root object, e.g. has no parent object.
+    # 
+    # @return [Boolean] True if the object has no parent; otherwise false.
+    def root?
+      parent.nil?
+    end # method root?
+  end # module
+end # module

data/lib/mongoid/sleeping_king_studios/has_tree/cache_ancestry.rb

@@ -0,0 +1,150 @@
+# lib/mongoid/sleeping_king_studios/has_tree/cache_ancestry.rb
+
+require 'mongoid/sleeping_king_studios'
+require 'mongoid/sleeping_king_studios/has_tree/errors'
+
+module Mongoid::SleepingKingStudios
+  module HasTree
+    # Adds #ancestors and #descendents methods for accessing ancestors and
+    # subtrees with a single read operation. Do not include this module
+    # directly; rather, add a :cache_ancestry => true options to the call
+    # to ::has_tree.
+    # 
+    # @example Setting up a tree with ancestry cache:
+    #   class SluggableDocument
+    #     include Mongoid::Document
+    #     include Mongoid::SleepingKingStudios::Tree
+    # 
+    #     has_tree :cache_ancestry => true
+    #   end # class
+    # 
+    # @since 0.5.0
+    module CacheAncestry
+      extend ActiveSupport::Concern
+
+      # @!attribute [r] ancestor_ids
+      #   Stores the ids of the object's ancestors, starting from the root
+      #   object of the current subtree to the object's current parent. If
+      #   the object has no parent, returns an empty array.
+      # 
+      #   @return [Array] The ancestors' ids.
+      # 
+      #   @since 0.5.0
+
+      # Class methods added to the base class via #extend.
+      module ClassMethods
+        # @overload cache_ancestry()
+        #   Adds the :ancestry_id field, the #ancestors and #descendents
+        #   scopes, and redefines #parent_id= to update the :ancestry_id
+        #   field on the object and its descendents.
+        # 
+        #   Do not call this method directly; rather, add a
+        #   :cache_ancestry => true options to the call to ::has_tree.
+        def cache_ancestry **options
+          parent_name   = options[:children][:inverse_of]
+          children_name = options[:parent][:inverse_of]
+
+          field :ancestor_ids, :type => Array, :default => []
+
+          alias_method :"set_parent_id", :"#{parent_name}_id="
+          private :set_parent_id
+          re_define_method "#{parent_name}_id=" do |value|
+            old_ancestor_ids = ancestor_ids.dup
+
+            set_parent_id value
+            new_ancestor_ids = parent ? parent.ancestor_ids + [parent.id] : []
+
+            descendents.each do |descendent|
+              ary = descendent.ancestor_ids.dup
+              ary[0..old_ancestor_ids.count] = new_ancestor_ids + [id]
+              descendent.update_attributes :ancestor_ids => ary
+            end # each
+            
+            self.send :ancestor_ids=, new_ancestor_ids
+          end # method #{parent_name}_id=
+        end # class method cache_ancestry
+      end # module ClassMethods
+
+      # Returns an array of the current object's ancestors, from the root
+      # object to the current parent. If the object has no parent, returns an
+      # empty array. If an error is raised, consider calling #rebuild_ancestry!
+      # 
+      # @raise [Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor]
+      #   If one or more of the ancestors is not found in the datastore (the id
+      #   is wrong, the object is not persisted, there is a nil value in
+      #   ancestor_ids, and so on).
+      # 
+      # @return [Array] The objects' ancestors
+      def ancestors
+        self.class.find(ancestor_ids)
+      rescue Mongoid::Errors::DocumentNotFound, Mongoid::Errors::InvalidFind
+        raise Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor.new ancestor_ids
+      end # method ancestors
+
+      # Returns a scope for all of the descendents of the current object, i.e.
+      # all objects that have the current object as an ancestor.
+      # 
+      # @return [Mongoid::Criteria] The criteria for finding the descendents.
+      def descendents
+        criteria = self.class.all
+
+        ancestor_ids.each_with_index do |ancestor_id, index|
+          criteria = criteria.where(:"ancestor_ids.#{index}" => ancestor_id)
+        end # each
+
+        criteria.where(:"ancestor_ids.#{ancestor_ids.count}" => id)
+      end # scope descendents
+
+      # Travels up the tree using the #parent method and saves the ancestors to
+      # the :ancestor_ids field. This overwrites the value of :ancestor_ids on
+      # the current object, but not on any of its ancestors.
+      # 
+      # @raise [Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor]
+      #   If the current object or an ancestor has an invalid #parent.
+      def rebuild_ancestry!
+        ary, object = [], self
+        while object.parent
+          ary.unshift object.parent.id
+          object = object.parent
+        end # while
+        self.send :ancestor_ids=, ary
+      rescue Mongoid::Errors::DocumentNotFound
+        raise Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor.new object.parent_id
+      end # method rebuild_ancestry!
+
+      # Travels up the tree using the :ancestor_ids and ensures that each
+      # ancestor exists and is persisted to the database, and that the
+      # object's parent correctly matches the last value in its own
+      # :ancestor_ids field.
+      # 
+      # @raise [Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor]
+      #   If any of the ancestors is not found in the datastore (the id is
+      #   wrong, the object is not persisted, there is a nil value in
+      #   ancestor_ids, and so on).
+      #
+      # @raise [Mongoid::SleepingKingStudios::HasTree::Errors::UnexpectedAncestor]
+      #   If there is a mismatch between an object's #parent and the last value
+      #   in the object's :ancestor_ids field.
+      def validate_ancestry!
+        return if ancestor_ids.empty?
+
+        ancestors = []
+        ancestor_ids.each_with_index do |ancestor_id, index|
+          begin
+            ancestor = self.class.find(ancestor_id)
+            ancestors << ancestor
+
+            if index > 0 && ancestor.parent_id != ancestor_ids[index - 1]
+              # If the ancestor's parent is not the same as the previous
+              # ancestor.
+              raise Mongoid::SleepingKingStudios::HasTree::Errors::UnexpectedAncestor.new ancestor.parent_id, ancestor_ids[index - 1]
+            end # if
+          rescue Mongoid::Errors::InvalidFind, Mongoid::Errors::DocumentNotFound
+            # If the ancestor id is nil, or the ancestor does not exist.
+            raise Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor.new ancestor_id
+          end # begin-rescue
+        end # each
+      end # method validate_ancestry!
+    end # module
+  end # module
+end # module

data/lib/mongoid/sleeping_king_studios/has_tree/errors.rb

@@ -0,0 +1,24 @@
+# lib/mongoid/sleeping_king_studios/has_tree/errors.rb
+
+require 'mongoid/sleeping_king_studios/error'
+
+module Mongoid::SleepingKingStudios
+  module HasTree
+    module Errors
+      class MissingAncestor < Mongoid::SleepingKingStudios::Error
+        def initialize ancestor_id
+          message = Array === ancestor_id ?
+            'ancestors with ids' :
+            'ancestor with id'
+          super "unable to find #{message} #{ancestor_id.inspect}"
+        end # constructor
+      end # class
+
+      class UnexpectedAncestor < Mongoid::SleepingKingStudios::Error
+        def initialize expected_id, received_id
+          super "expected ancestor with id #{expected_id.inspect}, but received id #{received_id.inspect}"
+        end # constructor
+      end # class
+    end # module Errors
+  end # module
+end # module

data/lib/mongoid/sleeping_king_studios/version.rb

@@ -2,6 +2,6 @@
 
 module Mongoid
   module SleepingKingStudios
-    VERSION = '0.3.1'
+    VERSION = '0.5.0'
   end # module
 end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoid-sleeping_king_studios
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
@@ -146,8 +146,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/mongoid/sleeping_king_studios/error.rb
+- lib/mongoid/sleeping_king_studios/has_tree/cache_ancestry.rb
+- lib/mongoid/sleeping_king_studios/has_tree/errors.rb
+- lib/mongoid/sleeping_king_studios/has_tree.rb
 - lib/mongoid/sleeping_king_studios/sluggable.rb
-- lib/mongoid/sleeping_king_studios/tree.rb
 - lib/mongoid/sleeping_king_studios/version.rb
 - lib/mongoid/sleeping_king_studios.rb
 - LICENSE

data/lib/mongoid/sleeping_king_studios/tree.rb

@@ -1,126 +0,0 @@
-# lib/mongoid/sleeping_king_studios/tree.rb
-
-require 'mongoid/sleeping_king_studios'
-
-module Mongoid::SleepingKingStudios
-  # Adds a belongs_to parent relation and a has_many children relation to set
-  # up a basic tree structure, as well as several helper methods.
-  # 
-  # @example Setting up the tree:
-  #   class SluggableDocument
-  #     include Mongoid::Document
-  #     include Mongoid::SleepingKingStudios::Tree
-  #   end # class
-  # 
-  # Since 0.3.0, you can customise the generated :parent and :children
-  # relations by defining optional class methods ::options_for_parent and
-  # ::options_for_children, which must return hashes of valid options. These
-  # must be defined prior to including this mixin, or the default options will
-  # be applied instead.
-  # 
-  # In addition, you can customise the names of the relations by adding a
-  # :relation_name key to either ::options_for hash. The concern will
-  # automatically update the respective :inverse_of options to match the
-  # updated relation names.
-  # 
-  # Since 0.3.1, you can additionally customise the name of the class methods
-  # used to determine the customised options by changing the value of
-  # Tree.options_for_parent_name and Tree.options_for_children_name.
-  # 
-  # @example Setting up the tree with alternate relation names:
-  #   class EvilEmployee
-  #     include Mongoid::Document
-  # 
-  #     def self.options_for_parent
-  #       { :relation_name => "overlord" }
-  #     end # class method options_for_parent
-  # 
-  #     def self.options_for_children
-  #       { :relation_name => "minions", :dependent => :destroy }
-  #     end # class method options_for_children
-  # 
-  #     include Mongoid::SleepingKingStudios::Tree
-  #   end # class
-  # 
-  # @since 0.2.0
-  module Tree
-    extend ActiveSupport::Concern
-
-    class << self
-      # Gets the name of the method on the base module that is used to find
-      # customisation options for the :parent relation.
-      # 
-      # @return [Symbol] By default, returns :options_for_parent.
-      # 
-      # @since 0.3.1
-      attr_accessor :options_for_parent_name
-
-      # Gets the name of the method on the base module that is used to find
-      # customisation options for the :children relation.
-      # 
-      # @return [Symbol] By default, returns :options_for_children.
-      # 
-      # @since 0.3.1
-      attr_accessor :options_for_children_name
-    end # class << self
-
-    self.options_for_parent_name   = :options_for_parent
-    self.options_for_children_name = :options_for_children
-
-    # @!method parent
-    #   Returns the parent object, or nil if the object is a root.
-    # 
-    #   @return [Tree, nil]
-
-    # @!method children
-    #   Returns the list of child objects.
-    # 
-    #   @return [Array<Tree>]
-
-    included do |base|
-      p_opts = { :relation_name => :parent,   :class_name => base.name }
-      c_opts = { :relation_name => :children, :class_name => base.name }
-      
-      p_opts.update(send Tree.options_for_parent_name)   if respond_to?(Tree.options_for_parent_name)
-      c_opts.update(send Tree.options_for_children_name) if respond_to?(Tree.options_for_children_name)
-
-      p_opts.update :inverse_of => c_opts[:relation_name]
-      c_opts.update :inverse_of => p_opts[:relation_name]
-      
-      belongs_to p_opts.delete(:relation_name), p_opts
-      has_many   c_opts.delete(:relation_name), c_opts
-    end # included
-
-    # Class methods added to the base class via #extend.
-    module ClassMethods
-      # Returns a Criteria specifying all root objects, e.g. objects with no
-      # parent object.
-      # 
-      # @return [Mongoid::Criteria]
-      def roots
-        where({ :parent_id => nil })
-      end # scope routes
-    end # module
-
-    # Returns the root object of the current object's tree.
-    # 
-    # @return [Tree]
-    def root
-      parent ? parent.root : self
-    end # method root
-
-    # Returns true if the object is a leaf object, e.g. has no child objects.
-    # 
-    # @return [Boolean] True if the object has no children; otherwise false.
-    def leaf?
-      children.empty?
-    end # method leaf?
-
-    # Returns true if the object is a root object, e.g. has no parent object.
-    # 
-    # @return [Boolean] True if the object has no parent; otherwise false.
-    def root?
-      parent.nil?
-    end # method root?
-  end # module
-end # module