jsonapi-resources 0.10.6 → 0.11.0.beta2

data/lib/jsonapi/{basic_resource.rb → resource_common.rb}

@@ -1,28 +1,30 @@
+# frozen_string_literal: true
+
 require 'jsonapi/callbacks'
 require 'jsonapi/configuration'
 
 module JSONAPI
-  class BasicResource
-    include Callbacks
-
-    @abstract = true
-    @immutable = true
-    @root = true
-
-    attr_reader :context
-
-    define_jsonapi_resources_callbacks :create,
-                                       :update,
-                                       :remove,
-                                       :save,
-                                       :create_to_many_link,
-                                       :replace_to_many_links,
-                                       :create_to_one_link,
-                                       :replace_to_one_link,
-                                       :replace_polymorphic_to_one_link,
-                                       :remove_to_many_link,
-                                       :remove_to_one_link,
-                                       :replace_fields
+  module ResourceCommon
+
+    def self.included(base)
+      base.extend ClassMethods
+
+      base.include Callbacks
+      base.define_jsonapi_resources_callbacks :create,
+                                         :update,
+                                         :remove,
+                                         :save,
+                                         :create_to_many_link,
+                                         :replace_to_many_links,
+                                         :create_to_one_link,
+                                         :replace_to_one_link,
+                                         :replace_polymorphic_to_one_link,
+                                         :remove_to_many_link,
+                                         :remove_to_one_link,
+                                         :replace_fields
+
+      base.attr_reader :context
+    end
 
     def initialize(model, context)
       @model = model
@@ -44,8 +46,16 @@ module JSONAPI
       JSONAPI::ResourceIdentity.new(self.class, id)
     end
 
+    def fragment(cache: nil, primary: false)
+      @fragment ||= JSONAPI::ResourceFragment.new(identity, resource: self, cache: cache, primary: primary)
+    end
+
+    def cache_field_value
+      _model.public_send(self.class._cache_field)
+    end
+
     def cache_id
-      [id, self.class.hash_cache_field(_model.public_send(self.class._cache_field))]
+      [id, self.class.hash_cache_field(cache_field_value)]
     end
 
     def is_new?
@@ -232,7 +242,7 @@ module JSONAPI
       return false if !relationship.reflect ||
         (!JSONAPI.configuration.use_relationship_reflection || options[:reflected_source])
 
-      inverse_relationship = relationship.resource_klass._relationships[relationship.inverse_relationship]
+      inverse_relationship = relationship.resource_klass._relationship(relationship.inverse_relationship)
       if inverse_relationship.nil?
         warn "Inverse relationship could not be found for #{self.class.name}.#{relationship.name}. Relationship reflection disabled."
         return false
@@ -241,7 +251,7 @@ module JSONAPI
     end
 
     def _create_to_many_links(relationship_type, relationship_key_values, options)
-      relationship = self.class._relationships[relationship_type]
+      relationship = self.class._relationship(relationship_type)
       relation_name = relationship.relation_name(context: @context)
 
       if options[:reflected_source]
@@ -263,7 +273,7 @@ module JSONAPI
 
       related_resources.each do |related_resource|
         if reflect
-          if related_resource.class._relationships[relationship.inverse_relationship].is_a?(JSONAPI::Relationship::ToMany)
+          if related_resource.class._relationship(relationship.inverse_relationship).is_a?(JSONAPI::Relationship::ToMany)
             related_resource.create_to_many_links(relationship.inverse_relationship, [id], reflected_source: self)
           else
             related_resource.replace_to_one_link(relationship.inverse_relationship, id, reflected_source: self)
@@ -285,9 +295,7 @@ module JSONAPI
       reflect = reflect_relationship?(relationship, options)
 
       if reflect
-        existing_rids = self.class.find_related_fragments([identity], relationship_type, options)
-
-        existing = existing_rids.keys.collect { |rid| rid.id }
+        existing = find_related_ids(relationship, options)
 
         to_delete = existing - (relationship_key_values & existing)
         to_delete.each do |key|
@@ -304,8 +312,8 @@ module JSONAPI
           ids = relationship_key_value[:ids]
 
           related_records = relationship_resource_klass
-            .records(options)
-            .where({relationship_resource_klass._primary_key => ids})
+                              .records(options)
+                              .where({relationship_resource_klass._primary_key => ids})
 
           missed_ids = ids - related_records.pluck(relationship_resource_klass._primary_key)
 
@@ -327,7 +335,7 @@ module JSONAPI
     end
 
     def _replace_to_one_link(relationship_type, relationship_key_value, _options)
-      relationship = self.class._relationships[relationship_type]
+      relationship = self.class._relationship(relationship_type)
 
       send("#{relationship.foreign_key}=", relationship_key_value)
       @save_needed = true
@@ -336,7 +344,7 @@ module JSONAPI
     end
 
     def _replace_polymorphic_to_one_link(relationship_type, key_value, key_type, _options)
-      relationship = self.class._relationships[relationship_type.to_sym]
+      relationship = self.class._relationship(relationship_type.to_sym)
 
       send("#{relationship.foreign_key}=", {type: key_type, id: key_value})
       @save_needed = true
@@ -345,7 +353,7 @@ module JSONAPI
     end
 
     def _remove_to_many_link(relationship_type, key, options)
-      relationship = self.class._relationships[relationship_type]
+      relationship = self.class._relationship(relationship_type)
 
       reflect = reflect_relationship?(relationship, options)
 
@@ -356,7 +364,7 @@ module JSONAPI
         if related_resource.nil?
           fail JSONAPI::Exceptions::RecordNotFound.new(key)
         else
-          if related_resource.class._relationships[relationship.inverse_relationship].is_a?(JSONAPI::Relationship::ToMany)
+          if related_resource.class._relationship(relationship.inverse_relationship).is_a?(JSONAPI::Relationship::ToMany)
             related_resource.remove_to_many_link(relationship.inverse_relationship, id, reflected_source: self)
           else
             related_resource.remove_to_one_link(relationship.inverse_relationship, reflected_source: self)
@@ -377,7 +385,7 @@ module JSONAPI
     end
 
     def _remove_to_one_link(relationship_type, _options)
-      relationship = self.class._relationships[relationship_type]
+      relationship = self.class._relationship(relationship_type)
 
       send("#{relationship.foreign_key}=", nil)
       @save_needed = true
@@ -417,8 +425,56 @@ module JSONAPI
       :completed
     end
 
-    class << self
+    def find_related_ids(relationship, options = {})
+      send(relationship.foreign_key)
+    end
+
+    module ClassMethods
+      def resource_retrieval_strategy(module_name = JSONAPI.configuration.default_resource_retrieval_strategy)
+        if @_resource_retrieval_strategy_loaded
+          warn "Resource retrieval strategy #{@_resource_retrieval_strategy_loaded} already loaded for #{self.name}"
+          return
+        end
+
+        module_name = module_name.to_s
+
+        return if module_name.blank? || module_name == 'self' || module_name == 'none'
+
+        class_eval do
+          resource_retrieval_module = module_name.safe_constantize
+          raise "Unable to find resource_retrieval_strategy #{module_name}" unless resource_retrieval_module
+
+          include resource_retrieval_module
+          extend "#{module_name}::ClassMethods".safe_constantize
+          @_resource_retrieval_strategy_loaded = module_name
+        end
+      end
+
+      def warn_about_missing_retrieval_methods
+        resource_retrieval_methods = %i[find count find_by_key find_by_keys find_to_populate_by_keys find_fragments
+                                        find_related_fragments find_included_fragments count_related]
+
+        resource_retrieval_methods.each do |method_name|
+          warn "#{self.name} has not defined standard method #{method_name}" unless self.respond_to?(method_name)
+        end
+      end
+
       def inherited(subclass)
+        super
+
+        # Defer loading the resource retrieval strategy module until the class has been fully read to allow setting
+        # a custom resource_retrieval_strategy in the class definition
+        trace_point = TracePoint.new(:end) do |tp|
+          if subclass == tp.self
+            unless subclass._abstract
+              subclass.warn_about_missing_retrieval_methods
+              subclass.warn_about_unused_methods if subclass.methods.include?(:warn_about_unused_methods)
+            end
+            tp.disable
+          end
+        end
+        trace_point.enable
+
         subclass.abstract(false)
         subclass.immutable(false)
         subclass.caching(_caching)
@@ -456,6 +512,9 @@ module JSONAPI
 
         subclass._clear_cached_attribute_options
         subclass._clear_fields_cache
+
+        subclass._resource_retrieval_strategy_loaded = @_resource_retrieval_strategy_loaded
+        subclass.resource_retrieval_strategy unless subclass._resource_retrieval_strategy_loaded
       end
 
       def rebuild_relationships(relationships)
@@ -467,7 +526,7 @@ module JSONAPI
           original_relationships.each_value do |relationship|
             options = relationship.options.dup
             options[:parent_resource] = self
-            options[:inverse_relationship] = relationship.inverse_relationship
+            options[:inverse_relationship] = relationship.options[:inverse_relationship]
             _add_relationship(relationship.class, relationship.name, options)
           end
         end
@@ -502,7 +561,8 @@ module JSONAPI
         end
       end
 
-      attr_accessor :_attributes, :_relationships, :_type, :_model_hints, :_routed, :_warned_missing_route
+      attr_accessor :_attributes, :_relationships, :_type, :_model_hints, :_routed, :_warned_missing_route,
+                    :_resource_retrieval_strategy_loaded
       attr_writer :_allowed_filters, :_paginator, :_allowed_sort
 
       def create(context)
@@ -565,23 +625,15 @@ module JSONAPI
                        # Note: this will allow the returning of model attributes without a corresponding
                        # resource attribute, for example a belongs_to id such as `author_id` or bypassing
                        # the delegate.
-                       attr = @_attributes[attribute]
+                       attr = @_attributes[attribute.to_sym]
                        attr && attr[:delegate] ? attr[:delegate].to_sym : attribute
                      end
-        if Rails::VERSION::MAJOR >= 5
-          attribute_type = _model_class.attribute_types[field_name.to_s]
-        else
-          attribute_type = _model_class.column_types[field_name.to_s]
-        end
-        { name: field_name, type: attribute_type}
+
+        { name: field_name, type: _model_class.attribute_types[field_name.to_s]}
       end
 
       def cast_to_attribute_type(value, type)
-        if Rails::VERSION::MAJOR >= 5
-          return type.cast(value)
-        else
-          return type.type_cast_from_database(value)
-        end
+        type.cast(value)
       end
 
       def default_attribute_options
@@ -591,14 +643,14 @@ module JSONAPI
       def relationship(*attrs)
         options = attrs.extract_options!
         klass = case options[:to]
-                  when :one
-                    Relationship::ToOne
-                  when :many
-                    Relationship::ToMany
-                  else
-                    #:nocov:#
-                    fail ArgumentError.new('to: must be either :one or :many')
-                    #:nocov:#
+                when :one
+                  Relationship::ToOne
+                when :many
+                  Relationship::ToMany
+                else
+                  #:nocov:#
+                  fail ArgumentError.new('to: must be either :one or :many')
+                  #:nocov:#
                 end
         _add_relationship(klass, *attrs, options.except(:to))
       end
@@ -609,10 +661,10 @@ module JSONAPI
 
       def belongs_to(*attrs)
         ActiveSupport::Deprecation.warn "In #{name} you exposed a `has_one` relationship "\
-                                        " using the `belongs_to` class method. We think `has_one`" \
-                                        " is more appropriate. If you know what you're doing," \
-                                        " and don't want to see this warning again, override the" \
-                                        " `belongs_to` class method on your resource."
+                                      " using the `belongs_to` class method. We think `has_one`" \
+                                      " is more appropriate. If you know what you're doing," \
+                                      " and don't want to see this warning again, override the" \
+                                      " `belongs_to` class method on your resource."
         _add_relationship(Relationship::ToOne, *attrs)
       end
 
@@ -636,7 +688,7 @@ module JSONAPI
       end
 
       def model_hint(model: _model_name, resource: _type)
-        resource_type = ((resource.is_a?(Class)) && (resource < JSONAPI::Resource)) ? resource._type : resource.to_s
+        resource_type = ((resource.is_a?(Class)) && resource.include?(JSONAPI::ResourceCommon)) ? resource._type : resource.to_s
 
         _model_hints[model.to_s.gsub('::', '/').underscore] = resource_type.to_s
       end
@@ -699,7 +751,22 @@ module JSONAPI
       end
 
       def fields
-        @_fields_cache ||= _relationships.keys | _attributes.keys
+        @_fields_cache ||= _relationships.select { |k,v| !v.hidden? }.keys | _attributes.keys
+      end
+
+      def to_one_relationships_including_optional_linkage_data
+        # ToDo: can we only calculate this once?
+        @to_one_relationships_including_optional_linkage_data =
+          _relationships.select do |_name, relationship|
+            relationship.is_a?(JSONAPI::Relationship::ToOne) && relationship.include_optional_linkage_data?
+          end
+      end
+
+      def to_one_relationships_for_linkage(include_related)
+        # exclude the relationships that are already included in the include_related param
+        include_related_names = include_related.present? ? include_related.keys : []
+        relationship_names = to_one_relationships_including_optional_linkage_data.keys - include_related_names
+        _relationships.fetch_values(*relationship_names)
       end
 
       def resources_for(records, context)
@@ -709,10 +776,14 @@ module JSONAPI
       end
 
       def resource_for(model_record, context)
-        resource_klass = self.resource_klass_for_model(model_record)
+        resource_klass = resource_klass_for_model(model_record)
         resource_klass.new(model_record, context)
       end
 
+      def resource_for_model(model, context)
+        resource_for(resource_type_for(model), context)
+      end
+
       def verify_filters(filters, context = nil)
         verified_filters = {}
         filters.each do |filter, raw_value|
@@ -773,12 +844,12 @@ module JSONAPI
         if @_singleton_options && @_singleton_options[:singleton_key]
           strategy = @_singleton_options[:singleton_key]
           case strategy
-            when Proc
-              key = strategy.call(context)
-            when Symbol, String
-              key = send(strategy, context)
-            else
-              raise "singleton_key must be a proc or function name"
+          when Proc
+            key = strategy.call(context)
+          when Symbol, String
+            key = send(strategy, context)
+          else
+            raise "singleton_key must be a proc or function name"
           end
         end
         key
@@ -853,13 +924,12 @@ module JSONAPI
 
       def _relationship(type)
         return nil unless type
-        type = type.to_sym
-        @_relationships[type]
+        @_relationships[type.to_sym]
       end
 
       def _model_name
         if _abstract
-           ''
+          ''
         else
           return @_model_name.to_s if defined?(@_model_name)
           class_name = self.name
@@ -882,7 +952,7 @@ module JSONAPI
       end
 
       def _default_primary_key
-        @_default_primary_key ||=_model_class.respond_to?(:primary_key) ? _model_class.primary_key : :id
+        @_default_primary_key ||= _model_class.respond_to?(:primary_key) ? _model_class.primary_key : :id
       end
 
       def _cache_field
@@ -973,14 +1043,14 @@ module JSONAPI
 
       def parse_exclude_links(exclude)
         case exclude
-          when :default, "default"
-            [:self]
-          when :none, "none"
-            []
-          when Array
-            exclude.collect {|link| link.to_sym}
-          else
-            fail "Invalid exclude_links"
+        when :default, "default"
+          [:self]
+        when :none, "none"
+          []
+        when Array
+          exclude.collect {|link| link.to_sym}
+        else
+          fail "Invalid exclude_links"
         end
       end
 
@@ -1016,6 +1086,22 @@ module JSONAPI
         nil
       end
 
+      def _included_strategy
+        @_included_strategy || JSONAPI.configuration.default_included_strategy
+      end
+
+      def included_strategy(included_strategy)
+        @_included_strategy = included_strategy
+      end
+
+      def _related_strategy
+        @_related_strategy || JSONAPI.configuration.default_related_strategy
+      end
+
+      def related_strategy(related_strategy)
+        @_related_strategy = related_strategy
+      end
+
       # Generate a hashcode from the value to be used as part of the cache lookup
       def hash_cache_field(value)
         value.hash
@@ -1054,7 +1140,7 @@ module JSONAPI
       end
 
       def default_sort
-        [{field: 'id', direction: :asc}]
+        [{field: _primary_key, direction: :asc}]
       end
 
       def construct_order_options(sort_params)
@@ -1083,11 +1169,23 @@ module JSONAPI
         end
       end
 
-      #   ResourceBuilder methods
+      def _setup_relationship(klass, *attrs)
+        _clear_fields_cache
+
+        options = attrs.extract_options!
+        options[:parent_resource] = self
+
+        relationship_name = attrs[0].to_sym
+        check_duplicate_relationship_name(relationship_name)
+
+        define_relationship_methods(relationship_name.to_sym, klass, options)
+      end
+
+      # ResourceBuilder methods
       def define_relationship_methods(relationship_name, relationship_klass, options)
         relationship = register_relationship(
-            relationship_name,
-            relationship_klass.new(relationship_name, options)
+          relationship_name,
+          relationship_klass.new(relationship_name, options)
         )
 
         define_foreign_key_setter(relationship)
@@ -1104,10 +1202,11 @@ module JSONAPI
             _model.method("#{relationship.foreign_key}=").call(value)
           end
         end
+        relationship.foreign_key
       end
 
       def define_on_resource(method_name, &block)
-        return if method_defined?(method_name)
+        return method_name if method_defined?(method_name)
         define_method(method_name, block)
       end
 

data/lib/jsonapi/resource_controller.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JSONAPI
   class ResourceController < ActionController::Base
     include JSONAPI::ActsAsResourceController

data/lib/jsonapi/resource_controller_metal.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JSONAPI
   class ResourceControllerMetal < ActionController::Metal
     MODULES = [

data/lib/jsonapi/resource_fragment.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JSONAPI
 
   # A ResourceFragment holds a ResourceIdentity and associated partial resource data.
@@ -6,42 +8,42 @@ module JSONAPI
   # cache - the value of the cache field for the resource instance
   # related - a hash of arrays of related resource identities, grouped by relationship name
   # related_from - a set of related resource identities that loaded the fragment
+  # resource - a resource instance
   #
-  # Todo: optionally use these for faster responses by bypassing model instantiation)
-  # attributes - resource attributes
 
   class ResourceFragment
-    attr_reader :identity, :attributes, :related_from, :related
+    attr_reader :identity, :related_from, :related, :resource
 
     attr_accessor :primary, :cache
 
     alias :cache_field :cache #ToDo: Rename one or the other
 
-    def initialize(identity)
+    def initialize(identity, resource: nil, cache: nil, primary: false)
       @identity = identity
-      @cache = nil
-      @attributes = {}
+      @cache = cache
+      @resource = resource
+      @primary = primary
+
       @related = {}
-      @primary = false
-      @related_from = Set.new
+      @related_from = SortedSet.new
     end
 
     def initialize_related(relationship_name)
-      @related ||= {}
       @related[relationship_name.to_sym] ||= Set.new
     end
 
     def add_related_identity(relationship_name, identity)
       initialize_related(relationship_name)
-      @related[relationship_name.to_sym] << identity
+      @related[relationship_name.to_sym] << identity if identity
     end
 
-    def add_related_from(identity)
-      @related_from << identity
+    def merge_related_identities(relationship_name, identities)
+      initialize_related(relationship_name)
+      @related[relationship_name.to_sym].merge(identities) if identities
     end
 
-    def add_attribute(name, value)
-      @attributes[name] = value
+    def add_related_from(identity)
+      @related_from << identity
     end
   end
-end
+end

data/lib/jsonapi/resource_identity.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JSONAPI
 
   # ResourceIdentity describes a unique identity of a resource in the system.
@@ -32,6 +34,10 @@ module JSONAPI
       [@resource_klass, @id].hash
     end
 
+    def <=>(other_identity)
+      self.id <=> other_identity.id
+    end
+
     # Creates a string representation of the identifier.
     def to_s
       # :nocov:

data/lib/jsonapi/resource_serializer.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 module JSONAPI
   class ResourceSerializer
 
     attr_reader :link_builder, :key_formatter, :serialization_options,
                 :fields, :include_directives, :always_include_to_one_linkage_data,
-                :always_include_to_many_linkage_data
+                :always_include_to_many_linkage_data, :options
 
     # initialize
     # Options can include
@@ -18,11 +20,12 @@ module JSONAPI
     # serialization_options: additional options that will be passed to resource meta and links lambdas
 
     def initialize(primary_resource_klass, options = {})
+      @options                = options
       @primary_resource_klass = primary_resource_klass
       @fields                 = options.fetch(:fields, {})
       @include                = options.fetch(:include, [])
-      @include_directives     = options[:include_directives]
-      @include_directives     ||= JSONAPI::IncludeDirectives.new(@primary_resource_klass, @include)
+      @include_directives     = options.fetch(:include_directives,
+                                              JSONAPI::IncludeDirectives.new(@primary_resource_klass, @include))
       @key_formatter          = options.fetch(:key_formatter, JSONAPI.configuration.key_formatter)
       @id_formatter           = ValueFormatter.value_formatter_for(:id)
       @link_builder           = generate_link_builder(primary_resource_klass, options)
@@ -41,6 +44,19 @@ module JSONAPI
       @_supplying_relationship_fields = {}
     end
 
+    # Converts a single resource, or an array of resources to a hash, conforming to the JSONAPI structure
+    def serialize_to_hash(source)
+      include_related = include_directives[:include_related]
+      resource_set = JSONAPI::ResourceSet.new(source, include_related, options)
+      resource_set.populate!(self, options[:context], options)
+
+      if source.is_a?(Array)
+        serialize_resource_set_to_hash_plural(resource_set)
+      else
+        serialize_resource_set_to_hash_single(resource_set)
+      end
+    end
+
     # Converts a resource_set to a hash, conforming to the JSONAPI structure
     def serialize_resource_set_to_hash_single(resource_set)
 
@@ -291,7 +307,7 @@ module JSONAPI
         if field_set.include?(name)
 
           relationship_name = unformat_key(name).to_sym
-          relationship_klass = source.resource_klass._relationships[relationship_name]
+          relationship_klass = source.resource_klass._relationship(relationship_name)
 
           if relationship_klass.is_a?(JSONAPI::Relationship::ToOne)
             # include_linkage = @always_include_to_one_linkage_data | relationship_klass.always_include_linkage_data