lhs 21.3.1 → 23.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c43753bff8b039bf6b5b2384333afcc1d09da6c61f1616b06751c7a023e0fbc0
-  data.tar.gz: ee5cd17ace1e7f82fc8a713dc493543e800658bd76909ddb026951d84f31c2df
+  metadata.gz: bdbfabed0cdff17a569b59c362c34716507eb5447b6e54f4b2903cf057736d9a
+  data.tar.gz: 2ac0567f16a82722d370de8a75a1cdabc412266957047d4ed24e87a00c655f36
 SHA512:
-  metadata.gz: 14d9ddf1745b15e1c635060eec564a3e578f31829e24dede722ca5509a1dffeefec3fb0daaeb27c94f3c9854314d41fe9042cccfbd04ca3fdc2bab3a32bb9120
-  data.tar.gz: ac97fc333b97f8492bc519b401b68377af441e398486ceaea183d8b006015b691d1aad9a0f518ebf5367cf4427098d767e96354813da94807021195a38f3e997
+  metadata.gz: 4abe219f4c365168b7b6abd9095bb1f72cf8bbf5dc2591ff8457062f50590254c6321b0d244cbac07a5a7cc88c3915cdf135dd9b9185984f7cd029fb152274ef
+  data.tar.gz: 80a97943d67cc14578f23ad6d20074cb329155f54abf89812f3872f84b1c698dacafa12f6616302b1d68787db735ac211295642cc44688033ee85a61be4cce51

data/README.md

@@ -99,6 +99,8 @@ record.review # "Lunch was great
         * [Change/Update existing records](#changeupdate-existing-records)
            * [save](#save)
            * [update](#update)
+              * [Directly via Record](#directly-via-record)
+              * [per Instance](#per-instance)
            * [partial_update](#partial_update)
         * [Endpoint url parameter injection during record creation/change](#endpoint-url-parameter-injection-during-record-creationchange)
         * [Record validation](#record-validation)
@@ -119,8 +121,8 @@ record.review # "Lunch was great
         * [Record getters](#record-getters)
      * [Include linked resources (hyperlinks and hypermedia)](#include-linked-resources-hyperlinks-and-hypermedia)
         * [Generate links from parameters](#generate-links-from-parameters)
-        * [Ensure the whole linked collection is included: includes_all](#ensure-the-whole-linked-collection-is-included-includes_all)
-        * [Include the first linked page or single item is included: include](#include-the-first-linked-page-or-single-item-is-included-include)
+        * [Ensure the whole linked collection is included with includes](#ensure-the-whole-linked-collection-is-included-with-includes)
+        * [Include only the first linked page of a linked collection: includes_first_page](#include-only-the-first-linked-page-of-a-linked-collection-includes_first_page)
         * [Include various levels of linked data](#include-various-levels-of-linked-data)
         * [Identify and cast known records when including records](#identify-and-cast-known-records-when-including-records)
         * [Apply options for requests performed to fetch included records](#apply-options-for-requests-performed-to-fetch-included-records)
@@ -152,6 +154,7 @@ record.review # "Lunch was great
 
 
 
+
 ## Installation/Startup checklist
 
 - [ ] Install LHS gem, preferably via `Gemfile`
@@ -1607,6 +1610,21 @@ POST https://service.example.com/records/1z-5r1fkaj { body: "{ 'name': 'Starbuck
 
 ##### update
 
+###### Directly via Record
+
+```ruby
+# app/controllers/some_controller.rb
+
+Record.update(id: '1z-5r1fkaj', name: 'Steve')
+
+```
+```
+GET https://service.example.com/records/1z-5r1fkaj
+{ name: 'Steve' }
+```
+
+###### per Instance
+
 `update` persists the whole object after new parameters are applied through arguments.
 
 `update` will return false if persisting fails. `update!` instead will raise an exception.
@@ -2093,7 +2111,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 +2130,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 +2166,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 +2197,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 +2217,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.
 
@@ -2261,6 +2279,17 @@ In parallel:
   GET https://service.example.com/places/4 { headers: { 'Authentication': 'Bearer 123' } }
 ```
 
+Here is another example, if you want to ignore errors, that occure while you fetch included resources:
+
+```ruby
+# app/controllers/some_controller.rb
+
+feedback = Feedback
+  .includes(campaign: :entry)
+  .references(campaign: { ignored_errors: [LHC::NotFound] })
+  .find(12345)
+```
+
 ### Record batch processing
 
 **Be careful using methods for batch processing. They could result in a lot of HTTP requests!**

data/lhs.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency 'activemodel'
   s.add_dependency 'activesupport', '>= 4.2.11'
-  s.add_dependency 'lhc', '>= 10', '< 12'
+  s.add_dependency 'lhc', '>= 11.2.0', '< 12'
   s.add_dependency 'local_uri'
 
   s.add_development_dependency 'capybara'

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/concerns/record/request.rb

@@ -138,6 +138,7 @@ class LHS::Record
       end
 
       def extend_base_item!(data, addition, key)
+        return if addition.nil?
         if addition.collection?
           extend_base_item_with_collection!(data, addition, key)
         else # simple case merges hash into hash
@@ -187,7 +188,7 @@ class LHS::Record
           options = extend_with_reference(options, reference)
           addition = load_include(options, data, sub_includes, reference)
           extend_raw_data!(data, addition, included)
-          expand_addition!(data, included, options) if no_expanded_data?(addition)
+          expand_addition!(data, included, options) unless expanded_data?(addition)
         end
       end
 
@@ -205,28 +206,24 @@ class LHS::Record
       def expand_addition!(data, included, reference)
         addition = data[included]
         options = options_for_data(addition)
-        options = extend_with_reference(options, reference.except(:url))
+        options = extend_with_reference(options, reference)
         record = record_for_options(options) || self
         options = convert_options_to_endpoints(options) if record_for_options(options)
-        expanded_data = begin
-          record.request(options)
-        rescue LHC::NotFound
-          LHS::Data.new({}, data, record)
-        end
+        expanded_data = record.request(options)
         extend_raw_data!(data, expanded_data, included)
       end
 
-      def no_expanded_data?(addition)
+      def expanded_data?(addition)
         return false if addition.blank?
         if addition.item?
-          (addition._raw.keys - [:href]).empty?
+          (addition._raw.keys - [:href]).any?
         elsif addition.collection?
-          addition.all? do |item|
+          addition.any? do |item|
             next if item.blank?
             if item._raw.is_a?(Hash)
-              (item._raw.keys - [:href]).empty?
+              (item._raw.keys - [:href]).any?
             elsif item._raw.is_a?(Array)
-              item.any? { |item| (item._raw.keys - [:href]).empty? }
+              item.any? { |item| (item._raw.keys - [:href]).any? }
             end
           end
         end
@@ -234,7 +231,8 @@ class LHS::Record
 
       # Extends request options with options provided for this reference
       def extend_with_reference(options, reference)
-        return options unless reference
+        return options if reference.blank?
+        reference = reference.except(:url)
         options ||= {}
         if options.is_a?(Array)
           options.map { |request_options| request_options.merge(reference) if request_options.present? }
@@ -348,18 +346,14 @@ class LHS::Record
       end
 
       # Load additional resources that are requested with include
-      def load_include(options, data, sub_includes, references)
+      def load_include(options, _data, sub_includes, references)
         record = record_for_options(options) || self
         options = convert_options_to_endpoints(options) if record_for_options(options)
-        begin
-          prepare_options_for_include_request!(options, sub_includes, references)
-          if references && references[:all] # include all linked resources
-            load_include_all!(options, record, sub_includes, references)
-          else # simply request first page/batch
-            load_include_simple!(options, record)
-          end
-        rescue LHC::NotFound
-          LHS::Data.new({}, data, record)
+        prepare_options_for_include_request!(options, sub_includes, references)
+        if references && references[:all] # include all linked resources
+          load_include_all!(options, record, sub_includes, references)
+        else # simply request first page/batch
+          load_include_simple!(options, record)
         end
       end
 
@@ -372,7 +366,7 @@ class LHS::Record
 
       def load_include_simple!(options, record)
         data = record.request(options)
-        warn "[WARNING] You included `#{options[:url]}`, but this endpoint is paginated. You might want to use `includes_all` instead of `includes` (https://github.com/local-ch/lhs#includes_all-for-paginated-endpoints)." if paginated?(data._raw)
+        warn "[WARNING] You included `#{options[:url]}`, but this endpoint is paginated. You might want to use `includes_all` instead of `includes` (https://github.com/local-ch/lhs#includes_all-for-paginated-endpoints)." if data && paginated?(data._raw)
         data
       end
 

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'active_support'
+
+class LHS::Record
+
+  module Update
+    extend ActiveSupport::Concern
+
+    included do
+      class <<self
+        alias_method :update, :create
+        alias_method :update!, :create!
+      end
+    end
+  end
+end

data/lib/lhs/record.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 class LHS::Record
+  autoload :AttributeAssignment,
+    'lhs/concerns/record/attribute_assignment'
   autoload :Batch,
     'lhs/concerns/record/batch'
   autoload :Chainable,
@@ -45,9 +47,10 @@ class LHS::Record
     'lhs/concerns/record/scope'
   autoload :Tracing,
     'lhs/concerns/record/tracing'
-  autoload :AttributeAssignment,
-    'lhs/concerns/record/attribute_assignment'
+  autoload :Update,
+    'lhs/concerns/record/update'
 
+  include AttributeAssignment
   include Batch
   include Chainable
   include Configuration
@@ -72,7 +75,7 @@ class LHS::Record
   include Relations
   include Scope
   include Tracing
-  include AttributeAssignment
+  include Update
 
   delegate :_proxy, :_endpoint, :merge_raw!, :select, :becomes, :respond_to?, to: :_data
 

data/lib/lhs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LHS
-  VERSION = '21.3.1'
+  VERSION = '23.0.1'
 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,737 @@
+# 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
+    before 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)
+    end
+
+    it 'raises LHC::NotFound for links that cannot be included' do
+      expect(-> {
+        Feedback.includes_first_page(campaign: :entry).find(123)
+      }).to raise_error LHC::NotFound
+    end
+
+    it 'ignores LHC::NotFound for links that cannot be included if configured so with reference options' do
+      feedback = Feedback
+        .includes_first_page(campaign: :entry)
+        .references(campaign: { ignored_errors: [LHC::NotFound] })
+        .find(123)
+      expect(feedback.campaign._raw.keys.length).to eq 1
+    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