munson 0.2.0 → 0.3.0

data/bin/console

@@ -2,13 +2,5 @@
 
 require "bundler/setup"
 require "munson"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start
+require "pry"
+Pry.start

data/lib/munson/agent.rb

@@ -1,55 +1,12 @@
 module Munson
   class Agent
-    extend Forwardable
-    def_delegators :query, :includes, :sort, :filter, :fields, :fetch, :page
-
-    attr_writer :connection
-
-    attr_accessor :type
-    attr_accessor :query_builder
-
-    attr_reader :paginator
-    attr_accessor :paginator_options
-
     # Creates a new Munson::Agent
     #
-    # @param [Hash] opts={} describe opts={}
-    # @option opts [Munson::Connection] :connection to use
-    # @option opts [#to_s, Munson::Paginator] :paginator to use on query builder
-    # @option opts [Class] :query_builder provide a custom query builder, defaults to {Munson::QueryBuilder}
-    # @option opts [#to_s] :type JSON Spec type. Type will be added to the base path set in the Faraday::Connection
-    def initialize(opts={})
-      @connection    = opts[:connection]
-      @type          = opts[:type]
-
-      @query_builder = opts[:query_builder].is_a?(Class) ?
-        opts[:query_builder] : Munson::QueryBuilder
-
-      self.paginator     = opts[:paginator]
-      @paginator_options = opts[:paginator_options]
-    end
-
-    def paginator=(pager)
-      if pager.is_a?(Symbol)
-        @paginator = Munson.lookup_paginator(pager)
-      else
-        @paginator = pager
-      end
-    end
-
-    # Munson::QueryBuilder factory
-    #
-    # @example creating a query
-    #   @agent.includes('user').sort(age: :desc)
-    #
-    # @return [Munson::QueryBuilder] a query builder
-    def query
-      if paginator
-        query_pager = paginator.new(paginator_options || {})
-        @query_builder.new paginator: query_pager, agent: self
-      else
-        @query_builder.new agent: self
-      end
+    # @param [#to_s] path to JSON API Resource. Path will be added to the base path set in the Faraday::Connection
+    # @param [Munson::Connection] connection to use
+    def initialize(path, connection: nil)
+      @path       = path
+      @connection = connection
     end
 
     # Connection that will be used for HTTP requests
@@ -60,36 +17,42 @@ module Munson
       Munson.default_connection
     end
 
-    def find(id, headers: nil, params: nil)
-      path = [type, id].join('/')
-      response = get(path: path, headers: headers, params: params)
-      ResponseMapper.new(response).resource
-    end
-
     # JSON API Spec GET request
     #
     # @option [Hash,nil] params: nil query params
-    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#type
+    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#default_path
     # @option [Hash] headers: nil HTTP Headers
+    # @option [String,Fixnum] id: nil ID to append to @path (provided in #new) when accessing a resource. If :path and :id are both specified, :path wins
     # @return [Faraday::Response]
-    def get(params: nil, path: nil, headers: nil)
+    def get(params: nil, path: nil, headers: nil, id: nil)
       connection.get(
-        path: (path || type),
+        path: negotiate_path(path, id),
         params: params,
         headers: headers
       )
     end
 
+    def negotiate_path(path = nil, id = nil)
+      if path
+        path
+      elsif id
+        [@path, id].join('/')
+      else
+        @path
+      end
+    end
+
     # JSON API Spec POST request
     #
     # @option [Hash,nil] body: {} query params
-    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#type
+    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#default_path
     # @option [Hash] headers: nil HTTP Headers
     # @option [Type] http_method: :post describe http_method: :post
+    # @option [String,Fixnum] id: nil ID to append to default path when accessing a resource. If :path and :id are both specified, :path wins
     # @return [Faraday::Response]
-    def post(body: {}, path: nil, headers: nil, http_method: :post)
+    def post(body: {}, path: nil, headers: nil, http_method: :post, id: nil)
       connection.post(
-        path: (path || type),
+        path: negotiate_path(path, id),
         body: body,
         headers: headers,
         http_method: http_method
@@ -99,31 +62,34 @@ module Munson
     # JSON API Spec PATCH request
     #
     # @option [Hash,nil] body: nil query params
-    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#type
+    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#default_path
     # @option [Hash] headers: nil HTTP Headers
+    # @option [String,Fixnum] id: nil ID to append to default path when accessing a resource. If :path and :id are both specified, :path wins
     # @return [Faraday::Response]
-    def patch(body: nil, path: nil, headers: nil)
-      post(body, path: path, headers: headers, http_method: :patch)
+    def patch(body: nil, path: nil, headers: nil, id: nil)
+      post(body: body, path: path, headers: headers, http_method: :patch, id: id)
     end
 
     # JSON API Spec PUT request
     #
     # @option [Hash,nil] body: nil query params
-    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#type
+    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#default_path
     # @option [Hash] headers: nil HTTP Headers
+    # @option [String,Fixnum] id: nil ID to append to default path when accessing a resource. If :path and :id are both specified, :path wins
     # @return [Faraday::Response]
-    def put(body: nil, path: nil, headers: nil)
-      post(body, path: path, headers: headers, http_method: :put)
+    def put(body: nil, path: nil, headers: nil, id: nil)
+      post(body: body, path: path, headers: headers, http_method: :put, id: id)
     end
 
     # JSON API Spec DELETE request
     #
     # @option [Hash,nil] body: nil query params
-    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#type
+    # @option [String] path: nil path to GET, defaults to Faraday::Connection url + Agent#default_path
     # @option [Hash] headers: nil HTTP Headers
+    # @option [String,Fixnum] id: nil ID to append to default path when accessing a resource. If :path and :id are both specified, :path wins
     # @return [Faraday::Response]
-    def delete(body: nil, path: nil, headers: nil)
-      post(body, path: path, headers: headers, http_method: :delete)
+    def delete(body: nil, path: nil, headers: nil, id: nil)
+      post(body: body, path: path, headers: headers, http_method: :delete, id: id)
     end
   end
 end

data/lib/munson/attribute.rb

@@ -0,0 +1,76 @@
+module Munson
+  class Attribute
+    attr_reader :name
+    attr_reader :cast_type
+    attr_reader :options
+
+    def initialize(name, cast_type, options={})
+      options[:default] ||= nil
+      options[:array]   ||= false
+      @name      = name
+      @cast_type = cast_type
+      @options   = options
+    end
+
+    # Process a raw JSON value
+    def process(value)
+      value.nil? ? default_value : cast(value)
+    end
+
+    # Super naive casting!
+    def cast(value)
+      return (@options[:array] ? [] : nil) if value.nil?
+      value.is_a?(Array) ?
+        value.map { |v| cast_value(v) } :
+        cast_value(value)
+    end
+
+    def cast_value(value)
+      return nil if value.nil?
+
+      case cast_type
+      when Proc
+        cast_type.call(value)
+      when :string, :to_s, String
+        value.to_s
+      when :integer, :to_i, Fixnum
+        value.to_i
+      when :bigdecimal
+        BigDecimal.new(value.to_s)
+      when :float, :to_f, Float
+        value.to_f
+      when :date, Date
+        Date.parse(value) rescue nil
+      when :time, Time
+        Time.parse(value) rescue nil
+      else
+        value
+      end
+    end
+
+
+    # Serializes the value back to JSON datatype
+    #
+    def serialize(value)
+      case options[:serialize]
+      when Proc
+        options[:serialize].call(value)
+      when Symbol
+        value.send(options[:serialize])
+      else
+        value
+      end
+    end
+
+    def default_value
+      case @options[:default]
+      when Proc
+        @options[:default].call
+      when nil
+        @options[:array] ? [] : nil
+      else
+        @options[:default].clone
+      end
+    end
+  end
+end

data/lib/munson/client.rb

@@ -0,0 +1,43 @@
+module Munson
+  class Client
+    extend Forwardable
+    def_delegators :query, :include, :sort, :filter, :fields, :fetch, :page, :find
+    def_delegators :connection, :url=, :url, :response_key_format, :response_key_format=
+
+    attr_writer :path
+    attr_writer :query_builder
+    attr_accessor :type
+
+    def initialize(opts={})
+      opts.each do |k,v|
+        setter = "#{k}="
+        send(setter,v) if respond_to?(setter)
+      end
+    end
+
+    def query
+      (@query_builder || Query).new(self)
+    end
+
+    def agent
+      Agent.new(path, connection: connection)
+    end
+
+    def path
+      @path || "/#{type}"
+    end
+
+    def configure(&block)
+      yield(self)
+      self
+    end
+
+    def connection
+      @connection ||= Munson.default_connection.clone
+    end
+
+    def connection=(connection)
+      @connection = connection
+    end
+  end
+end

data/lib/munson/collection.rb

@@ -1,4 +1,22 @@
 module Munson
-  class Collection < ::Array
+  class Collection
+    include Enumerable
+    extend Forwardable
+    def_delegator :@collection, :last
+    
+    attr_reader :meta
+    attr_reader :jsonapi
+    attr_reader :links
+
+    def initialize(collection=[], errors: nil, meta: nil, jsonapi: nil, links: nil)
+      @collection = collection
+      @meta       = meta
+      @jsonapi    = jsonapi
+      @links      = links
+    end
+
+    def each(&block)
+      @collection.each(&block)
+    end
   end
 end

data/lib/munson/connection.rb

@@ -7,6 +7,7 @@ module Munson
     # @private
     attr_reader :faraday, :options
 
+    CONNECTION_OPTIONS = [:response_key_format].freeze
     FARADAY_OPTIONS = [:request, :proxy, :ssl, :builder, :url,
       :parallel_manager, :params, :headers, :builder_class].freeze
 
@@ -14,21 +15,35 @@ module Munson
     # a faraday connection that includes two pieces of middleware for handling
     # JSON API Spec
     #
-    # @param [Hash] opts {Munson::Connection} configuration options
+    # @param [Hash] args {Munson::Connection} configuration arguments
     # @param [Proc] block to yield to Faraday::Connection
     # @see https://github.com/lostisland/faraday/blob/master/lib/faraday/connection.rb Faraday::Connection
     #
+    # @example Setting the key format
+    #   $my_connection = Munson::Connection.new response_key_format: :dasherize, url: "http://api.example.com" do |c|
+    #     c.use Your::Custom::Middleware
+    #   end
+    #
+    #   $my_connection = Munson::Connection.new response_key_format: :camelize, url: "http://api.example.com" do |c|
+    #     c.use Your::Custom::Middleware
+    #   end
+    #
     # @example Creating a new connection
-    #   my_connection = Munson::Connection.new url: "http://api.example.com" do |c|
+    #   $my_connection = Munson::Connection.new url: "http://api.example.com" do |c|
     #     c.use Your::Custom::Middleware
     #   end
     #
-    #   class User
-    #     include Munson::Resource
-    #     munson.connection = my_connection
+    #   class User < Munson::Resource
+    #     self.type = :users
+    #     munson.connection = $my_connection
     #   end
-    def initialize(opts, &block)
-      configure(opts, &block)
+    def initialize(args, &block)
+      configure(args, &block)
+    end
+
+    # Clones a connection
+    def clone
+      Connection.new(options.dup, &@block)
     end
 
     # JSON API Spec GET request
@@ -43,7 +58,7 @@ module Munson
     def get(path: nil, params: nil, headers: nil)
       faraday.get do |request|
         request.headers.merge!(headers) if headers
-        request.url path.to_s, params
+        request.url path.to_s, externalize_keys(params)
       end
     end
 
@@ -55,14 +70,13 @@ module Munson
     # @option [Type] http_method: :post describe http_method: :post
     # @return [Faraday::Response]
     def post(body: {}, path: nil, headers: nil, http_method: :post)
-      connection.faraday.send(http_method) do |request|
+      faraday.send(http_method) do |request|
         request.headers.merge!(headers) if headers
         request.url path.to_s
         request.body = body
       end
     end
 
-
     # Configure the connection
     #
     # @param [Hash] opts {Munson::Connection} configuration options
@@ -82,18 +96,51 @@ module Munson
     #   Munson::Connection.new url: "http://api.example.com" do |c|
     #     c.use MyTokenAuth
     #   end
-    def configure(opts={}, &block)
-      @options = opts
+    def configure(args={}, &block)
+      # Cache these for #clone method
+      @options = args
+      @block = block
 
       faraday_options = @options.reject { |key, value| !FARADAY_OPTIONS.include?(key.to_sym) }
       @faraday = Faraday.new(faraday_options) do |conn|
         yield conn if block_given?
 
-        conn.use Munson::Middleware::EncodeJsonApi
-        conn.use Munson::Middleware::JsonParser
+        conn.request :"Munson::Middleware::EncodeJsonApi", key_formatter
+        conn.response :"Munson::Middleware::JsonParser", key_formatter
 
         conn.adapter Faraday.default_adapter
       end
     end
+
+    (CONNECTION_OPTIONS + FARADAY_OPTIONS).each do |option_writer|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        # Set the option value and reconfigure this connection
+        def #{option_writer}=(value)
+          @options[:#{option_writer}] = value
+          configure(@options, &@block)
+          @options[:#{option_writer}]
+        end
+      RUBY
+    end
+
+    def url
+      faraday.url_prefix.to_s
+    end
+
+    def response_key_format
+      @options[:response_key_format]
+    end
+
+    private def key_formatter
+      response_key_format ? Munson::KeyFormatter.new(response_key_format) : nil
+    end
+
+    private def externalize_keys(value)
+      if response_key_format && value.is_a?(Hash)
+        key_formatter.externalize(value)
+      else
+        value
+      end
+    end
   end
 end

data/lib/munson/document.rb

@@ -0,0 +1,140 @@
+module Munson
+  class Document
+    attr_accessor :id
+    attr_reader :type
+
+    def initialize(jsonapi_document)
+      @id   = jsonapi_document[:data][:id]
+      @type = jsonapi_document[:data][:type].to_sym
+      @jsonapi_document = jsonapi_document
+
+      if jsonapi_document[:data] && jsonapi_document[:data][:attributes]
+        @original_attributes = jsonapi_document[:data][:attributes].clone
+        @attributes          = jsonapi_document[:data][:attributes].clone
+      else
+        @original_attributes = {}
+        @attributes          = {}
+      end
+    end
+
+    # @return [Hash] hash for persisting this JSON API Resource via POST/PATCH/PUT
+    def payload
+      doc = { data: { type: @type } }
+      if id
+        doc[:data][:id] = id
+        doc[:data][:attributes] = changed
+      else
+        doc[:data][:attributes] = attributes
+      end
+      doc
+    end
+
+    def data
+      @jsonapi_document[:data]
+    end
+
+    def included
+      @jsonapi_document[:included] || []
+    end
+
+    def attributes
+      @attributes
+    end
+
+    def attributes=(attrs)
+      @attributes.merge!(attrs)
+    end
+
+    def changes
+      attributes.reduce({}) do |memo, (k,v)|
+        if @original_attributes[k] != attributes[k]
+          memo[k] = [@original_attributes[k], attributes[k]]
+        end
+        memo
+      end
+    end
+
+    def changed
+      attributes.reduce({}) do |memo, (k,v)|
+        if @original_attributes[k] != attributes[k]
+          memo[k] = attributes[k]
+        end
+        memo
+      end
+    end
+
+    def save(agent)
+      response = if id
+        agent.patch(id: id.to_s, body: payload)
+      else
+        agent.post(body: payload)
+      end
+
+      Munson::Document.new(response.body)
+    end
+
+    def url
+      links[:self]
+    end
+
+    def [](key)
+      attributes[key]
+    end
+
+    def errors
+      data[:errors] || []
+    end
+
+    # Raw relationship hashes
+    def relationships
+      data[:relationships] || {}
+    end
+
+    def links
+      data[:links] || {}
+    end
+
+    def meta
+      data[:meta] || {}
+    end
+
+    # Initialized {Munson::Document} from #relationships
+    # @param [Symbol] name of relationship
+    def relationship(name)
+      if relationship_data(name).is_a?(Array)
+        relationship_data(name).map { |meta_data| find_included_item(meta_data) }
+      elsif relationship_data(name).is_a?(Hash)
+        find_included_item(relationship_data(name))
+      else
+        raise RelationshipNotFound, <<-ERR
+        The relationship `#{name}` was called, but does not exist on the document.
+        Relationships available are: #{relationships.keys.join(',')}
+        ERR
+      end
+    end
+
+    def relationship_data(name)
+      relationships[name] ? relationships[name][:data] : nil
+    end
+
+    # @param [Hash] relationship from JSONAPI relationships hash
+    # @return [Munson::Document,nil] the included relationship, if found
+    private def find_included_item(relationship)
+      resource = included.find do |included_resource|
+        included_resource[:type] == relationship[:type] &&
+          included_resource[:id] == relationship[:id]
+      end
+
+      if resource
+        Document.new(data: resource, included: included)
+      else
+        raise RelationshipNotIncludedError, <<-ERR
+        The relationship `#{relationship[:type]}` was called,
+        but it was not included in the request.
+
+        Try adding `include=#{relationship[:type]}` to your query.
+        ERR
+      end
+    end
+  end
+end

data/lib/munson/key_formatter.rb

@@ -0,0 +1,87 @@
+class Munson::KeyFormatter
+  # @param [Symbol] resource_key_format
+  def initialize(resource_key_format)
+    @format = resource_key_format
+  end
+
+  # Converts underscored keys to `format`
+  def externalize(hash)
+    deep_transform_keys(hash) do |key|
+      if @format == :dasherize
+        dasherize(key)
+      elsif @format == :camelize
+        camelize(key)
+      else
+        raise UnrecognizedKeyFormatter, <<-ERR
+        No key formatter found for `#{@format}`.
+
+        Valid :key_format values are `:camelize` and `:underscore`.
+        You may also provide a hash of lambdas `{format:->(key){}, unformat:->(key){}}`
+        ERR
+      end
+    end
+  end
+
+  # Converts keys formatted in `format` to underscore
+  def internalize(hash)
+    deep_transform_keys(hash) do |key|
+      if @format == :dasherize
+        undasherize(key)
+      elsif @format == :camelize
+        underscore(key)
+      else
+        raise UnrecognizedKeyFormatter, <<-ERR
+        No key formatter found for `#{@format}`.
+
+        Valid :key_format values are `:camelize` and `:underscore`.
+        You may also provide a hash of lambdas `{format:->(key){}, unformat:->(key){}}`
+        ERR
+      end
+    end
+  end
+
+  private
+    def deep_transform_keys(hash, &block)
+      result = {}
+      hash.each do |key, value|
+        result[yield(key)] = map_value(value, &block)
+      end
+      result
+    end
+
+    def map_value(value, &block)
+      case value
+      when Hash
+        deep_transform_keys(value, &block)
+      when Array
+        value.map { |v| map_value(v, &block) }
+      else
+        value
+      end
+    end
+
+    def camelize(key)
+      string = key.to_s
+      string = string.sub(/^(?:(?=\b|[A-Z_])|\w)/) { |match| match.downcase }
+      string.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
+      string.to_sym
+    end
+
+    def underscore(camel_cased_word)
+      return camel_cased_word unless camel_cased_word =~ /[A-Z-]|::/
+      word = camel_cased_word.to_s
+      word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2'.freeze)
+      word.gsub!(/([a-z\d])([A-Z])/, '\1_\2'.freeze)
+      word.tr!("-".freeze, "_".freeze)
+      word.downcase!
+      word.to_sym
+    end
+
+    def undasherize(key)
+      key.to_s.tr('-'.freeze, '_'.freeze).to_sym
+    end
+
+    def dasherize(key)
+      key.to_s.tr('_'.freeze, '-'.freeze).to_sym
+    end
+end