lhs 21.3.1 → 22.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c43753bff8b039bf6b5b2384333afcc1d09da6c61f1616b06751c7a023e0fbc0
-  data.tar.gz: ee5cd17ace1e7f82fc8a713dc493543e800658bd76909ddb026951d84f31c2df
+  metadata.gz: a749e7862bb20791a4a25fa5fdce92461ebfceaf6e30602c7e600f7342a69806
+  data.tar.gz: eceb2d57d258630583394079f495474320354db45e15c205f66005b570abc448
 SHA512:
-  metadata.gz: 14d9ddf1745b15e1c635060eec564a3e578f31829e24dede722ca5509a1dffeefec3fb0daaeb27c94f3c9854314d41fe9042cccfbd04ca3fdc2bab3a32bb9120
-  data.tar.gz: ac97fc333b97f8492bc519b401b68377af441e398486ceaea183d8b006015b691d1aad9a0f518ebf5367cf4427098d767e96354813da94807021195a38f3e997
+  metadata.gz: 9432edd5f7d4c2d76f873d21bb3e79c2bc54965e64d3a2df7aa8c06f64dbea479274adde5ea4d1f1acf3e128d4cc7af1fa8fb41bc801b6b3629e6ddbf1156667
+  data.tar.gz: 719d291ec00314bf8061cbe72a6abab98e1466a7162dcd174588ffc57823b8509951eb2ed28a4be3d6b6e938bd0791ff26cab9f6d478dd49f50cf28139b3cdbf

data/README.md

@@ -2093,7 +2093,7 @@ In a service-oriented architecture using [hyperlinks](https://en.wikipedia.org/w
 
 When fetching records with LHS, you can specify in advance all the linked resources that you want to include in the results. 
 
-With `includes` or `includes_all` (to enforce fetching all remote objects for paginated endpoints), LHS ensures that all matching and explicitly linked resources are loaded and merged.
+With `includes` LHS ensures that all matching and explicitly linked resources are loaded and merged (even if the linked resources are paginated).
 
 Including linked resources/records is heavily influenced by [https://guides.rubyonrails.org/active_record_querying.html](https://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations) and you should read it to understand this feature in all it's glory.
 
@@ -2112,16 +2112,16 @@ Presence.create(place: { href: Place.href_for(123) })
 POST '/presences' { place: { href: "http://datastore/places/123" } }
 ```
 
-#### Ensure the whole linked collection is included: includes_all
+#### Ensure the whole linked collection is included with includes
 
-In case endpoints are paginated and you are certain that you'll need all objects of a set and not only the first page/batch, use `includes_all`.
+In case endpoints are paginated and you are certain that you'll need all objects of a set and not only the first page/batch, use `includes`.
 
 LHS will ensure that all linked resources are around by loading all pages (parallelized/performance optimized).
 
 ```ruby
 # app/controllers/some_controller.rb
 
-customer = Customer.includes_all(contracts: :products).find(1)
+customer = Customer.includes(contracts: :products).find(1)
 ```
 ```
 > GET https://service.example.com/customers/1
@@ -2148,14 +2148,14 @@ customer.contracts.first.products.first.name # Local Business Card
 
 ```
 
-#### Include the first linked page or single item is included: include
+#### Include only the first linked page of a linked collection: includes_first_page
 
-`includes` includes the first page/response when loading the linked resource. **If the endpoint is paginated, only the first page will be included.**
+`includes_first_page` includes the first page/response when loading the linked resource. **If the endpoint is paginated, only the first page will be included.**
 
 ```ruby
 # app/controllers/some_controller.rb
 
-customer = Customer.includes(contracts: :products).find(1)
+customer = Customer.includes_first_page(contracts: :products).find(1)
 ```
 ```
 > GET https://service.example.com/customers/1
@@ -2179,7 +2179,7 @@ customer.contracts.first.products.first.name # Local Business Card
 
 #### Include various levels of linked data
 
-The method syntax of `includes` and `includes_all`, allows you include hyperlinks stored in deep nested data strutures:
+The method syntax of `includes` allows you include hyperlinks stored in deep nested data strutures:
 
 Some examples:
 
@@ -2199,7 +2199,7 @@ Record.includes(campaign: [:entry, :user])
 
 #### Identify and cast known records when including records
 
-When including linked resources with `includes` or `includes_all`, already defined records and their endpoints and configurations are used to make the requests to fetch the additional data.
+When including linked resources with `includes`, already defined records and their endpoints and configurations are used to make the requests to fetch the additional data.
 
 That also means that options for endpoints of linked resources are applied when requesting those in addition.
 

data/lib/lhs/concerns/record/chainable.rb

@@ -64,11 +64,11 @@ class LHS::Record
         chain
       end
 
-      def includes(*args)
+      def includes_first_page(*args)
         Chain.new(self, Include.new(Chain.unfold(args)))
       end
 
-      def includes_all(*args)
+      def includes(*args)
         chain = Chain.new(self, Include.new(Chain.unfold(args)))
         chain.include_all!(args)
         chain
@@ -259,11 +259,11 @@ class LHS::Record
         push(ErrorHandling.new(error_class => handler))
       end
 
-      def includes(*args)
+      def includes_first_page(*args)
         push(Include.new(Chain.unfold(args)))
       end
 
-      def includes_all(*args)
+      def includes(*args)
         chain = push(Include.new(Chain.unfold(args)))
         chain.include_all!(args)
         chain

data/lib/lhs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LHS
-  VERSION = '21.3.1'
+  VERSION = '22.0.0'
 end

data/spec/item/destroy_spec.rb

@@ -56,7 +56,7 @@ describe LHS::Item do
           .to_return(status: 200, body: data.to_json)
         stub_request(:get, "#{datastore}/v2/restaurants/1")
           .to_return(status: 200, body: { name: 'Casa Ferlin' }.to_json)
-        item = Record.includes(:restaurant).find(1)
+        item = Record.includes_first_page(:restaurant).find(1)
         item.destroy
       end
     end

data/spec/proxy/record_identification_spec.rb

@@ -27,7 +27,7 @@ describe LHS::Proxy do
         .to_return(body: {
           items: [{ review: 'Nice restaurant' }]
         }.to_json)
-      result = Search.where(what: 'Blumen').includes(place: :feedbacks)
+      result = Search.where(what: 'Blumen').includes_first_page(place: :feedbacks)
       expect(result.place.feedbacks).to be_kind_of Feedback
       expect(result.place.feedbacks.first.review).to eq 'Nice restaurant'
     end

data/spec/record/all_spec.rb

@@ -52,7 +52,7 @@ describe LHS::Record do
       end
 
       it 'works in combination with include and includes' do
-        records = Record.includes(:product).includes_all(:options).all(color: 'blue')
+        records = Record.includes_first_page(:product).includes(:options).all(color: 'blue')
         expect(records.length).to eq total
         expect(first_page_request).to have_been_requested.times(1)
         expect(second_page_request).to have_been_requested.times(1)

data/spec/record/endpoints_spec.rb

@@ -88,7 +88,7 @@ describe LHS::Record do
         stub_request(:get, "#{datastore}/products/LBC")
           .to_return(body: { name: 'Local Business Card' }.to_json)
         expect(lambda {
-          Contract.includes(:product).where(entry_id: '123').all.first
+          Contract.includes_first_page(:product).where(entry_id: '123').all.first
         }).not_to raise_error # Multiple base endpoints found
       end
     end

data/spec/record/handle_includes_errors_spec.rb

@@ -25,7 +25,7 @@ describe LHS::Record do
 
   it 'allows to pass error_handling for includes to LHC' do
     handler = ->(_) { return { deleted: true } }
-    record = Record.includes(:other).references(other: { error_handler: { LHC::NotFound => handler } }).find(id: 1)
+    record = Record.includes_first_page(:other).references(other: { error_handler: { LHC::NotFound => handler } }).find(id: 1)
 
     expect(record.other.deleted).to be(true)
   end

data/spec/record/has_many_spec.rb

@@ -112,7 +112,7 @@ describe LHS::Record do
     end
 
     it 'explicit association configuration overrules href class casting' do
-      place = Place.includes(:categories).find(1)
+      place = Place.includes_first_page(:categories).find(1)
       expect(place.categories.first).to be_kind_of NewCategory
       expect(place.categories.first.name).to eq('Pizza')
     end

data/spec/record/has_one_spec.rb

@@ -108,7 +108,7 @@ describe LHS::Record do
     end
 
     it 'explicit association configuration overrules href class casting' do
-      place = Place.includes(:category).find(1)
+      place = Place.includes_first_page(:category).find(1)
       expect(place.category).to be_kind_of NewCategory
       expect(place.category.name).to eq('Pizza')
     end

data/spec/record/includes_first_page_spec.rb

@@ -0,0 +1,727 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+describe LHS::Record do
+  let(:datastore) { 'http://local.ch/v2' }
+  before { LHC.config.placeholder('datastore', datastore) }
+
+  let(:stub_campaign_request) do
+    stub_request(:get, "#{datastore}/content-ads/51dfc5690cf271c375c5a12d")
+      .to_return(body: {
+        'href' => "#{datastore}/content-ads/51dfc5690cf271c375c5a12d",
+        'entry' => { 'href' => "#{datastore}/local-entries/lakj35asdflkj1203va" },
+        'user' => { 'href' => "#{datastore}/users/lakj35asdflkj1203va" }
+      }.to_json)
+  end
+
+  let(:stub_entry_request) do
+    stub_request(:get, "#{datastore}/local-entries/lakj35asdflkj1203va")
+      .to_return(body: { 'name' => 'Casa Ferlin' }.to_json)
+  end
+
+  let(:stub_user_request) do
+    stub_request(:get, "#{datastore}/users/lakj35asdflkj1203va")
+      .to_return(body: { 'name' => 'Mario' }.to_json)
+  end
+
+  context 'singlelevel includes' do
+    before do
+      class LocalEntry < LHS::Record
+        endpoint '{+datastore}/local-entries'
+        endpoint '{+datastore}/local-entries/{id}'
+      end
+      class User < LHS::Record
+        endpoint '{+datastore}/users'
+        endpoint '{+datastore}/users/{id}'
+      end
+      class Favorite < LHS::Record
+        endpoint '{+datastore}/favorites'
+        endpoint '{+datastore}/favorites/{id}'
+      end
+      stub_request(:get, "#{datastore}/local-entries/1")
+        .to_return(body: { company_name: 'local.ch' }.to_json)
+      stub_request(:get, "#{datastore}/users/1")
+        .to_return(body: { name: 'Mario' }.to_json)
+      stub_request(:get, "#{datastore}/favorites/1")
+        .to_return(body: {
+          local_entry: { href: "#{datastore}/local-entries/1" },
+          user: { href: "#{datastore}/users/1" }
+        }.to_json)
+    end
+
+    it 'includes a resource' do
+      favorite = Favorite.includes_first_page(:local_entry).find(1)
+      expect(favorite.local_entry.company_name).to eq 'local.ch'
+    end
+
+    it 'duplicates a class' do
+      expect(Favorite.object_id).not_to eq(Favorite.includes_first_page(:local_entry).object_id)
+    end
+
+    it 'includes a list of resources' do
+      favorite = Favorite.includes_first_page(:local_entry, :user).find(1)
+      expect(favorite.local_entry).to be_kind_of LocalEntry
+      expect(favorite.local_entry.company_name).to eq 'local.ch'
+      expect(favorite.user.name).to eq 'Mario'
+    end
+
+    it 'includes an array of resources' do
+      favorite = Favorite.includes_first_page([:local_entry, :user]).find(1)
+      expect(favorite.local_entry.company_name).to eq 'local.ch'
+      expect(favorite.user.name).to eq 'Mario'
+    end
+  end
+
+  context 'multilevel includes' do
+    before do
+      class Feedback < LHS::Record
+        endpoint '{+datastore}/feedbacks'
+        endpoint '{+datastore}/feedbacks/{id}'
+      end
+      stub_campaign_request
+      stub_entry_request
+      stub_user_request
+    end
+
+    it 'includes linked resources while fetching multiple resources from one service' do
+      stub_request(:get, "#{datastore}/feedbacks?has_reviews=true")
+        .to_return(status: 200, body: {
+          items: [
+            {
+              'href' => "#{datastore}/feedbacks/-Sc4_pYNpqfsudzhtivfkA",
+              'campaign' => { 'href' => "#{datastore}/content-ads/51dfc5690cf271c375c5a12d" }
+            }
+          ]
+        }.to_json)
+
+      feedbacks = Feedback.includes_first_page(campaign: :entry).where(has_reviews: true)
+      expect(feedbacks.first.campaign.entry.name).to eq 'Casa Ferlin'
+    end
+
+    it 'includes linked resources while fetching a single resource from one service' do
+      stub_request(:get, "#{datastore}/feedbacks/123")
+        .to_return(status: 200, body: {
+          'href' => "#{datastore}/feedbacks/-Sc4_pYNpqfsudzhtivfkA",
+          'campaign' => { 'href' => "#{datastore}/content-ads/51dfc5690cf271c375c5a12d" }
+        }.to_json)
+
+      feedbacks = Feedback.includes_first_page(campaign: :entry).find(123)
+      expect(feedbacks.campaign.entry.name).to eq 'Casa Ferlin'
+    end
+
+    it 'includes linked resources with array while fetching a single resource from one service' do
+      stub_request(:get, "#{datastore}/feedbacks/123")
+        .to_return(status: 200, body: {
+          'href' => "#{datastore}/feedbacks/-Sc4_pYNpqfsudzhtivfkA",
+          'campaign' => { 'href' => "#{datastore}/content-ads/51dfc5690cf271c375c5a12d" }
+        }.to_json)
+
+      feedbacks = Feedback.includes_first_page(campaign: [:entry, :user]).find(123)
+      expect(feedbacks.campaign.entry.name).to eq 'Casa Ferlin'
+      expect(feedbacks.campaign.user.name).to eq 'Mario'
+    end
+
+    it 'includes list of linked resources while fetching a single resource from one service' do
+      stub_request(:get, "#{datastore}/feedbacks/123")
+        .to_return(status: 200, body: {
+          'href' => "#{datastore}/feedbacks/-Sc4_pYNpqfsudzhtivfkA",
+          'campaign' => { 'href' => "#{datastore}/content-ads/51dfc5690cf271c375c5a12d" },
+          'user' => { 'href' => "#{datastore}/users/lakj35asdflkj1203va" }
+        }.to_json)
+
+      feedbacks = Feedback.includes_first_page(:user, campaign: [:entry, :user]).find(123)
+      expect(feedbacks.campaign.entry.name).to eq 'Casa Ferlin'
+      expect(feedbacks.campaign.user.name).to eq 'Mario'
+      expect(feedbacks.user.name).to eq 'Mario'
+    end
+
+    context 'include objects from known services' do
+      let(:stub_feedback_request) do
+        stub_request(:get, "#{datastore}/feedbacks")
+          .to_return(status: 200, body: {
+            items: [
+              {
+                'href' => "#{datastore}/feedbacks/-Sc4_pYNpqfsudzhtivfkA",
+                'entry' => {
+                  'href' => "#{datastore}/local-entries/lakj35asdflkj1203va"
+                }
+              }
+            ]
+          }.to_json)
+      end
+
+      let(:interceptor) { spy('interceptor') }
+
+      before do
+        class Entry < LHS::Record
+          endpoint '{+datastore}/local-entries/{id}'
+        end
+        LHC.config.interceptors = [interceptor]
+      end
+
+      it 'uses interceptors for included links from known services' do
+        stub_feedback_request
+        stub_entry_request
+        expect(Feedback.includes_first_page(:entry).where.first.entry.name).to eq 'Casa Ferlin'
+        expect(interceptor).to have_received(:before_request).twice
+      end
+    end
+
+    context 'includes not present in response' do
+      before do
+        class Parent < LHS::Record
+          endpoint '{+datastore}/local-parents'
+          endpoint '{+datastore}/local-parents/{id}'
+        end
+
+        class OptionalChild < LHS::Record
+          endpoint '{+datastore}/local-children/{id}'
+        end
+      end
+
+      it 'handles missing but included fields in single object response' do
+        stub_request(:get, "#{datastore}/local-parents/1")
+          .to_return(status: 200, body: {
+            'href' => "#{datastore}/local-parents/1",
+            'name' => 'RspecName'
+          }.to_json)
+
+        parent = Parent.includes_first_page(:optional_children).find(1)
+        expect(parent).not_to be nil
+        expect(parent.name).to eq 'RspecName'
+        expect(parent.optional_children).to be nil
+      end
+
+      it 'handles missing but included fields in collection response' do
+        stub_request(:get, "#{datastore}/local-parents")
+          .to_return(status: 200, body: {
+            items: [
+              {
+                'href' => "#{datastore}/local-parents/1",
+                'name' => 'RspecParent'
+              }, {
+                'href'           => "#{datastore}/local-parents/2",
+                'name'           => 'RspecParent2',
+                'optional_child' => {
+                  'href' => "#{datastore}/local-children/1"
+                }
+              }
+            ]
+          }.to_json)
+
+        stub_request(:get, "#{datastore}/local-children/1")
+          .to_return(status: 200, body: {
+            href: "#{datastore}/local_children/1",
+            name: 'RspecOptionalChild1'
+          }.to_json)
+
+        child = Parent.includes_first_page(:optional_child).where[1].optional_child
+        expect(child).not_to be nil
+        expect(child.name).to eq 'RspecOptionalChild1'
+      end
+    end
+  end
+
+  context 'links pointing to nowhere' do
+    it 'sets nil for links that cannot be included' do
+      class Feedback < LHS::Record
+        endpoint '{+datastore}/feedbacks'
+        endpoint '{+datastore}/feedbacks/{id}'
+      end
+
+      stub_request(:get, "#{datastore}/feedbacks/123")
+        .to_return(status: 200, body: {
+          'href' => "#{datastore}/feedbacks/-Sc4_pYNpqfsudzhtivfkA",
+          'campaign' => { 'href' => "#{datastore}/content-ads/51dfc5690cf271c375c5a12d" }
+        }.to_json)
+
+      stub_request(:get, "#{datastore}/content-ads/51dfc5690cf271c375c5a12d")
+        .to_return(status: 404)
+
+      feedback = Feedback.includes_first_page(campaign: :entry).find(123)
+      expect(feedback.campaign._raw.keys.count).to eq 1
+      expect(feedback.campaign.href).to be_present
+    end
+  end
+
+  context 'modules' do
+    before do
+      module Services
+        class LocalEntry < LHS::Record
+          endpoint '{+datastore}/local-entries'
+        end
+
+        class Feedback < LHS::Record
+          endpoint '{+datastore}/feedbacks'
+        end
+      end
+      stub_request(:get, "http://local.ch/v2/feedbacks?id=123")
+        .to_return(body: [].to_json)
+    end
+
+    it 'works with modules' do
+      Services::Feedback.includes_first_page(campaign: :entry).find(123)
+    end
+  end
+
+  context 'arrays' do
+    before do
+      class Place < LHS::Record
+        endpoint '{+datastore}/place'
+        endpoint '{+datastore}/place/{id}'
+      end
+    end
+
+    let!(:place_request) do
+      stub_request(:get, "#{datastore}/place/1")
+        .to_return(body: {
+          'relations' => [
+            { 'href' => "#{datastore}/place/relations/2" },
+            { 'href' => "#{datastore}/place/relations/3" }
+          ]
+        }.to_json)
+    end
+
+    let!(:relation_request_1) do
+      stub_request(:get, "#{datastore}/place/relations/2")
+        .to_return(body: { name: 'Category' }.to_json)
+    end
+
+    let!(:relation_request_2) do
+      stub_request(:get, "#{datastore}/place/relations/3")
+        .to_return(body: { name: 'ZeFrank' }.to_json)
+    end
+
+    it 'includes items of arrays' do
+      place = Place.includes_first_page(:relations).find(1)
+      expect(place.relations.first.name).to eq 'Category'
+      expect(place.relations[1].name).to eq 'ZeFrank'
+    end
+
+    context 'parallel with empty links' do
+      let!(:place_request_2) do
+        stub_request(:get, "#{datastore}/place/2")
+          .to_return(body: {
+            'relations' => []
+          }.to_json)
+      end
+
+      it 'loads places in parallel and merges included data properly' do
+        place = Place.includes_first_page(:relations).find(2, 1)
+        expect(place[0].relations.empty?).to be true
+        expect(place[1].relations[0].name).to eq 'Category'
+        expect(place[1].relations[1].name).to eq 'ZeFrank'
+      end
+    end
+  end
+
+  context 'empty collections' do
+    it 'skips including empty collections' do
+      class Place < LHS::Record
+        endpoint '{+datastore}/place'
+        endpoint '{+datastore}/place/{id}'
+      end
+
+      stub_request(:get, "#{datastore}/place/1")
+        .to_return(body: {
+          'available_products' => {
+            "url" => "#{datastore}/place/1/products",
+            "items" => []
+          }
+        }.to_json)
+
+      place = Place.includes_first_page(:available_products).find(1)
+      expect(place.available_products.empty?).to eq true
+    end
+  end
+
+  context 'extend items with arrays' do
+    it 'extends base items with arrays' do
+      class Place < LHS::Record
+        endpoint '{+datastore}/place'
+        endpoint '{+datastore}/place/{id}'
+      end
+
+      stub_request(:get, "#{datastore}/place/1")
+        .to_return(body: {
+          'contracts' => {
+            'items' => [{ 'href' => "#{datastore}/place/1/contacts/1" }]
+          }
+        }.to_json)
+
+      stub_request(:get, "#{datastore}/place/1/contacts/1")
+        .to_return(body: {
+          'products' => { 'href' => "#{datastore}/place/1/contacts/1/products" }
+        }.to_json)
+
+      place = Place.includes_first_page(:contracts).find(1)
+      expect(place.contracts.first.products.href).to eq "#{datastore}/place/1/contacts/1/products"
+    end
+  end
+
+  context 'unexpanded response when requesting the included collection' do
+    before do
+      class Customer < LHS::Record
+        endpoint '{+datastore}/customer/{id}'
+      end
+    end
+
+    let!(:customer_request) do
+      stub_request(:get, "#{datastore}/customer/1")
+        .to_return(body: {
+          places: {
+            href: "#{datastore}/places"
+          }
+        }.to_json)
+    end
+
+    let!(:places_request) do
+      stub_request(:get, "#{datastore}/places")
+        .to_return(body: {
+          items: [{ href: "#{datastore}/places/1" }]
+        }.to_json)
+    end
+
+    let!(:place_request) do
+      stub_request(:get, "#{datastore}/places/1")
+        .to_return(body: {
+          name: 'Casa Ferlin'
+        }.to_json)
+    end
+
+    it 'loads the collection and the single items, if not already expanded' do
+      place = Customer.includes_first_page(:places).find(1).places.first
+      assert_requested(place_request)
+      expect(place.name).to eq 'Casa Ferlin'
+    end
+
+    context 'forwarding options' do
+      let!(:places_request) do
+        stub_request(:get, "#{datastore}/places")
+          .with(headers: { 'Authorization' => 'Bearer 123' })
+          .to_return(
+            body: {
+              items: [{ href: "#{datastore}/places/1" }]
+            }.to_json
+          )
+      end
+
+      let!(:place_request) do
+        stub_request(:get, "#{datastore}/places/1")
+          .with(headers: { 'Authorization' => 'Bearer 123' })
+          .to_return(
+            body: {
+              name: 'Casa Ferlin'
+            }.to_json
+          )
+      end
+
+      it 'forwards options used to expand those unexpanded items' do
+        place = Customer
+          .includes_first_page(:places)
+          .references(places: { headers: { 'Authorization' => 'Bearer 123' } })
+          .find(1)
+          .places.first
+        assert_requested(place_request)
+        expect(place.name).to eq 'Casa Ferlin'
+      end
+    end
+  end
+
+  context 'includes with options' do
+    before do
+      class Customer < LHS::Record
+        endpoint '{+datastore}/customers/{id}'
+        endpoint '{+datastore}/customers'
+      end
+
+      class Place < LHS::Record
+        endpoint '{+datastore}/places'
+      end
+
+      stub_request(:get, "#{datastore}/places?forwarded_params=123")
+        .to_return(body: {
+          'items' => [{ id: 1 }]
+        }.to_json)
+    end
+
+    it 'forwards includes options to requests made for those includes' do
+      stub_request(:get, "#{datastore}/customers/1")
+        .to_return(body: {
+          'places' => {
+            'href' => "#{datastore}/places"
+          }
+        }.to_json)
+      customer = Customer
+        .includes_first_page(:places)
+        .references(places: { params: { forwarded_params: 123 } })
+        .find(1)
+      expect(customer.places.first.id).to eq 1
+    end
+
+    it 'is chain-able' do
+      stub_request(:get, "#{datastore}/customers?name=Steve")
+        .to_return(body: [
+          'places' => {
+            'href' => "#{datastore}/places"
+          }
+        ].to_json)
+      customers = Customer
+        .where(name: 'Steve')
+        .references(places: { params: { forwarded_params: 123 } })
+        .includes_first_page(:places)
+      expect(customers.first.places.first.id).to eq 1
+    end
+  end
+
+  context 'more complex examples' do
+    before do
+      class Place < LHS::Record
+        endpoint 'http://datastore/places/{id}'
+      end
+    end
+
+    it 'forwards complex references' do
+      stub_request(:get, "http://datastore/places/123?limit=1&forwarded_params=for_place")
+        .to_return(body: {
+          'contracts' => {
+            'href' => "http://datastore/places/123/contracts"
+          }
+        }.to_json)
+      stub_request(:get, "http://datastore/places/123/contracts?forwarded_params=for_contracts")
+        .to_return(body: {
+          href: "http://datastore/places/123/contracts?forwarded_params=for_contracts",
+          items: [
+            { product: { 'href' => "http://datastore/products/llo" } }
+          ]
+        }.to_json)
+      stub_request(:get, "http://datastore/products/llo?forwarded_params=for_product")
+        .to_return(body: {
+          'href' => "http://datastore/products/llo",
+          'name' => 'Local Logo'
+        }.to_json)
+      place = Place
+        .options(params: { forwarded_params: 'for_place' })
+        .includes_first_page(contracts: :product)
+        .references(
+          contracts: {
+            params: { forwarded_params: 'for_contracts' },
+            product: { params: { forwarded_params: 'for_product' } }
+          }
+        )
+        .find_by(id: '123')
+      expect(
+        place.contracts.first.product.name
+      ).to eq 'Local Logo'
+    end
+
+    it 'expands empty arrays' do
+      stub_request(:get, "http://datastore/places/123")
+        .to_return(body: {
+          'contracts' => {
+            'href' => "http://datastore/places/123/contracts"
+          }
+        }.to_json)
+      stub_request(:get, "http://datastore/places/123/contracts")
+        .to_return(body: {
+          href: "http://datastore/places/123/contracts",
+          items: []
+        }.to_json)
+      place = Place.includes_first_page(:contracts).find('123')
+      expect(place.contracts.collection?).to eq true
+      expect(
+        place.contracts.as_json
+      ).to eq('href' => 'http://datastore/places/123/contracts', 'items' => [])
+      expect(place.contracts.to_a).to eq([])
+    end
+  end
+
+  context 'include and merge arrays when calling find in parallel' do
+    before do
+      class Place < LHS::Record
+        endpoint 'http://datastore/places/{id}'
+      end
+      stub_request(:get, 'http://datastore/places/1')
+        .to_return(body: {
+          category_relations: [{ href: 'http://datastore/category/1' }, { href: 'http://datastore/category/2' }]
+        }.to_json)
+      stub_request(:get, 'http://datastore/places/2')
+        .to_return(body: {
+          category_relations: [{ href: 'http://datastore/category/2' }, { href: 'http://datastore/category/1' }]
+        }.to_json)
+      stub_request(:get, "http://datastore/category/1").to_return(body: { name: 'Food' }.to_json)
+      stub_request(:get, "http://datastore/category/2").to_return(body: { name: 'Drinks' }.to_json)
+    end
+
+    it 'includes and merges linked resources in case of an array of links' do
+      places = Place
+        .includes_first_page(:category_relations)
+        .find(1, 2)
+      expect(places[0].category_relations[0].name).to eq 'Food'
+      expect(places[1].category_relations[0].name).to eq 'Drinks'
+    end
+  end
+
+  context 'single href with array response' do
+    it 'extends base items with arrays' do
+      class Sector < LHS::Record
+        endpoint '{+datastore}/sectors'
+        endpoint '{+datastore}/sectors/{id}'
+      end
+
+      stub_request(:get, "#{datastore}/sectors")
+        .with(query: hash_including(key: 'my_service'))
+        .to_return(body: [
+          {
+            href: "#{datastore}/sectors/1",
+            services: {
+              href: "#{datastore}/sectors/1/services"
+            },
+            keys: [
+              {
+                key: 'my_service',
+                language: 'de'
+              }
+            ]
+          }
+        ].to_json)
+
+      stub_request(:get, "#{datastore}/sectors/1/services")
+        .to_return(body: [
+          {
+            href: "#{datastore}/services/s1",
+            price_in_cents: 9900,
+            key: 'my_service_service_1'
+          },
+          {
+            href: "#{datastore}/services/s2",
+            price_in_cents: 19900,
+            key: 'my_service_service_2'
+          }
+        ].to_json)
+
+      sector = Sector.includes_first_page(:services).find_by(key: 'my_service')
+      expect(sector.services.length).to eq 2
+      expect(sector.services.first.key).to eq 'my_service_service_1'
+    end
+  end
+
+  context 'include for POST/create' do
+
+    before do
+      class Record < LHS::Record
+        endpoint 'https://records'
+      end
+      stub_request(:post, 'https://records/')
+        .with(body: { color: 'blue' }.to_json)
+        .to_return(
+          body: {
+            color: 'blue',
+            alternative_categories: [
+              { href: 'https://categories/blue' }
+            ]
+          }.to_json
+        )
+      stub_request(:get, 'https://categories/blue')
+        .to_return(
+          body: {
+            name: 'blue'
+          }.to_json
+        )
+    end
+
+    it 'includes the resources from the post response' do
+      records = Record.includes_first_page(:alternative_categories).create(color: 'blue')
+      expect(records.alternative_categories.first.name).to eq 'blue'
+    end
+  end
+
+  context 'nested within another structure' do
+    before do
+      class Place < LHS::Record
+        endpoint 'https://places/{id}'
+      end
+      stub_request(:get, "https://places/1")
+        .to_return(body: {
+          customer: {
+            salesforce: {
+              href: 'https://salesforce/customers/1'
+            }
+          }
+        }.to_json)
+    end
+
+    let!(:nested_request) do
+      stub_request(:get, "https://salesforce/customers/1")
+        .to_return(body: {
+          name: 'Steve'
+        }.to_json)
+    end
+
+    it 'includes data that has been nested in an additional structure' do
+      place = Place.includes_first_page(customer: :salesforce).find(1)
+      expect(nested_request).to have_been_requested
+      expect(place.customer.salesforce.name).to eq 'Steve'
+    end
+
+    context 'included data has a configured record endpoint option' do
+      before do
+        class SalesforceCustomer < LHS::Record
+          endpoint 'https://salesforce/customers/{id}', headers: { 'Authorization': 'Bearer 123' }
+        end
+      end
+
+      let!(:nested_request) do
+        stub_request(:get, "https://salesforce/customers/1")
+          .with(headers: { 'Authorization' => 'Bearer 123' })
+          .to_return(body: {
+            name: 'Steve'
+          }.to_json)
+      end
+
+      it 'includes data that has been nested in an additional structure' do
+        place = Place.includes_first_page(customer: :salesforce).find(1)
+        expect(nested_request).to have_been_requested
+        expect(place.customer.salesforce.name).to eq 'Steve'
+      end
+    end
+  end
+
+  context 'include empty structures' do
+    before do
+      class Place < LHS::Record
+        endpoint 'https://places/{id}'
+      end
+      stub_request(:get, "https://places/1")
+        .to_return(body: {
+          id: '123'
+        }.to_json)
+    end
+
+    it 'skips includes when there is nothing and also does not raise an exception' do
+      expect(-> {
+        Place.includes_first_page(contracts: :product).find(1)
+      }).not_to raise_exception
+    end
+  end
+
+  context 'include partially empty structures' do
+    before do
+      class Place < LHS::Record
+        endpoint 'https://places/{id}'
+      end
+      stub_request(:get, "https://places/1")
+        .to_return(body: {
+          id: '123',
+          customer: {}
+        }.to_json)
+    end
+
+    it 'skips includes when there is nothing and also does not raise an exception' do
+      expect(-> {
+        Place.includes_first_page(customer: :salesforce).find(1)
+      }).not_to raise_exception
+    end
+  end
+end