moribus 0.0.1

data/lib/moribus/aggregated_behavior.rb

@@ -0,0 +1,80 @@
+module Moribus
+  # Adds aggregated behavior to a model. An aggregated model tries to insure
+  # it will not duplicate itself for whatever parents it belongs to. Whenever
+  # an aggregated model is about to be saved, it uses its attributes to
+  # perform a lookup for an existing record with the same attributes. If the
+  # lookup succeeds, its id is used to replace id of model being saved, and
+  # no 'INSERT' statement is executed. If the lookup fails, the original AR
+  # save routines are performed.
+  #
+  # This behavior ignores by default the columns it doesn't consider to
+  # contain content such as the ones created and used by ActiveRecord. These
+  # can be expanded through the API:
+  # @example:
+  #   acts_as_aggregated :non_content_columns => %w(some other colums)
+  module AggregatedBehavior
+    extend ActiveSupport::Concern
+
+    included do
+      # specifies a list of attributes to exclude from lookup
+      class_attribute :aggregated_behaviour_non_content_columns, :instance_writer => false
+      self.aggregated_behaviour_non_content_columns = %w(id created_at updated_at lock_version)
+    end
+
+    # Override the original AR::Base #save method with the aggregated
+    # behavior. This cannot be done using a before_save callback, because, if
+    # the lookup succeeds, we don't want the original #save to be executed.
+    # But if +false+ is returned by the callback, it will also be returned
+    # by the #save method, wrongly indicating the result of saving.
+    def save(*)
+      @updated_as_aggregated = false
+      run_callbacks(:save) do
+        return (lookup_self_and_replace or super) if new_record?
+
+        is_any_content_attr_changed =
+          attributes.except(*aggregated_behaviour_non_content_columns).keys.
+            any?{ |attr| attribute_changed?(attr) }
+
+        if is_any_content_attr_changed
+          to_new_record!
+          lookup_self_and_replace or return super
+
+          true
+        else
+          super
+        end
+      end
+    end
+
+    # Bang version of #save.
+    def save!(*args)
+      save(*args) or raise ActiveRecord::RecordNotSaved
+    end
+
+    # Use the +lookup_relation+ to get the very first existing record that
+    # corresponds to +self+.
+    def lookup_self
+      lookup_relation.first
+    end
+    private :lookup_self
+
+    # Use the attributes of +self+ to generate a relation that corresponds to
+    # the existing record in the table with the same attributes.
+    def lookup_relation
+      self.class.unscoped.where(attributes.except(*aggregated_behaviour_non_content_columns))
+    end
+    private :lookup_relation
+
+    # If #lookup_self successfully returns a record, 'replace' +self+ by it
+    # (using its id, created_at, updated_at values).
+    def lookup_self_and_replace
+      @updated_as_aggregated = true
+      existing               = lookup_self
+
+      if existing.present? then
+        to_persistent!(existing)
+      end
+    end
+    private :lookup_self_and_replace
+  end
+end

data/lib/moribus/aggregated_cache_behavior.rb

@@ -0,0 +1,76 @@
+module Moribus
+  # This module provides additional in-memory caching for model that
+  # behaves in aggregated way. For that reason, <tt>:aggregated_records_cache</tt>
+  # hash class instance variable is added, and the <tt>@aggregated_caching_column</tt>
+  # class instance variable should be defined by class. The value of
+  # corresponding attribute of the model is used as a cache key.
+  #
+  # The original +lookup_self+ method is overloaded to lookup in cache
+  # first. If this lookup fails, native aggregated routines are performed
+  # and resulting record is added to the cache.
+  #
+  # Please note that this module is not to be included manually. Use
+  # class-level +acts_as_aggregated+ instead, supplied with an <tt>:cache_by</tt>
+  # option:
+  #
+  #   class EmailDomain < ActiveRecord::Base
+  #     acts_as_aggregated :cache_by => :domain
+  #     # .. rest of definition
+  #   end
+  module AggregatedCacheBehavior
+    extend ActiveSupport::Concern
+
+    # Raised when trying to include the module to a non-aggregated model.
+    NotAggregatedError = Class.new(::ArgumentError)
+
+    included do
+      unless self < AggregatedBehavior
+        raise NotAggregatedError, 'AggregatedCache can be used only in Aggregated models'
+      end
+
+      class_attribute :aggregated_records_cache
+      self.aggregated_records_cache = {}
+
+      after_save :cache_aggregated_record, :on => :create
+    end
+
+    # Class methods for model that includes AggregatedCacheBehavior
+    module ClassMethods
+      # Empty the cache of aggregated records.
+      def clear_cache
+        self.aggregated_records_cache = {}
+      end
+
+      # Return the column (attribute). Its value is used as a key for
+      # caching records.
+      def aggregated_caching_column
+        @aggregated_caching_column
+      end
+    end
+
+    # Overridden for caching support.
+    def lookup_self
+      cache = self.class.aggregated_records_cache
+      cache_by = caching_attribute
+      return cache[cache_by] if cache.key? cache_by
+      lookup_result = super
+      cache[cache_by] = lookup_result if lookup_result
+      lookup_result
+    end
+    private :lookup_self
+
+    # Cache the record.
+    def cache_aggregated_record
+      cache_by = caching_attribute
+      self.class.aggregated_records_cache[cache_by] = dup.tap{ |d| d.to_persistent!(self); d.freeze }
+    end
+    private :cache_aggregated_record
+
+    # Return the value of the caching column (attribute) used as a key of
+    # the records cache.
+    def caching_attribute
+      read_attribute(self.class.aggregated_caching_column)
+    end
+    private :caching_attribute
+  end
+end

data/lib/moribus/alias_association.rb

@@ -0,0 +1,106 @@
+module Moribus
+  # When included, adds alias_association public class method for aliasing
+  # specific association. Association name and association-specific methods
+  # will be aliased. Example:
+  #
+  #   class Customer
+  #     belongs_to :person_name
+  #     has_many :orders
+  #     alias_association :name, :person_name
+  #     alias_association :bookings, :orders
+  #   end
+  #
+  #   Customer.reflect_on_association(:name) # => #<ActiveRecord::Reflection::AssociationReflection ...>
+  #   c = Customer.includes(:bookings).first
+  #   c.booking_ids # => [1, 2, 3]
+  #   c.build_name(:first_name => 'John', :last_name => 'Smith') # => #<PersonName ...>
+  module AliasAssociation
+    extend ActiveSupport::Concern
+
+    # Class methods for ActiveRecord::Base
+    module ClassMethods
+      # Aliases association reflection in reflections hash and
+      # association-specific methods. See module description for example
+      def alias_association(alias_name, association_name)
+        if reflection = reflect_on_association(association_name)
+          reflections[alias_name] = reflections[association_name]
+          alias_association_methods(alias_name, reflection)
+          reflection
+        end
+      end
+
+      # Allows :alias option to alias belongs_to association
+      def belongs_to(name, opts = {})
+        alias_name = opts.delete(:alias)
+        reflection = super(name, opts)
+        alias_association(alias_name, name) if alias_name
+        reflection
+      end
+
+      # Allows :alias option to alias has_many association
+      def has_many(name, opts = {})
+        alias_name = opts.delete(:alias)
+        reflection = super(name, opts)
+        alias_association(alias_name, name) if alias_name
+        reflection
+      end
+
+      # Allows :alias option to alias has_one association
+      def has_one(name, opts = {})
+        alias_name = opts.delete(:alias)
+        reflection = super(name, opts)
+        alias_association(alias_name, name) if alias_name
+        reflection
+      end
+
+
+      # Aliases association methods for a given association reflections: creates
+      # association accessors aliases (such as <tt>other</tt> and <tt>other=</tt>),
+      # also aliases association-specific methods(such as <tt>build_other</tt> and
+      # <tt>create_other</tt> for singular association, and <tt>other_ids</tt> and
+      # <tt>other_ids=</tt> for collection association)
+      def alias_association_methods(alias_name, reflection)
+        association_name = reflection.name
+        alias_association_accessor_methods(alias_name, association_name)
+        case reflection.macro
+          when :has_one, :belongs_to
+            alias_singular_association_methods(alias_name, association_name)
+          when :has_many, :has_and_belongs_to_many
+            alias_collection_association_methods(alias_name, association_name)
+        end
+      end
+      private :alias_association_methods
+
+      # Aliases association accessor methods:
+      # * <tt>other</tt>
+      # * <tt>other=</tt>
+      def alias_association_accessor_methods(alias_name, association_name)
+        alias_method alias_name, association_name
+        alias_method "#{alias_name}=", "#{association_name}="
+      end
+      private :alias_association_accessor_methods
+
+      # Aliases singular association methods:
+      # * <tt>build_other</tt>
+      # * <tt>create_other</tt>
+      # * <tt>create_other!</tt>
+      def alias_singular_association_methods(alias_name, association_name)
+        alias_method "build_#{alias_name}", "build_#{association_name}"
+        alias_method "create_#{alias_name}", "create_#{association_name}"
+        alias_method "create_#{alias_name}!", "create_#{association_name}!"
+      end
+      private :alias_singular_association_methods
+
+      # Aliases collection association methods:
+      # * <tt>other_ids</tt>
+      # * <tt>other_ids=</tt>
+      def alias_collection_association_methods(alias_name, association_name)
+        singularized_alias_name = alias_name.to_s.singularize
+        singularized_association_name = association_name.to_s.singularize
+        alias_method "#{singularized_alias_name}_ids", "#{singularized_association_name}_ids"
+        alias_method "#{singularized_alias_name}_ids=", "#{singularized_association_name}_ids="
+      end
+      private :alias_collection_association_methods
+    end
+  end
+end

data/lib/moribus/extensions.rb

@@ -0,0 +1,37 @@
+module Moribus
+  # Extends the default Rails +has_one+ and +belongs_to+ associations
+  # to enable tracked and aggregated behaviors.
+  module Extensions
+    extend ActiveSupport::Concern
+    extend ActiveSupport::Autoload
+
+    autoload :HasAggregatedExtension
+    autoload :HasCurrentExtension
+    autoload :DelegateAssociated
+
+    # :nodoc:
+    module ClassMethods
+      # Adds special delegation for +has_aggregated+ association to Rails'
+      # +belongs_to+ reflection object.
+      def extend_has_aggregated_reflection(reflection)
+        HasAggregatedExtension::Helper.new(self, reflection).extend
+      end
+      private :extend_has_aggregated_reflection
+    end
+
+    # Overrides Rails' default #association method to extend resulting
+    # +association+ objects by custom behaviors.
+    def association(name)
+      association = super
+      reflection = self.class.reflect_on_association(name)
+      case reflection.macro
+      when :belongs_to
+        association.extend(HasAggregatedExtension) if reflection.options[:aggregated]
+      when :has_one
+        association.extend(HasCurrentExtension) if reflection.options[:is_current]
+      else # do nothing
+      end
+      association
+    end
+  end
+end

data/lib/moribus/extensions/delegate_associated.rb

@@ -0,0 +1,48 @@
+module Moribus
+  module Extensions
+    # This module is included by the class on the first call to
+    # +delegate_associated+ method. When included, it will add
+    # +classes_delegating_to+ class attribute to memorize classes
+    # of delegated associations. This information will be used
+    # for multi-parameter attributes assignment.
+    module DelegateAssociated
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :classes_delegating_to
+        self.classes_delegating_to = []
+      end
+
+      # Overloaded AR::Base method that will additionally check column
+      # in delegated associations classes. Purpose:
+      #
+      #   class Customer < ActiveRecord::Base
+      #     has_one_current :customer_info
+      #
+      #     delegate_associated :date_of_birth, :to => :customer_info
+      #   end
+      #
+      #   customer = Customer.new({
+      #     'date_of_birth(1i)' => '1950',
+      #     'date_of_birth(2i)' => '03',
+      #     'date_of_birth(3i)' => '18'
+      #   })
+      #
+      # Here, for multi-parameter attribute assignment, Rails will try to
+      # get the column class of 'date_of_birth' attribute. Since it is not
+      # presented in Customer, the code will result in exception without
+      # the following hook:
+      def column_for_attribute(name)
+        unless (column = super).nil?
+          return column
+        end
+
+        self.class.classes_delegating_to.each do |klass|
+          column = klass.columns_hash[name.to_s]
+          return column unless column.nil?
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/moribus/extensions/has_aggregated_extension.rb

@@ -0,0 +1,94 @@
+module Moribus
+  module Extensions
+    # Minor extension for Rails' +belongs_to+ association that will correct
+    # foreign key assignment during association autosave.
+    module HasAggregatedExtension
+      # Return +true+ if the association has an @updated value (set by
+      # default Rails behavior) or if the target record was updated during
+      # lookup, indicating that the association owner's foreign key should
+      # be updated also.
+      def updated?
+        @updated || target.try(:updated_as_aggregated?)
+      end
+
+      # This helper class is used to effectively extend +has_aggregated+
+      # association by adding attribute delegation of attributes and enum
+      # readers to the effective reader of the association owner. Behaves
+      # much like ActiveRecord::Associations::Builder classes.
+      class Helper
+        # Among all attribute methods, we're interested only in reader and
+        # writers - discard the rest
+        EXCLUDE_METHODS_REGEXP = /^_|\?$|^reset|_cast$|_was$|_change!?$|lock_version|created_at|updated_at/
+
+        attr_reader :model, :reflection
+
+        # Save association owner and reflection for subsequent processing.
+        def initialize(model, reflection)
+          @model, @reflection = model, reflection
+        end
+
+        # Extend association: add the delegation module to the reflection,
+        # fill it with the delegation methods and include it into the model.
+        def extend
+          define_delegation_module(reflection)
+          add_delegated_methods(reflection)
+          include_delegation_module(reflection)
+        end
+
+        # Define the delegation module for a reflection, available through
+        # #delegated_attribute_methods* method.
+        def define_delegation_module(reflection)
+          reflection.define_singleton_method(:delegated_attribute_methods) do
+            @delegated_attribute_methods ||= Module.new
+          end
+        end
+        private :define_delegation_module
+
+        # Add all the interesting methods of the association's klass:
+        # generated attribute readers and writers, as well as enum readers
+        # and writers.
+        def add_delegated_methods(reflection)
+          mod = reflection.delegated_attribute_methods
+          model.define_attribute_methods unless model.attribute_methods_generated?
+          methods_to_delegate = methods_to_delegate_to(reflection) - model.instance_methods.map(&:to_sym)
+          methods_to_delegate.each do |method|
+            mod.delegate method, :to => name
+          end
+        end
+        private :add_delegated_methods
+
+        # Return a list of methods we want to delegate to the association:
+        # will generate attribute methods for a klass if they have not yet
+        # been generated by Rails, and will select reader and writer methods
+        # from the generated model. Also, adds enum readers and writers to
+        # a result. Also, it selects methods that can be treated as
+        # 'custom_writers' - they were declared within the class itself
+        # and have a names like '<column_name>='
+        def methods_to_delegate_to(reflection)
+          klass = reflection.klass
+          enum_methods = klass.reflect_on_all_enumerated.map do |reflection|
+            name = reflection.name
+            [name, "#{name}="]
+          end
+          klass.define_attribute_methods unless klass.attribute_methods_generated?
+          attribute_methods = klass.generated_attribute_methods.instance_methods.select{ |m| m !~ EXCLUDE_METHODS_REGEXP }
+          custom_writers = klass.instance_methods(false).map(&:to_s) & klass.column_names.map{ |name| "#{name}=" }
+          (attribute_methods + enum_methods.flatten + custom_writers).map(&:to_sym)
+        end
+        private :methods_to_delegate_to
+
+        # Include the reflection's attributes delegation module into a model.
+        def include_delegation_module(reflection)
+          model.send(:include, reflection.delegated_attribute_methods)
+        end
+        private :include_delegation_module
+
+        # Return the effective name of the association we're delegating to.
+        def name
+          @reflection_name ||= "effective_#{reflection.name}"
+        end
+        private :name
+      end
+    end
+  end
+end

data/lib/moribus/extensions/has_current_extension.rb

@@ -0,0 +1,17 @@
+module Moribus
+  module Extensions
+    # Minor extension for Rails' +has_one+ association that will help
+    # dealing with current record assignment.
+    module HasCurrentExtension
+      # Sets 'is_current' flag of overridden record to false, instead
+      # of deleting it or setting foreign key to nil.
+      def remove_target!(*)
+        if target.new_record?
+          target.is_current = false
+        else
+          target.update_attribute(:is_current, false)
+        end
+      end
+    end
+  end
+end