jsonapi_compliable 0.6.4 → 0.6.5

data/lib/jsonapi_compliable/adapters/null.rb

@@ -1,25 +1,65 @@
 module JsonapiCompliable
   module Adapters
+    # The Null adapter is a 'pass-through' adapter. It won't modify the scope.
+    # Useful when your customization does not support all possible
+    # configuration (e.g. the service you hit does not support sorting)
     class Null < Abstract
+      # (see Adapters::Abstract#filter)
       def filter(scope, attribute, value)
         scope
       end
 
+      # (see Adapters::Abstract#order)
       def order(scope, attribute, direction)
         scope
       end
 
-      def paginate(scope, number, size)
+      # (see Adapters::Abstract#paginate)
+      def paginate(scope, current_page, per_page)
         scope
       end
 
-      def sideload(scope, includes)
+      # (see Adapters::Abstract#count)
+      def count(scope, attr)
         scope
       end
 
-      def transaction
+      # (see Adapters::Abstract#average)
+      def average(scope, attr)
+        scope
+      end
+
+      # (see Adapters::Abstract#sum)
+      def sum(scope, attr)
+        scope
+      end
+
+      # (see Adapters::Abstract#sum)
+      def maximum(scope, attr)
+        scope
+      end
+
+      # (see Adapters::Abstract#minimum)
+      def minimum(scope, attr)
+        scope
+      end
+
+      # Since this is a null adapter, just yield
+      # @see Adapters::ActiveRecord#transaction
+      # @return Result of yield
+      # @param [Class] model_class The class we're operating on
+      def transaction(model_class)
         yield
       end
+
+      # (see Adapters::Abstract#resolve)
+      def resolve(scope)
+        scope
+      end
+
+      # (see Adapters::Abstract#associate)
+      def associate(parent, child, association_name, association_type)
+      end
     end
   end
 end

data/lib/jsonapi_compliable/base.rb

@@ -1,9 +1,10 @@
 module JsonapiCompliable
+  # Provides main interface to jsonapi_compliable
+  #
+  # This gets mixed in to a "context" class, such as a Rails controller.
   module Base
     extend ActiveSupport::Concern
 
-    MAX_PAGE_SIZE = 1_000
-
     included do
       class << self
         attr_accessor :_jsonapi_compliable
@@ -15,22 +16,77 @@ module JsonapiCompliable
       end
     end
 
-    def resource
-      @resource ||= self.class._jsonapi_compliable.new
+    # @!classmethods
+    module ClassMethods
+      # Define your JSONAPI configuration
+      #
+      # @example Inline Resource
+      #   # 'Quick and Dirty' solution that does not require a separate
+      #   # Resource object
+      #   class PostsController < ApplicationController
+      #     jsonapi do
+      #       type :posts
+      #       use_adapter JsonapiCompliable::Adapters::ActiveRecord
+      #
+      #       allow_filter :title
+      #     end
+      #   end
+      #
+      # @example Resource Class (preferred)
+      #   # Make code reusable by encapsulating it in a Resource class
+      #   class PostsController < ApplicationController
+      #     jsonapi resource: PostResource
+      #   end
+      #
+      # @see Resource
+      # @param resource [Resource] the Resource class associated to this endpoint
+      # @return [void]
+      def jsonapi(foo = 'bar', resource: nil, &blk)
+        if resource
+          self._jsonapi_compliable = resource
+        else
+          if !self._jsonapi_compliable
+            self._jsonapi_compliable = Class.new(JsonapiCompliable::Resource)
+          end
+        end
+
+        self._jsonapi_compliable.class_eval(&blk) if blk
+      end
     end
 
-    def resource!
-      @resource = self.class._jsonapi_compliable.new
+    # Returns an instance of the associated Resource
+    #
+    # In other words, if you configured your controller as:
+    #
+    #   jsonapi resource: MyResource
+    #
+    # This returns MyResource.new
+    #
+    # @return [Resource] the configured Resource for this controller
+    def resource
+      @resource ||= self.class._jsonapi_compliable.new
     end
 
+    # Instantiates the relevant Query object
+    #
+    # @see Query
+    # @return [Query] the Query object for this resource/params
     def query
       @query ||= Query.new(resource, params)
     end
 
+    # @see Query#to_hash
+    # @return [Hash] the normalized query hash for only the *current* resource
     def query_hash
       @query_hash ||= query.to_hash[resource.type]
     end
 
+    # Tracks the current context so we can refer to it within any
+    # random object. Helpful for easy-access to things like the current
+    # user.
+    #
+    # @api private
+    # @yieldreturn Code to run within the current context
     def wrap_context
       if self.class._jsonapi_compliable
         resource.with_context(self, action_name.to_sym) do
@@ -39,14 +95,57 @@ module JsonapiCompliable
       end
     end
 
+    # Use when direct, low-level access to the scope is required.
+    #
+    # @example Show Action
+    #   # Scope#resolve returns an array, but we only want to render
+    #   # one object, not an array
+    #   scope = jsonapi_scope(Employee.where(id: params[:id]))
+    #   render_jsonapi(scope.resolve.first, scope: false)
+    #
+    # @example Scope Chaining
+    #   # Chain onto scope after running through typical DSL
+    #   # Here, we'll add active: true to our hash if the user
+    #   # is filtering on something
+    #   scope = jsonapi_scope({})
+    #   scope.object.merge!(active: true) if scope.object[:filter]
+    #
+    # @see Resource#build_scope
+    # @return [Scope] the configured scope
     def jsonapi_scope(scope, opts = {})
       resource.build_scope(scope, query, opts)
     end
 
+    # @see Deserializer#initialize
+    # @return [Deserializer]
     def deserialized_params
       @deserialized_params ||= JsonapiCompliable::Deserializer.new(params, request.env)
     end
 
+    # Create the resource model and process all nested relationships via the
+    # serialized parameters. Any error, including validation errors, will roll
+    # back the transaction.
+    #
+    # @example Basic Rails
+    #   # Example Resource must have 'model'
+    #   #
+    #   # class PostResource < ApplicationResource
+    #   #   model Post
+    #   # end
+    #   def create
+    #     post, success = jsonapi_create.to_a
+    #
+    #     if success
+    #       render_jsonapi(post, scope: false)
+    #     else
+    #       render_errors_for(post)
+    #     end
+    #   end
+    #
+    # @see Resource.model
+    # @see #resource
+    # @see #deserialized_params
+    # @return [Util::ValidationResponse]
     def jsonapi_create
       _persist do
         resource.persist_with_relationships \
@@ -56,6 +155,28 @@ module JsonapiCompliable
       end
     end
 
+    # Update the resource model and process all nested relationships via the
+    # serialized parameters. Any error, including validation errors, will roll
+    # back the transaction.
+    #
+    # @example Basic Rails
+    #   # Example Resource must have 'model'
+    #   #
+    #   # class PostResource < ApplicationResource
+    #   #   model Post
+    #   # end
+    #   def update
+    #     post, success = jsonapi_update.to_a
+    #
+    #     if success
+    #       render_jsonapi(post, scope: false)
+    #     else
+    #       render_errors_for(post)
+    #     end
+    #   end
+    #
+    # @see #jsonapi_create
+    # @return [Util::ValidationResponse]
     def jsonapi_update
       _persist do
         resource.persist_with_relationships \
@@ -65,21 +186,37 @@ module JsonapiCompliable
       end
     end
 
-    def _persist
-      validation_response = nil
-      resource.transaction do
-        object = yield
-        validation_response = Util::ValidationResponse.new \
-          object, deserialized_params
-        raise Errors::ValidationError unless validation_response.to_a[1]
-      end
-      validation_response
-    end
-
-    def perform_render_jsonapi(opts)
-      JSONAPI::Serializable::Renderer.render(opts.delete(:jsonapi), opts)
-    end
-
+    # Similar to +render :json+ or +render :jsonapi+
+    #
+    # By default, this will "build" the scope via +#jsonapi_scope+. To avoid
+    # this, pass +scope: false+
+    #
+    # This builds relevant options and sends them to
+    # +JSONAPI::Serializable::Renderer.render+from
+    # {http://jsonapi-rb.org jsonapi-rb}
+    #
+    # @example Build Scope by Default
+    #   # Employee.all returns an ActiveRecord::Relation. No SQL is fired at this point.
+    #   # We further 'chain' onto this scope, applying pagination, sorting,
+    #   # filters, etc that the user has requested.
+    #   def index
+    #     employees = Employee.all
+    #     render_jsonapi(employees)
+    #   end
+    #
+    # @example Avoid Building Scope by Default
+    #   # Maybe we already manually scoped, and don't want to fire the logic twice
+    #   # This code is equivalent to the above example
+    #   def index
+    #     scope = jsonapi_scope(Employee.all)
+    #     # ... do other things with the scope ...
+    #     render_jsonapi(scope.resolve, scope: false)
+    #   end
+    #
+    # @param scope [Scope, Object] the scope to build or render.
+    # @param [Hash] opts the render options passed to {http://jsonapi-rb.org jsonapi-rb}
+    # @option opts [Boolean] :scope Default: true. Should we call #jsonapi_scope on this object?
+    # @see #jsonapi_scope
     def render_jsonapi(scope, opts = {})
       scope = jsonapi_scope(scope) unless opts[:scope] == false || scope.is_a?(JsonapiCompliable::Scope)
       opts  = default_jsonapi_render_options.merge(opts)
@@ -89,29 +226,41 @@ module JsonapiCompliable
       perform_render_jsonapi(opts)
     end
 
-    # render_jsonapi(foo) equivalent to
-    # render jsonapi: foo, default_jsonapi_render_options
+    # Define a hash that will be automatically merged into your
+    # render_jsonapi call
+    #
+    # @example
+    #   # this
+    #   render_jsonapi(foo)
+    #   # is equivalent to this
+    #   render jsonapi: foo, default_jsonapi_render_options
+    #
+    # @see #render_jsonapi
+    # @return [Hash] the options hash you define
     def default_jsonapi_render_options
       {}.tap do |options|
       end
     end
 
+    private
+
     def force_includes?
       not params[:data].nil?
     end
 
-    module ClassMethods
-      def jsonapi(resource: nil, &blk)
-        if resource
-          self._jsonapi_compliable = resource
-        else
-          if !self._jsonapi_compliable
-            self._jsonapi_compliable = Class.new(JsonapiCompliable::Resource)
-          end
-        end
+    def perform_render_jsonapi(opts)
+      JSONAPI::Serializable::Renderer.render(opts.delete(:jsonapi), opts)
+    end
 
-        self._jsonapi_compliable.class_eval(&blk) if blk
+    def _persist
+      validation_response = nil
+      resource.transaction do
+        object = yield
+        validation_response = Util::ValidationResponse.new \
+          object, deserialized_params
+        raise Errors::ValidationError unless validation_response.to_a[1]
       end
+      validation_response
     end
   end
 end

data/lib/jsonapi_compliable/deserializer.rb

@@ -1,35 +1,81 @@
+# Responsible for parsing incoming write payloads
+#
+# Given a PUT payload like:
+#
+#   {
+#     data: {
+#       id: '1',
+#       type: 'posts',
+#       attributes: { title: 'My Title' },
+#       relationships: {
+#         author: {
+#           data: {
+#             id: '1',
+#             type: 'authors'
+#           }
+#         }
+#       }
+#     },
+#     included: [
+#       {
+#         id: '1'
+#         type: 'authors',
+#         attributes: { name: 'Joe Author' }
+#       }
+#     ]
+#   }
+#
+# You can now easily deal with this payload:
+#
+#   deserializer.attributes
+#   # => { id: '1', title: 'My Title' }
+#   deserializer.meta
+#   # => { type: 'posts', method: :update }
+#   deserializer.relationships
+#   # {
+#   #   author: {
+#   #     meta: { ... },
+#   #     attributes: { ... },
+#   #     relationships: { ... }
+#   #   }
+#   # }
+#
+# When creating objects, we accept a +temp-id+ so that the client can track
+# the object it just created. Expect this in +meta+:
+#
+#   { type: 'authors', method: :create, temp_id: 'abc123' }
 class JsonapiCompliable::Deserializer
+  # @param payload [Hash] The incoming payload with symbolized keys
+  # @param env [Hash] the Rack env (e.g. +request.env+).
   def initialize(payload, env)
     @payload = payload
     @env = env
   end
 
+  # @return [Hash] the raw :data value of the payload
   def data
     @payload[:data]
   end
 
+  # @return [String] the raw :id value of the payload
   def id
     data[:id]
   end
 
+  # @return [Hash] the raw :attributes hash + +id+
   def attributes
     @attributes ||= raw_attributes.tap do |hash|
       hash.merge!(id: id) if id
     end
   end
 
-  def attributes=(attrs)
-    @attributes = attrs
-  end
-
-  def method
-    case @env['REQUEST_METHOD']
-      when 'POST' then :create
-      when 'PUT', 'PATCH' then :update
-      when 'DELETE' then :destroy
-    end
-  end
-
+  # 'meta' information about this resource. Includes:
+  #
+  # +type+: the jsonapi type
+  # +method+: create/update/destroy/disassociate. Based on the request env or the +method+ within the +relationships+ hash
+  # +temp_id+: the +temp-id+, if specified
+  #
+  # @return [Hash]
   def meta
     {
       type: data[:type],
@@ -38,23 +84,25 @@ class JsonapiCompliable::Deserializer
     }
   end
 
+  # @return [Hash] the relationships hash
   def relationships
     @relationships ||= process_relationships(raw_relationships)
   end
 
-  def included
-    @payload[:included] || []
-  end
-
+  # Parses the +relationships+ recursively and builds an all-hash
+  # include directive like
+  #
+  #   { posts: { comments: {} } }
+  #
+  # Relationships that have been marked for destruction will NOT
+  # be part of the include directive.
+  #
+  # @return [Hash] the include directive
   def include_directive(memo = {}, relationship_node = nil)
     relationship_node ||= relationships
 
     relationship_node.each_pair do |name, relationship_payload|
-      arrayified = [relationship_payload].flatten
-      next if arrayified.all? { |rp| removed?(rp) }
-
-      memo[name] ||= {}
-      deep_merge!(memo[name], sub_directives(memo[name], arrayified))
+      merge_include_directive(memo, name, relationship_payload)
     end
 
     memo
@@ -62,6 +110,27 @@ class JsonapiCompliable::Deserializer
 
   private
 
+  def merge_include_directive(memo, name, relationship_payload)
+    arrayified = [relationship_payload].flatten
+    return if arrayified.all? { |rp| removed?(rp) }
+
+    memo[name] ||= {}
+    deep_merge!(memo[name], sub_directives(memo[name], arrayified))
+    memo
+  end
+
+  def included
+    @payload[:included] || []
+  end
+
+  def method
+    case @env['REQUEST_METHOD']
+      when 'POST' then :create
+      when 'PUT', 'PATCH' then :update
+      when 'DELETE' then :destroy
+    end
+  end
+
   def removed?(relationship_payload)
     method = relationship_payload[:meta][:method]
     [:disassociate, :destroy].include?(method)