concerns_on_rails 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d4b68b3625ea62546fa003654e7bd0618a56b09b615b406dcaed12f16560338
-  data.tar.gz: 4d048584cdf09f1eb9859a4cca0ccd64182b331bfa8a6ffb897ff61ab1c4636a
+  metadata.gz: d359c073e004cdacffbfeaf9e588abb581bf6794a631211fc3eca309f9522e31
+  data.tar.gz: c686a9ef9f5fa323a7d59ba4786e58c6d0a78265e65e01526036350b1ec8bc26
 SHA512:
-  metadata.gz: 8797f42f52e32309614fa95bf2a52b0a17e6adff54f07bbdcc9f9f27863a92fdfe0dfec1a14d7ad9b34285e25abc6a12cf37194a4da4532874a29d0fc7a13b01
-  data.tar.gz: e60133f68c2b4778cdea6b34fdcddd279eee5076ef060c009734c9e42eda3d379d65c9adfa847dd30dcb47e06e4a39c88313644fa248e407a5d60e242e8e3756
+  metadata.gz: 85af55992f8dad780dcbe588df3b8df21f042d46337eb331b85638040a1c016be004d17387e894fca8f787d8c1995b0d89f694fd9af9315cb4743ff556799d94
+  data.tar.gz: cd515ebcec0029801f5483872d94d7e833bbba64b0cd00da2247744e78c8789178ce950b4f0a52023612e19f8e3b2e40e6198800291a5e42655198e585692288

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 <!-- CHANGELOG.md -->
 
+## 1.5.0 (2026-05-16)
+
+### Added
+- Expirable: Single-timestamp expiry for tokens, API keys, sessions, and similar records. Adds `expirable_by` macro, `.active` / `.expired` / `.expiring_within(duration)` scopes, predicates (`active?`, `expired?`), mutators (`expire!`, `extend_expiry!`), and `time_until_expiry`. `nil` expiry means "never expires"; the expiry boundary is exclusive.
+
+## 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,8 @@ 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
+- ⏳ `Expirable`: Single-timestamp expiry with `.active` / `.expired` / `.expiring_within(duration)` scopes and `expire!` / `extend_expiry!` / `time_until_expiry` helpers
 
 ---
 
@@ -238,6 +240,119 @@ 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.
+
+---
+
+### 7. ⏳ Expirable
+
+For records with a single expiry timestamp — auth tokens, API keys, sessions, password-reset links, invitations.
+
+```ruby
+class ApiToken < ApplicationRecord
+  include ConcernsOnRails::Expirable
+
+  # Default field: :expires_at
+  expirable_by
+end
+
+token = ApiToken.create!(expires_at: 1.hour.from_now)
+token.active?               # => true
+token.expired?              # => false
+token.time_until_expiry     # => ActiveSupport::Duration (~1.hour)
+
+ApiToken.active                       # nil expiry OR future expiry
+ApiToken.expired                      # past expiry
+ApiToken.expiring_within(1.day)       # future expiry within the next 1.day
+```
+
+#### Mutators
+
+```ruby
+token.expire!                       # sets expires_at to now
+token.expire!(2.hours.from_now)     # sets to an explicit time
+token.extend_expiry!(by: 1.day)     # pushes expiry forward
+```
+
+`extend_expiry!` is "smart" about the base:
+- If `expires_at` is nil or already in the past, the new value is `now + by`.
+- If `expires_at` is still in the future, `by` is added to the existing value.
+
+#### Custom field name
+
+```ruby
+class License < ApplicationRecord
+  include ConcernsOnRails::Expirable
+
+  expirable_by :valid_until
+end
+```
+
+#### Notes
+- `nil` `expires_at` means **never expires** (the record stays `active?`).
+- The expiry boundary is **exclusive**: at exactly `expires_at`, the record is `expired?`.
+- No `default_scope` is added; chain `.active` explicitly to filter.
+- `Expirable` overlaps with `Schedulable`'s open-ended pattern (`schedulable_by starts_at: nil, ends_at: :expires_at`). Use `Expirable` when the API ergonomics around expiry — `active?`, `expire!`, `extend_expiry!`, `expiring_within` — fit your domain better; use `Schedulable` when you also need a start time.
+
+---
+
 ## 🛠️ Development
 
 To build the gem:

data/lib/concerns_on_rails/expirable.rb

@@ -0,0 +1,85 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Expirable
+    extend ActiveSupport::Concern
+
+    DEFAULT_FIELD = :expires_at
+
+    included do
+      class_attribute :expirable_field, instance_accessor: false, default: DEFAULT_FIELD
+
+      scope :active, lambda {
+        column = arel_table[expirable_field]
+        where(column.eq(nil).or(column.gt(Time.zone.now)))
+      }
+
+      scope :expired, lambda {
+        where(arel_table[expirable_field].lteq(Time.zone.now))
+      }
+
+      scope :expiring_within, lambda { |duration|
+        column = arel_table[expirable_field]
+        now = Time.zone.now
+        where(column.gt(now)).where(column.lteq(now + duration))
+      }
+    end
+
+    class_methods do
+      # Configure the expiry column.
+      # Example:
+      #   expirable_by                  # uses :expires_at
+      #   expirable_by :valid_until
+      def expirable_by(field = DEFAULT_FIELD)
+        self.expirable_field = field.to_sym
+
+        return if column_names.include?(expirable_field.to_s)
+
+        raise ArgumentError, "ConcernsOnRails::Expirable: expirable_field '#{expirable_field}' does not exist in the database"
+      end
+    end
+
+    def active?
+      !expired?
+    end
+
+    # nil means never expires; equal-to-now is treated as expired (exclusive boundary).
+    def expired?
+      value = self[self.class.expirable_field]
+      return false if value.nil?
+
+      value <= Time.zone.now
+    end
+
+    def expire!(time = Time.zone.now)
+      update(self.class.expirable_field => time)
+    end
+
+    # Push expiry forward by `by:`. If the record has no expiry yet, or has
+    # already expired, the new expiry is `now + by`. Otherwise it's added to
+    # the existing expiry.
+    def extend_expiry!(by:)
+      update(self.class.expirable_field => expiry_extension_base + by)
+    end
+
+    # Returns an ActiveSupport::Duration of how long until expiry, or nil
+    # when there's no expiry set, or 0.seconds when already expired.
+    def time_until_expiry
+      value = self[self.class.expirable_field]
+      return nil if value.nil?
+
+      now = Time.zone.now
+      return 0.seconds if value <= now
+
+      (value - now).seconds
+    end
+
+    private
+
+    def expiry_extension_base
+      value = self[self.class.expirable_field]
+      now = Time.zone.now
+      value.nil? || value <= now ? now : value
+    end
+  end
+end

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.5.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -5,6 +5,8 @@ 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"
+require "concerns_on_rails/expirable"
 
 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.5.0
 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
@@ -70,8 +70,10 @@ files:
 - CODE_OF_CONDUCT.md
 - README.md
 - lib/concerns_on_rails.rb
+- lib/concerns_on_rails/expirable.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 +93,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:
   - - ">="