munson 0.1.0

data/lib/munson/connection.rb

@@ -0,0 +1,99 @@
+module Munson
+  # Faraday::Connection wrapper for making JSON API Requests
+  #
+  # @attr_reader [Faraday::Connection] faraday connection object
+  # @attr_reader [Hash] options
+  class Connection
+    # @private
+    attr_reader :faraday, :options
+
+    FARADAY_OPTIONS = [:request, :proxy, :ssl, :builder, :url,
+      :parallel_manager, :params, :headers, :builder_class].freeze
+
+    # Create a new connection. A connection serves as a thin wrapper around a
+    # a faraday connection that includes two pieces of middleware for handling
+    # JSON API Spec
+    #
+    # @param [Hash] opts {Munson::Connection} configuration options
+    # @param [Proc] block to yield to Faraday::Connection
+    # @see https://github.com/lostisland/faraday/blob/master/lib/faraday/connection.rb Faraday::Connection
+    #
+    # @example Creating a new connection
+    #   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
+    #   end
+    def initialize(opts, &block)
+      configure(opts, &block)
+    end
+
+    # JSON API Spec GET request
+    #
+    # @example making a GET request
+    #   @connection.get(path: 'addresses', params: {include: 'user'}, headers: {'X-API-Token' => '2kewl'})
+    #
+    # @option [Hash,nil] params: nil query params
+    # @option [String] path: nil to GET
+    # @option [Hash] headers: nil HTTP Headers
+    # @return [Faraday::Response]
+    def get(path: nil, params: nil, headers: nil)
+      faraday.get do |request|
+        request.headers.merge!(headers) if headers
+        request.url path.to_s, params
+      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 [Hash] headers: nil HTTP Headers
+    # @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|
+        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
+    # @return Faraday::Connection
+    #
+    # @example Setting up the default API connection
+    #   Munson::Connection.new url: "http://api.example.com"
+    #
+    # @example A custom middleware added to the default list
+    #   class MyTokenAuth < Faraday::Middleware
+    #     def call(env)
+    #       env[:request_headers]["X-API-Token"] = "SECURE_TOKEN"
+    #       @app.call(env)
+    #     end
+    #   end
+    #
+    #   Munson::Connection.new url: "http://api.example.com" do |c|
+    #     c.use MyTokenAuth
+    #   end
+    def configure(opts={}, &block)
+      @options = opts
+
+      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.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/munson/middleware/encode_json_api.rb

@@ -0,0 +1,43 @@
+module Munson
+  module Middleware
+    class EncodeJsonApi < Faraday::Middleware
+      CONTENT_TYPE = 'Content-Type'.freeze
+      ACCEPT       = 'Accept'.freeze
+      MIME_TYPE    = 'application/vnd.api+json'.freeze
+
+      def call(env)
+        env[:request_headers][ACCEPT] ||= MIME_TYPE
+        match_content_type(env) do |data|
+          env[:body] = encode data
+        end
+        @app.call env
+      end
+
+      def encode(data)
+        ::JSON.dump data
+      end
+
+      def match_content_type(env)
+        if process_request?(env)
+          env[:request_headers][CONTENT_TYPE] ||= MIME_TYPE
+          yield env[:body] unless env[:body].respond_to?(:to_str)
+        end
+      end
+
+      def process_request?(env)
+        type = request_type(env)
+        has_body?(env) and (type.empty? or type == MIME_TYPE)
+      end
+
+      def has_body?(env)
+        body = env[:body] and !(body.respond_to?(:to_str) and body.empty?)
+      end
+
+      def request_type(env)
+        type = env[:request_headers][CONTENT_TYPE].to_s
+        type = type.split(';', 2).first if type.index(';')
+        type
+      end
+    end
+  end
+end

data/lib/munson/middleware/json_parser.rb

@@ -0,0 +1,22 @@
+module Munson
+  module Middleware
+    class JsonParser < Faraday::Middleware
+      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])
+        end
+      end
+
+      private
+
+      def parse(body)
+        unless body.strip.empty?
+          ::JSON.parse(body, symbolize_names: true)
+        else
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/munson/model.rb

@@ -0,0 +1,15 @@
+# module Munson
+#   module Model
+#     extend ActiveSupport::Concern
+#
+#     included do
+#       self.include Munson::Resource
+#     end
+#
+#     class_methods do
+#       def has_many(*);end;
+#       def has_one(*);end;
+#       def belongs_to(*);end;
+#     end
+#   end
+# end

data/lib/munson/paginator/offset_paginator.rb

@@ -0,0 +1,44 @@
+module Munson
+  module Paginator
+    class OffsetPaginator
+      def initialize(options={})
+        @max_limit = options[:max]
+        @default_limit = options[:default]
+      end
+
+      def set(opts={})
+        limit(opts[:limit]) if opts[:limit]
+        offset(opts[:offset]) if opts[:offset]
+      end
+
+      def to_params
+        {
+          page: {
+            limit: @limit || @default_limit || 10,
+            offset: @offset
+          }.compact
+        }
+      end
+
+      private
+
+      # Set limit of resources per page
+      #
+      # @param [Fixnum] num number of resources per page
+      def limit(num)
+        if @max_limit && num > @max_limit
+          @limit = @max_limit
+        else
+          @limit = num
+        end
+      end
+
+      # Set offset
+      #
+      # @param [Fixnum] num pages to offset
+      def offset(num)
+        @offset = num
+      end
+    end
+  end
+end

data/lib/munson/paginator/paged_paginator.rb

@@ -0,0 +1,45 @@
+module Munson
+  module Paginator
+    class PagedPaginator
+      def initialize(options={})
+        @max_size = options[:max]
+        @default_size = options[:default]
+      end
+
+      def set(opts={})
+        number(opts[:number]) if opts[:number]
+        size(opts[:size]) if opts[:size]
+      end
+
+      def to_params
+        {
+          page: {
+            size: @size || @default_size || 10,
+            number: @number
+          }.compact
+        }
+      end
+
+      private
+
+      # Set number of resources per page
+      #
+      # @param [Fixnum] num number of resources per page
+      def size(num)
+        if @max_size && num > @max_size
+          @size = @max_size
+        else
+          @size = num
+        end
+      end
+
+      # Set page number
+      #
+      # @param [Fixnum] num page number
+      def number(num)
+        @number = num
+      end
+
+    end
+  end
+end

data/lib/munson/paginator.rb

@@ -0,0 +1,6 @@
+module Munson
+  module Paginator
+    autoload :OffsetPaginator, "munson/paginator/offset_paginator"
+    autoload :PagedPaginator, "munson/paginator/paged_paginator"
+  end
+end

data/lib/munson/query_builder.rb

@@ -0,0 +1,226 @@
+module Munson
+  class QueryBuilder
+    attr_reader :query
+    attr_reader :paginator
+    attr_reader :agent
+    class UnsupportedSortDirectionError < StandardError; end;
+    class PaginatorNotSet < StandardError; end;
+    class AgentNotSet < StandardError; end;
+
+    # Description of method
+    #
+    # @param [Class] paginator: nil instantiated paginator
+    # @param [Class] agent: nil instantiated agent to use for fetching results
+    # @return [Type] description of returned object
+    def initialize(paginator: nil, agent: nil)
+      @paginator = paginator
+      @agent = agent
+
+      @query = {
+        include: [],
+        fields:  [],
+        filter:  [],
+        sort:    []
+      }
+    end
+
+    # @return [String] query as a query string
+    def to_query_string
+      to_params.to_query
+    end
+
+    def to_s
+      to_query
+    end
+
+    def to_params
+      str = {}
+      str[:filter] = filter_to_query_value unless @query[:filter].empty?
+      str[:fields] = fields_to_query_value unless @query[:fields].empty?
+      str[:include] = includes_to_query_value unless @query[:include].empty?
+      str[:sort] = sort_to_query_value unless @query[:sort].empty?
+
+      str.merge!(paginator.to_params) if paginator
+
+      str
+    end
+
+    # Fetches resources using {Munson::Agent}
+    #
+    # @return [Array] Array of resources
+    def fetch
+      if @agent
+        response = @agent.get(params: to_params)
+        resources = ResponseMapper.new(response).resources
+        Collection.new(resources)
+      else
+        raise AgentNotSet, "Agent was not set. QueryBuilder#new(agent:)"
+      end
+    end
+
+    def paging?
+      !!paginator
+    end
+
+    # Paginator proxy
+    #
+    # @return [Class,nil] paginator if set
+    def page(opts={})
+      if paging?
+        paginator.set(opts)
+        self
+      else
+        raise PaginatorNotSet, "Paginator was not set. QueryBuilder#new(paginator:)"
+      end
+    end
+
+    # Chainably include related resources.
+    #
+    # @example including a resource
+    #   Munson::QueryBuilder.new.includes(:user)
+    #
+    # @example including a related resource
+    #   Munson::QueryBuilder.new.includes("user.addresses")
+    #
+    # @example including multiple resources
+    #   Munson::QueryBuilder.new.includes("user.addresses", "user.images")
+    #
+    # @param [Array<String,Symbol>] *args relationships to include
+    # @return [Munson::QueryBuilder] self for chaining queries
+    #
+    # @see http://jsonapi.org/format/#fetching-includes JSON API Including Relationships
+    def includes(*args)
+      @query[:include] += args
+      self
+    end
+
+    # Chainably sort results
+    # @note Default order is ascending
+    #
+    # @example sorting by a single field
+    #   Munsun::QueryBuilder.new.sort(:created_at)
+    #
+    # @example sorting by a multiple fields
+    #   Munsun::QueryBuilder.new.sort(:created_at, :age)
+    #
+    # @example specifying sort direction
+    #   Munsun::QueryBuilder.new.sort(:created_at, age: :desc)
+    #
+    # @example specifying sort direction
+    #   Munsun::QueryBuilder.new.sort(score: :desc, :created_at)
+    #
+    # @param [Hash<Symbol,Symbol>, Symbol] *args fields to sort by
+    # @return [Munson::QueryBuilder] 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)})
+      @query[:sort] += args
+      self
+    end
+
+    # Hash resouce_name: [array of attribs]
+    def fields(*args)
+      @query[:fields] += args
+      self
+    end
+
+    def filter(*args)
+      @query[:filter] += args
+      self
+    end
+
+    def self.includes(*args)
+      new.includes(*args)
+    end
+
+    def self.sort(*args)
+      new.sort(*args)
+    end
+
+    def self.fields(*args)
+      new.fields(*args)
+    end
+
+    def self.filter(*args)
+      new.filter(*args)
+    end
+
+    protected
+
+    def sort_to_query_value
+      @query[: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
+      @query[: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 includes_to_query_value
+      @query[:include].map(&:to_s).sort.join(',')
+    end
+
+    # Since the filter query 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 CustomQueryBuilder inheriting from {Munson::QueryBuilder}
+    # {Munson::Agent} takes a QueryBuilder class to use. This method could be overriden in your custom class
+    #
+    # @example Custom Query Builder
+    #   class MyBuilder < Munson::QueryBuilder
+    #     def filter_to_query_value
+    #       # ... your fancier logic
+    #     end
+    #   end
+    #
+    #   class Article
+    #     def self.munson
+    #       return @munson if @munson
+    #       @munson = Munson::Agent.new(
+    #         query_builder: MyBuilder
+    #         path: 'products'
+    #       )
+    #     end
+    #   end
+    #
+    def filter_to_query_value
+      @query[: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 UnsupportedSortDirectionError, "Unknown direction '#{v}'. Use :asc or :desc"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/munson/resource.rb

@@ -0,0 +1,26 @@
+module Munson
+  module Resource
+    extend ActiveSupport::Concern
+
+    included do
+      def self.munson
+        return @munson if @munson
+        @munson = Munson::Agent.new
+        @munson
+      end
+
+      self.munson.type = name.demodulize.tableize
+      Munson.register_type(self.munson.type, self)
+    end
+
+    class_methods do
+      [:includes, :sort, :filter, :fields, :fetch, :find, :page].each do |method|
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{method}(*args)
+            munson.#{method}(*args)
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/munson/response_mapper.rb

@@ -0,0 +1,54 @@
+module Munson
+  class ResponseMapper
+    class UnsupportedDatatype < StandardError;end;
+
+    def initialize(response)
+      @data     = response.body[:data]
+      @includes = response.body[:include]
+    end
+
+    def resources
+      if data_is_collection?
+        map_data(@data)
+      else
+        raise StandardError, "Called #resources, but response was a single resource. Use ResponseMapper#resource"
+      end
+    end
+
+    def resource
+      if data_is_resource?
+        map_data(@data)
+      else
+        raise StandardError, "Called #resource, but response was a collection of resources. Use ResponseMapper#resources"
+      end
+    end
+
+    private
+
+    def data_is_resource?
+      @data.is_a?(Hash)
+    end
+
+    def data_is_collection?
+      @data.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
+    end
+
+    def map_resource(resource)
+      if klass = Munson.lookup_type(resource[:type])
+        klass.new(resource[:attributes].merge(id: resource[:id]))
+      else
+        resource
+      end
+    end
+  end
+end

data/lib/munson/version.rb

@@ -0,0 +1,3 @@
+module Munson
+  VERSION = "0.1.0"
+end

data/lib/munson.rb

@@ -0,0 +1,70 @@
+require 'json'
+
+require 'active_support/concern'
+require "active_support/inflector"
+require "active_support/core_ext/hash"
+
+require 'faraday'
+require 'faraday_middleware'
+
+require "munson/version"
+
+require "munson/middleware/encode_json_api"
+require "munson/middleware/json_parser"
+
+require 'munson/collection'
+require 'munson/paginator'
+require 'munson/response_mapper'
+require 'munson/query_builder'
+require 'munson/connection'
+require 'munson/agent'
+require 'munson/resource'
+
+module Munson
+  @registered_types = {}
+  class << self
+    # Configure the default connection.
+    #
+    # @param [Hash] opts {Munson::Connection} configuration options
+    # @param [Proc] block to yield to Faraday::Connection
+    # @return [Munson::Connection] the default connection
+
+    # @see https://github.com/lostisland/faraday/blob/master/lib/faraday/connection.rb Faraday::Connection
+    # @see Munson::Connection
+    def configure(opts={}, &block)
+      @default_connection = Munson::Connection.new(opts, &block)
+    end
+
+    # The default connection
+    #
+    # @return [Munson::Connection, nil] the default connection if configured
+    def default_connection
+      defined?(@default_connection) ? @default_connection : nil
+    end
+
+    # Register a JSON Spec resource type to a class
+    # This is used in Faraday response middleware to package the JSON into a domain model
+    #
+    # @example Mapping a type
+    #   Munson.register_type("addresses", Address)
+    #
+    # @param [#to_s] type JSON Spec type
+    # @param [Class] klass to map to
+    def register_type(type, klass)
+      @registered_types[type] = klass
+    end
+
+    # Lookup a class by JSON Spec type name
+    #
+    # @param [#to_s] type JSON Spec type
+    # @return [Class] domain model
+    def lookup_type(type)
+      @registered_types[type]
+    end
+
+    # @private
+    def flush_types!
+      @registered_types = {}
+    end
+  end
+end

data/munson.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'munson/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "munson"
+  spec.version       = Munson::VERSION
+  spec.authors       = ["Cory O'Daniel"]
+  spec.email         = ["cory@coryodaniel.com"]
+
+  spec.summary       = %q{A JSON API Spec client for Ruby}
+  spec.homepage      = "http://github.com/coryodaniel/munson"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday"
+  spec.add_dependency "faraday_middleware"
+  spec.add_dependency "activesupport"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency 'rspec-mocks'
+  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-byebug"
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'yard-activesupport-concern'
+  spec.add_development_dependency 'webmock'
+end