Class: Oz::CursorPage

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/oz/cursor_page.rb

Overview

An Enumerable page of results from a cursor-paginated endpoint (currently GET /agent/runs).

Iterate a single page directly, or use #auto_paging_each to transparently walk every page:

page = client.agent.runs.list(limit: 50, state: ["INPROGRESS"])
page.each { |run| puts run.run_id }          # this page only
page.auto_paging_each { |run| ... }           # every page
page.next_page if page.next_page?

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(body, resource:, params: {}, items_key: 'runs') ⇒ CursorPage

Returns a new instance of CursorPage.

Parameters:

  • body (Hash) —

    decoded { “runs” => […], “page_info” => {…} }

  • resource (#list) —

    the resource used to fetch subsequent pages

  • params (Hash) (defaults to: {}) —

    the filter params used for this request

  • items_key (String) (defaults to: 'runs') —

    the key under which items live in body



30
31
32
33
34
35
36
37
38
39
 
# File 'lib/oz/cursor_page.rb', line 30

def initialize(body, resource:, params: {}, items_key: 'runs')
  @raw = body.is_a?(Hash) ? body : {}
  @resource = resource
  @params = params || {}
  @items_key = items_key
  @data = Array(@raw[items_key]).map { |item| Model.build(item) }
  page_info = @raw['page_info'] || {}
  @has_next_page = page_info['has_next_page']
  @next_cursor = page_info['next_cursor']
end

Instance Attribute Details

#data ⇒ Array<Oz::Model> (readonly)

Returns the items on this page.

Returns:

  • (Array<Oz::Model>) —

    the items on this page.



18
19
20
 
# File 'lib/oz/cursor_page.rb', line 18

def data
  @data
end

#has_next_page ⇒ Boolean? (readonly)

Returns server hint on whether more pages exist.

Returns:

  • (Boolean, nil) —

    server hint on whether more pages exist.



20
21
22
 
# File 'lib/oz/cursor_page.rb', line 20

def has_next_page
  @has_next_page
end

#next_cursor ⇒ String? (readonly)

Returns cursor to fetch the next page.

Returns:

  • (String, nil) —

    cursor to fetch the next page.



22
23
24
 
# File 'lib/oz/cursor_page.rb', line 22

def next_cursor
  @next_cursor
end

#raw ⇒ Hash (readonly)

Returns the raw decoded response body.

Returns:

  • (Hash) —

    the raw decoded response body.



24
25
26
 
# File 'lib/oz/cursor_page.rb', line 24

def raw
  @raw
end

Instance Method Details

#auto_paging_each(&block) ⇒ Object

Iterates over every item across all pages, fetching them lazily. Returns an Enumerator when no block is given.



66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/oz/cursor_page.rb', line 66

def auto_paging_each(&block)
  return enum_for(:auto_paging_each) unless block_given?

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

    page = page.next_page
  end
end

#each ⇒ Object

Iterates over the items on this page only.



42
43
44
45
46
 
# File 'lib/oz/cursor_page.rb', line 42

def each(&)
  return enum_for(:each) unless block_given?

  @data.each(&)
end

#empty? ⇒ Boolean

Returns whether this page has no items.

Returns:

  • (Boolean) —

    whether this page has no items.



79
80
81
 
# File 'lib/oz/cursor_page.rb', line 79

def empty?
  @data.empty?
end

#next_page ⇒ CursorPage

Fetches the next page, reusing the original filters with the new cursor.

Returns:

Raises:



58
59
60
61
62
 
# File 'lib/oz/cursor_page.rb', line 58

def next_page
  raise Oz::Error, 'No next page available' unless next_page?

  @resource.list(**@params, cursor: @next_cursor)
end

#next_page? ⇒ Boolean

Returns whether a further page can be fetched.

Returns:

  • (Boolean) —

    whether a further page can be fetched.



49
50
51
52
53
 
# File 'lib/oz/cursor_page.rb', line 49

def next_page?
  return false if @has_next_page == false

  !(@next_cursor.nil? || @next_cursor.to_s.empty?)
end

#size ⇒ Integer Also known as: length

Returns number of items on this page.

Returns:

  • (Integer) —

    number of items on this page.



84
85
86
 
# File 'lib/oz/cursor_page.rb', line 84

def size
  @data.size
end