Class: WorkOS::Types::ListStruct

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/workos/types/list_struct.rb

Overview

Paginated response wrapper with auto-pagination support.

result = @client.organizations.list_organizations(limit: 10)
result.data              # => [WorkOS::Organization, ...]
result.list_metadata     # => { "before" => nil, "after" => "org_..." }
result.auto_paging_each { |org| puts org.id }

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data:, list_metadata:, fetch_next: nil, fetch_previous: nil, filters: {}) ⇒ ListStruct

Returns a new instance of ListStruct.



17
18
19
20
21
22
23
 
# File 'lib/workos/types/list_struct.rb', line 17

def initialize(data:, list_metadata:, fetch_next: nil, fetch_previous: nil, filters: {})
  @data = data || []
  @list_metadata = list_metadata || {}
  @fetch_next = fetch_next
  @fetch_previous = fetch_previous
  @filters = filters
end

Instance Attribute Details

#data ⇒ Object

Returns the value of attribute data.



15
16
17
 
# File 'lib/workos/types/list_struct.rb', line 15

def data
  @data
end

#fetch_next ⇒ Object

Returns the value of attribute fetch_next.



15
16
17
 
# File 'lib/workos/types/list_struct.rb', line 15

def fetch_next
  @fetch_next
end

#fetch_previous ⇒ Object

Returns the value of attribute fetch_previous.



15
16
17
 
# File 'lib/workos/types/list_struct.rb', line 15

def fetch_previous
  @fetch_previous
end

#filters ⇒ Object

Returns the value of attribute filters.



15
16
17
 
# File 'lib/workos/types/list_struct.rb', line 15

def filters
  @filters
end

#last_response ⇒ Object

Returns the value of attribute last_response.



15
16
17
 
# File 'lib/workos/types/list_struct.rb', line 15

def last_response
  @last_response
end

#list_metadata ⇒ Object

Returns the value of attribute list_metadata.



15
16
17
 
# File 'lib/workos/types/list_struct.rb', line 15

def list_metadata
  @list_metadata
end

Class Method Details

.from_response(response, model: nil, filters: {}, fetch_next: nil, fetch_previous: nil) ⇒ ListStruct

Build a ListStruct from a raw HTTP response, mapping items through an optional model class and wiring cursor-based auto-pagination.

Parameters:

  • response (Net::HTTPResponse) —

    Raw HTTP response with JSON body. model.new accepts a JSON String or a Hash (see BaseModel.normalize).

  • model (Class, nil) (defaults to: nil) —

    Model class whose .new accepts a Hash. When nil, items are returned as raw Hashes.

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

    Filter state forwarded to the next page.

  • fetch_next (Proc, nil) (defaults to: nil) —

    Proc called to fetch the next page given the current page's after cursor.

  • fetch_previous (Proc, nil) (defaults to: nil) —

    Proc called to fetch the previous page given the current page's before cursor.

Returns:



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/workos/types/list_struct.rb', line 38

def self.from_response(response, model: nil, filters: {}, fetch_next: nil, fetch_previous: nil)
  parsed = JSON.parse(response.body)
  items = parsed["data"] || []
  items = items.map { |item| model.new(item) } if model
  result = new(
    data: items,
    list_metadata: parsed["list_metadata"],
    filters: filters,
    fetch_next: fetch_next,
    fetch_previous: fetch_previous
  )
  result.last_response = ApiResponse.new(
    http_status: response.code.to_i,
    http_headers: response.each_header.to_h,
    request_id: response["x-request-id"]
  )
  result
end

Instance Method Details

#auto_paging_each ⇒ Object

Iterate over every item across pages.

Requires a fetch_next proc wired at construction time. The generator emits this automatically for list endpoints whose spec includes a cursor pagination parameter.



96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/workos/types/list_struct.rb', line 96

def auto_paging_each
  return enum_for(:auto_paging_each) unless block_given?

  page = self
  loop do
    page.data.each { |item| yield item }
    next_page = page.next_page
    break if next_page.nil?
    break unless next_page.is_a?(ListStruct)
    break if next_page.data.nil? || next_page.data.empty?

    page = next_page
  end
end

#each(&block) ⇒ Enumerator

Iterates the current page only. Use auto_paging_each to span pages.

Returns:

  • (Enumerator) 


60
61
62
 
# File 'lib/workos/types/list_struct.rb', line 60

def each(&block)
  @data.each(&block)
end

#each_page ⇒ Object

Iterate one page at a time across all pages.

result.each_page do |page|
page.data.each { |item| bulk_insert(item) }
end


116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/workos/types/list_struct.rb', line 116

def each_page
  return enum_for(:each_page) unless block_given?

  page = self
  loop do
    yield page
    next_page = page.next_page
    break if next_page.nil?
    break unless next_page.is_a?(ListStruct)
    break if next_page.data.nil? || next_page.data.empty?

    page = next_page
  end
end

#has_more? ⇒ Boolean

Returns:

  • (Boolean) 


64
65
66
67
 
# File 'lib/workos/types/list_struct.rb', line 64

def has_more?
  cursor = @list_metadata.is_a?(Hash) ? (@list_metadata["after"] || @list_metadata[:after]) : nil
  !cursor.nil? && !cursor.to_s.empty?
end

#next_page ⇒ ListStruct?

Fetch the next page when an after cursor is present.

Returns:



72
73
74
75
76
77
78
 
# File 'lib/workos/types/list_struct.rb', line 72

def next_page
  cursor = @list_metadata.is_a?(Hash) ? (@list_metadata["after"] || @list_metadata[:after]) : nil
  return nil if cursor.nil? || cursor.to_s.empty?
  return nil unless @fetch_next

  @fetch_next.call(cursor)
end

#previous_page ⇒ ListStruct?

Fetch the previous page when a before cursor is present.

Returns:



83
84
85
86
87
88
89
 
# File 'lib/workos/types/list_struct.rb', line 83

def previous_page
  cursor = @list_metadata.is_a?(Hash) ? (@list_metadata["before"] || @list_metadata[:before]) : nil
  return nil if cursor.nil? || cursor.to_s.empty?
  return nil unless @fetch_previous

  @fetch_previous.call(cursor)
end