lhs 12.0.3 → 12.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4f0a470d4ad01eb619b6b2863640c8282c37ed21
-  data.tar.gz: 8006e9ea160a63f470318b472a4e5d34623517d0
+  metadata.gz: 3a3fd78d0dd9d0ee88751c3b0ba15652bd4a15d9
+  data.tar.gz: 0629f8dfc7068fa195ce3fc5d556313b59c0a713
 SHA512:
-  metadata.gz: 44e55fac18e3e4a4cf8ce9a7093ea10cc87e726dbba63d0943a3fb3bfaebbcf095d5fb9b32fffdc8c7f3055af1c5cdae20e377d199cdb6f1e5be63c5c01fb20e
-  data.tar.gz: 8468fee414fe7f8ad40f2eebbd4ddeaefc1886eddf239b174cc7d2d686ebf9c835fbcb94eedd9e81f7d5a002d814bb35ca67d5c8c7e97895289be4e1b0c3a432
+  metadata.gz: 9042c4d3e3d7b70be32018087fef6c1b472de591048b19866aad7f2fa9098e223490f318b5527a3e53708a0e591419bb0f77f47650df5c1c1f26f5ffd5b38b1e
+  data.tar.gz: 8c0571a35bcacaa09ccd58fa729b083e84d1613cee295cfec64208c1d130d9615c1e9b32cc92ab36978e8e82722316d063baf4baa806c8c5b8e0df6d6b6b018e

data/README.md

@@ -855,8 +855,21 @@ class Results < LHS::Record
 end
 ```
 
+In case of paginated resources it's important to know the difference between [count vs. length](#count-vs-length)
+
+## Configuration of Records
+
+```ruby
+class Search < LHS::Record
+  configuration items_key: 'searchResults', total_key: 'total', limit_key: 'limit', pagination_key: 'offset', pagination_strategy: 'offset'
+  endpoint 'https://search'
+end
+```
+
 `items_key` key used to determine items of the current page (e.g. `docs`, `items`, etc.).
 
+`item_created_key` key used to merge record data thats nested in the creation response body.
+
 `limit_key` key used to work with page limits (e.g. `size`, `limit`, etc.)
 
 `pagination_key` key used to paginate multiple pages (e.g. `offset`, `page`, `startAt` etc.).
@@ -865,7 +878,48 @@ end
 
 `total_key` key used to determine the total amount of items (e.g. `total`, `totalResults`, etc.).
 
-In case of paginated resources it's important to know the difference between [count vs. length](#count-vs-length)
+### Configure complex accessors for nested data (EXPERIMENTAL)
+
+If items, limit, pagination, total etc. is nested in the responding objects, use complex data structures for configuring a record.
+
+```
+  response: {
+    offset: 0,
+    max: 50,
+    count: 1,
+    businesses: [
+      {}
+    ]
+  }
+```
+
+```ruby
+  class Business < LHS::Record
+    configuration items_key: [:response, :businesses], limit_key: [:response, :max], pagination_key: [:response, :offset], total_key: [:response, :count], pagination_strategy: :offset
+    endpoint 'http://uberall/businesses'
+  end
+```
+
+If record data after creation is nested in the response body, configure the record, so that it gets properl merged with the your record instance:
+
+```
+POST /businesses
+  response: {
+    business: {
+      id: 123
+    }
+  }
+```
+
+```ruby
+  class Business < LHS::Record
+    configuration item_created_key: [:response, :business]
+    endpoint 'http://uberall/businesses'
+  end
+
+  business = Business.create(name: 'localsearch')
+  business.id # 123
+```
 
 ### Pagination Chains
 

data/lib/lhs/collection.rb

@@ -1,7 +1,12 @@
 # A collection is a special type of data
 # that contains multiple items
 class LHS::Collection < LHS::Proxy
-  autoload :InternalCollection, 'lhs/concerns/collection/internal_collection'
+  autoload :HandleNested,
+    'lhs/concerns/collection/handle_nested'
+  autoload :InternalCollection,
+    'lhs/concerns/collection/internal_collection'
+
+  include HandleNested
   include InternalCollection
   include Create
 
@@ -23,7 +28,7 @@ class LHS::Collection < LHS::Proxy
 
   def _collection
     raw = _data._raw if _data._raw.is_a?(Array)
-    raw ||= _data._raw[items_key]
+    raw ||= _data.access(input: _data._raw, record: _record)
     Collection.new(raw, _data, _record)
   end
 
@@ -39,7 +44,7 @@ class LHS::Collection < LHS::Proxy
     if _raw.is_a?(Array)
       _raw
     else
-      _raw[items_key]
+      access(input: _raw, record: _record)
     end
   end
 
@@ -64,11 +69,6 @@ class LHS::Collection < LHS::Proxy
 
   private
 
-  def items_key
-    return _record.items_key if _record
-    :items
-  end
-
   # Encloses accessed collection item
   # by wrapping it in an LHS::Item
   def enclose_item_in_data(value)

data/lib/lhs/concerns/collection/handle_nested.rb

@@ -0,0 +1,41 @@
+require 'active_support'
+
+class LHS::Collection < LHS::Proxy
+
+  # Handles pontentially (deep-)nested collections
+  #   Examples:
+  #     [ { name: 'Steve '} ]
+  #     { items: [ { name: 'Steve' } ] }
+  #     { response: { business: [ { name: 'Steve' } ] } }
+  module HandleNested
+    extend ActiveSupport::Concern
+
+    delegate :access, :nest, :concat, to: :class
+
+    module ClassMethods
+      # Access potentially nested collection of items
+      def access(input:, record: nil)
+        input.dig(*items_key(record))
+      end
+
+      # Initializes nested collection
+      def nest(input:, value: nil, record: nil)
+        input[items_key(record)] = value
+      end
+
+      # Concats existing nested collection of items
+      # with given items
+      def concat(input:, items:, record: nil)
+        input.dig(*items_key(record)).concat(items)
+      end
+
+      private
+
+      # Takes configured items key to access collection of items
+      # of falls back to the default key
+      def items_key(record)
+        record && record.items_key || LHS::Record.items_key
+      end
+    end
+  end
+end

data/lib/lhs/concerns/proxy/accessors.rb

@@ -33,15 +33,15 @@ class LHS::Proxy
 
     def accessing_item?(value, record)
       return false unless value.is_a?(Hash)
-      return false if record && value[record.items_key].present?
-      return false if !record && value[LHS::Record::Configuration::DEFAULT_ITEMS_KEY].present?
+      return false if record && access(input: value, record: record).present?
+      return false if !record && value[:items].present?
       true
     end
 
     def accessing_collection?(value, record)
       return true if value.is_a?(Array)
-      return true if value.is_a?(Hash) && record && value[record.items_key].present?
-      return true if value.is_a?(Hash) && !record && value[LHS::Record::Configuration::DEFAULT_ITEMS_KEY].present?
+      return true if value.is_a?(Hash) && record && access(input: value, record: record).present?
+      return true if value.is_a?(Hash) && !record && value[:items].present?
     end
 
     def convert(value)

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

@@ -7,8 +7,6 @@ class LHS::Record
   module Configuration
     extend ActiveSupport::Concern
 
-    DEFAULT_ITEMS_KEY = :items
-
     mattr_accessor :configuration
 
     module ClassMethods
@@ -17,25 +15,49 @@ class LHS::Record
       end
 
       def items_key
-        (@configuration.try(:[], :items_key) || DEFAULT_ITEMS_KEY).to_sym
+        symbolize_unless_complex(
+          @configuration.try(:[], :items_key) || :items
+        )
+      end
+
+      def item_created_key
+        symbolize_unless_complex(
+          @configuration.try(:[], :item_created_key)
+        )
       end
 
       def limit_key
-        (@configuration.try(:[], :limit_key) || :limit).to_sym
+        symbolize_unless_complex(
+          @configuration.try(:[], :limit_key) || :limit
+        )
       end
 
       def total_key
-        (@configuration.try(:[], :total_key) || :total).to_sym
+        symbolize_unless_complex(
+          @configuration.try(:[], :total_key) || :total
+        )
       end
 
       # Key used for determine current page
       def pagination_key
-        (@configuration.try(:[], :pagination_key) || :offset).to_sym
+        symbolize_unless_complex(
+          @configuration.try(:[], :pagination_key) || :offset
+        )
       end
 
       # Strategy used for calculationg next pages and navigate pages
       def pagination_strategy
-        (@configuration.try(:[], :pagination_strategy) || :offset).to_sym
+        symbolize_unless_complex(
+          @configuration.try(:[], :pagination_strategy) || :offset
+        )
+      end
+
+      private
+
+      def symbolize_unless_complex(value)
+        return if value.blank?
+        return value.to_sym unless value.is_a?(Array)
+        value
       end
     end
   end

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

@@ -124,11 +124,11 @@ class LHS::Record
       end
 
       def extend_base_item_with_hash_of_items!(target, addition)
-        target._raw[items_key] ||= []
-        if target._raw[items_key].empty?
-          target._raw[items_key] = addition.map(&:_raw)
+        LHS::Collection.nest(input: target._raw, value: [], record: self)
+        if LHS::Collection.access(input: target._raw, record: self).empty?
+          LHS::Collection.nest(input: target._raw, value: addition.map(&:_raw), record: self)
         else
-          target._raw[items_key].each_with_index do |item, index|
+          LHS::Collection.access(input: target._raw, record: self).each_with_index do |item, index|
             item.merge!(addition[index])
           end
         end
@@ -326,7 +326,7 @@ class LHS::Record
       end
 
       def merge_batch_data_with_parent!(batch_data, parent_data)
-        parent_data._raw[items_key].concat batch_data.raw_items
+        parent_data.concat(input: parent_data._raw, items: batch_data.raw_items, record: self)
         parent_data._raw[limit_key] = batch_data._raw[limit_key]
         parent_data._raw[total_key] = batch_data._raw[total_key]
         parent_data._raw[pagination_key] = batch_data._raw[pagination_key]

data/lib/lhs/data.rb

@@ -30,7 +30,11 @@ class LHS::Data
   # e.g. when loading remote data via link
   def merge_raw!(data)
     return false if data.blank? || !data._raw.is_a?(Hash)
-    _raw.merge! data._raw
+    if _record && _record.item_created_key
+      _raw.merge! data._raw.dig(*_record.item_created_key)
+    else
+      _raw.merge! data._raw
+    end
   end
 
   def _root
@@ -83,7 +87,7 @@ class LHS::Data
   private
 
   def collection_proxy?(input)
-    (input.is_a?(Hash) && input[items_key]) ||
+    (input.is_a?(Hash) && LHS::Collection.access(input: input, record: _record)) ||
       input.is_a?(Array) ||
       _raw.is_a?(Array)
   end

data/lib/lhs/pagination/base.rb

@@ -17,15 +17,15 @@ module LHS::Pagination
     end
 
     def total
-      data._raw[_record.total_key.to_sym]
+      data._raw.dig(*_record.total_key)
     end
 
     def limit
-      data._raw[_record.limit_key.to_sym] || DEFAULT_LIMIT
+      data._raw.dig(*_record.limit_key) || DEFAULT_LIMIT
     end
 
     def offset
-      data._raw[_record.pagination_key.to_sym].presence || 0
+      data._raw.dig(*_record.pagination_key) || 0
     end
     alias current_page offset
     alias start offset

data/lib/lhs/version.rb

@@ -1,3 +1,3 @@
 module LHS
-  VERSION = "12.0.3"
+  VERSION = "12.1.0"
 end

data/spec/record/dig_configuration_spec.rb

@@ -0,0 +1,67 @@
+require 'rails_helper'
+
+describe LHS::Record do
+  before(:each) do
+    class Business < LHS::Record
+      configuration items_key: [:response, :businesses], limit_key: [:response, :max], pagination_key: [:response, :offset], total_key: [:response, :count], pagination_strategy: :offset
+      endpoint 'http://uberall/businesses'
+    end
+  end
+
+  let(:stub_single_business_request) do
+    stub_request(:get, "http://uberall/businesses?identifier=ABC123&limit=1")
+      .to_return(body: {
+        status: "SUCCESS",
+        response: {
+          offset: 0,
+          max: 50,
+          count: 1,
+          businesses: [
+            {
+              identifier: 'ABC123',
+              name: 'localsearch'
+            }
+          ]
+        }
+      }.to_json)
+  end
+
+  let(:stub_multiple_businesses_request) do
+    stub_request(:get, "http://uberall/businesses?name=localsearch")
+      .to_return(body: {
+        status: "SUCCESS",
+        response: {
+          offset: 0,
+          max: 50,
+          count: 2,
+          businesses: [
+            {
+              identifier: 'ABC123',
+              name: 'localsearch'
+            },
+            {
+              identifier: 'ABC121',
+              name: 'Swisscom'
+            }
+          ]
+        }
+      }.to_json)
+  end
+
+  context 'access nested keys for configuration' do
+    it 'uses paths from configuration to access nested values' do
+      stub_single_business_request
+      business = Business.find_by(identifier: 'ABC123')
+      expect(business.identifier).to eq 'ABC123'
+      expect(business.name).to eq 'localsearch'
+    end
+
+    it 'digs for meta data when meta information is nested' do
+      stub_multiple_businesses_request
+      businesses = Business.where(name: 'localsearch')
+      expect(businesses.length).to eq 2
+      expect(businesses.count).to eq 2
+      expect(businesses.offset).to eq 0
+    end
+  end
+end

data/spec/record/items_created_key_configuration_spec.rb

@@ -0,0 +1,35 @@
+require 'rails_helper'
+
+describe LHS::Record do
+  before(:each) do
+    class Business < LHS::Record
+      configuration item_created_key: [:response, :business], limit_key: [:response, :max], pagination_key: [:response, :offset], total_key: [:response, :count], pagination_strategy: :offset
+      endpoint 'http://uberall/businesses'
+    end
+  end
+
+  let(:stub_create_business_request) do
+    stub_request(:post, "http://uberall/businesses")
+      .to_return(body: {
+        status: "SUCCESS",
+        response: {
+          business: {
+            identifier: 'ABC123',
+            name: 'localsearch',
+            id: 239650
+          }
+        }
+      }.to_json)
+  end
+
+  it 'uses paths from configuration to access nested values' do
+    stub_create_business_request
+    business = Business.create!(
+      identifier: 'ABC123',
+      name: 'localsearch'
+    )
+    expect(business.identifier).to eq 'ABC123'
+    expect(business.name).to eq 'localsearch'
+    expect(business.id).to eq 239650
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lhs
 version: !ruby/object:Gem::Version
-  version: 12.0.3
+  version: 12.1.0
 platform: ruby
 authors:
 - https://github.com/local-ch/lhs/graphs/contributors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-26 00:00:00.000000000 Z
+date: 2017-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lhc
@@ -198,6 +198,7 @@ files:
 - lib/lhs/collection.rb
 - lib/lhs/complex.rb
 - lib/lhs/concerns/autoload_records.rb
+- lib/lhs/concerns/collection/handle_nested.rb
 - lib/lhs/concerns/collection/internal_collection.rb
 - lib/lhs/concerns/configuration.rb
 - lib/lhs/concerns/data/equality.rb
@@ -340,6 +341,7 @@ files:
 - spec/record/creation_failed_spec.rb
 - spec/record/definitions_spec.rb
 - spec/record/destroy_spec.rb
+- spec/record/dig_configuration_spec.rb
 - spec/record/endpoint_inheritance_spec.rb
 - spec/record/endpoint_misconfiguration_spec.rb
 - spec/record/endpoint_options_spec.rb
@@ -357,6 +359,7 @@ files:
 - spec/record/includes_all_spec.rb
 - spec/record/includes_spec.rb
 - spec/record/includes_warning_spec.rb
+- spec/record/items_created_key_configuration_spec.rb
 - spec/record/loading_twice_spec.rb
 - spec/record/mapping_spec.rb
 - spec/record/model_name_spec.rb
@@ -507,6 +510,7 @@ test_files:
 - spec/record/creation_failed_spec.rb
 - spec/record/definitions_spec.rb
 - spec/record/destroy_spec.rb
+- spec/record/dig_configuration_spec.rb
 - spec/record/endpoint_inheritance_spec.rb
 - spec/record/endpoint_misconfiguration_spec.rb
 - spec/record/endpoint_options_spec.rb
@@ -524,6 +528,7 @@ test_files:
 - spec/record/includes_all_spec.rb
 - spec/record/includes_spec.rb
 - spec/record/includes_warning_spec.rb
+- spec/record/items_created_key_configuration_spec.rb
 - spec/record/loading_twice_spec.rb
 - spec/record/mapping_spec.rb
 - spec/record/model_name_spec.rb