Refactor + add configurable defaults.

Author: beauby

lib/generators/jsonapi/initializer/templates/initializer.rb

@@ -1,6 +1,31 @@
 JSONAPI::Rails.configure do |config|
-  # config.register_mime_type = true
-  # config.register_param_parser = true
-  # config.register_renderers = true
-  # config.extend_action_controller = true
+  # # Set a default serializable class mapping.
+  # config.jsonapi_class = Hash.new { |h, k|
+  #   names = k.to_s.split('::')
+  #   klass = names.pop
+  #   h[k] = [*names, "Serializable#{klass}"].join('::').safe_constantize
+  # }
+  #
+  # # Set a default serializable class mapping for errors.
+  # config.jsonapi_errors_class = Hash.new { |h, k|
+  #   names = k.to_s.split('::')
+  #   klass = names.pop
+  #   h[k] = [*names, "Serializable#{klass}"].join('::').safe_constantize
+  # }.tap { |h|
+  #   h[:'ActiveModel::Errors'] = JSONAPI::Rails::SerializableActiveModelErrors
+  #   h[:Hash] = JSONAPI::Rails::SerializableErrorHash
+  # }
+  #
+  # # Set a default JSON API object.
+  # config.jsonapi_object = {
+  #   version: '1.0'
+  # }
+  #
+  # # Set default exposures.
+  # config.jsonapi_expose = {
+  #   url_helpers: ::Rails.application.routes.url_helpers
+  # }
+  #
+  # # Set a default pagination scheme.
+  # config.jsonapi_pagination = ->(_) { nil }
 end

lib/jsonapi/rails/configuration.rb

@@ -1,12 +1,37 @@
+require 'jsonapi/rails/serializable_active_model_errors'
+require 'jsonapi/rails/serializable_error_hash'
+
 module JSONAPI
   module Rails
     class Configuration < ActiveSupport::InheritableOptions; end
+    DEFAULT_JSONAPI_CLASS = Hash.new do |h, k|
+      names = k.to_s.split('::')
+      klass = names.pop
+      h[k] = [*names, "Serializable#{klass}"].join('::').safe_constantize
+    end.freeze
+
+    DEFAULT_JSONAPI_ERRORS_CLASS = DEFAULT_JSONAPI_CLASS.dup.merge!(
+      'ActiveModel::Errors'.to_sym =>
+        JSONAPI::Rails::SerializableActiveModelErrors,
+      Hash: JSONAPI::Rails::SerializableErrorHash
+    ).freeze
+
+    DEFAULT_JSONAPI_OBJECT = {
+      version: '1.0'
+    }.freeze
+
+    DEFAULT_JSONAPI_EXPOSE = {
+      url_helpers: ::Rails.application.routes.url_helpers
+    }.freeze
+
+    DEFAULT_JSONAPI_PAGINATION = ->(_) { nil }
 
     DEFAULT_CONFIG = {
-      register_parameter_parser: true,
-      register_mime_type: true,
-      register_renderers: true,
-      extend_action_controller: true
+      jsonapi_class: DEFAULT_JSONAPI_CLASS,
+      jsonapi_errors_class: DEFAULT_JSONAPI_ERRORS_CLASS,
+      jsonapi_object: DEFAULT_JSONAPI_OBJECT,
+      jsonapi_expose: DEFAULT_JSONAPI_EXPOSE,
+      jsonapi_pagination: DEFAULT_JSONAPI_PAGINATION
     }.freeze
 
     def self.configure

lib/jsonapi/rails/controller.rb

@@ -1,9 +1,11 @@
 require 'jsonapi/deserializable'
 require 'jsonapi/parser'
+require 'jsonapi/rails/configuration'
 
 module JSONAPI
   module Rails
     module Deserializable
+      # @private
       class Resource < JSONAPI::Deserializable::Resource
         id
         type
@@ -20,22 +22,56 @@ class Resource < JSONAPI::Deserializable::Resource
       end
     end
 
+    # ActionController methods and hooks for JSON API deserialization and
+    #   rendering.
     module Controller
       extend ActiveSupport::Concern
 
-      JSONAPI_POINTERS_KEY = 'jsonapi_deserializable.jsonapi_pointers'.freeze
+      JSONAPI_POINTERS_KEY = 'jsonapi-rails.jsonapi_pointers'.freeze
 
       class_methods do
+        # Declare a deserializable resource.
+        #
+        # @param key [Symbol] The key under which the deserialized hash will be
+        #   available within the `params` hash.
+        # @param options [Hash]
+        # @option class [Class] A custom deserializer class. Optional.
+        # @option only List of actions for which deserialization should happen.
+        #   Optional.
+        # @option except List of actions for which deserialization should not
+        #   happen. Optional.
+        # @yieldreturn Optional block for in-line definition of custom
+        #   deserializers.
+        #
+        # @example
+        #   class ArticlesController < ActionController::Base
+        #     deserializable_resource :article, only: [:create, :update]
+        #
+        #     def create
+        #       article = Article.new(params[:article])
+        #
+        #       if article.save
+        #         render jsonapi: article
+        #       else
+        #         render jsonapi_errors: article.errors
+        #       end
+        #     end
+        #
+        #     # ...
+        #   end
+        #
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
         def deserializable_resource(key, options = {}, &block)
           options = options.dup
           klass = options.delete(:class) ||
                   Class.new(JSONAPI::Rails::Deserializable::Resource, &block)
 
           before_action(options) do |controller|
+            # TODO(lucas): Fail with helpful error message if _jsonapi not
+            #   present.
             hash = controller.params[:_jsonapi].to_unsafe_hash
-            ActiveSupport::Notifications.instrument('parse.jsonapi',
-                                                    payload: hash,
-                                                    class: klass) do
+            ActiveSupport::Notifications
+              .instrument('parse.jsonapi', payload: hash, class: klass) do
               JSONAPI::Parser::Resource.parse!(hash)
               resource = klass.new(hash[:data])
               controller.request.env[JSONAPI_POINTERS_KEY] =
@@ -44,34 +80,46 @@ def deserializable_resource(key, options = {}, &block)
             end
           end
         end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
       end
 
+      # Hook for serializable class mapping (for resources).
+      # Overridden by the `class` renderer option.
+      # @return [Hash{Symbol=>Class}]
       def jsonapi_class
-        # TODO(lucas): Make this configurable
-        Hash.new do |h, k|
-          names = k.to_s.split('::')
-          klass = names.pop
-          h[k] = [*names, "Serializable#{klass}"].join('::').safe_constantize
-        end
+        JSONAPI::Rails.config[:jsonapi_class]
+      end
+
+      # Hook for serializable class mapping (for errors).
+      # Overridden by the `class` renderer option.
+      # @return [Hash{Symbol=>Class}]
+      def jsonapi_errors_class
+        JSONAPI::Rails.config[:jsonapi_errors_class]
       end
 
+      # Hook for the jsonapi object.
+      # Overridden by the `jsonapi_object` renderer option.
+      # @return [Hash]
       def jsonapi_object
-        nil
+        JSONAPI::Rails.config[:jsonapi_object]
       end
 
+      # Hook for default exposures.
+      # @return [Hash]
       def jsonapi_expose
-        # TODO(lucas): Make this configurable
-        {
-          url_helpers: ::Rails.application.routes.url_helpers
-        }
+        JSONAPI::Rails.config[:jsonapi_expose]
       end
 
-      def jsonapi_pagination(_collection)
-        nil
+      # Hook for pagination scheme.
+      # @return [Hash]
+      def jsonapi_pagination(resources)
+        instance_exec(resources, &JSONAPI::Rails.config[:jsonapi_pagination])
       end
 
+      # JSON pointers for deserialized fields.
+      # @return [Hash{Symbol=>String}]
       def jsonapi_pointers
-        request.env[JSONAPI_POINTERS_KEY]
+        request.env[JSONAPI_POINTERS_KEY] || {}
       end
     end
   end

lib/jsonapi/rails/parser.rb

@@ -2,56 +2,66 @@
 require 'action_controller'
 require 'active_support'
 
-require 'jsonapi/rails/configuration'
-require 'jsonapi/rails/controller'
-require 'jsonapi/rails/parser'
 require 'jsonapi/rails/renderer'
 
 module JSONAPI
   module Rails
+    # @private
     class Railtie < ::Rails::Railtie
       MEDIA_TYPE = 'application/vnd.api+json'.freeze
+      PARSER = lambda do |body|
+        data = JSON.parse(body)
+        hash = { _jsonapi: data }
+
+        hash.with_indifferent_access
+      end
       RENDERERS = {
         jsonapi:        SuccessRenderer.new,
         jsonapi_errors: ErrorsRenderer.new
       }.freeze
 
-      initializer 'jsonapi.init', after: :load_config_initializers do
-        if JSONAPI::Rails.config.register_mime_type
-          Mime::Type.register MEDIA_TYPE, :jsonapi
+      initializer 'jsonapi-rails.init' do
+        register_mime_type
+        register_parameter_parser
+        register_renderers
+        ActiveSupport.on_load(:action_controller) do
+          require 'jsonapi/rails/controller'
+          include ::JSONAPI::Rails::Controller
         end
+      end
 
-        if JSONAPI::Rails.config.register_parameter_parser
-          if ::Rails::VERSION::MAJOR >= 5
-            ::ActionDispatch::Request.parameter_parsers[:jsonapi] = PARSER
-          else
-            ::ActionDispatch::ParamsParser::DEFAULT_PARSERS[Mime[:jsonapi]] = PARSER
-          end
-        end
+      private
 
-        if JSONAPI::Rails.config.extend_action_controller
-          ActiveSupport.on_load(:action_controller) do
-            include ::JSONAPI::Rails::Controller
-          end
+      def register_mime_type
+        Mime::Type.register(MEDIA_TYPE, :jsonapi)
+      end
+
+      def register_parameter_parser
+        if ::Rails::VERSION::MAJOR >= 5
+          ActionDispatch::Request.parameter_parsers[:jsonapi] = PARSER
+        else
+          ActionDispatch::ParamsParser::DEFAULT_PARSERS[Mime[:jsonapi]] = PARSER
         end
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def register_renderers
+        ActiveSupport.on_load(:action_controller) do
+          RENDERERS.each do |name, renderer|
+            ::ActionController::Renderers.add(name) do |resources, options|
+              # Renderer proc is evaluated in the controller context.
+              self.content_type ||= Mime[:jsonapi]
 
-        if JSONAPI::Rails.config.register_renderers
-          ActiveSupport.on_load(:action_controller) do
-            RENDERERS.each do |name, renderer|
-              ::ActionController::Renderers.add(name) do |resources, options|
-                # Renderer proc is evaluated in the controller context.
-                self.content_type ||= Mime[:jsonapi]
-
-                ActiveSupport::Notifications.instrument('render.jsonapi',
-                                                        resources: resources,
-                                                        options: options) do
-                  renderer.render(resources, options, self).to_json
-                end
+              ActiveSupport::Notifications.instrument('render.jsonapi',
+                                                      resources: resources,
+                                                      options: options) do
+                renderer.render(resources, options, self).to_json
               end
             end
           end
         end
       end
+      # rubocop:enable Metrics/MethodLength
     end
   end
 end

lib/jsonapi/rails/railtie.rb

@@ -1,9 +1,8 @@
-require 'jsonapi/rails/serializable_active_model_errors'
-require 'jsonapi/rails/serializable_error_hash'
 require 'jsonapi/serializable/renderer'
 
 module JSONAPI
   module Rails
+    # @private
     class SuccessRenderer
       def initialize(renderer = JSONAPI::Serializable::Renderer.new)
         @renderer = renderer
@@ -19,19 +18,20 @@ def render(resources, options, controller)
 
       private
 
-      # @api private
       def default_options(options, controller, resources)
         options.dup.tap do |opts|
           opts[:class] ||= controller.jsonapi_class
           if (pagination_links = controller.jsonapi_pagination(resources))
-            (opts[:links] ||= {}).merge!(pagination_links)
+            opts[:links] = (opts[:links] || {}).merge(pagination_links)
           end
-          opts[:expose]  = controller.jsonapi_expose.merge!(opts[:expose] || {})
-          opts[:jsonapi] = opts.delete(:jsonapi_object) || controller.jsonapi_object
+          opts[:expose]  = controller.jsonapi_expose.merge(opts[:expose] || {})
+          opts[:jsonapi] = opts.delete(:jsonapi_object) ||
+                           controller.jsonapi_object
         end
       end
     end
 
+    # @private
     class ErrorsRenderer
       def initialize(renderer = JSONAPI::Serializable::Renderer.new)
         @renderer = renderer
@@ -49,22 +49,15 @@ def render(errors, options, controller)
 
       private
 
-      # @api private
       def default_options(options, controller)
         options.dup.tap do |opts|
-          opts[:class] ||= controller.jsonapi_class
-          unless opts[:class].key?(:'ActiveModel::Errors')
-            opts[:class][:'ActiveModel::Errors'] =
-              JSONAPI::Rails::SerializableActiveModelErrors
-          end
-          unless opts[:class].key?(:Hash)
-            opts[:class][:Hash] = JSONAPI::Rails::SerializableErrorHash
-          end
+          opts[:class] ||= controller.jsonapi_errors_class
           opts[:expose] =
             controller.jsonapi_expose
-              .merge!(opts[:expose] || {})
-              .merge!(_jsonapi_pointers: controller.jsonapi_pointers)
-          opts[:jsonapi] = opts[:jsonapi_object] || controller.jsonapi_object
+                      .merge(opts[:expose] || {})
+                      .merge!(_jsonapi_pointers: controller.jsonapi_pointers)
+          opts[:jsonapi] = opts.delete(:jsonapi_object) ||
+                           controller.jsonapi_object
         end
       end
     end

lib/jsonapi/rails/renderer.rb

@@ -1,5 +1,6 @@
 module JSONAPI
   module Rails
+    # @private
     class SerializableActiveModelError < Serializable::Error
       title do
         "Invalid #{@field}" unless @field.nil?
@@ -14,6 +15,7 @@ class SerializableActiveModelError < Serializable::Error
       end
     end
 
+    # @private
     class SerializableActiveModelErrors
       def initialize(exposures)
         @errors = exposures[:object]