validates_timeliness 5.0.0 → 6.0.1

data/README.md

@@ -0,0 +1,319 @@
+# ValidatesTimeliness [![build](https://github.com/adzap/validates_timeliness/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/adzap/validates_timeliness/actions/workflows/ci.yml)
+
+- Source:  https://github.com/adzap/validates_timeliness
+- Issues:  https://github.com/adzap/validates_timeliness/issues
+
+
+## Description
+
+Complete validation of dates, times and datetimes for Rails 6.x and
+ActiveModel.
+
+Old Rails versions:
+
+- Rails 4.x: [https://github.com/adzap/validates_timeliness/tree/4-0-stable]
+- Rails 5.x: [https://github.com/adzap/validates_timeliness/tree/5-0-stable]
+
+
+## Features
+
+- Adds validation for dates, times and datetimes to ActiveModel
+- Handles timezones and type casting of values for you
+- Only Rails date/time validation plugin offering complete validation (See ORM/ODM support)
+- Uses extensible date/time parser (Using [timeliness gem](https://github.com/adzap/timeliness). See Plugin Parser)
+- Adds extensions to fix Rails date/time select issues (See Extensions)
+- Supports I18n for the error messages. For multi-language support try [timeliness-i18n gem](https://github.com/pedrofurtado/timeliness-i18n).
+- Supports all the Rubies (that any sane person would be using in production).
+
+
+## Installation
+
+In Gemfile
+```ruby
+gem 'validates_timeliness', '~> 6.0.0'
+```
+
+Run bundler:
+```bash
+$ bundle install
+```
+
+Then run
+```bash
+$ rails generate validates_timeliness:install
+```
+
+This creates configuration initializer and locale files. In the initializer, there are a number of config options to customize the plugin.
+
+**NOTE**: You may wish to enable the plugin parser and the extensions to start.
+Please read those sections first.
+
+## Examples
+
+```ruby
+validates_datetime :occurred_at
+
+validates_date :date_of_birth, before: lambda { 18.years.ago },
+                                before_message: "must be at least 18 years old"
+
+validates_datetime :finish_time, after: :start_time # Method symbol
+
+validates_date :booked_at, on: :create, on_or_after: :today # See Restriction Shorthand.
+
+validates_time :booked_at, between: ['9:00am', '5:00pm'] # On or after 9:00AM and on or before 5:00PM
+validates_time :booked_at, between: '9:00am'..'5:00pm' # The same as previous example
+validates_time :booked_at, between: '9:00am'...'5:00pm' # On or after 9:00AM and strictly before 5:00PM
+
+validates_time :breakfast_time, on_or_after: '6:00am',
+                                on_or_after_message: 'must be after opening time',
+                                before: :lunchtime,
+                                before_message: 'must be before lunch time'
+```
+
+## Usage
+
+To validate a model with a date, time or datetime attribute you just use the
+validation method:
+
+```ruby
+class Person < ActiveRecord::Base
+  validates_date :date_of_birth, on_or_before: lambda { Date.current }
+  # or
+  validates :date_of_birth, timeliness: { on_or_before: lambda { Date.current }, type: :date }
+end
+```
+
+or even on a specific record, per ActiveModel API.
+```ruby
+@person.validates_date :date_of_birth, on_or_before: lambda { Date.current }
+```
+
+The list of validation methods available are as follows:
+- `validates_date`     - validate value as date
+- `validates_time`     - validate value as time only i.e. '12:20pm'
+- `validates_datetime` - validate value as a full date and time
+- `validates`          - use the :timeliness key and set the type in the hash.
+
+The validation methods take the usual options plus some specific ones to
+restrict the valid range of dates or times allowed
+
+Temporal options (or restrictions):
+- `:is_at`        - Attribute must be equal to value to be valid
+- `:before`       - Attribute must be before this value to be valid
+- `:on_or_before` - Attribute must be equal to or before this value to be valid
+- `:after`        - Attribute must be after this value to be valid
+- `:on_or_after`  - Attribute must be equal to or after this value to be valid
+- `:between`      - Attribute must be between the values to be valid. Range or Array of 2 values.
+
+Regular validation options:
+- `:allow_nil`    - Allow a nil value to be valid
+- `:allow_blank`  - Allows a nil or empty string value to be valid
+- `:if`           - Execute validation when :if evaluates true
+- `:unless`       - Execute validation when :unless evaluates false
+- `:on`           - Specify validation context e.g :save, :create or :update. Default is :save.
+
+Special options:
+- `:ignore_usec`  - Ignores microsecond value on datetime restrictions
+- `:format`       - Limit validation to a single format for special cases. Requires plugin parser.
+
+The temporal restrictions can take 4 different value types:
+- Date, Time, or DateTime object value
+- Proc or lambda object which may take an optional parameter, being the record object
+- A symbol matching a method name in the model
+- String value
+
+
+When an attribute value is compared to temporal restrictions, they are
+compared as the same type as the validation method type. So using
+validates_date means all values are compared as dates.
+
+## Configuration
+
+### ORM/ODM Support
+
+The plugin adds date/time validation to ActiveModel for any ORM/ODM that
+supports the ActiveModel validations component. However, there is an issue
+with most ORM/ODMs which does not allow 100% date/time validation by default.
+Specifically, when you assign an invalid date/time value to an attribute, most
+ORM/ODMs will only store a nil value for the attribute. This causes an issue
+for date/time validation, since we need to know that a value was assigned but
+was invalid. To fix this, we need to cache the original invalid value to know
+that the attribute is not just nil.
+
+Each ORM/ODM requires a specific shim to fix it. The plugin includes a shim
+for ActiveRecord and Mongoid. You can activate them like so
+```ruby
+ValidatesTimeliness.setup do |config|
+  # Extend ORM/ODMs for full support (:active_record).
+  config.extend_orms = [ :active_record ]
+end
+```
+
+By default the plugin extends ActiveRecord if loaded. If you wish to extend
+another ORM then look at the [wiki page](https://github.com/adzap/validates_timeliness/wiki/ORM-Support) for more
+information.
+
+It is not required that you use a shim, but you will not catch errors when the
+attribute value is invalid and evaluated to nil.
+
+### Error Messages
+
+Using the I18n system to define new defaults:
+```yml
+en:
+  errors:
+    messages:
+      invalid_date: "is not a valid date"
+      invalid_time: "is not a valid time"
+      invalid_datetime: "is not a valid datetime"
+      is_at: "must be at %{restriction}"
+      before: "must be before %{restriction}"
+      on_or_before: "must be on or before %{restriction}"
+      after: "must be after %{restriction}"
+      on_or_after: "must be on or after %{restriction}"
+```
+
+The `%{restriction}` signifies where the interpolation value for the restriction will be inserted.
+
+You can also use validation options for custom error messages. The following
+option keys are available:
+```ruby
+:invalid_date_message
+:invalid_time_message
+:invalid_datetime_message
+:is_at_message
+:before_message
+:on_or_before_message
+:after_message
+:on_or_after_message
+```
+
+**Note**: There is no `:between_message` option. The between error message should be
+defined using the `:on_or_after` and `:on_or_before` (`:before` in case when
+`:between` argument is a `Range` with excluded high value, see Examples) messages.
+
+It is highly recommended you use the `I18n` system for error messages.
+
+### Plugin Parser
+
+The plugin uses the [timeliness gem](https://github.com/adzap/timeliness) as a
+fast, configurable and extensible date and time parser. You can add or remove
+valid formats for `dates`, `times`, and `datetimes`. It is also more strict than the
+Ruby parser, which means it won't accept day of the month if it's not a valid
+number for the month.
+
+By default the parser is disabled. To enable it:
+```ruby
+# in the setup block
+config.use_plugin_parser = true
+```
+
+Enabling the parser will mean that strings assigned to attributes validated
+with the plugin will be parsed using the gem. See the
+[wiki](https://github.com/adzap/validates_timeliness/wiki/Plugin-Parser) for
+more details about the parser configuration.
+
+### Restriction Shorthand
+
+It is common to restrict an attribute to being on or before the current time
+or current day. To specify this you need to use a lambda as an option value
+e.g. `lambda { Time.current }`. This can be tedious noise amongst your
+validations for something so common. To combat this the plugin allows you to
+use shorthand symbols for often used relative times or dates.
+
+Just provide the symbol as the option value like so:
+```ruby
+validates_date :birth_date, on_or_before: :today
+```
+
+The `:today` symbol is evaluated as `lambda { Date.current }`. The `:now` and
+`:today` symbols are pre-configured. Configure your own like so:
+```ruby
+# in the setup block
+config.restriction_shorthand_symbols.update(yesterday: lambda { 1.day.ago })
+```
+
+### Default Timezone
+
+The plugin needs to know the default timezone you are using when parsing or
+type casting values. If you are using ActiveRecord then the default is
+automatically set to the same default zone as ActiveRecord. If you are using
+another ORM you may need to change this setting.
+```ruby
+# in the setup block
+config.default_timezone = :utc
+```
+
+By default it will be `UTC` if ActiveRecord is not loaded.
+
+### Dummy Date For Time Types
+
+Given that Ruby has no support for a time-only type, all time type columns are
+evaluated as a regular Time class objects with a dummy date value set. Rails
+defines the dummy date as 2000-01-01. So a time of '12:30' is evaluated as a
+Time value of '2000-01-01 12:30'. If you need to customize this for some
+reason you can do so as follows:
+```ruby
+# in the setup block
+config.dummy_date_for_time_type = [2009, 1, 1]
+```
+
+The value should be an array of 3 values being year, month and day in that order.
+
+### Temporal Restriction Errors
+
+When using the validation temporal restrictions there are times when the
+restriction option value itself may be invalid. This will add an error to the
+model such as 'Error occurred validating birth_date for :before restriction'.
+These can be annoying in development or production as you most likely just
+want to skip the option if no valid value was returned. By default these
+errors are displayed in Rails test mode.
+
+To turn them on/off:
+```ruby
+# in the setup block
+config.ignore_restriction_errors = true
+```
+
+## Extensions
+
+### Strict Parsing for Select Helpers
+
+When using date/time select helpers, the component values are handled by
+ActiveRecord using the Time class to instantiate them into a time value. This
+means that some invalid dates, such as 31st June, are shifted forward and
+treated as valid. To handle these cases in a strict way, you can enable the
+plugin extension to treat them as invalid dates.
+
+To activate it, uncomment this line in the initializer:
+```ruby
+# in the setup block
+config.enable_multiparameter_extension!
+```
+
+### Display Invalid Values in Select Helpers
+
+The plugin offers an extension for ActionView to allowing invalid date and
+time values to be redisplayed to the user as feedback, instead of a blank
+field which happens by default in Rails. Though the date helpers make this a
+pretty rare occurrence, given the select dropdowns for each date/time
+component, but it may be something of interest.
+
+To activate it, uncomment this line in the initializer:
+```ruby
+# in the setup block
+config.enable_date_time_select_extension!
+```
+
+## Contributors
+
+To see the generous people who have contributed code, take a look at the
+[contributors list](https://github.com/adzap/validates_timeliness/contributors).
+
+## Maintainers
+
+* [Adam Meehan](https://github.com/adzap)
+
+## License
+
+Copyright (c) 2021 Adam Meehan, released under the MIT license.

data/Rakefile

@@ -5,7 +5,6 @@ require 'appraisal'
 
 Bundler::GemHelper.install_tasks
 
-require 'rdoc/task'
 require 'rspec/core/rake_task'
 
 desc "Run specs"
@@ -17,14 +16,5 @@ RSpec::Core::RakeTask.new(:coverage) do |t|
   t.rcov_opts = ['--exclude', 'spec']
 end
 
-desc 'Generate documentation for plugin.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'ValidatesTimeliness'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
 desc 'Default: run specs.'
 task :default => :spec

data/gemfiles/{rails_5_2.gemfile → rails_6_0.gemfile}

@@ -2,13 +2,12 @@
 
 source "http://rubygems.org"
 
-gem "rails", "~> 5.2.0"
+gem "rails", "~> 6.0.0"
 gem "rspec"
 gem "rspec-rails", "~> 3.7"
-gem "timecop"
+gem "sqlite3"
 gem "byebug"
 gem "appraisal"
-gem "sqlite3", "~> 1.3.6"
 gem "nokogiri", "~> 1.8"
 
 gemspec path: "../"

data/gemfiles/{rails_5_1.gemfile → rails_6_1.gemfile}

@@ -2,13 +2,13 @@
 
 source "http://rubygems.org"
 
-gem "rails", "~> 5.1.0"
+gem "rails", "~> 6.1.0"
 gem "rspec"
 gem "rspec-rails", "~> 3.7"
+gem "sqlite3"
 gem "timecop"
 gem "byebug"
 gem "appraisal"
-gem "sqlite3", "~> 1.3.6"
 gem "nokogiri", "~> 1.8"
 
 gemspec path: "../"

data/lib/validates_timeliness/converter.rb

@@ -19,12 +19,13 @@ module ValidatesTimeliness
       when :date
         value.to_date
       when :datetime
-        value.is_a?(Time) ? value : value.to_time
+        value.is_a?(Time) ? value : (time_zone_aware? ? value.in_time_zone : value.to_time)
       else
         value
       end
+
       if ignore_usec && value.is_a?(Time)
-        Timeliness::Parser.make_time(Array(value).reverse[4..9], (:current if time_zone_aware?))
+        value.change(usec: 0)
       else
         value
       end

data/lib/validates_timeliness/extensions/date_time_select.rb

@@ -43,7 +43,7 @@ module ValidatesTimeliness
           values[POSITION.key(position.to_i)] = value.to_i
         end
 
-        DateTimeValue.new(values)
+        DateTimeValue.new(**values)
       end
     end
   end

data/lib/validates_timeliness/helper_methods.rb

@@ -20,7 +20,7 @@ module ActiveModel
 
       def timeliness_validation_for(attr_names, type=nil)
         options = _merge_attributes(attr_names)
-        options.update(:type => type) if type
+        options.update(type: type) if type
         validates_with TimelinessValidator, options
       end
     end

data/lib/validates_timeliness/validator.rb

@@ -85,12 +85,12 @@ module ValidatesTimeliness
 
     def add_error(record, attr_name, message, value=nil)
       value = format_error_value(value) if value
-      message_options = { :message => options.fetch(:"#{message}_message", options[:message]), :restriction => value }
-      record.errors.add(attr_name, message, message_options)
+      message_options = { message: options.fetch(:"#{message}_message", options[:message]), restriction: value }
+      record.errors.add(attr_name, message, **message_options)
     end
 
     def format_error_value(value)
-      format = I18n.t(@type, :default => DEFAULT_ERROR_VALUE_FORMATS[@type], :scope => 'validates_timeliness.error_value_formats')
+      format = I18n.t(@type, default: DEFAULT_ERROR_VALUE_FORMATS[@type], scope: 'validates_timeliness.error_value_formats')
       value.strftime(format)
     end
 

data/lib/validates_timeliness/version.rb

@@ -1,3 +1,3 @@
 module ValidatesTimeliness
-  VERSION = '5.0.0'
+  VERSION = '6.0.1'
 end

data/spec/spec_helper.rb

@@ -5,7 +5,7 @@ require 'active_model'
 require 'active_model/validations'
 require 'active_record'
 require 'action_view'
-require 'timecop'
+require 'active_support/testing/time_helpers'
 
 require 'validates_timeliness'
 require 'validates_timeliness/orm/active_model'
@@ -89,6 +89,7 @@ RSpec.configure do |c|
   c.include(TagMatcher)
   c.include(ModelHelpers)
   c.include(ConfigHelper)
+  c.include(ActiveSupport::Testing::TimeHelpers)
   c.before do
     reset_validation_setup_for(Person)
     reset_validation_setup_for(PersonWithShim)

data/spec/support/test_model.rb

@@ -15,11 +15,11 @@ module TestModel
       self.model_attributes[name] = type
     end
 
-    def define_method_attribute=(attr_name)
+    def define_method_attribute=(attr_name, owner: nil)
       generated_attribute_methods.module_eval("def #{attr_name}=(new_value); @attributes['#{attr_name}']=self.class.type_cast('#{attr_name}', new_value); end", __FILE__, __LINE__)
     end
 
-    def define_method_attribute(attr_name)
+    def define_method_attribute(attr_name, owner: nil)
       generated_attribute_methods.module_eval("def #{attr_name}; @attributes['#{attr_name}']; end", __FILE__, __LINE__)
     end
 

data/spec/validates_timeliness/converter_spec.rb

@@ -7,7 +7,11 @@ RSpec.describe ValidatesTimeliness::Converter do
   let(:ignore_usec) { false }
 
   before do
-    Timecop.freeze(Time.mktime(2010, 1, 1, 0, 0, 0))
+    travel_to Time.mktime(2010, 1, 1, 0, 0, 0)
+  end
+
+  after do
+    travel_back
   end
 
   delegate :type_cast_value, :evaluate, :parse, :dummy_time, to: :converter
@@ -59,30 +63,61 @@ RSpec.describe ValidatesTimeliness::Converter do
 
     describe "for datetime type" do
       let(:type) { :datetime }
-      let(:time_zone_aware) { true }
 
-      it "should return Date as Time value" do
-        expect(type_cast_value(Date.new(2010, 1, 1))).to eq(Time.local(2010, 1, 1, 0, 0, 0))
+      it 'should return nil for invalid value types' do
+        expect(type_cast_value(12)).to eq(nil)
       end
 
-      it "should return same Time value" do
-        value = Time.utc(2010, 1, 1, 12, 34, 56)
-        expect(type_cast_value(Time.utc(2010, 1, 1, 12, 34, 56))).to eq(value)
-      end
+      context "time zone aware" do
+        let(:time_zone_aware) { true }
 
-      it "should return as Time with same component values" do
-        expect(type_cast_value(DateTime.civil_from_format(:utc, 2010, 1, 1, 12, 34, 56))).to eq(Time.utc(2010, 1, 1, 12, 34, 56))
-      end
+        around { |example|
+          Time.use_zone("Perth", &example)
+        }
+
+        it "should return Date as Time value" do
+          Time.use_zone('London') do
+            result = type_cast_value(Date.new(2010, 1, 1))
+            expected = Time.zone.local(2010, 1, 1, 0, 0, 0)
+
+            expect(result).to eq(expected)
+            expect(result.zone).to eq(expected.zone)
+          end
+        end
+
+        it "should return same Time value" do
+          value = Time.utc(2010, 1, 1, 12, 34, 56)
+          expect(type_cast_value(value)).to eq(value)
+        end
+
+        it "should return as Time with same component values" do
+          expect(type_cast_value(DateTime.civil_from_format(:utc, 2010, 1, 1, 12, 34, 56))).to eq(Time.utc(2010, 1, 1, 12, 34, 56))
+        end
 
-      it "should return same Time in correct zone if timezone aware" do
-        value = Time.utc(2010, 1, 1, 12, 34, 56)
-        result = type_cast_value(value)
-        expect(result).to eq(Time.zone.local(2010, 1, 1, 23, 34, 56))
-        expect(result.zone).to eq('AEDT')
+        it "should return same Time in correct zone if timezone aware" do
+          value = Time.utc(2010, 1, 1, 12, 34, 56)
+          result = type_cast_value(value)
+
+          expect(result).to eq(Time.zone.local(2010, 1, 1, 20, 34, 56))
+          expect(result.zone).to eq('AWST')
+        end
       end
 
-      it 'should return nil for invalid value types' do
-        expect(type_cast_value(12)).to eq(nil)
+      context "not time zone aware" do
+        let(:time_zone_aware) { false }
+
+        it "should return Date as Time value" do
+          expect(type_cast_value(Date.new(2010, 1, 1))).to eq(Time.local(2010, 1, 1, 0, 0, 0))
+        end
+
+        it "should return same Time value" do
+          value = Time.utc(2010, 1, 1, 12, 34, 56)
+          expect(type_cast_value(Time.utc(2010, 1, 1, 12, 34, 56))).to eq(value)
+        end
+
+        it "should return as Time with same component values" do
+          expect(type_cast_value(DateTime.civil_from_format(:utc, 2010, 1, 1, 12, 34, 56))).to eq(Time.utc(2010, 1, 1, 12, 34, 56))
+        end
       end
     end
 
@@ -195,10 +230,6 @@ RSpec.describe ValidatesTimeliness::Converter do
     end
 
     context "restriction shorthand" do
-      before do
-        Timecop.freeze(Time.mktime(2010, 1, 1, 0, 0, 0))
-      end
-
       it 'should evaluate :now as current time' do
         expect(evaluate(:now, person)).to eq(Time.now)
       end

data/spec/validates_timeliness/extensions/date_time_select_spec.rb

@@ -115,7 +115,11 @@ RSpec.describe 'ValidatesTimeliness::Extensions::DateTimeSelect' do
 
   describe "time_select" do
     before do
-      Timecop.freeze Time.mktime(2009,1,1)
+      travel_to Time.mktime(2009,1,1)
+    end
+
+    after do
+      travel_back
     end
 
     it "should use param values when attribute is nil" do
@@ -158,5 +162,5 @@ RSpec.describe 'ValidatesTimeliness::Extensions::DateTimeSelect' do
       expect(@output).not_to have_tag("select[id=person_#{attribute}_#{index}i] option[selected=selected]")
     end
   end
-  
+
 end

data/spec/validates_timeliness/validator/is_at_spec.rb

@@ -1,6 +1,10 @@
 RSpec.describe ValidatesTimeliness::Validator, ":is_at option" do
   before do
-    Timecop.freeze(Time.local(2010, 1, 1, 0, 0, 0))
+    travel_to Time.local(2010, 1, 1, 0, 0, 0)
+  end
+
+  after do
+    travel_back
   end
 
   describe "for date type" do

data/spec/validates_timeliness/validator_spec.rb

@@ -1,6 +1,10 @@
 RSpec.describe ValidatesTimeliness::Validator do
   before do
-    Timecop.freeze(Time.local(2010, 1, 1, 0, 0, 0))
+    travel_to Time.local(2010, 1, 1, 0, 0, 0)
+  end
+
+  after do
+    travel_back
   end
 
   describe "Model.validates with :timeliness option" do

data/validates_timeliness.gemspec

@@ -3,19 +3,30 @@ $:.push File.expand_path("../lib", __FILE__)
 require "validates_timeliness/version"
 
 Gem::Specification.new do |s|
+
+  github_url    = 'https://github.com/adzap/validates_timeliness'
+
   s.name        = "validates_timeliness"
   s.version     = ValidatesTimeliness::VERSION
   s.authors     = ["Adam Meehan"]
   s.summary     = %q{Date and time validation plugin for Rails which allows custom formats}
   s.description = %q{Adds validation methods to ActiveModel for validating dates and times. Works with multiple ORMS.}
   s.email       = %q{adam.meehan@gmail.com}
-  s.homepage    = %q{http://github.com/adzap/validates_timeliness}
+  s.homepage    = github_url
   s.license     = "MIT"
 
   s.require_paths    = ["lib"]
-  s.files            = `git ls-files`.split("\n") - %w{ .gitignore .rspec Gemfile Gemfile.lock autotest/discover.rb Appraisals Travis.yml } - Dir['gemsfiles/*']
+  s.files            = `git ls-files`.split("\n") - %w{ .gitignore .rspec Gemfile Gemfile.lock autotest/discover.rb Appraisals } - Dir['gemsfiles/*']
   s.test_files       = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.extra_rdoc_files = ["README.rdoc", "CHANGELOG.rdoc", "LICENSE"]
+  s.extra_rdoc_files = ["README.md", "CHANGELOG.md", "LICENSE"]
+
+  s.metadata = {
+    "bug_tracker_uri" => "#{github_url}/issues",
+    "changelog_uri"   => "#{github_url}/blob/master/CHANGELOG.md",
+    "source_code_uri" => "#{github_url}",
+    "wiki_uri"        => "#{github_url}/wiki",
+  }
 
-  s.add_runtime_dependency(%q<timeliness>, [">= 0.3.10", "< 1"])
+  s.add_runtime_dependency("activemodel", [">= 6.0.0", "< 7"])
+  s.add_runtime_dependency("timeliness", [">= 0.3.10", "< 1"])
 end