concerns_on_rails 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a0e7d53400756b8d2d3c27685da15e9f087f152fd6098beefb418a139f0b710
-  data.tar.gz: b11475b0b5c0b494d6ef4f356840bf63570519f85ba9c4d348d11026997937af
+  metadata.gz: 7bdaf4512b253a9c3b7307ace69f16d616f180d38ce3a3f5292099f0c97dedb5
+  data.tar.gz: de2843d32ebd1cea0e3c9fce3e8f5d6d18adaa6eb6e92ce4056af3bb2ab4d368
 SHA512:
-  metadata.gz: 4377941466783167c7f797e00b45a13d4280ce19127323407a671c30ee85bf1791500a60203e3e2141510bbb699fbad6bda5febd5b6706639236dca62741fc20
-  data.tar.gz: 9eb22fb7cca58c2bebd9544a558bbb7e060450a02377cee7f5d5ed13b68c453a26d67aca894ed3939aa5d79dfcc92c8874215f646db79b5441151c3a44070a55
+  metadata.gz: 315ff80a677ef032630d0b81f8c0b5c3b88d132a288ad075ed00732e2d676ccef954725c8966231af793ee89dc2485cb48e6b0c1de03ea93d47c7f283545815d
+  data.tar.gz: 13c59b78fc2b9dbd8dfca9877550a3a7fcd778fca493dd1b97c9151f9c4d111f94aa8eb3d8692b9b7e0299ccd52bf270944dee2a6987aae3c88917532cce2404

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 <!-- CHANGELOG.md -->
 
+## 1.7.0 (2026-05-21)
+
+### Added
+- **Models::Searchable**: LIKE-based search across one or more columns via `searchable_by :title, :body`. Adds a `.search(query)` scope that uses Arel's `matches` (emits `ILIKE` on Postgres, `LIKE` elsewhere), ORs predicates across all configured fields, escapes user input so `%` / `_` / `\` are treated as literals, and returns the full relation for blank queries.
+- **Models::Activatable**: Boolean active/inactive toggle via `activatable_by` (defaults to the `:active` column). Adds `.active` / `.inactive` scopes (treats `NULL` as inactive), predicates (`active?`, `inactive?`), and mutators (`activate!`, `deactivate!`, `toggle_active!`).
+- **Controllers::ErrorHandleable**: `rescue_from` handlers for `ActiveRecord::RecordNotFound` (404), `ActionController::ParameterMissing` (400), and `ActiveRecord::RecordInvalid` (422) that render the same JSON envelope as `Respondable#render_error`. Each handler is overridable for custom wording. Pairs naturally with `Respondable`.
+
 ## 1.6.0 (2026-05-19)
 
 ### Added

data/README.md

@@ -33,11 +33,14 @@ Article.published.without_deleted.find("hello-world")
   - [Schedulable](#-schedulable) — `starts_at` / `ends_at` time windows
   - [Expirable](#-expirable) — single-timestamp expiry
   - [Normalizable](#-normalizable) — attribute normalization (`:email`, `:phone`, …)
+  - [Searchable](#-searchable) — LIKE/ILIKE search across configured columns
+  - [Activatable](#-activatable) — boolean active/inactive toggle
 - **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
 - [Module paths & namespacing](#-module-paths--namespacing)
 - [Development](#-development)
 - [Contributing](#-contributing)
@@ -47,7 +50,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Eight model concerns + four controller concerns**, all production-ready
+- **Ten model concerns + five 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
@@ -60,7 +63,7 @@ Article.published.without_deleted.find("hello-world")
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.6"
+gem "concerns_on_rails", "~> 1.7"
 ```
 
 Or pull the latest from GitHub:
@@ -429,6 +432,59 @@ User.create(phone: "+1 (415) 555-1234").phone       # => "14155551234"
 
 ---
 
+## 🔍 Searchable
+
+LIKE-based search across one or more columns — no external search engine, no extra gems.
+
+```ruby
+class Article < ApplicationRecord
+  include ConcernsOnRails::Searchable
+
+  searchable_by :title, :body
+end
+
+Article.search("hello")                # WHERE title ILIKE '%hello%' OR body ILIKE '%hello%'
+Article.search("")                     # no-op — returns the full relation
+Article.search("foo").where(state: 1)  # chainable like any scope
+```
+
+**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.
+
+---
+
+## ✅ Activatable
+
+Boolean active/inactive toggle backed by a single column.
+
+```ruby
+class Subscription < ApplicationRecord
+  include ConcernsOnRails::Activatable
+
+  activatable_by               # defaults to :active
+  # activatable_by :enabled    # custom column name
+end
+
+sub = Subscription.create!(active: true)
+sub.active?            # => true
+sub.deactivate!
+sub.inactive?          # => true
+sub.toggle_active!     # flips back to true
+
+Subscription.active     # WHERE active = TRUE
+Subscription.inactive   # WHERE active = FALSE OR active IS NULL
+```
+
+**Notes**
+- `NULL` is treated as inactive (same convention as most apps' "unset = off").
+- The configured column must exist; `activatable_by` raises `ArgumentError` otherwise.
+- `SoftDeletable` also defines a `.active` scope (alias of `.without_deleted`). If both concerns are included on the same model, the later one wins — include the one whose `.active` semantics you want last, or stick to one of them.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -567,6 +623,51 @@ end
 
 ---
 
+## 🛟 ErrorHandleable
+
+Install `rescue_from` handlers for the three most common controller exceptions and render them as the same JSON envelope used by Respondable.
+
+```ruby
+class Api::BaseController < ApplicationController
+  include ConcernsOnRails::Controllers::Respondable       # recommended
+  include ConcernsOnRails::Controllers::ErrorHandleable
+end
+```
+
+**Handled exceptions**
+
+| Exception                              | Status | `code`                |
+|----------------------------------------|--------|-----------------------|
+| `ActiveRecord::RecordNotFound`         | 404    | `"not_found"`         |
+| `ActionController::ParameterMissing`   | 400    | `"parameter_missing"` |
+| `ActiveRecord::RecordInvalid`          | 422    | `"record_invalid"`    |
+
+Response shape (matches `Respondable#render_error`):
+
+```json
+{ "success": false, "error": { "message": "...", "code": "...", "details": [...] } }
+```
+
+**Overriding a handler**
+
+Each handler is a public instance method, so subclasses can customize the message or response shape without re-declaring the `rescue_from`:
+
+```ruby
+class Api::BaseController < ApplicationController
+  include ConcernsOnRails::Controllers::ErrorHandleable
+
+  def handle_record_not_found(error)
+    render json: { success: false, error: { message: "Not here, friend." } }, status: :not_found
+  end
+end
+```
+
+**Notes**
+- When `Respondable` is also included, the handlers delegate to `render_error` so the envelope shape stays in one place. Otherwise they render the same envelope inline.
+- `RecordInvalid.details` are populated from `error.record.errors.full_messages`.
+
+---
+
 ## 🗂️ Module paths & namespacing
 
 Every concern is available under two paths:
@@ -598,7 +699,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.6.0.gem       # install locally
+gem install ./concerns_on_rails-1.7.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/error_handleable.rb

@@ -0,0 +1,72 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Controllers
+    # Installs `rescue_from` handlers for the three most common controller
+    # exceptions and renders them as the JSON error envelope used by Respondable.
+    #
+    #   class Api::BaseController < ApplicationController
+    #     include ConcernsOnRails::Controllers::Respondable      # optional, but recommended
+    #     include ConcernsOnRails::Controllers::ErrorHandleable
+    #   end
+    #
+    # Handled:
+    #   * ActiveRecord::RecordNotFound          → 404 not_found
+    #   * ActionController::ParameterMissing    → 400 parameter_missing
+    #   * ActiveRecord::RecordInvalid           → 422 record_invalid (with field errors)
+    #
+    # If Respondable is also included on the controller, the handlers delegate
+    # to `render_error` so the envelope shape stays in one place. Otherwise the
+    # handlers render the same envelope inline.
+    #
+    # Each handler is a public instance method, so subclasses can override the
+    # message wording or response shape without re-declaring the `rescue_from`.
+    module ErrorHandleable
+      extend ActiveSupport::Concern
+
+      included do
+        rescue_from "ActiveRecord::RecordNotFound",       with: :handle_record_not_found
+        rescue_from "ActionController::ParameterMissing", with: :handle_parameter_missing
+        rescue_from "ActiveRecord::RecordInvalid",        with: :handle_record_invalid
+      end
+
+      def handle_record_not_found(error)
+        render_error_envelope(
+          message: error.message,
+          code: "not_found",
+          status: :not_found
+        )
+      end
+
+      def handle_parameter_missing(error)
+        render_error_envelope(
+          message: "Parameter missing: #{error.param}",
+          code: "parameter_missing",
+          status: :bad_request
+        )
+      end
+
+      def handle_record_invalid(error)
+        record = error.respond_to?(:record) ? error.record : nil
+        details = record.respond_to?(:errors) ? record.errors.full_messages : nil
+
+        render_error_envelope(
+          message: error.message,
+          code: "record_invalid",
+          status: :unprocessable_entity,
+          errors: details
+        )
+      end
+
+      private
+
+      def render_error_envelope(message:, code:, status:, errors: nil)
+        return render_error(message: message, code: code, status: status, errors: errors) if respond_to?(:render_error)
+
+        error = { message: message, code: code }
+        error[:details] = errors if errors
+        render json: { success: false, error: error }, status: status
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -10,4 +10,6 @@ module ConcernsOnRails
   Schedulable   = Models::Schedulable
   Expirable     = Models::Expirable
   Normalizable  = Models::Normalizable
+  Searchable    = Models::Searchable
+  Activatable   = Models::Activatable
 end

data/lib/concerns_on_rails/models/activatable.rb

@@ -0,0 +1,65 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Models
+    # Boolean active/inactive toggle backed by a single column.
+    #
+    #   class Subscription < ApplicationRecord
+    #     include ConcernsOnRails::Activatable
+    #
+    #     activatable_by             # defaults to :active
+    #     # activatable_by :enabled  # custom column name
+    #   end
+    #
+    #   Subscription.active     # WHERE active = TRUE
+    #   Subscription.inactive   # WHERE active = FALSE OR active IS NULL
+    #
+    # NULL is treated as inactive, mirroring how unset booleans behave in most apps.
+    #
+    # Note: SoftDeletable also defines a `.active` scope (alias of `.without_deleted`).
+    # If both concerns are included on the same model, the later one wins.
+    module Activatable
+      extend ActiveSupport::Concern
+
+      DEFAULT_FIELD = :active
+
+      included do
+        class_attribute :activatable_field, instance_accessor: false, default: DEFAULT_FIELD
+      end
+
+      class_methods do
+        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
+
+          scope :active,   -> { where(activatable_field => true) }
+          scope :inactive, -> { where(activatable_field => [false, nil]) }
+        end
+      end
+
+      def active?
+        self[self.class.activatable_field] == true
+      end
+
+      def inactive?
+        !active?
+      end
+
+      def activate!
+        update(self.class.activatable_field => true)
+      end
+
+      def deactivate!
+        update(self.class.activatable_field => false)
+      end
+
+      def toggle_active!
+        active? ? deactivate! : activate!
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/models/searchable.rb

@@ -0,0 +1,58 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Models
+    # LIKE-based search across one or more columns.
+    #
+    #   class Article < ApplicationRecord
+    #     include ConcernsOnRails::Searchable
+    #
+    #     searchable_by :title, :body
+    #   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.
+    module Searchable
+      extend ActiveSupport::Concern
+
+      LIKE_ESCAPE = "\\".freeze
+      LIKE_SPECIAL = /[\\%_]/
+
+      included do
+        class_attribute :searchable_fields, instance_accessor: false, default: []
+      end
+
+      class_methods do
+        def searchable_by(*fields)
+          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
+
+          self.searchable_fields = fields.map(&:to_sym)
+
+          scope :search, ->(query) { search_relation(query) }
+        end
+
+        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}%"
+
+          predicates = searchable_fields.map { |field| arel_table[field].matches(pattern, LIKE_ESCAPE) }
+          where(predicates.reduce { |memo, p| memo.or(p) })
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.6.0".freeze
+  VERSION = "1.7.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -15,12 +15,15 @@ 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"
 
 # 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"
 
 # 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.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -70,16 +70,19 @@ files:
 - CODE_OF_CONDUCT.md
 - README.md
 - 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/paginatable.rb
 - lib/concerns_on_rails/controllers/respondable.rb
 - lib/concerns_on_rails/controllers/sortable.rb
 - lib/concerns_on_rails/legacy_aliases.rb
+- lib/concerns_on_rails/models/activatable.rb
 - lib/concerns_on_rails/models/expirable.rb
 - lib/concerns_on_rails/models/hashable.rb
 - lib/concerns_on_rails/models/normalizable.rb
 - lib/concerns_on_rails/models/publishable.rb
 - lib/concerns_on_rails/models/schedulable.rb
+- lib/concerns_on_rails/models/searchable.rb
 - lib/concerns_on_rails/models/sluggable.rb
 - lib/concerns_on_rails/models/soft_deletable.rb
 - lib/concerns_on_rails/models/sortable.rb