Class: Nombaone::Page

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Enumerable[Nombaone::NombaObject]
Defined in:
lib/nombaone/pagination.rb,
sig/nombaone/pagination.rbs

Overview

One page of a list result, plus everything needed to keep going. A Page is Enumerable: iterating it (each, map, select, first(n), …) walks every item across every following page, fetching each next page lazily as you go — so list.first(3) stops after one page.

For a single page, read #data; for page-by-page control, use #next_page / #next_page? or #each_page.

Examples:

Every item, cursors handled for you

nombaone.customers.list.each { |customer| puts customer.email }

Just this page

page = nombaone.invoices.list(status: "open", limit: 50)
page.data              # => [<Invoice>, …]
page.next_cursor       # => "…" or nil

Manual paging

page = page.next_page if page.next_page?

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(fetcher:, query:, result:) ⇒ Page

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Page.



31
32
33
34
35
36
37
38
 
# File 'lib/nombaone/pagination.rb', line 31

def initialize(fetcher:, query:, result:)
  @fetcher = fetcher
  @query = query || {}
  @data = Array(result.data).map { |item| item.is_a?(Hash) ? NombaObject.new(item) : item }
  @page = result.pagination || { limit: @data.length, has_more: false, next_cursor: nil }
  @request_id = result.request_id
  @response = result.response
end

Instance Attribute Details

#data ⇒ Array<NombaObject> (readonly)

Returns the items on this page.

Returns:



26
27
28
 
# File 'lib/nombaone/pagination.rb', line 26

def data
  @data
end

#request_id ⇒ String? (readonly)

Returns the request id of the fetch that produced this page.

Returns:

  • (String, nil) —

    the request id of the fetch that produced this page.



28
29
30
 
# File 'lib/nombaone/pagination.rb', line 28

def request_id
  @request_id
end

Instance Method Details

#each ⇒ self #each ⇒ Enumerator[Nombaone::NombaObject, self] Also known as: auto_paging_each

Iterate every item across this and all following pages. Without a block, returns an Enumerator (so the whole Enumerable toolbox works and stays lazy — each only fetches the next page when the current one is drained).

Overloads:

Yields:

Yield Parameters:

Yield Returns:

  • (void)

Returns:

  • (Enumerator, self) 


85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/nombaone/pagination.rb', line 85

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

  page = self
  loop do
    page.data.each(&block)
    break unless page.next_page?

    page = page.next_page
  end
  self
end

#each_page ⇒ self #each_page ⇒ Enumerator[Nombaone::Page, self]

Iterate page-by-page (this page first), fetching each next page lazily.

Overloads:

Yields:

Yield Parameters:

Yield Returns:

  • (void)

Returns:

  • (Enumerator, self) 


103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/nombaone/pagination.rb', line 103

def each_page
  return to_enum(:each_page) unless block_given?

  page = self
  loop do
    yield page
    break unless page.next_page?

    page = page.next_page
  end
  self
end

#has_more? ⇒ Boolean

Whether more items exist beyond this page.

Returns:

  • (Boolean) 


46
 
# File 'lib/nombaone/pagination.rb', line 46

def has_more? = @page[:has_more]

#limit ⇒ Integer

The applied page size (1–100; the API default is 20).

Returns:

  • (Integer) 


42
 
# File 'lib/nombaone/pagination.rb', line 42

def limit = @page[:limit]

#next_cursor ⇒ String?

The opaque cursor for the next page, or nil when there is none.

Returns:

  • (String, nil) 


50
 
# File 'lib/nombaone/pagination.rb', line 50

def next_cursor = @page[:next_cursor]

#next_page ⇒ Page

Fetch the next page (same filters, next cursor).

Returns:

Raises:



70
71
72
73
74
75
76
77
 
# File 'lib/nombaone/pagination.rb', line 70

def next_page
  unless next_page?
    raise Error, "No next page available — check next_page? before calling next_page."
  end

  paged_query = @query.merge(cursor: next_cursor)
  Page.new(fetcher: @fetcher, query: paged_query, result: @fetcher.call(paged_query))
end

#next_page? ⇒ Boolean Also known as: has_next_page?

Returns whether #next_page will return another page.

Returns:

  • (Boolean) —

    whether #next_page will return another page.



53
54
55
 
# File 'lib/nombaone/pagination.rb', line 53

def next_page?
  has_more? && !next_cursor.nil?
end

#pagination ⇒ NombaObject

The cursor block as an object: pagination.limit, pagination.has_more, pagination.next_cursor.

Returns:



61
62
63
64
65
 
# File 'lib/nombaone/pagination.rb', line 61

def pagination
  @pagination ||= NombaObject.new(
    { "limit" => limit, "hasMore" => has_more?, "nextCursor" => next_cursor },
  )
end