Revert to immediately retrieved collections by default

Closes #460

Introduce both the `config.active_resource.lazy_collections`
configuration, as well as the `Base.lazy_collections` class attribute.

Restore the original behavior of immediately retrieving collections by
defaulting the initial value to `false`, but deprecate the behavior and
encourage migrating to setting the value to `true`.

Author: seanpdoyle

README.md

@@ -192,6 +192,29 @@ people = Person.where(last_name: "Durden")
 people.first  # => <Person::xxx 'first_name' => 'Tyler' ...>
 ```
 
+Collections are retrieved immediately by default. To defer the loading of the
+records until their first access, set `Base.lazy_collections = true`:
+
+```ruby
+Person.lazy_collections = true
+
+# Builds a lazy collection with an initial filter
+people = Person.where(first_name: "Tyler")
+
+# Modifies the lazy collection with an additional filter
+people = people.where(last_name: "Durden")
+
+# Expects a response of
+#
+# [
+#   {"id":1,"first_name":"Tyler","last_name":"Durden"},
+# ]
+#
+# for GET http://api.people.com:3000/people.json?first_name=Tyler&last_name=Durden
+
+people.first  # => <Person::xxx 'first_name' => 'Tyler' ...>
+```
+
 ### Create
 
 Creating a new resource submits the JSON form of the resource as the body of the request and expects

lib/active_resource/base.rb

@@ -380,6 +380,8 @@ def self.logger=(logger)
     class_attribute :connection_class
     self.connection_class = Connection
 
+    class_attribute :lazy_collections, instance_accessor: false, default: false
+
     class << self
       include ThreadsafeAttributes
       threadsafe_attribute :_headers, :_connection, :_user, :_password, :_bearer_token, :_site, :_proxy
@@ -1126,7 +1128,18 @@ def last(*args)
       # This is an alias for find(:all). You can pass in all the same
       # arguments to this method as you can to <tt>find(:all)</tt>
       def all(*args)
-        WhereClause.new(self, *args)
+        if lazy_collections
+          WhereClause.new(self, *args)
+        else
+          ActiveResource.deprecator.warn(<<~MSG)
+            In the next Active Resource release, calling ActiveResource::Base#all will defer the http request submission
+            until the collection is used.
+            To fix this warning, ensure your code doesn't rely on eagerly loading collection and
+            remove the `ActiveResource::Base.lazy_collections` flag from your configuration.
+          MSG
+
+          find(:all, *args)
+        end
       end
 
       # This is an alias for all. You can pass in all the same

lib/active_resource/railtie.rb

@@ -8,6 +8,7 @@ class Railtie < Rails::Railtie
     config.eager_load_namespaces << ActiveResource
 
     config.active_resource = ActiveSupport::OrderedOptions.new
+    config.active_resource.lazy_collections = false
 
     initializer "active_resource.set_configs" do |app|
       ActiveSupport.on_load(:active_resource) do

test/cases/finder_test.rb

@@ -61,6 +61,22 @@ def test_all
     assert_equal "David", all.last.name
   end
 
+  def test_all_immediately_finds_by_default
+    assert_deprecated(/defer the http request submission/, ActiveResource.deprecator) do
+      Person.all
+    end
+
+    request, *other_requests = ActiveResource::HttpMock.requests
+    assert_equal "/people.json", request.path
+    assert_empty other_requests
+  end
+
+  def test_all_with_lazy_collections
+    DeferredPerson.all
+
+    assert_empty ActiveResource::HttpMock.requests
+  end
+
   def test_all_with_params
     all = StreetAddress.all(params: { person_id: 1 })
     assert_equal 1, all.size
@@ -84,7 +100,7 @@ def test_where_with_clauses
   def test_where_with_multiple_where_clauses
     ActiveResource::HttpMock.respond_to.get "/people.json?id=2&name=david", {}, @people_david
 
-    people = Person.where(id: 2).where(name: "david")
+    people = DeferredPerson.where(id: 2).where(name: "david")
     assert_equal 1, people.size
     assert_kind_of Person, people.first
     assert_equal 2, people.first.id
@@ -94,7 +110,7 @@ def test_where_with_multiple_where_clauses
   def test_where_chained_from_all
     ActiveResource::HttpMock.respond_to.get "/records.json?id=2", {}, @people_david
 
-    people = Person.all(from: "/records.json").where(id: 2)
+    people = DeferredPerson.all(from: "/records.json").where(id: 2)
     assert_equal 1, people.size
     assert_kind_of Person, people.first
     assert_equal 2, people.first.id
@@ -104,7 +120,7 @@ def test_where_chained_from_all
   def test_where_with_chained_into_all
     ActiveResource::HttpMock.respond_to.get "/records.json?id=2&name=david", {}, @people_david
 
-    people = Person.where(id: 2).all(from: "/records.json", params: { name: "david" })
+    people = DeferredPerson.where(id: 2).all(from: "/records.json", params: { name: "david" })
     assert_equal 1, people.size
     assert_kind_of Person, people.first
     assert_equal 2, people.first.id
@@ -113,7 +129,7 @@ def test_where_with_chained_into_all
 
   def test_where_loading
     ActiveResource::HttpMock.respond_to.get "/people.json?id=2", {}, @people_david
-    people = Person.where(id: 2)
+    people = DeferredPerson.where(id: 2)
 
     assert_changes -> { ActiveResource::HttpMock.requests.count }, from: 0, to: 1 do
       people.load
@@ -125,7 +141,7 @@ def test_where_loading
 
   def test_where_reloading
     ActiveResource::HttpMock.respond_to.get "/people.json?id=2", {}, @people_david
-    people = Person.where(id: 2)
+    people = DeferredPerson.where(id: 2)
 
     assert_changes -> { ActiveResource::HttpMock.requests.count }, from: 0, to: 1 do
       assert_equal 1, people.size

test/cases/notifications_test.rb

@@ -15,7 +15,7 @@ def setup
   end
 
   def test_get_request_with_params
-    payload = capture_notifications { Person.where(name: "Matz").load }
+    payload = capture_notifications { Person.where(name: "Matz") }
 
     assert_equal :get, payload[:method]
     assert_equal "http://37s.sunrise.i:3000/people.json?name=Matz", payload[:request_uri]

test/fixtures/person.rb

@@ -4,6 +4,11 @@ class Person < ActiveResource::Base
   self.site = "http://37s.sunrise.i:3000"
 end
 
+class DeferredPerson < Person
+  self.element_name = "person"
+  self.lazy_collections = true
+end
+
 module External
   class Person < ActiveResource::Base
     self.site = "http://atq.caffeine.intoxication.it"