jsonapi_compliable 0.6.4 → 0.6.5

data/lib/jsonapi_compliable/scope.rb

@@ -1,5 +1,29 @@
 module JsonapiCompliable
+  # A Scope wraps an underlying object. It modifies that object
+  # using the corresponding Resource and Query, and how to resolve
+  # that underlying object scope.
+  #
+  # @example Basic Controller usage
+  #   def index
+  #     base  = Post.all
+  #     scope = jsonapi_scope(base)
+  #     scope.object == base # => true
+  #     scope.object = scope.object.where(active: true)
+  #
+  #     # actually fires sql
+  #     scope.resolve #=> [#<Post ...>, #<Post ...>, etc]
+  #   end
   class Scope
+    # @param object - The underlying, chainable base scope object
+    # @param resource - The Resource that will process the object
+    # @param query - The Query object for the current request
+    # @param [Hash] opts Options to configure the Scope
+    # @option opts [String] :namespace The nested relationship name
+    # @option opts [Boolean] :filter Opt-out of filter scoping
+    # @option opts [Boolean] :extra_fields Opt-out of extra_fields scoping
+    # @option opts [Boolean] :sort Opt-out of sort scoping
+    # @option opts [Boolean] :pagination Opt-out of pagination scoping
+    # @option opts [Boolean] :default_paginate Opt-out of default pagination when not specified in request
     def initialize(object, resource, query, opts = {})
       @object    = object
       @resource  = resource
@@ -7,17 +31,32 @@ module JsonapiCompliable
 
       # Namespace for the 'outer' or 'main' resource is its type
       # For its relationships, its the relationship name
-      # IOW when hitting /states, it's resource type 'states
+      # IOW when hitting /states, it's resource type 'states'
       # when hitting /authors?include=state its 'state'
       @namespace = opts.delete(:namespace) || resource.type
 
       apply_scoping(opts)
     end
 
+    # Resolve the requested stats. Returns hash like:
+    #
+    #   { rating: { average: 5.5, maximum: 9 } }
+    #
+    # @return [Hash] the resolved stat info
+    # @api private
     def resolve_stats
       Stats::Payload.new(@resource, query_hash, @unpaginated_object).generate
     end
 
+    # Resolve the scope. This is where SQL is actually fired, an HTTP
+    # request is actually made, etc.
+    #
+    # Does nothing if the user requested zero results, ie /posts?page[size]=0
+    #
+    # First resolves the top-level resource, then processes each relevant sideload
+    #
+    # @see Resource#resolve
+    # @return [Array] an array of resolved model instances
     def resolve
       if @query.zero_results?
         []
@@ -28,6 +67,9 @@ module JsonapiCompliable
       end
     end
 
+    # The slice of Query#to_hash for the current namespace
+    # @see Query#to_hash
+    # @api private
     def query_hash
       @query_hash ||= @query.to_hash[@namespace]
     end

data/lib/jsonapi_compliable/scoping/base.rb

@@ -1,8 +1,28 @@
 module JsonapiCompliable
   module Scoping
+    # The interface for scoping logic (filter, paginate, etc).
+    #
+    # This class defines some common behavior, such as falling back on
+    # a default if not part of the user request.
+    #
+    # @attr_reader [Resource] resource The corresponding Resource instance
+    # @attr_reader [Hash] query_hash the Query#to_hash node relevant to the current resource
+    #
+    # @see Scoping::DefaultFilter
+    # @see Scoping::ExtraFields
+    # @see Scoping::Filter
+    # @see Scoping::Paginate
+    # @see Scoping::Sort
+    # @see Scope#initialize
+    # @see Scope#query_hash
+    # @see Query#to_hash
     class Base
       attr_reader :resource, :query_hash
 
+      # @param [Resource] resource the Resource instance
+      # @param [Hash] query_hash the Query#to_hash node relevant to the current resource
+      # @param scope the base scope object to chain/modify
+      # @param [Hash] opts configuration options used by subclasses
       def initialize(resource, query_hash, scope, opts = {})
         @query_hash = query_hash
         @resource   = resource
@@ -10,6 +30,23 @@ module JsonapiCompliable
         @opts       = opts
       end
 
+      # Apply this scoping criteria.
+      # This is where we would chain on pagination, sorting, etc.
+      #
+      # If #apply? returns false, does nothing. Otherwise will apply
+      # the default logic:
+      #
+      #   # no block, run default logic via adapter
+      #   allow_filter :name
+      #
+      # Or the customized proc:
+      #
+      #   allow_filter :name do |scope, value|
+      #     scope.where("upper(name) = ?", value.upcase)
+      #   end
+      #
+      # @see #apply?
+      # @return the scope object
       def apply
         if apply?
           apply_standard_or_override
@@ -18,10 +55,31 @@ module JsonapiCompliable
         end
       end
 
+      # Should we process this scope logic?
+      #
+      # Useful for when we want to explicitly opt-out on
+      # certain requests, or avoid a default in certain contexts.
+      #
+      # @return [Boolean] if we should apply this scope logic
       def apply?
         true
       end
 
+      # Defines how to call/apply the default scoping logic
+      def apply_standard_scope
+        raise 'override in subclass'
+      end
+
+      # Defines how to call/apply the custom scoping logic provided by the
+      # user.
+      def apply_custom_scope
+        raise 'override in subclass'
+      end
+
+      private
+
+      # If the user customized (by providing a block in the Resource DSL)
+      # then call the custom proc. Else, call the default proc.
       def apply_standard_or_override
         if apply_standard_scope?
           @scope = apply_standard_scope
@@ -32,17 +90,10 @@ module JsonapiCompliable
         @scope
       end
 
+      # Should we apply the default proc, or a custom one?
       def apply_standard_scope?
         custom_scope.nil?
       end
-
-      def apply_standard_scope
-        raise 'override in subclass'
-      end
-
-      def apply_custom_scope
-        raise 'override in subclass'
-      end
     end
   end
 end

data/lib/jsonapi_compliable/scoping/default_filter.rb

@@ -1,7 +1,40 @@
 module JsonapiCompliable
+  # Default filters apply to every request, unless specifically overridden in
+  # the request.
+  #
+  # Maybe we only want to show active posts:
+  #
+  #   class PostResource < ApplicationResource
+  #     # ... code ...
+  #     default_filter :active do |scope|
+  #       scope.where(active: true)
+  #     end
+  #   end
+  #
+  # But if the user is an admin and specifically requests inactive posts:
+  #
+  #   class PostResource < ApplicationResource
+  #     # ... code ...
+  #     allow_filter :active, if: admin?
+  #
+  #     default_filter :active do |scope|
+  #       scope.where(active: true)
+  #     end
+  #   end
+  #
+  #   # Now a GET /posts?filter[active]=false will return inactive posts
+  #   # if the user is an admin.
+  #
+  # @see Resource.default_filter
+  # @see Resource.allow_filter
   class Scoping::DefaultFilter < Scoping::Base
     include Scoping::Filterable
 
+    # Apply the default filtering logic.
+    # Loop through each defined default filter, and apply the default
+    # proc unless an explicit override is requested
+    #
+    # @return scope the scope object we are chaining/modifying
     def apply
       resource.default_filters.each_pair do |name, opts|
         next if overridden?(name)

data/lib/jsonapi_compliable/scoping/extra_fields.rb

@@ -1,5 +1,38 @@
 module JsonapiCompliable
+  # Apply logic when an extra field is requested. Useful for eager loading
+  # associations used to compute the extra field.
+  #
+  # Given a Resource
+  #
+  #   class PersonResource < ApplicationResource
+  #     extra_field :net_worth do |scope|
+  #       scope.includes(:assets)
+  #     end
+  #   end
+  #
+  # And a corresponding serializer:
+  #
+  #   class SerializablePerson < JSONAPI::Serializable::Resource
+  #     extra_attribute :net_worth do
+  #       @object.assets.sum(&:value)
+  #     end
+  #   end
+  #
+  # When the user requests the extra field 'net_worth':
+  #
+  #   GET /people?extra_fields[people]=net_worth
+  #
+  # The +assets+ will be eager loaded and the 'net_worth' attribute
+  # will be present in the response. If this field is not explicitly
+  # requested, none of this logic fires.
+  #
+  # @see Resource.extra_field
+  # @see Extensions::ExtraAttribute
   class Scoping::ExtraFields < Scoping::Base
+    # Loop through all requested extra fields. If custom scoping
+    # logic is define for that field, run it. Otherwise, do nothing.
+    #
+    # @return the scope object we are chaining/modofying
     def apply
       each_extra_field do |callable|
         @scope = callable.call(@scope)

data/lib/jsonapi_compliable/scoping/filter.rb

@@ -1,7 +1,32 @@
 module JsonapiCompliable
+  # Apply filtering logic to the scope
+  #
+  # If the user requests to filter a field that has not been whitelisted,
+  # a +JsonapiCompliable::Errors::BadFilter+ error will be raised.
+  #
+  #   allow_filter :title # :title now whitelisted
+  #
+  # If the user requests a filter field that has been whitelisted, but
+  # does not pass the associated `+:if+ clause, +BadFilter+ will be raised.
+  #
+  #   allow_filter :title, if: :admin?
+  #
+  # This will also honor filter aliases.
+  #
+  #   # GET /posts?filter[headline]=foo will filter on title
+  #   allow_filter :title, aliases: [:headline]
+  #
+  # @see Adapters::Abstract#filter
+  # @see Adapters::ActiveRecord#filter
+  # @see Resource.allow_filter
   class Scoping::Filter < Scoping::Base
     include Scoping::Filterable
 
+    # Apply the filtering logic.
+    #
+    # Loop and parse all requested filters, taking into account guards and
+    # aliases. If valid, call either the default or custom filtering logic.
+    # @return the scope we are chaining/modifying
     def apply
       each_filter do |filter, value|
         @scope = filter_scope(filter, value)
@@ -10,6 +35,10 @@ module JsonapiCompliable
       @scope
     end
 
+    private
+
+    # If there's custom logic, run it, otherwise run the default logic
+    # specified in the adapter.
     def filter_scope(filter, value)
       if custom_scope = filter.values.first[:filter]
         custom_scope.call(@scope, value)
@@ -18,8 +47,6 @@ module JsonapiCompliable
       end
     end
 
-    private
-
     def each_filter
       filter_param.each_pair do |param_name, param_value|
         filter = find_filter!(param_name.to_sym)

data/lib/jsonapi_compliable/scoping/filterable.rb

@@ -1,11 +1,14 @@
 module JsonapiCompliable
+  # @api private
   module Scoping::Filterable
+    # @api private
     def find_filter(name)
       find_filter!(name)
     rescue JsonapiCompliable::Errors::BadFilter
       nil
     end
 
+    # @api private
     def find_filter!(name)
       filter_name, filter_value = \
         resource.filters.find { |_name, opts| opts[:aliases].include?(name.to_sym) }
@@ -16,6 +19,7 @@ module JsonapiCompliable
       { filter_name => filter_value }
     end
 
+    # @api private
     def filter_param
       query_hash[:filter]
     end

data/lib/jsonapi_compliable/scoping/paginate.rb

@@ -1,7 +1,32 @@
 module JsonapiCompliable
+  # Apply pagination logic to the scope
+  #
+  # If the user requests a page size greater than +MAX_PAGE_SIZE+,
+  # a +JsonapiCompliable::Errors::UnsupportedPageSize+ error will be raised.
+  #
+  # Notably, this will not fire when the `default: false` option is passed.
+  # This is the case for sideloads - if the user requests "give me the post
+  # and its comments", we shouldn't implicitly limit those comments to 20.
+  # *BUT* if the user requests, "give me the post and 3 of its comments", we
+  # *should* honor that pagination.
+  #
+  # This can be confusing because there are also 'default' and 'customized'
+  # pagination procs. The default comes 'for free'. Customized pagination
+  # looks like
+  #
+  #   class PostResource < ApplicationResource
+  #     paginate do |scope, current_page, per_page|
+  #       # ... the custom logic ...
+  #     end
+  #   end
+  #
+  # We should use the default unless the user has customized.
+  # @see Resource.paginate
   class Scoping::Paginate < Scoping::Base
     MAX_PAGE_SIZE = 1_000
 
+    # Apply the pagination logic. Raise error if over the max page size.
+    # @return the scope object we are chaining/modifying
     def apply
       if size > MAX_PAGE_SIZE
         raise JsonapiCompliable::Errors::UnsupportedPageSize
@@ -11,6 +36,11 @@ module JsonapiCompliable
       end
     end
 
+    # We want to apply this logic unless we've explicitly received the
+    # +default: false+ option. In that case, only apply if pagination
+    # was explicitly specified in the request.
+    #
+    # @return [Boolean] should we apply this logic?
     def apply?
       if @opts[:default] == false
         not [page_param[:size], page_param[:number]].all?(&:nil?)
@@ -19,14 +49,17 @@ module JsonapiCompliable
       end
     end
 
+    # @return [Proc, Nil] the custom pagination proc
     def custom_scope
       resource.pagination
     end
 
+    # Apply default pagination proc via the Resource adapter
     def apply_standard_scope
       resource.adapter.paginate(@scope, number, size)
     end
 
+    # Apply the custom pagination proc
     def apply_custom_scope
       custom_scope.call(@scope, number, size)
     end

data/lib/jsonapi_compliable/scoping/sort.rb

@@ -1,9 +1,25 @@
 module JsonapiCompliable
+  # Apply sorting logic to the scope.
+  #
+  # By default, sorting comes 'for free'. To specify a custom sorting proc:
+  #
+  #   class PostResource < ApplicationResource
+  #     sort do |scope, att, dir|
+  #       int = dir == :desc ? -1 : 1
+  #       scope.sort_by { |x| x[att] * int }
+  #     end
+  #   end
+  #
+  # The sorting proc will be called once for each sort att/dir requested.
+  # @see Resource.sort
   class Scoping::Sort < Scoping::Base
+    # @return [Proc, Nil] The custom proc specified by Resource DSL
     def custom_scope
       resource.sorting
     end
 
+    # Apply default scope logic via Resource adapter
+    # @return the scope we are chaining/modifying
     def apply_standard_scope
       each_sort do |attribute, direction|
         @scope = resource.adapter.order(@scope, attribute, direction)
@@ -11,6 +27,8 @@ module JsonapiCompliable
       @scope
     end
 
+    # Apply custom scoping proc configured via Resource DSL
+    # @return the scope we are chaining/modifying
     def apply_custom_scope
       each_sort do |attribute, direction|
         @scope = custom_scope.call(@scope, attribute, direction)

data/lib/jsonapi_compliable/sideload.rb

@@ -1,4 +1,15 @@
 module JsonapiCompliable
+  # @attr_reader [Symbol] name The name of the sideload
+  # @attr_reader [Class] resource_class The corresponding Resource class
+  # @attr_reader [Boolean] polymorphic Is this a polymorphic sideload?
+  # @attr_reader [Hash] polymorphic_groups The subgroups, when polymorphic
+  # @attr_reader [Hash] sideloads The associated sibling sideloads
+  # @attr_reader [Proc] scope_proc The configured 'scope' block
+  # @attr_reader [Proc] assign_proc The configured 'assign' block
+  # @attr_reader [Proc] grouper The configured 'group_by' proc
+  # @attr_reader [Symbol] foreign_key The attribute used to match objects - need not be a true database foreign key.
+  # @attr_reader [Symbol] primary_key The attribute used to match objects - need not be a true database primary key.
+  # @attr_reader [Symbol] type One of :has_many, :belongs_to, etc
   class Sideload
     attr_reader :name,
       :resource_class,
@@ -12,6 +23,11 @@ module JsonapiCompliable
       :primary_key,
       :type
 
+    # NB - the adapter's +#sideloading_module+ is mixed in on instantiation
+    #
+    # An anonymous Resource will be assigned when none provided.
+    #
+    # @see Adapters::Abstract#sideloading_module
     def initialize(name, type: nil, resource: nil, polymorphic: false, primary_key: :id, foreign_key: nil)
       @name               = name
       @resource_class     = (resource || Class.new(Resource))
@@ -25,30 +41,178 @@ module JsonapiCompliable
       extend @resource_class.config[:adapter].sideloading_module
     end
 
+    # @see #resource_class
+    # @return [Resource] an instance of +#resource_class+
     def resource
       @resource ||= resource_class.new
     end
 
+    # Is this sideload polymorphic?
+    #
+    # Polymorphic sideloads group the parent objects in some fashion,
+    # so different 'types' can be resolved differently. Let's say an
+    # +Office+ has a polymorphic +Organization+, which can be either a
+    # +Business+ or +Government+:
+    #
+    #   allow_sideload :organization, :polymorphic: true do
+    #     group_by { |record| record.organization_type }
+    #
+    #     allow_sideload 'Business', resource: BusinessResource do
+    #       # ... code ...
+    #     end
+    #
+    #     allow_sideload 'Governemnt', resource: GovernmentResource do
+    #       # ... code ...
+    #     end
+    #   end
+    #
+    # You probably want to extract this code into an Adapter. For instance,
+    # with ActiveRecord:
+    #
+    #   polymorphic_belongs_to :organization,
+    #     group_by: ->(office) { office.organization_type },
+    #     groups: {
+    #       'Business' => {
+    #         scope: -> { Business.all },
+    #         resource: BusinessResource,
+    #         foreign_key: :organization_id
+    #       },
+    #       'Government' => {
+    #         scope: -> { Government.all },
+    #         resource: GovernmentResource,
+    #         foreign_key: :organization_id
+    #       }
+    #     }
+    #
+    # @see Adapters::ActiveRecordSideloading#polymorphic_belongs_to
+    # @return [Boolean] is this sideload polymorphic?
     def polymorphic?
       @polymorphic == true
     end
 
+    # Build a scope that will be used to fetch the related records
+    # This scope will be further chained with filtering/sorting/etc
+    #
+    # You probably want to wrap this logic in an Adapter, instead of
+    # specifying in your resource directly.
+    #
+    # @example Default ActiveRecord
+    #   class PostResource < ApplicationResource
+    #     # ... code ...
+    #     allow_sideload :comments, resource: CommentResource do
+    #       scope do |posts|
+    #         Comment.where(post_id: posts.map(&:id))
+    #       end
+    #       # ... code ...
+    #     end
+    #   end
+    #
+    # @example Custom Scope
+    #   # In this example, our base scope is a Hash
+    #   scope do |posts|
+    #     { post_ids: posts.map(&:id) }
+    #   end
+    #
+    # @example ActiveRecord via Adapter
+    #   class PostResource < ApplicationResource
+    #     # ... code ...
+    #     has_many :comments,
+    #       scope: -> { Comment.all },
+    #       resource: CommentResource,
+    #       foreign_key: :post_id
+    #   end
+    #
+    # @see Adapters::Abstract
+    # @see Adapters::ActiveRecordSideloading#has_many
+    # @see #allow_sideload
+    # @yieldparam parents - The resolved parent records
     def scope(&blk)
       @scope_proc = blk
     end
 
+    # The proc used to assign the resolved parents and children.
+    #
+    # You probably want to wrap this logic in an Adapter, instead of
+    # specifying in your resource directly.
+    #
+    # @example Default ActiveRecord
+    #   class PostResource < ApplicationResource
+    #     # ... code ...
+    #     allow_sideload :comments, resource: CommentResource do
+    #       # ... code ...
+    #       assign do |posts, comments|
+    #         posts.each do |post|
+    #           relevant_comments = comments.select { |c| c.post_id == post.id }
+    #           post.comments = relevant_comments
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # @example ActiveRecord via Adapter
+    #   class PostResource < ApplicationResource
+    #     # ... code ...
+    #     has_many :comments,
+    #       scope: -> { Comment.all },
+    #       resource: CommentResource,
+    #       foreign_key: :post_id
+    #   end
+    #
+    # @see Adapters::Abstract
+    # @see Adapters::ActiveRecordSideloading#has_many
+    # @see #allow_sideload
+    # @yieldparam parents - The resolved parent records
+    # @yieldparam children - The resolved child records
     def assign(&blk)
       @assign_proc = blk
     end
 
+    # Configure how to associate parent and child records.
+    #
+    # @example Basic attr_accessor
+    #   def associate(parent, child)
+    #     if type == :has_many
+    #       parent.send(:"#{name}").push(child)
+    #     else
+    #       child.send(:"#{name}=", parent)
+    #     end
+    #   end
+    #
+    # @see #name
+    # @see #type
     def associate(parent, child)
       resource_class.config[:adapter].associate(parent, child, name, type)
     end
 
+    # Define a proc that groups the parent records. For instance, with
+    # an ActiveRecord polymorphic belongs_to there will be a +parent_id+
+    # and +parent_type+. We would want to group on +parent_type+:
+    #
+    #  allow_sideload :organization, polymorphic: true do
+    #    # group parent_type, parent here is 'organization'
+    #    group_by ->(office) { office.organization_type }
+    #  end
+    #
+    # @see #polymorphic?
     def group_by(&grouper)
       @grouper = grouper
     end
 
+    # Resolve the sideload.
+    #
+    # * Uses the 'scope' proc to build a 'base scope'
+    # * Chains additional criteria onto that 'base scope'
+    # * Resolves that scope (see Scope#resolve)
+    # * Assigns the resulting child objects to their corresponding parents
+    #
+    # @see Scope#resolve
+    # @param [Object] parents The resolved parent models
+    # @param [Query] query The Query instance
+    # @param [Symbol] namespace The current namespace (see Resource#with_context)
+    # @see Query
+    # @see Resource#with_context
+    # @return [void]
+    # @api private
     def resolve(parents, query, namespace = nil)
       namespace ||= name
 
@@ -59,6 +223,44 @@ module JsonapiCompliable
       end
     end
 
+    # Configure a relationship between Resource objects
+    #
+    # You probably want to extract this logic into an adapter
+    # rather than using directly
+    #
+    # @example Default ActiveRecord
+    #   # What happens 'under the hood'
+    #   class CommentResource < ApplicationResource
+    #     # ... code ...
+    #     allow_sideload :post, resource: PostResource do
+    #       scope do |comments|
+    #         Post.where(id: comments.map(&:post_id))
+    #       end
+    #
+    #       assign do |comments, posts|
+    #         comments.each do |comment|
+    #           relevant_post = posts.find { |p| p.id == comment.post_id }
+    #           comment.post = relevant_post
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    #   # Rather than writing that code directly, go through the adapter:
+    #   class CommentResource < ApplicationResource
+    #     # ... code ...
+    #     use_adapter JsonapiCompliable::Adapters::ActiveRecord
+    #
+    #     belongs_to :post,
+    #       scope: -> { Post.all },
+    #       resource: PostResource,
+    #       foreign_key: :post_id
+    #   end
+    #
+    # @see Adapters::ActiveRecordSideloading#belongs_to
+    # @see #assign
+    # @see #scope
+    # @return void
     def allow_sideload(name, opts = {}, &blk)
       sideload = Sideload.new(name, opts)
       sideload.instance_eval(&blk) if blk
@@ -70,11 +272,37 @@ module JsonapiCompliable
       end
     end
 
+    # Fetch a Sideload object by its name
+    # @param [Symbol] name The name of the corresponding sideload
+    # @see +allow_sideload
+    # @return the corresponding Sideload object
     def sideload(name)
       @sideloads[name]
     end
 
-    # Grab from nested sideloads, AND resource, recursively
+    # Looks at all nested sideload, and all nested sideloads for the
+    # corresponding Resources, and returns an Include Directive hash
+    #
+    # For instance, this configuration:
+    #
+    #   class BarResource < ApplicationResource
+    #     allow_sideload :baz do
+    #     end
+    #   end
+    #
+    #   class PostResource < ApplicationResource
+    #     allow_sideload :foo do
+    #       allow_sideload :bar, resource: BarResource do
+    #       end
+    #     end
+    #   end
+    #
+    # +post_resource.sideloading.to_hash+ would return
+    #
+    #   { base: { foo: { bar: { baz: {} } } } }
+    #
+    # @return [Hash] The nested include hash
+    # @api private
     def to_hash(processed = [])
       return { name => {} } if processed.include?(self)
       processed << self