lhs 2.2.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d30520e791c021241701581bb76962de5bbb8e72
-  data.tar.gz: 23d3cbcf4ba46082b30e655aeb40af7d8680151e
+  metadata.gz: 23beb0804ec8b041eaa4e920e395a5d9b2bf394f
+  data.tar.gz: 3329ba17fc8d206210d143a8b8ad4aae09561316
 SHA512:
-  metadata.gz: 3ecc85bf22592f7b5bed6dd2f82180ec1bdb203bb5578ba9905fd11b1ba50f03c2e5be6b44c7c11c1b246c1f1c40205b47e66171ec43b334dbca237ed89b5a91
-  data.tar.gz: 7a5182fa1eae09ba69ecd5976a93e91c3c910fa132b1d7f8d47544bf4f5c3fc176834b5d0b570dc5f1142af142c0514d63cd590ae5e53e206038cbdecb37276b
+  metadata.gz: 451e95f0aa50d9f41eedd21f7339f36904d146f36c3ca880effe675f5b9b7c6a6198592e4a4d6e2c284a10fadbe4b7aa8a96b3f1e60748fae1988bc4e805f788
+  data.tar.gz: df8f2a78480a2ead8098c786e04f620e6541420c78803adaf2ee2524c31274a2ddd756d6dd4b7309d08c76cacea9bda907c797a1b6a346e3c2ecdf59a04ae45b

data/README.md

@@ -3,65 +3,331 @@ LHS
 
 LHS uses [LHC](//github.com/local-ch/LHC) for http requests.
 
-## Service
-A service connects your application to backend endpoints and provides you access to their data.
+## Very Short Introduction
+
+A LHS::Record makes data available using backend services and one or multiple endpoints.
 
 ```ruby
-class Feedback < LHS::Service
+class Feedback < LHS::Record
 
   endpoint ':datastore/v2/content-ads/:campaign_id/feedbacks'
   endpoint ':datastore/v2/feedbacks'
 
 end
 
-data = Feedback.where(has_reviews: true) #<LHS::Data>
+feedback = Feedback.find_by_email('somebody@mail.com') #<Feedback>
+feedback.review # "Lunch was great"
 ```
 
-→ [Read more about services](docs/services.md)
+## Where to store LHS::Records
+
+Please store all defined LHS::Records in `app/models` as they are not autoloaded by rails otherwise.
+
+## Endpoints
+
+You setup a LHS::Record by configuring one or multiple backend endpoints. You can also add request options for an endpoint (see following example).
+
+```ruby
+class Feedback < LHS::Record
+
+  endpoint ':datastore/v2/content-ads/:campaign_id/feedbacks'
+  endpoint ':datastore/v2/content-ads/:campaign_id/feedbacks/:id'
+  endpoint ':datastore/v2/feedbacks', cache: true, cache_expires_in: 1.day
+  endpoint ':datastore/v2/feedbacks/:id', cache: true, cache_expires_in: 1.day
+
+end
+```
 
-## Data
-An instance of LHS::Data contains raw data (json) and a proxy that is used to access data.
+If you try to setup a LHS::Record with clashing endpoints it will immediately raise an exception.
 
 ```ruby
-Service.where #<LHS::Data @_proxy_=#<LHS::Collection>>
-Service.find(123) #<LHS::Data @_proxy_=#<LHS::Item>>
+class Feedback < LHS::Record
+
+  endpoint ':datastore/v2/reviews'
+  endpoint ':datastore/v2/feedbacks'
+
+end
+# raises: Clashing endpoints.
 ```
 
-→ [Read more about data](docs/data.md)
+## Find multiple records
+
+You can query a backend service to provide records by using `where`.
+
+```ruby
+  Feedback.where(has_reviews: true)
+```
+
+This uses the `:datastore/v2/feedbacks` endpoint, cause `:campaign_id` was not provided. In addition it would add `?has_reviews=true` to the get parameters.
+
+```ruby
+  Feedback.where(campaign_id: 'fq-a81ngsl1d')
+```
+
+Uses the `:datastore/v2/content-ads/:campaign_id/feedbacks` endpoint.
+
+## Find single records
+
+`find` finds a unique record by uniqe identifier (usualy id).
+
+If no record is found an error is raised.
 
 ## Proxy
-A proxy is used to access data. It is divided in Collection and Item.
+Instead of mapping data when it arrives from the backend, the proxy makes data accessible when you access it, not when you fetch it. The proxy is used to access data and it is divided in `Collection` and `Item`. 
+
+`find` can also be used to find a single uniqe record with parameters:
+
+```ruby
+  Feedback.find(campaign_id: 123, id: 456)
+```
+
+`find_by` finds the first record matching the specified conditions.
+
+If no record is found, `nil` is returned.
+
+`find_by!` raises LHC::NotFound if nothing was found.
+
+```ruby
+  Feedback.find_by(id: 'z12f-3asm3ngals')
+  Feedback.find_by(id: 'doesntexist') # nil
+```
+
+`first` is an alias for finding the first record without parameters.
+
+```ruby
+  Feedback.first
+```
+
+If no record is found, `nil` is returned.
+
+`first!` raises LHC::NotFound if nothing was found.
+
+## Batch processing
 
-For every proxy that contains an `href` you can use `load!` or `reload!` to receive latest backend data.
+**Be carefull using methods for batch processing. They could result in a lot of HTTP requests!**
+
+`all` fetches all records from the backend by doing multiple requests if necessary.
 
 ```ruby
-{
-  "href" => "http://local.ch/v2/content-ads/51dfc5690cf271c375c5a12d"
-}
+data = Feedback.all
+data.count # 998
+data.total # 998
+```
+
+`find_each` is a more fine grained way to process single records that are fetched in batches.
 
-item.load!.id
-item.reload! # loads it again
-item.load! # wont load it again, because its already arround
+```ruby
+Feedback.find_each(start: 50, batch_size: 20, params: { has_reviews: true }) do |feedback|
+  # Iterates over each record. Starts with record nr. 50 and fetches 20 records each batch.
+  feedback 
+  break if feedback.some_attribute == some_value
+end
+```
+
+`find_in_batches` is used by `find_each` and processes batches.
+```ruby
+Feedback.find_in_batches(start: 50, batch_size: 20, params: { has_reviews: true }) do |feedbacks|
+  # Iterates over multiple records (batch size is 20). Starts with record nr. 50 and fetches 20 records each batch.
+  feedbacks
+  break if feedback.some_attribute == some_value
+end
 ```
 
-## Collection
-A collection contains multiple items.
+## Create records
 
 ```ruby
-data = Feedback.where(has_reviews: true) #<LHS::Data @_proxy_=#<LHS::Collection>>
-data.count # 10
-data.total # 98
+  feedback = Feedback.create(
+    recommended: true,
+    source_id: 'aaa',
+    content_ad_id: '1z-5r1fkaj'
+  )
+```
+
+When creation fails, the object contains errors. It provides them through the `errors` attribute:
+
+```ruby
+  feedback.errors #<LHS::Errors>
+  feedback.errors.include?(:ratings) # true
+  feedback.errors[:ratings] # ['REQUIRED_PROPERTY_VALUE']
+  record.errors.messages # {:ratings=>["REQUIRED_PROPERTY_VALUE"], :recommended=>["REQUIRED_PROPERTY_VALUE"]}
+  record.errors.message # ratings must be set when review or name or review_title is set | The property value is required; it cannot be null, empty, or blank."
+```
+
+## Build new records
+
+Build and persist new items from scratch are done either with `new` or it's alias `build`.
+
+```ruby
+  feedback = Feedback.new(recommended: true)
+  feedback.save
+```
+
+## Include linked resources
+
+When fetching records, you can specify in advance all the linked resources that you want to include in the results. With `includes`, LHS ensures that all matching and explicitly linked resources are loaded and merged.
+
+The implementation is heavily influenced by [http://guides.rubyonrails.org/active_record_class_querying](http://guides.rubyonrails.org/active_record_class_querying.html#eager-loading-associations) and you should read it to understand this feature in all its glory.
+
+### One-Level `includes`
+
+```ruby
+  # a claim has a localch_account
+  claims = Claims.includes(:localch_account).where(place_id: 'huU90mB_6vAfUdVz_uDoyA')
+  claims.first.localch_account.email # 'test@email.com'
+```
+* [see the JSON without include](examples/claim_no_include.json)
+* [see the JSON with include](examples/claim_with_include.json)
+
+### Two-Level `includes`
+
+```ruby
+  # a feedback has a campaign, which has an entry
+  feedbacks = Feedback.includes(campaign: :entry).where(has_reviews: true)
+  feedbacks.first.campaign.entry.name # 'Casa Ferlin'
+```
+
+### Multiple `includes`
+
+```ruby
+  # list of includes
+  claims = Claims.includes(:localch_account, :entry).where(place_id: 'huU90mB_6vAfUdVz_uDoyA')
+  
+  # array of includes
+  claims = Claims.includes([:localch_account, :entry]).where(place_id: 'huU90mB_6vAfUdVz_uDoyA')
+  
+  # Two-level with array of includes
+  feedbacks = Feedback.includes(campaign: [:entry, :user]).where(has_reviews: true)
+```
+
+### Known LHS::Records are used to request linked resources
+
+When including linked resources with `includes`, known/defined services and endpoints are used to make those requests. 
+That also means that options for endpoints of linked resources are applied when requesting those in addition.
+This allows you to include protected resources (e.g. OAuth) as endpoint options for oauth authentication get applied.
+
+The [Auth Inteceptor](https://github.com/local-ch/lhc-core-interceptors#auth-interceptor) from [lhc-core-interceptors](https://github.com/local-ch/lhc-core-interceptors) is used to configure the following endpoints.
+
+```ruby
+class Favorite < LHS::Record
+
+  endpoint ':datastore/:user_id/favorites', auth: { bearer: -> { bearer_token } }
+  endpoint ':datastore/:user_id/favorites/:id', auth: { bearer: -> { bearer_token } }
+
+end
+
+class Place < LHS::Record
+
+  endpoint ':datastore/v2/places', auth: { bearer: -> { bearer_token } }
+  endpoint ':datastore/v2/places/:id', auth: { bearer: -> { bearer_token } }
+
+end
+
+Favorite.includes(:place).where(user_id: current_user.id) 
+# Will include places and applies endpoint options to authenticate the request.
+```
+
+## Map data
+
+To influence how data is accessed/provied, you can use mappings to either map deep nested data or to manipulate data when its accessed. Simply create methods inside the LHS::Record. They can access underlying data:
+
+```ruby
+class LocalEntry < LHS::Record
+  endpoint ':datastore/v2/local-entries'
+
+  def name
+    addresses.first.business.identities.first.name
+  end
+
+end
+```
+
+### Known LHS::Records when accessing mapped data from nested data
+
+As LHS detects LHS::Records as soon as a link is present, mappings will also be applied on nested data:
+
+```
+class Place < LHS::Record
+  endpoint ':datastore/v2/places'
+
+  def name
+    addresses.first.business.identities.first.name
+  end
+end
+
+class Favorite < LHS::Record
+  endpoint ':datastore/v2/favorites'
+end
+
+favorite = Favorite.includes(:place).find(1)
+favorite.place.name # local.ch AG
+```
+
+## Setters
+
+You can change attributes of LHS::Records:
+
+```
+  record = Feedback.find(id: 'z12f-3asm3ngals')
+  rcord.recommended = false
+```
+
+## Save
+
+You can persist changes with `save`. `save` will return `false` if persisting fails. `save!` instead will raise an exception.
+
+```ruby
+  feedback = Feedback.find('1z-5r1fkaj')
+  feedback.recommended = false
+  feedback.save
+```
+
+## Update
+
+`update` will return false if persisting fails. `update!` instead will an raise exception.
+
+`update` always updates the data of the local object first, before it tries to sync with an endpoint. So even if persisting fails, the local object is updated.
+
+```ruby
+feedback = Feedback.find('1z-5r1fkaj')
+feedback.update(recommended: false)
+```
+
+## Destroy
+
+You can delete records remotely by calling `destroy` on an LHS::Record.
+
+```ruby
+  feedback = Feedback.find('1z-5r1fkaj')
+  feedback.destroy
+```
+
+## Validation
+
+In order to validate LHS::Records before persisting them, you can use the `valid?` (`validate` alias) method.
+
+The specific endpoint has to support validations with the `persist=false` parameter. The endpoint has to be enabled (opt-in) for validations in the service configuration.
+
+```
+class User < LHS::Record
+  endpoint ':datastore/v2/users', validates: true
+end
+
+user = User.build(email: 'im not an email address')
+unless user.valid?
+  fail(user.errors[:email])
+end
 ```
 
-→ [Read more about collections](docs/collections.md)
+## Collections: Offset / Limit / Pagination
 
-## Item
-An item is a concrete record. It can be part of another proxy like collection.
+You can paginate by passing offset, and limit params. They will be forwarded to the backend.
 
 ```ruby
-data = Feedback.where(has_reviews: true).first #<LHS::Data @_proxy_=#<LHS::Item>>
-data.recommended # true
-data.created_date # Fri, 19 Sep 2014 14:03:35 +0200
+data = Feedback.where(limit: 50)
+data.count // 50
+Feedback.where(limit: 50, offset: 51)
 ```
 
-→ [Read more about items](docs/items.md)
+`total` provides total amount of items (even if paginated).
+`limit` provides amount of items per page.
+`offset` provides how many items where skipped to start the current page.

data/lhs.gemspec

@@ -7,11 +7,11 @@ require "lhs/version"
 Gem::Specification.new do |s|
   s.name        = "lhs"
   s.version     = LHS::VERSION
-  s.authors     = ['local.ch']
+  s.authors     = ['https://github.com/local-ch/lhs/graphs/contributors']
   s.email       = ['ws-operations@local.ch']
   s.homepage    = 'https://github.com/local-ch/lhs'
-  s.summary     = 'LocalHttpServices'
-  s.description = 'Rails gem providing an easy interface to use http services here at local'
+  s.summary     = 'Rails gem providing an easy, active-record-like interface to use http backend services'
+  s.description = s.summary
 
   s.files        = `git ls-files`.split("\n")
   s.test_files   = `git ls-files -- spec/*`.split("\n")

data/lib/lhs.rb

@@ -4,10 +4,3 @@ module LHS
 end
 
 Gem.find_files('lhs/**/*.rb').each { |path| require path }
-
-# Preload all the services that are defined in app/services
-class Engine < Rails::Engine
-  initializer 'Load all services' do |app|
-    Dir.glob(app.root.join('app/services/**/*.rb')).each {|file| require file }
-  end
-end

data/lib/lhs/collection.rb

@@ -25,7 +25,7 @@ class LHS::Collection < LHS::Proxy
   def _collection
     raw = _data._raw if _data._raw.is_a?(Array)
     raw ||= _data._raw[:items]
-    Collection.new(raw, _data, _data._service)
+    Collection.new(raw, _data, _data._record_class)
   end
 
   def _raw
@@ -59,16 +59,16 @@ class LHS::Collection < LHS::Proxy
     attr_accessor :raw
     delegate :last, :sample, :[], :present?, :blank?, :empty?, to: :raw
 
-    def initialize(raw, parent, service)
+    def initialize(raw, parent, record)
       self.raw = raw
       @parent = parent
-      @service = service
+      @record = record
     end
 
     def each(&block)
       raw.each do |item|
         if item.is_a? Hash
-          yield LHS::Data.new(item, @parent, @service)
+          yield LHS::Data.new(item, @parent, @record)
         else
           yield item
         end

data/lib/lhs/concerns/item/destroy.rb

@@ -7,8 +7,8 @@ class LHS::Item < LHS::Proxy
     extend ActiveSupport::Concern
 
     def destroy
-      service = _data._root._service
-      _data._request = service.request(method: :delete, url: href)._request
+      record = _data._root._record_class
+      _data._request = record.request(method: :delete, url: href)._request
       _data
     end
   end

data/lib/lhs/concerns/item/save.rb

@@ -14,14 +14,14 @@ class LHS::Item < LHS::Proxy
     end
 
     def save!
-      service = _data._root._service
+      record = _data._root._record_class
       data = _data._raw.dup
       url = if href.present?
        href
       else
-        service.find_endpoint(data).compile(data)
+        record.find_endpoint(data).compile(data)
       end
-      data = service.request(method: :post, url: url, body: data.to_json, headers: {'Content-Type' => 'application/json'})
+      data = record.request(method: :post, url: url, body: data.to_json, headers: {'Content-Type' => 'application/json'})
       self._data.merge_raw!(data)
       true
     end