standard_pagination 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8213902bdeb4fed07cf6c759eb52fc064a4f62154a25a7c92dafba705232a7d
-  data.tar.gz: 6fc78271275b84da5b601836cd6b03e100545b43a8c79ffc6ef8ea30a761e139
+  metadata.gz: 488e76612676ede6f2beabac3c2bcd9c64e9568de2e69967d11fda8e704cb2ea
+  data.tar.gz: f06fdab7e881ecd290e20287f2f073614ad92b895e035881be0f147f98e8ac64
 SHA512:
-  metadata.gz: 41c6e457018dd8e2c9d320cd7ea298a7c8812cefd64ff47d1828d12851cdcbe6e45da01add2a7cf70b8cda166789b4d851dec5812cc6f8fb8443e6737f914f50
-  data.tar.gz: 631d2e4e9ad5bd57077073417663f19e709912171918b6dd39feaf8370848f7d9fb6ac8ea228ec41b5fe334a992393593a47b622c450c6bfbe7204d78c6efd4d
+  metadata.gz: 1c6b369a714822c0d50025ad79f7f9919ba2e2fa735172651b11fbc6edb491321b118abd00135ddbb0eb43b418d384241df6615c2815e077bbf1e696baee969d
+  data.tar.gz: f33f5b5a13a41e8c7169996e355e20717c24a32ad1518f7eb49bbeddefe527f5888d2e963d5d93530cabc9db4b1fe9629b2692559f77d50fa4165df718761211

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-26
+
+### Added
+- `Controller#paginate_cursor` and `#cursor_data`: keyset (cursor) pagination for feeds, with one envelope, `{ data, next_cursor, has_more }`. The client sends `next_cursor` back as `?cursor=` (`config.cursor_key`). The primary key is appended so the order is total, and a cursor the server didn't issue is a 400 for JSON, or a redirect without it for HTML. This is the estate convention for new feeds. sidekick-web, jumpdrive and the rest had each hand-rolled their own (`has_more`/`before`/`next_page_token`, `next_cursor`, `since`).
+- `config.client_limit_formats = :non_html` lets every request whose format isn't HTML choose the page size.
+- `pagination_client_limit`, a class attribute that sets the `client_limit:` default for a controller and its subclasses. Set it on an API base controller: a client that sends no JSON `Accept` header is treated as HTML by Rails, so neither the JSON default nor `:non_html` would let it choose a page size. sidekick-web's sandbox endpoint passed `client_limit: true` per call for this reason.
+
 ## [0.1.2] - 2026-10-26
 
 ### Added

data/README.md

@@ -46,7 +46,8 @@ 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; an Array accepts aliases, e.g. %w[limit per_page]
-  c.client_limit_formats = %i[json]
+  c.client_limit_formats = %i[json] # or :non_html for every non-HTML request
+  c.cursor_key = "cursor"         # param paginate_cursor reads the cursor from
   c.tiebreak = true
   c.raise_range_error = true
   c.strict_options = nil          # nil = raise in dev/test, log elsewhere
@@ -69,7 +70,18 @@ render inertia: "factory/devices/index", props: {
 `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:`.
+- `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. A request value that is junk, zero or negative falls back to `limit:`. When omitted it falls back to:
+  1. the controller's `pagination_client_limit`, if set;
+  2. otherwise `config.client_limit_formats`: on for JSON and off for HTML by default.
+
+An API base controller whose clients may send no `Accept: application/json` header (Rails treats those requests as HTML) should opt in once, instead of per call:
+
+```ruby
+class Api::BaseController < ActionController::API
+  include StandardPagination::Controller
+  self.pagination_client_limit = true   # or an Integer cap
+end
+```
 - `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.
 
@@ -111,6 +123,29 @@ An unordered relation gets `ORDER BY id ASC`. The relation is left alone when th
 
 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)`.
 
+## Cursor pagination
+
+For feeds and append-heavy APIs, `paginate_cursor` uses pagy's keyset paginator: no `COUNT`, no `OFFSET`, and rows inserted while a client pages don't shift or repeat what it sees.
+
+```ruby
+pagy, events = paginate_cursor(Event.where(device:).order(occurred_at: :desc), limit: 50)
+
+render json: { data: events.map { EventSerializer.new(_1) }, **cursor_data(pagy) }
+```
+
+This is the one envelope for cursor-paged responses:
+
+```json
+{ "data": [...], "next_cursor": "eyJ...", "has_more": true }
+```
+
+- The client sends `next_cursor` back as `?cursor=` (`config.cursor_key`). `next_cursor` is `null` and `has_more` is `false` on the last page.
+- Order the set with hash or symbol orders (`order(occurred_at: :desc)`), not SQL strings: pagy builds the cursor from those columns. The primary key is appended so the order is total.
+- `limit:`, `client_limit:` and `tiebreak:` work as in `paginate`.
+- A cursor the server didn't issue raises `Pagy::OptionError`: `rescue_pagination_errors` answers 400 for JSON, and for HTML redirects without the cursor.
+
+Use it for new feeds, and when an existing feed is reworked. Feeds that mobile clients already parse keep their current shape until their clients move.
+
 ## MCP tools
 
 ```ruby
@@ -122,10 +157,10 @@ 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
+## Not in the gem
 
-- **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.
+- **Cursor pagination for MCP list tools.** `Mcp.paginate` keeps the offset shape MCP clients already parse.
 
 ## Development
 

data/lib/standard_pagination/config.rb

@@ -7,9 +7,12 @@ module StandardPagination
     # Request param a client sets the page size with (when allowed). An Array
     # accepts aliases; the first one the request sends wins.
     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.
+    # Formats for which `paginate` honours the client's page size by default:
+    # an Array of format symbols, or :non_html for every request whose format
+    # isn't HTML. HTML pages keep the size the call site chose.
     attr_accessor :client_limit_formats
+    # Request param `paginate_cursor` reads the cursor from.
+    attr_accessor :cursor_key
     # 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.
@@ -25,6 +28,7 @@ module StandardPagination
       @max_limit = 100
       @limit_key = "limit"
       @client_limit_formats = %i[json]
+      @cursor_key = "cursor"
       @raise_range_error = true
       @tiebreak = true
       @strict_options = nil

data/lib/standard_pagination/controller.rb

@@ -19,6 +19,13 @@ module StandardPagination
       include Pagy::Method
 
       class_attribute :_pagination_error_handling, instance_accessor: false, default: nil
+      # The `client_limit:` default for every `paginate`/`paginate_cursor` in
+      # this controller and its subclasses (true, an Integer cap, or false).
+      # nil falls back to config.client_limit_formats. Set it on an API base
+      # controller, whose clients may send no JSON Accept header at all:
+      #
+      #   self.pagination_client_limit = true
+      class_attribute :pagination_client_limit, instance_accessor: false, default: nil
     end
 
     class_methods do
@@ -92,6 +99,49 @@ module StandardPagination
       StandardPagination.data(pagy)
     end
 
+    # Cursor (keyset) pagination for feeds: no COUNT, no OFFSET, and rows
+    # inserted while a client pages don't shift what it sees. Returns
+    # `[pagy, records]`; send `cursor_data(pagy)` with the records.
+    #
+    # The set must be ordered with hash/symbol orders (`order(created_at:
+    # :desc)`), which pagy turns into the cursor's columns; the primary key
+    # is appended as a tie-breaker so the order is total. The client sends
+    # back `next_cursor` as config.cursor_key (`?cursor=`). `limit:`,
+    # `client_limit:` and `tiebreak:` work as in `paginate`.
+    #
+    # A cursor this didn't issue raises Pagy::OptionError, which
+    # rescue_pagination_errors answers with a 400 (or, for HTML, a redirect
+    # without it).
+    def paginate_cursor(set, limit: nil, client_limit: nil, tiebreak: nil, **options)
+      config = StandardPagination.config
+      tiebreak = config.tiebreak if tiebreak.nil?
+      set = StableOrder.apply(set) if tiebreak
+
+      cursor = params[config.cursor_key]
+      if cursor.present? && !(cursor.is_a?(String) && Pagy::Keyset.decode(cursor).is_a?(Array))
+        raise Pagy::OptionError.new(nil, config.cursor_key.to_sym, "to be a next_cursor value", cursor)
+      end
+
+      pagy(
+        :keyset,
+        set,
+        **options,
+        page_key: config.cursor_key.to_s,
+        limit: resolve_pagination_limit(limit || config.default_limit, client_limit),
+        max_limit: nil,
+        client_limit: nil,
+        client_max_limit: nil
+      )
+    end
+
+    # The cursor envelope's metadata: `{ next_cursor:, has_more: }`.
+    # `next_cursor` is nil on the last page.
+    #
+    #   render json: { data: ..., **cursor_data(pagy) }
+    def cursor_data(pagy)
+      StandardPagination.cursor_data(pagy)
+    end
+
     def resolve_pagination_limit(limit, client_limit)
       cap = pagination_client_limit_cap(client_limit)
       return limit unless cap
@@ -109,6 +159,7 @@ module StandardPagination
     end
 
     def pagination_client_limit_cap(client_limit)
+      client_limit = self.class.pagination_client_limit if client_limit.nil?
       client_limit = pagination_client_limit_format? if client_limit.nil?
 
       case client_limit
@@ -119,7 +170,9 @@ module StandardPagination
 
     def pagination_client_limit_format?
       formats = StandardPagination.config.client_limit_formats
-      formats.any? { |format| request.format.public_send(:"#{format}?") }
+      return !request.format&.html? if formats == :non_html
+
+      Array(formats).any? { |format| request.format.public_send(:"#{format}?") }
     end
 
     def handle_pagination_error(exception)
@@ -150,7 +203,10 @@ module StandardPagination
       if last_page
         query[page_key] = last_page
       else
-        query = query.except((options[:limit_key] || Pagy::DEFAULT[:limit_key]).to_s, *pagination_limit_keys)
+        query = query.except(
+          (options[:limit_key] || Pagy::DEFAULT[:limit_key]).to_s, *pagination_limit_keys,
+          StandardPagination.config.cursor_key.to_s
+        )
         # 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

data/lib/standard_pagination/version.rb

@@ -1,3 +1,3 @@
 module StandardPagination
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/standard_pagination.rb

@@ -38,6 +38,13 @@ module StandardPagination
       pagy.data_hash(data_keys: DATA_KEYS)
     end
 
+    # The one cursor envelope for feeds, alongside the records as `data`:
+    # `{ next_cursor: "<opaque>" | nil, has_more: true | false }`.
+    def cursor_data(pagy)
+      next_cursor = pagy.next
+      { next_cursor:, has_more: !next_cursor.nil? }
+    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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_pagination
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Jaryl Sim