jsonapi_parameters 0.4.4 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84858e2d499d73db01b7438b76e694d0a9e00f0a09c7c60d39d5ab8f2b7cc93a
-  data.tar.gz: c9dd1b24e02193aa7bd2fb820510d4deb35e7da1dca5dea6b83370fb0341c603
+  metadata.gz: 514048af1321f2eb0d1c17e260d8bfc0ce3dbf3b0d8c70fc91f42724fdc6a0c1
+  data.tar.gz: 46a52ac2fa28952b732d11479b9c1a2a3c2ff88bafd37816a920626b32ceda31
 SHA512:
-  metadata.gz: fcde1c307a79942c9dc2725ad77855255102cba66f7d18cd8dc6c87f439e3c8e279ab8817ad2f3bfd2a8cfe044224c6e7e0e9f61011b0f9fa4ad2a1e9350e6f8
-  data.tar.gz: b4e8ffc48a859faa83c5224d0c384482ada8f3fddcc4ed07f298e3d9c9c6ce542df20db99f44b73bf8417320c06ba9391b721b14ab7085adaf3bc5c3ff371da3
+  metadata.gz: 406ea510828fb14bb8b4ba1298ad4a7f1c68a93391b8dce48a0e9132d8b7e05343febc0da9fd8f2e7aa8b6bb81f1a48a5cc23c51f01164d8d13e572b4f2b1c1e
+  data.tar.gz: b455719c009aae879edf3e457f34222cee455a3583ae9c1c58348f4784efafe92c1b2407732500a35d8f5da026bdce9dff5624482c90950a0d3a8d4430c48d81

data/README.md

@@ -1,17 +1,12 @@
 # JsonApi::Parameters
-Simple JSON:API compliant parameters translator.
+Simple [JSON:API](https://jsonapi.org/) compliant parameters translator.
 
 [![Gem Version](https://badge.fury.io/rb/jsonapi_parameters.svg)](https://badge.fury.io/rb/jsonapi_parameters)
 [![Maintainability](https://api.codeclimate.com/v1/badges/84fd5b548eea8d7e18af/maintainability)](https://codeclimate.com/github/visualitypl/jsonapi_parameters/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/84fd5b548eea8d7e18af/test_coverage)](https://codeclimate.com/github/visualitypl/jsonapi_parameters/test_coverage)
+[![CircleCI](https://circleci.com/gh/visualitypl/jsonapi_parameters.svg?style=svg)](https://circleci.com/gh/visualitypl/jsonapi_parameters)
 
-#### The problem
-
-JSON:API standard specifies not only responses (that can be handled nicely, using gems like [fast_jsonapi from Netflix](https://github.com/Netflix/fast_jsonapi)), but also the request structure. 
-
-#### The solution
-
-As we couldn't find any gem that would make it easier in Rails to use these structures, we decided to create something that will work for us - a translator that transforms JSON:API compliant request parameter strucure into a Railsy structure.
+[Documentation](https://github.com/visualitypl/jsonapi_parameters/wiki)
 
 ## Usage
 
@@ -75,212 +70,8 @@ Relationship parameters are being read from two optional trees:
 
 If you provide any related resources in the `relationships` table, this gem will also look for corresponding, `included` resources and their attributes. Thanks to that this gem supports nested attributes, and will try to translate these included resources and pass them along.
 
-##### belongs_to
-
-Passing a resource that is a single entity in relationships tree will make JsonApi::Parameters assume that it is a `belongs_to` relationship. 
-
-###### Without included entity
-Example:
-
-```
-class Movie < ActiveRecord::Model
-    belongs_to :director
-end
-```
-
-Request body:
-
-```
-{
-    data: {
-        type: 'movies',
-        attributes: {
-          title: 'The Terminator',
-        },
-        relationships: {
-          director: {
-            data: {
-              id: 682, type: 'directors'
-            }
-          }
-        }
-    }
-}
-```
-
-Will translate to:
-
-```
-{
-  movie: {
-    title: 'The Terminator',
-    director_id: 682
-  }
-}
-```
-
+For more examples take a look at [Relationships](https://github.com/visualitypl/jsonapi_parameters/wiki/Relationships) in the wiki documentation.
 
-###### With included entity:
-Example:
-
-```
-class Movie < ActiveRecord::Model
-    belongs_to :director
-    
-    accepts_nested_attributes_for :director
-end
-```
-
-Request body:
-```
-{
-    data: {
-        type: 'movies',
-        attributes: {
-          title: 'The Terminator',
-        },
-        relationships: {
-          director: {
-            data: {
-              id: 682, type: 'directors'
-            }
-          }
-        }
-    },
-    included: [
-        {
-            type: 'directors',
-            id: 682,
-            attributes: { 
-                name: 'Some guy'
-            }
-        }
-    ]
-}
-```
-
-Will translate to:   
-```
-{
-  movie: {
-    title: 'The Terminator',
-    director_attributes: { id: 682, name: 'Some guy' }
-  }
-}
-```
-
-##### has_many
-
-Passing a resource that is a an array of entities in relationships tree will make JsonApi::Parameters assume that it is a `has_many` relationship. 
-
-###### Without included entity
-Example:
-
-```
-class Movie < ActiveRecord::Model
-    has_many :genres
-end
-```
-
-Request body:
-
-```
-{
-    data: {
-        type: 'movies',
-        attributes: {
-          title: 'The Terminator',
-        },
-        relationships: {
-          genres: [{
-            data: {
-              id: 1, type: 'genres'
-            },
-            data: {
-              id: 2, type: 'genres'
-            },
-          }]
-        }
-    }
-}
-```
-
-Will translate to:
-
-```
-{
-  movie: {
-    title: 'The Terminator',
-    genre_ids: [1, 2]
-  }
-}
-```
-
-
-###### With included entity:
-Example:
-
-```
-class Movie < ActiveRecord::Model
-    has_many :genres
-    
-    accepts_nested_attributes_for :genres
-end
-```
-
-Request body:
-```
-{
-    data: {
-        type: 'movies',
-        attributes: {
-          title: 'The Terminator',
-        },
-        relationships: {
-          genres: [{
-            data: {
-              id: 1, type: 'genres'
-            }
-          }]
-        }
-    },
-    included: [
-        {
-            type: 'genre',
-            id: 1,
-            attributes: { 
-                name: 'Genre one'
-            }
-        }
-    ]
-}
-```
-
-Will translate to:   
-```
-{
-  movie: {
-    title: 'The Terminator',
-    genres_attributes: [{ id: 1, name: 'Genre one' }]
-  }
-}
-```
-
-
-#### Casing
-
-If the input is in a different convention than `:snake`, you should specify that.
- 
- You can do it in two ways: 
- * in an initializer, simply create `initializers/jsonapi_parameters.rb` with contents similar to: 
- ```ruby
- # config/initializers/jsonapi_parameters.rb
-  
-  JsonApi::Parameters.ensure_underscore_translation = true
- 
- ```
- 
- * while calling `.from_jsonapi`, for instance: `.from_jsonapi(:camel)`. **The value does not really matter, as anything different than `:snake` will result in deep keys transformation provided by [ActiveSupport](https://apidock.com/rails/v4.1.8/Hash/deep_transform_keys).**
 
 ### Plain Ruby / outside Rails
 
@@ -297,15 +88,6 @@ translator = Translator.new
 
 translator.jsonapify(params)
 ```
-
-#### Casing
-
-If the input is in a different convention than `:snake`, you should specify that.
- 
- You can do it in two ways:
- 
- * by a global setting: `JsonApi::Parameters.ensure_underscore_translation = true` 
- * while calling `.jsonapify`, for instance: `.jsonapify(params, naming_convention: :camel)`. **The value does not really matter, as anything different than `:snake` will result in deep keys transformation provided by [ActiveSupport](https://apidock.com/rails/v4.1.8/Hash/deep_transform_keys).**
  
 ## Mime Type
 
@@ -313,5 +95,11 @@ As [stated in the JSON:API specification](https://jsonapi.org/#mime-types) corre
 
 This gems intention is to make input consumption as easy as possible. Hence, it [registers this mime type for you](lib/jsonapi_parameters/core_ext/action_dispatch/http/mime_type.rb). 
 
+## Customization
+
+If you need custom relationship handling (for instance, if you have a relationship named `scissors` that is plural, but it actually is a single entity), you can use Handlers to define appropriate behaviour.
+
+Read more at [Relationship Handlers](https://github.com/visualitypl/jsonapi_parameters/wiki/Relationship-handlers).
+
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/jsonapi_parameters.rb

@@ -1,4 +1,5 @@
 require 'jsonapi_parameters/parameters'
+require 'jsonapi_parameters/handlers'
 require 'jsonapi_parameters/translator'
 require 'jsonapi_parameters/core_ext'
 require 'jsonapi_parameters/version'

data/lib/jsonapi_parameters/default_handlers/base_handler.rb

@@ -0,0 +1,30 @@
+module JsonApi
+  module Parameters
+    module Handlers
+      module DefaultHandlers
+        class BaseHandler
+          attr_reader :relationship_key, :relationship_value, :included
+
+          def self.call(key, val, included)
+            new(key, val, included).handle
+          end
+
+          def initialize(relationship_key, relationship_value, included)
+            @relationship_key = relationship_key
+            @relationship_value = relationship_value
+            @included = included
+          end
+
+          def find_included_object(related_id:, related_type:)
+            included.find do |included_object_enum|
+              included_object_enum[:id] &&
+                included_object_enum[:id] == related_id &&
+                included_object_enum[:type] &&
+                included_object_enum[:type] == related_type
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi_parameters/default_handlers/nil_relation_handler.rb

@@ -0,0 +1,27 @@
+require_relative './base_handler'
+
+module JsonApi
+  module Parameters
+    module Handlers
+      module DefaultHandlers
+        class NilRelationHandler < BaseHandler
+          include ActiveSupport::Inflector
+
+          def handle
+            # Graceful fail if nil on to-many association
+            # in case the relationship key is, for instance, `billable_hours`,
+            # we have to assume that it is a to-many relationship.
+            if pluralize(relationship_key).to_sym == relationship_key
+              raise NotImplementedError.new(
+                'plural resource cannot be nullified - please create a custom handler for this relation'
+              )
+            end
+
+            # Handle with empty hash.
+            ToOneRelationHandler.new(relationship_key, {}, {}).handle
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi_parameters/default_handlers/to_many_relation_handler.rb

@@ -0,0 +1,52 @@
+module JsonApi
+  module Parameters
+    module Handlers
+      module DefaultHandlers
+        class ToManyRelationHandler < BaseHandler
+          include ActiveSupport::Inflector
+
+          attr_reader :with_inclusion, :vals, :key
+
+          def handle
+            @with_inclusion = !relationship_value.empty?
+
+            prepare_relationship_vals
+
+            generate_key
+
+            [key, vals]
+          end
+
+          private
+
+          def prepare_relationship_vals
+            @vals = relationship_value.map do |relationship|
+              related_id = relationship.dig(:id)
+              related_type = relationship.dig(:type)
+
+              included_object = find_included_object(
+                related_id: related_id, related_type: related_type
+              ) || {}
+
+              # If at least one related object has not been found in `included` tree,
+              # we should not attempt to "#{relationship_key}_attributes" but
+              # "#{relationship_key}_ids" instead.
+              @with_inclusion &= !included_object.empty?
+
+              if with_inclusion
+                included_object.delete(:type)
+                included_object[:attributes].merge(id: related_id)
+              else
+                relationship.dig(:id)
+              end
+            end
+          end
+
+          def generate_key
+            @key = (with_inclusion ? "#{pluralize(relationship_key)}_attributes" : "#{singularize(relationship_key)}_ids").to_sym
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi_parameters/default_handlers/to_one_relation_handler.rb

@@ -0,0 +1,26 @@
+module JsonApi
+  module Parameters
+    module Handlers
+      module DefaultHandlers
+        class ToOneRelationHandler < BaseHandler
+          include ActiveSupport::Inflector
+
+          def handle
+            related_id = relationship_value.dig(:id)
+            related_type = relationship_value.dig(:type)
+
+            included_object = find_included_object(
+              related_id: related_id, related_type: related_type
+            ) || {}
+
+            return ["#{singularize(relationship_key)}_id".to_sym, related_id] if included_object.empty?
+
+            included_object.delete(:type)
+            included_object = included_object[:attributes].merge(id: related_id)
+            ["#{singularize(relationship_key)}_attributes".to_sym, included_object]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi_parameters/handlers.rb

@@ -0,0 +1,46 @@
+require_relative 'default_handlers/nil_relation_handler'
+require_relative 'default_handlers/to_many_relation_handler'
+require_relative 'default_handlers/to_one_relation_handler'
+
+module JsonApi
+  module Parameters
+    module Handlers
+      include DefaultHandlers
+
+      DEFAULT_HANDLER_SET = {
+        to_many: ToManyRelationHandler,
+        to_one: ToOneRelationHandler,
+        nil: NilRelationHandler
+      }.freeze
+
+      module_function
+
+      def add_handler(handler_name, klass)
+        handlers[handler_name.to_sym] = klass
+      end
+
+      def set_resource_handler(resource_key, handler_key)
+        unless handlers.key?(handler_key)
+          raise NotImplementedError.new(
+            'handler_key does not match any registered handlers'
+          )
+        end
+
+        resource_handlers[resource_key.to_sym] = handler_key.to_sym
+      end
+
+      def reset_handlers!
+        @handlers = DEFAULT_HANDLER_SET.dup
+        @resource_handlers = {}
+      end
+
+      def resource_handlers
+        @resource_handlers ||= {}
+      end
+
+      def handlers
+        @handlers ||= DEFAULT_HANDLER_SET.dup
+      end
+    end
+  end
+end

data/lib/jsonapi_parameters/translator.rb

@@ -15,7 +15,9 @@ module JsonApi::Parameters
     return params if params.nil? || params.empty?
 
     @jsonapi_unsafe_hash = if naming_convention != :snake || JsonApi::Parameters.ensure_underscore_translation
-                             params.deep_transform_keys { |key| key.to_s.underscore.to_sym }
+                             params = params.deep_transform_keys { |key| key.to_s.underscore.to_sym }
+                             params[:data][:type] = params[:data][:type].underscore if params.dig(:data, :type)
+                             params
                            else
                              params.deep_symbolize_keys
                            end
@@ -37,16 +39,23 @@ module JsonApi::Parameters
     jsonapi_unsafe_params.tap do |param|
       jsonapi_relationships.each do |relationship_key, relationship_value|
         relationship_value = relationship_value[:data]
-        key, val = case relationship_value
-                   when Array
-                     handle_to_many_relation(relationship_key, relationship_value)
-                   when Hash
-                     handle_to_one_relation(relationship_key, relationship_value)
-                   when nil
-                     handle_nil_relation(relationship_key)
-                   else
-                     raise jsonapi_not_implemented_err
-                   end
+        handler_args = [relationship_key, relationship_value, jsonapi_included]
+        handler = if Handlers.resource_handlers.key?(relationship_key)
+                    Handlers.handlers[Handlers.resource_handlers[relationship_key]]
+                  else
+                    case relationship_value
+                    when Array
+                      Handlers.handlers[:to_many]
+                    when Hash
+                      Handlers.handlers[:to_one]
+                    when nil
+                      Handlers.handlers[:nil]
+                    else
+                      raise NotImplementedError.new('relationship resource linkage has to be a type of Array, Hash or nil')
+                    end
+                  end
+
+        key, val = handler.call(*handler_args)
         param[key] = val
       end
     end
@@ -67,78 +76,4 @@ module JsonApi::Parameters
   def jsonapi_relationships
     @jsonapi_relationships ||= @jsonapi_unsafe_hash.dig(:data, :relationships) || []
   end
-
-  def handle_to_many_relation(relationship_key, relationship_value)
-    with_inclusion = true
-
-    vals = relationship_value.map do |relationship_value|
-      related_id = relationship_value.dig(:id)
-      related_type = relationship_value.dig(:type)
-
-      included_object = find_included_object(
-        related_id: related_id, related_type: related_type
-      ) || {}
-
-      # If at least one related object has not been found in `included` tree,
-      # we should not attempt to "#{relationship_key}_attributes" but
-      # "#{relationship_key}_ids" instead.
-      with_inclusion = with_inclusion ? !included_object.empty? : with_inclusion
-
-      if with_inclusion
-        included_object.delete(:type)
-        included_object[:attributes].merge(id: related_id)
-      else
-        relationship_value.dig(:id)
-      end
-    end
-
-    # We may have smells in our value array as `with_inclusion` may have been changed at some point
-    # but not in the beginning.
-    # Because of that we should clear it and make sure the results are unified (e.g. array of ids)
-    unless with_inclusion
-      vals.map do |val|
-        val.dig(:attributes, :id) if val.is_a?(Hash)
-      end
-    end
-
-    key = with_inclusion ? "#{pluralize(relationship_key)}_attributes".to_sym : "#{singularize(relationship_key)}_ids".to_sym
-
-    [key, vals]
-  end
-
-  def handle_to_one_relation(relationship_key, relationship_value)
-    related_id = relationship_value.dig(:id)
-    related_type = relationship_value.dig(:type)
-
-    included_object = find_included_object(
-      related_id: related_id, related_type: related_type
-    ) || {}
-
-    return ["#{singularize(relationship_key)}_id".to_sym, related_id] if included_object.empty?
-
-    included_object.delete(:type)
-    included_object = included_object[:attributes].merge(id: related_id)
-    ["#{singularize(relationship_key)}_attributes".to_sym, included_object]
-  end
-
-  def handle_nil_relation(relationship_key)
-    # Graceful fail if nil on to-many association.
-    raise jsonapi_not_implemented_err if pluralize(relationship_key).to_sym == relationship_key
-
-    # Handle with empty hash.
-    handle_to_one_relation(relationship_key, {})
-  end
-
-  def find_included_object(related_id:, related_type:)
-    jsonapi_included.find do |included_object_enum|
-      included_object_enum[:id] &&
-        included_object_enum[:id] == related_id &&
-        included_object_enum[:type] &&
-        included_object_enum[:type] == related_type
-    end
-  end
-
-  def jsonapi_not_implemented_err
-    NotImplementedError.new('relationship member must either be an Array or a Hash')
-  end
 end

data/lib/jsonapi_parameters/version.rb

@@ -1,5 +1,5 @@
 module JsonApi
   module Parameters
-    VERSION = '0.4.4'.freeze
+    VERSION = '2.1.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi_parameters
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 2.1.0
 platform: ruby
 authors:
 - Visuality
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-08 00:00:00.000000000 Z
+date: 2020-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -45,14 +45,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.10.4
-  type: :runtime
+        version: 1.10.5
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.10.4
+        version: 1.10.5
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -321,6 +321,11 @@ files:
 - lib/jsonapi_parameters/core_ext.rb
 - lib/jsonapi_parameters/core_ext/action_controller/parameters.rb
 - lib/jsonapi_parameters/core_ext/action_dispatch/http/mime_type.rb
+- lib/jsonapi_parameters/default_handlers/base_handler.rb
+- lib/jsonapi_parameters/default_handlers/nil_relation_handler.rb
+- lib/jsonapi_parameters/default_handlers/to_many_relation_handler.rb
+- lib/jsonapi_parameters/default_handlers/to_one_relation_handler.rb
+- lib/jsonapi_parameters/handlers.rb
 - lib/jsonapi_parameters/parameters.rb
 - lib/jsonapi_parameters/translator.rb
 - lib/jsonapi_parameters/version.rb
@@ -343,7 +348,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.4
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Translator for JSON:API compliant parameters