active_date_range 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca443decbae6f02f3b89ec4177942c925eb20fb00fe70b809d96d0573a4d332a
-  data.tar.gz: 915e82bd0b6449839876d7a193ad2430bd76bb810bedf31cd8b45c6c0abdabbd
+  metadata.gz: fa7f0092dab70e955754434aa37df4f7c0c11c5461d54b377c68d935ad115330
+  data.tar.gz: 44658f76ff5dca0336804ce7b7dc44fee1b96699365bd04e8bbf93741ff77f75
 SHA512:
-  metadata.gz: ff38e2d4be8755802f6ef51cb487366bd81341dd62948b38e463f6c583920fd5c4ec344052f3d9a0588bd60c8d04b25a12a41c8f0020dca3f80d879daea59120
-  data.tar.gz: e9dc0f34eca52082773c9c6fa2a4609af3955a4731c56ded61a5d94af357185348f98b724b029eb4b5e31e08469c27c6f860e7b07bd4ef712a49cf42be6247a3
+  metadata.gz: e7363eeba6c6e8747afd3e3f576fe2d3b24fbe03b17b30de980458fe4e65b9a13a31344a31207d9ae09fe8d0f7a7e97589e6c697f9564fa7977bbf227e80ac01
+  data.tar.gz: 5a3d15754ce33007ae78e56a0790ac5ede08f34a043d72e0e9866f61f912b2ebec9081af7df285927f83b3d6fd762c20bb4cbb11ae0bf411b7499966f7306e6e

data/CHANGELOG.md

@@ -1,3 +1,41 @@
+## 0.5.3
+
+* Add `safe_parse`, which returns `nil` instead of raising for input that isn't a valid date range. Use it for input you don't control, like a query parameter or a form field:
+
+```ruby
+DateRange.safe_parse("202101..202112") # => DateRange(2021-01-01..2021-12-31)
+DateRange.safe_parse("test")           # => nil
+DateRange.safe_parse("202112..202101") # => nil
+```
+
+  *wesselmoneybird*
+
+* Add a `safe: true` option to the `:date_range` ActiveModel type, which casts to `nil` instead of raising. Use it for attributes fed by input you don't control, so a validation can report the problem:
+
+```ruby
+attribute :period, :date_range, safe: true
+```
+
+  *wesselmoneybird*
+
+## 0.5.2
+
+* Add calendar-aware `DateRangeValidator` for ActiveModel validations. Unlike `validates_length_of` which compares day counts (causing `1.month` to use ~30.44 day averages), this validator uses date arithmetic so that February (28 or 29 days) correctly satisfies `minimum_duration: 1.month`:
+
+```ruby
+validates :period, date_range: { minimum_duration: 1.month }
+validates :period, date_range: { maximum_duration: 1.year }
+validates :period, date_range: { exact_duration: 3.months }
+validates :period, date_range: { duration: 1.month..1.year }
+validates :period, date_range: { bounded: true }
+validates :period, date_range: { full_periods_of: :month }
+validates :period, date_range: { starts_on: :beginning_of_month }
+validates :period, date_range: { ends_on: :end_of_month }
+validates :period, date_range: { covers: -> { Date.today } }
+```
+
+  *Edwin Vlieg*
+
 ## 0.5.1
 
 * Return `Float::INFINITY` from `size` for boundless ranges, making `validates_length_of` correctly reject them.

data/Gemfile.lock

@@ -1,16 +1,16 @@
 PATH
   remote: .
   specs:
-    active_date_range (0.5.1)
+    active_date_range (0.5.3)
       activesupport (~> 8.0)
       i18n (~> 1.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (8.0.3)
-      actionview (= 8.0.3)
-      activesupport (= 8.0.3)
+    actionpack (8.1.2)
+      actionview (= 8.1.2)
+      activesupport (= 8.1.2)
       nokogiri (>= 1.8.5)
       rack (>= 2.2.4)
       rack-session (>= 1.0.1)
@@ -18,22 +18,22 @@ GEM
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
       useragent (~> 0.16)
-    actionview (8.0.3)
-      activesupport (= 8.0.3)
+    actionview (8.1.2)
+      activesupport (= 8.1.2)
       builder (~> 3.1)
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
-    activemodel (8.0.3)
-      activesupport (= 8.0.3)
-    activesupport (8.0.3)
+    activemodel (8.1.2)
+      activesupport (= 8.1.2)
+    activesupport (8.1.2)
       base64
-      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
@@ -41,102 +41,102 @@ GEM
       uri (>= 0.13.1)
     ast (2.4.3)
     base64 (0.3.0)
-    benchmark (0.4.1)
     benchmark-ips (2.14.0)
-    bigdecimal (3.3.0)
+    bigdecimal (4.0.1)
     builder (3.3.0)
     coderay (1.1.3)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.4)
-    crass (1.0.6)
-    date (3.4.1)
+    concurrent-ruby (1.3.7)
+    connection_pool (3.0.2)
+    crass (1.0.7)
+    date (3.5.1)
     drb (2.2.3)
-    erb (5.0.3)
+    erb (6.0.1)
     erubi (1.13.1)
-    ffi (1.17.2)
-    ffi (1.17.2-x86_64-linux-gnu)
-    formatador (1.2.1)
+    ffi (1.17.3)
+    ffi (1.17.3-x86_64-linux-gnu)
+    formatador (1.2.3)
       reline
-    guard (2.19.1)
+    guard (2.20.1)
       formatador (>= 0.2.4)
       listen (>= 2.7, < 4.0)
       logger (~> 1.6)
       lumberjack (>= 1.0.12, < 2.0)
       nenv (~> 0.1)
       notiffany (~> 0.0)
-      ostruct (~> 0.6)
       pry (>= 0.13.0)
       shellany (~> 0.0)
       thor (>= 0.18.1)
     guard-compat (1.2.1)
-    guard-minitest (2.4.6)
+    guard-minitest (3.0.0)
       guard-compat (~> 1.2)
-      minitest (>= 3.0)
-    i18n (1.14.7)
+      minitest (>= 5.0.4, < 7.0)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    io-console (0.8.1)
-    irb (1.15.2)
+    io-console (0.8.2)
+    irb (1.17.0)
       pp (>= 0.6.0)
+      prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.15.1)
+    json (2.18.1)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    listen (3.9.0)
+    listen (3.10.0)
+      logger
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
-    loofah (2.24.1)
+    loofah (2.25.2)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
     lumberjack (1.4.2)
     memory_profiler (1.1.0)
     method_source (1.1.0)
     mini_portile2 (2.8.9)
-    minitest (5.25.5)
+    minitest (5.27.0)
     nenv (0.3.0)
-    nokogiri (1.18.10)
+    nokogiri (1.19.4)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    nokogiri (1.18.10-x86_64-linux-gnu)
+    nokogiri (1.19.4-x86_64-linux-gnu)
       racc (~> 1.4)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    ostruct (0.6.3)
     parallel (1.27.0)
-    parser (3.3.9.0)
+    parser (3.3.10.2)
       ast (~> 2.4.1)
       racc
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.5.1)
-    pry (0.15.2)
+    prism (1.9.0)
+    pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    psych (5.2.6)
+      reline (>= 0.6.0)
+    psych (5.3.1)
       date
       stringio
     racc (1.8.1)
-    rack (3.2.2)
+    rack (3.2.5)
     rack-session (2.1.1)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
     rack-test (2.2.0)
       rack (>= 1.3)
-    rackup (2.2.1)
+    rackup (2.3.1)
       rack (>= 3)
     rails-dom-testing (2.3.0)
       activesupport (>= 5.0.0)
       minitest
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.6.2)
-      loofah (~> 2.21)
+    rails-html-sanitizer (1.7.1)
+      loofah (~> 2.25, >= 2.25.2)
       nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
-    railties (8.0.3)
-      actionpack (= 8.0.3)
-      activesupport (= 8.0.3)
+    railties (8.1.2)
+      actionpack (= 8.1.2)
+      activesupport (= 8.1.2)
       irb (~> 1.13)
       rackup (>= 1.0.0)
       rake (>= 12.2)
@@ -144,18 +144,18 @@ GEM
       tsort (>= 0.2)
       zeitwerk (~> 2.6)
     rainbow (3.1.1)
-    rake (13.3.0)
+    rake (13.3.1)
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rdoc (6.15.0)
+    rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
     regexp_parser (2.11.3)
-    reline (0.6.2)
+    reline (0.6.3)
       io-console (~> 0.5)
-    rubocop (1.81.1)
+    rubocop (1.84.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -163,20 +163,20 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     rubocop-packaging (0.6.0)
       lint_roller (~> 1.1.0)
       rubocop (>= 1.72.1, < 2.0)
-    rubocop-performance (1.26.0)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
-    rubocop-rails (2.33.4)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rails (2.34.3)
       activesupport (>= 4.2.0)
       lint_roller (~> 1.1)
       rack (>= 1.1)
@@ -185,17 +185,17 @@ GEM
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
     shellany (0.0.1)
-    stringio (3.1.7)
-    thor (1.4.0)
+    stringio (3.2.0)
+    thor (1.5.0)
     tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
-    uri (1.0.4)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
     useragent (0.16.11)
-    zeitwerk (2.7.3)
+    zeitwerk (2.7.5)
 
 PLATFORMS
   ruby
@@ -218,4 +218,4 @@ DEPENDENCIES
   rubocop-rails (~> 2.33)
 
 BUNDLED WITH
-   2.3.5
+   2.6.9

data/README.md

@@ -55,6 +55,14 @@ ActiveDateRange::DateRange.parse('20210101..20210115')
 
 Parse accepts three formats: `YYYYMM..YYYYMM`, `YYYYMMDD..YYYYMMDD` and any short hand like `this_month`.
 
+`parse` raises `InvalidDateRangeFormat` or `InvalidDateRange` on input it can't handle. For input you don't control, like a query parameter or a form field, use `safe_parse` instead. It returns `nil` in those cases, the same way `safe_constantize` relates to `constantize`:
+
+```ruby
+ActiveDateRange::DateRange.safe_parse('202101..202112') # => DateRange(2021-01-01..2021-12-31)
+ActiveDateRange::DateRange.safe_parse('test')           # => nil
+ActiveDateRange::DateRange.safe_parse('202112..202101') # => nil
+```
+
 ### The date range instance
 
 A `DateRange` object is an extension of a regular `Range` object. You can use [all methods available on `Range`](https://ruby-doc.org/core-3.0.0/Range.html):
@@ -126,6 +134,21 @@ class Report
 end
 ```
 
+The attribute raises on a value it can't parse. For an attribute fed by input you don't control, like a query parameter or a form field, pass `safe: true`. The attribute then casts to `nil` instead, so a validation can report the problem:
+
+```ruby
+class ReportFilter
+  include ActiveModel::Attributes
+  include ActiveModel::Validations
+
+  attribute :period, :date_range, safe: true
+
+  validates :period, date_range: { bounded: true }
+end
+
+ReportFilter.new(period: "test").period # => nil
+```
+
 ### Usage example
 
 Use the shorthands to link to a specific period:

data/lib/active_date_range/active_model_type.rb

@@ -2,8 +2,17 @@
 
 module ActiveDateRange
   class DateRangeType < ActiveModel::Type::String
+    # Pass <tt>safe: true</tt> for attributes fed by input you don't control, like a query
+    # parameter. The attribute then casts to nil instead of raising:
+    #
+    #   attribute :period, :date_range, safe: true
+    def initialize(safe: false)
+      @safe = safe
+      super()
+    end
+
     def cast(value)
-      ActiveDateRange::DateRange.parse(value)
+      @safe ? ActiveDateRange::DateRange.safe_parse(value) : ActiveDateRange::DateRange.parse(value)
     end
   end
 end

data/lib/active_date_range/date_range.rb

@@ -41,6 +41,19 @@ module ActiveDateRange
       DateRange.new(parse_date(begin_date), parse_date(end_date, last: true))
     end
 
+    # Parses a date range string like #parse, but returns nil when the input isn't a valid date
+    # range, the same way <tt>safe_constantize</tt> relates to <tt>constantize</tt>. Use this for
+    # input you don't control, like a query parameter or a form field.
+    #
+    #   DateRange.safe_parse("202101..202112") # => DateRange(2021-01-01..2021-12-31)
+    #   DateRange.safe_parse("test")           # => nil
+    #   DateRange.safe_parse("202112..202101") # => nil
+    def self.safe_parse(input)
+      parse(input)
+    rescue InvalidDateRangeFormat, InvalidDateRange
+      nil
+    end
+
     def self.parse_date(input, last: false)
       return if input.blank?
 

data/lib/active_date_range/locale/en.yml

@@ -39,3 +39,14 @@ en:
     long_quarter: "quarter %{quarter}"
     short_quarter: "Q%{quarter}"
     range: "%{begin} - %{end}"
+  errors:
+    messages:
+      not_a_date_range: "is not a valid date range"
+      unbounded: "must have both a start and end date"
+      duration_too_short: "is too short (minimum duration is %{duration})"
+      duration_too_long: "is too long (maximum duration is %{duration})"
+      wrong_duration: "has the wrong duration (should be %{duration})"
+      not_full_periods: "must consist of full %{period}s"
+      misaligned_start: "must start at the %{alignment}"
+      misaligned_end: "must end at the %{alignment}"
+      does_not_cover: "must include %{date}"

data/lib/active_date_range/validators/date_range_validator.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module ActiveDateRange
+  module Validators
+    class DateRangeValidator < ActiveModel::EachValidator
+      include ResolveValue
+
+      DURATION_OPTIONS = %i[minimum_duration maximum_duration exact_duration duration].freeze
+      GRANULARITY_MAP = {
+        month: :full_month?,
+        quarter: :full_quarter?,
+        year: :full_year?,
+        week: :full_week?
+      }.freeze
+      START_ALIGNMENT_MAP = {
+        beginning_of_month: :begin_at_beginning_of_month?,
+        beginning_of_quarter: :begin_at_beginning_of_quarter?,
+        beginning_of_year: :begin_at_beginning_of_year?,
+        beginning_of_week: :begin_at_beginning_of_week?
+      }.freeze
+      END_ALIGNMENT_MAP = {
+        end_of_month: ->(r) { r.end == r.end.at_end_of_month },
+        end_of_quarter: ->(r) { r.end == r.end.at_end_of_quarter },
+        end_of_year: ->(r) { r.end == r.end.at_end_of_year },
+        end_of_week: ->(r) { r.end == r.end.at_end_of_week }
+      }.freeze
+
+      def validate_each(record, attribute, value)
+        unless value.is_a?(ActiveDateRange::DateRange)
+          record.errors.add(attribute, :not_a_date_range, **options.except(*known_options))
+          return
+        end
+
+        validate_bounded(record, attribute, value)
+        validate_duration(record, attribute, value)
+        validate_full_periods_of(record, attribute, value)
+        validate_starts_on(record, attribute, value)
+        validate_ends_on(record, attribute, value)
+        validate_covers(record, attribute, value)
+      end
+
+      private
+        def known_options
+          DURATION_OPTIONS + %i[bounded full_periods_of starts_on ends_on covers message]
+        end
+
+        def validate_bounded(record, attribute, value)
+          return unless options[:bounded]
+
+          if value.boundless?
+            record.errors.add(attribute, :unbounded, **options.except(*known_options))
+          end
+        end
+
+        def validate_duration(record, attribute, value)
+          return if value.boundless?
+
+          if options[:duration]
+            range = resolve_value(record, options[:duration])
+            validate_minimum_duration(record, attribute, value, range.begin) if range.begin
+            validate_maximum_duration(record, attribute, value, range.end) if range.end
+          end
+
+          if options[:minimum_duration]
+            duration = resolve_value(record, options[:minimum_duration])
+            validate_minimum_duration(record, attribute, value, duration)
+          end
+
+          if options[:maximum_duration]
+            duration = resolve_value(record, options[:maximum_duration])
+            validate_maximum_duration(record, attribute, value, duration)
+          end
+
+          if options[:exact_duration]
+            duration = resolve_value(record, options[:exact_duration])
+            validate_exact_duration(record, attribute, value, duration)
+          end
+        end
+
+        def validate_minimum_duration(record, attribute, value, duration)
+          unless meets_minimum_duration?(value, duration)
+            record.errors.add(attribute, :duration_too_short,
+              duration: humanize_duration(duration),
+              **options.except(*known_options))
+          end
+        end
+
+        def validate_maximum_duration(record, attribute, value, duration)
+          unless meets_maximum_duration?(value, duration)
+            record.errors.add(attribute, :duration_too_long,
+              duration: humanize_duration(duration),
+              **options.except(*known_options))
+          end
+        end
+
+        def validate_exact_duration(record, attribute, value, duration)
+          unless meets_minimum_duration?(value, duration) && meets_maximum_duration?(value, duration)
+            record.errors.add(attribute, :wrong_duration,
+              duration: humanize_duration(duration),
+              **options.except(*known_options))
+          end
+        end
+
+        # Calendar-aware: Feb 1..Feb 28 with 1.month → begin + 1.month - 1.day = Feb 28 <= Feb 28 ✓
+        def meets_minimum_duration?(range, duration)
+          range.begin + duration - 1.day <= range.end
+        end
+
+        # Calendar-aware: Jan 1..Dec 31 with 1.year → begin + 1.year - 1.day = Dec 31 >= Dec 31 ✓
+        def meets_maximum_duration?(range, duration)
+          range.begin + duration - 1.day >= range.end
+        end
+
+        def validate_full_periods_of(record, attribute, value)
+          return unless options[:full_periods_of]
+
+          period = options[:full_periods_of].to_sym
+          method = GRANULARITY_MAP[period]
+
+          unless method && value.respond_to?(method) && value.public_send(method)
+            record.errors.add(attribute, :not_full_periods,
+              period: period,
+              **options.except(*known_options))
+          end
+        end
+
+        def validate_starts_on(record, attribute, value)
+          return unless options[:starts_on]
+
+          alignment = options[:starts_on].to_sym
+          method = START_ALIGNMENT_MAP[alignment]
+
+          unless method && value.respond_to?(method) && value.public_send(method)
+            record.errors.add(attribute, :misaligned_start,
+              alignment: alignment.to_s.tr("_", " "),
+              **options.except(*known_options))
+          end
+        end
+
+        def validate_ends_on(record, attribute, value)
+          return unless options[:ends_on]
+          return if value.end.nil?
+
+          alignment = options[:ends_on].to_sym
+          checker = END_ALIGNMENT_MAP[alignment]
+
+          unless checker&.call(value)
+            record.errors.add(attribute, :misaligned_end,
+              alignment: alignment.to_s.tr("_", " "),
+              **options.except(*known_options))
+          end
+        end
+
+        def validate_covers(record, attribute, value)
+          return unless options[:covers]
+
+          date = resolve_value(record, options[:covers])
+
+          unless value.cover?(date)
+            record.errors.add(attribute, :does_not_cover,
+              date: date,
+              **options.except(*known_options))
+          end
+        end
+
+        def humanize_duration(duration)
+          return duration.inspect unless duration.respond_to?(:parts)
+
+          duration.parts.map do |unit, amount|
+            label = amount == 1 ? unit.to_s.singularize : unit.to_s.pluralize
+            "#{amount} #{label}"
+          end.join(", ")
+        end
+    end
+  end
+end

data/lib/active_date_range/validators/resolve_value.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveDateRange
+  module Validators
+    module ResolveValue
+      private
+        def resolve_value(record, value)
+          case value
+          when Proc   then value.arity == 0 ? value.call : value.call(record)
+          when Symbol then record.send(value)
+          else value
+          end
+        end
+    end
+  end
+end

data/lib/active_date_range/validators.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "active_date_range/validators/resolve_value"
+require "active_date_range/validators/date_range_validator"
+
+# Register validator at top level so `validates :x, date_range: {}` works
+::DateRangeValidator = ActiveDateRange::Validators::DateRangeValidator

data/lib/active_date_range/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveDateRange
-  VERSION = "0.5.1"
+  VERSION = "0.5.3"
 end

data/lib/active_date_range.rb

@@ -12,6 +12,7 @@ require "active_date_range/version"
 require "active_date_range/date_range"
 require "active_date_range/humanizer"
 require "active_date_range/active_model_type"
+require "active_date_range/validators" if defined?(ActiveModel)
 
 module ActiveDateRange
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_date_range
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.3
 platform: ruby
 authors:
 - Edwin Vlieg
@@ -139,6 +139,9 @@ files:
 - lib/active_date_range/humanizer.rb
 - lib/active_date_range/i18n.rb
 - lib/active_date_range/locale/en.yml
+- lib/active_date_range/validators.rb
+- lib/active_date_range/validators/date_range_validator.rb
+- lib/active_date_range/validators/resolve_value.rb
 - lib/active_date_range/version.rb
 homepage: https://github.com/moneybird/active-date-range
 licenses: