concerns_on_rails 1.8.2 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5126c79ca466ff1a85a20eb0d4a29f7a2d471bc4186e7b4762481bfad2084f42
-  data.tar.gz: '086922bf94b7efa7ef99699e4d96ab4e24ae2e731c2308bd1b0a8471e1f065a2'
+  metadata.gz: 743380a3be200eda289e97edef227f8b900550ba08af52c4a06b995fc5c8297a
+  data.tar.gz: 7e8e8cb4bfd923819ec96178d75e68378829fb0f80b5a2e3cf3cd84e150fcc32
 SHA512:
-  metadata.gz: 6b3e968d8cf97c9d11b14ff1d8374a64731ed3416d114ca0acf525a64f65843a35f0261da219d9f725e539eba7ac6460ba331a3aaf2b701b88627d841ac70a2a
-  data.tar.gz: 61f80dadd2112d36c1c1ceaf88fe01fb5dcf68f22911e1535e68414ecdbaca07ca363365c7ec3032c2698aec1cb0929d054036d2b8ebf73d1c347093976f3bb4
+  metadata.gz: 48e77b0bb95ee7419207289be7e1f74166f43aa4e31f4af6a6269ac2a84ccb90ac38e81a2a11a44cdafb7bd678d48153070c41d502b37f0a6baeabfd114f73f0
+  data.tar.gz: bb03d4bcfb6b26b7963f70cdaee8e591293fc8f96e34aa636aab84df6ce20647ae9df01e3d52554c8b6a9cb52cfce68c2da2c0f967ede2a3ec7960be737f4bd2

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 <!-- CHANGELOG.md -->
 
+## 1.10.0 (2026-06-03)
+
+### Added
+- **Models::Addressable**: Declarative postal-address normalization + format validation via a single `addressable_by` macro. Maps the canonical parts (`line1` / `line2` / `city` / `state` / `postal_code` / `country`) onto real columns — any subset works, missing columns are skipped, and required parts are schema-checked. Normalizes in `before_validation` (strip + squish, postal-code upcasing with canonical CA spacing, 2-letter country/state codes upcased) and validates required-part presence, ISO 3166-1 alpha-2 country codes, per-country postal formats (US/CA/GB/AU/DE/FR + a permissive fallback), and opt-in US/CA state codes. Offline and dependency-free; layer real deliverability checks via the opt-in `verify_with:` callable. Adds helpers `full_address`, `address_lines`, `address_present?`, `address_complete?`, and `address_attributes`.
+
+### Internal
+- Added `ConcernsOnRails::Support::AddressData` — ISO 3166-1 alpha-2 country codes, per-country postal-format patterns, US state / CA province sets, and the case-insensitive lookups (`valid_country?`, `postal_format_for`, `valid_state?`, `normalize_postal`) backing the Addressable concern.
+
+## 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,15 @@ 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
+  - [Addressable](#-addressable) — postal address normalization + format validation
 - **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 +54,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Eleven model concerns + five controller concerns**, all production-ready
+- **Thirteen 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 +67,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 +148,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 +217,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 +266,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 +281,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 +487,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 +578,130 @@ 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.
+
+---
+
+## 🏠 Addressable
+
+Normalize and format-validate a postal address spread across several columns — one macro for whitespace cleanup, postal-code and ISO country-code checks, required-part presence, and a `full_address` helper. No external geocoding service required.
+
+```ruby
+class Location < ApplicationRecord
+  include ConcernsOnRails::Addressable
+
+  addressable_by   # standard columns: line1, line2, city, state, postal_code, country
+end
+
+loc = Location.create(line1: "  1 Infinite  Loop ", city: "Cupertino",
+                      state: "ca", postal_code: "95014", country: "us")
+loc.line1         # => "1 Infinite Loop"   (stripped + squished)
+loc.state         # => "CA"                (2-letter code upcased)
+loc.country       # => "US"
+loc.full_address  # => "1 Infinite Loop, Cupertino, CA, 95014, US"
+```
+
+Map onto your own column names and tune behavior:
+
+```ruby
+class Place < ApplicationRecord
+  include ConcernsOnRails::Addressable
+
+  addressable_by line1: :street, postal_code: :zip, country: :country_code,
+                 required:        %i[line1 city postal_code country],
+                 default_country: "GB",                       # country used when the record has none
+                 validate_state:  true,                       # opt-in US/CA state-code check
+                 verify_with:     ->(rec) { Usps.verify(rec) } # opt-in external verifier
+end
+```
+
+**Options**
+
+| Option            | Default                              | Purpose                                                              |
+|-------------------|--------------------------------------|---------------------------------------------------------------------|
+| `line1:` … `country:` | same-named columns               | Map each canonical part to a real column. Missing columns are skipped. |
+| `required:`       | `%i[line1 city postal_code country]` | Parts (by canonical name) that must be present. Each must map to an existing column. |
+| `default_country:`| `"US"`                               | Country used to pick the postal-code format when the record has no recognized country. |
+| `validate_state:` | `false`                              | When `true`, validates the state against US / CA code sets.         |
+| `verify_with:`    | `nil`                                | A callable for real-world verification (see below).                 |
+
+**What it normalizes** (in `before_validation`)
+- Text parts: `strip` + `squish`.
+- `postal_code`: squish + upcase, with canonical spacing for CA (`A1A1A1` → `A1A 1A1`).
+- `country` / `state`: upcased when they look like a 2-letter code (full names left alone).
+
+**What it validates**
+- Presence of every `required:` part.
+- `country`: a 2-letter value must be a real ISO 3166-1 alpha-2 code.
+- `postal_code`: matched against a per-country pattern (US, CA, GB, AU, DE, FR) with a permissive fallback for everything else.
+- `state`: only when `validate_state: true` and the country is US/CA.
+
+**External verification (`verify_with:`)** — runs **only after** structural validation passes, so you never spend an API call on an obviously-broken address. The callable receives the record and may either add to `record.errors` itself, or return:
+
+| Return value      | Effect                                          |
+|-------------------|-------------------------------------------------|
+| `true` / `nil`    | success                                         |
+| `false`           | adds a generic `:base` error                    |
+| `String`          | added as a `:base` error                        |
+| `Array`           | each element added as a `:base` error           |
+
+**Notes**
+- Scope is **format/structure only** — it checks shape, not real-world deliverability. Plug a USPS/Google/Smarty client into `verify_with:` for that.
+- Error messages are plain English strings — no host-app i18n setup required.
+- Partial schemas just work: a model without a `line2` (or any other) column simply omits that part.
+- Pairs with [Normalizable](#-normalizable) when you also have non-address fields to clean up.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -709,6 +885,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 +956,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,6 @@ module ConcernsOnRails
   Searchable    = Models::Searchable
   Activatable   = Models::Activatable
   Tokenizable   = Models::Tokenizable
+  Stateable     = Models::Stateable
+  Addressable   = Models::Addressable
 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]) }