standard_pagination 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d60e0bc850fa3f5f3efdfc07c355de37b9c4d569d86f05ddd47962c20e4a1636
+  data.tar.gz: dd47c304ed63c9f5a6df5f7c69a07eff5ef32fe495b372fe1cc0b1b072af52e7
+SHA512:
+  metadata.gz: f07018870793cd23b22a8043c8e0aa34977dbf46547355922e90855135ee36fa6fb60cccc452f4bebff45ca4667cdd9456e4a176f5f922bde78dfc977dbc407e
+  data.tar.gz: 5a0762267cadaf3fad98ad90b2dd7cef1dfee4862bc66ee8d4b1dcf0c1e5966e8384afebe1063c50f434c1b0d073add3b47d39e1c131096cf170a5fa9d468c5e

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-25
+
+### Added
+- `StandardPagination::Controller`, a concern that adds:
+  - `paginate`, which wraps `pagy`. HTML pages ignore a client-chosen page size, JSON lets clients choose one up to `config.max_limit`, and the primary key is appended as a tie-breaker. It also neutralises any `max_limit`/`client_limit` left in `Pagy::OPTIONS` for that call.
+  - `pagination_data`, which returns the standard `data_hash` keys.
+  - `rescue_pagination_errors(html:, notice:)`: a 400 for JSON; for HTML a redirect that keeps filters (and answers 400 rather than redirect to the same failing URL), a 404, or a custom method. Declaring it again replaces the earlier handler.
+- `StandardPagination::Mcp.paginate`, the MCP list helper, which keeps the `page`/`per_page`/`total_count`/`total_pages` shape. A non-positive or junk `per_page` now falls back to the default instead of becoming 1.
+- `StandardPagination::StableOrder` and `StandardPagination::Model#stable_order`.
+- A Railtie boot check for leftover client-limit options in `Pagy::OPTIONS`.
+- Tested against pagy 43.6 and 43.8.

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rarebit One
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,136 @@
+# StandardPagination
+
+Shared pagination conventions for the estate's Rails apps, built on [pagy](https://github.com/ddnexus/pagy) 43.
+
+Before this gem, sidekick-web, nutripod-web, fundbright-web and luminality-web each kept their own copy of the same helpers, and shared the same bugs:
+
+- **Clients could set the page size on every list.** Each app's `Pagy::OPTIONS[:max_limit] = 100` became pagy 43.7's `client_limit`, which lets a client pick any page size up to 100 with `?limit=`, even where the call site fixed one.
+- **Rows repeated or went missing between pages.** Lists sorted only on a timestamp, so equal rows could land in a different order on the next page's query.
+- **Errors returned 500 or looped.** JSON APIs had no pagy rescue, and an HTML redirect could lose filters or loop.
+
+The gem provides one copy of each helper, and these fixes:
+
+| Piece | What it does |
+|---|---|
+| `StandardPagination::Controller` | `paginate` and `pagination_data`. HTML pages keep the page size the call site sets, and JSON clients may choose one up to a cap. It adds an id tie-breaker and lets you opt in to `rescue_pagination_errors`. |
+| `StandardPagination::Mcp.paginate` | The MCP list-tool helper every app's `ApplicationTool` carried a copy of. It keeps the same response shape. |
+| `StandardPagination::StableOrder` / `Model#stable_order` | Appends the primary key to an ORDER BY when that is safe. |
+| Railtie | At boot, flags a leftover `max_limit` or `client_limit` in `Pagy::OPTIONS`. It raises in development and test, and logs elsewhere. |
+
+## Install
+
+```ruby
+gem "standard_pagination", "~> 0.1"
+```
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include StandardPagination::Controller   # includes Pagy::Method
+
+  rescue_from StandardError, with: :render_error   # catch-alls first...
+  rescue_pagination_errors html: :redirect          # ...then this, so it wins
+end
+
+# app/models/application_record.rb
+class ApplicationRecord < ActiveRecord::Base
+  include StandardPagination::Model
+end
+```
+
+Delete `max_limit` (or `client_limit`) from `config/initializers/pagy.rb`. Leave `raise_range_error` out as well: `paginate` passes `config.raise_range_error`, which defaults to `true`.
+
+```ruby
+# config/initializers/standard_pagination.rb (optional; these are the defaults)
+StandardPagination.configure do |c|
+  c.default_limit = 20            # rows when a call site passes no limit:
+  c.max_limit = 100               # cap on a client-chosen page size
+  c.limit_key = "limit"           # param a client sets it with ("per_page" in luminality)
+  c.client_limit_formats = %i[json]
+  c.tiebreak = true
+  c.raise_range_error = true
+  c.strict_options = nil          # nil = raise in dev/test, log elsewhere
+end
+```
+
+## Controllers
+
+```ruby
+pagy, devices = paginate(Device.where(zone:).order(created_at: :desc), limit: 25)
+
+render inertia: "factory/devices/index", props: {
+  devices: devices.map { DeviceSerializer.new(_1) },
+  pagination: pagination_data(pagy)
+}
+```
+
+`pagination_data` returns `{ page, pages, count, limit, from, to, previous, next }`. `previous` and `next` are left out on the first and last page, as pagy's `data_hash` always did. It is the shape every app's `PaginationMetadata` TypeScript type already describes.
+
+`paginate` options:
+
+- `limit:` is the page size. It defaults to `config.default_limit`.
+- `client_limit:` lets the request set the page size through `config.limit_key`. Pass an Integer cap, `true` for `config.max_limit`, or `false` to turn it off. It defaults to on for JSON and off for HTML. A request value that is junk, zero or negative falls back to `limit:`.
+- `tiebreak:` defaults to `config.tiebreak`.
+- `paginator:` defaults to `:offset`. `:countless` skips the `COUNT(*)` on big append-only tables. Any other pagy option, such as `page_key:` or `count:`, passes through.
+
+For several tables on one page, give each its own `page_key:`:
+
+```ruby
+pagy_new, new_apps = paginate(new_scope, page_key: "new_page")
+pagy_done, done_apps = paginate(done_scope, page_key: "done_page")
+```
+
+### Errors
+
+`rescue_pagination_errors` handles `Pagy::OptionError`, which includes its subclass `Pagy::RangeError`.
+
+| Request | Out-of-range page | Any other bad option |
+|---|---|---|
+| JSON | 400 `{ error: "Page out of range", last_page: 4 }` | 400 `{ error: "Invalid pagination parameters", last_page: null }` |
+| HTML, `html: :redirect` | Redirects to the last page, keeping every other param | Redirects without the page and limit params; 400 if there are none to drop |
+| HTML, `html: :not_found` | 404 | 404 |
+| HTML, `html: :my_method` | Calls `my_method(exception)` | Calls `my_method(exception)` |
+
+`notice:` sets the redirect's flash. Pass a String, or a Proc for I18n: `notice: -> { t("flash.application.pagination_out_of_range") }`.
+
+## Ordering
+
+`paginate` and `Mcp.paginate` append the primary key in the direction of the last sort key:
+
+```sql
+ORDER BY occurred_at DESC              -- before
+ORDER BY occurred_at DESC, id DESC     -- after
+```
+
+An unordered relation gets `ORDER BY id ASC`. The relation is left alone when the key is already in the order, and in these unsafe cases:
+
+- it has a `GROUP BY`
+- it uses `DISTINCT` with a custom `SELECT`
+- it has a custom `FROM`
+- the model's primary key is composite
+
+Outside a paginator (a query object, or an engine scope a host will page through), use `Model.stable_order(...)`, for example `AuditLog.where(...).stable_order(occurred_at: :desc)`.
+
+## MCP tools
+
+```ruby
+# lib/mcp/tools/application_tool.rb
+def paginate(scope, page: 1, per_page: DEFAULT_PER_PAGE)
+  StandardPagination::Mcp.paginate(scope, page:, per_page:, max_per_page: MAX_PER_PAGE)
+end
+```
+
+It returns `[records, { page:, per_page:, total_count:, total_pages: }]`, the shape MCP clients already parse. A `GROUP BY` relation counts its groups, and a page past the end returns no records.
+
+## Not in 0.1
+
+- **Keyset or cursor pagination for feeds and APIs.** Today these are hand-rolled in sidekick-web's companion queries and in jumpdrive. 0.2 is meant to settle on a single `next_cursor` / `has_more` envelope.
+- **A shared React `<Pagination>` component.** It belongs in a frontend package, not a gem.
+
+## Development
+
+```bash
+bundle exec rspec                                              # newest pagy
+BUNDLE_GEMFILE=gemfiles/pagy-43.6.gemfile bundle exec rspec    # oldest a consumer runs
+bundle exec rubocop
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/standard_pagination/config.rb

@@ -0,0 +1,32 @@
+module StandardPagination
+  class Config
+    # Rows per page when a call site passes no `limit:`.
+    attr_accessor :default_limit
+    # Largest page size a client may request when client limits are on.
+    attr_accessor :max_limit
+    # Request param a client sets the page size with (when allowed).
+    attr_accessor :limit_key
+    # Formats for which `paginate` honours the client's page size by default.
+    # HTML pages keep the size the call site chose.
+    attr_accessor :client_limit_formats
+    # Pagy raises Pagy::RangeError for a page past the last one, which
+    # Controller.rescue_pagination_errors turns into a redirect, 404 or 400.
+    # With it off, pagy serves an empty page instead.
+    attr_accessor :raise_range_error
+    # `paginate` appends the primary key to the ORDER BY unless told not to.
+    attr_accessor :tiebreak
+    # Raise (rather than warn) at boot when Pagy::OPTIONS still sets a
+    # client-limit option. Defaults to true in development and test only.
+    attr_accessor :strict_options
+
+    def initialize
+      @default_limit = 20
+      @max_limit = 100
+      @limit_key = "limit"
+      @client_limit_formats = %i[json]
+      @raise_range_error = true
+      @tiebreak = true
+      @strict_options = nil
+    end
+  end
+end

data/lib/standard_pagination/controller.rb

@@ -0,0 +1,164 @@
+require "active_support/concern"
+require "action_controller"
+
+module StandardPagination
+  # Include in ApplicationController (and any API base controller that does not
+  # inherit from it):
+  #
+  #   include StandardPagination::Controller
+  #   rescue_pagination_errors html: :redirect   # last, after any catch-alls
+  #
+  #   pagy, records = paginate(Device.where(...).order(created_at: :desc))
+  #   render inertia: "devices/index", props: { devices: ..., pagination: pagination_data(pagy) }
+  module Controller
+    extend ActiveSupport::Concern
+
+    HTML_STRATEGIES = %i[redirect not_found].freeze
+
+    included do
+      include Pagy::Method
+
+      class_attribute :_pagination_error_handling, instance_accessor: false, default: nil
+    end
+
+    class_methods do
+      # Turns Pagy::OptionError (and its subclass Pagy::RangeError) into a
+      # response instead of a 500.
+      #
+      # JSON requests get a 400 with `last_page` (an integer for an
+      # out-of-range page, null for any other bad option). HTML requests,
+      # depending on `html:`:
+      #
+      # - `:redirect` redirects to the last page, keeping every other query
+      #   param so filters survive. For a bad option other than the page, it
+      #   drops the page and limit params instead; if there are none to drop,
+      #   it responds 400 rather than redirect to the same failing URL.
+      # - `:not_found` responds 404 with an empty body.
+      # - a Symbol naming a controller method calls it with the exception,
+      #   e.g. `html: :render_not_found` for an app's own 404 page.
+      #
+      # `notice:` is the flash for the redirect: a String, or a Proc evaluated
+      # in the controller (for I18n).
+      #
+      # Rails looks rescue handlers up from last-declared to first, so call
+      # this after any `rescue_from StandardError`. Calling it again replaces
+      # the earlier registration rather than stacking a second handler.
+      def rescue_pagination_errors(html: :redirect, notice: nil)
+        self._pagination_error_handling = { html:, notice: }
+
+        self.rescue_handlers = rescue_handlers.reject { |handler| handler.first == "Pagy::OptionError" }
+        rescue_from Pagy::OptionError, with: :handle_pagination_error
+      end
+    end
+
+    private
+
+    # Paginates `collection` with pagy and returns `[pagy, records]`.
+    #
+    # - `limit:` is the page size for this call (default: config.default_limit).
+    # - `client_limit:` lets the request override the page size via the
+    #   config.limit_key param, capped at an Integer, or at config.max_limit
+    #   for `true`. It defaults to on for config.client_limit_formats (JSON)
+    #   and off for HTML, so an HTML page always shows the size it chose.
+    #   A non-positive or non-numeric request value falls back to `limit:`.
+    # - `tiebreak:` appends the primary key to the ORDER BY (StableOrder).
+    # - `paginator:` is passed through to pagy (`:offset`, `:countless`, ...),
+    #   as is any other pagy option (`page_key:`, `count:`, ...).
+    #
+    # Global client-limit options in Pagy::OPTIONS are neutralised for this
+    # call, so only `client_limit:` decides whether the client picks the size.
+    def paginate(collection, limit: nil, client_limit: nil, tiebreak: nil, paginator: :offset, **options)
+      config = StandardPagination.config
+      tiebreak = config.tiebreak if tiebreak.nil?
+      collection = StableOrder.apply(collection) if tiebreak
+      # pagy counts the underlying rows, not an inline DISTINCT's result set.
+      if paginator == :offset && !options.key?(:count) && StableOrder.inline_distinct?(collection)
+        options[:count] = Mcp.count(collection)
+      end
+
+      pagy(
+        paginator,
+        collection,
+        raise_range_error: config.raise_range_error,
+        **options,
+        limit: resolve_pagination_limit(limit || config.default_limit, client_limit),
+        max_limit: nil,
+        client_limit: nil,
+        client_max_limit: nil
+      )
+    end
+
+    def pagination_data(pagy)
+      StandardPagination.data(pagy)
+    end
+
+    def resolve_pagination_limit(limit, client_limit)
+      cap = pagination_client_limit_cap(client_limit)
+      return limit unless cap
+
+      requested = params[StandardPagination.config.limit_key].to_s
+      return limit unless requested.match?(/\A\d+\z/) && requested.to_i.positive?
+
+      [ requested.to_i, cap ].min
+    end
+
+    def pagination_client_limit_cap(client_limit)
+      client_limit = pagination_client_limit_format? if client_limit.nil?
+
+      case client_limit
+      when Integer then client_limit
+      when true then StandardPagination.config.max_limit
+      end
+    end
+
+    def pagination_client_limit_format?
+      formats = StandardPagination.config.client_limit_formats
+      formats.any? { |format| request.format.public_send(:"#{format}?") }
+    end
+
+    def handle_pagination_error(exception)
+      handling = self.class._pagination_error_handling || {}
+      last_page = exception.is_a?(Pagy::RangeError) ? exception.pagy&.last : nil
+
+      if request.format.json?
+        return render json: { error: pagination_error_message(exception), last_page: }, status: :bad_request
+      end
+
+      case handling.fetch(:html, :redirect)
+      when :redirect then redirect_after_pagination_error(exception, last_page, handling[:notice])
+      when :not_found then head :not_found
+      else send(handling[:html], exception)
+      end
+    end
+
+    def pagination_error_message(exception)
+      exception.is_a?(Pagy::RangeError) ? "Page out of range" : "Invalid pagination parameters"
+    end
+
+    def redirect_after_pagination_error(exception, last_page, notice)
+      options = exception.pagy&.options || {}
+      page_key = (options[:page_key] || Pagy::DEFAULT[:page_key]).to_s
+      original = request.query_parameters
+      query = original.except(page_key)
+
+      if last_page
+        query[page_key] = last_page
+      else
+        query = query.except((options[:limit_key] || Pagy::DEFAULT[:limit_key]).to_s, StandardPagination.config.limit_key)
+        # Nothing left to drop: the bad option came from the call site or a
+        # param this gem doesn't know, so redirecting would only repeat it.
+        return head(:bad_request) if query == original
+      end
+
+      # Rebuild the path from the current route rather than echoing
+      # request.path, and refuse other hosts, so the redirect can only ever
+      # land on this app. The query is appended separately: merged into the
+      # url_for options, a ?action= or ?host= param would steer the route.
+      path = url_for(request.path_parameters.merge(only_path: true))
+      location = query.empty? ? path : "#{path}?#{query.to_query}"
+      notice = instance_exec(&notice) if notice.respond_to?(:call)
+      flash = notice ? { notice: } : {}
+      redirect_to(location, allow_other_host: false, **flash)
+    end
+  end
+end

data/lib/standard_pagination/mcp.rb

@@ -0,0 +1,40 @@
+module StandardPagination
+  # Offset pagination for MCP list tools, shared by every app's
+  # ApplicationTool. MCP clients already consume this shape, so it keeps the
+  # `per_page`/`total_count`/`total_pages` keys rather than the controller's.
+  module Mcp
+    DEFAULT_PER_PAGE = 20
+    MAX_PER_PAGE = 100
+
+    module_function
+
+    # Returns `[records, { page:, per_page:, total_count:, total_pages: }]`.
+    # A page past the end returns no records rather than raising.
+    def paginate(scope, page: 1, per_page: DEFAULT_PER_PAGE, max_per_page: MAX_PER_PAGE, tiebreak: nil)
+      tiebreak = StandardPagination.config.tiebreak if tiebreak.nil?
+      page = [ page.to_i, 1 ].max
+      per_page = per_page.to_i
+      per_page = DEFAULT_PER_PAGE unless per_page.positive?
+      per_page = per_page.clamp(1, max_per_page)
+
+      total = count(scope)
+      scope = StableOrder.apply(scope) if tiebreak
+      records = scope.offset((page - 1) * per_page).limit(per_page).to_a
+
+      [ records, { page:, per_page:, total_count: total, total_pages: (total.to_f / per_page).ceil } ]
+    end
+
+    def count(scope)
+      # `select("DISTINCT ...")` returns fewer rows than count(:all) counts,
+      # so count the projected result set instead.
+      if StableOrder.inline_distinct?(scope)
+        return scope.klass.unscoped.from(scope.unscope(:order), :subquery).count
+      end
+
+      total = scope.count(:all)
+      # GROUP BY relations count to a Hash of group => count; the number of
+      # groups is the number of rows being paged over.
+      total.is_a?(Hash) ? total.size : total
+    end
+  end
+end

data/lib/standard_pagination/model.rb

@@ -0,0 +1,21 @@
+require "active_support/concern"
+
+module StandardPagination
+  # Include in ApplicationRecord to get a `stable_order` scope:
+  #
+  #   AuditLog.stable_order(occurred_at: :desc)
+  #   # ORDER BY occurred_at DESC, id DESC
+  #
+  # Use it where an ordering leaves the paginator, e.g. a query object or an
+  # engine scope that a host app will page through. Controller#paginate and
+  # Mcp.paginate apply the same tie-breaker on their own.
+  module Model
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def stable_order(*args)
+        StableOrder.apply(order(*args))
+      end
+    end
+  end
+end

data/lib/standard_pagination/railtie.rb

@@ -0,0 +1,16 @@
+require "rails/railtie"
+
+module StandardPagination
+  class Railtie < ::Rails::Railtie
+    # Runs after the app's config/initializers, so it sees the app's
+    # Pagy::OPTIONS. Raises in development and test (so CI catches it) and
+    # logs elsewhere, unless config.strict_options says otherwise.
+    config.after_initialize do
+      strict = StandardPagination.config.strict_options
+      strict = Rails.env.local? if strict.nil?
+
+      message = StandardPagination.check_pagy_options!(raise_error: strict)
+      Rails.logger&.warn("[standard_pagination] #{message}") if message
+    end
+  end
+end

data/lib/standard_pagination/stable_order.rb

@@ -0,0 +1,73 @@
+module StandardPagination
+  # Offset pagination over a non-unique ORDER BY can repeat or skip rows
+  # between pages: Postgres returns equal-sorting rows in any order, and that
+  # order can differ between the OFFSET 0 and OFFSET 20 queries. Appending the
+  # primary key makes the order total.
+  module StableOrder
+    DESC_PATTERN = /\bdesc\b/i
+
+    module_function
+
+    # Returns the relation with the primary key appended to its ORDER BY,
+    # in the direction of the last existing sort key. Returns it unchanged
+    # when that is unnecessary or would be unsafe:
+    #
+    # - not an ActiveRecord::Relation (arrays, search results)
+    # - no single-column primary key
+    # - already ordered by the primary key
+    # - GROUP BY (the key isn't in the group, so Postgres rejects it)
+    # - DISTINCT with a custom SELECT, including `select("DISTINCT ...")`
+    #   (the key may not be selected)
+    # - a custom FROM (the table name may not resolve)
+    def apply(relation)
+      return relation unless tiebreakable?(relation)
+
+      primary_key = relation.klass.primary_key
+      return relation if ordered_by?(relation, primary_key)
+
+      attribute = relation.klass.arel_table[primary_key]
+      relation.order(descending?(relation.order_values.last) ? attribute.desc : attribute.asc)
+    end
+
+    def tiebreakable?(relation)
+      return false unless defined?(::ActiveRecord::Relation) && relation.is_a?(::ActiveRecord::Relation)
+      return false unless relation.klass.primary_key.is_a?(String)
+      return false if relation.group_values.any?
+      return false if relation.distinct_value && relation.select_values.any?
+      return false if inline_distinct?(relation)
+
+      relation.from_clause.empty?
+    end
+
+    # `select("DISTINCT category")` leaves distinct_value unset.
+    def inline_distinct?(relation)
+      relation.select_values.any? { |value| !value.is_a?(Symbol) && value.to_s.match?(/\bdistinct\b/i) }
+    end
+
+    def ordered_by?(relation, primary_key)
+      table = relation.klass.table_name
+      pattern = /\A\s*(?:"?#{Regexp.escape(table)}"?\.)?"?#{Regexp.escape(primary_key)}"?(?:\s+(?:asc|desc))?\s*\z/i
+
+      relation.order_values.any? do |value|
+        node = value.is_a?(Arel::Nodes::Ordering) ? value.expr : value
+        case node
+        when Arel::Attributes::Attribute
+          node.name.to_s == primary_key && node.relation.name.to_s == table
+        when String, Symbol
+          node.to_s.split(",").any? { |part| part.match?(pattern) }
+        else
+          false
+        end
+      end
+    end
+
+    def descending?(value)
+      case value
+      when Arel::Nodes::Descending then true
+      when Arel::Nodes::Ordering then false
+      when String, Arel::Nodes::SqlLiteral then value.to_s.split(",").last.to_s.match?(DESC_PATTERN)
+      else false
+      end
+    end
+  end
+end

data/lib/standard_pagination/version.rb

@@ -0,0 +1,3 @@
+module StandardPagination
+  VERSION = "0.1.0"
+end

data/lib/standard_pagination.rb

@@ -0,0 +1,63 @@
+require "pagy"
+require "active_support"
+require "active_support/core_ext/module/attribute_accessors"
+
+require "standard_pagination/version"
+require "standard_pagination/config"
+require "standard_pagination/stable_order"
+require "standard_pagination/mcp"
+
+module StandardPagination
+  class ConfigurationError < StandardError; end
+
+  # The one metadata shape every Inertia prop and JSON list sends. pagy's
+  # `data_hash` omits a key whose value is nil, so `previous`/`next` are absent
+  # on the first/last page rather than null; consumers' TypeScript types
+  # already treat them as optional.
+  DATA_KEYS = %i[page pages count limit from to previous next].freeze
+
+  # Global pagy options that make pagy read the page size from the request.
+  # 43.6 reads `max_limit`; 43.7 reads `client_limit` and maps the other two
+  # onto it with a deprecation warning on every call.
+  CLIENT_LIMIT_OPTIONS = %i[max_limit client_limit client_max_limit].freeze
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_config!
+      @config = Config.new
+    end
+
+    def data(pagy)
+      pagy.data_hash(data_keys: DATA_KEYS)
+    end
+
+    # Global pagy client-limit options left over from before this gem. They
+    # still apply to any bare `pagy(...)` call that bypasses
+    # Controller#paginate, letting clients pick the page size.
+    def leftover_client_limit_options(options = Pagy::OPTIONS)
+      CLIENT_LIMIT_OPTIONS.select { |key| options.key?(key) }
+    end
+
+    def check_pagy_options!(options = Pagy::OPTIONS, raise_error: true)
+      leftovers = leftover_client_limit_options(options)
+      return if leftovers.empty?
+
+      message = "Pagy::OPTIONS sets #{leftovers.map(&:inspect).join(', ')}, which lets clients choose the page " \
+                "size on every bare `pagy` call. Remove it and use `paginate(..., client_limit:)` instead."
+      raise ConfigurationError, message if raise_error
+
+      message
+    end
+  end
+end
+
+require "standard_pagination/controller"
+require "standard_pagination/model"
+require "standard_pagination/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,162 @@
+--- !ruby/object:Gem::Specification
+name: standard_pagination
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jaryl Sim
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pagy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '43.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '44'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '43.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '44'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: brakeman
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: StandardPagination wraps pagy with one controller concern, one metadata
+  shape, safe page-size handling, out-of-range error handling, deterministic tie-broken
+  ordering, and an MCP list helper shared across Rails apps.
+email:
+- code@jaryl.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/standard_pagination.rb
+- lib/standard_pagination/config.rb
+- lib/standard_pagination/controller.rb
+- lib/standard_pagination/mcp.rb
+- lib/standard_pagination/model.rb
+- lib/standard_pagination/railtie.rb
+- lib/standard_pagination/stable_order.rb
+- lib/standard_pagination/version.rb
+homepage: https://github.com/rarebit-one/standard_pagination
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rarebit-one/standard_pagination
+  source_code_uri: https://github.com/rarebit-one/standard_pagination
+  changelog_uri: https://github.com/rarebit-one/standard_pagination/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/rarebit-one/standard_pagination/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Shared pagination conventions for Rails apps, built on pagy.
+test_files: []