acts_as_span 1.0.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1b2bd958d53e10e1816b39bbb073c8b9d21b105ab20b7bdd1d0f11048f2adf7
-  data.tar.gz: 9f211ee95efdcbad216591259729983fbf31fc26f6ce91d39fdd03be258d0c0e
+  metadata.gz: dce2b4057e3f17e47bc079858edd883ae157fab1ac07255e352471fc0d4a734e
+  data.tar.gz: 004a557469880ade02c121b63446f3014ce4bcea43ab6febfdc88e7e852fec30
 SHA512:
-  metadata.gz: aa5735e3051308f569cee93a81b13b833c33c1611feaacc0cfc2b985f1938dbaac923676bcd5e0fc75ed91f428651a3b2e10ff2a4ed48981e6191acc60494bd1
-  data.tar.gz: 2fc6f890b396e9829559aa063f6bdd6dfb21b1afc0806a83dc1114acbc736af6ce0cf6dec2c319a259ad1adfdbd52657f81c2adc439b32a3d05c4844f179b7f5
+  metadata.gz: eef25c86ddff4ce610a0cfe4e2a9b3fbf983768821566c0b056cdbb117d82f9ab0573c2309cb839ac61077f00fb7a5a6f1302f8bd64371ce43a5fa1d6068bfaa
+  data.tar.gz: 7815bd5e31b5eca225a88278dad84af946a98ad0adef280b5dcdd24f358ae3a4c2005da40dfc035344525c9f157cf98e96aea52b526c5a69c729179849c6e135

data/.tool-versions

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

data/.travis.yml

@@ -2,7 +2,11 @@ language: ruby
 rvm:
   - 2.4.5
   - 2.5.3
-  - 2.6.1
-before_install: gem install bundler
+  - 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/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Types of changes:
+  - **Added** for new features.
+  - **Changed** for changes in existing functionality.
+  - **Deprecated** for soon-to-be removed features.
+  - **Removed** for now removed features.
+  - **Fixed** for any bug fixes.
+  - **Security** in case of vulnerabilities.
+
+Please include the Github issue or pull request number when applicable
+
+## [Unreleased]
+### Added
+- A change log #31
+### Fixed
+- Syntax error in EndDatePropagator#propagate #30

data/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+## Checklist
+- [ ] Continuous integration passes, or no functional code was changed
+- [ ] Changelog entry added, or no entry is necessary
+
+## Notes

data/acts_as_span.gemspec

@@ -1,39 +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{ActiveRecord model w/ a start_date and an end_date == ActsAsSpan}
-  s.license       = "MIT"
+  s.description = 'ActiveRecord model w/ a start_date and an end_date == ActsAsSpan'
+  s.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 s.respond_to?(:metadata)
-    s.metadata["allowed_push_host"] = "https://rubygems.org"
+    s.metadata['allowed_push_host'] = 'https://rubygems.org'
   else
-    raise "RubyGems 2.0 or newer is required to protect against " \
-          "public gem pushes."
+    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.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = %w[lib]
 
-  s.add_development_dependency "bundler", "~> 2.0.1"
-  s.add_development_dependency "rake", "~> 10.0"
-  s.add_development_dependency "rspec", "~> 3.0"
-  s.add_development_dependency "sqlite3", "~> 1.3.6"
-  s.add_development_dependency "has_siblings", "~> 0.2.7"
-  s.add_development_dependency "temping"
-  s.add_development_dependency "pry-byebug"
+  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', '>= 4.2.0')
-  s.add_runtime_dependency('activesupport', '>= 4.2.0')
+  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

@@ -6,10 +6,13 @@ require 'acts_as_span/span_instance'
 require 'acts_as_span/no_overlap_validator'
 require 'acts_as_span/within_parent_date_span_validator'
 
+require 'acts_as_span/end_date_propagator'
 
 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
 

data/lib/acts_as_span/end_date_propagator.rb

@@ -0,0 +1,219 @@
+# 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
+
+      # NOTE: Rails 5 support
+      if ActiveRecord::VERSION::MAJOR > 5
+        add_errors(result.errors)
+      else
+        add_rails_5_errors(result.errors)
+      end
+
+      object
+    end
+
+    private
+
+    def add_errors(errors)
+      errors.each do |error|
+        if object.errors[error.attribute].exclude? error.message
+          object.errors.add(error.attribute, error.message)
+        end
+      end
+    end
+
+    # Treat errors like a Hash
+    # NOTE: Rails 5 support
+    def add_rails_5_errors(errors)
+      errors.each do |attribute, message|
+        if object.errors[attribute].exclude? message
+          object.errors.add(attribute, message)
+        end
+      end
+    end
+
+    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|
+          next if object.errors.added?(:base, message)
+
+          object.errors.add(:base, 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

data/lib/acts_as_span/no_overlap_validator.rb

@@ -1,49 +1,84 @@
+# frozen_string_literal: true
+
 require 'active_model'
 
 module ActsAsSpan
+  # Validator that checks whether a record is overlapping with others
+  #
+  # Takes options `:instance_scope` (optional) and `:scope` (required):
+  # * `instance_scope` is a proc which, when evaluated by the record, returns
+  #   a boolean value. When false, the validatior will not check for overlap.
+  #   When true, the validator checks normally.
+  # * `scope` is also a proc. This is must return an ActiveRecord Relation that
+  #   determines which records' spans to compare.
+  #
+  # Usage:
+  # Given a record with `siblings` defined, the most basic use case is:
+  # ```
+  # validates_with ActsAsSpan::NoOverlapValidator,
+  #   scope: proc { siblings }
+  # ```
+  # When this record is validated, every record in the ActiveRecord relation
+  #   `record.siblings` is checked for mutual overlap with `record`.
+  #
+  # Use `instance_scope` if there is some condition where a record oughtn't be
+  #   validated for whatever reason:
+  # ```
+  # validates_with ActsAsSpan::NoOverlapValidator,
+  #   scope: proc { siblings }, instance_scope: proc { favorite? }
+  # ```
+  # Now, when this record is validated, if `record.favorite?` is `true`,
+  #   `record` must pass the overlap check with its siblings.
+  #   If `record.favorite?` is `false`, it is under less scrutiny.
+  #
   class NoOverlapValidator < ActiveModel::Validator
     def validate(record)
       overlapping_records = temporally_overlapping_for(record)
-      instance_scope = options[:instance_scope].is_a?(Proc) ? record.instance_eval(&options[:instance_scope]) : true
-
-      if overlapping_records.any? && instance_scope
+      instance_scope = if options[:instance_scope].is_a? Proc
+                         record.instance_eval(&options[:instance_scope])
+                       else
+                         true
+                       end
 
-        error_type = overlapping_records.size == 1 ? "no_overlap.one" : "no_overlap.other"
+      return unless overlapping_records.any? && instance_scope
 
-        record.errors.add(
-          :base,
-          error_type.to_sym,
-          model_name: record.class.model_name.human,
-          model_name_plural: record.class.model_name.plural.humanize,
-          start_date: record.start_date,
-          end_date: record.end_date,
-          count: overlapping_records.size,
-          overlapping_records_s: overlapping_records.join(",")
-        )
-      end
+      error_message = options[:message] || :no_overlap
+      record.errors.add(
+        :base,
+        error_message,
+        model_name: record.class.model_name.human,
+        model_name_plural: record.class.model_name.plural.humanize,
+        start_date: record.span.start_date,
+        end_date: record.span.end_date,
+        count: overlapping_records.size,
+        overlapping_records_s: overlapping_records.join(', ')
+      )
     end
 
-    #TODO add back condition for start_date nil
-    #TODO add configuration for span configuration
+    # TODO: add back condition for start_date nil
+    # TODO: add support for multiple spans (currently only checks :default)
     def temporally_overlapping_for(record)
       scope = record.instance_eval(&options[:scope])
 
-      start_date = record.start_date || Date.current
-      end_date = record.end_date
+      start_date = record.span.start_date || Date.current
+
+      end_date = record.span.end_date
+      end_field = record.span.end_field
+
       arel_table = record.class.arel_table
 
       if end_date
         scope.where(
-          arel_table[:start_date].lteq(end_date).
-          and(
-            arel_table[:end_date].gteq(start_date).
-            or(arel_table[:end_date].eq(nil))
+          arel_table[record.span.start_field].lteq(end_date)
+          .and(
+            arel_table[end_field].gteq(start_date)
+          .or(arel_table[end_field].eq(nil))
           )
         )
       else
         scope.where(
-          arel_table[:end_date].gteq(start_date).
-          or(arel_table[:end_date].eq(nil))
+          arel_table[end_field].gteq(start_date)
+          .or(arel_table[end_field].eq(nil))
         )
       end
     end