Class: WebFunction::Page

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/webfunction/page.rb

Overview

A page of results from a paginated endpoint.

Paginated responses follow the Web Function pagination contract: a JSON object with page, next, and previous keys. Request detects this shape and returns a Page instead of a bare Hash. The next and previous values are opaque request bodies — call #next_page or #previous_page to fetch the adjacent page; do not construct or modify them.

See the pagination specification for the full contract.

Examples:

page = WebFunction::Request.execute(
  "https://api.example.com/list-people",
  args: { filters: { first_name: "Joe" } },
)
page.page        # => [{ "person_id" => "...", ... }, ...]
page.next?       # => true
next_page = page.next_page
next_page.previous? # => true

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(page:, next_body:, previous_body:, url:, bearer_auth: nil, version: nil) ⇒ Page

Returns a new instance of Page.



28
29
30
31
32
33
34
35
 
# File 'lib/webfunction/page.rb', line 28

def initialize(page:, next_body:, previous_body:, url:, bearer_auth: nil, version: nil)
  @page = page
  @next_body = next_body
  @previous_body = previous_body
  @url = url
  @bearer_auth = bearer_auth
  @version = version
end

Instance Attribute Details

#page ⇒ Array (readonly)

The items on the current page.

Returns:

  • (Array) 


79
80
81
 
# File 'lib/webfunction/page.rb', line 79

def page
  @page
end

Class Method Details

.paginated?(response) ⇒ Boolean

Whether response matches the paginated response shape.

Parameters:

  • response (Object) —

    A parsed JSON response

Returns:

  • (Boolean) 


44
45
46
47
48
49
50
51
52
 
# File 'lib/webfunction/page.rb', line 44

def paginated?(response)
  response.is_a?(Hash) &&
    response.key?("page") &&
    response.key?("next") &&
    response.key?("previous") &&
    response["page"].is_a?(Array) &&
    (response["next"].nil? || response["next"].is_a?(Hash)) &&
    (response["previous"].nil? || response["previous"].is_a?(Hash))
end

.wrap(response, request:) ⇒ Page, Object

Wraps a paginated response in a WebFunction::Page, or returns response unchanged.

Parameters:

  • response (Object) —

    A parsed JSON response

  • request (Request) —

    The request that produced the response

Returns:



61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/webfunction/page.rb', line 61

def wrap(response, request:)
  return response unless paginated?(response)

  new(
    page: response["page"],
    next_body: response["next"],
    previous_body: response["previous"],
    url: request.url,
    bearer_auth: request.bearer_auth,
    version: request.version,
  )
end

Instance Method Details

#each {|Object| ... } ⇒ Enumerator, Page

Iterates over the items on the current page.

Yields:

  • (Object) —

    Each item in #page

Returns:

  • (Enumerator, Page) 


119
120
121
122
123
124
 
# File 'lib/webfunction/page.rb', line 119

def each(&block)
  return enum_for(:each) unless block

  @page.each(&block)
  self
end

#next? ⇒ Boolean

Whether a next page is available.

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/webfunction/page.rb', line 85

def next?
  !@next_body.nil?
end

#next_page ⇒ Page?

Fetches the next page by posting the opaque next body to the same endpoint.

Returns:

  • (Page, nil) —

    The next page, or nil if there is none



101
102
103
 
# File 'lib/webfunction/page.rb', line 101

def next_page
  fetch(@next_body)
end

#previous? ⇒ Boolean

Whether a previous page is available.

Returns:

  • (Boolean) 


93
94
95
 
# File 'lib/webfunction/page.rb', line 93

def previous?
  !@previous_body.nil?
end

#previous_page ⇒ Page?

Fetches the previous page by posting the opaque previous body to the same endpoint.

Returns:

  • (Page, nil) —

    The previous page, or nil if there is none



109
110
111
 
# File 'lib/webfunction/page.rb', line 109

def previous_page
  fetch(@previous_body)
end