jsonapi_parameters 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daa7f46ec2ca9f23be7199bf5b8ee043a1b40317ed96070f9b0025a624328eeb
-  data.tar.gz: 29b227bd32c0b86cb6b5e29c368bc4728a445c369f22852037b3ff6f8e929b07
+  metadata.gz: 6ad28494a05c8bc7f45b3b4408989aa44c311741fbefea777bd9fedb91bba464
+  data.tar.gz: 57180a59200f87667ebfdc57c1063e1855ce16777c80e4d8562780bfbbd96bfa
 SHA512:
-  metadata.gz: 30da56dbc5654aed7331e5db54f54da59414fdf747a97c75755ba184af9e813a9ef50f7f2251f4af418ca04d11b54d353d1d4ca7c1e12a638e2049fa7bcae972
-  data.tar.gz: a67da822ec846764be2cc6a999a6a70655b7816b5be9b733770a2f4ec32246a39cf587260a2fdfe6fa6836fe0290cc0e08088b873a8649fb2e61ab1fab59d839
+  metadata.gz: 166f3aed4fe6f74806fdad8f17bb924812d4678f8fc2ca55d16cfdff7c2497a43d4c9331280b128b74ac1051ccb6022e16880daae409fb93a402134196c34937
+  data.tar.gz: 8556b0aaed3936f78999f7fe7a0438ce1c66af2c7f2d78e499a7ba53c00ff6d60c9c83b949a4096b88a79ddf248bfa0cba89559923fa4f73ce720caf1f49ffec

data/README.md

@@ -1,17 +1,11 @@
 # 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)
 
-#### 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 +69,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'
-            },
-            {
-              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: 'genres',
-      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 +87,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 +94,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]()
+
 ## 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,26 @@
+module JsonApi
+  module Parameters
+    module Handlers
+      module DefaultHandlers
+        class BaseHandler
+          attr_reader :relationship_key, :relationship_value, :included
+
+          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: ->(k, v, included) { ToManyRelationHandler.new(k, v, included).handle },
+        to_one: ->(k, v, included) { ToOneRelationHandler.new(k, v, included).handle },
+        nil: ->(k, v, included) { NilRelationHandler.new(k, v, included).handle }
+      }.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

@@ -37,16 +37,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 +74,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 = !relationship_value.empty?
-
-    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
-
-    # 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 = '1.0.0'.freeze
+    VERSION = '1.1.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi_parameters
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Visuality
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-28 00:00:00.000000000 Z
+date: 2019-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -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