json_api_resource 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7885048db5c04d2db691e4b6bd64ecd4c4be98bc
-  data.tar.gz: ea2293ae4e78d3ff60cfae0a0d6a61cec82e1491
+  metadata.gz: 1d1601705bb9dd846cb112a656fab64ad71f8128
+  data.tar.gz: 01986a0b6f6af3331de1394fb40f0c92d516ad38
 SHA512:
-  metadata.gz: 350b7f7cac7fb8ac73915c2ecb367e5cc4b8b14b1d0e68d483e982382ca896754a999b16e292429c5df53ff180870d77cb7ff5d548e493eee298827580fa23de
-  data.tar.gz: 2a30c2ea518d8cceb37d2420ca2e5acd594968b041c2617c49763b36ca87a89e80b0e5857f98c16efb9866e96dcd84ff166fb229f64572dc1c61c234ba603163
+  metadata.gz: d73fc8efe1f0d87995b012f40e900220eaa4fe1261e5468f3f69bce791ea4e3c98c443e96bd7e40dae642506ddf1737124ebf34551cf0c5c60ee8658b350c7a3
+  data.tar.gz: 89239740324124cc32de4f453dfc48eed9115a6958c89d156743d110856379f185a17ac51ffaa594541ba75d9d40ac41930cb82e05c168b40e9e428ff1c6e3c7

data/README.md

@@ -1,17 +1,167 @@
 # JsonApiResource
 
-Common code wrapper object or Adapter class to extend a JsonApiClient::Resource
+JsonApiResource is an abstraction layer that sits on top of [JsonApiClient](https://github.com/chingor13/json_api_client) that lets the user interact with client objects the way they would with an ActiveRecord model. It provides objectification of attributes, population with defaults, metadata and error handling on server requests. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'json_api_resource'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install json_api_resource
 
 ## Usage
 
-### Basic
+### Example
+
+Let's say you have a JsonApi server Account, which has a RESTful controller, `UsersController` and you have a `JsonApiClient` that can talk to it. And you would like to interact with the server result as an object, rather than
 
+```ruby
+  user = Account::Client::User.find(15)
+  user["name"]
 ```
-class Customer < JsonApiResource::Resource
-  property :name => 'name', :email => '', :permissions => []
-  api_client Ledger::Client::Customer
+
+You can wrap it in a `JsonApiResource`
+
+```ruby
+module Account
+  class User < JsonApiResource::Resource
+
+    # define what your client is
+    wraps Account::Client::User
+
+    # define what fields you expect, with defaults, should you create a new object
+    #   or should the server omit fields in its response
+    properties   id: nil,
+               name: "",
+        permissions: [],
+         friend_ids: []
+
+    # your custom code here
+    def friends
+      @friends ||= where(id: friend_ids)
+    end
+
+    #etc
+  end
 end
+```
+
+Then you can interface with the `Account::User` class, as you would any old AR class.
+
+```ruby
+
+  # find works the way you would expect
+  john = Account::User.find(38)
+  john.name = "Johnny"
+
+  # will make a PUT call to the server
+  john.save # => true
+
+  # if you preforma an action that fails validation
+  john.name = ""
+  john.save  # => false
+
+  john.errors # ActiveModel::Errors errors that you can nicely pipe into your forms
+
+  mark = Account::User.new
+  mark.id # => nil
+
+  mark.name = "Mark"
+
+  mark.save # => true
+
+  # etc
+```
+
+### Keywords
+
+#### wraps
+
+`wraps` is an interface method that defines what `JsonApiClient` class the resource will wrap and connect to.
+
+```ruby
+module Account
+  class User < JsonApiResource::Resource
+
+    wraps Account::Client::User
+
+  end
+end
+```
+
+#### property
+
+Define a single property that will be populated on new object or if the field is missing.
+
+```ruby
+class User < JsonApiResource::Resource
+  wraps Whatever 
+
+  # defaults to nil
+  property :id
+
+  # defaults to ""
+  property :name, ""
+end
+
+```
+
+#### properties
+
+Define multiple properties
+
+```ruby
+class User < JsonApiResource::Resource
+  wraps Whatever 
+
+  properties id: nil,
+           name: ""
+end
+```
+
+NOTE: all properties are optional. If you don't have it defined and it's in the payload, it will still be part of your resulting object. For example, if you define no properties, but your payload comes in as
+
+```json
+{  
+           "id": 10,
+         "name": "john",
+  "permissions": []
+}
+```
+
+The object will still reply to `id`, `name` and `permissions`, but you won't be able to assume they are there, and they will not appear when you do `ResourceClass.new`.
+
+### Other Features
+
+#### Caching
+
+JsonApiResource does a full digest of the json blob, so if your server schema changes, you will see your client side cache burst.
+
+#### Error handling
+
+As seen in the example above, JsonApiResource extracts the server errors from the metadata and wraps them nicely in `ActiveModel::Errors`, for easy form integration.
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/avvo/json_api_resource.
+
 
-item = Customer.new
-#<Customer:0x007f84b7a72568 @client=#<Ledger::Client::Customer:0x007f84b7a71398 @attributes={"id"=>nil, "name"=>"name", "email"=>"", "permissions"=>[]}>>
+## License
 
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/json_api_resource/cacheable.rb

@@ -1,8 +1,13 @@
+require 'multiconnect'
+
 module JsonApiResource
   module Cacheable
     extend ActiveSupport::Concern
-    def cache_key
-      @cache_key ||= Digest::SHA256.hexdigest(self.to_json)
+    
+    included do
+      def cache_key
+        @cache_key ||= Digest::SHA256.hexdigest(self.to_json)
+      end
     end
   end
-end
+end

data/lib/json_api_resource/clientable.rb

@@ -1,3 +1,5 @@
+require 'multiconnect'
+
 module JsonApiResource
   module Clientable
     extend ActiveSupport::Concern
@@ -5,10 +7,14 @@ module JsonApiResource
     included do
       class_attribute :client_class
       self.client_class = nil
+      include Multiconnect::Connectable
 
       class << self
         def wraps(client)
           self.client_class = client
+
+          # now that we know where to connect to, let's do it
+          add_connection Connections::ServerConnection, client: client
         end
       end
     end

data/lib/json_api_resource/connections/server_connection.rb

@@ -0,0 +1,34 @@
+module JsonApiResource
+  module Connections
+    class ServerConnection < Multiconnect::Connection::Base
+      class_attribute :error_notifier
+
+      def report_error( e )
+        error_notifier.notify( self, e ) if error_notifier.present?
+      end
+
+      def request( action, *args )
+
+        result = self.client.send action, *args
+
+        if result.is_a? JsonApiClient::Scope
+          result = result.all
+        end
+
+        result
+
+      rescue JsonApiClient::Errors::NotFound => e
+
+        result = JsonApiClient::ResultSet.new
+
+        result.meta = {status: 404}
+
+        result.errors = ActiveModel::Errors.new(result)
+        result.errors.add("RecordNotFound", e.message)
+
+        result
+
+      end
+    end
+  end
+end

data/lib/json_api_resource/connections.rb

@@ -0,0 +1,5 @@
+module JsonApiResource
+  module Connections
+    autoload :ServerConnection,         'json_api_resource/connections/server_connection'
+  end
+end

data/lib/json_api_resource/error_notifier/base.rb

@@ -0,0 +1,11 @@
+module JsonApiResource
+  module ErrorNotifier
+    class Base
+      class << self
+        def notify( connection, error )
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/json_api_resource/error_notifier.rb

@@ -0,0 +1,5 @@
+module JsonApiResource
+  module ErrorNotifier
+    autoload :Base,     'json_api_resource/error_notifier/base'
+  end
+end

data/lib/json_api_resource/executable.rb

@@ -0,0 +1,47 @@
+require 'multiconnect'
+
+module JsonApiResource
+  module Executable
+    extend ActiveModel::Callbacks
+    extend ActiveSupport::Concern
+    extend ActiveSupport::Callbacks
+
+    included do
+
+      include Multiconnect::Connectable
+
+      def execute(action, *args)
+        result = nil
+        run_callbacks action do
+          result = connection.execute( action, *args )
+        end
+        result.success?
+      end
+
+      class << self
+        def execute(action, *args)
+          result = request(action, *args)
+          
+          result.map! do |result|
+            new(client: result)
+          end
+        rescue Multiconnect::Error::UnsuccessfulRequest => e
+          
+          result = JsonApiClient::ResultSet.new
+          result.meta = {status: 500}
+
+          result.errors = ActiveModel::Errors.new(result)
+          result.errors.add("ServerError", "Unable to connect to server or server returned 500")
+
+          result
+        end
+      end
+
+      private 
+
+      def connection
+        @connection ||= Connections::ServerConnection.new( client: self.client, caching: false )
+      end
+    end
+  end
+end

data/lib/json_api_resource/queryable.rb

@@ -6,8 +6,8 @@ module JsonApiResource
 
       define_model_callbacks :save, :update_attributes
 
-      around_save   :catch_errors
-      around_update_attributes :catch_errors
+      around_save   :update_meta
+      around_update_attributes :update_meta
 
       class << self
 
@@ -16,26 +16,26 @@ module JsonApiResource
         def find(id)
           return nil unless id.present?
 
-          results = request(:find, id: id)
+          results = execute(:find, id: id)
           JsonApiResource::Handlers::FindHandler.new(results).result # <= <#JsonApiclient::ResultSet @errors => <...>, @data => <...>, @linked_data => <...>>
         end
 
         def where(opts = {})
           opts[:per_page] = opts.fetch(:per_page, self.per_page)
-          request(:where, opts)
+          execute(:where, opts)
         end
       end
 
       
       def save
-        request :save
+        execute :save
       end
 
       def update_attributes(attrs = {})
-        request :update_attributes, attrs
+        execute :update_attributes, attrs
       end
 
-      def catch_errors
+      def update_meta
         yield
 
         self.errors ||= ActiveModel::Errors.new(self)
@@ -43,6 +43,8 @@ module JsonApiResource
           self.errors.add(k.to_sym, Array(messages).join(', '))
         end
         self.errors
+
+        self.meta = self.client.last_request_meta
       end
     end
   end

data/lib/json_api_resource/resource.rb

@@ -19,7 +19,7 @@ module JsonApiResource
     include JsonApiResource::Clientable
     include JsonApiResource::Schemable
     include JsonApiResource::Queryable
-    include JsonApiResource::Requestable
+    include JsonApiResource::Executable
     include JsonApiResource::Conversions
     include JsonApiResource::Cacheable
 
@@ -34,6 +34,7 @@ module JsonApiResource
       self.client = self.client_class.new(self.schema)
       self.errors = ActiveModel::Errors.new(self)
       self.attributes = opts
+      self.populate_missing_fields
     end
 
     def new_record?
@@ -61,15 +62,10 @@ module JsonApiResource
       if match = method.to_s.match(/^(.*=)$/)
         self.client.send(match[0], args.first)
       elsif self.client.respond_to?(method.to_sym)
-        self.client.send(method, *args)
+        connection.execute( method, *args ).data
       else
         super
       end
-
-    rescue JsonApiClient::Errors::ServerError => e
-      add_error e
-    rescue ArgumentError => e
-      raise JsonApiResourceError, class: self.class, message: "#{method}: #{e.message}"
     end
 
     def self.method_missing(method, *args, &block)
@@ -77,7 +73,7 @@ module JsonApiResource
         self.client_class.send(match[0], args.first)
        
       elsif self.client_class.respond_to?(method.to_sym)
-        results = self.client_class.send(method, *args)
+        results = request(method, *args).data
 
         if results.is_a? JsonApiClient::ResultSet
           results.map! do |result|
@@ -86,14 +82,11 @@ module JsonApiResource
         end
 
         results
-
       else
         super
       end
-    rescue JsonApiClient::Errors::ServerError => e
-      empty_set_with_errors e
-    rescue ArgumentError => e
-      raise JsonApiResourceError, class: self, message: "#{method}: #{e.message}"
+    rescue Multiconnect::Error::UnsuccessfulRequest => e
+      nil
     end
 
     def respond_to_missing?(method_name, include_private = false)

data/lib/json_api_resource/schemable.rb

@@ -19,6 +19,16 @@ module JsonApiResource
           self.schema = schema.merge name.to_sym => default
         end
       end
+
+      protected
+
+      def populate_missing_fields
+        self.class.schema.each_pair do |key, value|
+          unless self.attributes.has_key?(key)
+            self.attributes[key] = value
+          end
+        end
+      end
     end
   end
 end

data/lib/json_api_resource/version.rb

@@ -1,3 +1,3 @@
 module JsonApiResource
-  VERSION = "1.0.2"
+  VERSION = "2.0.0"
 end

data/lib/json_api_resource.rb

@@ -3,11 +3,13 @@ require 'json_api_client'
 module JsonApiResource
   autoload :Cacheable,              'json_api_resource/cacheable'
   autoload :Clientable,             'json_api_resource/clientable'
+  autoload :Connections,            'json_api_resource/connections'
   autoload :Conversions,            'json_api_resource/conversions'
+  autoload :ErrorNotifier,          'json_api_resource/error_notifier'
   autoload :Handlers,               'json_api_resource/handlers'
   autoload :JsonApiResourceError,   'json_api_resource/json_api_resource_error'
   autoload :Queryable,              'json_api_resource/queryable'
   autoload :Resource,               'json_api_resource/resource'
-  autoload :Requestable,            'json_api_resource/requestable'
+  autoload :Executable,             'json_api_resource/executable'
   autoload :Schemable,              'json_api_resource/schemable'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: json_api_resource
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Brandon Sislow
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-28 00:00:00.000000000 Z
+date: 2016-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json_api_client
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: multiconnect
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -92,12 +106,16 @@ files:
 - lib/json_api_resource.rb
 - lib/json_api_resource/cacheable.rb
 - lib/json_api_resource/clientable.rb
+- lib/json_api_resource/connections.rb
+- lib/json_api_resource/connections/server_connection.rb
 - lib/json_api_resource/conversions.rb
+- lib/json_api_resource/error_notifier.rb
+- lib/json_api_resource/error_notifier/base.rb
+- lib/json_api_resource/executable.rb
 - lib/json_api_resource/handlers.rb
 - lib/json_api_resource/handlers/find_handler.rb
 - lib/json_api_resource/json_api_resource_error.rb
 - lib/json_api_resource/queryable.rb
-- lib/json_api_resource/requestable.rb
 - lib/json_api_resource/resource.rb
 - lib/json_api_resource/schemable.rb
 - lib/json_api_resource/version.rb
@@ -121,9 +139,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: Build wrapper/adapter objects around JsonApiClient instances
 test_files: []
-has_rdoc: 

data/lib/json_api_resource/requestable.rb

@@ -1,71 +0,0 @@
-module JsonApiResource
-  module Requestable
-    extend ActiveModel::Callbacks
-    extend ActiveSupport::Concern
-    extend ActiveSupport::Callbacks
-
-    included do
-      def request(action, *args)
-        run_callbacks action do
-          self.client.send(action, *args)
-        end
-        self
-
-      rescue JsonApiClient::Errors::ServerError => e
-        add_error e
-      end
-
-      class << self
-        def request(action, *args)
-          result = self.client_class.send(action, *args)
-          
-          result = result.all if result.is_a? JsonApiClient::Scope
-          
-          result.map! do |result|
-            new(client: result)
-          end
-          
-        rescue JsonApiClient::Errors::ServerError => e
-          empty_set_with_errors e
-        end
-
-        def empty_set_with_errors(e)
-          append_errors e do |status, error|
-            error_response status, error
-          end
-        end
-
-        def append_errors(e, &block)
-          case e.class.to_s
-
-          when "JsonApiClient::Errors::NotFound"
-            yield 404, { name: "RecordNotFound", message: e.message }
-
-          when "JsonApiClient::Errors::UnexpectedStatus"
-            yield e.code, { name: "UnexpectedStatus", message: e.message }
-
-          else
-            yield 500, { name: "ServerError", message: e.message }
-          end
-        end
-
-        def error_response(status, error)
-          result = JsonApiClient::ResultSet.new
-
-          result.meta = {status: status}
-
-          result.errors = ActiveModel::Errors.new(result)
-          result.errors.add(error[:name], Array(error[:message]).join(', '))
-
-          result
-        end
-      end
-
-      def add_error(e, &block)
-        self.class.append_errors e do |status, error|
-          errors.add error[:name], error[:message]
-        end
-      end
-    end
-  end
-end