Class: Uploadcare::Collections::Paginated

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/uploadcare/collections/paginated.rb

Overview

Paginated collection for API list responses.

Wraps paginated API responses and provides methods for navigating between pages. Implements Enumerable for easy iteration over resources.

Examples:

Iterating over resources

files = client.files.list
files.each { |file| puts file.uuid }

Navigating pages

files = client.files.list
while files
  files.each { |file| process(file) }
  files = files.next_page
end

Fetching all resources

all_files = client.files.list.all

Direct Known Subclasses

FileSearchResult

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(params = {}) ⇒ Paginated

Initialize a new Paginated collection.

Parameters:

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

    Collection parameters

Options Hash (params):

  • :resources (Array) —

    Array of resource objects

  • :next_page (String, nil) —

    URL for next page

  • :previous_page (String, nil) —

    URL for previous page

  • :per_page (Integer) —

    Items per page

  • :total (Integer) —

    Total item count

  • :api_client (Object) —

    API client for fetching pages

  • :resource_class (Class) —

    Class for instantiating resources

  • :client (Uploadcare::Client, nil) —

    Client for resources

  • :request_options (Hash) —

    Request options for subsequent page fetches



65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/uploadcare/collections/paginated.rb', line 65

def initialize(params = {})
  @resources = params[:resources] || []
  @next_page_url = params[:next_page]
  @previous_page_url = params[:previous_page]
  @per_page = params[:per_page]
  @total = params[:total]
  @api_client = params[:api_client]
  @resource_class = params[:resource_class]
  @client = params[:client]
  @request_options = params[:request_options] || {}
end

Instance Attribute Details

#api_client ⇒ Object (readonly)

Returns API endpoint client for fetching additional pages.

Returns:

  • (Object) —

    API endpoint client for fetching additional pages



42
43
44
 
# File 'lib/uploadcare/collections/paginated.rb', line 42

def api_client
  @api_client
end

#client ⇒ Uploadcare::Client? (readonly)

Returns Client for resource instantiation.

Returns:



48
49
50
 
# File 'lib/uploadcare/collections/paginated.rb', line 48

def client
  @client
end

#next_page_url ⇒ String? (readonly)

Returns URL for the next page, or nil if on last page.

Returns:

  • (String, nil) —

    URL for the next page, or nil if on last page



30
31
32
 
# File 'lib/uploadcare/collections/paginated.rb', line 30

def next_page_url
  @next_page_url
end

#per_page ⇒ Integer (readonly)

Returns Number of items per page.

Returns:

  • (Integer) —

    Number of items per page



36
37
38
 
# File 'lib/uploadcare/collections/paginated.rb', line 36

def per_page
  @per_page
end

#previous_page_url ⇒ String? (readonly)

Returns URL for the previous page, or nil if on first page.

Returns:

  • (String, nil) —

    URL for the previous page, or nil if on first page



33
34
35
 
# File 'lib/uploadcare/collections/paginated.rb', line 33

def previous_page_url
  @previous_page_url
end

#request_options ⇒ Hash (readonly)

Returns Request options used when fetching pages.

Returns:

  • (Hash) —

    Request options used when fetching pages



51
52
53
 
# File 'lib/uploadcare/collections/paginated.rb', line 51

def request_options
  @request_options
end

#resource_class ⇒ Class (readonly)

Returns Resource class for instantiating items from raw data.

Returns:

  • (Class) —

    Resource class for instantiating items from raw data



45
46
47
 
# File 'lib/uploadcare/collections/paginated.rb', line 45

def resource_class
  @resource_class
end

#resources ⇒ Array (readonly)

Returns Array of resource objects in the current page.

Returns:

  • (Array) —

    Array of resource objects in the current page



27
28
29
 
# File 'lib/uploadcare/collections/paginated.rb', line 27

def resources
  @resources
end

#total ⇒ Integer (readonly)

Returns Total number of items across all pages.

Returns:

  • (Integer) —

    Total number of items across all pages



39
40
41
 
# File 'lib/uploadcare/collections/paginated.rb', line 39

def total
  @total
end

Instance Method Details

#all(limit: nil) ⇒ Array<Object>

Fetch all resources across all pages.

Parameters:

  • limit (Integer, nil) (defaults to: nil) —

    Maximum number of resources to return

Returns:

  • (Array<Object>) —

    All resources up to the requested limit



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/uploadcare/collections/paginated.rb', line 103

def all(limit: nil)
  return [] if limit && limit <= 0

  collection = self
  items = []
  remaining = limit

  while collection
    page_items = collection.resources || []
    if remaining
      page_slice = page_items.first(remaining)
      items.concat(page_slice)
      remaining -= page_slice.length
      break if remaining <= 0
    else
      items.concat(page_items)
    end

    collection = collection.next_page
  end

  items
end

#each {|resource| ... } ⇒ Object

Iterate over resources in the current page.

Yields:

  • (resource) —

    Block to execute for each resource

Yield Parameters:

  • resource (Object) —

    A resource object



81
82
83
 
# File 'lib/uploadcare/collections/paginated.rb', line 81

def each(&)
  @resources.each(&)
end

#next_page ⇒ Uploadcare::Collections::Paginated?

Fetch the next page of resources.

Returns:

  • (Uploadcare::Collections::Paginated, nil) —

    Next page, or nil if on last page



88
89
90
 
# File 'lib/uploadcare/collections/paginated.rb', line 88

def next_page
  fetch_page(@next_page_url)
end

#previous_page ⇒ Uploadcare::Collections::Paginated?

Fetch the previous page of resources.

Returns:

  • (Uploadcare::Collections::Paginated, nil) —

    Previous page, or nil if on first page



95
96
97
 
# File 'lib/uploadcare/collections/paginated.rb', line 95

def previous_page
  fetch_page(@previous_page_url)
end