concerns_on_rails 1.2.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 603d571510be78d62d3d71f071b703dbf70bf505e6463e1766e4a99c4c039012
-  data.tar.gz: eefa6a75c74a0ff0db01e129cc85c73af7ae3b16fb38c2ceab757ff5fc1e2656
+  metadata.gz: 6e784268a8fb00ef3e77b613eca3ddc44da0ca95e0f9f1784ce019356f2f5905
+  data.tar.gz: fdc824e479b2607b097762debf8940c622044f47a108a5482729e9b74c1233c0
 SHA512:
-  metadata.gz: 01b37a0a698df95131be947ebc0874c970dc1f4cadf591aca2de84b1bc4da8075967cc5d469a45713165d07c763e55c7296b34a621248bffa82e7af127c5b5b0
-  data.tar.gz: e0978b66b4208ef653563602e9b153f10f56867cd2ad821ae8323f12fad8eff9c917127f64ae567a0ffa62945b562c5244aed72e743419e47a22a1de8f121ad1
+  metadata.gz: ae9b3876ae0eea6a02f51710d33074aba898bc1ab22609a33cfb27a8eb1747c5d4c12ef01fc1de180026658adf0f4d1d788842abc5f83322616d80dac35ac238
+  data.tar.gz: '09cb150b92adbcd6ab21b670b122d42ad6f71bcbb4616e5bfa89ac2cdc385fc8e42cbac98f8b11d3c2d9bba462c32a0fa2d8e9bd46c5b6e3e0f8407e41242e97'

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 <!-- 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
+- Hashable: Auto-generate a random value on create (`:hex`, `:uuid`, `:integer`, or `:custom` alphabet). Adds `hashable_by` macro and a dynamic `regenerate_<field>!` instance method.
+
 ## 1.1.0 (2025-04-17)
 
 ### Added

data/README.md

@@ -10,6 +10,8 @@ A simple collection of reusable Rails concerns to keep your models clean and DRY
 - 🔢 `Sortable`: Sort records based on a field using `acts_as_list`, with flexible sorting field and direction
 - 📤 `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
 
 ---
 
@@ -194,6 +196,110 @@ end
 
 ---
 
+### 5. Hashable
+
+Auto-generate a random value (hex, UUID, fixed-digit integer, or custom-alphabet string) on create.
+
+```ruby
+class Order < ApplicationRecord
+  include ConcernsOnRails::Hashable
+
+  # Defaults: type: :hex, length: 16 (32-char hex string)
+  hashable_by :token
+end
+
+order = Order.create!
+order.token              # => "a3f7c9b1e2d40859e2f1c9b73d40a857"
+order.regenerate_token!  # rolls a new random value and persists it
+```
+
+#### Types
+
+```ruby
+hashable_by :token,       type: :hex,     length: 16
+hashable_by :external_id, type: :uuid
+hashable_by :code,        type: :integer, length: 6
+hashable_by :code,        type: :custom,  length: 8,
+            alphabet: "ABCDEFGHJKMNPQRSTUVWXYZ23456789"
+```
+
+| Type       | `length` means          | Example output           |
+|------------|-------------------------|--------------------------|
+| `:hex`     | byte count (output is `length * 2` hex chars) | `"a3f7c9b1e2d40859"` |
+| `:uuid`    | ignored                 | `"550e8400-e29b-41d4-a716-446655440000"` |
+| `:integer` | digit count             | `483921`                 |
+| `:custom`  | output length, samples from `alphabet:` | `"K7M3PQ9A"` |
+
+#### Notes
+- Auto-assigns on `before_create` only when the field is blank, so callers can still pass an explicit value.
+- A `regenerate_<field>!` instance method is defined dynamically to match the configured column.
+- No uniqueness retry is built in. For collision-prone configurations (e.g. short integer codes), add a unique index and rescue at the application level.
+- For fixed-width numeric codes (e.g. `000042`), use a string column — integer columns drop leading zeros.
+- If your model has `validates :<field>, presence: true`, switch to a `before_validation` callback in your model since the concern uses `before_create`.
+
+---
+
+### 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/hashable.rb

@@ -0,0 +1,77 @@
+require "active_support/concern"
+require "securerandom"
+
+module ConcernsOnRails
+  module Hashable
+    extend ActiveSupport::Concern
+
+    VALID_TYPES = %i[hex uuid integer custom].freeze
+
+    included do
+      class_attribute :hashable_field, instance_accessor: false
+      class_attribute :hashable_type, instance_accessor: false, default: :hex
+      class_attribute :hashable_length, instance_accessor: false, default: 16
+      class_attribute :hashable_alphabet, instance_accessor: false, default: nil
+    end
+
+    class_methods do
+      # Define hashable field and generation options.
+      # Example:
+      #   hashable_by :token
+      #   hashable_by :token, type: :hex, length: 16
+      #   hashable_by :external_id, type: :uuid
+      #   hashable_by :code, type: :integer, length: 6
+      #   hashable_by :code, type: :custom, length: 8, alphabet: "ABCDEFGHJKMNPQRSTUVWXYZ23456789"
+      def hashable_by(field, type: :hex, length: 16, alphabet: nil)
+        self.hashable_field = field.to_sym
+        self.hashable_type = type.to_sym
+        self.hashable_length = length.to_i
+        self.hashable_alphabet = alphabet
+
+        validate_hashable_options!
+        before_create :assign_hashable_value
+
+        define_method("regenerate_#{hashable_field}!") do
+          update!(self.class.hashable_field => self.class.generate_hashable_value)
+        end
+      end
+    end
+
+    class_methods do
+      # Generate a new random value using the configured type/length/alphabet.
+      def generate_hashable_value
+        case hashable_type
+        when :hex     then SecureRandom.hex(hashable_length)
+        when :uuid    then SecureRandom.uuid
+        when :integer then SecureRandom.random_number(10**hashable_length).to_s.rjust(hashable_length, "0").to_i
+        when :custom  then Array.new(hashable_length) { hashable_alphabet[SecureRandom.random_number(hashable_alphabet.size)] }.join
+        end
+      end
+
+      private
+
+      def validate_hashable_options!
+        unless column_names.include?(hashable_field.to_s)
+          raise ArgumentError, "ConcernsOnRails::Hashable: hashable_field '#{hashable_field}' does not exist in the database"
+        end
+
+        unless VALID_TYPES.include?(hashable_type)
+          raise ArgumentError, "ConcernsOnRails::Hashable: unknown type '#{hashable_type}'. Valid types: #{VALID_TYPES.join(', ')}"
+        end
+
+        return unless hashable_type == :custom && (!hashable_alphabet.is_a?(String) || hashable_alphabet.empty?)
+
+        raise ArgumentError, "ConcernsOnRails::Hashable: type :custom requires a non-empty alphabet: String"
+      end
+    end
+
+    # Assigns the generated value only when the field is blank,
+    # so callers can still pass an explicit value at create time.
+    def assign_hashable_value
+      field = self.class.hashable_field
+      return if self[field].present?
+
+      self[field] = self.class.generate_hashable_value
+    end
+  end
+end

data/lib/concerns_on_rails/publishable.rb

@@ -8,7 +8,7 @@ module ConcernsOnRails
       class_attribute :publishable_field, instance_accessor: false, default: :published_at
 
       scope :published, -> { where(arel_table[publishable_field].lteq(Time.zone.now)) }
-      scope :unpublished, -> {
+      scope :unpublished, lambda {
         where(arel_table[publishable_field].eq(nil).or(arel_table[publishable_field].gt(Time.zone.now)))
       }
     end
@@ -17,9 +17,9 @@ module ConcernsOnRails
       def publishable_by(field = nil)
         self.publishable_field = field || :published_at
 
-        unless column_names.include?(publishable_field.to_s)
-          raise ArgumentError, "ConcernsOnRails::Publishable: publishable_field '#{publishable_field}' does not exist in the database"
-        end
+        return if column_names.include?(publishable_field.to_s)
+
+        raise ArgumentError, "ConcernsOnRails::Publishable: publishable_field '#{publishable_field}' does not exist in the database"
       end
     end
 
@@ -44,6 +44,7 @@ module ConcernsOnRails
     def published?
       value = self[self.class.publishable_field]
       return false unless value.present?
+
       value.respond_to?(:<=) ? value <= Time.zone.now : true
     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/sluggable.rb

@@ -12,6 +12,7 @@ module ConcernsOnRails
       self.sluggable_field ||= :name
 
       extend FriendlyId
+
       # we need use a lambda to access the instance variable
       # instead of friendly_id :slug_source, use: :slugged
       friendly_id :slug_source, use: :slugged
@@ -37,11 +38,12 @@ module ConcernsOnRails
       end
 
       private
+
       # Validate sluggable_field exists in database
       def validate_sluggable_field!
-        unless column_names.include?(sluggable_field.to_s)
-          raise ArgumentError, "ConcernsOnRails::Sluggable: sluggable_field '#{sluggable_field}' does not exist in the database"
-        end
+        return if column_names.include?(sluggable_field.to_s)
+
+        raise ArgumentError, "ConcernsOnRails::Sluggable: sluggable_field '#{sluggable_field}' does not exist in the database"
       end
     end
 
@@ -55,4 +57,4 @@ module ConcernsOnRails
       respond_to?(field) ? send(field) : to_s
     end
   end
-end
+end

data/lib/concerns_on_rails/soft_deletable.rb

@@ -8,14 +8,13 @@ module ConcernsOnRails
       # declare class attributes and set default values
       class_attribute :soft_delete_field, instance_accessor: false, default: :deleted_at
       class_attribute :soft_delete_touch, instance_accessor: false, default: true
-      
+
       # scopes
       scope :active, -> { unscope(where: soft_delete_field).where(soft_delete_field => nil) }
       scope :without_deleted, -> { unscope(where: soft_delete_field).where(soft_delete_field => nil) }
       scope :soft_deleted, -> { unscope(where: soft_delete_field).where.not(soft_delete_field => nil) }
       # Optionally, uncomment to hide deleted by default:
       default_scope { without_deleted }
-
     end
 
     class_methods do
@@ -26,9 +25,9 @@ module ConcernsOnRails
         self.soft_delete_field = field || :deleted_at
         self.soft_delete_touch = touch
 
-        unless column_names.include?(soft_delete_field.to_s)
-          raise ArgumentError, "ConcernsOnRails::SoftDeletable: soft_delete_field '#{soft_delete_field}' does not exist in the database"
-        end
+        return if column_names.include?(soft_delete_field.to_s)
+
+        raise ArgumentError, "ConcernsOnRails::SoftDeletable: soft_delete_field '#{soft_delete_field}' does not exist in the database"
       end
 
       # Override destroy_all to perform soft delete on all records
@@ -50,24 +49,26 @@ module ConcernsOnRails
 
     def soft_delete!
       return true if deleted?
+
       before_soft_delete
       result = if self.class.soft_delete_touch
-        update(self.class.soft_delete_field => Time.zone.now)
-      else
-        update_column(self.class.soft_delete_field, Time.zone.now)
-      end
+                 update(self.class.soft_delete_field => Time.zone.now)
+               else
+                 update_column(self.class.soft_delete_field, Time.zone.now)
+               end
       after_soft_delete if result
       result
     end
 
     def restore!
       return true unless deleted?
+
       before_restore
       result = if self.class.soft_delete_touch
-        update(self.class.soft_delete_field => nil)
-      else
-        update_column(self.class.soft_delete_field, nil)
-      end
+                 update(self.class.soft_delete_field => nil)
+               else
+                 update_column(self.class.soft_delete_field, nil)
+               end
       after_restore if result
       result
     end
@@ -77,15 +78,15 @@ module ConcernsOnRails
       self.class.unscoped.where(self.class.primary_key => id).delete_all
       freeze
     end
-  
+
     def deleted?
       self[self.class.soft_delete_field].present?
     end
 
     # alias methods
     # define here to avoid issue: undefined method `deleted?' for module `ConcernsOnRails::SoftDeletable'
-    alias_method :is_soft_deleted?, :deleted?
-    alias_method :soft_deleted?, :deleted?
+    alias is_soft_deleted? deleted?
+    alias soft_deleted? deleted?
 
     def is_really_deleted?
       !self.class.unscoped.exists?(id)

data/lib/concerns_on_rails/sortable.rb

@@ -26,6 +26,7 @@ module ConcernsOnRails
         unless column_names.include?(sortable_field.to_s)
           raise ArgumentError, "#{name}: '#{sortable_field}' column not found. Call `sortable_by :your_column` to configure the sort field."
         end
+
         order(sortable_field => sortable_direction)
       end
     end
@@ -40,7 +41,9 @@ module ConcernsOnRails
       #   sortable_by position: :desc
       #
       #   sortable_by :position, use_acts_as_list: false
-      def sortable_by(field_config, use_acts_as_list: true)
+      def sortable_by(field_config = nil, use_acts_as_list: true, **field_options)
+        field_config = field_options if field_config.nil? && field_options.any?
+
         # parse field_config
         field, direction = parse_sortable_config(field_config)
 
@@ -57,6 +60,7 @@ module ConcernsOnRails
       end
 
       private
+
       def parse_sortable_config(config)
         if config.is_a?(Hash)
           # extract key and value
@@ -71,9 +75,9 @@ module ConcernsOnRails
 
       # Validate sortable_field exists in database
       def validate_sortable_field!
-        unless column_names.include?(sortable_field.to_s)
-          raise ArgumentError, "ConcernsOnRails::Sortable: sortable_field '#{sortable_field}' does not exist in the database"
-        end
+        return if column_names.include?(sortable_field.to_s)
+
+        raise ArgumentError, "ConcernsOnRails::Sortable: sortable_field '#{sortable_field}' does not exist in the database"
       end
     end
   end

data/lib/concerns_on_rails/version.rb

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

data/lib/concerns_on_rails.rb

@@ -4,6 +4,8 @@ require "concerns_on_rails/sortable"
 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.2.0
+  version: 1.4.2
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-10 00:00:00.000000000 Z
+date: 2026-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -70,7 +70,9 @@ files:
 - CODE_OF_CONDUCT.md
 - README.md
 - 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
@@ -90,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:
   - - ">="