concerns_on_rails 1.4.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e784268a8fb00ef3e77b613eca3ddc44da0ca95e0f9f1784ce019356f2f5905
-  data.tar.gz: fdc824e479b2607b097762debf8940c622044f47a108a5482729e9b74c1233c0
+  metadata.gz: d359c073e004cdacffbfeaf9e588abb581bf6794a631211fc3eca309f9522e31
+  data.tar.gz: c686a9ef9f5fa323a7d59ba4786e58c6d0a78265e65e01526036350b1ec8bc26
 SHA512:
-  metadata.gz: ae9b3876ae0eea6a02f51710d33074aba898bc1ab22609a33cfb27a8eb1747c5d4c12ef01fc1de180026658adf0f4d1d788842abc5f83322616d80dac35ac238
-  data.tar.gz: '09cb150b92adbcd6ab21b670b122d42ad6f71bcbb4616e5bfa89ac2cdc385fc8e42cbac98f8b11d3c2d9bba462c32a0fa2d8e9bd46c5b6e3e0f8407e41242e97'
+  metadata.gz: 85af55992f8dad780dcbe588df3b8df21f042d46337eb331b85638040a1c016be004d17387e894fca8f787d8c1995b0d89f694fd9af9315cb4743ff556799d94
+  data.tar.gz: cd515ebcec0029801f5483872d94d7e833bbba64b0cd00da2247744e78c8789178ce950b4f0a52023612e19f8e3b2e40e6198800291a5e42655198e585692288

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 <!-- 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

data/README.md

@@ -12,6 +12,7 @@ A simple collection of reusable Rails concerns to keep your models clean and DRY
 - ❌ `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
 
 ---
 
@@ -300,6 +301,58 @@ promo.reschedule!(starts_at: 1.day.from_now,
 
 ---
 
+### 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/version.rb

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

data/lib/concerns_on_rails.rb

@@ -6,6 +6,7 @@ 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.5.0
 platform: ruby
 authors:
 - Ethan Nguyen
@@ -70,6 +70,7 @@ 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