concerns_on_rails 1.27.0 → 1.28.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b06bf25720ff6c5c3a243efdb7b0d575351d50b8a9f33ae4778c1354816075bb
-  data.tar.gz: 01dc0ff521bee7b5c74c9f30ddee414932441d2ceff84a15af1d9ae8e6d30ccc
+  metadata.gz: 00337457f7ea35fd2e02bb74bcb4031208109536946b448706104a9e031bd9ea
+  data.tar.gz: 3bfc8749303d212e51d98d8dd7fa4323888e3d984444c768695d5c290df311a3
 SHA512:
-  metadata.gz: 37a533852c90cc1876519bd8b52fd07f165bfcfb02efca47bd1ed9d3ff86de94457755d57f9b986d244674a29992cead1b43698de7e3480e92276a0b9c9f1eda
-  data.tar.gz: 3651f6a175bf1a1e203bbe8353a9fc8b7a2c6457dd19f73e89e31fa108a8e238f36a7004aeffface605800b2838f6bb935694ef823a65dc0be943763bfd31293
+  metadata.gz: 50ea50c59f6b15978fe3f1cc86f03266998249bd4b17dc84b36ff6a717e9a57d0efba37f2e5648c58009761aeb2198f14368b2c20715c0bc40c246c1e7b5ee25
+  data.tar.gz: f6b8c7784e26ac3f5c8f14217e07cbe6d846ecab216fad6c61fb192bf06a18aa4484d80efb32fd82d625c683d917d9fb8c9b88724adcf2a11878fb0ea6a1f7e9

data/CHANGELOG.md

@@ -1,5 +1,98 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.1 (2026-09-07)
+
+One additive Paginatable option (#89): `pagination_meta` can now publish the
+page window a pagination bar needs — first, last and N pages either side of the
+current page — instead of leaving every client to compute it from
+`total_pages`. Opt-in, controller-only, no extra query, and existing responses
+are byte-for-byte unchanged. 1314 examples, 0 failures.
+
+### Added
+- **Controllers::Paginatable**: `paginate_by window: 3` adds a `pages:` key to
+  `pagination_meta` — the first page, the last page, and N pages either side of
+  the current one, with the Symbol `:gap` standing in for each run left out
+  (`[1, :gap, 44, 45, 46, 47, 48, 49, 50, :gap, 100]`) — enough to render a
+  `1 … 44 45 46 [47] 48 49 50 … 100` bar straight from the meta Hash. Opt-in:
+  without `window:` the key is absent entirely (not `nil`), so no existing
+  meta Hash or serialized body changes shape, and `meta.key?(:pages)` is a
+  clean probe. The window is arithmetic over the `total` already counted, so it
+  costs no extra query on either the memoized `paginated` path or the fresh
+  `pagination_meta` one. A jump of exactly two pages is filled with the page it
+  would have hidden (`1 2 3`, never the wider `1 … 3`), and a `?page=` past the
+  last page windows around the last page as `rel="prev"` already does.
+  `window:` is validated at declaration — a non-negative Integer, or
+  `nil`/`false` to disable; `0` yields first, current and last only. Headers
+  and `Link` rels are unchanged: `pages:` is body-only by design. (#89)
+
+### Internal
+- `set_pagination_headers` no longer splats the memoized meta Hash, which
+  raised `unknown keyword: :pages` once that Hash could carry the window; the
+  four header values are passed explicitly.
+- README's advertised example counts were stale (1,160 and 1,303) and now read
+  1,314.
+
+## 1.28.0 (2026-09-06)
+
+Pagination is the theme: the four-PR Paginatable stack (#40, #45, #62, #83)
+from the September enhancement loop. Paginatable now paginates in-memory
+collections, both paginators emit RFC 8288 `Link` headers, results that were
+already paginated upstream can pass `total:`, and the page / per-page parameter
+names (including JSON:API's `page[number]` / `page[size]`) are configurable.
+Controller-only: no new columns, migrations or runtime dependencies. 1303
+examples, 0 failures.
+
+### Added
+- **Controllers::Paginatable**: `paginated` / `pagination_meta` accept in-memory
+  collections — an `Array`, `Set`, `Range` or any other non-Hash `Enumerable` —
+  not only ActiveRecord relations. The collection is materialized once, the
+  total is its size and the current page comes back as an `Array` with the same
+  `X-Total-Count` / `X-Page` / `X-Per-Page` / `X-Total-Pages` headers and
+  memoized meta. Relations still paginate in SQL. A `Hash`, `nil` or a
+  non-collection raises `ArgumentError` naming the class received. (#40)
+- **Controllers::Paginatable / CursorPaginatable**: RFC 8288 `Link` response
+  header — `first`/`prev`/`next`/`last` page URLs for Paginatable, `next`
+  (+ `prev` in bidirectional mode, `first` once a cursor is in play) for
+  CursorPaginatable — rebuilt from the current request with every other query
+  param preserved and appended to any existing `Link` header. Opt out with
+  `link_header: false` on either macro. Backed by the new shared
+  `Support::LinkHeader`. (#45)
+- **Controllers::Paginatable**: `paginated(collection, total:)` /
+  `pagination_meta(total:)` for collections that are already one page — an
+  external API's or search service's page N plus its total: nothing is sliced
+  or counted, and `total` drives the `X-*` headers and the `Link` header.
+  `total:` must be a non-negative Integer. (#62)
+- **Controllers::Paginatable**: `paginate_by page_param:` / `per_page_param:`
+  (a top-level name or a nested path such as `%i[page number]`) and
+  `style: :jsonapi` (`?page[number]=&page[size]=`); explicit `*_param:` options
+  win over the style, anything else raises at declaration. Readers dig the path
+  through `ScalarParam`, so a scalar where a Hash is expected falls back to the
+  default instead of raising. The `Link` header URLs are rebuilt under the
+  configured names (nested paths Rack-encoded, sibling keys preserved). (#83)
+
+### Notes
+The `Link` header is **on by default**, so every non-empty paginated response
+grows by one header. Its URLs are built from `request.base_url` + `request.path`,
+i.e. whatever host Rails sees — behind a proxy configure `trusted_proxies` /
+forwarded headers, or pass `link_header: false`. The `X-*` headers are
+unchanged either way, and the existing `?page=&per_page=` behaviour is
+byte-for-byte the same when no `page_param:` / `per_page_param:` / `style:` is
+given.
+
+### Internal
+- New `Support::LinkHeader` (autoloaded): `available?(controller)` — a request
+  exposing `base_url` / `path` / `query_parameters` (the dependency-free
+  `FakeController` has none, so emission is silently skipped); `url_for(request,
+  drop:, **overrides)` — Rack nested-query encoding, nested params survive, Hash
+  override values deep-stringified, `nil` / `drop:` removes a key;
+  `append(response, rels)` — never clobbers an existing `Link`.
+- `Paginatable.paginate_by` moved into `module ClassMethods` alongside its new
+  private helpers (RuboCop scope rule; the Stateable precedent).
+- Development dependencies: simplecov `~> 1.1`, sqlite3 `~> 2.9.6`, rubocop
+  `~> 1.89`; GitHub Actions `checkout` v7, `configure-pages` v6, `deploy-pages`
+  v5, `upload-pages-artifact` v5. The lockfile now resolves `permittable` 0.2.0
+  (the `~> 0.1` runtime pin is unchanged).
+
 ## 1.27.0 (2026-08-29)
 
 Scope-name collisions finally have an escape hatch on the eight concerns whose

data/README.md

@@ -148,7 +148,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early — with a ready-to-paste `rails generate migration` hint when it doesn't
 - **Composable** — concerns are independent; mix and match per model
-- **Tested like an app, not a snippet** — **1,160 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,314 RSpec examples** run against a real database on every CI build
 - **Documented twice** — everything in this README also lives as a per-concern page on the [docs site](https://vsn2015.github.io/concerns_on_rails), searchable and deep-linkable
 
 ---
@@ -158,7 +158,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.26"
+gem "concerns_on_rails", "~> 1.28"
 ```
 
 Or pull the latest from GitHub:
@@ -1455,6 +1455,30 @@ class ArticlesController < ApplicationController
 end
 ```
 
+**Arrays and other Enumerables work too.** Results that never touched the database — an
+external API response, a loaded association, a hand-built list of Structs — get the same
+slicing, headers and `pagination_meta`. Relations still paginate in SQL (`LIMIT`/`OFFSET`);
+an in-memory collection is sliced in Ruby and comes back as an `Array`:
+
+```ruby
+def search
+  render json: paginated(ExternalCatalog.search(params[:q]))   # Array in, current page out
+end
+```
+
+Anything answering `limit`/`offset` is treated as a relation; any other non-`Hash` `Enumerable`
+(`Array`, `Set`, `Range`, `Enumerator` — consumed once) is materialized and sliced. A `Hash`,
+`nil` or a non-collection raises `ArgumentError` (call `.to_a` to paginate a Hash's pairs).
+
+**Already paginated upstream?** When an external API or search service hands you page N and the
+total it counted, pass `total:` — nothing is sliced, limited or counted; the collection comes back
+as-is and `total` drives `X-Total-Count`, `X-Total-Pages` and the `Link` header:
+
+```ruby
+result = Catalog.search(params[:q], page: params[:page], per_page: params[:per_page])
+render_success(data: paginated(result.hits, total: result.total_hits), meta: pagination_meta)
+```
+
 **URL params**
 
 | Param        | Default | Notes                              |
@@ -1462,7 +1486,54 @@ end
 | `?page=`     | `1`     | Page numbers below 1 are clamped to 1 |
 | `?per_page=` | `25`    | Capped at `max_per_page` (default 200) |
 
-**Response headers**: `X-Total-Count`, `X-Page`, `X-Per-Page`, `X-Total-Pages`.
+Rename them, or speak JSON:API — the `Link` header URLs follow whatever you pick:
+
+```ruby
+paginate_by page_param: :p, per_page_param: :limit                 # ?p=2&limit=10
+paginate_by style: :jsonapi                                        # ?page[number]=2&page[size]=10
+paginate_by page_param: %i[paging page], per_page_param: %i[paging per]   # any nested path
+```
+
+**Page window for a pagination bar**
+
+`window:` adds a `pages:` key to `pagination_meta` — the first page, the last page, and N pages
+either side of the current one, with `:gap` standing in for the runs left out. It is opt-in:
+without `window:` the key is absent entirely. No extra query either way — it is arithmetic over
+the total already counted.
+
+```ruby
+paginate_by per_page: 10, window: 3
+
+pagination_meta
+# => { total: 1000, page: 47, per_page: 10, total_pages: 100,
+#      pages: [1, :gap, 44, 45, 46, 47, 48, 49, 50, :gap, 100] }
+```
+
+Render it straight into a `1 … 44 45 46 [47] 48 49 50 … 100` bar:
+
+```erb
+<% pagination_meta[:pages].each do |page| %>
+  <%= page == :gap ? "…" : link_to(page, url_for(page: page)) %>
+<% end %>
+```
+
+| Situation | `pages:` |
+|-----------|----------|
+| `?page=47` of 100 | `[1, :gap, 44, 45, 46, 47, 48, 49, 50, :gap, 100]` |
+| `?page=2` of 100 | `[1, 2, 3, 4, 5, :gap, 100]` — no leading gap once the window reaches page 1 |
+| `?page=6` of 100 | `[1, 2, 3, 4, 5, 6, 7, 8, 9, :gap, 100]` — a one-page gap is filled, never `1 … 3` |
+| 5 pages total | `[1, 2, 3, 4, 5]` — the window spans everything |
+| empty collection | key absent |
+| `window: 0` | `[1, :gap, 47, :gap, 100]` — first, current and last only |
+
+`?page=` past the last page windows around the last page (as `rel="prev"` already does), and
+`window:` must be a non-negative Integer or `nil`/`false` — validated at declaration.
+
+**Response headers**: `X-Total-Count`, `X-Page`, `X-Per-Page`, `X-Total-Pages`, and an RFC 8288 `Link`
+header with `first` / `prev` / `next` / `last` URLs rebuilt from the current request (other query params
+preserved; `prev`/`next` only when such a page exists; nothing for an empty collection) — the GitHub
+convention, so clients follow links instead of computing page numbers. Appended to any `Link` header
+already set (Deprecatable, CDN hints). `paginate_by link_header: false` turns it off.
 
 ---
 
@@ -1490,7 +1561,7 @@ end
 | `?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`.
+**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`. Plus an RFC 8288 `Link` header: `rel="next"` carries the next-cursor URL, `rel="prev"` the prev-cursor URL (bidirectional), `rel="first"` the current URL with the cursor dropped (once a cursor is in play); `per_page` and the order preset are preserved. `cursor_paginate_by link_header: false` turns it off.
 
 **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).
@@ -2086,9 +2157,9 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 
 ```sh
 bundle install                                  # install dev dependencies
-bundle exec rspec                               # run the test suite (1,245 examples)
+bundle exec rspec                               # run the test suite (1,314 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.27.0.gem      # install locally
+gem install ./concerns_on_rails-1.28.1.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000

data/lib/concerns_on_rails/controllers/cursor_paginatable.rb

@@ -2,6 +2,7 @@ require "active_support/concern"
 require "concerns_on_rails/support/error_envelope"
 require "concerns_on_rails/support/scalar_param"
 require "json"
+require "concerns_on_rails/support/link_header"
 require "time" # Time#iso8601(fraction_digits) lives in the stdlib time library
 
 module ConcernsOnRails
@@ -141,6 +142,7 @@ module ConcernsOnRails
         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
+        class_attribute :cursor_paginatable_link_header, default: true
 
         # Real controllers (anything with ActiveSupport::Rescuable) get the 400
         # handlers automatically; bare objects let the errors propagate.
@@ -161,7 +163,7 @@ module ConcernsOnRails
         # 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)
+                               bidirectional: false, predicate: :auto, link_header: true)
           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 =
@@ -171,6 +173,7 @@ module ConcernsOnRails
           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)
+          self.cursor_paginatable_link_header = link_header ? true : false
         end
       end
 
@@ -506,11 +509,31 @@ module ConcernsOnRails
         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]
+        apply_cursor_pagination_links(meta)
         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
+
+      # RFC 8288 Link: rel="next" carries the X-Next-Cursor token, rel="prev"
+      # the X-Prev-Cursor one (bidirectional mode), rel="first" is the current
+      # URL with the cursor dropped — emitted once a cursor is in play. Other
+      # query params (per_page, the order preset) are preserved. Skipped when
+      # disabled or without a real request.
+      def apply_cursor_pagination_links(meta)
+        return unless self.class.cursor_paginatable_link_header
+        return unless ConcernsOnRails::Support::LinkHeader.available?(self)
+
+        cursor_url = ->(token) { ConcernsOnRails::Support::LinkHeader.url_for(request, cursor: token) }
+        raw_cursor = params[:cursor]
+        ConcernsOnRails::Support::LinkHeader.append(
+          response,
+          first: ConcernsOnRails::Support::ScalarParam.scalar?(raw_cursor) && !raw_cursor.to_s.empty? ? cursor_url.call(nil) : nil,
+          prev: meta[:prev_cursor] && cursor_url.call(meta[:prev_cursor]),
+          next: meta[:next_cursor] && cursor_url.call(meta[:next_cursor])
+        )
+      end
     end
   end
 end

data/lib/concerns_on_rails/controllers/paginatable.rb

@@ -1,5 +1,6 @@
 require "active_support/concern"
 require "concerns_on_rails/support/scalar_param"
+require "concerns_on_rails/support/link_header"
 
 module ConcernsOnRails
   module Controllers
@@ -14,95 +15,266 @@ module ConcernsOnRails
     #       render json: paginated(Article.all)
     #     end
     #   end
+    #
+    # `paginated` also takes an in-memory collection — an Array, Set, Range or
+    # any other non-Hash Enumerable — so results assembled outside the
+    # database (an external API, a loaded association, a hand-built list of
+    # Structs) get the same slicing, headers and `pagination_meta`:
+    #
+    #   def search
+    #     render json: paginated(ExternalCatalog.search(params[:q]))
+    #   end
+    #
+    # Every paginated response also carries an RFC 8288 `Link` header with
+    # first/prev/next/last URLs rebuilt from the current request (other query
+    # params preserved) — the GitHub convention, so clients can follow links
+    # instead of computing page numbers. `paginate_by link_header: false` turns
+    # it off.
     module Paginatable
       extend ActiveSupport::Concern
 
+      LABEL = "ConcernsOnRails::Controllers::Paginatable".freeze
       DEFAULT_PER_PAGE = 25
       DEFAULT_MAX_PER_PAGE = 200
 
       included do
         class_attribute :paginatable_per_page, default: DEFAULT_PER_PAGE
         class_attribute :paginatable_max_per_page, default: DEFAULT_MAX_PER_PAGE
+        class_attribute :paginatable_link_header, default: true
+        # Half-width of the page window in `pagination_meta[:pages]`; nil = no
+        # window, and no `pages:` key at all.
+        class_attribute :paginatable_window, default: nil
+        # Where page / per_page are read from — a path of param names (`["page"]`,
+        # or `["page", "number"]` for JSON:API's page[number]).
+        class_attribute :paginatable_page_param, default: %w[page].freeze
+        class_attribute :paginatable_per_page_param, default: %w[per_page].freeze
       end
 
-      class_methods do
-        # Configure the default page size and the hard cap on per_page.
+      # A real module (not `class_methods do`) so the macro and its private
+      # helpers share one `private` without tripping RuboCop's scope analysis.
+      module ClassMethods
+        # Configure the default page size, the hard cap on per_page, and whether
+        # the RFC 8288 Link header is emitted.
         # Example:
-        #   paginate_by per_page: 50, max_per_page: 500
-        def paginate_by(per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE)
+        #   paginate_by per_page: 50, max_per_page: 500, link_header: false
+        def paginate_by(per_page: DEFAULT_PER_PAGE, max_per_page: DEFAULT_MAX_PER_PAGE, link_header: true,
+                        page_param: nil, per_page_param: nil, style: :flat, window: nil)
           self.paginatable_per_page = per_page.to_i
           self.paginatable_max_per_page = max_per_page.to_i
+          self.paginatable_link_header = link_header ? true : false
+          self.paginatable_window = paginatable_window!(window)
+          defaults = paginatable_style_params!(style)
+          self.paginatable_page_param = paginatable_param_path!(:page_param, page_param || defaults[0])
+          self.paginatable_per_page_param = paginatable_param_path!(:per_page_param, per_page_param || defaults[1])
+        end
+
+        private
+
+        # :flat → page / per_page; :jsonapi → page[number] / page[size].
+        def paginatable_style_params!(style)
+          case style.to_sym
+          when :flat then [%w[page], %w[per_page]]
+          when :jsonapi then [%w[page number], %w[page size]]
+          else raise ArgumentError, "#{LABEL}: style: must be :flat or :jsonapi (got #{style.inspect})"
+          end
+        end
+
+        # nil / false disable the window (no `pages:` key). `0` is meaningful:
+        # first, current and last only.
+        def paginatable_window!(value)
+          return nil if value.nil? || value == false
+          return value if value.is_a?(Integer) && !value.negative?
+
+          raise ArgumentError, "#{LABEL}: window: must be a non-negative Integer or nil (got #{value.inspect})"
+        end
+
+        # A name or a non-empty path of names, normalized to Strings.
+        def paginatable_param_path!(option, value)
+          path = Array(value)
+          valid = path.any? && path.all? { |segment| (segment.is_a?(Symbol) || segment.is_a?(String)) && !segment.to_s.empty? }
+          raise ArgumentError, "#{LABEL}: #{option}: must be a param name or a path of names (got #{value.inspect})" unless valid
+
+          path.map(&:to_s).freeze
         end
       end
 
-      # Apply pagination to a relation and set the standard response headers.
-      # Returns the paginated relation; the metadata is memoized so a follow-up
-      # `pagination_meta` (no argument) reuses it. Safe on empty relations.
-      def paginated(relation)
+      # Apply pagination to a relation or an in-memory collection and set the
+      # standard response headers. A relation comes back as a relation with
+      # LIMIT/OFFSET applied (still lazy); an Enumerable comes back as the
+      # current page's Array slice (`[]` past the last page). The metadata is
+      # memoized so a follow-up `pagination_meta` (no argument) reuses it.
+      # Safe on empty collections.
+      #
+      # `total:` says the collection IS the current page already — an external
+      # API or search service returned page N of a result set it counted for
+      # you. Nothing is sliced, limited or counted: the records come back
+      # untouched and `total` drives X-Total-Count, X-Total-Pages and the Link
+      # header. Ask the upstream for the same page/per_page you read here.
+      def paginated(collection, total: nil)
         @paginatable_meta = nil
+        source = paginatable_source(collection)
+        pre_paginated = !total.nil?
         page = pagination_page
         per_page = pagination_per_page
         offset = (page - 1) * per_page
 
-        total = paginatable_total(relation)
+        total = pre_paginated ? paginatable_validate_total!(total) : paginatable_total(source)
         total_pages = per_page.positive? ? (total.to_f / per_page).ceil : 0
 
-        records = relation.limit(per_page).offset(offset)
+        records =
+          if pre_paginated
+            source # the caller already fetched exactly this page: an Array stays an Array, a relation is not limited
+          elsif source.is_a?(Array)
+            source[offset, per_page] || []
+          else
+            source.limit(per_page).offset(offset)
+          end
 
-        @paginatable_meta = { total: total, page: page, per_page: per_page, total_pages: total_pages }
-        set_pagination_headers(**@paginatable_meta)
+        @paginatable_meta =
+          paginatable_windowed(total: total, page: page, per_page: per_page, total_pages: total_pages)
+        set_pagination_headers(total: total, page: page, per_page: per_page, total_pages: total_pages)
+        set_pagination_links(page: page, total_pages: total_pages)
         records
       end
 
-      # Pagination metadata WITHOUT applying limit/offset — handy for
-      # body-based pagination (compose with Respondable's `meta:`). Call with
-      # no argument after `paginated` to reuse its memoized meta — the
+      # Pagination metadata WITHOUT applying limit/offset (or slicing) — handy
+      # for body-based pagination (compose with Respondable's `meta:`). Call
+      # with no argument after `paginated` to reuse its memoized meta — the
       # documented records+meta composition used to run the identical COUNT
-      # twice per request. Pass a relation to compute fresh.
-      def pagination_meta(relation = nil)
-        return @paginatable_meta if relation.nil? && @paginatable_meta
-
-        if relation.nil?
-          raise ArgumentError,
-                "ConcernsOnRails::Controllers::Paginatable: pagination_meta needs a relation " \
-                "(no prior paginated call in this request to reuse)"
-        end
+      # twice per request. Pass a relation or collection to compute fresh.
+      # With `total:` the COUNT is skipped (and the collection may be omitted).
+      def pagination_meta(collection = nil, total: nil)
+        return @paginatable_meta if collection.nil? && total.nil? && @paginatable_meta
 
-        total = paginatable_total(relation)
+        total = paginatable_meta_total(collection, total)
         per_page = pagination_per_page
-        {
+        paginatable_windowed(
           total: total,
           page: pagination_page,
           per_page: per_page,
           total_pages: per_page.positive? ? (total.to_f / per_page).ceil : 0
-        }
+        )
       end
 
       private
 
-      # COUNT with the clauses that break or skew it stripped: order/limit/
-      # offset are irrelevant, a custom SELECT list would turn into the invalid
-      # COUNT(a, b), and count(:all) keeps DISTINCT semantics. A grouped
-      # relation counts as a Hash (group => count); the meaningful total is the
-      # number of groups.
-      def paginatable_total(relation)
-        counted = relation.except(:order, :limit, :offset, :select).count(:all)
+      # Relations — anything answering `limit` and `offset`: an
+      # ActiveRecord::Relation, an association CollectionProxy, a model class —
+      # pass through untouched so they keep paginating in SQL. Any other
+      # non-Hash Enumerable is materialized ONCE into an Array, so an
+      # Enumerator is not consumed twice (once to count, once to slice). A Hash
+      # is rejected rather than silently paginated as [key, value] pairs.
+      def paginatable_source(collection)
+        return collection if collection.respond_to?(:limit) && collection.respond_to?(:offset)
+        return collection.to_a if collection.is_a?(Enumerable) && !collection.is_a?(Hash)
+
+        hint = collection.is_a?(Hash) ? " — call .to_a to paginate a Hash as [key, value] pairs" : ""
+        raise ArgumentError,
+              "#{LABEL}: expected an ActiveRecord relation or an Enumerable (Array, Set, Range, ...), " \
+              "got #{collection.class}#{hint}"
+      end
+
+      # `total:` wins (validated); otherwise COUNT the collection; neither
+      # given and nothing memoized is a caller error.
+      def paginatable_meta_total(collection, total)
+        return paginatable_validate_total!(total) unless total.nil?
+        return paginatable_total(paginatable_source(collection)) unless collection.nil?
+
+        raise ArgumentError,
+              "#{LABEL}: pagination_meta needs a relation or collection " \
+              "(no prior paginated call in this request to reuse)"
+      end
+
+      def paginatable_validate_total!(total)
+        return total if total.is_a?(Integer) && total >= 0
+
+        raise ArgumentError, "#{LABEL}: total: must be a non-negative Integer (got #{total.inspect})"
+      end
+
+      # Arrays already know their size. Relations COUNT with the clauses that
+      # break or skew it stripped: order/limit/offset are irrelevant, a custom
+      # SELECT list would turn into the invalid COUNT(a, b), and count(:all)
+      # keeps DISTINCT semantics. A grouped relation counts as a Hash
+      # (group => count); the meaningful total is the number of groups.
+      def paginatable_total(source)
+        return source.size if source.is_a?(Array)
+
+        counted = source.except(:order, :limit, :offset, :select).count(:all)
         counted.is_a?(Hash) ? counted.length : counted
       end
 
       # Both readers route through ScalarParam: `?page[]=1` / `?page[x]=1`
       # arrive as Array/Parameters, and calling .to_i on those was a 500.
       def pagination_page
-        [ConcernsOnRails::Support::ScalarParam.to_i(params[:page], default: 0), 1].max
+        [ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_page_param), default: 0), 1].max
       end
 
       def pagination_per_page
-        requested = ConcernsOnRails::Support::ScalarParam.to_i(params[:per_page], default: 0)
+        requested = ConcernsOnRails::Support::ScalarParam.to_i(pagination_param(self.class.paginatable_per_page_param), default: 0)
         requested = self.class.paginatable_per_page if requested < 1
         cap = self.class.paginatable_max_per_page
         cap.positive? ? [requested, cap].min : requested
       end
 
+      # Dig the configured path out of params: `["page"]` → params[:page];
+      # `["page", "number"]` → params[:page][:number]. A scalar where a Hash
+      # is expected yields nil (→ the default), like any other garbage.
+      def pagination_param(path)
+        path.reduce(params) do |node, key|
+          break nil unless node.respond_to?(:[]) && !node.is_a?(String) && !node.is_a?(Array)
+
+          node[key]
+        end
+      end
+
+      # The `overrides` for LinkHeader.url_for that set the page number under the
+      # configured name — replacing the whole nested Hash for a path so the
+      # other keys in it (page[size]) survive.
+      def pagination_page_override(number)
+        path = self.class.paginatable_page_param
+        return { path.first.to_sym => number } if path.size == 1
+
+        nested = request.query_parameters.to_h.transform_keys(&:to_s)[path.first]
+        nested = nested.is_a?(Hash) ? nested.deep_dup : {}
+        node = nested
+        path[1...-1].each { |key| node = (node[key] = node[key].is_a?(Hash) ? node[key] : {}) }
+        node[path.last] = number
+        { path.first.to_sym => nested }
+      end
+
+      # Adds `pages:` to a meta Hash when `window:` is declared, and leaves the
+      # Hash untouched otherwise — the key is absent, never nil, so
+      # `meta.key?(:pages)` is a clean opt-in probe.
+      def paginatable_windowed(meta)
+        pages = paginatable_page_window(meta[:page], meta[:total_pages])
+        pages ? meta.merge(pages: pages) : meta
+      end
+
+      # First, last, and `window` pages either side of the current page, with
+      # :gap standing in for the runs left out — [1, :gap, 46, 47, 48, :gap, 100].
+      # Pure arithmetic over the total already counted: no extra query. A page
+      # past the last one windows around the last page, as `prev` already does.
+      def paginatable_page_window(page, total_pages)
+        window = self.class.paginatable_window
+        return nil if window.nil? || total_pages < 1
+
+        current = page.clamp(1, total_pages)
+        from = [current - window, 1].max
+        to = [current + window, total_pages].min
+        paginatable_insert_gaps(([1, total_pages] + (from..to).to_a).uniq.sort)
+      end
+
+      # A jump of exactly two pages is filled with the page it would have
+      # hidden — "1 2 3", never the wider "1 … 3"; anything longer collapses
+      # into one :gap.
+      def paginatable_insert_gaps(numbers)
+        numbers.each_cons(2).with_object([numbers.first]) do |(previous, current), result|
+          result << (previous + 1) if current - previous == 2
+          result << :gap if current - previous > 2
+          result << current
+        end
+      end
+
       def set_pagination_headers(total:, page:, per_page:, total_pages:)
         return unless respond_to?(:response) && response
 
@@ -111,6 +283,30 @@ module ConcernsOnRails
         response.set_header("X-Per-Page", per_page.to_s)
         response.set_header("X-Total-Pages", total_pages.to_s)
       end
+
+      # Link: <…?page=1>; rel="first", <…?page=1>; rel="prev", <…?page=3>;
+      # rel="next", <…?page=5>; rel="last". prev/next only when such a page
+      # exists; past the end, prev points at the last page. Nothing is emitted
+      # for an empty collection, when disabled, or without a real request.
+      def set_pagination_links(page:, total_pages:)
+        return unless pagination_links_applicable?(total_pages)
+
+        page_url = ->(number) { ConcernsOnRails::Support::LinkHeader.url_for(request, **pagination_page_override(number)) }
+        ConcernsOnRails::Support::LinkHeader.append(
+          response,
+          first: page_url.call(1),
+          prev: page > 1 ? page_url.call([page - 1, total_pages].min) : nil,
+          next: page < total_pages ? page_url.call(page + 1) : nil,
+          last: page_url.call(total_pages)
+        )
+      end
+
+      def pagination_links_applicable?(total_pages)
+        return false unless self.class.paginatable_link_header && total_pages.positive?
+        return false unless respond_to?(:response) && response
+
+        ConcernsOnRails::Support::LinkHeader.available?(self)
+      end
     end
   end
 end

data/lib/concerns_on_rails/support/link_header.rb

@@ -0,0 +1,54 @@
+require "rack/utils"
+
+module ConcernsOnRails
+  module Support
+    # RFC 8288 `Link` response header for the paginators: rebuilds the current
+    # request URL with a few query params changed (`page=3`, `cursor=…`) and
+    # appends `<url>; rel="next"` entries to the response — never clobbering a
+    # Link header something else already set (Deprecatable's rel="deprecation",
+    # CDN preload hints). Shared by Paginatable and CursorPaginatable.
+    module LinkHeader
+      module_function
+
+      # True when the controller has a request the URLs can be rebuilt from.
+      # The dependency-free FakeController has none, so emission is skipped.
+      def available?(controller)
+        return false unless controller.respond_to?(:request)
+
+        request = controller.request
+        %i[base_url path query_parameters].all? { |reader| request.respond_to?(reader) }
+      end
+
+      # The request's URL with `overrides` merged into its query string (a nil
+      # value or a key in `drop:` removes that param; a Hash value replaces a
+      # nested param wholesale — `page: { "number" => 3, "size" => 10 }`).
+      # Existing params keep their order; nested params survive via Rack's
+      # nested-query encoding.
+      def url_for(request, drop: [], **overrides)
+        query = request.query_parameters.to_h.transform_keys(&:to_s)
+        overrides.each { |key, value| value.nil? ? query.delete(key.to_s) : query[key.to_s] = stringify_deep(value) }
+        Array(drop).each { |key| query.delete(key.to_s) }
+
+        base = "#{request.base_url}#{request.path}"
+        query.empty? ? base : "#{base}?#{Rack::Utils.build_nested_query(query)}"
+      end
+
+      # build_nested_query wants String keys and String leaves.
+      def stringify_deep(value)
+        return value.to_h { |k, v| [k.to_s, stringify_deep(v)] } if value.is_a?(Hash)
+
+        value.to_s
+      end
+
+      # `links` is { rel => url }; nil urls are skipped and nothing is set when
+      # none remain. Appends to an existing Link header, comma-separated.
+      def append(response, links)
+        entries = links.filter_map { |rel, url| %(<#{url}>; rel="#{rel}") if url }
+        return if entries.empty?
+
+        existing = response.headers["Link"]
+        response.set_header("Link", [existing, entries.join(", ")].reject { |part| part.nil? || part.empty? }.join(", "))
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.27.0".freeze
+  VERSION = "1.28.1".freeze
 end

data/lib/concerns_on_rails.rb

@@ -80,6 +80,7 @@ module ConcernsOnRails
     autoload :Encryptor,               "concerns_on_rails/support/encryptor"
     autoload :Affix,                   "concerns_on_rails/support/affix"
     autoload :BatchOps,                "concerns_on_rails/support/batch_ops"
+    autoload :LinkHeader,              "concerns_on_rails/support/link_header"
   end
 
   # Encryption config + error types (Support::Encryptor requires it itself)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.27.0
+  version: 1.28.1
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-30 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -186,6 +186,7 @@ files:
 - lib/concerns_on_rails/support/error_envelope.rb
 - lib/concerns_on_rails/support/filter_parameter_registry.rb
 - lib/concerns_on_rails/support/html_sanitizers.rb
+- lib/concerns_on_rails/support/link_header.rb
 - lib/concerns_on_rails/support/masker.rb
 - lib/concerns_on_rails/support/money.rb
 - lib/concerns_on_rails/support/random_value.rb