class GraphQL::Pagination::Connection

A Connection wraps a list of items and provides cursor-based pagination over it.

Connections were introduced by Facebook’s Relay front-end framework, but proved to be generally useful for GraphQL APIs. When in doubt, use connections to serve lists (like Arrays, ActiveRecord::Relations) via GraphQL.

Unlike the previous connection implementation, these default to bidirectional pagination.

Pagination arguments and context may be provided at initialization or assigned later (see Schema::Field::ConnectionExtension).

Attributes

after_value [RW]

Raw access to client-provided values. (max_page_size not applied to first or last.)

arguments [RW]

Returns

Hash<Symbol => Object> — The field arguments from the field that returned this connection

before_value [RW]

Raw access to client-provided values. (max_page_size not applied to first or last.)

context [R]

Returns

GraphQL::Query::Context

edge_class [RW]

Returns

Class — A wrapper class for edges of this connection

field [RW]

Returns

GraphQL::Schema::Field — The field this connection was returned by

first [W]

first_value [RW]

Raw access to client-provided values. (max_page_size not applied to first or last.)

items [R]

Returns

Object — A list object, from the application. This is the unpaginated value passed into the connection.

last [W]

last_value [RW]

Raw access to client-provided values. (max_page_size not applied to first or last.)

lookahead [RW]

Returns

GraphQL::Execution::Lookahead Selections on this connection, set by connection fields

parent [RW]

Returns

Object — the object this collection belongs to

was_authorized_by_scope_items [W]

Public Class Methods

Source

# File lib/graphql/pagination/connection.rb, line 107
def initialize(items, parent: nil, field: nil, context: nil, first: nil, after: nil, max_page_size: NOT_CONFIGURED, default_page_size: NOT_CONFIGURED, last: nil, before: nil, edge_class: nil, arguments: nil)
  @items = items
  @parent = parent
  @context = context
  @field = field
  @first_value = first
  @after_value = after
  @last_value = last
  @before_value = before
  @arguments = arguments
  @edge_class = edge_class || self.class.const_get(:Edge)
  # This is only true if the object was _initialized_ with an override
  # or if one is assigned later.
  @has_max_page_size_override = max_page_size != NOT_CONFIGURED
  @max_page_size = if max_page_size == NOT_CONFIGURED
    nil
  else
    max_page_size
  end
  @has_default_page_size_override = default_page_size != NOT_CONFIGURED
  @default_page_size = if default_page_size == NOT_CONFIGURED
    nil
  else
    default_page_size
  end
  @was_authorized_by_scope_items = detect_was_authorized_by_scope_items
end

Parameters

items (Object) — some unpaginated collection item, like an Array or ActiveRecord::Relation
context (Query::Context)
parent (Object) — The object this collection belongs to
first (Integer, nil) — The limit parameter from the client, if it provided one
after (String, nil) — A cursor for pagination, if the client provided one
last (Integer, nil) — Limit parameter from the client, if provided
before (String, nil) — A cursor for pagination, if the client provided one.
arguments (Hash) — The arguments to the field that returned the collection wrapped by this connection
max_page_size (Integer, nil) — A configured value to cap the result size. Applied as first if neither first or last are given and no default_page_size is set.
default_page_size (Integer, nil) — A configured value to determine the result size when neither first or last are given.

Public Instance Methods

after() → String | nil

Source

# File lib/graphql/pagination/connection.rb, line 79
def after
  if defined?(@after)
    @after
  else
    @after = @after_value == "" ? nil : @after_value
  end
end

Returns

String, nil — the client-provided cursor. "" is treated as nil.

before() → String | nil

Source

# File lib/graphql/pagination/connection.rb, line 65
def before
  if defined?(@before)
    @before
  else
    @before = @before_value == "" ? nil : @before_value
  end
end

Returns

String, nil — the client-provided cursor. "" is treated as nil.

context= (new_ctx)

Source

# File lib/graphql/pagination/connection.rb, line 43
def context=(new_ctx)
  @context = new_ctx
  if @was_authorized_by_scope_items.nil?
    @was_authorized_by_scope_items = detect_was_authorized_by_scope_items
  end
  @context
end

cursor_for(Object item) → String

Source

# File lib/graphql/pagination/connection.rb, line 322
def cursor_for(item)
  raise PaginationImplementationMissingError, "Implement #{self.class}#cursor_for(item) to return the cursor for #{item.inspect}"
end

Return a cursor for this item.

Parameters

item (Object) — one of the passed in items, taken from nodes

Returns

String

default_page_size ()

Source

# File lib/graphql/pagination/connection.rb, line 163
def default_page_size
  if @has_default_page_size_override
    @default_page_size
  else
    context.schema.default_page_size
  end
end

default_page_size= (new_value)

Source

# File lib/graphql/pagination/connection.rb, line 158
def default_page_size=(new_value)
  @has_default_page_size_override = true
  @default_page_size = new_value
end

edge_nodes ()

Source

# File lib/graphql/pagination/connection.rb, line 261
def edge_nodes
  nodes
end

A dynamic alias for compatibility with GraphQL::Types::Relay::BaseConnection. Deprecated: use nodes instead

edges() → Array[Edge]

Source

# File lib/graphql/pagination/connection.rb, line 226
def edges
  @edges ||= nodes.each_with_index.map do |n, index|
    edge = @edge_class.new(n, self)
    edge.graphql_connection_position = index
    edge
  end
end

Returns

Array<Edge> — nodes, but wrapped with Edge instances

end_cursor() → String

Source

# File lib/graphql/pagination/connection.rb, line 306
def end_cursor
  nodes.last && cursor_for_position(nodes.last, nodes.length - 1)
end

Returns

String — The cursor of the last item in nodes

first() → Integer | nil

Source

# File lib/graphql/pagination/connection.rb, line 182
def first
  @first ||= begin
    capped = limit_pagination_argument(@first_value, max_page_size)
    if capped.nil? && last.nil?
      capped = limit_pagination_argument(default_page_size, max_page_size) || max_page_size
    end
    capped
  end
end

Returns

Integer, nil — A clamped first value. (The underlying instance variable doesn’t have limits on it.) If neither first nor last is given, but default_page_size is present, default_page_size is used for first. If default_page_size is greater than max_page_size``, it'll be clamped down to max_page_size. If default_page_sizeis nil, usemax_page_size`.

has_default_page_size_override? ()

Source

# File lib/graphql/pagination/connection.rb, line 171
def has_default_page_size_override?
  @has_default_page_size_override
end

has_max_page_size_override? ()

Source

# File lib/graphql/pagination/connection.rb, line 154
def has_max_page_size_override?
  @has_max_page_size_override
end

has_next_page() → bool

Source

# File lib/graphql/pagination/connection.rb, line 276
def has_next_page
  raise PaginationImplementationMissingError, "Implement #{self.class}#has_next_page to return the next-page check"
end

Returns

Boolean — True if there are more items after this page

has_previous_page() → bool

Source

# File lib/graphql/pagination/connection.rb, line 286
def has_previous_page
  raise PaginationImplementationMissingError, "Implement #{self.class}#has_previous_page to return the previous-page check"
end

Returns

Boolean — True if there were items before these items

last() → Integer | nil

Source

# File lib/graphql/pagination/connection.rb, line 216
def last
  @last ||= limit_pagination_argument(@last_value, max_page_size)
end

Returns

Integer, nil — A clamped last value. (The underlying instance variable doesn’t have limits on it)

max_page_size ()

Source

# File lib/graphql/pagination/connection.rb, line 146
def max_page_size
  if @has_max_page_size_override
    @max_page_size
  else
    context.schema.default_max_page_size
  end
end

max_page_size= (new_value)

Source

# File lib/graphql/pagination/connection.rb, line 141
def max_page_size=(new_value)
  @has_max_page_size_override = true
  @max_page_size = new_value
end

nodes() → Array[Object]

Source

# File lib/graphql/pagination/connection.rb, line 255
def nodes
  raise PaginationImplementationMissingError, "Implement #{self.class}#nodes to paginate `@items`"
end

Returns

Array<Object> — A slice of items, constrained by @first_value/@after_value/@last_value/@before_value

page_info ()

Source

# File lib/graphql/pagination/connection.rb, line 266
def page_info
  self
end

The connection object itself implements PageInfo fields

range_add_edge(Object item) → Edge

Source

# File lib/graphql/pagination/connection.rb, line 205
def range_add_edge(item)
  edge_class.new(item, self)
end

This is called by Relay::RangeAdd – it can be overridden when item needs some modifications based on this connection’s state.

Parameters

item (Object) — An item newly added to items

Returns

Edge

start_cursor() → String

Source

# File lib/graphql/pagination/connection.rb, line 296
def start_cursor
  nodes.first && cursor_for_position(nodes.first, 0)
end

Returns

String — The cursor of the first item in nodes

was_authorized_by_scope_items? ()

Source

# File lib/graphql/pagination/connection.rb, line 137
def was_authorized_by_scope_items?
  @was_authorized_by_scope_items
end