spot-gps 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 13e4a0abb43ad3882974975b75c91103d6d0be42
-  data.tar.gz: 164e08de3895f9d0f2dc8b666e6ba769f34941be
+  metadata.gz: ae8f932cea97f131527f1b2f24b693b21c78bfaa
+  data.tar.gz: 506fa0a9ce404eb350cd8e7847d15b8b0099a49a
 SHA512:
-  metadata.gz: be02344cbfec73c32678b5d16b1829179ee9be435acdf5aa5957e1616152298fd69260f14783089b1b967f6b397af0ef2c528273854fba5d5068e421f049c7ac
-  data.tar.gz: 5c0207c3806fb992c1e7ba0a046442539c906674c886d704d829b4dd2196fa8e82b9b89ea06310dfd378d37ba1065be92ea2f9101a9cc92cf860493903578a0c
+  metadata.gz: c81515b2b992f025958fbbd3de61d9fb06b6cab5d8b48c2e10bfde32d072beb2cb9808c6a6761cd4d2fb5e8f501689715f771d24d98e006872256d8113fac7f9
+  data.tar.gz: daad07e097b8decddb8c78adfd9c95b1804dabb0839108a9e5d0a3c5ca524d3768221b4c1975cc67deb963773f1cb3c196924a5b86f55b382c0b392889eabce4

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## v0.1.0, 10 July 2016
+
+- Move old `all` functionality to `list`
+- Introduce new `all` method, that lazily paginates through all resources
+
 ## v0.0.2, 10 July 2016
 
 - Wrap responses in SPOT::Resources::Message objects, making them easier to work

data/README.md

@@ -41,18 +41,27 @@ Currently, the SPOT API only supports a single `messages` resource.
 Messages are communications sent from a SPOT device.
 
 ```ruby
-api.messages.all     # => Returns a (paginated) list of all messages for a feed
+api.messages.all     # => Returns a lazily paginated list of messages for a feed
+api.messages.list    # => Returns a list of messages for a given page of a feed
 api.messages.latest  # => Returns the most recent message for a feed
 ```
 
 ### Pagination
 
-All resources that support an `all` method also support pagination. By default,
-the first page of 50 records are fetched. To fetch subsequent pages (each of 50
-records), specify a `page`.
+If you want to get all of the records for a given resource type, you can use the
+`#all` method to get a lazily paginated list. `#all` will deal with making extra
+API requests to paginate through all the data for you:
 
 ```ruby
-api.messages.all(page: 2)
+api.messages.all.each { |message| puts message.created_at }
+```
+
+Alternatively, you can use the `#list` method to get a specific page of entries.
+By default, the first page of 50 records are fetched. To fetch subsequent pages
+(each of 50 records), specify a `page`.
+
+```ruby
+api.messages.list(page: 2)
 ```
 
 ### Filtering
@@ -60,7 +69,7 @@ api.messages.all(page: 2)
 The SPOT API supports filtering by date.
 
 ```ruby
-api.messages.all(start_at: '2014-06-01T00:00:00', end_at: '2015-06-01T00:00:00')
+api.messages.list(start_at: '2014-06-01T00:00:00', end_at: '2015-06-01T00:00:00')
 ```
 
 ### Error Handling

data/lib/spot-gps/paginator.rb

@@ -0,0 +1,39 @@
+module SPOT
+  # A class that can take an API LIST query and auto paginate through results
+  class Paginator
+    def initialize(service:, params: {})
+      @service = service
+      @params = (params || {}).dup
+    end
+
+    # Get a lazy enumerable for listing data from the API
+    def enumerator
+      Enumerator.new do |yielder|
+        response = get_initial_response
+
+        loop do
+          items = response.records
+
+          # If there are no records, we're done
+          break if items.empty?
+
+          # Otherwise, iterate through the records...
+          items.each { |item| yielder << item }
+
+          # ...and fetch the next page
+          @params ||= {}
+          @params[:page] ||= 1
+          @params[:page] += 1
+
+          response = @service.list(**@params)
+        end
+      end.lazy
+    end
+
+    private
+
+    def get_initial_response
+      @initial_response ||= @service.list(**@params)
+    end
+  end
+end

data/lib/spot-gps/services/messages.rb

@@ -1,7 +1,18 @@
 module SPOT
   module Services
     class Messages < Base
-      def all(page: nil, start_at: nil, end_at: nil)
+      def all(start_at: nil, end_at: nil)
+        query_params = {}
+        query_params[:startDate] = spot_formatted_time(start_at) if start_at
+        query_params[:endDate] = spot_formatted_time(end_at) if end_at
+
+        SPOT::Paginator.new(
+          service: self,
+          params: query_params
+        ).enumerator
+      end
+
+      def list(page: nil, start_at: nil, end_at: nil)
         query_params = {}
         query_params[:start] = start(page) if page
         query_params[:startDate] = spot_formatted_time(start_at) if start_at

data/lib/spot-gps/version.rb

@@ -1,3 +1,3 @@
 module SPOT
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.1.0'.freeze
 end

data/lib/spot.rb

@@ -7,6 +7,7 @@ require 'spot-gps/client'
 require 'spot-gps/api_response'
 require 'spot-gps/api_service'
 require 'spot-gps/list_response'
+require 'spot-gps/paginator'
 require 'spot-gps/resources/message'
 require 'spot-gps/services/base'
 require 'spot-gps/services/messages'

data/spec/fixtures/message.json

@@ -18,12 +18,12 @@
                     {
                         "@clientUnixTime": "0",
                         "id": 585079373,
-                        "messengerId": "0-2855693",
-                        "messengerName": "Grey's SPOT",
+                        "messengerId": "0-1234567",
+                        "messengerName": "My SPOT",
                         "unixTime": 1468164566,
                         "messageType": "OK",
-                        "latitude": 51.54875,
-                        "longitude": -0.0697,
+                        "latitude": 61.54875,
+                        "longitude": -3.0697,
                         "modelId": "SPOT3",
                         "showCustomMsg": "Y",
                         "dateTime": "2016-07-10T15:29:26+0000",
@@ -33,13 +33,13 @@
                     },
                     {
                         "@clientUnixTime": "0",
-                        "id": 584982167,
-                        "messengerId": "0-2855693",
-                        "messengerName": "Grey's SPOT",
+                        "id": 585079373,
+                        "messengerId": "0-1234567",
+                        "messengerName": "My SPOT",
                         "unixTime": 1468149143,
                         "messageType": "OK",
-                        "latitude": 51.5489,
-                        "longitude": -0.06988,
+                        "latitude": 61.54875,
+                        "longitude": -3.0697,
                         "modelId": "SPOT3",
                         "showCustomMsg": "Y",
                         "dateTime": "2016-07-10T11:12:23+0000",

data/spec/services/messages_spec.rb

@@ -5,6 +5,55 @@ describe SPOT::Services::Messages do
 
   describe "#all" do
     subject(:all) { messages.all(args) }
+    let(:args) { {} }
+
+    it { is_expected.to be_a(Enumerator) }
+
+    context "with records" do
+      before do
+        stub_url = SPOT.endpoint + 'EXAMPLE_ID/message.json'
+        stub_request(:get, stub_url).to_return(
+          body: load_fixture('message.json'),
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+        stub_request(:get, stub_url + "?start=50").to_return(
+          body: load_fixture('message.json'),
+          headers: { 'Content-Type' => 'application/json' }
+        )
+
+        stub_request(:get, stub_url + "?start=100").to_return(
+          body: load_fixture('no_messages.json'),
+          headers: { 'Content-Type' => 'application/json' }
+        )
+      end
+
+      its(:first) { is_expected.to be_a(SPOT::Resources::Message) }
+      its("to_a.length") { is_expected.to eq(4) }
+
+      it "makes the correct number of requests" do
+        all.map(&:created_at).to_a
+        expect(a_request(:get, /#{Regexp.quote(SPOT.endpoint)}/)).
+          to have_been_made.times(3)
+      end
+    end
+
+    context "with no records" do
+      before do
+        stub_url = SPOT.endpoint + 'EXAMPLE_ID/message.json'
+        stub_request(:get, stub_url).to_return(
+          body: load_fixture('no_messages.json'),
+          headers: { 'Content-Type' => 'application/json' }
+        )
+      end
+
+      its(:first) { is_expected.to eq(nil) }
+      its("to_a.length") { is_expected.to eq(0) }
+    end
+  end
+
+  describe "#list" do
+    subject(:list) { messages.list(args) }
 
     before do
       stub_url = SPOT.endpoint + 'EXAMPLE_ID/message.json'
@@ -14,7 +63,6 @@ describe SPOT::Services::Messages do
       )
     end
 
-
     context "without any arguments" do
       let(:args) { {} }
 
@@ -24,7 +72,7 @@ describe SPOT::Services::Messages do
           with(path: 'message.json', params: {}).
           and_call_original
 
-        messages.all
+        messages.list
       end
 
       it { is_expected.to be_a(SPOT::ListResponse) }
@@ -47,12 +95,12 @@ describe SPOT::Services::Messages do
     context "with a page parameter" do
       context "that is invalid" do
         let(:args) { { page: "invalid" } }
-        specify { expect { all }.to raise_error(ArgumentError) }
+        specify { expect { list }.to raise_error(ArgumentError) }
       end
 
       context "that is zero" do
         let(:args) { { page: 0 } }
-        specify { expect { all }.to raise_error(ArgumentError) }
+        specify { expect { list }.to raise_error(ArgumentError) }
       end
 
       context "that is greater than zero" do
@@ -64,7 +112,7 @@ describe SPOT::Services::Messages do
             with(path: 'message.json', params: { start: 0 }).
             and_call_original
 
-          all
+          list
         end
 
         context "and greater than 1" do
@@ -76,7 +124,7 @@ describe SPOT::Services::Messages do
               with(path: 'message.json', params: { start: 50 }).
               and_call_original
 
-            all
+            list
           end
         end
       end
@@ -85,7 +133,7 @@ describe SPOT::Services::Messages do
     context "with a start_at or end_at parameter" do
       context "that is invalid" do
         let(:args) { { start_at: "invalid" } }
-        specify { expect { all }.to raise_error(ArgumentError) }
+        specify { expect { list }.to raise_error(ArgumentError) }
       end
 
       context "that is a valid string" do
@@ -99,7 +147,7 @@ describe SPOT::Services::Messages do
                            endDate: '2016-02-01T00:00:00-0000' }).
             and_call_original
 
-          all
+          list
         end
       end
 
@@ -113,7 +161,7 @@ describe SPOT::Services::Messages do
                  params: { startDate: '2016-01-01T00:00:00-0000' }).
             and_call_original
 
-          all
+          list
         end
       end
 
@@ -127,7 +175,7 @@ describe SPOT::Services::Messages do
                  params: { startDate: '2016-01-01T00:00:00-0000' }).
             and_call_original
 
-          all
+          list
         end
       end
 
@@ -141,7 +189,7 @@ describe SPOT::Services::Messages do
                  params: { startDate: '2016-01-01T00:00:00-0000' }).
             and_call_original
 
-          all
+          list
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spot-gps
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Grey Baker
@@ -89,6 +89,7 @@ files:
 - lib/spot-gps/client.rb
 - lib/spot-gps/configuration.rb
 - lib/spot-gps/list_response.rb
+- lib/spot-gps/paginator.rb
 - lib/spot-gps/resources/message.rb
 - lib/spot-gps/services/base.rb
 - lib/spot-gps/services/messages.rb