mongoid-sleeping_king_studios 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fdd1c69e257d2151ecdb439fc1f9ab974628c9ba
-  data.tar.gz: cf273c392e0fde12e79b244819c1c880de8e11dd
+  metadata.gz: 218763356e4b6bc56393162ae45be295d7ccc478
+  data.tar.gz: 3fa4cfd1063e65e22322c5be1b183a6f04f10fc7
 SHA512:
-  metadata.gz: 0e20060ad75456272818d391425dad43a7deca8babe64f104a586a946221db0aa0e57d227bb16acee3ac7a3921d272a12d8da2bde3a4d2794b85a6f8233965b8
-  data.tar.gz: 6ab47ee0aed555756fd7ab7dadabe617985abe5c32d61efc1e4374546427abc0afebcb60185c84dfe50b87e083f8ca8ec10038120cc8480cca4adfdf7a54c8bf
+  metadata.gz: 1c2f385e2cc2184c33009e5907a15b8b052780dfbe90345dfa3bc9679a637e955df9acac88f2d429a207d53ba738d491db5d8ab491b2e4fa170b95f885803367
+  data.tar.gz: 7b579653a20b03b32db94736019d9c0caec715884948b9eff640397cae9d518c3f364d47c25e09a4bb2795151531f7f35316940aca01ee01629b1a4dd3c669d0

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.7.0
+
+* Add Orderable concern.
+
 ## 0.6.2
 
 * Update dependencies (no user-facing changes).

data/README.md

@@ -77,6 +77,58 @@ 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.
 
+### Orderable
+
+    require 'mongoid/sleeping_king_studios/orderable'
+
+Adds a field that tracks the index of each record with respect to the provided
+sort order parameters.
+
+**How To Use:**
+
+    class OrderedDocument
+      include Mongoid::Document
+      include Mongoid::SleepingKingStudios::Orderable
+
+      cache_ordering :created_at.desc, :as => :most_recent_order
+    end # class
+
+The ::cache_ordering method accepts a subset of the params for an Origin
+\#order_by query operation, e.g.:
+
+- :first_field.desc, :second_field
+- { :first_field => -1, :second_field => :asc }
+- [[:first_field, :desc], [:second_field, 1]]
+
+#### Helpers
+
+Creating an ordering cache also creates the following helpers:
+
+##### ::reorder_ordering_name!
+
+Loops through the collection and sets each item's field to the appropriate
+ordered index. Normally, this is handled on item save, but this helper allows
+a bulk update of the collection when adding the concern to an existing model,
+or if data corruption or other issues have broken the existing values.
+
+#### Options
+
+##### As
+
+    cache_ordering sort_params, :as => :named_order
+
+Sets the name of the generated order field and helpers. If no name is 
+specified, one will be automatically generated of the form 
+first_field_desc_second_field_asc_order.
+
+##### Filter
+
+    cache_ordering sort_params, :filter => { :published => true }
+
+Restricts which records from the collection will be sorted to generate the
+ordering values. If a record is filtered out, its ordering field will be set 
+to nil.
+
 ### Sluggable
 
     require 'mongoid/sleeping_king_studios/sluggable'

data/lib/mongoid/sleeping_king_studios/orderable.rb

@@ -0,0 +1,172 @@
+# lib/mongoid/sleeping_king_studios/orderable.rb
+
+require 'mongoid/sleeping_king_studios/orderable/metadata'
+
+module Mongoid::SleepingKingStudios
+  # Adds an order field that stores the index of the record relative to the
+  # specified sort query. Storing the order in this fashion allows, for
+  # example, finding the next or previous records in the set without needing to
+  # perform the full sort query each time.
+  # 
+  # @example Order by Most Recently Created:
+  #   class SortedDocument
+  #     include Mongoid::Document
+  #     include Mongoid::SleepingKingStudios::Ordering
+  # 
+  #     cache_ordering :created_at.desc, :as => :most_recent_order
+  #   end # class
+  # 
+  # @see ClassMethods#cache_ordering
+  # 
+  # @since 0.7.0
+  module Orderable
+    extend ActiveSupport::Concern
+    extend Mongoid::SleepingKingStudios::Concern
+
+    # @api private
+    # 
+    # Sets up the orderable relation, creating fields, callbacks and helper
+    # methods.
+    # 
+    # @param [Class] base The base class into which the concern is mixed in.
+    # @param [Symbol, Array, Hash] sort_params The params used to sort the
+    #   collection, generating the cached order index.
+    # @param [Hash] options The options for the relation.
+    def self.apply base, sort_params, options
+      name = :orderable
+      validate_options    name, options
+      options.update :sort_params => sort_params
+      meta = characterize name, options, Metadata
+
+      relate base, name, meta
+
+      define_fields    base, meta
+      define_callbacks base, meta
+      define_helpers   base, meta
+    end # module method apply
+
+    # @api private
+    # 
+    # Creates an order field of type Integer on the base class, and sets the
+    # writer to private.
+    # 
+    # @param [Class] base The base class into which the concern is mixed in.
+    # @param [Metadata] metadata The metadata for the relation.
+    def self.define_fields base, metadata
+      base.send :field,   metadata.field_name, :type => Integer
+
+      base.send :private, metadata.field_writer
+    end # module method define_fields
+
+    # @api private
+    # 
+    # Adds an after_save callback to update the index of the record and all
+    # subsequent records in the ordering.
+    # 
+    # @param [Class] base The base class into which the concern is mixed in.
+    # @param [Metadata] metadata The metadata for the relation.
+    def self.define_callbacks base, metadata
+      base.after_save do
+        criteria    = metadata.sort_criteria(base)
+        ordering    = criteria.to_a
+        order_index = ordering.index(self)
+
+        if order_index.nil?
+          if send(metadata.field_was).nil?
+            # Both the old and new values are nil, so mission accomplished.
+            return
+          else
+            # The old value wasn't nil, so remember it and set the new value,
+            # then start looping through the ordered collection at the old
+            # value.
+            order_index = send(metadata.field_was)
+
+            # Update the current instance.
+            self[metadata.field_name] = nil
+
+            # Set the value in the datastore.
+            set(metadata.field_name => order_index)
+          end # unless
+        else
+          # Update the current instance.
+          self[metadata.field_name] = order_index
+        end # if
+
+        ordering[order_index..-1].each_with_index do |object, i|
+          object.set(metadata.field_name => (order_index + i))
+        end # each
+      end # callback
+    end # module method define_callbacks
+
+    # @api private
+    #
+    # Adds a class-level reorder! helper that loops through the entire
+    # collection and updates the ordering of each item.
+    # 
+    # @param [Class] base The base class into which the concern is mixed in.
+    # @param [Metadata] metadata The metadata for the relation.
+    def self.define_helpers base, metadata
+      name = :"reorder_#{metadata.field_name.to_s.gsub(/_order\z/,'')}!"
+      meta = class << base; self; end
+      meta.send :define_method, name do
+        base.update_all(metadata.field_name => nil)
+        
+        criteria = metadata.sort_criteria(base)
+        ordering = criteria.to_a
+
+        ordering.each_with_index do |record, index|
+          record.set(metadata.field_name => index)
+        end # each
+      end # method
+    end # module method define_helpers
+
+    # Returns a list of options that are valid for this concern.
+    # 
+    # @return [Array<Symbol>] The list of valid options.
+    def self.valid_options
+      super + %i(
+        as
+        filter
+      ) # end array
+    end # module method valid options
+
+    # Class methods added to the base class via #extend.
+    module ClassMethods
+      # @overload cache_ordering sort_params, options = {}
+      #   Creates the order field and sets up the callbacks and helpers.
+      # 
+      #   @param [Array] sort_params The sort query used to order the
+      #     collection. Accepts a subset of the options for a default
+      #     Origin sort operation:
+      #     - :field_name.desc, :another_field
+      #     - { :field_name => -1, :another_field => 1 }
+      #     - \[[:field_name, -1], [:another_field, :asc]]
+      #   @param [Hash] options The options for the relation.
+      #   @option options [Symbol] :as
+      #     Sets the name of the generated field and helpers. By default,
+      #     uses the name(s) and direction(s) of the fields from the sort
+      #     query, e.g. :field_name_asc_another_field_desc_order.
+      #   @option options [Hash] :filter
+      #     Sets a filter that excludes collection items from the ordering
+      #     process. Accepts the same parameters as a Mongoid #where query.
+      # 
+      #   @raise [Mongoid::Errors::InvalidOptions] If any of the provided
+      #     options are invalid.
+      def cache_ordering *sort_params, **options
+        concern = Mongoid::SleepingKingStudios::Orderable
+        concern.apply self, sort_params, options
+      end # class method slugify
+
+      # @!method reorder_ordering_name!
+      #   Iterates through the entire collection and sets the cached order of
+      #   each item to its current order index. Filtered items have their order
+      #   set to nil. Normally, this should be taken care of when the items are
+      #   saved, but this method allows the process to be reset in case of data
+      #   corruption or other issues.
+      # 
+      #   The generated name of this method will depend on the sort params or
+      #   the :as option provided. For example, :as => :alphabetical_order will
+      #   result in a class method ::reorder_alphabetical!
+    end # module
+  end # module
+end # module

data/lib/mongoid/sleeping_king_studios/orderable/metadata.rb

@@ -0,0 +1,111 @@
+# lib/mongoid/sleeping_king_studios/orderable/metadata.rb
+
+require 'mongoid/sleeping_king_studios/concern/metadata'
+
+module Mongoid::SleepingKingStudios
+  module Orderable
+    # Stores information about an Orderable concern.
+    class Metadata < Mongoid::SleepingKingStudios::Concern::Metadata
+      # @param [Symbol, String] name The name of the concern or relation.
+      # @param [Hash] properties The properties of the concern or relation.
+      def initialize name, properties = {}
+        super
+
+        self[:sort_params] = case properties[:sort_params]
+        when Array
+          properties[:sort_params].reduce({}) do |hsh, param|
+            hsh.merge parse_sort_param(param)
+          end # each
+        when Hash
+          properties[:sort_params].each.with_object({}) do |(key, value), hsh|
+            hsh[key] = parse_sort_direction(value)
+          end # each
+        when Symbol, Origin::Key
+          parse_sort_param(properties[:sort_params])
+        end # case
+      end # method initialize
+
+      # The name of the field used to store the order.
+      #
+      # @return [Symbol] The field name.
+      def field_name
+        fetch(:as, default_field_name).intern
+      end # method field_name
+
+      # @return [Boolean] True if a custom field name is defined; otherwise
+      # false.
+      def field_name?
+        !!self[:as]
+      end # method field_name
+
+      # The name of the dirty tracking method for the order field.
+      # 
+      # @return [Symbol] The method name.
+      def field_was
+        :"#{field_name}_was"
+      end # method field_was
+
+      # The name of the writer for the order field.
+      # 
+      # @return [Symbol] The method name.
+      def field_writer
+        :"#{field_name}="
+      end # method field_writer
+
+      # The criteria to filter only the desired collection items to sort.
+      # 
+      # @param [Mongoid::Criteria] criteria The base criteria to modify using
+      #   the filter params.
+      # 
+      # @return [Mongoid::Criteria]
+      def filter_criteria criteria
+        filter_params? ? criteria.where(filter_params) : criteria
+      end # method filter_criteria
+
+      # The options (if any) to filter the collection by prior to sorting.
+      # 
+      # @return [Hash]
+      def filter_params
+        self[:filter]
+      end # method filter_params
+
+      # @return [Boolean] True if filter params are defined; otherwise false.
+      def filter_params?
+        !!self[:filter]
+      end # method filter_params?
+
+      # The criteria to be used when sorting the collection.
+      # 
+      # @param [Mongoid::Criteria] criteria The base criteria to modify using
+      #   the sort params.
+      # 
+      # @return [Mongoid::Criteria]
+      def sort_criteria criteria
+        filter_criteria(criteria).order_by(self[:sort_params])
+      end # method sort_criteria
+
+      private
+
+      def default_field_name
+        self[:sort_params].map { |key, value|
+          "#{key}_#{value == 1 ? 'asc' : 'desc'}"
+        }.join('_') + '_order'
+      end # method default_field_name
+
+      def parse_sort_param param
+        case param
+        when Array
+          { param[0] => parse_sort_direction(param[1]) }
+        when Origin::Key
+          { param.name => param.operator }
+        when Symbol
+          { param => 1 }
+        end # case
+      end # method sort_param=
+
+      def parse_sort_direction direction
+        (direction == -1 || direction.to_s.downcase == 'desc') ? -1 : 1
+      end # method parse_sort_direction
+    end # class
+  end # module
+end # module

data/lib/mongoid/sleeping_king_studios/version.rb

@@ -3,6 +3,6 @@
 module Mongoid
   module SleepingKingStudios
     # The current version of the gem.
-    VERSION = '0.6.2'
+    VERSION = '0.7.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.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
@@ -122,6 +122,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: |2
       A collection of concerns and extensions to add functionality to Mongoid
       documents and collections. The features can be included individually or by
@@ -143,6 +157,8 @@ files:
 - lib/mongoid/sleeping_king_studios/has_tree/metadata.rb
 - lib/mongoid/sleeping_king_studios/has_tree/parent/metadata.rb
 - lib/mongoid/sleeping_king_studios/has_tree.rb
+- lib/mongoid/sleeping_king_studios/orderable/metadata.rb
+- lib/mongoid/sleeping_king_studios/orderable.rb
 - lib/mongoid/sleeping_king_studios/sluggable/metadata.rb
 - lib/mongoid/sleeping_king_studios/sluggable.rb
 - lib/mongoid/sleeping_king_studios/version.rb