concerns_on_rails 1.17.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5759f8cf9f86e11087369181f53f807875909047c17fe8abb19a5b6bafaae697
-  data.tar.gz: d6e34235431b2c54a36de7126b4829b9892b05f66f0fc6b476ff561731452100
+  metadata.gz: 30c62bfbc26afd05fe7ed2e991add6fa180f3e71316ec638a045932e89bf2ce1
+  data.tar.gz: af936258d441cf0206e120853f0a227967f663e577983628087defe2d60d7202
 SHA512:
-  metadata.gz: 2b101b659f6d47f0adcface39ef7069a978d8342e6499661d358af12037c12fb1b7d317cdd075ca9b5593989df2941e121ecf46e02d51c11e4f445cdf91801dd
-  data.tar.gz: 984342a4be9bae7692c880bb2436de85cd86a3a0e8cd4ba1c167168db297bf4a0ce42a3a7025de910b7e33495d67e8352667ea302b8d47e12c1824cd7bd4ae31
+  metadata.gz: 359c8240a7d15da31c2a3236a69cb75b1cce57dc5fb80869214c64c05b3b7051d2a17ee17e73d5e9aec3321a53ca8a5de7ada2e73fa80f1f4da50e41fbfc6398
+  data.tar.gz: 6b7388a71ceed19ee2517786f5bffdde6acb2e13506ce4ee00b983ff46293a9479aa91d01e2f6912e50a7eb1944f644534369215274fa2234fd889315e32e6f1

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 <!-- CHANGELOG.md -->
 
+## 1.18.0 (2026-06-12)
+
+Two new concerns, designed and hardened through adversarial design- and code-review rounds (a shared-reflection registration strategy that produced invalid SQL was caught and replaced before implementation; a time-serialization path that silently lost sub-second precision likewise; a NULL page-boundary value that would have silently dropped rows now raises; a post-review pass fixed `has_many :through` aliasing, which crashed at macro time under lazy class loading and re-derived its `source:` from the alias name at query time). A follow-up enhancement round added bidirectional cursors, allow-listed order presets, and row-value predicates to CursorPaginatable, and `only:`/`except:`/`deprecated:`/`alias_foreign_key:` to Aliasable. 793 examples, 0 failures.
+
+### Added
+- **Models::Aliasable**: full association aliasing — `alias_association :writer, :author` (argument order mirrors `alias_method new, old`) gives read, write/assign, `build_`/`create_`/`create_!`/`reload_`/`reset_`, the `_ids` pair, and the query side (`joins`/`includes`/`preload`/`eager_load`/`where`-hash/`reflect_on_association`). One loaded cache under two names (`record.association(:alias)` IS the source's proxy) and only the source macro installs callbacks, so `dependent:`, counter caches, autosave and validations run exactly once. The query side registers a *renamed reflection copy* (registering the same object emits mismatched JOIN/WHERE table names — invalid SQL), with `class_name`/`foreign_key`/`foreign_type` (direct associations) or `source:` (`has_many`/`has_one :through` — resolved exactly when the through class is already loaded, anchored to the source association's own name when it is not) pinned so nothing re-derives from the alias name; the `_reflections` key form (String on <= 7.x, Symbol on newer) is probed at runtime. Aliases are inherited; re-declaring one with the same source in a subclass after redefining that source refreshes the reflection (descendant caches cleared), while repointing an existing alias at a different source raises. Collision validation sweeps every generated method name against associations, methods, columns, and virtual attributes — skipped gracefully when no database is reachable at load time. Aliases of aliases collapse to the terminal source; `has_and_belongs_to_many` is rejected (use `has_many :through`); the `belongs_to` FK attribute is not aliased by default (`alias_foreign_key: true` aliases the `<alias>_id`/`<alias>_type` pair via `alias_attribute`, collision-checked). Options: `only:`/`except:` narrow the generated method map by group (`:reader`/`:writer`/`:build`/`:reload`/`:ids`; narrowing re-declares prune their stale delegators); `deprecated:` (true or a String hint) warns through the new `ConcernsOnRails.deprecator` on every delegator call — the gradual-rename story. Zero new runtime dependencies.
+- **Controllers::CursorPaginatable**: cursor/keyset pagination — the no-COUNT, concurrent-insert-stable complement to Paginatable. `cursor_paginate_by order: { created_at: :desc }, per_page: 25, max_per_page: 200` (+ per-call `order:`/`per_page:`); `cursor_paginated(scope)` returns the page (loaded Array, limit+1 has-more detection) and sets `X-Per-Page`, `X-Count` (this page — totals deliberately never computed), `X-Has-More`, `X-Next-Cursor`; `cursor_pagination_meta` memoizes for Respondable `meta:` composition. The primary key is always appended as a strict tiebreaker (duplicate values never skip/repeat rows; proven by a ties-walk spec) and the keyset WHERE is Arel OR-expansion, portable across adapters and mixed asc/desc. Cursors are opaque URL-safe Base64 tokens pinned to the table + column:direction list — malformed, tampered (non-scalar values, wrong arity), cross-model, or stale-config cursors raise `InvalidCursor`, auto-rescued to a 400 (`invalid_cursor`, `render_invalid_cursor` override point, delegates to Respondable) on any Rescuable controller. Boundary timestamps serialize at microsecond precision (`iso8601(6)`) and cast back through the model's attribute types so each adapter quotes natively. Ordering columns are chosen in code only, validated against the schema; `reorder` defeats `default_scope` ordering; composite/PK-less tables raise `ArgumentError`, as does a NULL ordering value on a page-boundary row (which would otherwise silently drop rows — SQL three-valued logic). Opt-in extras: `bidirectional: true` mints `X-Prev-Cursor`/`X-Has-Prev` (backward fetches walk the inverted ordering and flip back to canonical order; direction is pinned in the token, so prev tokens replayed at forward-only endpoints 400 and pre-bidirectional tokens stay valid forward cursors); `order_presets:`/`default_preset:`/`order_param:` give clients allow-listed named orderings (unknown names → 400 `invalid_order_preset`; switching presets mid-walk invalidates the cursor); `predicate: :auto` upgrades the keyset WHERE to a composite-index-friendly row-value tuple `(a, b, id) > (x, y, z)` on PostgreSQL/MySQL/SQLite under uniform directions, falling back to the portable OR-expansion (`:row` forces tuples and raises on mixed directions; `:or` forces the expansion). Zero new runtime dependencies (URL-safe Base64 via `pack("m0")`, as in WebhookVerifiable).
+
 ## 1.17.0 (2026-06-10)
 
 Two new concerns, hardened by two adversarial review rounds (in-memory state is restored when a raising lock/unlock hook rolls the write back, so retries can't silently no-op; a hook aborting via `ActiveRecord::Rollback` makes `lock_access!`/`unlock_access!` return false instead of a fake success; invalid-UTF-8 signature headers fail closed instead of raising). 679 examples, 0 failures.

data/README.md

@@ -45,8 +45,10 @@ Article.published.without_deleted.find("hello-world")
   - [Monetizable](#-monetizable) — integer-cents money columns (BigDecimal)
   - [Auditable](#-auditable) — single-column change history ("paper_trail-lite")
   - [Lockable](#-lockable) — failed-attempt tracking + account lockout
+  - [Aliasable](#-aliasable) — full read/write/query aliases for associations
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
+  - [CursorPaginatable](#-cursorpaginatable) — cursor (keyset) pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
   - [Sortable (controller)](#-sortable-controller) — URL-param ordering with allow-list
   - [Respondable](#-respondable) — standardized JSON envelopes
@@ -68,7 +70,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Twenty model concerns + thirteen controller concerns**, all production-ready
+- **Twenty-one model concerns + fourteen 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
@@ -1004,6 +1006,39 @@ User.locked / User.unlocked     # expiry-aware scopes
 
 ---
 
+## 🪞 Aliasable
+
+Alias an existing association under a second name with **full** semantics — read, write/assign, build/create, and the query side (`joins` / `includes` / `where`-hash) — not just a delegated reader. (`alias_attribute` covers columns only; Rails has no built-in association aliasing.)
+
+```ruby
+class Book < ApplicationRecord
+  include ConcernsOnRails::Aliasable
+
+  belongs_to :author
+  has_many :chapters
+
+  alias_association :writer,   :author      # alias_method order: new, old
+  alias_association :sections, :chapters
+end
+
+book.writer                   # same cached object as book.author
+book.writer = user            # assigns through the original association
+book.build_writer(...)        # build_ / create_ / create_! / reload_ (singular)
+book.sections << chapter      # the same CollectionProxy as book.chapters
+book.section_ids              # ids reader/writer (collection)
+Book.joins(:sections).where(sections: { title: "Intro" })
+```
+
+**Options**: `alias_association new_name, source_name` — repeatable; declare it **after** the source association; re-declaring an existing alias with the **same** source (e.g. in a subclass that redefined the source) is allowed and refreshes it, while repointing an alias at a *different* source raises. Keyword options: `only:`/`except:` narrow the generated methods by group (`:reader`, `:writer`, `:build`, `:reload`, `:ids`); `deprecated: true` (or a String hint) makes every delegator warn through `ConcernsOnRails.deprecator` — the gradual-rename story; `alias_foreign_key: true` (`belongs_to` only) also aliases `<alias>_id` (and `<alias>_type` when polymorphic) via `alias_attribute`.
+
+**Notes**
+- One loaded cache under two names: `record.association(:alias)` IS `record.association(:source)`, and only the source macro installs callbacks — `dependent:`, counter caches, autosave and validations run exactly once.
+- The where-hash key must match the name you joined under (stock-Rails rule): `joins(:sections).where(sections: {...})` works; `joins(:chapters).where(sections: {...})` does not.
+- The `belongs_to` foreign-key **attribute** is not aliased — pair with `alias_attribute :writer_id, :author_id` if you need it.
+- `has_and_belongs_to_many` cannot be aliased (use `has_many :through`). `has_many`/`has_one :through` **can** — the copy pins `source:` so it is not re-derived from the alias name; if your classes load lazily and the through model names the source differently (e.g. `belongs_to :author` behind `has_many :authors`), declare `source:` explicitly on the original association. Aliases are inherited by subclasses.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1035,6 +1070,41 @@ end
 
 ---
 
+## 🧭 CursorPaginatable
+
+Cursor (keyset) pagination — the constant-time complement to Paginatable: **no COUNT query**, stable under concurrent inserts, ideal for infinite scroll and sync feeds.
+
+```ruby
+class ArticlesController < ApplicationController
+  include ConcernsOnRails::Controllers::CursorPaginatable
+
+  cursor_paginate_by order: { created_at: :desc }, per_page: 25, max_per_page: 200
+
+  def index
+    render json: cursor_paginated(Article.all)   # bad cursors are rescued to a 400 automatically
+  end
+end
+```
+
+**URL params**
+
+| Param        | Default | Notes                                                    |
+|--------------|---------|----------------------------------------------------------|
+| `?cursor=`   | —       | The opaque token from `X-Next-Cursor` (omit for page 1)  |
+| `?per_page=` | `25`    | Capped at `max_per_page` (default 200; `0` disables the cap) |
+| `?order=`    | first preset | With `order_presets:` only — selects a named ordering from the allow-list (unknown names → 400 `invalid_order_preset`) |
+
+**Response headers**: `X-Per-Page`, `X-Count` (rows on **this** page — totals are deliberately not computed), `X-Has-More`, `X-Next-Cursor` (only while more pages exist). With `bidirectional: true`: also `X-Has-Prev`, `X-Prev-Cursor`.
+
+**Notes**
+- The primary key is always appended as a tiebreaker, so duplicate values never skip or repeat rows; ordering columns are chosen **in code** (never from params) and should be `NOT NULL` (a NULL boundary value raises rather than silently dropping rows).
+- Cursors are opaque, table/order-pinned tokens — a malformed, cross-endpoint, or stale-config cursor renders a 400 (`invalid_cursor`; override `render_invalid_cursor` to customize, delegates to Respondable's `render_error` when present). They are **not signed**: a client can mint different boundary values, but values are cast through the model's attribute types and bound by Arel (no injection) and the relation's own scoping still applies — treat a cursor as a page position, never an authorization boundary.
+- `cursor_paginated` uses `reorder` (replaces any `default_scope` ORDER BY) and returns a loaded Array. Don't wrap it with the controller Sortable's `sorted` — pass `order:` per call instead.
+- Forward-only by default — `bidirectional: true` (macro or per call) adds prev cursors and `X-Has-Prev`/`X-Prev-Cursor`; direction is pinned in the token, so prev tokens replayed on forward-only endpoints 400 and old direction-less tokens stay valid. `order_presets: { newest: {...}, top: {...} }` (+ `default_preset:`, `order_param:`) lets clients pick a **named** ordering from an allow-list. `predicate: :auto` upgrades the keyset WHERE to a row-value tuple `(a, b, id) > (x, y, z)` on PostgreSQL/MySQL/SQLite when directions are uniform — composite-index friendly — falling back to the portable OR-expansion (`:row`/`:or` force a strategy).
+- Use Paginatable when you need page numbers and totals.
+
+---
+
 ## 🔎 Filterable
 
 Declarative URL-param filtering with three modes per filter.

data/lib/concerns_on_rails/controllers/cursor_paginatable.rb

@@ -0,0 +1,501 @@
+require "active_support/concern"
+require "json"
+require "time" # Time#iso8601(fraction_digits) lives in the stdlib time library
+
+module ConcernsOnRails
+  module Controllers
+    # Cursor (keyset) pagination for API controllers — the constant-time
+    # complement to Paginatable's offset pagination. No COUNT query, stable
+    # under concurrent inserts, suitable for infinite scroll and sync feeds.
+    #
+    #   class ArticlesController < ApplicationController
+    #     include ConcernsOnRails::Controllers::CursorPaginatable
+    #     cursor_paginate_by order: { created_at: :desc }, per_page: 25, max_per_page: 200
+    #
+    #     def index
+    #       render json: cursor_paginated(Article.all)
+    #     end
+    #   end
+    #
+    # Reads params[:cursor] (the opaque token from X-Next-Cursor) and
+    # params[:per_page]. The primary key is always appended as a tiebreaker.
+    # Ordering columns are chosen in code (never from params), must live on the
+    # base model's table, be selected by the relation, and should be NOT NULL.
+    #
+    # Optional capabilities (all opt-in, defaults unchanged):
+    #   * bidirectional: true — mints X-Prev-Cursor / X-Has-Prev alongside the
+    #     next cursor, so clients can page back without keeping old tokens.
+    #   * order_presets: { newest: { created_at: :desc }, top: { score: :desc } }
+    #     — allow-listed, client-selectable named orderings (?order= picks a
+    #     preset NAME; columns stay code-chosen). Unknown names raise
+    #     InvalidOrderPreset (auto-rescued to a 400).
+    #   * predicate: :auto (default) — on adapters with row-value support
+    #     (PostgreSQL/MySQL/SQLite) and uniform directions, the keyset WHERE is
+    #     a tuple comparison `(a, b, id) > (x, y, z)` that walks a composite
+    #     index directly; everything else falls back to the OR-expansion.
+    #
+    # Malformed or mismatched cursors raise CursorPaginatable::InvalidCursor;
+    # on real controllers a rescue_from is registered automatically and renders
+    # a 400 (via Respondable's render_error when included). Override
+    # #render_invalid_cursor to customize the body. Cursors are opaque but NOT
+    # signed — boundary values are cast through the model's attribute types
+    # and bound by Arel (no injection) and the relation's scoping still
+    # applies, so treat a cursor as a page position, never an authorization
+    # boundary.
+    #
+    # Do not combine with Controllers::Sortable#sorted — cursor_paginated uses
+    # reorder, which replaces any prior ORDER BY (including Models::Sortable's
+    # default_scope). Pass `order:` per call instead.
+    module CursorPaginatable
+      extend ActiveSupport::Concern
+
+      DEFAULT_PER_PAGE = 25
+      DEFAULT_MAX_PER_PAGE = 200
+      VALID_DIRECTIONS = %i[asc desc].freeze
+      VALID_PREDICATES = %i[auto row or].freeze
+      CURSOR_DIRECTIONS = %w[next prev].freeze
+      # Adapters whose SQL supports row-value (tuple) comparison: (a, b) > (x, y).
+      ROW_PREDICATE_ADAPTERS = /postgres|mysql|trilogy|sqlite/i
+
+      # Raised when params[:cursor] is malformed, tampered with, or was minted
+      # under a different table/order configuration. Auto-rescued to a 400 when
+      # the including class supports rescue_from (real controllers do).
+      class InvalidCursor < StandardError; end
+
+      # Raised when params[?order=] (or the configured order_param) names no
+      # configured preset. Auto-rescued to a 400 like InvalidCursor.
+      class InvalidOrderPreset < StandardError; end
+
+      # Normalizes Symbol / Array-of-Symbols / Hash order declarations to
+      # [[column, direction], ...]. Raises ArgumentError on anything else.
+      def self.normalize_order!(order)
+        pairs =
+          case order
+          when Hash then order.map { |col, dir| [col.to_sym, dir.to_sym] }
+          when Array then order.map { |col| [normalize_order_column!(col), :asc] }
+          else [[normalize_order_column!(order), :asc]]
+          end
+        raise ArgumentError, "#{name}: at least one order column is required" if pairs.empty?
+
+        validate_order_directions!(pairs)
+        pairs
+      end
+
+      def self.validate_order_directions!(pairs)
+        pairs.each do |col, dir|
+          next if VALID_DIRECTIONS.include?(dir)
+
+          raise ArgumentError, "#{name}: direction for '#{col}' must be :asc or :desc"
+        end
+      end
+
+      def self.normalize_order_column!(col)
+        return col.to_sym if col.is_a?(Symbol) || col.is_a?(String)
+
+        raise ArgumentError, "#{name}: order entries must be column names (Symbol/String); " \
+                             "use a Hash like { column: :desc } to set directions"
+      end
+
+      # Macro-time validation/normalization for order_presets / default_preset
+      # / predicate (module functions so class_methods stays thin).
+      def self.normalize_presets!(presets)
+        raise ArgumentError, "#{name}: order_presets must be a non-empty Hash" unless presets.is_a?(Hash) && presets.any?
+
+        presets.to_h { |key, order| [key.to_sym, normalize_order!(order)] }
+      end
+
+      def self.resolve_default_preset!(presets, default_preset, order)
+        validate_order_sources!(presets, default_preset, order)
+        return nil unless presets
+
+        key = (default_preset || presets.keys.first).to_sym
+        raise ArgumentError, "#{name}: default_preset '#{key}' is not one of the order_presets" unless presets.key?(key)
+
+        key
+      end
+
+      def self.validate_order_sources!(presets, default_preset, order)
+        raise ArgumentError, "#{name}: pass order: or order_presets:, not both" if order && presets
+        raise ArgumentError, "#{name}: order: or order_presets: is required" if order.nil? && presets.nil?
+        raise ArgumentError, "#{name}: default_preset: requires order_presets:" if default_preset && presets.nil?
+      end
+
+      def self.validate_predicate!(predicate)
+        predicate = predicate.to_sym
+        return predicate if VALID_PREDICATES.include?(predicate)
+
+        raise ArgumentError, "#{name}: predicate: must be one of #{VALID_PREDICATES.join(', ')}"
+      end
+
+      included do
+        class_attribute :cursor_paginatable_order, default: nil
+        class_attribute :cursor_paginatable_order_presets, default: nil
+        class_attribute :cursor_paginatable_default_preset, default: nil
+        class_attribute :cursor_paginatable_order_param, default: :order
+        class_attribute :cursor_paginatable_per_page, default: DEFAULT_PER_PAGE
+        class_attribute :cursor_paginatable_max_per_page, default: DEFAULT_MAX_PER_PAGE
+        class_attribute :cursor_paginatable_bidirectional, default: false
+        class_attribute :cursor_paginatable_predicate, default: :auto
+
+        # Real controllers (anything with ActiveSupport::Rescuable) get the 400
+        # handlers automatically; bare objects let the errors propagate.
+        if respond_to?(:rescue_from)
+          rescue_from InvalidCursor, with: :render_invalid_cursor
+          rescue_from InvalidOrderPreset, with: :render_invalid_order_preset
+        end
+      end
+
+      class_methods do
+        # Configure the keyset ordering and page-size defaults. Exactly one of
+        # order: (a fixed ordering) or order_presets: (named orderings the
+        # client picks via ?<order_param>=) is required.
+        # Examples:
+        #   cursor_paginate_by order: { created_at: :desc }, per_page: 50, max_per_page: 500
+        #   cursor_paginate_by order_presets: { newest: { created_at: :desc }, top: { score: :desc } },
+        #                      default_preset: :newest, bidirectional: true
+        # max_per_page: 0 (or negative) disables the per_page cap.
+        def cursor_paginate_by(order: nil, order_presets: nil, default_preset: nil, order_param: :order,
+                               per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE,
+                               bidirectional: false, predicate: :auto)
+          self.cursor_paginatable_order = order && CursorPaginatable.normalize_order!(order)
+          self.cursor_paginatable_order_presets = order_presets && CursorPaginatable.normalize_presets!(order_presets)
+          self.cursor_paginatable_default_preset =
+            CursorPaginatable.resolve_default_preset!(cursor_paginatable_order_presets, default_preset, order)
+          self.cursor_paginatable_order_param = order_param.to_sym
+          self.cursor_paginatable_per_page = per_page.to_i
+          self.cursor_paginatable_max_per_page = max_per_page.to_i
+          self.cursor_paginatable_bidirectional = bidirectional ? true : false
+          self.cursor_paginatable_predicate = CursorPaginatable.validate_predicate!(predicate)
+        end
+      end
+
+      # Run the keyset query (limit + 1 to detect has_more), set the standard
+      # response headers, and return the page as a loaded Array (laziness is
+      # impossible here: has_more detection materializes limit + 1 rows).
+      # Raises InvalidCursor (rescued to a 400 on real controllers) on bad
+      # cursors.
+      def cursor_paginated(relation, order: nil, per_page: nil, bidirectional: nil)
+        @cursor_pagination_meta = nil # never expose a previous call's meta after a failure
+        result = cursor_paginate_result(relation, order: order, per_page: per_page, bidirectional: bidirectional)
+        @cursor_pagination_meta = result[:meta]
+        apply_cursor_pagination_headers(result[:meta])
+        result[:records]
+      end
+
+      # With no arguments: the meta Hash memoized by the last cursor_paginated
+      # call (no extra query; nil if that call failed or never ran). With a
+      # relation: runs the query and returns meta WITHOUT setting headers or
+      # touching the memo — for body-based pagination (Respondable's meta:).
+      def cursor_pagination_meta(relation = nil, order: nil, per_page: nil, bidirectional: nil)
+        return @cursor_pagination_meta if relation.nil?
+
+        cursor_paginate_result(relation, order: order, per_page: per_page, bidirectional: bidirectional)[:meta]
+      end
+
+      # Public override point (mirrors ErrorHandleable's public handlers):
+      # delegates to Respondable#render_error when available.
+      def render_invalid_cursor(error)
+        return render_error(message: error.message, status: :bad_request, code: "invalid_cursor") if respond_to?(:render_error)
+
+        render json: { success: false, error: { message: error.message, code: "invalid_cursor" } }, status: :bad_request
+      end
+
+      # Same override contract for unknown ?order= preset names.
+      def render_invalid_order_preset(error)
+        return render_error(message: error.message, status: :bad_request, code: "invalid_order_preset") if respond_to?(:render_error)
+
+        render json: { success: false, error: { message: error.message, code: "invalid_order_preset" } }, status: :bad_request
+      end
+
+      private
+
+      def cursor_paginate_result(relation, order:, per_page:, bidirectional: nil)
+        relation = relation.all if relation.is_a?(Class)
+        pairs = cursor_order_pairs(relation, order)
+        limit = cursor_per_page(per_page)
+        bidi = bidirectional.nil? ? self.class.cursor_paginatable_bidirectional : bidirectional
+        cursor = decode_cursor(params[:cursor], pairs, relation.model, bidirectional: bidi)
+        fetch = cursor_fetch_page(relation, pairs, limit, cursor)
+        { records: fetch[:page],
+          meta: cursor_build_meta(relation.model, pairs, limit, fetch, bidi) }
+      end
+
+      # A backward ("prev") cursor walks the INVERTED ordering so LIMIT grabs
+      # the rows nearest the boundary, then flips the page back to canonical
+      # order. reorder (not order) so the keyset columns REPLACE any prior
+      # ORDER BY — including a Models::Sortable default_scope order.
+      def cursor_fetch_page(relation, pairs, limit, cursor)
+        backward = cursor ? cursor[:backward] : false
+        effective = backward ? cursor_invert_pairs(pairs) : pairs
+        scoped = relation.reorder(effective.to_h)
+        scoped = scoped.where(cursor_predicate(relation.model, effective, cursor[:values])) if cursor
+        rows = scoped.limit(limit + 1).to_a
+
+        page = rows.first(limit)
+        page.reverse! if backward
+        { page: page, extra: rows.size > limit, backward: backward, arrived: !cursor.nil? }
+      end
+
+      def cursor_invert_pairs(pairs)
+        pairs.map { |col, dir| [col, dir == :asc ? :desc : :asc] }
+      end
+
+      # The limit+1 probe detects "more" in the direction of travel; the
+      # other side is implied by the cursor we arrived on. Cursors are only
+      # minted from a non-empty page — an over-walked empty page returns no
+      # cursors and both flags false (clients keep their previous tokens).
+      # prev_cursor/has_prev appear in the meta only in bidirectional mode,
+      # so the forward-only meta shape is unchanged.
+      def cursor_build_meta(model, pairs, limit, fetch, bidi)
+        page = fetch[:page]
+        has_next = page.any? && (fetch[:backward] || fetch[:extra])
+        meta = { per_page: limit, count: page.size, has_more: has_next,
+                 next_cursor: has_next ? encode_cursor(model, pairs, page.last, "next") : nil }
+        meta.merge!(cursor_prev_meta(model, pairs, fetch)) if bidi
+        meta
+      end
+
+      def cursor_prev_meta(model, pairs, fetch)
+        page = fetch[:page]
+        has_prev = page.any? && (fetch[:backward] ? fetch[:extra] : fetch[:arrived])
+        { has_prev: has_prev,
+          prev_cursor: has_prev ? encode_cursor(model, pairs, page.first, "prev") : nil }
+      end
+
+      # Resolved [[column, direction], ...] with the primary key appended as a
+      # tiebreaker (inheriting the last column's direction) when not declared.
+      def cursor_order_pairs(relation, override)
+        pairs = override ? CursorPaginatable.normalize_order!(override) : cursor_configured_pairs
+        pairs = (pairs || []).dup
+        pk = relation.model.primary_key
+        unless pk.is_a?(String) # Array under composite PKs, nil for PK-less tables
+          raise ArgumentError,
+                "#{CursorPaginatable.name}: #{relation.model.table_name} needs a single-column primary key"
+        end
+
+        pk = pk.to_sym
+        pairs << [pk, pairs.empty? ? :asc : pairs.last.last] unless pairs.any? { |col, _| col == pk }
+        validate_cursor_columns!(relation.model, pairs)
+        pairs
+      end
+
+      def validate_cursor_columns!(model, pairs)
+        pairs.map(&:first).each do |col|
+          next if model.column_names.include?(col.to_s)
+
+          raise ArgumentError,
+                "#{CursorPaginatable.name}: '#{col}' does not exist in the database (table: #{model.table_name})"
+        end
+      end
+
+      def cursor_configured_pairs
+        self.class.cursor_paginatable_order || cursor_preset_order_pairs
+      end
+
+      # Resolves params[<order_param>] against the allow-listed presets. The
+      # param only ever picks a preset NAME — columns stay code-chosen. An
+      # unknown name raises (→ 400) rather than silently falling back: a
+      # typo'd ?order= must not quietly reorder the walk. Switching presets
+      # mid-walk invalidates the cursor via the pinned column:direction list.
+      def cursor_preset_order_pairs
+        presets = self.class.cursor_paginatable_order_presets
+        return nil unless presets
+
+        raw = params[self.class.cursor_paginatable_order_param]
+        return presets[self.class.cursor_paginatable_default_preset] if raw.nil? || raw.to_s.strip.empty?
+
+        key = presets.keys.find { |k| k.to_s == raw.to_s }
+        return presets[key] if key
+
+        raise InvalidOrderPreset, "Unknown order preset '#{raw}'. Available: #{presets.keys.join(', ')}."
+      end
+
+      def cursor_per_page(override)
+        requested = (override || params[:per_page]).to_i
+        requested = self.class.cursor_paginatable_per_page if requested < 1
+        cap = self.class.cursor_paginatable_max_per_page
+        cap.positive? ? [requested, cap].min : requested
+      end
+
+      # ----- cursor encode/decode -----
+
+      # "o" always pins the CANONICAL column:direction list (scope checks
+      # compare against it regardless of travel direction); "d" carries the
+      # direction this cursor travels.
+      def encode_cursor(model, pairs, record, direction)
+        payload = {
+          "t" => model.table_name, # pin the table so cross-model replay is rejected
+          "o" => pairs.map { |col, dir| "#{col}:#{dir}" },
+          "d" => direction,
+          "v" => pairs.map { |col, _dir| serialize_cursor_value(cursor_boundary_value!(record, col)) }
+        }
+        cursor_base64_encode(JSON.generate(payload))
+      end
+
+      # A NULL boundary value would emit `col > NULL` — never TRUE in SQL
+      # three-valued logic — and silently drop rows from every later page.
+      # Fail loudly instead: this is a data/configuration problem.
+      def cursor_boundary_value!(record, col)
+        value = record.public_send(col)
+        return value unless value.nil?
+
+        raise ArgumentError,
+              "#{CursorPaginatable.name}: ordering column '#{col}' is NULL on the page-boundary row " \
+              "(id: #{record.id.inspect}) — cursor pagination needs non-NULL ordering values; " \
+              "use NOT NULL columns or COALESCE"
+      end
+
+      # Explicit is_a? checks (NOT acts_like?, which needs an un-required
+      # core_ext; NOT case/when, whose Module#=== misses TimeWithZone — its
+      # redefined #is_a? returns true for Time). iso8601(6) keeps microsecond
+      # precision so boundary equality survives the round trip.
+      def serialize_cursor_value(value)
+        return value.to_time.utc.iso8601(6) if value.is_a?(Time) || value.is_a?(DateTime)
+        return value.iso8601 if value.is_a?(Date)
+        return value.to_s if value.is_a?(BigDecimal)
+
+        value
+      end
+
+      # nil → no cursor param (first page). Otherwise {values:, backward:}:
+      # the boundary values cast back to native types via the model's
+      # attribute types, so Arel quotes them correctly per database adapter
+      # (SQLite stores datetimes with a space, not ISO "T" — raw string
+      # comparison would silently break).
+      def decode_cursor(raw, pairs, model, bidirectional:)
+        return nil if raw.nil? || raw.to_s.strip.empty?
+
+        payload = parse_cursor_payload(raw.to_s)
+        raise InvalidCursor, "Invalid pagination cursor." unless payload
+
+        verify_cursor_scope!(payload, pairs, model)
+        direction = cursor_direction!(payload, bidirectional)
+        values = payload["v"]
+        raise InvalidCursor, "Invalid pagination cursor." unless valid_cursor_values?(values, pairs.size)
+
+        { values: pairs.zip(values).map { |(col, _dir), value| model.type_for_attribute(col.to_s).cast(value) },
+          backward: direction == "prev" }
+      end
+
+      # Pre-bidirectional cursors carry no "d" — they are forward cursors and
+      # stay valid. "prev" requires bidirectional mode: a backward token
+      # replayed against a forward-only endpoint is a configuration mismatch,
+      # not a first page.
+      def cursor_direction!(payload, bidirectional)
+        direction = payload["d"] || "next"
+        raise InvalidCursor, "Invalid pagination cursor." unless CURSOR_DIRECTIONS.include?(direction)
+        raise InvalidCursor, "Cursor does not match the current pagination configuration." if direction == "prev" && !bidirectional
+
+        direction
+      end
+
+      def parse_cursor_payload(raw)
+        parsed = JSON.parse(cursor_base64_decode(raw))
+        parsed.is_a?(Hash) ? parsed : nil
+      # ArgumentError: unpack1("m0") on invalid Base64; JSON::ParserError:
+      # malformed JSON. Nothing else in the body raises either.
+      rescue ArgumentError, JSON::ParserError
+        nil
+      end
+
+      # Hand-rolled URL-safe Base64 (pack("m0") is strict RFC 4648, raising
+      # ArgumentError on garbage) — same trick as WebhookVerifiable, keeping
+      # the gem off the base64 gem, which left Ruby's default gems in 3.4.
+      def cursor_base64_encode(json)
+        [json].pack("m0").tr("+/", "-_").delete("=")
+      end
+
+      def cursor_base64_decode(raw)
+        standard = raw.tr("-_", "+/")
+        standard += "=" * ((4 - (standard.length % 4)) % 4)
+        standard.unpack1("m0")
+      end
+
+      # Exact match on table + column:direction list rejects cursors minted on
+      # another model, under another order config, or after a config change.
+      def verify_cursor_scope!(payload, pairs, model)
+        expected = pairs.map { |col, dir| "#{col}:#{dir}" }
+        return if payload["t"] == model.table_name && payload["o"] == expected
+
+        raise InvalidCursor, "Cursor does not match the current pagination configuration."
+      end
+
+      # Only non-null JSON scalars may be cast — a tampered Hash/Array value
+      # would cast to nil (silently empty page) or raise adapter-dependent
+      # errors, and we never mint null boundary values (see
+      # cursor_boundary_value!), so a null here is tampering too.
+      def valid_cursor_values?(values, expected_size)
+        values.is_a?(Array) && values.size == expected_size && values.all? { |v| cursor_scalar?(v) }
+      end
+
+      def cursor_scalar?(value)
+        value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
+      end
+
+      # ----- keyset WHERE -----
+      # Two strategies, same strict lexicographic semantics (the boundary row
+      # itself is excluded):
+      #   :or  — (c1 > v1) OR (c1 = v1 AND c2 > v2) OR ... with gt/lt per
+      #          column direction; portable, supports mixed asc/desc.
+      #   :row — (c1, c2, id) > (v1, v2, v3) tuple comparison; lets the
+      #          planner walk a composite index directly, but only expresses
+      #          uniform directions and needs adapter support.
+      def cursor_predicate(model, pairs, values)
+        if cursor_row_predicate?(model, pairs)
+          cursor_row_predicate(model, pairs, values)
+        else
+          cursor_or_predicate(model, pairs, values)
+        end
+      end
+
+      # :auto picks :row when it is expressible (>= 2 uniform-direction
+      # columns) and the adapter supports tuples, silently falling back
+      # otherwise; an explicit :row raises on mixed directions instead of
+      # silently changing strategy.
+      def cursor_row_predicate?(model, pairs)
+        mode = self.class.cursor_paginatable_predicate
+        return false if mode == :or || pairs.size < 2
+
+        uniform = pairs.map(&:last).uniq.size == 1
+        if mode == :row
+          raise ArgumentError, "#{CursorPaginatable.name}: predicate: :row requires uniform order directions" unless uniform
+
+          return true
+        end
+        uniform && model.connection.adapter_name.match?(ROW_PREDICATE_ADAPTERS)
+      end
+
+      def cursor_row_predicate(model, pairs, values)
+        table = model.arel_table
+        lhs = Arel::Nodes::Grouping.new(pairs.map { |col, _dir| table[col] })
+        rhs = Arel::Nodes::Grouping.new(
+          pairs.each_with_index.map { |(col, _dir), i| Arel::Nodes.build_quoted(values[i], table[col]) }
+        )
+        pairs.first.last == :asc ? Arel::Nodes::GreaterThan.new(lhs, rhs) : Arel::Nodes::LessThan.new(lhs, rhs)
+      end
+
+      def cursor_or_predicate(model, pairs, values)
+        table = model.arel_table
+        branches = pairs.each_index.map do |i|
+          eqs = (0...i).map { |j| table[pairs[j][0]].eq(values[j]) }
+          cmp = pairs[i][1] == :asc ? table[pairs[i][0]].gt(values[i]) : table[pairs[i][0]].lt(values[i])
+          (eqs + [cmp]).reduce(:and)
+        end
+        branches.reduce(:or)
+      end
+
+      def apply_cursor_pagination_headers(meta)
+        return unless respond_to?(:response) && response
+
+        response.set_header("X-Per-Page", meta[:per_page].to_s)
+        response.set_header("X-Count", meta[:count].to_s)
+        response.set_header("X-Has-More", meta[:has_more].to_s)
+        response.set_header("X-Next-Cursor", meta[:next_cursor]) if meta[:next_cursor]
+        return unless meta.key?(:has_prev)
+
+        response.set_header("X-Has-Prev", meta[:has_prev].to_s)
+        response.set_header("X-Prev-Cursor", meta[:prev_cursor]) if meta[:prev_cursor]
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -22,4 +22,5 @@ module ConcernsOnRails
   Monetizable   = Models::Monetizable
   Auditable     = Models::Auditable
   Lockable      = Models::Lockable
+  Aliasable     = Models::Aliasable
 end

data/lib/concerns_on_rails/models/aliasable.rb

@@ -0,0 +1,405 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Models
+    # Alias an existing ActiveRecord association under a second name with
+    # FULL support — read, write/assign, build/create, and the query side
+    # (joins / includes / preload / eager_load / where hash conditions) —
+    # not just a delegated reader. Rails' alias_attribute covers columns
+    # only; there is no built-in way to alias an association.
+    #
+    #   class Book < ApplicationRecord
+    #     include ConcernsOnRails::Aliasable
+    #
+    #     belongs_to :author
+    #     has_many :chapters
+    #
+    #     alias_association :writer,   :author     # alias_method order: new, old
+    #     alias_association :sections, :chapters
+    #
+    #     # Options:
+    #     alias_association :penman, :author, only: :reader            # no writer/build_/create_
+    #     alias_association :parts,  :chapters, except: :ids           # skip part_ids/part_ids=
+    #     alias_association :owner,  :author, deprecated: "use #author"  # warns on use
+    #     alias_association :maker,  :author, alias_foreign_key: true    # maker_id -> author_id
+    #   end
+    #
+    #   book.writer                  # same cached object as book.author
+    #   book.writer = user           # assigns through the original association
+    #   book.build_writer(...)       # build_/create_/create_!/reload_ (singular)
+    #   book.sections << chapter     # the same CollectionProxy as book.chapters
+    #   book.section_ids             # ids reader/writer (collection)
+    #   Book.joins(:writer)          # INNER JOIN "authors"
+    #   Book.joins(:sections).where(sections: { title: "Intro" })
+    #
+    # Notes:
+    #   * Declare alias_association AFTER the source association — it raises
+    #     "does not exist" when the source has not been defined yet.
+    #   * One loaded cache under two names: record.association(:alias) IS
+    #     record.association(:source), and only the source macro installs
+    #     callbacks — dependent:, counter_cache, autosave and validations
+    #     run exactly once.
+    #   * Query SQL: a bare joins(:sections) joins "chapters" directly; when
+    #     paired with where(sections: {...}) Rails aliases the join as
+    #     "sections" (INNER JOIN "chapters" "sections"). A where-hash key
+    #     must match the name you joined under (same rule as stock Rails):
+    #     joins(:sections).where(sections: {...}) works,
+    #     joins(:chapters).where(sections: {...}) does not.
+    #   * The belongs_to foreign-key attribute is NOT aliased — pair with
+    #     Rails' alias_attribute (e.g. :writer_id, :author_id) if needed.
+    #   * has_and_belongs_to_many cannot be aliased — use has_many :through.
+    #   * has_many/has_one :through CAN be aliased (the copy pins `source:`
+    #     so it is not re-derived from the alias name). One caveat: when the
+    #     alias is declared before the through model's class has loaded AND
+    #     the through model defines the source under a different name (e.g.
+    #     belongs_to :author behind has_many :authors), declare `source:`
+    #     explicitly on the original association.
+    #   * Subclasses inherit aliases. If a subclass redefines the source
+    #     association, re-declare the alias there (re-declaring with the SAME
+    #     source is allowed and idempotent) so the query side picks up the
+    #     new reflection. Repointing an existing alias at a DIFFERENT source
+    #     raises.
+    #   * only:/except: narrow the generated methods by group — :reader,
+    #     :writer, :build, :reload (singular), :ids (collection). Groups that
+    #     do not apply to the reflection type are ignored; the query side
+    #     (joins/includes/where-hash) is always registered.
+    #   * deprecated: true (or a String hint) makes every generated delegator
+    #     warn through ConcernsOnRails.deprecator before delegating — the
+    #     gradual-rename story: point the OLD name at the new association and
+    #     deprecate it. The query side and alias_foreign_key attribute
+    #     aliases do not warn.
+    #   * alias_foreign_key: true (belongs_to only) also aliases the FK
+    #     attribute via Rails' alias_attribute (<alias>_id, plus <alias>_type
+    #     when polymorphic).
+    module Aliasable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Models::Aliasable".freeze
+
+      # Method stems per reflection type, keyed by the only:/except: group
+      # names; %s is the association name. The reload_/reset_ stems vary
+      # across the supported Rails range and build_/create_ are skipped by
+      # Rails for polymorphic belongs_to, so each SOURCE method is
+      # existence-checked before its delegator is made. The :ids pair is
+      # handled separately (it singularizes the association name).
+      SINGULAR_STEM_GROUPS = {
+        reader: ["%s"].freeze,
+        writer: ["%s="].freeze,
+        build: ["build_%s", "create_%s", "create_%s!"].freeze,
+        reload: ["reload_%s", "reset_%s"].freeze
+      }.freeze
+      COLLECTION_STEM_GROUPS = {
+        reader: ["%s"].freeze,
+        writer: ["%s="].freeze
+      }.freeze
+      METHOD_GROUPS = %i[reader writer build reload ids].freeze
+
+      included do
+        # Guarded so re-including the concern (e.g. ApplicationRecord and a
+        # model both include it) cannot reset an inherited, populated hash —
+        # that would desync the #association override from the inherited
+        # delegators and split the loaded caches. aliasable_alias_methods
+        # records which delegators each alias defined, so a re-declare with
+        # narrower only:/except: prunes the ones no longer wanted.
+        unless respond_to?(:aliasable_aliases)
+          class_attribute :aliasable_aliases, instance_accessor: false, default: {}
+          class_attribute :aliasable_alias_methods, instance_accessor: false, default: {}
+        end
+      end
+
+      module ClassMethods
+        # Register `new_name` as a full alias of the existing association
+        # `source_name`. Argument order mirrors `alias_method new, old`.
+        # Callable many times; aliases of aliases collapse to the terminal
+        # source; re-declaring an existing alias WITH THE SAME SOURCE (the
+        # STI subclass path) refreshes its reflection in place instead of
+        # raising, while repointing it at a different source raises — that is
+        # almost always an accident, and the generated methods/reflection
+        # would silently change meaning.
+        # Options:
+        #   only:/except: — narrow the generated method map by group
+        #     (:reader, :writer, :build, :reload, :ids); inapplicable groups
+        #     are ignored, unknown ones raise.
+        #   deprecated: — true or a String hint; delegators warn through
+        #     ConcernsOnRails.deprecator before delegating.
+        #   alias_foreign_key: — belongs_to only; alias_attribute the FK
+        #     (<alias>_id, plus <alias>_type when polymorphic).
+        def alias_association(new_name, source_name, only: nil, except: nil, deprecated: nil, alias_foreign_key: false)
+          new_name = new_name.to_sym
+          source = aliasable_aliases[source_name.to_sym] || source_name.to_sym # collapse alias-of-alias
+          aliasable_guard_repoint!(new_name, source)
+          reflection = aliasable_validate!(new_name, source)
+          aliasable_validate_foreign_key!(new_name, reflection) if alias_foreign_key
+          aliasable_install(new_name, source, reflection,
+                            groups: aliasable_method_groups(only, except),
+                            deprecated: deprecated, alias_foreign_key: alias_foreign_key)
+          new_name
+        end
+
+        private
+
+        def aliasable_guard_repoint!(new_name, source)
+          existing = aliasable_aliases[new_name]
+          return unless existing && existing != source
+
+          raise ArgumentError,
+                "#{LABEL}: '#{new_name}' is already aliased to '#{existing}' (model: #{name}) — " \
+                "repointing an alias is not allowed; remove the original declaration first"
+        end
+
+        def aliasable_install(new_name, source, reflection, groups:, deprecated:, alias_foreign_key:)
+          method_map = aliasable_method_map(new_name, source, reflection, groups)
+          unless aliasable_aliases.key?(new_name)
+            sweep = method_map.keys
+            sweep += aliasable_foreign_key_names(new_name, reflection) if alias_foreign_key
+            aliasable_check_collisions!(new_name, sweep)
+          end
+
+          self.aliasable_aliases = aliasable_aliases.merge(new_name => source)
+          aliasable_register_reflection(new_name, source, reflection)
+          aliasable_define_methods(new_name, method_map, aliasable_deprecation_message(new_name, source, deprecated))
+          aliasable_define_foreign_key_aliases(new_name, reflection) if alias_foreign_key
+        end
+
+        def aliasable_validate!(new_name, source)
+          raise ArgumentError, "#{LABEL}: alias '#{new_name}' must differ from the source association" if new_name == source
+
+          reflection = reflect_on_association(source)
+          unless reflection
+            raise ArgumentError,
+                  "#{LABEL}: association '#{source}' does not exist (model: #{name}) — " \
+                  "declare alias_association after the association"
+          end
+          # HABTM: Reflection.create cannot build habtm copies and the public
+          # reflections rebuild drops parent_reflection children — reject.
+          if reflection.macro == :has_and_belongs_to_many ||
+             (reflection.respond_to?(:parent_reflection) && reflection.parent_reflection)
+            raise ArgumentError, "#{LABEL}: has_and_belongs_to_many associations cannot be aliased — use has_many :through"
+          end
+
+          reflection
+        end
+
+        # only:/except: narrow generation by named group. Unknown names
+        # raise; names that don't apply to the reflection type (e.g. :build
+        # on a collection) are ignored so one declaration can serve both
+        # shapes.
+        def aliasable_method_groups(only, except)
+          raise ArgumentError, "#{LABEL}: pass only: or except:, not both" if only && except
+
+          requested = (Array(only) + Array(except)).map(&:to_sym)
+          unknown = requested - METHOD_GROUPS
+          if unknown.any?
+            raise ArgumentError,
+                  "#{LABEL}: unknown method group(s): #{unknown.join(', ')} (valid: #{METHOD_GROUPS.join(', ')})"
+          end
+          return METHOD_GROUPS - requested if except
+
+          only ? requested : METHOD_GROUPS
+        end
+
+        def aliasable_validate_foreign_key!(new_name, reflection)
+          return if reflection.belongs_to?
+
+          raise ArgumentError,
+                "#{LABEL}: alias_foreign_key: is only supported for belongs_to associations " \
+                "('#{new_name}' aliases a #{reflection.macro})"
+        end
+
+        # Sweeps every name the declaration would generate (the configured
+        # method map plus the alias_foreign_key attribute pair) against
+        # existing associations, methods, columns, and declared attributes
+        # (virtual attributes).
+        def aliasable_check_collisions!(new_name, method_names)
+          raise ArgumentError, "#{LABEL}: '#{new_name}' is already an association on #{name}" if reflect_on_association(new_name)
+
+          schema = aliasable_schema_reachable?
+          method_names.each { |meth| aliasable_check_method_collision!(meth, schema) }
+        end
+
+        def aliasable_check_method_collision!(meth, schema)
+          attr_name = meth.to_s.delete_suffix("!").delete_suffix("=")
+          if schema && (column_names.include?(attr_name) || attribute_types.key?(attr_name))
+            raise ArgumentError, "#{LABEL}: '#{attr_name}' is already a column or attribute on #{name} (table: #{table_name})"
+          end
+          return unless method_defined?(meth) || private_method_defined?(meth)
+
+          raise ArgumentError, "#{LABEL}: '#{meth}' is already defined as a method on #{name}"
+        end
+
+        # Column collisions can only be checked against a live schema. Class
+        # loading without a database (rake db:create, assets:precompile) must
+        # not crash, so the column/attribute sweep is best-effort. The rescue
+        # is scoped to AR's own error hierarchy (no connection, no database,
+        # statement errors) — a NameError/NoMethodError from a real bug must
+        # still surface.
+        def aliasable_schema_reachable?
+          table_exists?
+        rescue ActiveRecord::ActiveRecordError
+          false
+        end
+
+        # Register a RENAMED COPY of the source reflection under the alias.
+        # Registering the same object does NOT work: PredicateBuilder aliases
+        # the arel table to the where-hash key while JoinDependency names the
+        # JOIN after reflection.name, so a shared object yields `JOIN "books"`
+        # + `WHERE "works"...` — invalid SQL. With the renamed copy the two
+        # agree (`INNER JOIN "books" "works"` when the where-hash references
+        # the alias), and the #association override below keeps the copy on
+        # the source's loaded cache. Reflection.create builds metadata only —
+        # it installs no callbacks, autosave, or validations, so side effects
+        # never run twice.
+        def aliasable_register_reflection(new_name, source, src)
+          renamed = ActiveRecord::Reflection.create(src.macro, new_name, src.scope, aliasable_copy_options(src), self)
+          # _reflections is String-keyed on Rails <= 7.x and Symbol-keyed on
+          # newer releases — probe the source's own entry, never hardcode.
+          key = _reflections.key?(source.to_s) ? new_name.to_s : new_name
+          # class_attribute writer: a subclass call never mutates the parent.
+          self._reflections = _reflections.merge(key => renamed)
+          aliasable_clear_reflection_caches
+        end
+
+        # Every option a reflection copy would re-derive from the ALIAS name
+        # must be pinned to what the source derived.
+        #   * through: pin :source (Rails derives it from the association
+        #     name — the copy would look for the alias on the through model).
+        #     class_name is NOT touched: ThroughReflection#class_name resolves
+        #     the source-reflection chain eagerly, raising NameError at macro
+        #     time while the through/target classes are still unloaded, and
+        #     with :source pinned the copy derives its klass correctly anyway.
+        #   * direct: pin class_name via the lazy string (NOT src.klass.name —
+        #     calling klass at macro time raises NameError while the target
+        #     class is unloaded). belongs_to also derives its FK from the
+        #     association name, so pin foreign_key (and foreign_type when
+        #     polymorphic).
+        def aliasable_copy_options(src)
+          opts = src.options.dup
+          if opts[:through]
+            opts[:source] ||= aliasable_through_source_name(src)
+          else
+            aliasable_pin_direct_options!(opts, src)
+          end
+          opts
+        end
+
+        def aliasable_pin_direct_options!(opts, src)
+          opts[:class_name] ||= src.class_name.to_s unless src.polymorphic?
+          return unless src.belongs_to?
+
+          opts[:foreign_key] ||= src.foreign_key
+          opts[:foreign_type] ||= src.foreign_type if src.polymorphic?
+        end
+
+        # Exact resolution (src.source_reflection.name) handles sources the
+        # through model defines under a different form (e.g. belongs_to
+        # :author behind has_many :authors), but it loads the through class —
+        # impossible while classes are still loading. Fall back to the source
+        # association's own name, Rails' derivation anchor; a lazily-loading
+        # app whose source lives under a different name must declare `source:`
+        # on the original association (standard Rails practice).
+        def aliasable_through_source_name(src)
+          src.source_reflection&.name || src.name
+        rescue NameError, ActiveRecord::ActiveRecordError
+          src.name
+        end
+
+        # The memoized reflections cache is per-class; descendants that have
+        # already memoized would otherwise stay stale (this matters on the
+        # re-declare-in-a-subclass path). respond_to? guard: private method,
+        # presence varies across the supported range.
+        def aliasable_clear_reflection_caches
+          ([self] + descendants).each do |klass|
+            klass.send(:clear_reflections_cache) if klass.respond_to?(:clear_reflections_cache, true)
+          end
+        end
+
+        def aliasable_method_map(new_name, source, reflection, groups)
+          stem_groups = reflection.collection? ? COLLECTION_STEM_GROUPS : SINGULAR_STEM_GROUPS
+          map = {}
+          stem_groups.each do |group, stems|
+            next unless groups.include?(group)
+
+            stems.each { |stem| map[format(stem, new_name)] = format(stem, source) }
+          end
+          aliasable_add_ids_pair(map, new_name, source) if reflection.collection? && groups.include?(:ids)
+          map
+        end
+
+        def aliasable_add_ids_pair(map, new_name, source)
+          alias_ids = "#{new_name.to_s.singularize}_ids"
+          source_ids = "#{source.to_s.singularize}_ids"
+          map[alias_ids] = source_ids
+          map["#{alias_ids}="] = "#{source_ids}="
+        end
+
+        # Defines the configured delegators and prunes ones a previous,
+        # broader declaration of this alias created (a re-declare narrowing
+        # only:/except: must not leave stale methods behind). Only methods
+        # this class's OWN generated_association_methods defined are pruned —
+        # a parent's declaration is never touched from a subclass.
+        def aliasable_define_methods(new_name, method_map, deprecation)
+          aliasable_prune_stale_delegators(new_name, method_map)
+          defined = method_map.filter_map do |alias_method_name, source_method_name|
+            next unless method_defined?(source_method_name)
+
+            aliasable_delegate(alias_method_name, source_method_name, deprecation)
+            alias_method_name
+          end
+          self.aliasable_alias_methods = aliasable_alias_methods.merge(new_name => defined)
+        end
+
+        def aliasable_prune_stale_delegators(new_name, method_map)
+          stale = (aliasable_alias_methods[new_name] || []) - method_map.keys
+          mod = generated_association_methods
+          stale.each { |meth| mod.send(:remove_method, meth) if mod.method_defined?(meth, false) }
+        end
+
+        # Delegators (not alias_method) so the alias honors model overrides
+        # of the source method, finds sources declared on a superclass, and
+        # tracks later redefinitions. They live in
+        # generated_association_methods — the same module Rails puts its own
+        # association methods in — so a model can override an alias and call
+        # super. A deprecated alias warns once per call, BEFORE delegating,
+        # so the warning fires even when the source raises.
+        def aliasable_delegate(alias_method_name, source_method_name, deprecation)
+          generated_association_methods.define_method(alias_method_name) do |*args, **kwargs, &block|
+            ConcernsOnRails.deprecator.warn(deprecation) if deprecation
+            __send__(source_method_name, *args, **kwargs, &block)
+          end
+        end
+
+        # Computed once at macro time; true gives the generic message and a
+        # String is appended as the migration hint. Query-side use and the
+        # alias_foreign_key attribute aliases do not warn — only delegators.
+        def aliasable_deprecation_message(new_name, source, deprecated)
+          return nil if deprecated.nil? || deprecated == false
+
+          base = "#{name}##{new_name} is a deprecated alias of ##{source}"
+          deprecated.is_a?(String) ? "#{base} — #{deprecated}" : base
+        end
+
+        def aliasable_foreign_key_names(new_name, reflection)
+          names = ["#{new_name}_id", "#{new_name}_id="]
+          names.push("#{new_name}_type", "#{new_name}_type=") if reflection.polymorphic?
+          names
+        end
+
+        # alias_attribute, not delegators: the FK is a real column, and Rails
+        # resolves attribute aliases in attribute APIs and where-hashes.
+        def aliasable_define_foreign_key_aliases(new_name, reflection)
+          alias_attribute :"#{new_name}_id", reflection.foreign_key.to_sym
+          alias_attribute :"#{new_name}_type", reflection.foreign_type.to_sym if reflection.polymorphic?
+        end
+      end
+
+      # Route the alias to the source association proxy so
+      # record.association(:alias) IS record.association(:source) — one
+      # loaded cache. Load-bearing for the preloader, which assigns loaded
+      # records via record.association(reflection.name) using the alias's
+      # renamed reflection.
+      def association(name)
+        super(self.class.aliasable_aliases[name.to_sym] || name)
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.17.0".freeze
+  VERSION = "1.18.0".freeze
 end

data/lib/concerns_on_rails.rb

@@ -1,10 +1,22 @@
 require "active_support/concern"
+require "active_support/deprecation"
 require "concerns_on_rails/version"
 
 module ConcernsOnRails
   module Models; end
   module Controllers; end
   module Support; end
+
+  # Gem-wide deprecator backing `alias_association ..., deprecated:` (and any
+  # future deprecation surface). A dedicated instance — not the global
+  # ActiveSupport::Deprecation singleton, whose direct use is itself
+  # deprecated on Rails 7.1+. Default behavior prints to $stderr; Rails apps
+  # can re-route it (e.g. `config.active_support.deprecation` style):
+  #
+  #   ConcernsOnRails.deprecator.behavior = :log
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("2.0", "concerns_on_rails")
+  end
 end
 
 # Shared internal helpers (must load before the concerns that use them)
@@ -37,6 +49,7 @@ 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"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"
@@ -52,6 +65,7 @@ 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"
 
 # 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.17.0
+  version: 1.18.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -71,6 +71,7 @@ files:
 - README.md
 - lib/concerns_on_rails.rb
 - lib/concerns_on_rails/controllers/authorizable.rb
+- lib/concerns_on_rails/controllers/cursor_paginatable.rb
 - lib/concerns_on_rails/controllers/error_handleable.rb
 - lib/concerns_on_rails/controllers/filterable.rb
 - lib/concerns_on_rails/controllers/idempotentable.rb
@@ -86,6 +87,7 @@ files:
 - lib/concerns_on_rails/legacy_aliases.rb
 - lib/concerns_on_rails/models/activatable.rb
 - lib/concerns_on_rails/models/addressable.rb
+- lib/concerns_on_rails/models/aliasable.rb
 - lib/concerns_on_rails/models/auditable.rb
 - lib/concerns_on_rails/models/expirable.rb
 - lib/concerns_on_rails/models/hashable.rb