Class: GraphQL::Pagination::Connection
- Inherits:
-
Object
- Object
- GraphQL::Pagination::Connection
- Defined in:
- lib/graphql/pagination/connection.rb
Overview
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).
Direct Known Subclasses
Defined Under Namespace
Classes: Edge, PaginationImplementationMissingError
Instance Attribute Summary collapse
-
#after_value ⇒ Object
Raw access to client-provided values.
-
#before_value ⇒ Object
Raw access to client-provided values.
-
#context ⇒ GraphQL::Query::Context
-
#first ⇒ Integer?
A clamped
first
value. -
#first_value ⇒ Object
Raw access to client-provided values.
-
#items ⇒ Object
readonly
A list object, from the application.
-
#last ⇒ Integer?
A clamped
last
value. -
#last_value ⇒ Object
Raw access to client-provided values.
-
#parent ⇒ Object
The object this collection belongs to.
Class Method Summary collapse
-
.edge_class ⇒ Class
The class to use for wrapping items as
edges { ... }
.
Instance Method Summary collapse
-
#after ⇒ String?
The client-provided cursor.
-
#before ⇒ String?
The client-provided cursor.
-
#cursor_for(item) ⇒ String
Return a cursor for this item.
-
#edge_nodes ⇒ Object
deprecated
Deprecated.
use #nodes instead
-
#edges ⇒ Array<Edge>
#nodes, but wrapped with Edge instances.
-
#end_cursor ⇒ String
The cursor of the last item in #nodes.
-
#has_max_page_size_override? ⇒ Boolean
-
#has_next_page ⇒ Boolean
True if there are more items after this page.
-
#has_previous_page ⇒ Boolean
True if there were items before these items.
-
#initialize(items, parent: nil, context: nil, first: nil, after: nil, max_page_size: :not_given, last: nil, before: nil) ⇒ Connection
constructor
A new instance of Connection.
-
#max_page_size ⇒ Object
-
#max_page_size=(new_value) ⇒ Object
-
#nodes ⇒ Array<Object>
A slice of #items, constrained by @first_value/@after_value/@last_value/@before_value.
-
#page_info ⇒ Object
The connection object itself implements
PageInfo
fields. -
#start_cursor ⇒ String
The cursor of the first item in #nodes.
Constructor Details
#initialize(items, parent: nil, context: nil, first: nil, after: nil, max_page_size: :not_given, last: nil, before: nil) ⇒ Connection
Returns a new instance of Connection.
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 |
# File 'lib/graphql/pagination/connection.rb', line 61 def initialize(items, parent: nil, context: nil, first: nil, after: nil, max_page_size: :not_given, last: nil, before: nil) @items = items @parent = parent @context = context @first_value = first @after_value = after @last_value = last @before_value = before # 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_given @max_page_size = if max_page_size == :not_given nil else max_page_size end end |
Instance Attribute Details
#after_value ⇒ Object
Raw access to client-provided values. (max_page_size
not applied to first or last.)
33 34 35 |
# File 'lib/graphql/pagination/connection.rb', line 33 def after_value @after_value end |
#before_value ⇒ Object
Raw access to client-provided values. (max_page_size
not applied to first or last.)
33 34 35 |
# File 'lib/graphql/pagination/connection.rb', line 33 def before_value @before_value end |
#context ⇒ GraphQL::Query::Context
27 28 29 |
# File 'lib/graphql/pagination/connection.rb', line 27 def context @context end |
#first ⇒ Integer?
Returns A clamped first
value.
(The underlying instance variable doesn’t have limits on it.)
If neither first
nor last
is given, but max_page_size
is present, max_page_size is used for first.
102 103 104 105 106 107 108 109 110 |
# File 'lib/graphql/pagination/connection.rb', line 102 def first @first ||= begin capped = limit_pagination_argument(@first_value, max_page_size) if capped.nil? && last.nil? capped = max_page_size end capped end end |
#first_value ⇒ Object
Raw access to client-provided values. (max_page_size
not applied to first or last.)
33 34 35 |
# File 'lib/graphql/pagination/connection.rb', line 33 def first_value @first_value end |
#items ⇒ Object (readonly)
Returns A list object, from the application. This is the unpaginated value passed into the connection.
24 25 26 |
# File 'lib/graphql/pagination/connection.rb', line 24 def items @items end |
#last ⇒ Integer?
Returns A clamped last
value. (The underlying instance variable doesn’t have limits on it).
114 115 116 |
# File 'lib/graphql/pagination/connection.rb', line 114 def last @last ||= limit_pagination_argument(@last_value, max_page_size) end |
#last_value ⇒ Object
Raw access to client-provided values. (max_page_size
not applied to first or last.)
33 34 35 |
# File 'lib/graphql/pagination/connection.rb', line 33 def last_value @last_value end |
#parent ⇒ Object
Returns the object this collection belongs to.
30 31 32 |
# File 'lib/graphql/pagination/connection.rb', line 30 def parent @parent end |
Class Method Details
.edge_class ⇒ Class
Returns The class to use for wrapping items as edges { ... }
. Defaults to Connection::Edge
.
19 20 21 |
# File 'lib/graphql/pagination/connection.rb', line 19 def self.edge_class self::Edge end |
Instance Method Details
#after ⇒ String?
Returns the client-provided cursor. ""
is treated as nil
.
45 46 47 48 49 50 51 |
# File 'lib/graphql/pagination/connection.rb', line 45 def after if defined?(@after) @after else @after = @after_value == "" ? nil : @after_value end end |
#before ⇒ String?
Returns the client-provided cursor. ""
is treated as nil
.
36 37 38 39 40 41 42 |
# File 'lib/graphql/pagination/connection.rb', line 36 def before if defined?(@before) @before else @before = @before_value == "" ? nil : @before_value end end |
#cursor_for(item) ⇒ String
Return a cursor for this item.
162 163 164 |
# File 'lib/graphql/pagination/connection.rb', line 162 def cursor_for(item) raise PaginationImplementationMissingError, "Implement #{self.class}#cursor_for(item) to return the cursor for #{item.inspect}" end |
#edge_nodes ⇒ Object
use #nodes instead
A dynamic alias for compatibility with Relay::BaseConnection.
130 131 132 |
# File 'lib/graphql/pagination/connection.rb', line 130 def edge_nodes nodes end |
#edges ⇒ Array<Edge>
Returns #nodes, but wrapped with Edge instances.
119 120 121 |
# File 'lib/graphql/pagination/connection.rb', line 119 def edges @edges ||= nodes.map { |n| self.class.edge_class.new(n, self) } end |
#end_cursor ⇒ String
Returns The cursor of the last item in #nodes.
155 156 157 |
# File 'lib/graphql/pagination/connection.rb', line 155 def end_cursor nodes.last && cursor_for(nodes.last) end |
#has_max_page_size_override? ⇒ Boolean
93 94 95 |
# File 'lib/graphql/pagination/connection.rb', line 93 def has_max_page_size_override? @has_max_page_size_override end |
#has_next_page ⇒ Boolean
Returns True if there are more items after this page.
140 141 142 |
# File 'lib/graphql/pagination/connection.rb', line 140 def has_next_page raise PaginationImplementationMissingError, "Implement #{self.class}#has_next_page to return the next-page check" end |
#has_previous_page ⇒ Boolean
Returns True if there were items before these items.
145 146 147 |
# File 'lib/graphql/pagination/connection.rb', line 145 def has_previous_page raise PaginationImplementationMissingError, "Implement #{self.class}#has_previous_page to return the previous-page check" end |
#max_page_size ⇒ Object
85 86 87 88 89 90 91 |
# File 'lib/graphql/pagination/connection.rb', line 85 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) ⇒ Object
80 81 82 83 |
# File 'lib/graphql/pagination/connection.rb', line 80 def max_page_size=(new_value) @has_max_page_size_override = true @max_page_size = new_value end |
#nodes ⇒ Array<Object>
Returns A slice of #items, constrained by @first_value/@after_value/@last_value/@before_value.
124 125 126 |
# File 'lib/graphql/pagination/connection.rb', line 124 def nodes raise PaginationImplementationMissingError, "Implement #{self.class}#nodes to paginate `@items`" end |
#page_info ⇒ Object
The connection object itself implements PageInfo
fields
135 136 137 |
# File 'lib/graphql/pagination/connection.rb', line 135 def page_info self end |
#start_cursor ⇒ String
Returns The cursor of the first item in #nodes.
150 151 152 |
# File 'lib/graphql/pagination/connection.rb', line 150 def start_cursor nodes.first && cursor_for(nodes.first) end |