munson 0.2.0 → 0.3.0

data/lib/munson/middleware/encode_json_api.rb

@@ -4,7 +4,12 @@ module Munson
       CONTENT_TYPE = 'Content-Type'.freeze
       ACCEPT       = 'Accept'.freeze
       MIME_TYPE    = 'application/vnd.api+json'.freeze
-      USER_AGENT   = 'User-Agent'
+      USER_AGENT   = 'User-Agent'.freeze
+
+      def initialize(app, key_formatter = nil)
+        super(app)
+        @key_formatter = key_formatter
+      end
 
       def call(env)
         env[:request_headers][USER_AGENT] = "Munson v#{Munson::VERSION}"
@@ -16,7 +21,8 @@ module Munson
       end
 
       def encode(data)
-        ::JSON.dump data
+        json = @key_formatter ? @key_formatter.externalize(data) : data
+        ::JSON.dump(json)
       end
 
       def match_content_type(env)
@@ -43,3 +49,5 @@ module Munson
     end
   end
 end
+
+Faraday::Request.register_middleware :"Munson::Middleware::EncodeJsonApi" => Munson::Middleware::EncodeJsonApi

data/lib/munson/middleware/json_parser.rb

@@ -1,10 +1,14 @@
 module Munson
   module Middleware
-    class JsonParser < Faraday::Middleware
+    class JsonParser < Faraday::Response::Middleware
+      def initialize(app, key_formatter = nil)
+        super(app)
+        @key_formatter = key_formatter
+      end
+
       def call(request_env)
-        @app.call(request_env).on_complete do |response_env|
-          response_env[:raw_body] = response_env[:body]
-          response_env[:body] = parse(response_env[:body])
+        @app.call(request_env).on_complete do |request_env|
+          request_env[:body] = parse(request_env[:body])
         end
       end
 
@@ -12,7 +16,8 @@ module Munson
 
       def parse(body)
         unless body.strip.empty?
-          ::JSON.parse(body, symbolize_names: true)
+          json = ::JSON.parse(body, symbolize_names: true)
+          @key_formatter ? @key_formatter.internalize(json) : json
         else
           {}
         end
@@ -20,3 +25,4 @@ module Munson
     end
   end
 end
+Faraday::Response.register_middleware :"Munson::Middleware::JsonParser" => Munson::Middleware::JsonParser

data/lib/munson/query.rb

@@ -0,0 +1,218 @@
+module Munson
+  class Query
+    attr_reader :values
+
+    # Description of method
+    #
+    # @param [Munson::Client] client
+    def initialize(client = nil)
+      @client   = client
+      @headers  = {}
+      @values    = {
+        include: [],
+        fields:  [],
+        filter:  [],
+        sort:    [],
+        page:    {}
+      }
+    end
+
+    def fetch
+      if @client
+        response = @client.agent.get(params: to_params, headers: @headers)
+        ResponseMapper.new(response.body).collection
+      else
+        raise Munson::ClientNotSet, "Client was not set. Query#new(client)"
+      end
+    end
+
+    def find(id)
+      if @client
+        response = @client.agent.get(id: id, params: to_params, headers: @headers)
+        ResponseMapper.new(response.body).resource
+      else
+        raise Munson::ClientNotSet, "Client was not set. Query#new(client)"
+      end
+    end
+
+    # @return [String] query as a query string
+    def to_query_string
+      Faraday::Utils.build_nested_query(to_params)
+    end
+
+    def to_s
+      to_query_string
+    end
+
+    def to_params
+      str = {}
+      str[:filter]  = filter_to_query_value unless @values[:filter].empty?
+      str[:fields]  = fields_to_query_value unless @values[:fields].empty?
+      str[:include] = include_to_query_value unless @values[:include].empty?
+      str[:sort]    = sort_to_query_value unless @values[:sort].empty?
+      str[:page]    = @values[:page] unless @values[:page].empty?
+      str
+    end
+
+    # Chainably set page options
+    #
+    # @example set a limit and offset
+    #   Munson::Query.new.page(limit: 10, offset: 5)
+    #
+    # @example set a size and number
+    #   Munson::Query.new.page(size: 10, number: 5)
+    #
+    # @return [Munson::Query] self for chaining queries
+    def page(opts={})
+      @values[:page].merge!(opts)
+      self
+    end
+
+    # Chainably set headers
+    #
+    # @example set a header
+    #   Munson::Query.new.headers("X-API-TOKEN" => "banana")
+    #
+    # @example set headers
+    #   Munson::Query.new.headers("X-API-TOKEN" => "banana", "X-API-VERSION" => "1.3")
+    #
+    # @return [Munson::Query] self for chaining queries
+    def headers(opts={})
+      @headers.merge!(opts)
+      self
+    end
+
+    # Chainably include related resources.
+    #
+    # @example including a resource
+    #   Munson::Query.new.include(:user)
+    #
+    # @example including a related resource
+    #   Munson::Query.new.include("user.addresses")
+    #
+    # @example including multiple resources
+    #   Munson::Query.new.include("user.addresses", "user.images")
+    #
+    # @param [Array<String,Symbol>] *args relationships to include
+    # @return [Munson::Query] self for chaining queries
+    #
+    # @see http://jsonapi.org/format/#fetching-includes JSON API Including Relationships
+    def include(*args)
+      @values[:include] += args
+      self
+    end
+
+    # Chainably sort results
+    # @note Default order is ascending
+    #
+    # @example sorting by a single field
+    #   Munsun::Query.new.sort(:created_at)
+    #
+    # @example sorting by a multiple fields
+    #   Munsun::Query.new.sort(:created_at, :age)
+    #
+    # @example specifying sort direction
+    #   Munsun::Query.new.sort(:created_at, age: :desc)
+    #
+    # @example specifying sort direction
+    #   Munsun::Query.new.sort(score: :desc, :created_at)
+    #
+    # @param [Hash<Symbol,Symbol>, Symbol] *args fields to sort by
+    # @return [Munson::Query] self for chaining queries
+    #
+    # @see http://jsonapi.org/format/#fetching-sorting JSON API Sorting Spec
+    def sort(*args)
+      validate_sort_args(args.select{|arg| arg.is_a?(Hash)})
+      @values[:sort] += args
+      self
+    end
+
+    # Hash resouce_name: [array of attribs]
+    def fields(*args)
+      @values[:fields] += args
+      self
+    end
+
+    def filter(*args)
+      @values[:filter] += args
+      self
+    end
+
+    protected
+
+    def sort_to_query_value
+      @values[:sort].map{|item|
+        if item.is_a?(Hash)
+          item.to_a.map{|name,dir|
+            dir.to_sym == :desc ? "-#{name}" : name.to_s
+          }
+        else
+          item.to_s
+        end
+      }.join(',')
+    end
+
+    def fields_to_query_value
+      @values[:fields].inject({}) do |acc, hash_arg|
+        hash_arg.each do |k,v|
+          acc[k] ||= []
+          v.is_a?(Array) ?
+            acc[k] += v :
+            acc[k] << v
+
+          acc[k].map(&:to_s).uniq!
+        end
+
+        acc
+      end.map { |k, v| [k, v.join(',')] }.to_h
+    end
+
+    def include_to_query_value
+      @values[:include].map(&:to_s).sort.join(',')
+    end
+
+    # Since the filter param's format isn't specified in the [spec](http://jsonapi.org/format/#fetching-filtering)
+    # this implemenation uses (JSONAPI::Resource's implementation](https://github.com/cerebris/jsonapi-resources#filters)
+    #
+    # To override, implement your own CustomQuery inheriting from {Munson::Query}
+    # {Munson::Client} takes a Query class to use. This method could be overriden in your custom class
+    #
+    # @example Custom Query Builder
+    #   class MyBuilder < Munson::Query
+    #     def filter_to_query_value
+    #       # ... your fancier logic
+    #     end
+    #   end
+    #
+    #   class Article
+    #     def self.munson
+    #       return @munson if @munson
+    #       @munson = Munson::Client.new(
+    #         query_builder: MyQuery,
+    #         path: 'products'
+    #       )
+    #     end
+    #   end
+    #
+    def filter_to_query_value
+      @values[:filter].reduce({}) do |acc, hash_arg|
+        hash_arg.each do |k,v|
+          acc[k] ||= []
+          v.is_a?(Array) ? acc[k] += v : acc[k] << v
+          acc[k].uniq!
+        end
+        acc
+      end.map { |k, v| [k, v.join(',')] }.to_h
+    end
+
+    def validate_sort_args(hashes)
+      hashes.each do |hash|
+        hash.each do |k,v|
+          if !%i(desc asc).include?(v.to_sym)
+            raise Munson::UnsupportedSortDirectionError, "Unknown direction '#{v}'. Use :asc or :desc"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/munson/resource.rb

@@ -1,28 +1,182 @@
-module Munson
-  module Resource
-    def self.included(base)
-      base.extend ClassMethods
+class Munson::Resource
+  extend Forwardable
+  attr_reader :document
+  attr_reader :attributes
+
+  # @example Given a Munson::Document
+  #   document = Munson::Document.new(jsonapi_hash)
+  #   Person.new(document)
+  #
+  # @example Given an attributes hash
+  #   Person.new(first_name: "Chauncy", last_name: "Vünderboot")
+  #
+  # @param [Hash,Munson::Document] attrs
+  def initialize(attrs = {})
+    if attrs.is_a?(Munson::Document)
+      @document = attrs
+    else
+      @document = Munson::Document.new(
+        data: {
+          type: self.class.type,
+          id: attrs.delete(:id),
+          attributes: attrs
+        }
+      )
     end
 
-    module ClassMethods
-      def munson
-        return @munson if @munson
-        @munson = Munson::Agent.new
-        @munson
-      end
-      
-      def register_munson_type(name)
-        Munson.register_type(name, self)
-        self.munson.type = name
+    initialize_attrs
+  end
+
+  def id
+    return nil if document.id.nil?
+    @id ||= self.class.format_id(document.id)
+  end
+
+  def initialize_attrs
+    @attributes = @document.attributes.clone
+    self.class.schema.each do |name, attribute|
+      casted_value = attribute.process(@attributes[name])
+      @attributes[name] = casted_value
+    end
+  end
+
+  def persisted?
+    !id.nil?
+  end
+
+  def save
+    @document = document.save(agent)
+    !errors?
+  end
+
+  # @return [Array<Hash>] array of JSON API errors
+  def errors
+    document.errors
+  end
+
+  def errors?
+    document.errors.any?
+  end
+
+  # @return [Munson::Agent] a new {Munson::Agent} instance
+  def agent
+    self.class.munson.agent
+  end
+
+  def serialized_attributes
+    serialized_attrs = {}
+    self.class.schema.each do |name, attribute|
+      serialized_value = attribute.serialize(@attributes[name])
+      serialized_attrs[name] = serialized_value
+    end
+    serialized_attrs
+  end
+
+  def ==(other)
+    self.class.type == other.class.type && self.id == other.id
+  end
+
+  class << self
+    def inherited(subclass)
+      if subclass.to_s.respond_to?(:tableize)
+        subclass.type = subclass.to_s.tableize.to_sym
       end
+    end
 
-      [:includes, :sort, :filter, :fields, :fetch, :find, :page].each do |method|
-        class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          def #{method}(*args)
-            munson.#{method}(*args)
-          end
-        RUBY
+    def key_type(type)
+      @key_type = type
+    end
+
+    def format_id(id)
+      case @key_type
+      when :integer, nil
+        id.to_i
+      when :string
+        id.to_s
+      when Proc
+        @key_type.call(id)
       end
     end
+
+    def schema
+      @schema ||= {}
+    end
+
+    def attribute(attribute_name, cast_type, **options)
+      schema[attribute_name] = Munson::Attribute.new(attribute_name, cast_type, options)
+
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{attribute_name}
+          @attributes[:#{attribute_name}]
+        end
+      RUBY
+
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{attribute_name}=(val)
+          document.attributes[:#{attribute_name}] = self.class.schema[:#{attribute_name}].serialize(val)
+          @attributes[:#{attribute_name}] = val
+        end
+      RUBY
+    end
+
+    def has_one(relation_name)
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{relation_name}
+          return @_#{relation_name}_relationship if @_#{relation_name}_relationship
+          related_document = document.relationship(:#{relation_name})
+          @_#{relation_name}_relationship = Munson.factory(related_document)
+        end
+      RUBY
+    end
+
+    def has_many(relation_name)
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{relation_name}
+          return @_#{relation_name}_relationship if @_#{relation_name}_relationship
+          documents  = document.relationship(:#{relation_name})
+          collection = Munson::Collection.new(documents.map{ |doc| Munson.factory(doc) })
+          @_#{relation_name}_relationship = collection
+        end
+      RUBY
+    end
+
+    def munson_initializer(document)
+      new(document)
+    end
+
+    def munson
+      return @munson if @munson
+      @munson = Munson::Client.new
+      @munson
+    end
+
+    # Set the JSONAPI type
+    def type=(type)
+      Munson.register_type(type, self)
+      munson.type = type
+    end
+
+    # Get the JSONAPI type
+    def type
+      munson.type
+    end
+
+    # Overwrite Connection#fields delegator to allow for passing an array of fields
+    # @example
+    #   Cat.fields(:name, :favorite_toy) #=> Query(fields[cats]=name,favorite_toy)
+    #   Cat.fields(name, owner: [:name]) #=> Query(fields[cats]=name&fields[people]=name)
+    def fields(*args)
+      hash_fields = args.last.is_a?(Hash) ? args.pop : {}
+      hash_fields[type] = args if args.any?
+      munson.fields(hash_fields)
+    end
+
+    [:include, :sort, :filter, :fetch, :find, :page].each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}(*args)
+          munson.#{method}(*args)
+        end
+      RUBY
+    end
   end
 end

data/lib/munson/response_mapper.rb

@@ -1,54 +1,114 @@
 module Munson
+  # Maps JSONAPI Responses to ruby objects.
+  #
+  # @note
+  #   When a JSONAPI collection (data: <Array>) is received it maps the response
+  #   into multiple JSONAPI resource objects (data: <Hash>) and passes each to the #initialize_resource method
+  #   so that each resource can act independently of the collection. JSONAPI collection are wrapped in a Munson::Collection
+  #   which will also contain metadata from the request
+  #
+  # @example Mapping an unregistered JSONAPI collection response
+  #   json   = {
+  #     data: [
+  #       {id: 1, type: :cats, attributes: {name: 'Gorbypuff'}},
+  #       {id: 1, type: :cats, attributes: {name: 'Grumpy Cat'}}
+  #     ]
+  #   }
+  #
+  #   mapper = ResponseMapper.new(json)
+  #   mapper.collection #=>
+  #   Munson::Collection([
+  #     {data: {id: 1, type: :cats, attributes: {name: 'Gorbypuff'}}},
+  #     {data: {id: 1, type: :cats, attributes: {name: 'Grumpy Cat'}}
+  #   ])
+  #
+  # @example Mapping a registered JSONAPI collection response
+  #   json   = {
+  #     data: [
+  #       {id: 1, type: :cats, attributes: {name: 'Gorbypuff'}},
+  #       {id: 1, type: :cats, attributes: {name: 'Grumpy Cat'}}
+  #     ]
+  #   }
+  #   class Cat
+  #     #... munson config
+  #     def self.munson_initializer(resource)
+  #       Cat.new(resource)
+  #     end
+  #
+  #     def new(attribs)
+  #       #do what you want
+  #     end
+  #   end
+  #   Munson.register_type(:cats, Cat)
+  #
+  #   mapper.collection #=> Munson::Collection([cat1, cat2])
+  #
+  # ResourceMapper maps responses in 3 ways:
+  # @example Mapping a Munson::Resource
+  #
+  # @example Mapping a registered type
+  #
+  # @example Mapping an unregistered type
+  #
   class ResponseMapper
-    class UnsupportedDatatype < StandardError;end;
-
-    def initialize(response)
-      @data     = response.body[:data]
-      @includes = response.body[:include]
+    # @param [Hash] response_body jsonapi formatted hash
+    def initialize(response_body)
+      @body = response_body
     end
 
-    def resources
-      if data_is_collection?
-        map_data(@data)
+    # Moved top level keys to the collection
+    # * errors: an array of error objects
+    # * meta: a meta object that contains non-standard meta-information.
+    # * jsonapi: an object describing the server’s implementation
+    # * links: a links object related to the primary data.
+    def collection
+      if errors?
+        raise Exception, "IMPLEMENT ERRORS JERK"
+      elsif collection?
+        # Make each item in :data its own document, stick included into that document
+        records = @body[:data].reduce([]) do |agg, resource|
+          json = { data: resource }
+          json[:included] = @body[:included] if @body[:included]
+          agg << json
+          agg
+        end
+
+        Collection.new(records.map{ |datum| Munson.factory(datum) },
+          meta:    @body[:meta],
+          jsonapi: @body[:jsonapi],
+          links:   @body[:links]
+        )
       else
-        raise StandardError, "Called #resources, but response was a single resource. Use ResponseMapper#resource"
+        raise Munson::Error, "Called #collection, but response was a single resource. Use ResponseMapper#resource"
       end
     end
 
     def resource
-      if data_is_resource?
-        map_data(@data)
+      if errors?
+        raise Exception, "IMPLEMENT ERRORS JERK"
+      elsif resource?
+        Munson.factory(@body)
       else
-        raise StandardError, "Called #resource, but response was a collection of resources. Use ResponseMapper#resources"
+        raise Munson::Error, "Called #resource, but response was a collection of resources. Use ResponseMapper#collection"
       end
     end
 
-    private
-
-    def data_is_resource?
-      @data.is_a?(Hash)
+    def jsonapi_resources
+      data = collection? ? @body[:data] : [@body[:data]]
+      included = @body[:included] || []
+      (data + included)
     end
 
-    def data_is_collection?
-      @data.is_a?(Array)
+    private def errors?
+      @body[:errors].is_a?(Array)
     end
 
-    def map_data(data)
-      if data_is_collection?
-        @data.map{ |datum| map_resource(datum) }
-      elsif data_is_resource?
-        map_resource(@data)
-      else
-        raise UnsupportedDatatype, "No mapping rule for #{data.class}"
-      end
+    private def resource?
+      @body[:data].is_a?(Hash)
     end
 
-    def map_resource(resource)
-      if klass = Munson.lookup_type(resource[:type])
-        klass.new(resource[:attributes].merge(id: resource[:id]))
-      else
-        resource
-      end
+    private def collection?
+      @body[:data].is_a?(Array)
     end
   end
 end

data/lib/munson/version.rb

@@ -1,3 +1,3 @@
 module Munson
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end