concerns_on_rails 1.8.2 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5126c79ca466ff1a85a20eb0d4a29f7a2d471bc4186e7b4762481bfad2084f42
-  data.tar.gz: '086922bf94b7efa7ef99699e4d96ab4e24ae2e731c2308bd1b0a8471e1f065a2'
+  metadata.gz: d01db047d91e470c1c2bb03f6fbe95be1eea7592199d9a548b6ac5dbacc84452
+  data.tar.gz: f47e6149addbee52badc7ae4d56fbc66c636adc75d5a32f7742a57d18eda1cd8
 SHA512:
-  metadata.gz: 6b3e968d8cf97c9d11b14ff1d8374a64731ed3416d114ca0acf525a64f65843a35f0261da219d9f725e539eba7ac6460ba331a3aaf2b701b88627d841ac70a2a
-  data.tar.gz: 61f80dadd2112d36c1c1ceaf88fe01fb5dcf68f22911e1535e68414ecdbaca07ca363365c7ec3032c2698aec1cb0929d054036d2b8ebf73d1c347093976f3bb4
+  metadata.gz: 1a856b89dd65fc126612d33aa276cfe49949484594a6d9c1cca2af01e91474883b1eb170e3f36647a125375ed645914cff6a1564cac3f955e2d7066a7c3c0e37
+  data.tar.gz: 2056b850ffddb607084f672018498b4f366a0ab7c0f97bf22e806355031eae146c256f2f62c4bc3ef5e769ee75a3bd05d2bfc56864a5994ea9b204a1a9b730ab

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 <!-- CHANGELOG.md -->
 
+## 1.9.0 (2026-05-25)
+
+### Added
+- **Models::Stateable**: Lightweight string-backed state machine — predicates (`draft?`, `published?`), scopes (`Article.draft`), direct setters (`published!`), guarded transitions (`publish!` / `may_publish?`) with optional `transitions:` config, generic `transition_to!`, and a configurable default applied via `after_initialize`. Supports `prefix:` / `suffix:` to avoid name clashes. Raises `Stateable::InvalidTransition` for disallowed state changes.
+- **Controllers::Includable**: Whitelisted association sideloading + sparse fieldsets for JSON APIs. `includable :author, :comments, fields: { articles: %i[id title] }` declares an allow-list; `with_includes(relation)` applies only the requested, permitted associations; `requested_includes` / `requested_fields` return sanitized values to pass directly to serializers.
+- **Models::SoftDeletable**: New scopes `with_deleted` (all records including deleted), `only_deleted` (alias for `soft_deleted`), `deleted_within(duration)` (recently deleted in a time window); new class method `restore_all` (bulk-restores all soft-deleted records).
+- **Models::Publishable**: New scopes `scheduled` (future `published_at`) and `draft` (nil `published_at`); predicates `scheduled?` / `draft?`; mutator `publish_at!(time)` for scheduling a future publish; opt-in `publishable_by :published_at, default_scope: true` to hide unpublished records from `.all` (default is off).
+- **Models::Searchable**: New options — `mode: :all` (AND all whitespace-separated terms across fields instead of OR), `match: :prefix` (anchors at start) / `match: :exact` (full match) / `match: :contains` (default, substring); option validation raises `ArgumentError` for unknown values.
+- **Models::Sluggable**: New options — `history: true` (keeps slug history via the `friendly_id_slugs` table so old slugs still resolve) and `scope: :account_id` (slug uniqueness scoped to a foreign-key column). Both delegate to `friendly_id`'s built-in `:history` / `:scoped` modules.
+
+### Internal
+- Extracted duplicated column-existence checks from all 11 model concerns into `ConcernsOnRails::Support::ColumnGuard`. Error messages are now unified: `"<Concern>: '<field>' does not exist in the database (table: <table>)"` — the `/does not exist/` substring is preserved across all concerns.
+- Extracted duplicated random-value generation (`Hashable` `:custom` branch + `Tokenizable`) into `ConcernsOnRails::Support::RandomValue`. No behavior change.
+
 ## 1.8.2 (2026-05-22)
 
 ### Internal

data/README.md

@@ -36,12 +36,14 @@ Article.published.without_deleted.find("hello-world")
   - [Searchable](#-searchable) — LIKE/ILIKE search across configured columns
   - [Activatable](#-activatable) — boolean active/inactive toggle
   - [Tokenizable](#-tokenizable) — security tokens with timing-safe lookup
+  - [Stateable](#-stateable) — lightweight string-backed state machine
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
   - [Sortable (controller)](#-sortable-controller) — URL-param ordering with allow-list
   - [Respondable](#-respondable) — standardized JSON envelopes
   - [ErrorHandleable](#-errorhandleable) — JSON `rescue_from` handlers for common controller errors
+  - [Includable](#-includable) — whitelisted association sideloading + sparse fieldsets
 - [Module paths & namespacing](#-module-paths--namespacing)
 - [Development](#-development)
 - [Contributing](#-contributing)
@@ -51,7 +53,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Eleven model concerns + five controller concerns**, all production-ready
+- **Twelve model concerns + six controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable); controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
@@ -64,7 +66,7 @@ Article.published.without_deleted.find("hello-world")
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.8"
+gem "concerns_on_rails", "~> 1.9"
 ```
 
 Or pull the latest from GitHub:
@@ -145,10 +147,23 @@ post.slug              # => "hello-world"  (regenerates on title change)
 Post.friendly.find("hello-world")
 ```
 
+**Options**
+
+```ruby
+# Keep old slugs resolvable after a title change (needs a friendly_id_slugs migration)
+sluggable_by :title, history: true
+Post.friendly.find("old-slug")   # still resolves to the renamed post
+
+# Unique slug only within a scope column (same slug allowed in different accounts)
+sluggable_by :title, scope: :account_id
+```
+
 **Notes**
 - Schema must have a `slug` column (string).
+- `history: true` requires a `friendly_id_slugs` table — generate with `rails generate friendly_id` or add a manual migration.
+- `scope: :col` requires `col` to exist in the same table.
 - Falls back to `to_s` if the configured source field doesn't respond.
-- Uses friendly_id's `:slugged` strategy under the hood.
+- Uses friendly_id's `:slugged` (+ optionally `:history`, `:scoped`) strategies under the hood.
 
 ---
 
@@ -201,11 +216,29 @@ article.unpublish!
 
 Article.published       # WHERE published_at <= NOW()
 Article.unpublished     # WHERE published_at IS NULL OR published_at > NOW()
+Article.scheduled       # WHERE published_at > NOW()  (future-dated — not live yet)
+Article.draft           # WHERE published_at IS NULL  (no date set at all)
+```
+
+**Scheduling**
+
+```ruby
+article.publish_at!(1.week.from_now)   # sets published_at to a future time
+article.scheduled?                      # => true (not live yet)
+article.draft?                          # => false
+```
+
+**Opt-in default scope**
+
+```ruby
+publishable_by :published_at, default_scope: true
+# Article.all now returns only published records automatically
+# Article.unscoped reaches everything
 ```
 
 **Notes**
-- "Published" means `published_at` is set **and** in the past — so scheduled posts (future `published_at`) stay unpublished until their time arrives.
-- No `default_scope` is added; chain `.published` explicitly.
+- "Published" means `published_at` is set **and** in the past — so future-dated posts stay unpublished until their time arrives.
+- No `default_scope` is added by default; chain `.published` explicitly (or opt in with `default_scope: true`).
 
 ---
 
@@ -232,11 +265,14 @@ user.really_delete!        # bypasses callbacks, hard deletes from DB
 **Scopes**
 
 ```ruby
-User.active           # alias of .without_deleted — non-deleted records
-User.without_deleted  # same
-User.soft_deleted     # only deleted records
-User.all              # default scope: non-deleted only
-User.unscoped         # everything (deleted + non-deleted)
+User.active               # alias of .without_deleted — non-deleted records
+User.without_deleted      # same
+User.soft_deleted         # only deleted records (timestamp set)
+User.only_deleted         # alias for .soft_deleted
+User.with_deleted         # all records — deleted + non-deleted
+User.deleted_within(7.days)  # soft-deleted within the last 7 days
+User.all                  # default scope: non-deleted only
+User.unscoped             # everything (deleted + non-deleted)
 ```
 
 **Bulk operations**
@@ -244,6 +280,7 @@ User.unscoped         # everything (deleted + non-deleted)
 ```ruby
 User.destroy_all          # soft-deletes all matching records
 User.really_destroy_all   # hard-deletes all matching records
+User.restore_all          # restores all soft-deleted records
 ```
 
 **Lifecycle hooks** — override these methods on the model:
@@ -449,11 +486,25 @@ Article.search("")                     # no-op — returns the full relation
 Article.search("foo").where(state: 1)  # chainable like any scope
 ```
 
+**Options**
+
+```ruby
+# mode: :any (default) — any term in any field matches (OR)
+# mode: :all           — every whitespace-separated term must match somewhere (AND per term, OR across fields)
+searchable_by :title, :body, mode: :all
+Article.search("ruby framework")  # title OR body must contain "ruby" AND "framework"
+
+# match: :contains (default) — %term% (substring)
+# match: :prefix           — term%  (starts with)
+# match: :exact            — term   (full match)
+searchable_by :sku, match: :prefix
+```
+
 **Notes**
 - Uses Arel's `matches`, which emits `ILIKE` on Postgres (case-insensitive) and `LIKE` elsewhere.
 - The query is escaped before interpolation — `%`, `_`, and `\` from user input are treated as literals, not wildcards.
-- Blank or nil queries return the relation unchanged so it's safe to drop into a controller pipeline.
-- Single-term substring match by design; reach for `pg_search` / Elasticsearch when you need ranking, stemming, or multi-term queries.
+- Blank or nil queries return the relation unchanged, so it's safe to drop into a controller pipeline.
+- Reach for `pg_search` / Elasticsearch when you need ranking, stemming, or full-text indexes.
 
 ---
 
@@ -526,6 +577,59 @@ User.authenticate_by_api_token(token)     # timing-safe; returns user or nil
 
 ---
 
+## 🔄 Stateable
+
+Lightweight string-backed state machine — the 80% of AASM without the dependency.
+
+```ruby
+class Article < ApplicationRecord
+  include ConcernsOnRails::Stateable
+
+  stateable_by :status,
+               states:      %i[draft pending published archived],
+               default:     :draft,
+               transitions: {
+                 publish:  { from: %i[draft pending], to: :published },
+                 archive:  { to: :archived }   # no :from → allowed from any state
+               }
+end
+```
+
+**Generated API**
+
+```ruby
+article = Article.new          # status defaults to "draft"
+article.draft?                 # => true   (predicate per state)
+article.published?             # => false
+
+Article.draft                  # scope: WHERE status = 'draft'
+Article.published              # scope: WHERE status = 'published'
+
+article.published!             # direct setter — updates regardless of current state
+article.publish!               # guarded transition — raises InvalidTransition if not allowed
+article.may_publish?           # => true  (guard check without raising)
+
+article.transition_to!(:archived)  # generic move to any declared state
+```
+
+**Prefix / suffix** — avoid clashes when the state names overlap with other concerns or scopes:
+
+```ruby
+stateable_by :state, states: %i[open closed], prefix: true
+# generates: state_open?, state_closed?, state_open!, state_closed!, State.state_open, …
+```
+
+**Validation**
+- Raises `ArgumentError` if the column, states, default, or transition config is invalid.
+- Raises `Stateable::InvalidTransition` at runtime for disallowed guarded transitions.
+
+**Notes**
+- String-column backed (not integer-backed like Rails enum) — values are stored as-is.
+- States like `active` / `expired` overlap with `Activatable`/`Expirable` scopes — use `prefix:` or `suffix:` to disambiguate.
+- No persistence of transition history; combine with `Publishable` / `Schedulable` for time-based state tracking.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -709,6 +813,46 @@ end
 
 ---
 
+## 🔗 Includable
+
+Whitelisted association sideloading + sparse fieldsets for JSON APIs — zero arbitrary `.includes` from user input.
+
+```ruby
+class ArticlesController < ApplicationController
+  include ConcernsOnRails::Controllers::Includable
+
+  includable :author, :comments,
+             fields: { articles: %i[id title published_at], authors: %i[id name] }
+
+  def index
+    render json: with_includes(Article.all),
+           include: requested_includes,
+           fields:  requested_fields
+  end
+end
+```
+
+**URL params**
+
+```
+GET /articles?include=author,comments&fields[articles]=id,title&fields[authors]=id,name
+```
+
+**API**
+
+| Method               | What it does                                                                               |
+|----------------------|--------------------------------------------------------------------------------------------|
+| `with_includes(rel)` | Parses `params[:include]`, intersects with the allow-list, calls `relation.includes(...)`  |
+| `requested_includes` | Returns the sanitized `[:author, :comments]` array (pass to `render json:, include:`)     |
+| `requested_fields`   | Returns `{ articles: [:id, :title] }` sanitized map (pass to your serializer)             |
+
+**Notes**
+- Non-whitelisted associations are **silently dropped** — no error, no arbitrary eager-loading.
+- Non-whitelisted tables in `params[:fields]` are dropped; non-whitelisted columns within an allowed table are dropped.
+- Pass `requested_fields` to your serializer (e.g. AMS / Blueprinter) — `Includable` itself does not alter the JSON output, only the query.
+
+---
+
 ## 🗂️ Module paths & namespacing
 
 Every concern is available under two paths:
@@ -740,7 +884,7 @@ Both forms reference the same module, so you can freely mix them.
 bundle install                                  # install dev dependencies
 bundle exec rspec                               # run the test suite
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.7.0.gem       # install locally
+gem install ./concerns_on_rails-1.9.0.gem       # install locally
 ```
 
 The test suite uses an in-memory SQLite database and a lightweight `FakeController` harness for controller-concern specs — no Rails routes or boot required.

data/lib/concerns_on_rails/controllers/includable.rb

@@ -0,0 +1,85 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Controllers
+    # Whitelisted association sideloading + sparse fieldsets for JSON APIs.
+    # Same allow-list philosophy as Controllers::Sortable: a client can only ask
+    # for associations/fields you've explicitly permitted, so `?include=` can
+    # never trigger an arbitrary `.includes` (N+1 / data-exposure risk).
+    #
+    #   class ArticlesController < ApplicationController
+    #     include ConcernsOnRails::Controllers::Includable
+    #
+    #     includable :author, :comments,
+    #                fields: { articles: %i[id title], authors: %i[id name] }
+    #
+    #     def index
+    #       render json: with_includes(Article.all),
+    #              include: requested_includes,
+    #              fields: requested_fields
+    #     end
+    #   end
+    #
+    # URL params:
+    #   ?include=author,comments         -> eager-loads only whitelisted associations
+    #   ?fields[articles]=id,title       -> sanitized down to the allowed columns
+    #
+    # `requested_includes` / `requested_fields` return sanitized values you can
+    # hand to your serializer; they never mutate the rendered output themselves.
+    module Includable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :includable_associations, default: []
+        class_attribute :includable_fields, default: {}
+      end
+
+      class_methods do
+        # Whitelist sideloadable associations and (optionally) the columns
+        # exposable per resource via sparse fieldsets.
+        def includable(*associations, fields: {})
+          self.includable_associations = associations.map(&:to_sym)
+          self.includable_fields = fields.each_with_object({}) do |(table, cols), memo|
+            memo[table.to_sym] = Array(cols).map(&:to_sym)
+          end
+        end
+      end
+
+      # Eager-load only the whitelisted associations requested via ?include=.
+      # Returns the relation unchanged when nothing valid was requested.
+      def with_includes(relation)
+        associations = requested_includes
+        associations.empty? ? relation : relation.includes(*associations)
+      end
+
+      # Sanitized association list: requested ∩ allow-list.
+      def requested_includes
+        requested = params[:include].to_s.split(",").map { |token| token.strip.to_sym }
+        requested & self.class.includable_associations
+      end
+
+      # Sanitized sparse fieldsets: { table => [cols] }, each intersected with
+      # the allowed columns for that table. Unknown tables/columns are dropped.
+      def requested_fields
+        raw = params[:fields]
+        return {} unless raw.respond_to?(:each_pair)
+
+        allowed = self.class.includable_fields
+        raw.each_with_object({}) do |(table, cols), memo|
+          key = table.to_sym
+          next unless allowed.key?(key)
+
+          permitted = split_field_list(cols) & allowed[key]
+          memo[key] = permitted unless permitted.empty?
+        end
+      end
+
+      private
+
+      def split_field_list(cols)
+        list = cols.is_a?(Array) ? cols : cols.to_s.split(",")
+        list.map { |col| col.to_s.strip.to_sym }
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -13,4 +13,5 @@ module ConcernsOnRails
   Searchable    = Models::Searchable
   Activatable   = Models::Activatable
   Tokenizable   = Models::Tokenizable
+  Stateable     = Models::Stateable
 end

data/lib/concerns_on_rails/models/activatable.rb

@@ -28,13 +28,11 @@ module ConcernsOnRails
       end
 
       class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
         def activatable_by(field = DEFAULT_FIELD)
           self.activatable_field = field.to_sym
-
-          unless column_names.include?(activatable_field.to_s)
-            raise ArgumentError,
-                  "ConcernsOnRails::Models::Activatable: activatable_field '#{activatable_field}' does not exist in the database"
-          end
+          ensure_columns!("ConcernsOnRails::Models::Activatable", activatable_field)
 
           scope :active,   -> { where(activatable_field => true) }
           scope :inactive, -> { where(activatable_field => [false, nil]) }

data/lib/concerns_on_rails/models/expirable.rb

@@ -27,16 +27,15 @@ module ConcernsOnRails
       end
 
       class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
         # 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::Models::Expirable: expirable_field '#{expirable_field}' does not exist in the database"
+          ensure_columns!("ConcernsOnRails::Models::Expirable", expirable_field)
         end
       end
 

data/lib/concerns_on_rails/models/hashable.rb

@@ -16,6 +16,8 @@ module ConcernsOnRails
       end
 
       class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
         # Define hashable field and generation options.
         # Example:
         #   hashable_by :token
@@ -29,6 +31,7 @@ module ConcernsOnRails
           self.hashable_length = length.to_i
           self.hashable_alphabet = alphabet
 
+          ensure_columns!("ConcernsOnRails::Models::Hashable", hashable_field)
           validate_hashable_options!
           before_create :assign_hashable_value
 
@@ -45,17 +48,13 @@ module ConcernsOnRails
           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
+          when :custom  then ConcernsOnRails::Support::RandomValue.from_alphabet(hashable_alphabet, hashable_length)
           end
         end
 
         private
 
         def validate_hashable_options!
-          unless column_names.include?(hashable_field.to_s)
-            raise ArgumentError, "ConcernsOnRails::Models::Hashable: hashable_field '#{hashable_field}' does not exist in the database"
-          end
-
           unless VALID_TYPES.include?(hashable_type)
             raise ArgumentError,
                   "ConcernsOnRails::Models::Hashable: unknown type '#{hashable_type}'. Valid types: #{VALID_TYPES.join(', ')}"

data/lib/concerns_on_rails/models/normalizable.rb

@@ -22,6 +22,8 @@ module ConcernsOnRails
       end
 
       class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
         # Declare which fields should be normalized and how.
         # Example:
         #   normalizable :email, with: :email
@@ -31,7 +33,7 @@ module ConcernsOnRails
           raise ArgumentError, "ConcernsOnRails::Models::Normalizable: at least one field is required" if fields.empty?
 
           normalizer = resolve_normalizer(with)
-          fields.each { |field| validate_normalizable_field!(field) }
+          ensure_columns!("ConcernsOnRails::Models::Normalizable", fields)
           self.normalizable_rules = normalizable_rules.merge(fields.to_h { |f| [f.to_sym, normalizer] })
         end
       end
@@ -39,12 +41,6 @@ module ConcernsOnRails
       class_methods do
         private
 
-        def validate_normalizable_field!(field)
-          return if column_names.include?(field.to_s)
-
-          raise ArgumentError, "ConcernsOnRails::Models::Normalizable: field '#{field}' does not exist in the database"
-        end
-
         def resolve_normalizer(with)
           case with
           when Symbol

data/lib/concerns_on_rails/models/publishable.rb

@@ -10,18 +10,33 @@ module ConcernsOnRails
 
         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)))
+          column = arel_table[publishable_field]
+          unscope(where: publishable_field).where(column.eq(nil).or(column.gt(Time.zone.now)))
         }
+        # Set, but the publish time is still in the future.
+        scope :scheduled, -> { unscope(where: publishable_field).where(arel_table[publishable_field].gt(Time.zone.now)) }
+        # Never set — a true draft.
+        scope :draft, -> { unscope(where: publishable_field).where(publishable_field => nil) }
       end
 
       class_methods do
-        def publishable_by(field = nil)
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Pass `default_scope: true` to hide unpublished records by default
+        # (`.all` then returns only published). The negative scopes
+        # (.unpublished/.scheduled/.draft) unscope the field, so they still work.
+        def publishable_by(field = nil, default_scope: false)
           self.publishable_field = field || :published_at
+          ensure_columns!("ConcernsOnRails::Models::Publishable", publishable_field)
+          enable_published_default_scope if default_scope
+        end
 
-          return if column_names.include?(publishable_field.to_s)
+        private
 
-          raise ArgumentError,
-                "ConcernsOnRails::Models::Publishable: publishable_field '#{publishable_field}' does not exist in the database"
+        # Routed through a helper so the `default_scope:` keyword doesn't shadow
+        # the `default_scope` macro inside `publishable_by`.
+        def enable_published_default_scope
+          default_scope { published }
         end
       end
 
@@ -56,6 +71,26 @@ module ConcernsOnRails
       def unpublished?
         !published?
       end
+
+      # Set, but the publish time is still in the future.
+      def scheduled?
+        value = self[self.class.publishable_field]
+        return false if value.blank?
+
+        value.respond_to?(:>) ? value > Time.zone.now : false
+      end
+
+      # Never set — a true draft.
+      def draft?
+        self[self.class.publishable_field].blank?
+      end
+
+      # Publish at an explicit time. A future time schedules the record.
+      # Example:
+      #   record.publish_at!(1.day.from_now)
+      def publish_at!(time)
+        update(self.class.publishable_field => time)
+      end
     end
   end
 end

data/lib/concerns_on_rails/models/schedulable.rb

@@ -39,6 +39,8 @@ module ConcernsOnRails
       end
 
       class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
         # Configure the start/end timestamp columns.
         # Example:
         #   schedulable_by                                          # uses :starts_at and :ends_at
@@ -52,11 +54,8 @@ module ConcernsOnRails
             raise ArgumentError, "ConcernsOnRails::Models::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::Models::Schedulable: field '#{field}' does not exist in the database"
-          end
+          ensure_columns!("ConcernsOnRails::Models::Schedulable",
+                          schedulable_starts_at_field, schedulable_ends_at_field)
         end
       end
 

data/lib/concerns_on_rails/models/searchable.rb

@@ -7,38 +7,53 @@ module ConcernsOnRails
     #   class Article < ApplicationRecord
     #     include ConcernsOnRails::Searchable
     #
-    #     searchable_by :title, :body
+    #     searchable_by :title, :body                                  # defaults below
+    #     searchable_by :title, :body, mode: :all                      # every term must match
+    #     searchable_by :sku,         match: :prefix                   # "abc" -> "abc%"
+    #     searchable_by :code,        match: :exact, case_sensitive: true
     #   end
     #
     #   Article.search("hello")            # WHERE title ILIKE '%hello%' OR body ILIKE '%hello%'
     #   Article.search("")                 # no-op — returns the full relation
     #   Article.search("foo").where(...)   # chainable like any scope
     #
-    # Uses Arel's `matches`, which emits ILIKE on Postgres and LIKE elsewhere —
-    # so case-insensitivity comes for free on PG. The query is escaped before
-    # interpolation, so `%` / `_` / `\` from user input are treated as literals.
+    # Options (all optional; the defaults reproduce a single-term, case-insensitive
+    # "contains" search across the given columns):
+    #   mode:           :any (default) treats the whole query as one term;
+    #                   :all splits on whitespace and requires every term to match.
+    #   match:          :contains (default, "%q%"), :prefix ("q%"), or :exact ("q").
+    #   case_sensitive: false (default) emits ILIKE on Postgres; true emits LIKE.
+    #
+    # Uses Arel's `matches`. The query is escaped before interpolation, so
+    # `%` / `_` / `\` from user input are treated as literals.
     module Searchable
       extend ActiveSupport::Concern
 
       LIKE_ESCAPE = "\\".freeze
       LIKE_SPECIAL = /[\\%_]/
+      VALID_MODES = %i[any all].freeze
+      VALID_MATCHES = %i[contains prefix exact].freeze
 
       included do
         class_attribute :searchable_fields, instance_accessor: false, default: []
+        class_attribute :searchable_mode, instance_accessor: false, default: :any
+        class_attribute :searchable_match, instance_accessor: false, default: :contains
+        class_attribute :searchable_case_sensitive, instance_accessor: false, default: false
       end
 
       class_methods do
-        def searchable_by(*fields)
+        include ConcernsOnRails::Support::ColumnGuard
+
+        def searchable_by(*fields, mode: :any, match: :contains, case_sensitive: false)
           raise ArgumentError, "ConcernsOnRails::Models::Searchable: at least one field is required" if fields.empty?
 
-          fields.each do |field|
-            unless column_names.include?(field.to_s)
-              raise ArgumentError,
-                    "ConcernsOnRails::Models::Searchable: field '#{field}' does not exist in the database"
-            end
-          end
+          ensure_columns!("ConcernsOnRails::Models::Searchable", fields)
+          validate_search_options!(mode, match)
 
           self.searchable_fields = fields.map(&:to_sym)
+          self.searchable_mode = mode.to_sym
+          self.searchable_match = match.to_sym
+          self.searchable_case_sensitive = case_sensitive
 
           scope :search, ->(query) { search_relation(query) }
         end
@@ -46,11 +61,39 @@ module ConcernsOnRails
         def search_relation(query)
           return all if query.nil? || query.to_s.strip.empty?
 
-          escaped = query.to_s.gsub(LIKE_SPECIAL) { |c| "#{LIKE_ESCAPE}#{c}" }
-          pattern = "%#{escaped}%"
+          terms = searchable_mode == :all ? query.to_s.split : [query.to_s]
+          terms.reduce(all) { |relation, term| relation.where(search_term_predicate(term)) }
+        end
+      end
+
+      class_methods do
+        private
+
+        # OR the per-field LIKE predicate for a single term.
+        def search_term_predicate(term)
+          pattern = search_like_pattern(term)
+          predicates = searchable_fields.map do |field|
+            arel_table[field].matches(pattern, LIKE_ESCAPE, searchable_case_sensitive)
+          end
+          predicates.reduce { |memo, predicate| memo.or(predicate) }
+        end
+
+        def search_like_pattern(term)
+          escaped = term.to_s.gsub(LIKE_SPECIAL) { |char| "#{LIKE_ESCAPE}#{char}" }
+          case searchable_match
+          when :prefix then "#{escaped}%"
+          when :exact  then escaped
+          else "%#{escaped}%"
+          end
+        end
+
+        def validate_search_options!(mode, match)
+          unless VALID_MODES.include?(mode.to_sym)
+            raise ArgumentError, "ConcernsOnRails::Models::Searchable: unknown mode '#{mode}'. Valid modes: #{VALID_MODES.join(', ')}"
+          end
+          return if VALID_MATCHES.include?(match.to_sym)
 
-          predicates = searchable_fields.map { |field| arel_table[field].matches(pattern, LIKE_ESCAPE) }
-          where(predicates.reduce { |memo, p| memo.or(p) })
+          raise ArgumentError, "ConcernsOnRails::Models::Searchable: unknown match '#{match}'. Valid matches: #{VALID_MATCHES.join(', ')}"
         end
       end
     end

data/lib/concerns_on_rails/models/sluggable.rb

@@ -29,22 +29,32 @@ module ConcernsOnRails
 
       # class methods
       class_methods do
-        # Define sluggable field
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Define sluggable field, with optional friendly_id features.
         # Example:
         #   sluggable_by :wonderful_name
-        def sluggable_by(field)
+        #   sluggable_by :title, history: true       # old slugs keep resolving (needs a friendly_id_slugs table)
+        #   sluggable_by :title, scope: :account_id  # slugs unique per scope column
+        def sluggable_by(field, history: false, scope: nil)
           self.sluggable_field = field.to_sym
-
-          validate_sluggable_field!
+          ensure_columns!("ConcernsOnRails::Models::Sluggable", [sluggable_field, scope].compact)
+          reconfigure_friendly_id(history: history, scope: scope) if history || scope
         end
 
         private
 
-        # Validate sluggable_field exists in database
-        def validate_sluggable_field!
-          return if column_names.include?(sluggable_field.to_s)
-
-          raise ArgumentError, "ConcernsOnRails::Models::Sluggable: sluggable_field '#{sluggable_field}' does not exist in the database"
+        # Re-runs friendly_id with the extra modules. friendly_id merges config
+        # across calls, so this layers :history / :scoped onto the base :slugged.
+        def reconfigure_friendly_id(history:, scope:)
+          modules = [:slugged]
+          modules << :history if history
+          modules << :scoped if scope
+          options = { use: modules }
+          options[:scope] = scope if scope
+          # friendly_id's second argument is a positional options hash (not kwargs),
+          # so pass it positionally to stay correct on both Ruby 2.7 and 3.x.
+          friendly_id(:slug_source, options)
         end
       end
 

data/lib/concerns_on_rails/models/soft_deletable.rb

@@ -14,22 +14,25 @@ module ConcernsOnRails
         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) }
+        scope :only_deleted, -> { soft_deleted }
+        # `with_deleted` peels off the default scope so deleted + non-deleted are both returned.
+        scope :with_deleted, -> { unscope(where: soft_delete_field) }
+        # Records soft-deleted within the last `duration` (e.g. `deleted_within(7.days)`).
+        scope :deleted_within, ->(duration) { soft_deleted.where(soft_delete_field => duration.ago..) }
         # Optionally, uncomment to hide deleted by default:
         default_scope { without_deleted }
       end
 
       class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
         # Define soft delete field and options
         # Example:
         #   soft_deletable_by :deleted_at, touch: false
         def soft_deletable_by(field = nil, touch: true)
           self.soft_delete_field = field || :deleted_at
           self.soft_delete_touch = touch
-
-          return if column_names.include?(soft_delete_field.to_s)
-
-          raise ArgumentError,
-                "ConcernsOnRails::Models::SoftDeletable: soft_delete_field '#{soft_delete_field}' does not exist in the database"
+          ensure_columns!("ConcernsOnRails::Models::SoftDeletable", soft_delete_field)
         end
 
         # Override destroy_all to perform soft delete on all records
@@ -41,6 +44,11 @@ module ConcernsOnRails
         def really_destroy_all
           unscoped.delete_all
         end
+
+        # Restore every soft-deleted record (mirror of the destroy_all override).
+        def restore_all
+          soft_deleted.each(&:restore!)
+        end
       end
 
       # Soft delete hooks

data/lib/concerns_on_rails/models/sortable.rb

@@ -24,11 +24,7 @@ module ConcernsOnRails
 
         # we cannot use acts_as_list here
         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
-
+          ensure_columns!("ConcernsOnRails::Models::Sortable", sortable_field)
           order(sortable_field => sortable_direction)
         end
       end
@@ -36,6 +32,8 @@ module ConcernsOnRails
       # class methods
       # Example: Task.sortable_by(priority: :asc)
       class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
         # Define sortable field and direction
         # Example:
         #   sortable_by :position
@@ -56,7 +54,7 @@ module ConcernsOnRails
           self.sortable_field = field
           self.sortable_direction = direction
 
-          validate_sortable_field!
+          ensure_columns!("ConcernsOnRails::Models::Sortable", sortable_field)
 
           acts_as_list column: sortable_field if use_acts_as_list
         end
@@ -74,13 +72,6 @@ module ConcernsOnRails
             [config.to_sym, :asc]
           end
         end
-
-        # Validate sortable_field exists in database
-        def validate_sortable_field!
-          return if column_names.include?(sortable_field.to_s)
-
-          raise ArgumentError, "ConcernsOnRails::Models::Sortable: sortable_field '#{sortable_field}' does not exist in the database"
-        end
       end
     end
   end

data/lib/concerns_on_rails/models/stateable.rb

@@ -0,0 +1,165 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Models
+    # Lightweight, string-backed state machine — the common 80% of a state
+    # machine without an AASM-sized dependency.
+    #
+    #   class Article < ApplicationRecord
+    #     include ConcernsOnRails::Stateable
+    #
+    #     stateable_by :status,
+    #                  states: %i[draft pending published archived],
+    #                  default: :draft,
+    #                  transitions: {
+    #                    publish: { from: %i[draft pending], to: :published },
+    #                    archive: { to: :archived }          # :from omitted => any state
+    #                  }
+    #   end
+    #
+    # Generates, for each state (method names honor prefix:/suffix:):
+    #   * predicate  — article.draft?       => status == "draft"
+    #   * scope      — Article.draft        => where(status: "draft")
+    #   * setter     — article.published!   => update!(status: "published")  (unguarded)
+    #
+    # And for each declared transition:
+    #   * event!     — article.publish!     => guarded; raises InvalidTransition from a bad state
+    #   * guard?     — article.may_publish? => whether the transition is allowed now
+    #
+    # Plus a generic `transition_to!(state)`.
+    #
+    # Options for stateable_by: default:, transitions:, prefix:, suffix:
+    # (prefix:/suffix: take `true` to use the field name, or a literal string/symbol).
+    #
+    # Notes:
+    #   * String columns only (store the state name) — not integer-backed like Rails enum.
+    #   * A state named like an AR method (`new`, `valid`) or a concern scope
+    #     (`active`, `expired`) will clash — use prefix:/suffix: to disambiguate.
+    module Stateable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Models::Stateable".freeze
+
+      # Raised when a guarded transition is attempted from a disallowed state.
+      class InvalidTransition < StandardError; end
+
+      included do
+        class_attribute :stateable_field, instance_accessor: false
+        class_attribute :stateable_states, instance_accessor: false, default: []
+        class_attribute :stateable_default, instance_accessor: false
+        class_attribute :stateable_transitions, instance_accessor: false, default: {}
+        class_attribute :stateable_prefix, instance_accessor: false
+        class_attribute :stateable_suffix, instance_accessor: false
+      end
+
+      # Move to any declared state by name, bypassing transition guards.
+      def transition_to!(state)
+        state = state.to_sym
+        raise InvalidTransition, "#{LABEL}: '#{state}' is not a declared state" unless self.class.stateable_states.include?(state)
+
+        update!(self.class.stateable_field => state.to_s)
+      end
+
+      # Defined as a real module (not `class_methods do`) so all the private
+      # builder helpers live under a single `private` and aren't constrained by
+      # Metrics/BlockLength. ActiveSupport::Concern auto-extends `ClassMethods`.
+      module ClassMethods
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Configure the state column. See the module docs for the full DSL.
+        def stateable_by(field, states:, **options)
+          stateable_configure!(field, states, options)
+          stateable_validate!
+          stateable_define_states
+          stateable_define_transitions
+          stateable_apply_default
+        end
+
+        private
+
+        def stateable_configure!(field, states, options)
+          self.stateable_field = field.to_sym
+          self.stateable_states = Array(states).map(&:to_sym)
+          self.stateable_default = options[:default]&.to_sym
+          self.stateable_transitions = options[:transitions] || {}
+          self.stateable_prefix = stateable_affix(options[:prefix])
+          self.stateable_suffix = stateable_affix(options[:suffix])
+          ensure_columns!(LABEL, stateable_field)
+        end
+
+        # `true` => use the field name; a string/symbol => use it literally; else none.
+        def stateable_affix(option)
+          return nil unless option
+
+          option == true ? stateable_field.to_s : option.to_s
+        end
+
+        def stateable_method_name(base)
+          [stateable_prefix, base, stateable_suffix].compact.join("_")
+        end
+
+        def stateable_validate!
+          raise ArgumentError, "#{LABEL}: states: cannot be empty" if stateable_states.empty?
+
+          if stateable_default && !stateable_states.include?(stateable_default)
+            raise ArgumentError, "#{LABEL}: default '#{stateable_default}' is not a declared state"
+          end
+
+          stateable_transitions.each { |event, config| stateable_validate_transition!(event, config) }
+        end
+
+        def stateable_validate_transition!(event, config)
+          raise ArgumentError, "#{LABEL}: transition '#{event}' must declare :to" unless config[:to]
+
+          unknown = (Array(config[:from]) + [config[:to]]).map(&:to_sym) - stateable_states
+          raise ArgumentError, "#{LABEL}: transition '#{event}' references unknown states: #{unknown.join(', ')}" if unknown.any?
+
+          return unless stateable_states.include?(event.to_sym)
+
+          raise ArgumentError, "#{LABEL}: transition '#{event}' clashes with the same-named state setter; use prefix:/suffix:"
+        end
+
+        def stateable_define_states
+          field = stateable_field
+          stateable_states.each do |state|
+            value = state.to_s
+            name = stateable_method_name(state)
+            scope name, -> { where(field => value) }
+            define_method("#{name}?") { self[field].to_s == value }
+            define_method("#{name}!") { update!(field => value) }
+          end
+        end
+
+        def stateable_define_transitions
+          field = stateable_field
+          stateable_transitions.each do |event, config|
+            from = Array(config[:from]).map(&:to_s)
+            to = config.fetch(:to).to_s
+            name = stateable_method_name(event)
+            define_method("may_#{name}?") { from.empty? || from.include?(self[field].to_s) }
+            define_method("#{name}!") { stateable_perform_transition!(field, to, from, event) }
+          end
+        end
+
+        def stateable_apply_default
+          return unless stateable_default
+
+          field = stateable_field
+          default = stateable_default.to_s
+          after_initialize { self[field] = default if new_record? && self[field].blank? }
+        end
+      end
+
+      private
+
+      # Instance-level guarded transition body, shared by every `<event>!`.
+      def stateable_perform_transition!(field, to, from, event)
+        unless from.empty? || from.include?(self[field].to_s)
+          raise InvalidTransition, "#{self.class.name}: cannot #{event} from '#{self[field]}'"
+        end
+
+        update!(field => to)
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/models/tokenizable.rb

@@ -38,6 +38,8 @@ module ConcernsOnRails
       end
 
       class_methods do
+        include ConcernsOnRails::Support::ColumnGuard
+
         # Configure a tokenizable field.
         #
         # Options:
@@ -48,7 +50,8 @@ module ConcernsOnRails
           type = type.to_sym
           length = length.to_i
 
-          validate_tokenizable_options!(field, type, length)
+          ensure_columns!("ConcernsOnRails::Models::Tokenizable", field)
+          validate_tokenizable_options!(type, length)
 
           # Build a fresh hash so subclasses don't mutate the parent's config.
           self.tokenizable_fields = tokenizable_fields.merge(field => { type: type, length: length })
@@ -69,8 +72,8 @@ module ConcernsOnRails
           case config[:type]
           when :urlsafe      then SecureRandom.urlsafe_base64(length)[0, length]
           when :hex          then SecureRandom.hex((length + 1) / 2)[0, length]
-          when :alphanumeric then random_string_from_alphabet(ALPHANUMERIC_ALPHABET, length)
-          when :numeric      then random_string_from_alphabet(NUMERIC_ALPHABET, length)
+          when :alphanumeric then ConcernsOnRails::Support::RandomValue.from_alphabet(ALPHANUMERIC_ALPHABET, length)
+          when :numeric      then ConcernsOnRails::Support::RandomValue.from_alphabet(NUMERIC_ALPHABET, length)
           end
         end
       end
@@ -100,12 +103,7 @@ module ConcernsOnRails
       end
 
       class_methods do
-        def validate_tokenizable_options!(field, type, length)
-          unless column_names.include?(field.to_s)
-            raise ArgumentError,
-                  "ConcernsOnRails::Models::Tokenizable: tokenizable field '#{field}' does not exist in the database"
-          end
-
+        def validate_tokenizable_options!(type, length)
           unless VALID_TYPES.include?(type)
             raise ArgumentError,
                   "ConcernsOnRails::Models::Tokenizable: unknown type '#{type}'. Valid types: #{VALID_TYPES.join(', ')}"
@@ -116,11 +114,7 @@ module ConcernsOnRails
           raise ArgumentError, "ConcernsOnRails::Models::Tokenizable: length must be a positive integer"
         end
 
-        def random_string_from_alphabet(alphabet, length)
-          Array.new(length) { alphabet[SecureRandom.random_number(alphabet.size)] }.join
-        end
-
-        private :validate_tokenizable_options!, :random_string_from_alphabet
+        private :validate_tokenizable_options!
       end
 
       # Assigns the generated value only when blank, so callers can pass an explicit one.

data/lib/concerns_on_rails/support/column_guard.rb

@@ -0,0 +1,32 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Support
+    # Shared schema-validation helper mixed into a concern's ClassMethods.
+    # Runs in class context, so `column_names` / `table_name` resolve against
+    # the including model. Centralizes the column-existence check that every
+    # model concern used to re-implement, and keeps the error wording uniform.
+    #
+    #   class_methods do
+    #     include ConcernsOnRails::Support::ColumnGuard
+    #
+    #     def activatable_by(field = :active)
+    #       self.activatable_field = field.to_sym
+    #       ensure_columns!("ConcernsOnRails::Models::Activatable", activatable_field)
+    #     end
+    #   end
+    #
+    # The phrase "does not exist" is preserved so existing specs that match
+    # /does not exist/ keep passing.
+    module ColumnGuard
+      def ensure_columns!(concern, *fields)
+        fields.flatten.compact.each do |field|
+          next if column_names.include?(field.to_s)
+
+          raise ArgumentError,
+                "#{concern}: '#{field}' does not exist in the database (table: #{table_name})"
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/random_value.rb

@@ -0,0 +1,16 @@
+require "securerandom"
+
+module ConcernsOnRails
+  module Support
+    # Shared random-value generation used by Hashable (:custom) and Tokenizable
+    # (:alphanumeric / :numeric). Samples `length` characters uniformly from
+    # `alphabet` using SecureRandom.
+    module RandomValue
+      module_function
+
+      def from_alphabet(alphabet, length)
+        Array.new(length) { alphabet[SecureRandom.random_number(alphabet.size)] }.join
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.8.2".freeze
+  VERSION = "1.9.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -4,8 +4,13 @@ require "concerns_on_rails/version"
 module ConcernsOnRails
   module Models; end
   module Controllers; end
+  module Support; end
 end
 
+# Shared internal helpers (must load before the concerns that use them)
+require "concerns_on_rails/support/column_guard"
+require "concerns_on_rails/support/random_value"
+
 # Model concerns
 require "concerns_on_rails/models/sluggable"
 require "concerns_on_rails/models/sortable"
@@ -18,6 +23,7 @@ require "concerns_on_rails/models/normalizable"
 require "concerns_on_rails/models/searchable"
 require "concerns_on_rails/models/activatable"
 require "concerns_on_rails/models/tokenizable"
+require "concerns_on_rails/models/stateable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"
@@ -25,6 +31,7 @@ require "concerns_on_rails/controllers/filterable"
 require "concerns_on_rails/controllers/sortable"
 require "concerns_on_rails/controllers/respondable"
 require "concerns_on_rails/controllers/error_handleable"
+require "concerns_on_rails/controllers/includable"
 
 # Backwards compatibility (top-level aliases for pre-1.6 module paths)
 require "concerns_on_rails/legacy_aliases"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.8.2
+  version: 1.9.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-22 00:00:00.000000000 Z
+date: 2026-05-25 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/controllers/error_handleable.rb
 - lib/concerns_on_rails/controllers/filterable.rb
+- lib/concerns_on_rails/controllers/includable.rb
 - lib/concerns_on_rails/controllers/paginatable.rb
 - lib/concerns_on_rails/controllers/respondable.rb
 - lib/concerns_on_rails/controllers/sortable.rb
@@ -86,7 +87,10 @@ files:
 - lib/concerns_on_rails/models/sluggable.rb
 - lib/concerns_on_rails/models/soft_deletable.rb
 - lib/concerns_on_rails/models/sortable.rb
+- lib/concerns_on_rails/models/stateable.rb
 - lib/concerns_on_rails/models/tokenizable.rb
+- lib/concerns_on_rails/support/column_guard.rb
+- lib/concerns_on_rails/support/random_value.rb
 - lib/concerns_on_rails/version.rb
 homepage: https://github.com/VSN2015/concerns_on_rails
 licenses: