lib/ably/models/paginated_result.rb in ably-1.2.2 vs lib/ably/models/paginated_result.rb in ably-1.2.3

- old
+ new

@@ -1,18 +1,20 @@ module Ably::Models - # Wraps any Ably HTTP response that supports paging and provides methods to iterate through - # the pages using {#first}, {#next}, {#has_next?} and {#last?} + # Contains a page of results for message or presence history, stats, or REST presence requests. + # A PaginatedResult response from a REST API paginated query is also accompanied by metadata + # that indicates the relative queries available to the PaginatedResult object. # - # All items in the HTTP response are available in the Array returned from {#items} - # - # Paging information is provided by Ably in the LINK HTTP headers - # class PaginatedResult include Ably::Modules::AsyncWrapper if defined?(Ably::Realtime) - # The items contained within this {PaginatedResult} + # Contains the current page of results; for example, an array of {Ably::Models::Message} or {Ably::Models::PresenceMessage} objects + # for a channel history request. + # + # @spec TG3 + # # @return [Array] + # attr_reader :items # @param [Faraday::Response] http_response Initial HTTP response from an Ably request to a paged resource # @param [String] base_url Base URL for request that generated the http_response so that subsequent paged requests can be made # @param [Client] client {Ably::Client} used to make the request to Ably @@ -20,10 +22,11 @@ # @option options [Symbol,String] :coerce_into symbol or string representing class that should be used to create each item in the PaginatedResult # # @yield [Object] block will be called for each resource object for the current page. This is a useful way to apply a transformation to any page resources after they are retrieved # # @return [PaginatedResult] + # def initialize(http_response, base_url, client, options = {}, &each_block) @http_response = http_response @client = client @base_url = "#{base_url.gsub(%r{/[^/]*$}, '')}/" @coerce_into = options[:coerce_into] @@ -39,51 +42,63 @@ @items = coerce_items_into(items, @coerce_into) if @coerce_into @items = items.map { |item| yield item } if block_given? end - # Retrieve the first page of results. - # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object, - # and allows an optional success callback block to be provided. + # Returns a new PaginatedResult for the first page of results. # - # @return [PaginatedResult,Ably::Util::SafeDeferrable] + # @spec TG5 + # + # @return [PaginatedResult, Ably::Util::SafeDeferrable] + # def first(&success_callback) async_wrap_if_realtime(success_callback) do return nil unless supports_pagination? PaginatedResult.new(client.get(pagination_url('first')), base_url, client, pagination_options, &each_block) end end # Retrieve the next page of results. + # # When used as part of the {Ably::Realtime} library, it will return a {Ably::Util::SafeDeferrable} object, - # and allows an optional success callback block to be provided. + # and allows an optional success callback block to be provided. # + # @spec TG4 + # # @return [PaginatedResult,Ably::Util::SafeDeferrable] + # def next(&success_callback) async_wrap_if_realtime(success_callback) do return nil unless has_next? PaginatedResult.new(client.get(pagination_url('next')), base_url, client, pagination_options, &each_block) end end - # True if this is the last page in the paged resource set + # Returns true if this page is the last page and returns false if there are more pages available by calling next available. # + # @spec TG7 + # # @return [Boolean] + # def last? !supports_pagination? || pagination_header('next').nil? end - # True if there is a subsequent page in this paginated set available with {#next} + # Returns true if there are more pages available by calling next and returns false if this page is the last page available. # + # @spec TG6 + # # @return [Boolean] + # def has_next? supports_pagination? && !last? end # True if the HTTP response supports paging with the expected LINK HTTP headers # # @return [Boolean] + # def supports_pagination? !pagination_headers.empty? end def inspect