acts_as_span 0.0.5 → 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59d6ed6e5f0b02d6d3683a99d62ac5f3b11ccdb5cf510f5bf1a3197e095102ff
+  data.tar.gz: 856975edeadab3d35def0a65e51bb6d65987fc2042cdec822d72b7c76741a9cb
+SHA512:
+  metadata.gz: cb1ae3e3c092a528e83d7dcb2fd9ca7d601b985eaa974b6eac1c1eb2634dc4630473dc5bfcafd548d3748a602569185cd803c2f7f6551c486dddcee1905e8205
+  data.tar.gz: 605657a4fb0114f18018b4aab29d9c2f9c63bf87321fe7c04ceaccb7974ad064dc4112ce3b7e5b44c8b541b65680e768e60ef54e8d43e1502ec59f27f46c797d

data/.gitignore

@@ -1,3 +1,11 @@
-coverage
-rdoc
-pkg
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+
+.DS_Store
+*.log
+*.sqlite
+
+.rvmrc
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order rand

data/.tool-versions

@@ -0,0 +1 @@
+ruby 2.6.5

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 2.4.5
+  - 2.5.3
+  - 2.6.5
+
+# match the bundler version in the gemspec
+before_install:
+  - gem install -v 2.1.4 bundler --no-document
+  - bundle _2.1.4_ install
+notifications:
+  email: false

data/Gemfile

@@ -2,6 +2,3 @@ source "http://rubygems.org"
 
 # Specify your gem's dependencies in acts_as_span.gemspec
 gemspec
-
-gem 'rspec'
-gem 'acts_as_fu'

data/README.rdoc

@@ -1,6 +1,8 @@
 = acts_as_span
 
-ActiveRecord model w/ a start_date and an end_date
+ActiveRecord model w/ a start_date and an end_date == ActsAsSpan
+
+Treat those date spans like the objects they are!
 
 == Getting Started
 
@@ -14,20 +16,6 @@ In your model:
       acts_as_span
     end
 
-In your migrations:
-
-    class AddSpanToSpanRecord < ActiveRecord::Migration
-      def self.up
-        add_column :span_records, :start_date, :date
-        add_column :span_records, :end_date, :date
-      end
-
-      def self.down
-        remove_column :span_records, :start_date
-        remove_column :span_records, :end_date
-      end
-    end
-
 == Copyright
 
-Copyright (c) 2011 Annkissam. See LICENSE for details.
+Copyright (c) 2011-2018 Annkissam. See LICENSE for details.

data/Rakefile

@@ -1,4 +1,8 @@
-require 'bundler/gem_tasks'
+require "bundler/gem_tasks"
+
+#RSPEC
 require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec

data/acts_as_span.gemspec

@@ -1,23 +1,40 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "acts_as_span/version"
+# frozen_string_Literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'acts_as_span/version'
 
 Gem::Specification.new do |s|
-  s.name        = "acts_as_span"
+  s.name        = 'acts_as_span'
   s.version     = ActsAsSpan::VERSION::STRING
-  s.authors     = ["Eric Sullivan"]
-  s.email       = ["eric.sullivan@annkissam.com"]
-  s.homepage    = "https://github.com/annkissam/acts_as_span"
+  s.authors     = ['Eric Sullivan']
+  s.email       = ['eric.sullivan@annkissam.com']
+  s.homepage    = 'https://github.com/annkissam/acts_as_span'
   s.summary     = ActsAsSpan::VERSION::SUMMARY
-  s.description = %q{start_date and end_date as a span w/ ActiveRecord}
+  s.description = 'ActiveRecord model w/ a start_date and an end_date == ActsAsSpan'
+  s.license       = 'MIT'
 
-  s.rubyforge_project = "acts_as_span"
+  # 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 s.respond_to?(:metadata)
+    s.metadata['allowed_push_host'] = 'https://rubygems.org'
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+          'public gem pushes.'
+  end
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
-  
-  s.add_dependency(%q<activerecord>, [">= 3"])
-  s.add_dependency('activesupport')
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = %w[lib]
+
+  s.add_development_dependency 'bundler', '~> 2.1.4'
+  s.add_development_dependency 'has_siblings', '~> 0.2.7'
+  s.add_development_dependency 'pry-byebug'
+  s.add_development_dependency 'rake', '>= 12.3.3'
+  s.add_development_dependency 'rspec', '~> 3.0'
+  s.add_development_dependency 'sqlite3', '~> 1.4'
+  s.add_development_dependency 'temping'
+
+  s.add_runtime_dependency('activerecord', '>= 5.0.0')
+  s.add_runtime_dependency('activesupport', '>= 5.0.0')
 end

data/config/locales/en/acts_as_span.yml

@@ -0,0 +1,15 @@
+en:
+  activerecord:
+    errors:
+      messages:
+        end_date_propagator:
+          propagation_failure: "%{parent} could not propagate
+           %{end_date_field_name} to %{child}:\n%{reason}"
+        # TODO: let pluralize handle pluralization
+        no_overlap:
+          one: "A %{model_name} already exists between
+           %{start_date} - %{end_date}: %{overlapping_records_s}"
+          other: "%{count} %{model_name_plural} already exist between
+           %{start_date} - %{end_date}: %{overlapping_records_s}"
+        not_within_parent_date_span: Must exist within the %{parent} date span
+        start_date_after_end_date: Must be on or after %{start_field}

data/lib/acts_as_span.rb

@@ -1,161 +1,132 @@
-require 'active_support'
 require 'ostruct'
-require 'forwardable'
+require 'acts_as_span/version'
+require 'acts_as_span/span_klass'
+require 'acts_as_span/span_instance'
+
+require 'acts_as_span/no_overlap_validator'
+require 'acts_as_span/within_parent_date_span_validator'
 
-ACTS_AS_SPAN_PATH = File.dirname(__FILE__) + "/acts_as_span/"
+require 'acts_as_span/end_date_propagator'
 
-require ACTS_AS_SPAN_PATH + 'version'
-require ACTS_AS_SPAN_PATH + 'span_klass'
-require ACTS_AS_SPAN_PATH + 'span_instance'
+require 'active_support'
+require 'active_record'
+
+I18n.load_path += Dir[File.join(File.dirname(__dir__), 'config', 'locales', '**', 'acts_as_span.yml')]
 
 module ActsAsSpan
   extend ActiveSupport::Concern
-  
+
+  OPTIONS = %i[start_field end_field name].freeze
+
   class << self
     def options
       @options ||= {
-        :start_date_field => :start_date,
-        :end_date_field => :end_date,
-        :start_date_field_required => false,
-        :end_date_field_required => false,
-        :span_overlap_scope => nil,
-        :span_overlap_count => nil,
+        :start_field => :start_date,
+        :end_field => :end_date,
         :name => :default
       }
     end
-    
+
     def configure
       yield(self) if block_given?
     end
   end
-  
-  #by default, all model classess & their instances will return false w/ acts_as_span?
-  included do
-    self.send(:extend, ActsAsSpan::NegativeMethods)
-    self.send(:include, ActsAsSpan::NegativeMethods)
-  end
-  
+
   module ClassMethods
     def acts_as_span(*args)
-      #this model & its instances will return true w/ acts_as_span?
-      self.send(:extend, ActsAsSpan::PositiveMethods)
-      self.send(:include, ActsAsSpan::PositiveMethods)
-      
-      self.send(:extend, Forwardable)
-      
       self.send(:extend, ActsAsSpan::ExtendedClassMethods)
       self.send(:include, ActsAsSpan::IncludedInstanceMethods)
-      
+
+      # TODO: There's some refactoring that could be done here using keyword args (or the more standard old hash arg pattern)
       options = OpenStruct.new(args.last.is_a?(Hash) ? ActsAsSpan.options.merge(args.pop) : ActsAsSpan.options)
-      
-      #if span_overlap_scope is specified the span_overlap_count defaults to 0
-      options.span_overlap_count ||= 0 if options.span_overlap_scope
-      
+
+      unsupported_options =
+        options.to_h.keys.reject { |opt| OPTIONS.include? opt }
+      unless unsupported_options.empty?
+        raise ArgumentError,
+          'Unsupported option(s): ' <<
+          unsupported_options.map { |o| "'#{o}'" }.join(', ')
+      end
+
       acts_as_span_definitions[options.name] = options
-      
-      def_delegators :span, :close!,
-                            :close_on!,
-                            :span_status,
-                            :span_status_on,
-                            :span_status_to_s,
-                            :span_status_to_s_on,
-                            :current?,
-                            :current_on?,
-                            :future?,
-                            :future_on?,
-                            :expired?,
-                            :expired_on?
-                            
-      def_delegators 'self.class', :acts_as_span_definitions
-      
+
+      # TODO add tests that check delegation of all methos in span
+      delegate :span_status,
+               :span_status_on,
+               :current?,
+               :current_on?,
+               :future?,
+               :future_on?,
+               :expired?,
+               :expired_on?,
+               :past?,
+               :past_on?, to: :span
+
+      delegate :acts_as_span_definitions, to: :class
+
+      # TODO idem above
       class << self
-        self.send(:extend, Forwardable)
-        
-        def_delegators :span, :current,
-                              :current_on,
-                              :future,
-                              :future_on,
-                              :expired,
-                              :expired_on
+        delegate :current,
+                 :current_on,
+                 :future,
+                 :future_on,
+                 :expired,
+                 :expired_on,
+                 :past_on,
+                 :past,
+                 :current_or_future_on,
+                 :current_or_future, to: :span
       end
-      
+
       validate :validate_spans
     end
-    
+
     def acts_as_span_definitions
       @_acts_as_span_definitions ||= {}
     end
   end
-  
+
   module ExtendedClassMethods
-    def overlap(test_record)
-      overlap_for(test_record, :default, :default)
-    end
-    
-    def overlap_for(test_record, test_record_span_name = :default, this_span_name = :default)
-      span_for(this_span_name).overlap(test_record.span_for(test_record_span_name))
-    end
-    
     def spans
       acts_as_span_definitions.keys.map { |acts_as_span_definition_name| span_for(acts_as_span_definition_name) }
     end
-    
+
     def span
       span_for(:default)
     end
-    
+
     def span_for(name = :default)
       acts_as_span_klasses[name] ||= SpanKlass.new(name, self, acts_as_span_definitions[name])
     end
-    
+
     def acts_as_span_klasses
       @_acts_as_span_klasses ||= {}
     end
   end
-  
+
   module IncludedInstanceMethods
     def spans
       acts_as_span_definitions.keys.map { |acts_as_span_definition_name| span_for(acts_as_span_definition_name) }
     end
-    
+
     def span
       span_for(:default)
     end
-    
+
     def span_for(name = :default)
       acts_as_span_instances[name] ||= SpanInstance.new(name, self, acts_as_span_definitions[name])
     end
-    
+
     def acts_as_span_instances
       @_acts_as_span_instances ||= {}
     end
-    
+
     def validate_spans
       spans.each(&:validate)
     end
-    
-    #This syntax assumes :default span
-    def overlap?(other_record)
-      overlap_for?(other_record, :default, :default)
-    end
-    
-    #record.span_for(:this_span_name).overlap?(other_record.span_for(:other_record_span_name))
-    def overlap_for?(other_record, this_span_name = :default, other_record_span_name = :default)
-      span_for(this_span_name).overlap?(other_record.span_for(other_record_span_name))
-    end
-  end
-  
-  module PositiveMethods
-    send(:define_method, "acts_as_span?") do
-      true
-    end
-  end
-  
-  module NegativeMethods
-    send(:define_method, "acts_as_span?") do
-      false
-    end
   end
 end
 
-ActiveRecord::Base.send(:include, ActsAsSpan)
+if Object.const_defined?("ActiveRecord")
+  ActiveRecord::Base.send(:include, ActsAsSpan)
+end

data/lib/acts_as_span/end_date_propagator.rb

@@ -0,0 +1,198 @@
+# frozen_string_Literal: true
+
+module ActsAsSpan
+  # # End Date Propagator
+  #
+  # When editing the `end_date` of a record, the record's children often also
+  #   need to be updated. This propagator takes care of that.
+  # For each of the  child records (defined below in the function `children`),
+  #   the child record's `end_date` is updated to match that of the original
+  #   object. The function `propagate` is recursive, propagating to
+  #   children of children and so on.
+  # Records that should not have their end dates propagated in this manner
+  #   (e.g. StatusRecords) are manually excluded in `skipped_classes`.
+  # If there is some error preventing propagation, the child record is NOT saved
+  #   and that error message is added to the object's `errors`. These errors
+  #   propagate upwards into a flattened array of error messages.
+  #
+  # This class uses its own definition of 'child' for an object. For a given
+  #   object, the objects the propagator considers its children are:
+  #   * Associated via `has_many` association
+  #   * Association `:dependent` option is `:delete` or `:destroy`
+  #   * acts_as_span (checked via `respond_to?(:span)`)
+  #   * Not blacklisted via `skipped_classes` array
+  #
+  # The return value for `call` is the given object, updated to have children's
+  #   errors added to its `:base` errors if any children had errors.
+  #
+  # ## Usage:
+  #
+  # Propagate end dates for an object that acts_as_span and has propagatable
+  # children to all propagatable children:
+  # ```
+  # ActsAsSpan::EndDatePropagator.call(object)
+  # ```
+  #
+  # To propagate to a subset of its propagatable children:
+  # ```
+  # ActsAsSpan::EndDatePropagator.call(
+  #   object, skipped_classes: [ClassOne, ClassTwo]
+  # )
+  # ```
+  # ... where ClassOne and ClassTwo are the classes to be excluded.
+  #
+  # The EndDatePropagator does not use transactions. If the propagation should
+  # be run in a transaction, wrap the call in one like so:
+  # ```
+  # ActiveRecord::Base.transaction do
+  #   ActsAsSpan::EndDatePropagator.call(
+  #     obj, skipped_classes: [ClassOne, ClassTwo]
+  #   )
+  # end
+  # ```
+  #
+  # One use case for the transaction wrapper would be to not follow through
+  # with propagation if the object has errors:
+  # ```
+  # ActiveRecord::Base.transaction do
+  #   result = ActsAsSpan::EndDatePropagator.call(obj)
+  #   if result.errors.present?
+  #     fail OhNoMyObjetHasErrorsError, "Oh, no! My object has errors!"
+  #   end
+  # end
+  # ```
+  #
+  # Currently only propagates "default" span. The approach to implementing such
+  #   a feature is ambiguous - would all children have the same span propagated?
+  #   Would each acts_as_span model need a method to tell which span to
+  #   propagate to? Once there is a solid use case for using this object on
+  #   models with multiple spans, that will inform the implementation strategy.
+  class EndDatePropagator
+    attr_reader :object,
+                :errors_cache,
+                :skipped_classes,
+                :include_errors
+
+    def initialize(object, errors_cache: [], skipped_classes: [], include_errors: true)
+      @object = object
+      @errors_cache = errors_cache
+      @skipped_classes = skipped_classes
+      @include_errors = include_errors
+    end
+
+    # class-level call: enable the usage of ActsAsSpan::EndDatePropagator.call
+    def self.call(object, **opts)
+      new(object, opts).call
+    end
+
+    def call
+      result = propagate
+      # only add new errors to the object
+      result.errors.each do |error, message|
+        unless object.errors[error].include? message
+          object.errors.add(error, message: message)
+        end
+      end
+      object
+    end
+
+    private
+
+    def propagate
+      # return if there is nothing to propagate
+      return object unless should_propagate_from? object
+
+      children(object).each do |child|
+        # End the record, its children too. And their children, forever, true.
+        propagated_child = assign_end_date(child, object.span.end_date)
+
+        # save child and add errors to cache
+        save_with_errors(object, child, propagated_child)
+      end
+
+      if errors_cache.present?
+        errors_cache.each do |message|
+          skip if object.errors.added?(:base, message)
+
+          object.errors.add(:base, message: message)
+        end
+      end
+
+      # return the object, with any newly-added errors
+      object
+    end
+
+    # returns the given child, but possibly with errors
+    def assign_end_date(child, new_end_date)
+      child.assign_attributes({ child.span.end_field => new_end_date })
+      ActsAsSpan::EndDatePropagator.call(
+        child,
+        errors_cache: errors_cache,
+        skipped_classes: skipped_classes,
+      )
+    end
+
+    # save the child record, add errors.
+    def save_with_errors(object, child, propagated_child)
+      if object_has_errors?(propagated_child) && include_errors
+        errors_cache << propagation_error_message(object, child)
+      end
+      child.save
+    end
+
+    def propagation_error_message(object, child)
+      I18n.t(
+        'propagation_failure',
+        scope: %i[activerecord errors messages end_date_propagator],
+        end_date_field_name: child.class.human_attribute_name(
+          child.span.end_field,
+        ),
+        parent: object.model_name.human,
+        child: child.model_name.human,
+        reason: child.errors.full_messages.join('; '),
+      )
+    end
+
+    def object_has_errors?(object)
+      !object.valid? ||
+        (object.errors.present? && object.errors.messages.values.flatten.any?)
+    end
+
+    # check if the end_date analog is dirtied
+    def end_date_changed?(object)
+      end_date_field = object.span.end_field.to_s
+      object.changed.include? end_date_field
+    end
+
+    def should_propagate_from?(object)
+      object.respond_to?(:span) &&
+        end_date_changed?(object) &&
+        !object.span.end_date.nil?
+    end
+
+    # Use acts_as_span to determine whether a record has an end date
+    def should_propagate_to?(klass)
+      klass.respond_to?(:span) && @skipped_classes.exclude?(klass)
+    end
+
+    def child_associations(object)
+      object.class.reflect_on_all_associations(:has_many).select do |reflection|
+        %i[delete destroy].include?(reflection.options[:dependent]) &&
+          should_propagate_to?(reflection.klass)
+      end
+    end
+
+    def children(object)
+      child_objects = child_associations(object).flat_map do |reflection|
+        object.send(reflection.name)
+      end
+
+      # skip previously-ended children
+      child_objects.reject do |child|
+        child.span.end_date && child.span.end_date < object.span.end_date
+      end
+    end
+
+    attr_writer :object, :errors_cache
+  end
+end