concerns_on_rails 1.3.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d4b68b3625ea62546fa003654e7bd0618a56b09b615b406dcaed12f16560338
-  data.tar.gz: 4d048584cdf09f1eb9859a4cca0ccd64182b331bfa8a6ffb897ff61ab1c4636a
+  metadata.gz: 6e784268a8fb00ef3e77b613eca3ddc44da0ca95e0f9f1784ce019356f2f5905
+  data.tar.gz: fdc824e479b2607b097762debf8940c622044f47a108a5482729e9b74c1233c0
 SHA512:
-  metadata.gz: 8797f42f52e32309614fa95bf2a52b0a17e6adff54f07bbdcc9f9f27863a92fdfe0dfec1a14d7ad9b34285e25abc6a12cf37194a4da4532874a29d0fc7a13b01
-  data.tar.gz: e60133f68c2b4778cdea6b34fdcddd279eee5076ef060c009734c9e42eda3d379d65c9adfa847dd30dcb47e06e4a39c88313644fa248e407a5d60e242e8e3756
+  metadata.gz: ae9b3876ae0eea6a02f51710d33074aba898bc1ab22609a33cfb27a8eb1747c5d4c12ef01fc1de180026658adf0f4d1d788842abc5f83322616d80dac35ac238
+  data.tar.gz: '09cb150b92adbcd6ab21b670b122d42ad6f71bcbb4616e5bfa89ac2cdc385fc8e42cbac98f8b11d3c2d9bba462c32a0fa2d8e9bd46c5b6e3e0f8407e41242e97'

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 <!-- CHANGELOG.md -->
 
+## 1.4.2 (2026-05-16)
+
+### Added
+- Schedulable: Manage time-windowed records via `starts_at` / `ends_at` columns. Adds `schedulable_by` macro, scopes (`.current`, `.upcoming`, `.expired`, `.active_at(time)`), predicates (`current?`, `upcoming?`, `expired?`, `active_at?`), and mutators (`start!`, `finish!`, `reschedule!`). Supports custom column names and open-ended schedules (`starts_at: nil`).
+
+### Internal
+- Refactored `active_at?` into two private predicate helpers (`schedulable_started_by?` / `schedulable_not_ended_at?`) to satisfy `Metrics/CyclomaticComplexity`.
+
+### Notes
+- The `v1.4.0` and `v1.4.1` tags were created but never released to RubyGems (CI failed on `Gemfile.lock` regeneration and a RuboCop complexity check respectively). `1.4.2` is the first usable release of the Schedulable concern.
+
 ## 1.3.0 (2026-05-16)
 
 ### Added

data/README.md

@@ -11,6 +11,7 @@ A simple collection of reusable Rails concerns to keep your models clean and DRY
 - 📤 `Publishable`: Easily manage published/unpublished records using a simple `published_at` field
 - ❌ `SoftDeletable`: Soft delete records using a configurable timestamp field (e.g., `deleted_at`) with automatic scoping
 - 🔐 `Hashable`: Auto-generate a random hex/UUID/integer/custom-alphabet value on create, with a `regenerate_<field>!` helper
+- 🗓️ `Schedulable`: Manage time-windowed records via `starts_at` / `ends_at` with `.current`, `.upcoming`, `.expired`, and `.active_at(time)` scopes
 
 ---
 
@@ -238,6 +239,67 @@ hashable_by :code,        type: :custom,  length: 8,
 
 ---
 
+### 6. 🗓️ Schedulable
+
+Manage records with a time window using `starts_at` / `ends_at` columns.
+
+```ruby
+class Promotion < ApplicationRecord
+  include ConcernsOnRails::Schedulable
+
+  # Defaults: starts_at: :starts_at, ends_at: :ends_at
+  schedulable_by
+end
+
+promo = Promotion.create!(starts_at: 1.hour.ago, ends_at: 1.day.from_now)
+promo.current?   # => true
+promo.upcoming?  # => false
+promo.expired?   # => false
+
+Promotion.current                  # currently active
+Promotion.upcoming                 # starts_at in the future
+Promotion.expired                  # ends_at in the past
+Promotion.active_at(Time.zone.now) # active at any specific time
+```
+
+#### Custom column names
+
+```ruby
+class Event < ApplicationRecord
+  include ConcernsOnRails::Schedulable
+
+  schedulable_by starts_at: :starts_on, ends_at: :ends_on
+end
+```
+
+#### Open-ended start (only an expiry)
+
+```ruby
+class Coupon < ApplicationRecord
+  include ConcernsOnRails::Schedulable
+
+  schedulable_by starts_at: nil, ends_at: :expires_at
+end
+```
+
+#### Mutators
+
+```ruby
+promo.start!                                              # sets starts_at to now
+promo.finish!                                             # sets ends_at to now
+promo.reschedule!(starts_at: 1.day.from_now,
+                  ends_at: 2.days.from_now)               # sets both
+```
+
+#### Notes
+- Boundary semantics are **inclusive start, exclusive end**: a record is active at exactly `starts_at`, but not at exactly `ends_at`.
+- A `nil` `ends_at` means "no end" — the record stays active forever once started.
+- A `nil` `starts_at` means "not yet started" — the record is not active (unless `starts_at` is unconfigured).
+- No `default_scope` is added; chain `.current` (or any other scope) explicitly to filter.
+- `schedulable_by` validates that the configured columns exist and raises `ArgumentError` otherwise.
+
+---
+
 ## 🛠️ Development
 
 To build the gem:

data/lib/concerns_on_rails/schedulable.rb

@@ -0,0 +1,128 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Schedulable
+    extend ActiveSupport::Concern
+
+    DEFAULT_STARTS_AT_FIELD = :starts_at
+    DEFAULT_ENDS_AT_FIELD = :ends_at
+
+    included do
+      class_attribute :schedulable_starts_at_field, instance_accessor: false, default: DEFAULT_STARTS_AT_FIELD
+      class_attribute :schedulable_ends_at_field, instance_accessor: false, default: DEFAULT_ENDS_AT_FIELD
+
+      scope :active_at, lambda { |time|
+        starts_field = schedulable_starts_at_field
+        ends_field = schedulable_ends_at_field
+        relation = all
+        relation = relation.where(arel_table[starts_field].lteq(time)) if starts_field
+        relation = relation.where(arel_table[ends_field].eq(nil).or(arel_table[ends_field].gt(time))) if ends_field
+        relation
+      }
+
+      scope :current, -> { active_at(Time.zone.now) }
+
+      scope :upcoming, lambda {
+        field = schedulable_starts_at_field
+        next none unless field
+
+        where(arel_table[field].gt(Time.zone.now))
+      }
+
+      scope :expired, lambda {
+        field = schedulable_ends_at_field
+        next none unless field
+
+        where(arel_table[field].lteq(Time.zone.now))
+      }
+    end
+
+    class_methods do
+      # Configure the start/end timestamp columns.
+      # Example:
+      #   schedulable_by                                          # uses :starts_at and :ends_at
+      #   schedulable_by starts_at: :starts_on, ends_at: :ends_on
+      #   schedulable_by starts_at: nil, ends_at: :expires_at     # open-ended start
+      def schedulable_by(starts_at: DEFAULT_STARTS_AT_FIELD, ends_at: DEFAULT_ENDS_AT_FIELD)
+        self.schedulable_starts_at_field = starts_at&.to_sym
+        self.schedulable_ends_at_field = ends_at&.to_sym
+
+        if schedulable_starts_at_field.nil? && schedulable_ends_at_field.nil?
+          raise ArgumentError, "ConcernsOnRails::Schedulable: at least one of starts_at: or ends_at: must be configured"
+        end
+
+        [schedulable_starts_at_field, schedulable_ends_at_field].compact.each do |field|
+          next if column_names.include?(field.to_s)
+
+          raise ArgumentError, "ConcernsOnRails::Schedulable: field '#{field}' does not exist in the database"
+        end
+      end
+    end
+
+    # Is the record active at the given time? Inclusive start, exclusive end.
+    def active_at?(time)
+      schedulable_started_by?(time) && schedulable_not_ended_at?(time)
+    end
+
+    def current?
+      active_at?(Time.zone.now)
+    end
+
+    def upcoming?
+      field = self.class.schedulable_starts_at_field
+      value = field && self[field]
+      return false unless value
+
+      value > Time.zone.now
+    end
+
+    def expired?
+      field = self.class.schedulable_ends_at_field
+      value = field && self[field]
+      return false unless value
+
+      value <= Time.zone.now
+    end
+
+    def start!(time = Time.zone.now)
+      field = self.class.schedulable_starts_at_field
+      raise "ConcernsOnRails::Schedulable: starts_at field not configured" unless field
+
+      update(field => time)
+    end
+
+    def finish!(time = Time.zone.now)
+      field = self.class.schedulable_ends_at_field
+      raise "ConcernsOnRails::Schedulable: ends_at field not configured" unless field
+
+      update(field => time)
+    end
+
+    def reschedule!(starts_at:, ends_at:)
+      attrs = {}
+      starts_field = self.class.schedulable_starts_at_field
+      ends_field = self.class.schedulable_ends_at_field
+      attrs[starts_field] = starts_at if starts_field
+      attrs[ends_field] = ends_at if ends_field
+      update(attrs)
+    end
+
+    private
+
+    def schedulable_started_by?(time)
+      field = self.class.schedulable_starts_at_field
+      return true unless field
+
+      value = self[field]
+      !value.nil? && value <= time
+    end
+
+    def schedulable_not_ended_at?(time)
+      field = self.class.schedulable_ends_at_field
+      return true unless field
+
+      value = self[field]
+      value.nil? || value > time
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.3.0".freeze
+  VERSION = "1.4.2".freeze
 end

data/lib/concerns_on_rails.rb

@@ -5,6 +5,7 @@ require "concerns_on_rails/publishable"
 require "concerns_on_rails/sluggable"
 require "concerns_on_rails/soft_deletable"
 require "concerns_on_rails/hashable"
+require "concerns_on_rails/schedulable"
 
 module ConcernsOnRails
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.2
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-15 00:00:00.000000000 Z
+date: 2026-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -72,6 +72,7 @@ files:
 - lib/concerns_on_rails.rb
 - lib/concerns_on_rails/hashable.rb
 - lib/concerns_on_rails/publishable.rb
+- lib/concerns_on_rails/schedulable.rb
 - lib/concerns_on_rails/sluggable.rb
 - lib/concerns_on_rails/soft_deletable.rb
 - lib/concerns_on_rails/sortable.rb
@@ -91,7 +92,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="