concerns_on_rails 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8810e1d51d69ba3de04b06ec9f372aca86611a0ac555b0d0652284680b35d37a
-  data.tar.gz: d6d8d480ffac223059af1942c0161ab7eff86b6af5320852838a2e5c0c9e3611
+  metadata.gz: 0d4b68b3625ea62546fa003654e7bd0618a56b09b615b406dcaed12f16560338
+  data.tar.gz: 4d048584cdf09f1eb9859a4cca0ccd64182b331bfa8a6ffb897ff61ab1c4636a
 SHA512:
-  metadata.gz: fdc35dc31371b5bef4f0897494250778dcb794598136c21db6d33db5b165a0fc95151c2939ee610312249e3a6012738e0041673ce592846515eaa38b0a8dd453
-  data.tar.gz: b9704d4368ba22504f7b2bf6081832fd2e4a6014f74ea9a88abc73ab55dc0e4af07cc89d09cff6442d59357fa0907503eb19900e4165ef241e5183527e1b512f
+  metadata.gz: 8797f42f52e32309614fa95bf2a52b0a17e6adff54f07bbdcc9f9f27863a92fdfe0dfec1a14d7ad9b34285e25abc6a12cf37194a4da4532874a29d0fc7a13b01
+  data.tar.gz: e60133f68c2b4778cdea6b34fdcddd279eee5076ef060c009734c9e42eda3d379d65c9adfa847dd30dcb47e06e4a39c88313644fa248e407a5d60e242e8e3756

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 <!-- CHANGELOG.md -->
 
+## 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,7 @@ 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
 
 ---
 
@@ -127,29 +128,113 @@ Soft delete records using a timestamp field (default: `deleted_at`).
 class User < ApplicationRecord
   include ConcernsOnRails::SoftDeletable
 
-  soft_deletable_by :deleted_at
+  # Optional: customize field and touch behavior
+  soft_deletable_by :deleted_at, touch: true
 end
+```
 
-user = User.create!(name: "Alice")
-user.soft_delete!
-user.deleted? # => true
-
+#### Scopes
+```ruby
 User.without_deleted   # => returns only active users
 User.soft_deleted      # => returns soft-deleted users
+User.active            # => same as without_deleted
 User.all               # => returns only non-deleted by default (default_scope applied)
+```
+
+#### Soft delete and restore
+```ruby
+user.soft_delete!      # Soft delete the user (sets deleted_at)
+user.deleted?          # => true
+user.soft_deleted?     # => true (alias)
+user.is_soft_deleted?  # => true (alias)
 
-user.restore!
-user.deleted? # => false
+user.restore!          # Restore the user (sets deleted_at to nil)
+user.deleted?          # => false
 ```
 
-Additional features:
-- Default field is `deleted_at`, can be configured
-- Automatically applies `default_scope` to hide soft-deleted records
-- Scopes: `without_deleted`, `soft_deleted`, `active`
-- Methods: `soft_delete!`, `restore!`, `deleted?`, `really_delete!`
-- Callbacks: `before_soft_delete`, `after_soft_delete`, `before_restore`, `after_restore`
-- Touch support when soft deleting or restoring (can be turned off)
+#### Permanently delete
+```ruby
+user.really_delete!    # Hard delete the record from DB
+```
+
+#### Soft delete/hard delete all records
+```ruby
+User.destroy_all           # Soft delete all users (sets deleted_at)
+User.really_destroy_all    # Hard delete ALL users (removes from DB)
+```
+
+#### Callbacks (Hooks)
+You can use the following hooks to run logic before/after soft delete or restore:
+```ruby
+class User < ApplicationRecord
+  include ConcernsOnRails::SoftDeletable
+
+  def before_soft_delete
+    # Code to run before soft delete
+  end
+
+  def after_soft_delete
+    # Code to run after soft delete
+  end
+
+  def before_restore
+    # Code to run before restore
+  end
+
+  def after_restore
+    # Code to run after restore
+  end
+end
+```
+
+#### Notes
+- Default field is `deleted_at`, can be changed with `soft_deletable_by :your_field`
+- `touch: false` to skip updating updated_at when soft deleting/restoring
 - Aliases for `deleted?`: `soft_deleted?`, `is_soft_deleted?`
+- All scopes and methods work seamlessly with ActiveRecord
+
+---
+
+### 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`.
 
 ---
 

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

@@ -4,28 +4,22 @@ module ConcernsOnRails
   module Publishable
     extend ActiveSupport::Concern
 
-    # instance methods
     included do
-      # declare class attributes and set default values
-      class_attribute :publishable_field, instance_accessor: false
-      self.publishable_field ||= :published_at
+      class_attribute :publishable_field, instance_accessor: false, default: :published_at
+
+      scope :published, -> { where(arel_table[publishable_field].lteq(Time.zone.now)) }
+      scope :unpublished, lambda {
+        where(arel_table[publishable_field].eq(nil).or(arel_table[publishable_field].gt(Time.zone.now)))
+      }
     end
 
-    # class methods
     class_methods do
-      # Define publishable field
-      # Example:
-      #   publishable_by :published_at
       def publishable_by(field = nil)
         self.publishable_field = field || :published_at
 
-        # validate publishable_field exists in database
-        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)
 
-        scope :published, -> { where(arel_table[publishable_field].not_eq(nil)) }
-        scope :unpublished, -> { where(arel_table[publishable_field].eq(nil)) }
+        raise ArgumentError, "ConcernsOnRails::Publishable: publishable_field '#{publishable_field}' does not exist in the database"
       end
     end
 
@@ -48,7 +42,10 @@ module ConcernsOnRails
     # Example:
     #   record.published?
     def published?
-      self[self.class.publishable_field].present?
+      value = self[self.class.publishable_field]
+      return false unless value.present?
+
+      value.respond_to?(:<=) ? value <= Time.zone.now : true
     end
 
     # Check if the record is unpublished

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
 
@@ -51,13 +53,8 @@ module ConcernsOnRails
     # Example:
     #   record.slug_source
     def slug_source
-      if self.class.sluggable_field.present? && respond_to?(self.class.sluggable_field)
-        send(self.class.sluggable_field)
-      elsif respond_to?(:title)
-        title
-      else
-        to_s
-      end
+      field = self.class.sluggable_field
+      respond_to?(field) ? send(field) : to_s
     end
   end
-end
+end

data/lib/concerns_on_rails/soft_deletable.rb

@@ -8,17 +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 }
-
-      # define callbacks
-      define_model_callbacks :soft_delete
-      define_model_callbacks :restore
     end
 
     class_methods do
@@ -29,9 +25,19 @@ 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
+      def destroy_all
+        all.each(&:soft_delete!)
+      end
+
+      # Provide really_destroy_all to hard delete all records
+      def really_destroy_all
+        unscoped.delete_all
       end
     end
 
@@ -41,57 +47,49 @@ module ConcernsOnRails
     def before_restore; end
     def after_restore; end
 
-    # add soft delete methods
     def soft_delete!
       return true if deleted?
-      run_callbacks(:soft_delete) do
-        before_soft_delete
-        if self.class.soft_delete_touch
-          update(self.class.soft_delete_field => Time.zone.now).tap do |result|
-            touch if respond_to?(:touch)
-            after_soft_delete if result
-          end
-        else
-          update_column(self.class.soft_delete_field, Time.zone.now).tap do |result|
-            after_soft_delete if result
-          end
-        end
-      end
-    end
 
-    # really delete the record
-    def really_delete!
-      destroy
+      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
+      after_soft_delete if result
+      result
     end
-  
+
     def restore!
-      run_callbacks(:restore) do
-        before_restore
-        if self.class.soft_delete_touch
-          update(self.class.soft_delete_field => nil).tap do |result|
-            touch if respond_to?(:touch)
-            after_restore if result
-          end
-        else
-          update_column(self.class.soft_delete_field, nil).tap do |result|
-            after_restore if result
-          end
-        end
-      end
+      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
+      after_restore if result
+      result
     end
-  
+
+    # bypasses AR callbacks and validations — use when you want a true hard delete
+    def really_delete!
+      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?
 
-    # Is really deleted?
     def is_really_deleted?
-      !self.class.exists?(id)
+      !self.class.unscoped.exists?(id)
     end
   end
 end

data/lib/concerns_on_rails/sortable.rb

@@ -22,7 +22,13 @@ module ConcernsOnRails
       self.sortable_direction ||= :asc
 
       # we cannot use acts_as_list here
-      default_scope { order(sortable_field => sortable_direction) }
+      default_scope do
+        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
 
     # class methods
@@ -35,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)
 
@@ -48,15 +56,11 @@ module ConcernsOnRails
 
         validate_sortable_field!
 
-        # add acts_as_list and default scope
-        # Setup sorting behaviors
         acts_as_list column: sortable_field if use_acts_as_list
-
-        # add default scope: position => asc
-        default_scope { order(sortable_field => sortable_direction) }
       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.1.0"
+  VERSION = "1.3.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -4,6 +4,7 @@ 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"
 
 module ConcernsOnRails
 end

metadata

@@ -1,29 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-16 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: acts_as_list
   requirement: !ruby/object:Gem::Requirement
@@ -64,6 +70,7 @@ 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/sluggable.rb
 - lib/concerns_on_rails/soft_deletable.rb
@@ -91,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Reusable Rails concerns like Sortable, Publishable, and Sluggable