concerns_on_rails 1.23.0 → 1.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba3e5dc1bc6af51ec2bd4e29946973c5fc68736d4c1994fdbd472874f965c4bc
-  data.tar.gz: 16b2372635abe33484efabcae5407d1debe5a0627df9df0496a04e930c46ec65
+  metadata.gz: a5361fdba6417a0a46213e0e8e41f8ced13d00f76cb17f102404d1d794a98a39
+  data.tar.gz: 0fab62907022084c9b54d1cca52f8b4eeefbecced0a4bc905e4b3a8a55f8f582
 SHA512:
-  metadata.gz: 8a159b0026bca1ebc72dbc11c45e875caaa19ad2ec0615ee658abd5b3e8ab53e0bb309d816a5371ddba6bad5c609b82a76228e66d678d3346d624021634eddf5
-  data.tar.gz: da89fb098f9e17fd9ae49662efdb027efb64958007bf790ee895c0faf39a1c9f2cb76d2e95a4b0b3b075bcb404fe926c36d970f78ca152bdd287be81e7a3a991
+  metadata.gz: 5654215000d983a63260507d6741090add3b7861e200e81ebd180ad7d7de61891c0646c49b666d4b01b179b51ae88d1da73386ffb35bc1cbb24328d8f3238c99
+  data.tar.gz: 436b80fa129a4a3922a0a6b7ba4945f90205f1071a4d190875fa26e87458bb39ba483b0f682bff0c64cd3fb09fda79ec15cec776f22b3d085af03d14fe5a2275

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 <!-- CHANGELOG.md -->
 
+## 1.24.0 (2026-08-15)
+
+A developer-experience wave from the 2026-08-15 usability review: leaner install, lazy loading, teaching errors, and one-initializer store configuration. No behavior changes for configured concerns. 1084 examples, 0 failures.
+
+### Changed
+- **Dependencies**: the gem now depends on `actionpack` / `activerecord` / `activesupport` instead of the full `rails` meta-gem (API-only hosts stop pulling Action Cable / Mailbox / Text), and the `acts_as_list` constraint is `>= 0.7.5, < 2` — the old `~> 0.7.5` pin was an unresolvable Bundler conflict for any app already on acts_as_list 1.x. Suite verified against acts_as_list 1.2.6.
+- **Lazy loading**: `require "concerns_on_rails"` no longer eagerly loads all 40 concern/support files — everything is autoloaded on first constant reference, and `friendly_id` / `acts_as_list` load only when Sluggable / Sortable is actually used (a missing gem raises `ConcernsOnRails::MissingDependency`, a `LoadError` subclass whose message names the Gemfile line to add). The pre-1.6 top-level aliases (`ConcernsOnRails::Sluggable`, …) keep working, now resolved lazily via `const_missing`.
+- **Support::ColumnGuard** (all model concerns): the missing-column `ArgumentError` now teaches the fix — it appends a ready-to-paste `bin/rails generate migration ...` command carrying the concern's expected column type (e.g. `AddDeletedAtToArticles deleted_at:datetime`; token/slug columns suggest `string:uniq`, Encryptable blind-index columns `string:index`).
+
+### Added
+- **`ConcernsOnRails.setup`**: gem-wide configuration entry point (`lib/concerns_on_rails/configuration.rb`). First setting: `config.cache_store` — a store or a Proc (e.g. `-> { Rails.cache }`) used as the fallback store by `Controllers::Throttleable` and `Controllers::Idempotentable`, so one initializer line replaces per-controller `self.throttleable_store = ...` / `self.idempotency_store = ...` wiring. A class-level store still wins; with neither configured the concerns raise exactly as before.
+
 ## 1.23.0 (2026-07-26)
 
 Two new model concerns — the roadmap picks after 1.22's fixes round: the right-to-erasure capability that completes the sensitive-data suite, and the concern-aware deep copy that makes "duplicate this invoice" safe next to unique slugs, tokens, and sequence numbers. 1075 examples, 0 failures.

data/README.md

@@ -12,7 +12,7 @@ One `include`, one declarative macro — done.
 [![Rails](https://img.shields.io/badge/rails-5.0--8.x-CC0000?logo=rubyonrails&logoColor=white)](https://rubyonrails.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-3fb950.svg)](#-license)
 
-🧩 **23 model concerns**  ·  🎮 **16 controller concerns**  ·  🪶 **lean deps**  ·  ✅ **schema-validated**
+🧩 **26 model concerns**  ·  🎮 **16 controller concerns**  ·  🪶 **lean deps**  ·  ✅ **schema-validated**
 
 </div>
 
@@ -96,7 +96,7 @@ Article.published.without_deleted.find("hello-world")
 
 - **Twenty-six model concerns + sixteen 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
+- **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
 - **Composable** — concerns are independent; mix and match per model
 
@@ -107,7 +107,7 @@ Article.published.without_deleted.find("hello-world")
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.23"
+gem "concerns_on_rails", "~> 1.24"
 ```
 
 Or pull the latest from GitHub:
@@ -122,6 +122,27 @@ Then run:
 bundle install
 ```
 
+### Optional: one-initializer configuration
+
+Everything works with zero configuration. The store-backed controller concerns
+(`Throttleable`, `Idempotentable`) need a cache store — set it once, gem-wide,
+instead of per controller class:
+
+```ruby
+# config/initializers/concerns_on_rails.rb
+ConcernsOnRails.setup do |config|
+  config.cache_store = -> { Rails.cache }   # fallback for Throttleable / Idempotentable
+end
+
+# Encryptable's key lives in its own config (see the Encryptable section):
+ConcernsOnRails.configure_encryption do |c|
+  c.key = -> { Rails.application.credentials.dig(:encryption, :key) }
+end
+```
+
+A per-class `self.throttleable_store = ...` / `self.idempotency_store = ...`
+still wins over the gem-wide fallback.
+
 ---
 
 ## 🧪 Compatibility
@@ -1599,7 +1620,7 @@ Fixed-window counter: the key embeds a floored time bucket (`epoch / period`) so
 
 **Notes**
 - The store MUST support **atomic increment-with-expiry** (`Rails.cache` with `#increment`, or Redis) — a non-atomic store under-counts under concurrency.
-- There is **no in-process default store** on purpose: the first throttled request raises `ArgumentError` until you set `throttleable_store`, so you never silently rate-limit per-process.
+- There is **no in-process default store** on purpose: the first throttled request raises `ArgumentError` until you set `throttleable_store` (or the gem-wide fallback `ConcernsOnRails.setup { |c| c.cache_store = -> { Rails.cache } }`), so you never silently rate-limit per-process.
 - When `Respondable` is included, the 429 body delegates to `render_error` (`code: "rate_limited"`).
 - Backports the essentials of Rails 7.2's `rate_limit` (with standardized headers) to Rails 5.0+. For richer rules (fail2ban, allow/deny lists, exponential backoff) reach for [`rack-attack`](https://github.com/rack/rack-attack).
 
@@ -1648,7 +1669,7 @@ Per-key lifecycle: claim atomically (`write unless_exist`, TTL `lock_ttl:`) →
 
 **Notes**
 - Cache keys are scoped per `controller#action` and the client key is SHA256-hashed, so the same key on different endpoints never collides.
-- There is **no in-process default store** on purpose: the first keyed request raises `ArgumentError` until you set `idempotency_store`.
+- There is **no in-process default store** on purpose: the first keyed request raises `ArgumentError` until you set `idempotency_store` (or the gem-wide fallback `ConcernsOnRails.setup { |c| c.cache_store = -> { Rails.cache } }`).
 - When `Respondable` is included, the 400/409/422 bodies delegate to `render_error`.
 - Declare halting filters (authentication, `Throttleable`) **before** including this concern — a 401/403 rendered by an inner filter would be cached and replayed for the full TTL. Responses rendered by `rescue_from` handlers are never cached.
 - Keys must be ≤255 chars with no control characters (the raw key is echoed in `X-Idempotency-Key`); set `lock_ttl:` above the slowest declared action's worst case.
@@ -1813,7 +1834,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.23.0.gem      # install locally
+gem install ./concerns_on_rails-1.24.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/configuration.rb

@@ -0,0 +1,27 @@
+module ConcernsOnRails
+  # Gem-wide configuration, set once from an initializer:
+  #
+  #   ConcernsOnRails.setup do |config|
+  #     config.cache_store = -> { Rails.cache }
+  #   end
+  #
+  # `cache_store` is the fallback store consulted by Controllers::Throttleable
+  # and Controllers::Idempotentable when the controller class hasn't set its
+  # own (`self.throttleable_store = ...` / `self.idempotency_store = ...`
+  # still win). A store object or a zero-arg callable — prefer a Proc so
+  # `Rails.cache` is read lazily, after the framework has booted. The store
+  # contract is unchanged: atomic #increment for throttling, #read /
+  # #write(expires_in:, unless_exist:) / #delete for idempotency. There is
+  # still no in-process default on purpose — a non-atomic store silently
+  # under-counts, so the host must opt in explicitly (just once, here).
+  class Configuration
+    attr_accessor :cache_store
+
+    # The fallback store with any callable resolved (per lookup, so a Proc
+    # reading Rails.cache follows a swapped-out cache in tests). nil when the
+    # host never configured one.
+    def resolved_cache_store
+      cache_store.respond_to?(:call) ? cache_store.call : cache_store
+    end
+  end
+end

data/lib/concerns_on_rails/controllers/idempotentable.rb

@@ -33,8 +33,10 @@ module ConcernsOnRails
     # The claim is taken atomically via `write(..., unless_exist: true)`
     # (memcached `add` / Redis `SET NX` through Rails.cache); a store without
     # that atomicity is best-effort under concurrency. There is no in-process
-    # default store on purpose — configure one explicitly or the first keyed
-    # request raises ArgumentError. Note that responses rendered by
+    # default store on purpose — configure one explicitly (per controller as
+    # above, or once for the whole app via `ConcernsOnRails.setup { |c|
+    # c.cache_store = -> { Rails.cache } }`) or the first keyed request raises
+    # ArgumentError. Note that responses rendered by
     # `rescue_from` handlers bypass the around filter's success path and are
     # never cached.
     #
@@ -246,12 +248,13 @@ module ConcernsOnRails
       end
 
       def idempotency_store!
-        store = self.class.idempotency_store
+        store = self.class.idempotency_store || ConcernsOnRails.config.resolved_cache_store
         return store if store
 
         raise ArgumentError,
               "ConcernsOnRails::Controllers::Idempotentable: no store configured. " \
-              "Set `self.idempotency_store = Rails.cache` " \
+              "Set `self.idempotency_store = Rails.cache` on the controller, or the gem-wide " \
+              "fallback: ConcernsOnRails.setup { |c| c.cache_store = -> { Rails.cache } } " \
               "(must support #read, #write(expires_in:, unless_exist:) and #delete)."
       end
 

data/lib/concerns_on_rails/controllers/throttleable.rb

@@ -23,7 +23,9 @@ module ConcernsOnRails
     # exact. The store MUST support atomic increment-with-expiry (`Rails.cache`
     # with `#increment`, or Redis); a non-atomic store under-counts under
     # concurrency. There is no in-process default store on purpose — configure
-    # one explicitly or the first throttled request raises ArgumentError.
+    # one explicitly (per controller as above, or once for the whole app via
+    # `ConcernsOnRails.setup { |c| c.cache_store = -> { Rails.cache } }`) or
+    # the first throttled request raises ArgumentError.
     module Throttleable
       extend ActiveSupport::Concern
 
@@ -161,12 +163,14 @@ module ConcernsOnRails
       end
 
       def throttle_store!
-        store = self.class.throttleable_store
+        store = self.class.throttleable_store || ConcernsOnRails.config.resolved_cache_store
         return store if store
 
         raise ArgumentError,
               "ConcernsOnRails::Controllers::Throttleable: no store configured. " \
-              "Set `self.throttleable_store = Rails.cache` (must support atomic #increment)."
+              "Set `self.throttleable_store = Rails.cache` on the controller, or the gem-wide " \
+              "fallback: ConcernsOnRails.setup { |c| c.cache_store = -> { Rails.cache } } " \
+              "(must support atomic #increment)."
       end
 
       def throttle_action_name

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -1,31 +1,27 @@
 module ConcernsOnRails
-  # Backwards-compatibility aliases for pre-1.6 module paths.
-  # Existing apps doing `include ConcernsOnRails::Sluggable` continue to work;
-  # new code is encouraged to use the namespaced form: `ConcernsOnRails::Models::Sluggable`.
-  Sluggable     = Models::Sluggable
-  Sortable      = Models::Sortable
-  Publishable   = Models::Publishable
-  SoftDeletable = Models::SoftDeletable
-  Hashable      = Models::Hashable
-  Schedulable   = Models::Schedulable
-  Expirable     = Models::Expirable
-  Normalizable  = Models::Normalizable
-  Searchable    = Models::Searchable
-  Activatable   = Models::Activatable
-  Tokenizable   = Models::Tokenizable
-  Stateable     = Models::Stateable
-  Addressable   = Models::Addressable
-  Sequenceable  = Models::Sequenceable
-  Taggable      = Models::Taggable
-  Sanitizable   = Models::Sanitizable
-  Maskable      = Models::Maskable
-  Monetizable   = Models::Monetizable
-  Auditable     = Models::Auditable
-  Lockable      = Models::Lockable
-  Aliasable     = Models::Aliasable
-  Storable      = Models::Storable
-  CounterCacheable = Models::CounterCacheable
-  Encryptable = Models::Encryptable
-  Anonymizable = Models::Anonymizable
-  Duplicable = Models::Duplicable
+  # Backwards-compatibility aliases for pre-1.6 module paths, resolved lazily:
+  # eager `Sluggable = Models::Sluggable` assignments would force-load every
+  # concern file at boot and defeat the loader's autoload laziness. The first
+  # reference to `ConcernsOnRails::<Name>` loads the real module and pins the
+  # alias constant, so `include ConcernsOnRails::Sluggable` works unchanged.
+  # New code is encouraged to use the namespaced form:
+  # `ConcernsOnRails::Models::Sluggable`.
+  #
+  # Note `Sortable` resolves to Models::Sortable (as it always has) — the
+  # controller concern is only reachable as Controllers::Sortable.
+  LEGACY_MODEL_ALIASES = %i[
+    Sluggable Sortable Publishable SoftDeletable Hashable Schedulable
+    Expirable Normalizable Searchable Activatable Tokenizable Stateable
+    Addressable Sequenceable Taggable Sanitizable Maskable Monetizable
+    Auditable Lockable Aliasable Storable CounterCacheable Encryptable
+    Anonymizable Duplicable
+  ].freeze
+
+  def self.const_missing(name)
+    return super unless LEGACY_MODEL_ALIASES.include?(name)
+
+    # Idempotent under a concurrent first reference: both threads pin the
+    # same module object, and once pinned const_missing never fires again.
+    const_set(name, Models.const_get(name))
+  end
 end

data/lib/concerns_on_rails/models/activatable.rb

@@ -33,7 +33,7 @@ module ConcernsOnRails
 
         def activatable_by(field = DEFAULT_FIELD, prefix: nil, suffix: nil)
           self.activatable_field = field.to_sym
-          ensure_columns!("ConcernsOnRails::Models::Activatable", activatable_field)
+          ensure_columns!("ConcernsOnRails::Models::Activatable", activatable_field, types: :boolean)
 
           # Affix the scope names so two concerns that each define `.active`
           # (e.g. SoftDeletable / Expirable) can coexist on one model.

data/lib/concerns_on_rails/models/addressable.rb

@@ -86,7 +86,7 @@ module ConcernsOnRails
           raise ArgumentError, "#{LABEL}: unknown address part(s): #{unknown.join(', ')}" if unknown.any?
 
           overrides = mapping.to_h { |part, column| [part.to_sym, column.to_sym] }
-          ensure_columns!(LABEL, overrides.values)
+          ensure_columns!(LABEL, overrides.values, types: :string)
           DEFAULT_FIELDS.merge(overrides).select { |_part, column| column_names.include?(column.to_s) }
         end
 

data/lib/concerns_on_rails/models/auditable.rb

@@ -74,7 +74,7 @@ module ConcernsOnRails
           self.auditable_actor = actor
           self.auditable_max_entries = max_entries
           self.auditable_max_value_length = max_value_length
-          ensure_columns!(LABEL, into, *fields)
+          ensure_columns!(LABEL, into, *fields, types: { into => :text })
           auditable_guard_encryptable!(fields)
 
           before_save :auditable_capture_changes

data/lib/concerns_on_rails/models/counter_cacheable.rb

@@ -139,7 +139,7 @@ module ConcernsOnRails
           end
           return unless klass
 
-          ensure_columns_on!(LABEL, klass, count_column)
+          ensure_columns_on!(LABEL, klass, count_column, types: :integer)
         end
 
         def counter_cacheable_recount_rule(rule)

data/lib/concerns_on_rails/models/encryptable.rb

@@ -232,13 +232,13 @@ module ConcernsOnRails
         def encryptable(*fields, type: :string, key: nil, blind_index: nil)
           type = type.to_sym
           encryptable_validate!(fields, type, blind_index)
-          ensure_columns!(LABEL, *fields)
+          ensure_columns!(LABEL, *fields, types: :text)
 
           fields.each do |field|
             field = field.to_sym
             encryptable_guard_auditable!(field)
             bi = encryptable_normalize_blind_index(field, blind_index)
-            ensure_columns!(LABEL, bi[:column]) if bi
+            ensure_columns!(LABEL, bi[:column], types: "string:index") if bi
             self.encryptable_rules = encryptable_rules.merge(field => { type: type, key: key, blind_index: bi })
             attribute field, EncryptedType.new(type: type, key: key)
             encryptable_define_helpers(field)

data/lib/concerns_on_rails/models/expirable.rb

@@ -21,7 +21,7 @@ module ConcernsOnRails
         #   expirable_by :valid_until
         def expirable_by(field = DEFAULT_FIELD, prefix: nil, suffix: nil)
           self.expirable_field = field.to_sym
-          ensure_columns!("ConcernsOnRails::Models::Expirable", expirable_field)
+          ensure_columns!("ConcernsOnRails::Models::Expirable", expirable_field, types: :datetime)
           define_expirable_scopes(prefix, suffix)
         end
 

data/lib/concerns_on_rails/models/hashable.rb

@@ -37,7 +37,8 @@ module ConcernsOnRails
           self.hashable_alphabet = alphabet
           self.hashable_unique = unique
 
-          ensure_columns!("ConcernsOnRails::Models::Hashable", hashable_field)
+          ensure_columns!("ConcernsOnRails::Models::Hashable", hashable_field,
+                          types: hashable_unique ? "string:uniq" : :string)
           validate_hashable_options!
           before_create :assign_hashable_value
 

data/lib/concerns_on_rails/models/lockable.rb

@@ -75,7 +75,8 @@ module ConcernsOnRails
           self.lockable_locked_at_field = locked_at
           self.lockable_max_attempts = max_attempts
           self.lockable_unlock_in = unlock_in
-          ensure_columns!(LABEL, attempts, locked_at)
+          ensure_columns!(LABEL, attempts, locked_at,
+                          types: { attempts => :integer, locked_at => :datetime })
           validate_lockable_attempts_column!(attempts)
           define_lockable_scopes(prefix, suffix)
         end

data/lib/concerns_on_rails/models/monetizable.rb

@@ -47,7 +47,7 @@ module ConcernsOnRails
             raise ArgumentError, "ConcernsOnRails::Models::Monetizable: :subunit_to_unit must be a positive integer"
           end
 
-          ensure_columns!("ConcernsOnRails::Models::Monetizable", fields)
+          ensure_columns!("ConcernsOnRails::Models::Monetizable", fields, types: :integer)
           config = { unit: unit, precision: precision, delimiter: delimiter, separator: separator, subunit_to_unit: subunit_to_unit }
           fields.each { |cents_field| define_money_accessors(cents_field.to_sym, as, config) }
         end

data/lib/concerns_on_rails/models/publishable.rb

@@ -53,7 +53,7 @@ module ConcernsOnRails
         def publishable_by(field = nil, default_scope: false)
           self.publishable_field = field || :published_at
           @publishable_boolean_column = nil
-          ensure_columns!("ConcernsOnRails::Models::Publishable", publishable_field)
+          ensure_columns!("ConcernsOnRails::Models::Publishable", publishable_field, types: :datetime)
           enable_published_default_scope if default_scope
         end
 

data/lib/concerns_on_rails/models/schedulable.rb

@@ -56,7 +56,7 @@ module ConcernsOnRails
           end
 
           ensure_columns!("ConcernsOnRails::Models::Schedulable",
-                          schedulable_starts_at_field, schedulable_ends_at_field)
+                          schedulable_starts_at_field, schedulable_ends_at_field, types: :datetime)
         end
       end
 

data/lib/concerns_on_rails/models/sequenceable.rb

@@ -62,10 +62,10 @@ module ConcernsOnRails
           reset      = reset.to_sym
           scope_cols = Array(scope).map(&:to_sym)
 
-          ensure_columns!(NAME, field)
-          ensure_columns!(NAME, into) if into
+          ensure_columns!(NAME, field, types: :integer)
+          ensure_columns!(NAME, into, types: :string) if into
           ensure_columns!(NAME, *scope_cols) unless scope_cols.empty?
-          ensure_columns!(NAME, :created_at) unless reset == :never
+          ensure_columns!(NAME, :created_at, types: :datetime) unless reset == :never
           validate_sequenceable_options!(reset, template)
 
           self.sequenceable_config = sequenceable_config.merge(

data/lib/concerns_on_rails/models/sluggable.rb

@@ -1,6 +1,15 @@
 require "active_support/concern"
 require "concerns_on_rails/support/column_guard"
-require "friendly_id"
+
+# Loaded here — with the concern, on first use — rather than at gem boot, so
+# apps that never include Sluggable never load friendly_id.
+begin
+  require "friendly_id"
+rescue LoadError
+  raise ConcernsOnRails::MissingDependency,
+        "ConcernsOnRails::Models::Sluggable requires the friendly_id gem. " \
+        'Add `gem "friendly_id", "~> 5.4"` to your Gemfile to use it.'
+end
 
 module ConcernsOnRails
   module Models
@@ -59,7 +68,8 @@ module ConcernsOnRails
           # first save with an opaque friendly_id error instead of this
           # concern's clear ArgumentError.
           ensure_columns!("ConcernsOnRails::Models::Sluggable",
-                          [sluggable_field, friendly_id_config.slug_column, scope].compact)
+                          [sluggable_field, friendly_id_config.slug_column, scope].compact,
+                          types: { friendly_id_config.slug_column.to_sym => "string:uniq" })
           return unless history || scope || reserved_words || finders
 
           reconfigure_friendly_id(history: history, scope: scope,

data/lib/concerns_on_rails/models/soft_deletable.rb

@@ -50,7 +50,7 @@ module ConcernsOnRails
           self.soft_delete_field = field || :deleted_at
           self.soft_delete_touch = touch
           self.soft_delete_default_scope = default_scope
-          ensure_columns!("ConcernsOnRails::Models::SoftDeletable", soft_delete_field)
+          ensure_columns!("ConcernsOnRails::Models::SoftDeletable", soft_delete_field, types: :datetime)
         end
 
         # Soft-delete every matching record. Returns the Integer count of

data/lib/concerns_on_rails/models/sortable.rb

@@ -1,6 +1,15 @@
 require "active_support/concern"
 require "concerns_on_rails/support/column_guard"
-require "acts_as_list"
+
+# Loaded here — with the concern, on first use — rather than at gem boot, so
+# apps that never include Sortable never load acts_as_list.
+begin
+  require "acts_as_list"
+rescue LoadError
+  raise ConcernsOnRails::MissingDependency,
+        "ConcernsOnRails::Models::Sortable requires the acts_as_list gem. " \
+        'Add `gem "acts_as_list"` to your Gemfile to use it.'
+end
 
 module ConcernsOnRails
   module Models
@@ -62,7 +71,7 @@ module ConcernsOnRails
           self.sortable_field = field
           self.sortable_direction = direction
 
-          ensure_columns!("ConcernsOnRails::Models::Sortable", sortable_field)
+          ensure_columns!("ConcernsOnRails::Models::Sortable", sortable_field, types: :integer)
 
           return unless use_acts_as_list
 

data/lib/concerns_on_rails/models/stateable.rb

@@ -90,7 +90,7 @@ module ConcernsOnRails
           self.stateable_transitions = options[:transitions] || {}
           self.stateable_prefix = stateable_affix(options[:prefix])
           self.stateable_suffix = stateable_affix(options[:suffix])
-          ensure_columns!(LABEL, stateable_field)
+          ensure_columns!(LABEL, stateable_field, types: :string)
         end
 
         # `true` => use the field name; a string/symbol => use it literally; else none.

data/lib/concerns_on_rails/models/storable.rb

@@ -104,7 +104,7 @@ module ConcernsOnRails
         # named `prefix`/`suffix`. See the module docs.
         def storable_by(column, keys = {}, prefix: nil, suffix: nil, **kw_keys)
           column = column.to_sym
-          ensure_columns!(LABEL, column)
+          ensure_columns!(LABEL, column, types: :text)
 
           prepared = storable_merge_key_specs(keys, kw_keys).map do |key, raw_spec|
             key = key.to_sym

data/lib/concerns_on_rails/models/taggable.rb

@@ -53,7 +53,7 @@ module ConcernsOnRails
           self.taggable_field = field.to_sym
           self.taggable_delimiter = delimiter.to_s
           self.taggable_downcase = downcase
-          ensure_columns!(LABEL, taggable_field)
+          ensure_columns!(LABEL, taggable_field, types: :string)
 
           before_validation :taggable_normalize!
         end

data/lib/concerns_on_rails/models/tokenizable.rb

@@ -56,7 +56,7 @@ module ConcernsOnRails
           type = type.to_sym
           length = length.to_i
 
-          ensure_columns!("ConcernsOnRails::Models::Tokenizable", field)
+          ensure_columns!("ConcernsOnRails::Models::Tokenizable", field, types: "string:uniq")
           validate_tokenizable_options!(type, length)
 
           # Build a fresh hash so subclasses don't mutate the parent's config.

data/lib/concerns_on_rails/support/column_guard.rb

@@ -1,3 +1,5 @@
+require "active_support/core_ext/string/inflections"
+
 module ConcernsOnRails
   module Support
     # Shared schema-validation helper mixed into a concern's ClassMethods.
@@ -27,24 +29,41 @@ module ConcernsOnRails
     # The phrase "does not exist" is preserved so existing specs that match
     # /does not exist/ keep passing.
     module ColumnGuard
-      def ensure_columns!(concern, *fields)
-        ensure_columns_on!(concern, self, *fields)
+      # `types:` teaches the error message: a Symbol/String applies to every
+      # listed field, a Hash maps field => type. When present, the raised
+      # ArgumentError appends a ready-to-paste migration command. Generator
+      # column-modifier syntax is welcome ("string:uniq" — tokens/slugs want a
+      # unique index anyway).
+      def ensure_columns!(concern, *fields, types: nil)
+        ensure_columns_on!(concern, self, *fields, types: types)
       end
 
       # Same contract, validated against another class (e.g. CounterCacheable
       # checks the counter column on the *parent* model).
-      def ensure_columns_on!(concern, klass, *fields)
+      def ensure_columns_on!(concern, klass, *fields, types: nil)
         return false unless schema_reachable?(klass)
 
         fields.flatten.compact.each do |field|
           next if klass.column_names.include?(field.to_s)
 
           raise ArgumentError,
-                "#{concern}: '#{field}' does not exist in the database (table: #{klass.table_name})"
+                "#{concern}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
+                "#{column_migration_hint(klass, field, types)}"
         end
         true
       end
 
+      # " Add it with: bin/rails generate migration AddDeletedAtToArticles
+      # deleted_at:datetime" — every missing-column failure becomes a
+      # copy-paste fix. Without a known type the column name goes out bare
+      # (the generator defaults to string).
+      def column_migration_hint(klass, field, types)
+        type = types.is_a?(Hash) ? types[field.to_sym] : types
+        column = [field, type].compact.join(":")
+        " Add it with: bin/rails generate migration " \
+          "Add#{field.to_s.camelize}To#{klass.table_name.to_s.camelize} #{column}"
+      end
+
       # True when the class's table can actually be inspected. Connection
       # errors (ConnectionNotEstablished, NoDatabaseError, adapter errors)
       # all inherit from ActiveRecord::ActiveRecordError.

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.23.0".freeze
+  VERSION = "1.24.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -3,9 +3,86 @@ require "active_support/deprecation"
 require "concerns_on_rails/version"
 
 module ConcernsOnRails
-  module Models; end
-  module Controllers; end
-  module Support; end
+  # Raised (as a LoadError subclass, so a bare `rescue LoadError` still works)
+  # when a concern needs a third-party gem that isn't available. friendly_id
+  # and acts_as_list load lazily with the concern that uses them (Sluggable /
+  # Sortable), so hosts that never touch those concerns never load them.
+  class MissingDependency < LoadError; end
+
+  # Everything below is autoloaded on first constant reference instead of
+  # eagerly required: an app that uses two concerns loads two files (plus
+  # their support helpers), not all forty — and friendly_id / acts_as_list
+  # stay unloaded unless Sluggable / Sortable is actually included.
+  # Each concern file requires the Support helpers it uses, so a direct
+  # `require "concerns_on_rails/models/sluggable"` keeps working too.
+
+  module Models
+    autoload :Sluggable,        "concerns_on_rails/models/sluggable"
+    autoload :Sortable,         "concerns_on_rails/models/sortable"
+    autoload :Publishable,      "concerns_on_rails/models/publishable"
+    autoload :SoftDeletable,    "concerns_on_rails/models/soft_deletable"
+    autoload :Hashable,         "concerns_on_rails/models/hashable"
+    autoload :Schedulable,      "concerns_on_rails/models/schedulable"
+    autoload :Expirable,        "concerns_on_rails/models/expirable"
+    autoload :Normalizable,     "concerns_on_rails/models/normalizable"
+    autoload :Searchable,       "concerns_on_rails/models/searchable"
+    autoload :Activatable,      "concerns_on_rails/models/activatable"
+    autoload :Tokenizable,      "concerns_on_rails/models/tokenizable"
+    autoload :Stateable,        "concerns_on_rails/models/stateable"
+    autoload :Addressable,      "concerns_on_rails/models/addressable"
+    autoload :Sequenceable,     "concerns_on_rails/models/sequenceable"
+    autoload :Taggable,         "concerns_on_rails/models/taggable"
+    autoload :Sanitizable,      "concerns_on_rails/models/sanitizable"
+    autoload :Maskable,         "concerns_on_rails/models/maskable"
+    autoload :Monetizable,      "concerns_on_rails/models/monetizable"
+    autoload :Auditable,        "concerns_on_rails/models/auditable"
+    autoload :Lockable,         "concerns_on_rails/models/lockable"
+    autoload :Aliasable,        "concerns_on_rails/models/aliasable"
+    autoload :Storable,         "concerns_on_rails/models/storable"
+    autoload :CounterCacheable, "concerns_on_rails/models/counter_cacheable"
+    autoload :Encryptable,      "concerns_on_rails/models/encryptable"
+    autoload :Anonymizable,     "concerns_on_rails/models/anonymizable"
+    autoload :Duplicable,       "concerns_on_rails/models/duplicable"
+  end
+
+  module Controllers
+    autoload :Paginatable,       "concerns_on_rails/controllers/paginatable"
+    autoload :Filterable,        "concerns_on_rails/controllers/filterable"
+    autoload :Sortable,          "concerns_on_rails/controllers/sortable"
+    autoload :Respondable,       "concerns_on_rails/controllers/respondable"
+    autoload :ErrorHandleable,   "concerns_on_rails/controllers/error_handleable"
+    autoload :Includable,        "concerns_on_rails/controllers/includable"
+    autoload :SecureHeadable,    "concerns_on_rails/controllers/secure_headable"
+    autoload :Localizable,       "concerns_on_rails/controllers/localizable"
+    autoload :Authorizable,      "concerns_on_rails/controllers/authorizable"
+    autoload :Throttleable,      "concerns_on_rails/controllers/throttleable"
+    autoload :Timezoneable,      "concerns_on_rails/controllers/timezoneable"
+    autoload :Idempotentable,    "concerns_on_rails/controllers/idempotentable"
+    autoload :WebhookVerifiable, "concerns_on_rails/controllers/webhook_verifiable"
+    autoload :CursorPaginatable, "concerns_on_rails/controllers/cursor_paginatable"
+    autoload :Deprecatable,      "concerns_on_rails/controllers/deprecatable"
+    autoload :Cacheable,         "concerns_on_rails/controllers/cacheable"
+  end
+
+  module Support
+    autoload :ColumnGuard,             "concerns_on_rails/support/column_guard"
+    autoload :ScalarParam,             "concerns_on_rails/support/scalar_param"
+    autoload :UniqueRetry,             "concerns_on_rails/support/unique_retry"
+    autoload :ErrorEnvelope,           "concerns_on_rails/support/error_envelope"
+    autoload :FilterParameterRegistry, "concerns_on_rails/support/filter_parameter_registry"
+    autoload :RandomValue,             "concerns_on_rails/support/random_value"
+    autoload :AddressData,             "concerns_on_rails/support/address_data"
+    autoload :SequenceCalculator,      "concerns_on_rails/support/sequence_calculator"
+    autoload :HtmlSanitizers,          "concerns_on_rails/support/html_sanitizers"
+    autoload :Masker,                  "concerns_on_rails/support/masker"
+    autoload :Money,                   "concerns_on_rails/support/money"
+    autoload :Encryptor,               "concerns_on_rails/support/encryptor"
+  end
+
+  # Encryption config + error types (Support::Encryptor requires it itself)
+  autoload :Encryption, "concerns_on_rails/encryption"
+  # Gem-wide configuration object behind ConcernsOnRails.setup
+  autoload :Configuration, "concerns_on_rails/configuration"
 
   # Guards the lazy singletons below: the first encrypted attribute read (or
   # deprecation warning) can happen on any request thread, and an unsynchronized
@@ -26,6 +103,20 @@ module ConcernsOnRails
     end
   end
 
+  # Gem-wide configuration (see Configuration), set from an initializer:
+  #
+  #   ConcernsOnRails.setup do |config|
+  #     config.cache_store = -> { Rails.cache }
+  #   end
+  def self.config
+    @config || @config_mutex.synchronize { @config ||= Configuration.new }
+  end
+
+  def self.setup
+    yield config if block_given?
+    config
+  end
+
   # Gem-wide encryption configuration backing Models::Encryptable. Memoized like
   # `deprecator`; the host app supplies the key (see ConcernsOnRails::Encryption):
   #
@@ -54,70 +145,7 @@ module ConcernsOnRails
   end
 end
 
-# Encryption config + error types (loaded before the support codec that uses them)
-require "concerns_on_rails/encryption"
-
-# Shared internal helpers (must load before the concerns that use them)
-require "concerns_on_rails/support/column_guard"
-require "concerns_on_rails/support/scalar_param"
-require "concerns_on_rails/support/unique_retry"
-require "concerns_on_rails/support/error_envelope"
-require "concerns_on_rails/support/filter_parameter_registry"
-require "concerns_on_rails/support/random_value"
-require "concerns_on_rails/support/address_data"
-require "concerns_on_rails/support/sequence_calculator"
-require "concerns_on_rails/support/html_sanitizers"
-require "concerns_on_rails/support/masker"
-require "concerns_on_rails/support/money"
-require "concerns_on_rails/support/encryptor"
-
-# Model concerns
-require "concerns_on_rails/models/sluggable"
-require "concerns_on_rails/models/sortable"
-require "concerns_on_rails/models/publishable"
-require "concerns_on_rails/models/soft_deletable"
-require "concerns_on_rails/models/hashable"
-require "concerns_on_rails/models/schedulable"
-require "concerns_on_rails/models/expirable"
-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"
-require "concerns_on_rails/models/addressable"
-require "concerns_on_rails/models/sequenceable"
-require "concerns_on_rails/models/taggable"
-require "concerns_on_rails/models/sanitizable"
-require "concerns_on_rails/models/maskable"
-require "concerns_on_rails/models/monetizable"
-require "concerns_on_rails/models/auditable"
-require "concerns_on_rails/models/lockable"
-require "concerns_on_rails/models/aliasable"
-require "concerns_on_rails/models/storable"
-require "concerns_on_rails/models/counter_cacheable"
-require "concerns_on_rails/models/encryptable"
-require "concerns_on_rails/models/anonymizable"
-require "concerns_on_rails/models/duplicable"
-
-# Controller concerns
-require "concerns_on_rails/controllers/paginatable"
-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"
-require "concerns_on_rails/controllers/secure_headable"
-require "concerns_on_rails/controllers/localizable"
-require "concerns_on_rails/controllers/authorizable"
-require "concerns_on_rails/controllers/throttleable"
-require "concerns_on_rails/controllers/timezoneable"
-require "concerns_on_rails/controllers/idempotentable"
-require "concerns_on_rails/controllers/webhook_verifiable"
-require "concerns_on_rails/controllers/cursor_paginatable"
-require "concerns_on_rails/controllers/deprecatable"
-require "concerns_on_rails/controllers/cacheable"
-
-# Backwards compatibility (top-level aliases for pre-1.6 module paths)
+# Backwards compatibility (lazy top-level aliases for pre-1.6 module paths)
 require "concerns_on_rails/legacy_aliases"
 
 # Boot-time integration (filter_parameters registration), Rails apps only

metadata

@@ -1,17 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.23.0
+  version: 1.24.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-27 00:00:00.000000000 Z
+date: 2026-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: actionpack
+  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: activerecord
+  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: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -34,16 +74,22 @@ dependencies:
   name: acts_as_list
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.7.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.7.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: friendly_id
   requirement: !ruby/object:Gem::Requirement
@@ -71,6 +117,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/concerns_on_rails.rb
+- lib/concerns_on_rails/configuration.rb
 - lib/concerns_on_rails/controllers/authorizable.rb
 - lib/concerns_on_rails/controllers/cacheable.rb
 - lib/concerns_on_rails/controllers/cursor_paginatable.rb