recurable 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4934fe3e2307e356b7cd8a4ec8be35c0ca8369d38dbf0c2fa883403f062c1b95
+  data.tar.gz: 51dfeca41d7311251e0b8e691a5237ccb241a5e3197da03d523f12d0e821156b
+SHA512:
+  metadata.gz: d1cff6b649fdbc7fba5dc7e644dc0ac0c6a7be9daa43d29b47d23a8eac04a4e99edbdd0b40c4f138d07e125ffe34e9d331fbe7464d9c4ceaf2d614284709af0d
+  data.tar.gz: 2614f0cdb426943ad623c7d797f304dae23566c41af691a014dcd7af9820b7b7669f6781c98dd4a09072690ce9c058344d535de1c417ed80c5ded46e98fbb08c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Rosenberg, Matt Lewis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,311 @@
+# Recurable
+
+iCal RRULE recurrence library for Ruby with optional Rails/ActiveRecord integration. Full [RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.10) RRULE support.
+
+## Quick Start: Standalone
+
+No Rails required. Just ActiveModel and ActiveSupport.
+
+```ruby
+require 'recurable/recurrence'
+
+# Build a recurrence from attributes
+recurrence = Recurrence.new(frequency: 'DAILY', interval: 1)
+recurrence.to_rrule   # => "FREQ=DAILY;INTERVAL=1"
+
+# Parse an existing RRULE string
+recurrence = Recurrence.from_rrule('FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE,FR')
+recurrence.frequency  # => "WEEKLY"
+recurrence.interval   # => 2
+recurrence.by_day     # => ["MO", "WE", "FR"]
+
+# Frequency predicates
+recurrence.weekly?    # => true
+recurrence.daily?     # => false
+
+# Frequency comparison (YEARLY < MONTHLY < ... < MINUTELY)
+yearly  = Recurrence.new(frequency: 'YEARLY')
+monthly = Recurrence.new(frequency: 'MONTHLY')
+yearly < monthly      # => true
+```
+
+## Quick Start: With Rails
+
+Add the gem, then prepend the `Recurable` concern on any model with an `rrule` string column:
+
+```ruby
+class Plan < ApplicationRecord
+  include Recurable
+end
+
+plan = Plan.new
+plan.frequency = 'MONTHLY'
+plan.interval = 3
+plan.by_month_day = [15]
+plan.rrule                    # => #<Recurrence> with to_rrule "FREQ=MONTHLY;INTERVAL=3;BYMONTHDAY=15"
+plan.valid?                   # validates both the model and the recurrence
+plan.monthly?                 # => true
+plan.humanize_recurrence      # => "every 3 months on the 15th"
+
+# Time projection
+plan.recurrence_times(
+  project_from: Time.zone.local(2026, 1, 1),
+  project_to:   Time.zone.local(2026, 7, 1)
+)
+
+# Boundary queries
+plan.last_recurrence_time_before(Time.zone.now, dt_start_at: plan.created_at)
+plan.next_recurrence_time_after(Time.zone.now, dt_start_at: plan.created_at)
+```
+
+## Installation
+
+**Standalone** (no Rails):
+
+```ruby
+gem 'recurable'
+
+# Then in your code:
+require 'recurable/recurrence'
+```
+
+**With Rails**:
+
+```ruby
+gem 'recurable'
+
+# Then in your code:
+require 'recurable'
+```
+
+Requires ActiveRecord >= 7.1 for `serialize` with `default:` keyword support.
+
+## Recurrence Attributes
+
+`Recurrence` is a pure Ruby data class with named attributes mapping to [RFC 5545 RRULE components](https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.10):
+
+| Attribute | Type | RRULE Component | Example | Description |
+|-----------|------|-----------------|---------|-------------|
+| `frequency` | String | `FREQ` | `"MONTHLY"` | Every month |
+| `interval` | Integer | `INTERVAL` | `3` | Every 3rd frequency period |
+| `by_day` | Array\<String\> | `BYDAY` | `["+2MO"]` | The second Monday |
+| `by_day` | | | `["MO", "WE", "FR"]` | Monday, Wednesday, and Friday |
+| `by_month_day` | Array\<Integer\> | `BYMONTHDAY` | `[1, 15]` | The 1st and 15th of the month |
+| `by_set_pos` | Array\<Integer\> | `BYSETPOS` | `[-1]` | The last occurrence in the set |
+| `count` | Integer | `COUNT` | `10` | Stop after 10 occurrences |
+| `repeat_until` | Time (UTC) | `UNTIL` | `Time.utc(2026, 12, 31)` | Stop after December 31, 2026 |
+| `hour_of_day` | Array\<Integer\> | `BYHOUR` | `[9, 17]` | At 9 AM and 5 PM |
+| `minute_of_hour` | Array\<Integer\> | `BYMINUTE` | `[0, 30]` | At :00 and :30 past the hour |
+| `second_of_minute` | Array\<Integer\> | `BYSECOND` | `[0, 30]` | At :00 and :30 past the minute |
+| `month_of_year` | Array\<Integer\> | `BYMONTH` | `[1, 6]` | In January and June |
+| `day_of_year` | Array\<Integer\> | `BYYEARDAY` | `[1, -1]` | First and last day of the year |
+| `week_of_year` | Array\<Integer\> | `BYWEEKNO` | `[1, 52]` | Weeks 1 and 52 |
+| `week_start` | String | `WKST` | `"MO"` | Weeks start on Monday |
+
+All array attributes accept scalars (auto-wrapped) or arrays. `nil` and `[]` are normalized to `nil`.
+
+```ruby
+recurrence = Recurrence.new
+recurrence.by_day = 'MO'       # => stored as ["MO"]
+recurrence.by_day = %w[MO FR]  # => stored as ["MO", "FR"]
+recurrence.by_day = []          # => stored as nil
+```
+
+### Monthly Recurrence Options
+
+Monthly recurrences support two modes, determined by which attributes are set:
+
+```ruby
+# By date: "the 15th of every month"
+Recurrence.new(frequency: 'MONTHLY', interval: 1, by_month_day: [15])
+  .monthly_option         # => "DATE"
+
+# By nth weekday: "the last Friday of every month"
+Recurrence.new(frequency: 'MONTHLY', interval: 1, by_day: ['FR'], by_set_pos: [-1])
+  .monthly_option         # => "NTH_DAY"
+```
+
+### RRULE Generation & Parsing
+
+```ruby
+# Generate: attributes → RRULE string
+recurrence = Recurrence.new(frequency: 'MONTHLY', interval: 1, by_day: ['FR'], by_set_pos: [-1])
+recurrence.to_rrule  # => "FREQ=MONTHLY;INTERVAL=1;BYDAY=FR;BYSETPOS=-1"
+
+# Parse: RRULE string → Recurrence
+parsed = Recurrence.from_rrule('FREQ=MONTHLY;INTERVAL=1;BYDAY=FR;BYSETPOS=-1')
+parsed.by_day        # => ["FR"]
+parsed.by_set_pos    # => [-1]
+
+# Round-trip
+parsed.to_rrule == recurrence.to_rrule  # => true
+```
+
+### COUNT and UNTIL
+
+`COUNT` and `UNTIL` are mutually exclusive per RFC 5545. The `Recurable` concern validates this:
+
+```ruby
+# Limit by count
+Recurrence.new(frequency: 'DAILY', interval: 1, count: 10)
+  .to_rrule  # => "FREQ=DAILY;INTERVAL=1;COUNT=10"
+
+# Limit by end date (stored as UTC)
+Recurrence.new(frequency: 'DAILY', interval: 1, repeat_until: Time.utc(2026, 12, 31, 23, 59, 59))
+  .to_rrule  # => "FREQ=DAILY;INTERVAL=1;UNTIL=20261231T235959Z"
+```
+
+## Time Projection
+
+`RruleUtils` is an includable module for DST-aware time projection. Any object with a `recurrence` method returning a `Recurrence` can include it. The `Recurable` concern includes it automatically.
+
+```ruby
+# Project occurrences in a date range
+model.recurrence_times(
+  project_from: Time.zone.local(2026, 1, 1),
+  project_to:   Time.zone.local(2026, 2, 1),
+  dt_start_at:  model.created_at          # optional; defaults to project_from
+)
+
+# Find the last occurrence before a boundary
+model.last_recurrence_time_before(Time.zone.now, dt_start_at: model.created_at)
+
+# Find the next occurrence after a boundary
+model.next_recurrence_time_after(Time.zone.now, dt_start_at: model.created_at)
+
+# Human-readable description
+model.humanize_recurrence  # => "every 3 months on the 15th"
+```
+
+Time projection delegates to the [rrule](https://github.com/square/ruby-rrule) gem with timezone-aware DST handling.
+
+### DST Boundary Behavior
+
+Daily and sub-daily recurrences behave differently across DST transitions.
+
+**Spring forward** — On March 12, 2023 in `America/New_York`, clocks jump from 2:00 AM EST to 3:00 AM EDT.
+
+A daily recurrence at 1:00 PM is unaffected — the wall-clock time stays consistent across the boundary:
+
+```
+Mar 11  1:00 PM EST
+Mar 12  1:00 PM EDT  ← DST transition happened earlier this day, but 1 PM still fires
+Mar 13  1:00 PM EDT
+```
+
+An hourly recurrence skips the non-existent 2:00 AM hour, producing 23 unique hours:
+
+```
+12:00 AM EST
+ 1:00 AM EST
+ 3:00 AM EDT  ← 2:00 AM doesn't exist, jumps straight to 3:00 AM
+ 4:00 AM EDT
+ ...
+11:00 PM EDT
+```
+
+**Fall back** — On November 5, 2023, clocks fall back from 2:00 AM EDT to 1:00 AM EST. The 1:00 AM hour occurs twice, but the duplicate is removed:
+
+```
+12:00 AM EDT
+ 1:00 AM EDT
+ 1:00 AM EST  ← duplicate wall-clock hour, removed by .uniq
+ 2:00 AM EST
+ 3:00 AM EST
+ ...
+11:00 PM EST
+```
+
+This produces 24 unique wall-clock hours despite the repeated 1:00 AM.
+
+Try it yourself:
+
+```ruby
+Time.use_zone('America/New_York') do
+  spring_forward = Time.zone.local(2023, 3, 12)
+
+  # Daily at 1 PM: fires every day regardless of DST
+  daily = Recurrence.new(frequency: 'DAILY', interval: 1)
+  model = Struct.new(:recurrence).new(daily).extend(RruleUtils)
+  model.recurrence_times(
+    project_from: Time.zone.local(2023, 3, 11, 13),
+    project_to:   Time.zone.local(2023, 3, 13, 13),
+    dt_start_at:  Time.zone.local(2023, 3, 11, 13)
+  ).map { |t| t.strftime('%b %d %l:%M %p %Z') }
+  # => ["Mar 11  1:00 PM EST", "Mar 12  1:00 PM EDT", "Mar 13  1:00 PM EDT"]
+
+  # Hourly on spring-forward day: 23 unique hours, 2 AM is skipped
+  hourly = Recurrence.new(frequency: 'HOURLY', interval: 1)
+  model  = Struct.new(:recurrence).new(hourly).extend(RruleUtils)
+  hours  = model.recurrence_times(
+    project_from: spring_forward.beginning_of_day,
+    project_to:   spring_forward.end_of_day,
+    dt_start_at:  spring_forward
+  )
+  hours.size # => 23
+
+  # Hourly on fall-back day: 24 unique hours, duplicate 1 AM removed
+  fall_back = Time.zone.local(2023, 11, 5)
+  model = Struct.new(:recurrence).new(hourly).extend(RruleUtils)
+  hours = model.recurrence_times(
+    project_from: fall_back.beginning_of_day,
+    project_to:   fall_back.end_of_day,
+    dt_start_at:  Time.zone.local(2023, 11, 1)
+  )
+  hours.size # => 24
+end
+```
+
+## The Recurable Concern
+
+`Recurable` is an `ActiveSupport::Concern` included by ActiveRecord models with an `rrule` string column:
+
+```ruby
+class Plan < ApplicationRecord
+  include Recurable
+end
+```
+
+It provides:
+
+1. **Serialization** — `serialize :rrule, RecurrenceSerializer` transparently converts between DB strings and `Recurrence` objects
+2. **Delegation** — all `Recurrence` attributes and frequency predicates are delegated to the `rrule` object
+3. **Validation** — recurrence attributes are validated with appropriate constraints (frequency inclusion, interval positivity, array value ranges, BYDAY pattern matching, COUNT/UNTIL mutual exclusivity)
+4. **Time projection** — includes `RruleUtils` for `recurrence_times`, `last_recurrence_time_before`, `next_recurrence_time_after`, and `humanize_recurrence`
+
+## Supported Frequencies
+
+| Frequency | Period | Example |
+|-----------|--------|---------|
+| `YEARLY` | ~365 days | `FREQ=YEARLY;INTERVAL=1;BYMONTH=1,6` |
+| `MONTHLY` | ~31 days | `FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15` |
+| `WEEKLY` | 7 days | `FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE,FR` |
+| `DAILY` | 1 day | `FREQ=DAILY;INTERVAL=1` |
+| `HOURLY` | 1 hour | `FREQ=HOURLY;INTERVAL=4;BYMINUTE=0,30` |
+| `MINUTELY` | 1 minute | `FREQ=MINUTELY;INTERVAL=15` |
+
+## Constants
+
+`Recurrence` exposes named constants for use in validations and logic:
+
+```ruby
+Recurrence::DAILY          # => "DAILY"
+Recurrence::MONDAY         # => "MO"
+Recurrence::SUNDAY         # => "SU"
+Recurrence::MONTHLY_DATE   # => "DATE"
+Recurrence::MONTHLY_NTH_DAY # => "NTH_DAY"
+Recurrence::FREQUENCIES    # => {"YEARLY"=>365, "MONTHLY"=>31, ...}
+Recurrence::DAYS_OF_WEEK   # => ["SU", "MO", "TU", "WE", "TH", "FR", "SA"]
+Recurrence::NTH_DAY_OF_MONTH # => {first: 1, second: 2, ..., last: -1}
+```
+
+## Requirements
+
+- Ruby >= 3.3
+- ActiveModel >= 7.1
+- ActiveSupport >= 7.1
+- ActiveRecord >= 7.1 _(only if using the Recurable concern)_
+
+## License
+
+[MIT](LICENSE)

data/lib/recurable/array_inclusion_validator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'active_model'
+
+class ArrayInclusionValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    allowed = options[:in]
+    Array(value).each do |element|
+      valid = allowed.is_a?(Regexp) ? allowed.match?(element) : allowed.include?(element)
+      record.errors.add(attribute, "contains invalid value: #{element}") unless valid
+    end
+  end
+end

data/lib/recurable/recurrence.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'version'
+
+# Core model representing an iCal RRULE recurrence pattern.
+#
+# Pure Ruby data class — no Rails dependencies. Handles RRULE string
+# generation/parsing with named attributes and frequency comparison.
+#
+#   recurrence = Recurrence.new(frequency: 'DAILY', interval: 1)
+#   recurrence.rrule   # => "FREQ=DAILY;INTERVAL=1"
+#   recurrence.daily?  # => true
+#
+class Recurrence
+  # Provides `<`, `<=`, `>`, `>=`, `==`, `between?`, and `clamp` by defining `<=>`.
+  include Comparable
+
+  def initialize(**attrs)
+    unknown = attrs.keys - ATTRIBUTES
+    raise ArgumentError, "Unknown attribute(s): #{unknown.join(', ')}" if unknown.any?
+
+    attrs.each { |attr, value| public_send(:"#{attr}=", value) }
+  end
+
+  # iCal BYDAY codes derived from Date::DAYNAMES, ordered Sunday–Saturday.
+  # Exposes class constants: Recurrence::SUNDAY => 'SU', Recurrence::MONDAY => 'MO', etc.
+  # `const_set` returns the value of the constant and map returns an array of the transformed values.
+  DAYS_OF_WEEK = Date::DAYNAMES.map { |name| const_set(name.upcase, name[0, 2].upcase) }.freeze
+  # Ordered by increasing frequency. Values are approximate period in days.
+  # Order used by Comparable#<=> for RruleAdapter strategy selection.
+  # Exposes class constants: Recurrence::YEARLY, Recurrence::DAILY, etc. and defines frequency predicates.
+  FREQUENCIES = {
+    'YEARLY' => 365,
+    'MONTHLY' => 31,
+    'WEEKLY' => 7,
+    'DAILY' => 1,
+    'HOURLY' => 1 / 24.0,
+    'MINUTELY' => 1 / 24.0 / 60.0
+  }.each_key do |freq|
+    const_set(freq, freq)
+    define_method(:"#{freq.downcase}?") { freq == frequency }
+  end.freeze
+  FREQ_ORDER = FREQUENCIES.keys.each_with_index.to_h.freeze
+
+  # Exposes class constants: Recurrence::MONTHLY_DATE => 'DATE', Recurrence::MONTHLY_NTH_DAY => 'NTH_DAY'.
+  MONTHLY_OPTIONS = %w[DATE NTH_DAY].each { |opt| const_set("MONTHLY_#{opt}", opt) }.freeze
+  # Maps symbolic positions to iCal BYSETPOS integers. Positive 1–4 covers typical forward
+  # positions; negative -1/-2 covers "last" and "second to last" (deeper negatives are better
+  # expressed counting forward). A month has at most 5 of any single weekday.
+  NTH_DAY_OF_MONTH = {
+    first: 1,
+    second: 2,
+    third: 3,
+    fourth: 4,
+    last: -1,
+    second_to_last: -2
+  }.freeze
+
+  # Positive = calendar date (1st–28th), negative = from end (-1 = last day, -2 = second to last).
+  # Capped at ±28 because February has 28 days in a common year.
+  DATE_OF_MONTH_RANGE = ((-28..-1).to_a + (1..28).to_a).freeze
+  HOUR_OF_DAY_RANGE = 0..23
+  MINUTE_OF_HOUR_RANGE = SECOND_OF_MINUTE_RANGE = 0..59
+  MONTH_OF_YEAR_RANGE = 1..12
+  DAY_OF_YEAR_RANGE = ((-366..-1).to_a + (1..366).to_a).freeze
+  WEEK_OF_YEAR_RANGE = ((-53..-1).to_a + (1..53).to_a).freeze
+  BYDAY_PATTERN = /\A[+-]?\d*(?:#{Regexp.union(DAYS_OF_WEEK).source})\z/
+  # Parses an RRULE UNTIL string (e.g. "20261231T235959Z") into a Time object.
+  UNTIL_PATTERN = /\A(?<Y>\d{4})(?<m>\d{2})(?<d>\d{2})T(?<H>\d{2})(?<M>\d{2})(?<S>\d{2})Z\z/
+
+  ATTRIBUTES = %i[
+    by_day by_month_day by_set_pos count day_of_year frequency hour_of_day interval
+    minute_of_hour month_of_year repeat_until
+    second_of_minute week_of_year week_start
+  ].freeze
+
+  ARRAY_ATTRIBUTES = %i[
+    by_day by_month_day by_set_pos day_of_year hour_of_day minute_of_hour
+    month_of_year second_of_minute week_of_year
+  ].freeze
+
+  attr_accessor(*(ATTRIBUTES - ARRAY_ATTRIBUTES - %i[repeat_until]))
+  attr_reader :repeat_until, *ARRAY_ATTRIBUTES
+
+  class << self
+    def from_rrule(rrule)
+      new(**attributes_from(parse_components(rrule)))
+    end
+
+    private
+
+    # Parses "FREQ=DAILY;INTERVAL=1;BYDAY=MO…" into {"FREQ"=>"DAILY", "BYDAY"=>"MO", …}
+    def parse_components(rrule)
+      rrule.split(';').each_with_object({}) do |pair, hash|
+        next if pair.strip.empty?
+
+        key, value = pair.split('=', 2)
+        hash[key] = value
+      end
+    end
+
+    def attributes_from(components)
+      {
+        by_day: split_list(components['BYDAY']),
+        by_month_day: split_int_list(components['BYMONTHDAY']),
+        by_set_pos: split_int_list(components['BYSETPOS']),
+        count: components['COUNT']&.to_i,
+        day_of_year: split_int_list(components['BYYEARDAY']),
+        frequency: components['FREQ'],
+        hour_of_day: split_int_list(components['BYHOUR']),
+        interval: components['INTERVAL']&.to_i || 1,
+        minute_of_hour: split_int_list(components['BYMINUTE']),
+        month_of_year: split_int_list(components['BYMONTH']),
+        repeat_until: components['UNTIL'],
+        second_of_minute: split_int_list(components['BYSECOND']),
+        week_of_year: split_int_list(components['BYWEEKNO']),
+        week_start: components['WKST']
+      }
+    end
+
+    def split_list(csv)
+      return unless csv
+
+      list = csv.split(',')
+      list unless list.empty?
+    end
+
+    def split_int_list(csv)
+      split_list(csv)&.map(&:to_i)
+    end
+  end
+
+  ARRAY_ATTRIBUTES.each do |attr|
+    define_method(:"#{attr}=") do |value|
+      coerced = Array(value)
+      instance_variable_set(:"@#{attr}", coerced.empty? ? nil : coerced)
+    end
+  end
+
+  def repeat_until=(value)
+    @repeat_until = case value
+                    when nil, '' then nil
+                    when Time then value.utc
+                    when String then parse_until(value)
+                    end
+  end
+
+  def to_rrule
+    {
+      'FREQ' => frequency,
+      'INTERVAL' => interval,
+      'COUNT' => non_blank(count),
+      'UNTIL' => format_until(repeat_until),
+      'BYDAY' => join_list(by_day),
+      'BYMONTHDAY' => join_list(by_month_day),
+      'BYMONTH' => join_list(month_of_year),
+      'BYHOUR' => join_list(hour_of_day),
+      'BYMINUTE' => join_list(minute_of_hour),
+      'BYSECOND' => join_list(second_of_minute),
+      'BYYEARDAY' => join_list(day_of_year),
+      'BYWEEKNO' => join_list(week_of_year),
+      'BYSETPOS' => join_list(by_set_pos),
+      'WKST' => non_blank(week_start)
+    }.filter_map { |k, v| "#{k}=#{v}" unless v.nil? }.join(';')
+  end
+
+  def monthly_option
+    return unless frequency == 'MONTHLY'
+    return 'NTH_DAY' if by_set_pos&.any? && by_day&.any?
+
+    'DATE' if by_month_day&.any?
+  end
+
+  def by_month_day_option? = monthly_option == 'DATE'
+  def by_set_pos_option? = monthly_option == 'NTH_DAY'
+
+  def <=>(other)
+    return super unless other.is_a?(self.class)
+
+    FREQ_ORDER[frequency] <=> FREQ_ORDER[other.frequency]
+  end
+
+  private
+
+  def non_blank(value)
+    value unless value.nil? || value.to_s.strip.empty?
+  end
+
+  def join_list(array)
+    non_blank(array&.join(','))
+  end
+
+  def format_until(time)
+    time&.utc&.strftime('%Y%m%dT%H%M%SZ')
+  end
+
+  def parse_until(value)
+    return unless (match = non_blank(value)&.match(UNTIL_PATTERN))
+
+    Time.utc(match[:Y], match[:m], match[:d], match[:H], match[:M], match[:S])
+  end
+end

data/lib/recurable/recurrence_serializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'recurrence'
+
+# Serializes between RRULE strings and Recurrence objects. A Recurrence fully
+# represents an RRULE — it can be constructed from the string and stored back as one.
+class RecurrenceSerializer
+  def self.load(rrule)
+    Recurrence.from_rrule(rrule) if rrule.present?
+  end
+
+  def self.dump(recurrence_instance) = recurrence_instance&.to_rrule
+end

data/lib/recurable/rrule_utils.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/time/zones'
+require 'rrule'
+
+module RruleUtils
+  SUB_DAILY_NOUNS = { 'HOURLY' => 'hour', 'MINUTELY' => 'minute' }.freeze
+
+  def recurrence_times(project_from:, project_to:, dt_start_at: nil)
+    dt_start_at ||= project_from
+    RRule::Rule.new(recurrence.to_rrule, dtstart: dt_start_at, tzid: Time.zone.tzinfo.identifier)
+               .between(project_from, project_to)
+               .uniq
+  end
+
+  def last_recurrence_time_before(before, dt_start_at:)
+    project_from = (Recurrence::FREQUENCIES[recurrence.frequency] * recurrence.interval).days.ago(before)
+    recurrence_times(project_from:, project_to: before, dt_start_at:).last
+  end
+
+  def next_recurrence_time_after(after, dt_start_at:)
+    project_to = (Recurrence::FREQUENCIES[recurrence.frequency] * recurrence.interval).days.since(after)
+    recurrence_times(project_from: after, project_to:, dt_start_at:).first
+  end
+
+  def humanize_recurrence
+    noun = SUB_DAILY_NOUNS[recurrence.frequency]
+    return RRule::Rule.new(recurrence.to_rrule).humanize unless noun
+
+    "every #{recurrence.interval == 1 ? noun : "#{recurrence.interval} #{noun}s"}"
+  end
+end

data/lib/recurable/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Recurable
+  VERSION = '1.0.0'
+end

data/lib/recurable.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+require_relative 'recurable/version'
+require_relative 'recurable/recurrence'
+require_relative 'recurable/rrule_utils'
+require_relative 'recurable/array_inclusion_validator'
+require_relative 'recurable/recurrence_serializer'
+# A concern to be included by ActiveRecord models that persist an rrule string to the database. This concern gives them
+# access to a Recurrence object (instead of an rrule string) which encapsulates user-friendly getters and
+# setters for the rrule, as well as validation, display, and projection concerns.
+module Recurable
+  extend ActiveSupport::Concern
+
+  included do
+    include RruleUtils
+
+    # This concern should only be used with a model that has an `rrule` string column.
+    serialize :rrule, coder: RecurrenceSerializer, default: Recurrence.new(frequency: 'DAILY', interval: 1)
+    alias_attribute :recurrence, :rrule
+
+    delegate(*Recurrence::ATTRIBUTES.flat_map { |attr| [attr, :"#{attr}="] },
+             *Recurrence::FREQUENCIES.each_key.map { |freq| :"#{freq.downcase}?" },
+             :by_month_day_option?, :by_set_pos_option?,
+             to: :rrule)
+
+    validates :by_day, array_inclusion: { in: Recurrence::BYDAY_PATTERN }, allow_blank: true
+    validates :by_month_day, array_inclusion: { in: Recurrence::DATE_OF_MONTH_RANGE }, if: :by_month_day_option?
+    validates :by_set_pos, array_inclusion: { in: Recurrence::NTH_DAY_OF_MONTH.values }, if: :by_set_pos_option?
+    validates :count, numericality: { only_integer: true, greater_than: 0 }, allow_blank: true
+    validates :day_of_year, array_inclusion: { in: Recurrence::DAY_OF_YEAR_RANGE }, allow_blank: true
+    validates :frequency, presence: true, inclusion: { in: Recurrence::FREQUENCIES.keys }
+    validates :hour_of_day, array_inclusion: { in: Recurrence::HOUR_OF_DAY_RANGE }, allow_blank: true
+    validates :interval, presence: true, numericality: { only_integer: true, greater_than: 0 }
+    validates :minute_of_hour, array_inclusion: { in: Recurrence::MINUTE_OF_HOUR_RANGE }, allow_blank: true
+    validates :month_of_year, array_inclusion: { in: Recurrence::MONTH_OF_YEAR_RANGE }, allow_blank: true
+    validates :second_of_minute, array_inclusion: { in: Recurrence::SECOND_OF_MINUTE_RANGE }, allow_blank: true
+    validates :week_of_year, array_inclusion: { in: Recurrence::WEEK_OF_YEAR_RANGE }, allow_blank: true
+    validates :week_start, inclusion: { in: Recurrence::DAYS_OF_WEEK }, allow_blank: true
+    validate :count_and_until_mutually_exclusive
+  end
+
+  private
+
+  def count_and_until_mutually_exclusive
+    errors.add(:base, 'COUNT and UNTIL are mutually exclusive') if count.present? && repeat_until.present?
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: recurable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Aaron Rosenberg
+- Matt Lewis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: rrule
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+description: |
+  Provides Recurrence, RruleUtils, and RecurrenceSerializer as a standalone library
+  for working with iCal RRULE recurrence patterns (full RFC 5545 support). Optionally
+  integrates with Rails via the Recurable concern for transparent ActiveRecord
+  serialization. Handles DST-safe projection for all frequencies from minutely through yearly.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/recurable.rb
+- lib/recurable/array_inclusion_validator.rb
+- lib/recurable/recurrence.rb
+- lib/recurable/recurrence_serializer.rb
+- lib/recurable/rrule_utils.rb
+- lib/recurable/version.rb
+homepage: https://github.com/agrberg/recurable
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/agrberg/recurable
+  bug_tracker_uri: https://github.com/agrberg/recurable/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: iCal RRULE recurrence library with optional Rails integration
+test_files: []