json_apiable 0.3 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d67de4927cb04df83deea484a0890bdfdc36cbf48d6bda986000ffabcda8f3b
-  data.tar.gz: a90a940bc16d451c698355f1e18c74a5e183135ed3315f7aa272ad9a37e345f5
+  metadata.gz: 87003258543205a662a1a5963258ad69746fee6b5813a52a35cb604c7481488a
+  data.tar.gz: 13bc1aaeb033f6200a165f3b4d2878fd01a6478b0aa8c4348c455ea912929dfc
 SHA512:
-  metadata.gz: ee5e99fac5548996d4222e3b281ca8d3d03c78e95b57414c08b8f6f624497140c1eff43d0f5e5d54a3c2c2fec9501e92b09d37deb2e5c688c132161ca88f031c
-  data.tar.gz: 8d36927df5f8684188cc4e6f4ef263640429ddff9a84f9824860fe1ff1519c94fdb1b90642291681d5612478e9913ca818539a1f2c8d642657dba2d24d0f6a48
+  metadata.gz: 6b0a0a5be9cf7c2b43cd4a8cdb3a6cb9b68064cc5c97735c620e215a15cde00655243a8442b35d11a72c63664a3dce7e44d89abf444711e5ec5adf80941eaabb
+  data.tar.gz: 9968c847fbabe70821f12dc4ab991ae6ff1d3f1a197a9daae016e427a624a39b5e88ff18f15e8906b78e4d408b466c703103afd7de12acb5aa8548c5f92b77a2

data/.rubocop.yml

@@ -0,0 +1,39 @@
+AllCops:
+  TargetRubyVersion: 2.4
+  Exclude:
+    - 'db/**/*'
+    - 'bin/**/*'
+    - 'config/**/*'
+    - 'spec/**/*'
+    - 'json_apiable.gemspec'
+    - 'Gemfile'
+    - 'Rakefile'
+
+Metrics:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+
+Style/HashSyntax:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+Layout/DotPosition:
+  EnforcedStyle: trailing
+
+

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    json_apiable (0.3)
+    json_apiable (0.4)
       activerecord (>= 4.2)
       activesupport (>= 4.2)
       fast_jsonapi (~> 1.5)

data/README.md

@@ -1,4 +1,6 @@
 # JsonApiable
+[![Maintainability](https://api.codeclimate.com/v1/badges/add92f51e18446e44b29/maintainability)](https://codeclimate.com/github/mikemarsian/json_apiable/maintainability)
+[![Gem Version](https://badge.fury.io/rb/json_apiable.svg)](https://badge.fury.io/rb/json_apiable)
 
 JsonApiable is a Ruby module that makes it easier for Rails API controllers to handle JSON:API parameter and relationship parsing,
 strong parameter validation, returning well-structured errors and more - all in a Rails-friendly way.
@@ -54,7 +56,7 @@ class API::PostsController < API::BaseController
   # GET /v1/posts
   def index
     # pass page and include info to your logic
-    posts = GetPostsService.call(jsonapi_page, jsonapi_include)
+    posts = GetPostsService.call(jsonapi_page_hash, jsonapi_include_array)
     # some other gem, such as fast_jsonapi is assumed to produce the json:api output
     render json: posts
   end
@@ -97,7 +99,7 @@ class API::PostsController < API::BaseController
     # 
     # } 
     @post.update_attributes!(jsonapi_assign_params)
-    render json: @user
+    render json: @post
   end
 
   def create
@@ -111,7 +113,7 @@ class API::PostsController < API::BaseController
     @comments_hash = jsonapi_exclude_relationship(:comments)
     do_some_logc_with_excluded_params
     # jsonapi_assign_params wouldn't include 'author' attribute and 'comments' relationship
-    User.create!(jsonapi_assign_params)
+    Post.create!(jsonapi_assign_params)
   end
 
   protected
@@ -132,6 +134,76 @@ class API::PostsController < API::BaseController
 
 end
 ````
+### Filters
+JsonApiable supports parsing filter requests in the form `example.com/v1/posts?filter[status]=draft` and returning errors
+in case provided filter keys or values do not adhere to what you define:
+
+```ruby
+# Create filter class that inherits from JsonApiable::BaseFilter
+class API::PostFilter < JsonApiable::BaseFilter
+# Declare which filter keys are supported
+  def self.jsonapi_allowed_filters
+    {
+      # For each key, declare what values are allowed. The supported value matchers include: 
+      # 1) Array of values
+      # example.com/v1/posts?filter[status]=draft,published 
+      status: Post.statuses.keys,
+      
+      # 2) DateTime matcher - proc that checks that the provided value is a valid DateTime
+      # example.com/v1/posts?filter[published_at]='2001-02-03T04:05:06+03:00' 
+      published_at: datetime_matcher,
+      
+      # 3) Boolean matcher - proc that checks that the provided value is a boolean (true/t/1 for True, false/f/0 for False)
+      # example.com/v1/posts?filter[subscribers_only]=true       
+      subscribers_only: boolean_matcher,
+      
+      # 4) ID matcher - proc that checks that the provided ids exist for given model
+      # example.com/v1/posts?filter[ids]=10893,14596
+      ids: ids_matcher(Post),
+      
+      # Of course, you can also implement your own matchers. For example:
+      reviewed_at: recent_datetime_matcher 
+    }
+  end
+
+  # Example of custom filter value matcher
+  def self.recent_datetime_matcher
+    proc do |value|
+      datetime = Time.zone.parse(value)
+      datetime.present? && datetime > 10.years.ago && datetime < 2.years.from_now
+    end
+  end
+end
+```
+Now set the filter for actions which should support filtering:
+```ruby
+class API::PostsController < API::BaseController
+  before_action -> { set_jsonapi_filter(API::PostFilter) }, only: %i[index search]
+end
+
+```
+And you are good to go! 
+
+Incidentally, PostFilter class is also a good place to implement your filter logic:
+```ruby
+class API::PostFilter < JsonApiable::BaseFilter
+  # The following methods are available to a filter class instance:
+  # jsonapi_collection - collection on which to execute filtering
+  # jsonapi_filter_hash - a filter query hash, e.g. { 'status' => ['draft', 'published'], 'published_at' => '2001-02-03T04:05:06+03:00'  }
+  def call
+    jsonapi_collection.where(status: jsonapi_filter_hash[:status])
+  end
+end
+```
+Now you can call filter posts collection in your controller:
+```ruby
+posts = GetPosts.call
+# jsonapi_filter_class - API::PostFilter in our example
+# jsonapi_filter_hash - a filter query hash, e.g. { 'status' => ['draft', 'published'] }
+filtered_posts = jsonapi_filter_class.new(posts, jsonapi_filter_hash).call
+```
+
+
 ### Configuration
 Add an initializer to your app with the following config block:
 ```ruby

data/lib/json_apiable.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/all'
 require "json_apiable/version"
 require "json_apiable/core_extensions"
@@ -6,7 +8,10 @@ require 'json_apiable/renderers'
 require 'json_apiable/errors'
 require 'json_apiable/params_parser'
 require 'json_apiable/pagination_parser'
+require 'json_apiable/filter_parser'
+require 'json_apiable/filter_matchers'
+require 'json_apiable/base_filter'
 require 'json_apiable/json_apiable'
 
 String.include CoreExtensions::String
-Mime::Type.register JsonApiable::JSONAPI_CONTENT_TYPE, :json_api
+Mime::Type.register JsonApiable::JSONAPI_CONTENT_TYPE, :json_api

data/lib/json_apiable/base_filter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module JsonApiable
+  # Base class for Filters
+  class BaseFilter
+    extend JsonApiable::FilterMatchers
+
+    attr_reader :jsonapi_collection, :jsonapi_filter_hash, :current_user
+
+    protected
+
+    def initialize(a_collection, a_filter_hash, current_user)
+      @jsonapi_collection = a_collection
+      @jsonapi_filter_hash = a_filter_hash
+      @current_user = current_user
+    end
+
+    class << self
+      def jsonapi_allowed_filters
+        {}
+      end
+    end
+  end
+end

data/lib/json_apiable/configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JsonApiable
   class Configuration
     attr_accessor :valid_query_params, :supported_media_type_proc, :not_found_exception_class, :page_size
@@ -29,4 +31,4 @@ module JsonApiable
       @not_found_exception_class = klass
     end
   end
-end
+end

data/lib/json_apiable/core_extensions.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module CoreExtensions
   module String
     def integer?
       to_i.to_s == self
     end
   end
-end
+end

data/lib/json_apiable/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JsonApiable
   module Errors
     class ApiError < StandardError; end
@@ -7,4 +9,4 @@ module JsonApiable
     class ForbiddenError < ApiError; end
     class ConfigurationError < ApiError; end
   end
-end
+end

data/lib/json_apiable/filter_matchers.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module JsonApiable
+  module FilterMatchers
+    def matches?(allowed, given)
+      given.all? do |value|
+        allowed.is_a?(Proc) ? allowed.call(value) : allowed.include?(value)
+      end
+    end
+
+    module_function :matches?
+
+    # returns true for boolean values, false for any other
+    def boolean_matcher
+      proc do |value|
+        handle_error(value) do
+          if true_matcher.call(value) || (value == false || value =~ /^(false|f|0)$/i)
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+
+    # returns true for true values, false for any other
+    def true_matcher
+      proc do |value|
+        handle_error(value) do
+          if value == true || value =~ /^(true|t|1)$/i
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+
+    # returns true if the value is a valid date or datetime
+    def datetime_matcher
+      proc do |value|
+        handle_error(value) do
+          datetime = value.in_time_zone(Time.zone)
+          datetime.present?
+        end
+      end
+    end
+
+    # returns true if the value is a an array of existing ids of the given model
+    def ids_matcher(model)
+      proc do |value|
+        handle_error(value) do
+          given_ids = value.split(',')
+          found_records = model.where(id: given_ids)
+
+          given_ids.count == found_records.count
+        end
+      end
+    end
+
+    def handle_error(value)
+      yield
+    rescue ArgumentError => e
+      raise ArgumentError, "#{value}: #{e.message}"
+    end
+  end
+end

data/lib/json_apiable/filter_parser.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module JsonApiable
+  class FilterParser
+    def self.parse_filters!(jsonapi_build_params, filter_class)
+      FilterParser.new(jsonapi_build_params[:filter], filter_class).parse!
+    end
+
+    attr_reader :filter_param, :filter_class
+
+    def initialize(filter_param, filter_class)
+      @filter_param = filter_param
+      @filter_class = filter_class
+    end
+
+    # Support filtering in the form of example.com/v1/posts?filter[status]=draft,published
+    def parse!
+      raise_invalid_filter_class unless valid_filter_class?
+
+      filter_hash = ActiveSupport::HashWithIndifferentAccess.new
+      if valid_filter_query?
+        filter_param.keys.each do |k|
+          if valid_filter_key?(k)
+            # support notation ?filter[param]=value1,value2,value3&...
+            requested = filter_param[k].split(',')
+            allowed_values = allowed_filter_keys[k]
+            raise_invalid_filter_value(k) unless FilterMatchers.matches?(allowed_values, requested)
+
+            filter_hash[k] = requested
+          else
+            raise_invalid_filter_value(k)
+          end
+        end
+      elsif filter_param.present?
+        raise ArgumentError, 'filter'
+      end
+      filter_hash
+    end
+
+    private
+
+    def raise_argument_error(message)
+      raise ArgumentError, message
+    end
+
+    def raise_invalid_filter_value(k)
+      prefix = "filter[#{k}]"
+      msg = filter_param[k].present? ? "#{prefix}=#{filter_param[k]}" : prefix
+      raise_argument_error(msg)
+    end
+
+    def raise_invalid_filter_class
+      raise_argument_error("#{filter_class} does not specify jsonapi_allowed_filters")
+    end
+
+    def valid_filter_class?
+      filter_class.respond_to?(:jsonapi_allowed_filters)
+    end
+
+    def valid_filter_query?
+      filter_param.present? && (filter_param.is_a?(Hash) || filter_param.is_a?(ActionController::Parameters))
+    end
+
+    def valid_filter_key?(k)
+      allowed_filter_keys.key?(k) && filter_param[k].present?
+    end
+
+    def allowed_filter_keys
+      filter_class.jsonapi_allowed_filters.with_indifferent_access
+    end
+  end
+end

data/lib/json_apiable/json_apiable.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JsonApiable
   extend ActiveSupport::Concern
   include Errors
@@ -5,8 +7,8 @@ module JsonApiable
 
   JSONAPI_CONTENT_TYPE = 'application/vnd.api+json'
 
-  attr_reader :jsonapi_page, :jsonapi_include, :jsonapi_build_params, :jsonapi_assign_params, :jsonapi_default_page_size,
-              :jsonapi_exclude_attributes, :jsonapi_exclude_relationships
+  attr_reader :jsonapi_page_hash, :jsonapi_include_array, :jsonapi_filter_hash, :jsonapi_filter_class, :jsonapi_build_params,
+              :jsonapi_assign_params, :jsonapi_default_page_size, :jsonapi_exclude_attributes, :jsonapi_exclude_relationships
 
   included do
     before_action :ensure_jsonapi_content_type
@@ -25,7 +27,6 @@ module JsonApiable
     rescue_from JsonApiable.configuration.not_found_exception_class, with: :respond_to_not_found
   end
 
-
   class << self
     attr_writer :configuration
   end
@@ -63,8 +64,11 @@ module JsonApiable
   end
 
   def jsonapi_relationship_attribute(relationship, attribute)
-    [:id, :type].include?(attribute.to_sym) ? jsonapi_relationship_data(relationship)&.dig(attribute) :
-                                              jsonapi_relationship_data(relationship)&.dig(:attributes, attribute)
+    if [:id, :type].include?(attribute.to_sym)
+      jsonapi_relationship_data(relationship)&.dig(attribute)
+    else
+      jsonapi_relationship_data(relationship)&.dig(:attributes, attribute)
+    end
   end
 
   def jsonapi_assign_params
@@ -126,19 +130,24 @@ module JsonApiable
     end
   end
 
+  def set_jsonapi_filter(filter_class)
+    @jsonapi_filter_class = filter_class
+    @jsonapi_filter_hash = FilterParser.parse_filters!(jsonapi_build_params, filter_class)
+  end
+
   def set_jsonapi_content_type
     response.headers['Content-Type'] = JSONAPI_CONTENT_TYPE
   end
 
   def parse_jsonapi_pagination
-    @jsonapi_page = PaginationParser.parse_pagination!(query_params, jsonapi_default_page_size)
+    @jsonapi_page_hash = PaginationParser.parse_pagination!(query_params, jsonapi_default_page_size)
   end
 
   def parse_jsonapi_include
-    @jsonapi_include = query_params[:include].presence&.gsub(/ /, '')&.split(',')&.map(&:to_sym).to_a
+    @jsonapi_include_array = query_params[:include].presence&.gsub(/ /, '')&.split(',')&.map(&:to_sym).to_a
   end
 
   def query_params
     request.query_parameters
   end
-end
+end

data/lib/json_apiable/pagination_parser.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
+
 module JsonApiable
   class PaginationParser
-
     def self.parse_pagination!(query_params, default_page_size)
       PaginationParser.new(query_params[:page], query_params[:no_pagination], default_page_size).parse!
     end
@@ -15,7 +16,7 @@ module JsonApiable
 
     def parse!
       if no_pagination
-        jsonapi_page = nil
+        jsonapi_page_hash = nil
       elsif invalid_page_param?
         raise ArgumentError, 'page'
       elsif invalid_page_number?
@@ -23,14 +24,14 @@ module JsonApiable
       elsif invalid_page_size?
         raise ArgumentError, 'page[size]'
       else
-        jsonapi_page = page_param.presence.to_h.with_indifferent_access
+        jsonapi_page_hash = page_param.presence.to_h.with_indifferent_access
         # convert values to integers
-        jsonapi_page = jsonapi_page.merge(jsonapi_page) { |k,v| v.to_i } if jsonapi_page.present?
-        jsonapi_page = { number: Configuration::DEFAULT_PAGE_NUMBER, size: default_page_size } if jsonapi_page.blank?
-        jsonapi_page[:number] = Configuration::DEFAULT_PAGE_NUMBER if jsonapi_page[:number].blank?
-        jsonapi_page[:size] = default_page_size if jsonapi_page[:size].blank?
+        jsonapi_page_hash = jsonapi_page_hash.merge(jsonapi_page_hash) { |_, v| v.to_i } if jsonapi_page_hash.present?
+        jsonapi_page_hash = { number: Configuration::DEFAULT_PAGE_NUMBER, size: default_page_size } if jsonapi_page_hash.blank?
+        jsonapi_page_hash[:number] = Configuration::DEFAULT_PAGE_NUMBER if jsonapi_page_hash[:number].blank?
+        jsonapi_page_hash[:size] = default_page_size if jsonapi_page_hash[:size].blank?
       end
-      jsonapi_page
+      jsonapi_page_hash
     end
 
     private
@@ -56,4 +57,4 @@ module JsonApiable
       number > Configuration::MAX_PAGE_SIZE || number.zero? || number.negative?
     end
   end
-end
+end

data/lib/json_apiable/params_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JsonApiable
   class ParamsParser
     class DataParams
@@ -39,7 +41,9 @@ module JsonApiable
     end
 
     def self.build_relationships_hash(relationships, excluded_relationships, request)
-      attr_hash = {}; ids_array = []; ids_key = nil
+      attr_hash = {}
+      ids_array = []
+      ids_key = nil
 
       relationships&.each_pair do |key, data_hash|
         next if excluded_relationships&.include?(key.to_sym)
@@ -72,7 +76,7 @@ module JsonApiable
     end
 
     def self.hashify(allowed_relationships)
-      allowed_relationships.map{|rel| { rel => {}}}
+      allowed_relationships.map { |rel| { rel => {} } }
     end
   end
-end
+end

data/lib/json_apiable/renderers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JsonApiable
   module Renderers
     def respond_to_unsupported_media_type
@@ -49,4 +51,4 @@ module JsonApiable
       render json: { errors: json }, status: status
     end
   end
-end
+end

data/lib/json_apiable/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JsonApiable
-  VERSION = "0.3"
+  VERSION = "0.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: json_apiable
 version: !ruby/object:Gem::Version
-  version: '0.3'
+  version: '0.4'
 platform: ruby
 authors:
 - Mike Polischuk
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-01-19 00:00:00.000000000 Z
+date: 2020-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -201,6 +201,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - Gemfile
 - Gemfile.lock
@@ -211,9 +212,12 @@ files:
 - bin/setup
 - json_apiable.gemspec
 - lib/json_apiable.rb
+- lib/json_apiable/base_filter.rb
 - lib/json_apiable/configuration.rb
 - lib/json_apiable/core_extensions.rb
 - lib/json_apiable/errors.rb
+- lib/json_apiable/filter_matchers.rb
+- lib/json_apiable/filter_parser.rb
 - lib/json_apiable/json_apiable.rb
 - lib/json_apiable/pagination_parser.rb
 - lib/json_apiable/params_parser.rb