smooth_operator 0.4.4 → 1.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZDdlYTY3OGVhODk3ZWEzY2RkMTJjMGMyZmFiYmI2MTkzZTUwNDMyMg==
+    ZDVjYjVmMmQ5NDBjMjM3ZDFhODA0Y2FlODhmNzAxYmU2ZjJhMWU3Nw==
   data.tar.gz: !binary |-
-    MmZiZTg4YTc3ZGI0OTI2OTA5ZTRiZjkyZDhkYzliMmMzNWE3NDUxYg==
-!binary "U0hBNTEy":
+    MjhlNzJlYTA1YTc4OTgxYzlkZTUyOTczN2M3NDY2NzdhZGQ0YzczZQ==
+SHA512:
   metadata.gz: !binary |-
-    YzdkZDE5MjY4MjZkYzA4M2ZiNGVlNzMzZTViOWM5ZWIzY2FiMGYwZGMzZjJh
-    OTQ0NzYxMWI5ZmNhMjYzM2Y1Y2FkOGIyNmIyNmVkNzNiMmM3NGRkYTRiMjU3
-    YTA2YzNkMjVmZDAzMTFjZThmNDZhNWFhNWRjYWZmM2Y4YTgwYTE=
+    YzgxZjhhZTYzNjMxZmZiYmIyOWUzODAzYjg4OGUwYzgxOTRiMmUxMjJhZTIx
+    ODE1NTRhYTg2NmE4OTY1ZGExNzUyYzFjZTM5NjU2ZjljOWJiMGExNmMxNmJj
+    YTEyYmY0NDAxMzc4ZTQxNmJlYjMyMGM1ODJmOThhOTdhNTcxYzI=
   data.tar.gz: !binary |-
-    ZDY3ZmVjZmMyNDIxNmRhMWZmMzc2ZGUyNjNjOWQ0NzdkZjZjNTUxNTU5NmI0
-    N2FmYjk4M2IyY2YzNDZlM2UwMzlmNDgxNDg1NDI4NTJkODcwODkzNDY3ZmZh
-    NWUwYmJlNGYwNGQ1MTEzYzRmOGIyMDgxYTc2MDcxY2U4OGFhYWY=
+    YmNiZThmOGQyZTI5OWU5MTZiMTAwMjNjOTI5YTdhNmEzZWNhMTdjM2MwNDgz
+    Nzg1MzM2ZWRlODEwYmY1ZDY2OGRiNTBkMDhiYmJiM2UwMDAxZjVhN2JkYTQ0
+    NjNiNGU1N2ZkYWEwMWI3YmY4NGMyNjU5NWQ2MDkwMjJlZTdlNzk=

data/.gitignore

@@ -16,4 +16,5 @@ test/tmp
 test/version_tmp
 tmp
 
-.DS_Store
+.DS_Store
+.rvmrc

data/.rspec

@@ -0,0 +1,4 @@
+--tty
+--color
+--format documentation
+--format html -o "tmp/rspec_result.html"

data/Gemfile

@@ -2,3 +2,16 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in smooth_operator.gemspec
 gemspec
+
+gem 'simplecov', :require => false, :group => :test
+
+group :development, :test do
+  gem "pry"
+  gem "sinatra"
+  gem "typhoeus"
+  gem "activesupport"
+  gem "sinatra-contrib"
+  gem "rspec", "~> 3.0.0.beta1"
+  gem "factory_girl", "~> 4.0"
+  gem "ethon", :git => 'https://github.com/goncalvesjoao/ethon'
+end

data/README.md

@@ -1,8 +1,15 @@
 # SmoothOperator
 
-TODO: Write a gem description
+Ruby gem, that mimics the ActiveRecord behaviour but through external API's.
+It's a lightweight and flexible alternative to ActiveResource, that responds to a REST API like you expect it too.
 
-## Installation
+Depends only on Faraday gem, no need for ActiveSupport or any other Active* gem.
+
+Although if I18n is present it will respond to .human_attribute_name method and if ActiveModel is present it will make use of 'ActiveModel::Name' to improve .model_name method.
+
+---
+
+## 1) Installation
 
 Add this line to your application's Gemfile:
 
@@ -16,14 +23,255 @@ Or install it yourself as:
 
     $ gem install smooth_operator
 
-## Usage
+---
+
+## 2) Usage and Examples
+
+```ruby
+class MyBlogResource < SmoothOperator::Base
+  self.endpoint = 'http://myblog.com/api/v0'
+
+  # HTTP BASIC AUTH
+  self.endpoint_user = 'admin'
+  self.endpoint_pass = 'admin'
+end
+
+class Post < MyBlogResource
+end
+```
+
+---
+
+### 2.1) Creating a .new 'Post' and #save it
+
+```ruby
+post = Post.new(body: 'my first post', author: 'John Doe')
+
+post.new_record?     # true
+post.persisted?     # false
+post.body           # 'my first post'
+post.author         # 'John Doe'
+post.something_else # will raise NoMethodError
+
+save_result = post.save # will make a http POST call to 'http://myblog.com/api/v0/posts'
+                        # with `{ post: { body: 'my first post', author: 'John Doe' } }`
+
+post.last_remote_call # will contain a SmoothOperator::RemoteCall instance containing relevant information about the save remote call.
+
+# If the server response is positive (http code between 200 and 299):
+save_result       # true
+post.new_record?  # false
+post.persisted?   # true
+# server response contains { id: 1 } on its body
+post.id # 1
+
+# If the server response is negative (http code between 400 and 499):
+save_result       # false
+post.new_record?  # true
+post.persisted?   # false
+# server response contains { errors: { body: ['must be less then 10 letters'] } }
+post.errors.body # Array
+
+# If the server response is an error (http code between 500 and 599), or the connection was broke:
+save_result       # nil
+post.new_record?  # true
+post.persisted?   # false
+# server response contains { errors: { body: ['must be less then 10 letters'] } }
+post.errors # will raise NoMethodError
+
+  # In the positive and negative server response comes with a json,
+  # e.g. { id: 1 }, post will reflect that new data
+  post.id # 1
+
+  # In case of error and the server response contains a json,
+  # e.g. { id: 1 }, post will NOT reflect that data
+  post.id # raise NoMethodError
+
+```
+
+---
+
+### 2.2) Editing an existing record
+```ruby
+post = Post.find(2)
+
+post.body = 'editing my second page'
+
+post.save
+```
+
+---
+
+### 2.3) Customize #save 'url', 'params' and 'options'
+```ruby
+post = Post.new(id: 2, body: 'editing my second page')
+
+post.new_record? # false
+post.persisted?  # true
+
+post.save("#{post.id}/save_and_add_to_list", { admin: true, post: { author: 'Agent Smith', list_id: 1 } }, { timeout: 1 })
+# Will make a PUT to 'http://myblog.com/api/v0/posts/2/save_and_add_to_list'
+# with { admin: true, post: { body: 'editing my second page', list_id: 1 } }
+# and will only wait 1sec for the server to respond.
+```
+
+---
+
+### 2.4) Saving using HTTP Patch verb
+```ruby
+class Page < MyBlogResource
+  self.update_http_verb = :patch
+end
+
+page = Page.find(2)
+
+page.body = 'editing my second page'
+
+page.save # will make a http PATCH call to 'http://myblog.com/api/v0/pages/2'
+          # with `{ page: { body: 'editing my second page' } }`
+```
+
+---
+
+### 2.5) Retrieving remote objects - 'index' REST action
+
+```ruby
+remote_call = Page.find(:all) # Will make a GET call to 'http://myblog.com/api/v0/pages'
+                              # and will return a SmoothOperator::RemoteCall instance
+
+pages = remote_call.objects # 'pages = remote_call.data' also works
+
+# If the server response is positive (http code between 200 and 299):
+  remote_call.ok? # true
+  remote_call.not_processed? # false
+  remote_call.error? # false
+  remote_call.status # true
+  pages = remote_call.data # array of Page instances
+  remote_call.http_status # server_response code
+
+# If the server response is unprocessed entity (http code 422):
+  remote_call.ok? # false
+  remote_call.not_processed? # true
+  remote_call.error? # false
+  remote_call.status # false
+  remote_call.http_status # server_response code
+
+# If the server response is client error (http code between 400..499, except 422):
+  remote_call.ok? # false
+  remote_call.not_processed? # false
+  remote_call.error? # true
+  remote_call.status # nil
+  remote_call.http_status # server_response code
+
+# If the server response is server error (http code between 500 and 599), or the connection broke:
+  remote_call.ok? # false
+  remote_call.not_processed? # false
+  remote_call.error? # true
+  remote_call.status # nil
+  remote_call.http_status # server_response code or 0 if connection broke
+```
+
+---
+
+### 2.6) Retrieving remote objects - 'show' REST action
+
+```ruby
+remote_call = Page.find(2) # Will make a GET call to 'http://myblog.com/api/v0/pages/2'
+                           # and will return a SmoothOperator::RemoteCall instance
+
+page = remote_call.object # 'page = remote_call.data' also works
+```
+
+---
+
+### 2.7) Retrieving remote objects - custom query
+```ruby
+remote_call = Page.find('my_pages', { q: body_contains: 'link' }, { endpoint_user: 'admin', endpoint_pass: 'new_password' })
+# will make a GET call to 'http://myblog.com/api/v0/pages/my_pages?q={body_contains="link"}'
+# and will change the HTTP BASIC AUTH credentials to user: 'admin' and pass: 'new_password' for this connection only.
+
+# If the server json response is an Array [{ id: 1 }, { id: 2 }]
+  pages = remote.data # will return an array with 2 Page's instances
+  pages[0].id # 1
+  pages[1].id # 2
+
+# If the server json response is a Hash { id: 3 }
+  page = remote.data # will return a single Page instance
+  page.id # 3
+
+# If the server json response is Hash with a key called 'pages' { page: 1, total: 3, pages: [{ id: 4 }, { id: 5 }] }
+  pages = remote.data # will return a single ArrayWithMetaData instance, that will allow you to access to both the Page's instances array and the metadata.
+  pages.page # 1
+  pages.total # 3
+
+  pages[0].id # 4
+  pages[1].id # 5
+```
+
+---
+
+## 3) Methods
+
+---
+
+### 3.1) Persistence methods
+
+Methods | Behaviour | Arguments | Return
+------- | --------- | ------ | ---------
+.create | Generates a new instance of the class with *attributes and calls #save with the rest of its arguments| Hash attributes = nil, String relative_path = nil, Hash data = {}, Hash options = {} | Class instance
+#new_record? | Returns @new_record if defined, else populates it with true if #id is present or false if blank. | - | Boolean
+#destroyed?| Returns @destroyed if defined, else populates it with false. | - | Boolean
+#persisted?| Returns true if both #new_record? and #destroyed? return false, else returns false. | - | Boolean
+#save | if #new_record? makes a HTTP POST, else a PUT call. If !#new_record? and relative_path is blank, sets relative_path = id.to_s. If the server POST response is positive, sets @new_record = false. See 4.2) for more behaviour info. | String relative_path = nil, Hash data = {}, Hash options = {} | Boolean or Nil
+#save! | Executes the same behaviour as #save, but will raise RecordNotSaved if the returning value is not true | String relative_path = nil, Hash data = {}, Hash options = {} | Boolean or Nil
+#destroy | Does nothing if !persisted? else makes a HTTP DELETE call. If server response it positive, sets @destroyed = true. If relative_path is blank, sets relative_path = id.to_s. See 4.2) for more behaviour info. | String relative_path = nil, Hash data = {}, Hash options = {} | Boolean or Nil
+
+---
+
+### 3.2) Finder methods
+
+Methods | Behaviour | Arguments | Return
+------- | --------- | ------ | ---------
+.find | If relative_path == :all, sets relative_path = ''. Makes a Get call and initiates Class objects with the server's response data. See 4.3) and 4.4) for more behaviour info. | String relative_path, Hash data = {}, Hash options = {} | Class instance, Array of Class instances or an ArrayWithMetaData instance
+
+---
+
+### 3.3) Operator methods
+...
+
+---
+
+### 3.3) Remote call methods
+...
+
+---
+
+## 4) Behaviours
+
+---
+
+### 4.1) Delegation behaviour
+...
+
+---
+
+### 4.2) Persistent operator behaviour
+...
+
+---
+
+### 4.3) Operator behaviour
+...
+
+---
+
+### 4.4) Remote call behaviour
+...
 
-TODO: Write usage instructions here
+---
 
-## Contributing
+## 4) TODO
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+1. Finish "Methods" and "Behaviours" documentation;
+2. ModelSchema specs;
+3. Cache.

data/console.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH << './'
+$LOAD_PATH << './lib'
+
+require 'spec/require_helper'
+
+FactoryGirl.find_definitions
+
+LocalhostServer.new(TestServer.new, 4567)
+
+# user = nil
+
+# hydra = Typhoeus::Hydra::hydra
+
+# user = User::Base.new(id: 1)
+# user.reload(nil, nil, { hydra: hydra })
+
+# User::Base.find(1, nil, { hydra: hydra }) do |remote_call|
+#   user = remote_call.data
+# end
+
+#User::Base.post('', { user: { age: 1, posts: [{ body: 'post1' }, 2] } })
+
+#user = UserWithAddressAndPosts::Son.new(FactoryGirl.attributes_for(:user_with_address_and_posts))
+#user.save('', { status: 200 })
+
+# "[{\"patient_id\"=>33, \"messages\"=>[{\"id\"=>\"53722c20cb38247c36000003\", \"title\"=>\"Joao Goncalves\", \"created_at\"=>\"2014-05-13T14:28:48Z\"}, {\"id\"=>\"53722bfccb382485d5000002\", \"title\"=>\"Joao Goncalves\", \"created_at\"=>\"2014-05-13T14:28:12Z\"}, {\"id\"=>\"53722b91cb3824e913000001\", \"title\"=>\"Joao Goncalves\", \"created_at\"=>\"2014-05-13T14:26:25Z\"}]}]"
+
+post = Post.new(comments: [{ id: 1, name: '1' }, { id: 2, name: '2' }], address: { id: 1, name: 'address' })
+
+class Test < SimpleDelegator
+  def reload
+    "TODO"
+  end
+end
+
+class Test2 < Test
+  def reload2
+    "TODO2"
+  end
+end
+
+binding.pry

data/lib/smooth_operator/array_with_meta_data.rb

@@ -0,0 +1,31 @@
+module SmoothOperator
+  class ArrayWithMetaData < OpenStruct::Base
+
+    extend Forwardable
+
+    include Enumerable
+
+    attr_reader :meta_data, :internal_array
+
+    def_delegators :internal_array, :length, :<<, :[]
+
+    def initialize(attributes, object_class)
+      _attributes, _resources_name = attributes.dup, object_class.resources_name
+
+      @internal_array = [*_attributes[_resources_name]].map { |array_entry| object_class.new(array_entry).tap { |object| object.reloaded = true } }
+      _attributes.delete(_resources_name)
+
+      @meta_data = _attributes
+    end
+
+    def each
+      internal_array.each { |array_entry| yield array_entry }
+    end
+
+    def method_missing(method, *args, &block)
+      _method = method.to_s
+      meta_data.include?(_method) ? meta_data[_method] : super
+    end
+
+  end
+end

data/lib/smooth_operator/attribute_assignment.rb

@@ -0,0 +1,102 @@
+require 'smooth_operator/attributes/base'
+require 'smooth_operator/attributes/dirty'
+require 'smooth_operator/attributes/normal'
+
+module SmoothOperator
+
+  module AttributeAssignment
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      attr_writer :unknown_hash_class
+
+      def unknown_hash_class
+        Helpers.get_instance_variable(self, :unknown_hash_class, ::OpenStruct)
+      end
+
+      def attributes_white_list
+        Helpers.get_instance_variable(self, :attributes_white_list, Set.new)
+      end
+
+      def attributes_black_list
+        Helpers.get_instance_variable(self, :attributes_black_list, Set.new)
+      end
+
+      def attributes_white_list_add(*getters)
+        attributes_white_list.merge getters.map(&:to_s)
+      end
+
+      def attributes_black_list_add(*getters)
+        attributes_black_list.merge getters.map(&:to_s)
+      end
+
+      def dirty_attributes
+        @dirty_attributes = true
+      end
+
+      def dirty_attributes?
+        @dirty_attributes
+      end
+
+    end
+
+    def initialize(attributes = {}, options = {})
+      @_options = {}
+
+      before_initialize(attributes, options)
+
+      assign_attributes attributes, options
+
+      after_initialize(attributes, options)
+    end
+
+    attr_reader :_options, :_meta_data
+
+
+    def assign_attributes(_attributes = {}, options = {})
+      return nil unless _attributes.is_a?(Hash)
+
+      attributes = _attributes = Helpers.stringify_keys(_attributes)
+
+      if _attributes.include?(self.class.resource_name)
+        attributes = _attributes.delete(self.class.resource_name)
+        @_meta_data = _attributes
+      end
+
+      options.each { |key, value| @_options[key] = value } if options.is_a?(Hash)
+
+      attributes.each { |name, value| push_to_internal_data(name, value, true) }
+    end
+
+    def parent_object
+      _options[:parent_object]
+    end
+
+    def has_data_from_server
+      _options[:from_server] == true
+    end
+
+    alias :from_server :has_data_from_server
+
+    protected #################### PROTECTED METHODS DOWN BELOW ######################
+
+    def before_initialize(attributes, options); end
+
+    def after_initialize(attributes, options); end
+
+    def allowed_attribute(attribute)
+      if !self.class.attributes_white_list.empty?
+        self.class.attributes_white_list.include?(attribute)
+      elsif !self.class.attributes_black_list.empty?
+        !self.class.attributes_black_list.include?(attribute)
+      else
+        true
+      end
+    end
+
+  end
+end

data/lib/smooth_operator/attribute_methods.rb

@@ -0,0 +1,87 @@
+module SmoothOperator
+  module AttributeMethods
+
+    def internal_data
+      @internal_data ||= {}
+    end
+
+    def get_internal_data(field, method = :value)
+      result = internal_data[field]
+
+      if result.nil?
+        nil
+      elsif method == :value
+        result.is_a?(Attributes::Dirty) ? internal_data[field].send(method) : internal_data[field]
+      else
+        internal_data[field].send(method)
+      end
+    end
+
+    def get_attribute_type(attribute)
+      self.class.internal_structure[attribute.to_s]
+    end
+
+    def push_to_internal_data(attribute_name, attribute_value, cast = false)
+      attribute_name = attribute_name.to_s
+
+      return nil unless allowed_attribute(attribute_name)
+
+      known_attributes.add attribute_name
+
+      if internal_data[attribute_name].nil?
+        initiate_internal_data(attribute_name, attribute_value, cast)
+      else
+        update_internal_data(attribute_name, attribute_value, cast)
+      end
+
+      if self.class.respond_to?(:smooth_operator?)
+        trigger_necessary_events(attribute_name, attribute_value)
+      end
+    end
+
+    def column_for_attribute(attribute_name)
+      if defined?(ActiveRecord)
+        type = get_attribute_type(attribute_name)
+        ActiveRecord::ConnectionAdapters::Column.new(attribute_name.to_sym, type, type)
+      else
+        nil
+      end
+    end
+
+    protected #################### PROTECTED METHODS DOWN BELOW ######################
+
+    def trigger_necessary_events(attribute_name, attribute_value)
+      mark_for_destruction?(attribute_value) if attribute_name == self.class.destroy_key
+
+      new_record?(true) if attribute_name == self.class.primary_key
+    end
+
+    private ######################## PRIVATE #############################
+
+    def initiate_internal_data(attribute_name, attribute_value, cast)
+      if cast
+        internal_data[attribute_name] = new_attribute_object(attribute_name, attribute_value)
+
+        internal_data[attribute_name] = internal_data[attribute_name].value unless self.class.dirty_attributes?
+      else
+        internal_data[attribute_name] = attribute_value
+      end
+    end
+
+    def update_internal_data(attribute_name, attribute_value, cast)
+      if self.class.dirty_attributes?
+        internal_data[attribute_name].set_value(attribute_value, self)
+      else
+        internal_data[attribute_name] = cast ? new_attribute_object(attribute_name, attribute_value).value : attribute_value
+      end
+    end
+
+    def new_attribute_object(attribute_name, attribute_value)
+      attribute_class = self.class.dirty_attributes? ?  Attributes::Dirty : Attributes::Normal
+
+      attribute_class.new(attribute_name, attribute_value, self)
+    end
+
+  end
+
+end