graphql_declarative 0.1.0

data/gemfiles/ar_7.0.gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# AR <= 7.0 requires sqlite3 ~> 1.4, so this file declares dependencies directly
+# instead of using `gemspec`, whose dev dependency pins sqlite3 ~> 2.0.
+source "https://rubygems.org"
+gem "graphql_declarative", path: ".."
+gem "activerecord", "~> 7.0.0"
+gem "sqlite3", "~> 1.4"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.13"

data/gemfiles/ar_7.1.gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+gemspec path: ".."
+gem "activerecord", "~> 7.1.0"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.13"

data/gemfiles/ar_7.2.gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+gemspec path: ".."
+gem "activerecord", "~> 7.2.0"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.13"

data/gemfiles/ar_8.0.gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+gemspec path: ".."
+gem "activerecord", "~> 8.0.0"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.13"

data/lib/graphql_declarative/cursor.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "base64"
+require "bigdecimal"
+require "date"
+require "json"
+require "time"
+
+module GraphqlDeclarative
+  # Opaque keyset cursors. Encode the tuple (sort_value, id) — never the offset,
+  # and never the sort value alone, or ties silently drop records.
+  #
+  #   Cursor.encode(sort_value: "Ruby 101", id: 42)
+  #   Cursor.decode("eyJzIjoiUnVieSAxMDEiLCJpZCI6NDJ9")
+  #
+  # Seek predicate for ASC:  (sort_col, id) > (sort_value, id)
+  # Emulate row-value comparison where the adapter lacks it:
+  #   sort_col > :s OR (sort_col = :s AND id > :id)
+  #
+  # The payload is JSON `{"v" => sort_value, "i" => id}` in urlsafe, unpadded
+  # Base64. That encoding is an implementation detail: it is opaque to clients
+  # by contract and is not documented as stable.
+  class Cursor
+    KEY_VALUE = "v"
+    KEY_ID = "i"
+
+    # Fractional-second digits kept when a Time is serialised. A datetime that
+    # round-trips through `to_s` loses everything after the second, and two rows
+    # created in the same second then compare equal to the cursor: the seek
+    # `created_at > :v` drops the second one, or `>=` would repeat the first.
+    # Nine digits is more than any supported adapter stores.
+    TIME_PRECISION = 9
+
+    # @param sort_value [Object] the value of the sort column for this row
+    # @param id [Object] the row's primary key
+    # @return [String] urlsafe, unpadded Base64
+    def self.encode(sort_value:, id:)
+      payload = {KEY_VALUE => serialize(sort_value), KEY_ID => id}
+      Base64.urlsafe_encode64(JSON.generate(payload), padding: false)
+    end
+
+    # @param str [String] a cursor produced by .encode
+    # @param type [ActiveModel::Type::Value, Symbol, nil] the type of the sort
+    #   column, used to cast the decoded value back. Pass
+    #   `model.type_for_attribute(sort_column)` — without it a datetime comes
+    #   back as the ISO8601 String it was encoded as, and comparing a String
+    #   against a datetime column is adapter-dependent nonsense.
+    # @return [Hash] {sort_value:, id:}
+    # @raise [Error] on anything malformed. A bad cursor is never silently
+    #   treated as "start from the beginning": the client would be handed page 1
+    #   while believing it was on page 7, and would never notice.
+    def self.decode(str, type: nil)
+      raise Error, "cursor is missing" if str.nil? || str.to_s.empty?
+
+      payload = parse(str)
+      unless payload.is_a?(Hash) && payload.key?(KEY_VALUE) && payload.key?(KEY_ID)
+        raise Error, "malformed cursor: expected keys #{KEY_VALUE.inspect} and #{KEY_ID.inspect}"
+      end
+
+      id = payload[KEY_ID]
+      raise Error, "malformed cursor: missing id" if id.nil?
+
+      {sort_value: cast(payload[KEY_VALUE], type), id: id}
+    end
+
+    # Builds the seek predicate. Portable form, because SQLite's row-value
+    # support is version-dependent and MySQL's optimiser treats row-value
+    # comparisons differently again:
+    #
+    #   ASC:   sort_col > :v OR (sort_col = :v AND id > :i)
+    #   DESC:  sort_col < :v OR (sort_col = :v AND id < :i)
+    #
+    # Both halves flip together for DESC — the tiebreaker has to run the same
+    # way as the sort column or the tied rows come back in the wrong order and
+    # the page walks backwards through them.
+    #
+    # @param scope [ActiveRecord::Relation, Class]
+    # @param column [Symbol, String] sort column, from the `sortable_by`
+    #   whitelist only — never from user input (SPEC.md §7).
+    # @param direction [Symbol] :asc or :desc
+    # @param sort_value [Object] value half of the cursor
+    # @param id [Object] id half of the cursor
+    # @return [ActiveRecord::Relation]
+    def self.seek(scope, column:, direction:, sort_value:, id:)
+      direction = direction.to_s.downcase.to_sym
+      unless %i[asc desc].include?(direction)
+        raise Error, "seek direction must be :asc or :desc, got #{direction.inspect}"
+      end
+
+      model = scope.respond_to?(:klass) ? scope.klass : scope
+      column = column.to_sym
+      unless model.column_names.include?(column.to_s)
+        raise Error, "cannot seek on #{column.inspect}: #{model.name} has no such column"
+      end
+
+      if sort_value.nil?
+        # NULL never compares true, so every row after this one would be lost.
+        # v0.1.0 requires sortable columns to be NOT NULL (SPEC.md §6.4); this
+        # is where that requirement stops being silent.
+        raise Error,
+          "cannot seek on a NULL #{column} value: keyset pagination requires the sort column " \
+          "to be NOT NULL in v0.1.0 (a NULL never compares true, so the remaining rows vanish)."
+      end
+
+      table = model.arel_table
+      sort_col = table[column]
+      id_col = table[model.primary_key]
+
+      value_bind = bind(model, column, sort_value)
+      id_bind = bind(model, model.primary_key, id)
+
+      tie = ->(node) { Arel::Nodes::Grouping.new(sort_col.eq(value_bind).and(node)) }
+
+      predicate =
+        if direction == :asc
+          sort_col.gt(value_bind).or(tie.call(id_col.gt(id_bind)))
+        else
+          sort_col.lt(value_bind).or(tie.call(id_col.lt(id_bind)))
+        end
+
+      scope.where(predicate)
+    end
+
+    # Values are bind parameters, always — the column half of the predicate is
+    # an Arel attribute built from a whitelisted name, and the value half never
+    # reaches the SQL string. The QueryAttribute also type-casts, so an ISO8601
+    # String from a cursor is written to the wire exactly the way the column's
+    # own value was.
+    def self.bind(model, column, value)
+      type = model.type_for_attribute(column.to_s)
+      attribute = ActiveRecord::Relation::QueryAttribute.new(column.to_s, value, type)
+      Arel::Nodes::BindParam.new(attribute)
+    end
+    private_class_method :bind
+
+    def self.parse(str)
+      json = Base64.urlsafe_decode64(str.to_s)
+      JSON.parse(json)
+    rescue ArgumentError, JSON::ParserError => e
+      raise Error, "malformed cursor: #{e.message}"
+    end
+    private_class_method :parse
+
+    # Times are serialised at full precision rather than left to JSON, which
+    # would call #to_s and truncate to the second. BigDecimal likewise: JSON
+    # renders it as a String already, but "0.1e2" is not what comes back out of
+    # a decimal column.
+    def self.serialize(value)
+      case value
+      when Time, DateTime
+        value.to_time.iso8601(TIME_PRECISION)
+      when Date
+        value.iso8601
+      when BigDecimal
+        value.to_s("F")
+      else
+        value
+      end
+    end
+    private_class_method :serialize
+
+    # `type` may be an ActiveModel type object (anything responding to #cast) or
+    # a symbol looked up in ActiveRecord's type registry.
+    def self.cast(value, type)
+      return value if value.nil? || type.nil?
+      return type.cast(value) if type.respond_to?(:cast)
+
+      ActiveRecord::Type.lookup(type.to_sym).cast(value)
+    rescue ArgumentError, TypeError => e
+      raise Error, "malformed cursor: cannot cast #{value.inspect} (#{e.message})"
+    end
+    private_class_method :cast
+  end
+end

data/lib/graphql_declarative/filter.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module GraphqlDeclarative
+  # Applies a FilterInput's arguments to an ActiveRecord scope.
+  #
+  # THE IMPORTANT PART — see spec/pagination_through_associations_spec.rb.
+  # Filters declared with `through:` MUST NOT be applied as a join on the scope
+  # being paginated. Resolve them to an id subquery instead:
+  #
+  #   ids = model.joins(through).where(assoc_table => {column => value}).select(:id)
+  #   scope.where(id: ids)
+  #
+  # The base relation then stays un-joined, so LIMIT, ORDER BY and cursors all
+  # remain correct. Two `through:` filters on the same association must
+  # intersect within ONE subquery, not chain two (that changes the meaning from
+  # "one child matching both" to "children matching each").
+  #
+  # Chosen semantic, stated once so it is not rediscovered by accident:
+  # ONE CHILD ROW MUST SATISFY ALL PREDICATES DECLARED FOR THAT ASSOCIATION.
+  class Filter
+    # Ops that compare with a LIKE pattern. The pattern is built here, from a
+    # sanitized value, and passed as a bound/quoted node — never spliced into
+    # SQL text.
+    LIKE_PATTERNS = {
+      contains: ->(v) { "%#{v}%" },
+      starts_with: ->(v) { "#{v}%" },
+      ends_with: ->(v) { "%#{v}" }
+    }.freeze
+
+    # LIKE's own metacharacters are escaped so a user-supplied "100%" means the
+    # literal string, not "100 followed by anything". `ESCAPE '\'` is emitted
+    # explicitly because only MySQL assumes backslash by default.
+    LIKE_ESCAPE = "\\"
+
+    class << self
+      # scope        - ActiveRecord::Relation (or a model class)
+      # filter_class - a GraphqlDeclarative::FilterInput subclass
+      # args         - the `filter:` input, as a Hash with symbol keys, a
+      #                GraphQL::Schema::InputObject, or nil
+      def apply(scope, filter_class, args)
+        args = normalize_args(args)
+        relation = scope.respond_to?(:all) ? scope.all : scope
+        return relation if args.empty?
+
+        model = relation.klass
+        index = argument_index(filter_class)
+
+        direct = []
+        # Keyed by association name so that every predicate on one association
+        # ends up in the SAME subquery. This grouping IS the semantic.
+        through = Hash.new { |h, k| h[k] = [] }
+
+        args.each do |key, value|
+          definition, op = index[key.to_sym]
+          unless definition
+            raise Error, "unknown filter argument #{key.inspect} for #{filter_class}; " \
+                         "known arguments: #{index.keys.sort.inspect}"
+          end
+          # A key that was not supplied is absent from the hash; an explicit nil
+          # is treated as "not filtering on this", not as `IS NULL`.
+          next if value.nil?
+
+          (definition.through ? through[definition.through] : direct) << [definition, op, value]
+        end
+
+        relation = apply_direct(relation, model, direct)
+        apply_through(relation, model, through)
+      end
+
+      private
+
+      def normalize_args(args)
+        return {} if args.nil?
+        return args if args.is_a?(Hash)
+        return args.to_h if args.respond_to?(:to_h)
+
+        raise Error, "filter args must be a Hash or nil, got #{args.class}"
+      end
+
+      # {argument_name => [Definition, op]} — the reverse of the naming table in
+      # SPEC.md section 4. Built from `definitions` only, so every column and
+      # association identifier below is declaration-derived.
+      def argument_index(filter_class)
+        unless filter_class.respond_to?(:definitions)
+          raise Error, "#{filter_class} is not a GraphqlDeclarative::FilterInput"
+        end
+
+        filter_class.definitions.each_with_object({}) do |(name, definition), index|
+          definition.ops.each do |op|
+            index[FilterInput.argument_name_for(name, op)] = [definition, op]
+          end
+        end
+      end
+
+      def apply_direct(relation, model, entries)
+        entries.reduce(relation) do |rel, (definition, op, value)|
+          rel.where(predicate(model.arel_table, definition.column, op, value))
+        end
+      end
+
+      # One subquery per association, never a join on `relation` itself.
+      def apply_through(relation, model, grouped)
+        grouped.reduce(relation) do |rel, (association, entries)|
+          reflection = model.reflect_on_association(association)
+          unless reflection
+            raise Error, "#{model} has no association #{association.inspect} " \
+                         "(declared as `through:` on filter #{entries.first[0].name.inspect})"
+          end
+
+          assoc_table = reflection.klass.arel_table
+
+          # Build the subquery on the bare model. It may be joined freely: it
+          # projects ids, so duplicate rows collapse inside `IN (...)` and never
+          # reach the paginated relation.
+          subquery = entries.reduce(model.joins(association)) do |sub, (definition, op, value)|
+            sub.where(predicate(assoc_table, definition.column, op, value))
+          end
+
+          key = model.primary_key
+          rel.where(key => subquery.select(model.arel_table[key]))
+        end
+      end
+
+      # Column identifiers come from the Definition; values go through Arel's
+      # quoted/typecast nodes. There is no string interpolation of SQL here.
+      def predicate(table, column, op, value)
+        attribute = table[column]
+
+        case op
+        when :eq then attribute.eq(value)
+        when :in then attribute.in(Array(value))
+        when :gt then attribute.gt(value)
+        when :gte then attribute.gteq(value)
+        when :lt then attribute.lt(value)
+        when :lte then attribute.lteq(value)
+        when :contains, :starts_with, :ends_with
+          pattern = LIKE_PATTERNS.fetch(op).call(sanitize_like(value))
+          # case_sensitive: true keeps this a plain LIKE on PostgreSQL too,
+          # instead of Arel's default ILIKE.
+          attribute.matches(pattern, Arel::Nodes.build_quoted(LIKE_ESCAPE), true)
+        else
+          raise Error, "unsupported filter op #{op.inspect}"
+        end
+      end
+
+      def sanitize_like(value)
+        ActiveRecord::Base.sanitize_sql_like(value.to_s, LIKE_ESCAPE)
+      end
+    end
+  end
+end

data/lib/graphql_declarative/filter_input.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module GraphqlDeclarative
+  # A GraphQL::Schema::InputObject built from `filter` declarations.
+  #
+  #   class Types::CourseFilter < GraphqlDeclarative::FilterInput
+  #     filter :title,       :string,   ops: [:eq, :contains, :starts_with]
+  #     filter :published,   :boolean
+  #     filter :created_at,  :datetime, ops: [:gte, :lte]
+  #     filter :author_name, :string,   through: :author, column: :name
+  #   end
+  #
+  # Each (name, op) pair generates one argument: :title_contains, :created_at_gte.
+  # `:eq` generates the bare name (:title), not :title_eq.
+  #
+  # The registry (`definitions`) is what `Filter.apply` reads back at request
+  # time. It is the ONLY source of column and association identifiers — nothing
+  # in the SQL layer is ever derived from user input. See SPEC.md section 7.
+  class FilterInput < GraphQL::Schema::InputObject
+    DEFAULT_OPS = {
+      string: %i[eq contains starts_with ends_with in],
+      integer: %i[eq gt gte lt lte in],
+      float: %i[eq gt gte lt lte],
+      boolean: %i[eq],
+      datetime: %i[eq gt gte lt lte]
+    }.freeze
+
+    # The GraphQL scalar each declared type maps to. `:in` wraps this in a list
+    # and the LIKE ops (contains/starts_with/ends_with) override it to String.
+    GRAPHQL_TYPES = {
+      string: GraphQL::Types::String,
+      integer: GraphQL::Types::Int,
+      float: GraphQL::Types::Float,
+      boolean: GraphQL::Types::Boolean,
+      datetime: GraphQL::Types::ISO8601DateTime
+    }.freeze
+
+    Definition = Struct.new(:name, :type, :ops, :through, :column, keyword_init: true)
+
+    class << self
+      # Declare one filterable attribute and generate one argument per op.
+      #
+      # Everything here fails loudly at class-definition time (SPEC.md 6.1):
+      # an unknown type or an op that makes no sense for the type is a boot
+      # error, never a per-request surprise.
+      def filter(name, type, ops: nil, through: nil, column: nil)
+        name = name.to_sym
+        type = type.to_sym
+
+        valid_ops = DEFAULT_OPS[type]
+        unless valid_ops
+          raise Error, "unknown filter type #{type.inspect} for filter #{name.inspect}; " \
+                       "expected one of #{DEFAULT_OPS.keys.inspect}"
+        end
+
+        ops = Array(ops || valid_ops).map(&:to_sym)
+        raise Error, "filter #{name.inspect} declares an empty ops list" if ops.empty?
+
+        invalid = ops - valid_ops
+        unless invalid.empty?
+          raise Error, "invalid op(s) #{invalid.inspect} for #{type} filter #{name.inspect}; " \
+                       "valid ops for #{type} are #{valid_ops.inspect}"
+        end
+
+        definition = Definition.new(
+          name: name,
+          type: type,
+          ops: ops.freeze,
+          through: through&.to_sym,
+          # `column:` defaults to the filter name; for a `through:` filter it is
+          # the column on the ASSOCIATION's table, not on the base model.
+          column: (column || name).to_sym
+        )
+
+        own_definitions[name] = definition
+
+        ops.each do |op|
+          argument(argument_name_for(name, op), graphql_type_for(type, op), required: false)
+        end
+
+        definition
+      end
+
+      # {Symbol => Definition}. Inheritance-safe: walking `superclass` on every
+      # read means a subclass sees its parent's declarations without ever
+      # holding (or mutating) the parent's hash. Adding a filter to the parent
+      # after the subclass exists is picked up too.
+      def definitions
+        if superclass.respond_to?(:definitions)
+          superclass.definitions.merge(own_definitions)
+        else
+          own_definitions.dup
+        end
+      end
+
+      # Declarations made directly on this class, excluding inherited ones.
+      def own_definitions
+        @own_definitions ||= {}
+      end
+
+      # The argument naming table from SPEC.md section 4. `:eq` is the bare
+      # name — `title`, never `title_eq`.
+      def argument_name_for(name, op)
+        (op.to_sym == :eq) ? name.to_sym : :"#{name}_#{op}"
+      end
+
+      private
+
+      def graphql_type_for(type, op)
+        base =
+          case op
+          when :contains, :starts_with, :ends_with then GraphQL::Types::String
+          else GRAPHQL_TYPES.fetch(type)
+          end
+
+        (op == :in) ? [base] : base
+      end
+    end
+  end
+end

data/lib/graphql_declarative/keyset_connection.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module GraphqlDeclarative
+  # Returned directly from Resolver#resolve — graphql-ruby uses a Connection
+  # instance as-is instead of re-wrapping it.
+  #
+  # Unlike GraphQL::Pagination::RelationConnection, whose #cursor_for encodes an
+  # OFFSET (relation_connection.rb:47), this encodes the key tuple
+  # (sort_value, id). Offset cursors shift whenever a row is inserted or deleted
+  # before the current page, so pages repeat or skip records. See SPEC.md §6.5
+  # and spec/stability_spec.rb.
+  #
+  # has_next_page comes from fetching page_size + 1 rows, never from COUNT.
+  # has_previous_page is always false in v0.1.0 (forward-only). Documented, not hidden.
+  #
+  # Construction (see SPEC.md §5 for where this sits in the pipeline):
+  #
+  #   KeysetConnection.new(
+  #     scope,                       # filtered + sorted + seeked, NOT limited
+  #     sort_column: :created_at,    # the column Sort ordered by; :id by default
+  #     sort_direction: :asc,        # recorded for callers; not used to query here
+  #     preloader: ->(records) { GraphqlDeclarative::Preloader... },
+  #     first: args[:first], after: args[:after], context: context,
+  #     default_page_size: 25, max_page_size: 100
+  #   )
+  #
+  # The `after:` seek is applied by the caller *before* the relation gets here:
+  # the seek predicate belongs with Sort (SPEC.md §5, invariant 2). This class
+  # never re-applies it.
+  #
+  # `items` may be either:
+  #   * an ActiveRecord::Relation — this class applies LIMIT page_size + 1,
+  #     loads it, trims to page_size, and only then runs `preloader`. That order
+  #     is invariant 1 in SPEC.md §5: preloading an unbounded relation preloads
+  #     the whole filtered set.
+  #   * an Array the caller already bounded to page_size + 1 rows (use
+  #     .page_size_for to compute the same limit) — it is trimmed here, and
+  #     `preloader` is still applied if given.
+  class KeysetConnection < GraphQL::Pagination::Connection
+    # Fallbacks used only when neither an explicit override nor a schema-level
+    # setting is available (e.g. a connection built outside a query).
+    DEFAULT_PAGE_SIZE = 25
+    MAX_PAGE_SIZE = 100
+
+    # @return [Symbol] the column the relation is ordered by; also the value
+    #   half of every cursor this connection issues.
+    attr_reader :sort_column
+
+    # @return [Symbol] :asc or :desc — the direction the relation was sorted in.
+    #   Carried so a caller can round-trip it; the seek itself happens upstream.
+    attr_reader :sort_direction
+
+    def initialize(items, sort_column: :id, sort_direction: :asc, preloader: nil, **kwargs)
+      @sort_column = sort_column.to_sym
+      @sort_direction = sort_direction.to_sym
+      @preloader = preloader
+      super(items, **kwargs)
+    end
+
+    # The limit a caller must use if it wants to fetch the page itself:
+    # page_size + 1 rows, where the +1 is what makes has_next_page free.
+    #
+    # `first: 0` returns an empty page (Relay-conformant); only a negative
+    # `first:` is an error. The subtlety this class must not repeat: clamping a
+    # negative to 0 would let `load_page` fetch 1 row, report `has_next_page:
+    # true` off it, and trim `nodes` to `[]` — a page with no rows and no
+    # cursor, since `endCursor` is nil when `nodes` is empty. graphql-ruby's own
+    # RelationConnection avoids the whole question because `Connection#first`
+    # clamps through `limit_pagination_argument`; this class bypasses that by
+    # reading `first_value` (the raw, unclamped value) directly, so it validates
+    # the bound itself.
+    def self.page_size_for(first: nil, default_page_size: nil, max_page_size: nil)
+      # The Relay Cursor Connections spec treats first: 0 as valid — an empty
+      # page — and only a negative value as an error, so this returns 0 rather
+      # than raising. Note what that means: load_page fetches page_size + 1 == 1
+      # row, so hasNextPage is true whenever any row matches, with no endCursor
+      # to advance from. That is Relay-conformant, and a client that loops on
+      # hasNextPage while asking for first: 0 will not progress — but that is
+      # the client asking for no rows, not the connection misreporting.
+      if first&.negative?
+        raise GraphQL::ExecutionError,
+          "first: must not be negative (got #{first.inspect}). Omit first: to use the default " \
+          "page size."
+      end
+      return 0 if first == 0
+
+      requested = first || default_page_size || DEFAULT_PAGE_SIZE
+      max = max_page_size || MAX_PAGE_SIZE
+      [requested, max].min
+    end
+
+    # [first || default_page_size, max_page_size].min. A `first:` above
+    # max_page_size is clamped, not an error (SPEC.md §6.5).
+    def page_size
+      @page_size ||= self.class.page_size_for(
+        first: first_value,
+        default_page_size: configured_default_page_size,
+        max_page_size: configured_max_page_size
+      )
+    end
+
+    def nodes
+      load_page
+      @nodes
+    end
+
+    # True iff the LIMIT page_size + 1 query came back with the extra row.
+    # No COUNT — an unbounded count on a filtered set is the thing this avoids.
+    def has_next_page # rubocop:disable Naming/PredicateName
+      load_page
+      @has_next_page
+    end
+
+    # Forward-only in v0.1.0 (SPEC.md §3). Stated, not hidden: a client that
+    # walks forward never needs it, and honouring it would double the cursor
+    # logic for `last:`/`before:`.
+    def has_previous_page # rubocop:disable Naming/PredicateName
+      false
+    end
+
+    # The whole point of the class. RelationConnection encodes an offset here;
+    # this encodes the key tuple, so the cursor keeps meaning the same row even
+    # when rows are inserted or deleted before the current page.
+    def cursor_for(item)
+      Cursor.encode(sort_value: sort_value_for(item), id: item.id)
+    end
+
+    private
+
+    def load_page
+      return if defined?(@nodes)
+
+      fetched = fetch(page_size + 1)
+      @has_next_page = fetched.size > page_size
+      # first(page_size) also copes with a caller that handed us a longer array.
+      @nodes = @has_next_page ? fetched.first(page_size) : fetched
+      apply_preloader(@nodes)
+      @nodes
+    end
+
+    # LIMIT page_size + 1. The extra row is never returned; its existence is the
+    # has_next_page answer.
+    def fetch(limit)
+      if items.is_a?(Array)
+        items.first(limit)
+      elsif items.respond_to?(:limit)
+        items.limit(limit).to_a
+      else
+        items.first(limit).to_a
+      end
+    end
+
+    # Preloading runs here — after the page is bounded — never on `items`.
+    def apply_preloader(records)
+      return records if @preloader.nil? || records.empty?
+
+      @preloader.call(records)
+      records
+    end
+
+    def sort_value_for(item)
+      if item.respond_to?(:[])
+        item[sort_column]
+      else
+        item.public_send(sort_column)
+      end
+    end
+
+    # The base class reads default/max page size off `context.schema` when no
+    # override was given; `context` is nil for a connection built outside a
+    # query, so fall back to the documented defaults instead of blowing up.
+    def configured_default_page_size
+      value = default_page_size if has_default_page_size_override? || context
+      value || DEFAULT_PAGE_SIZE
+    end
+
+    def configured_max_page_size
+      value = max_page_size if has_max_page_size_override? || context
+      value || MAX_PAGE_SIZE
+    end
+  end
+end