active_facets 1.2.2

data/lib/active_facets/serializer/base.rb

@@ -0,0 +1,291 @@
+module ActiveFacets
+  module Serializer
+    module Base
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+
+        # ###
+        # DSL
+        # ###
+
+        # See Readme.md
+
+        # DSL Defines a transform to rename or reformat an attribute
+        # @param api_attribute [Symbol] name of the attribute
+        # @param options [Hash]
+        # @option options [Symbol] :as internal method name to call on the resource for serialization and hydration
+        # @option options [Symbol] :from internal method name to call on the resource for serialization
+        # @option options [Symbol] :to internal method name to call on the resource for hydration
+        # @option options [Symbol] :with name of a CustomAttributeSerializer Class for serialization and hydration
+        # @option options [Symbol] :within name of nested json attribute to serialize/hyrdrate within
+        def transform(api_attribute, options = {})
+          if options[:as].present?
+            config.transforms_from[api_attribute]  = options[:as]
+            config.transforms_to[api_attribute] = options[:as]
+          end
+          if options[:from].present?
+            config.transforms_from[api_attribute] = options[:from]
+            config.transforms_to[api_attribute] ||= options[:from]
+          end
+          if options[:to].present?
+            config.transforms_from[api_attribute] ||= options[:to]
+            config.transforms_to[api_attribute] = options[:to]
+          end
+          config.serializers[api_attribute] = options[:with]    if options[:with].present?
+          config.namespaces[api_attribute]  = options[:within]  if options[:within].present?
+          expose api_attribute
+        end
+
+        # DSL Defines an attribute extension available for decoration and serialization
+        # @param api_attribute [Symbol] name of the attribute
+        def extension(api_attribute)
+          config.extensions[api_attribute] = true
+          config.serializers[api_attribute] = api_attribute.to_sym
+          expose api_attribute
+        end
+
+        # DSL Defines an alias that can be used instead of a Field Set
+        # @param field_set_name [Symbol] the alias name
+        # @param options [Hash]
+        # @option as [MIXED] a nested field_set collection
+        def expose(field_set_name, options = {})
+          field_set_name = field_set_name.to_sym
+          raise ActiveFacets::Errors::ConfigurationError.new(ActiveFacets::Errors::ConfigurationError::ALL_ATTRIBUTES_ERROR_MSG) if field_set_name == :all_attributes
+          raise ActiveFacets::Errors::ConfigurationError.new(ActiveFacets::Errors::ConfigurationError::ALL_FIELDS_ERROR_MSG) if field_set_name == :all
+          config.alias_field_set(field_set_name, options.key?(:as) ? options[:as] : field_set_name)
+        end
+
+        #DSL Defines an alias for common ActiveRecord attributes
+        def expose_timestamps
+          transform :created_at, with: :time
+          transform :updated_at, with: :time
+          expose :timestamps, as: [:id, :created_at, :updated_at]
+        end
+
+        #DSL Registers the class type to be serialized
+        def resource_class(klass)
+          config.resource_class = klass
+        end
+
+        # ###
+        # Public Interface
+        # ###
+
+        # Singleton
+        # @return [Serializer::Base]
+        def new
+          @instance ||= super
+        end
+
+        # TODO --jdc change new/instance contract
+        # def instance
+        #   @instance ||= new
+        # end
+
+        # Memoized class getter
+        # @return [Config]
+        def config
+          @config ||= ActiveFacets::Config.new
+        end
+
+      end
+
+      # INSTANCE METHODS
+
+      # This method returns a hash suitable to pass into ActiveRecord.includes to avoid N+1
+      # @param field_set [Field Set] collections of fields to be serialized from this resource later
+      # given:
+      #  :basic is a defined collection
+      #  :extended is a defined collection
+      #  :orders is a defined association
+      #  :line_items is a defined association on OrderSerializer
+      # examples:
+      #  :basic
+      #  [:basic]
+      #  {basic: nil}
+      #  [:basic, :extended]
+      #  [:basic, :extended, :orders]
+      #  [:basic, :extended, {orders: :basic}]
+      #  [:basic, :extended, {orders: [:basic, :extended]}]
+      #  [:basic, :extended, {orders: [:basic, :line_items]}]
+      #  [:basic, :extended, {orders: [:basic, {line_items: :extended}]}]
+      # @return [Hash]
+      def scoped_includes(field_set = nil, options = {})
+        result = {}
+        config.field_set_itterator(field_set) do |field, nested_field_set|
+          case value = scoped_include(field, nested_field_set, options)
+          when nil
+          when Hash
+            result.deep_merge! value
+          else
+            result[value] ||= nil
+          end
+        end
+        result
+      end
+
+      def scoped_include(field, nested_field_set, options)
+        if is_association? field
+          attribute = resource_attribute_name(field)
+          if nested_field_set
+            serializer_class = get_association_serializer_class(field, options)
+            attribute = { attribute => serializer_class.present? ? serializer_class.scoped_includes(nested_field_set, options) : nested_field_set }
+          end
+          attribute
+        else
+          custom_includes(field, options)
+        end
+      end
+
+      # Returns field_set serialized for dependant resources in custom attribute serializers & extensions
+      # @param field [Field]
+      # @return [Field Set]
+      def custom_includes(field, options)
+        attribute = resource_attribute_name(field)
+        custom_serializer_name = config.serializers[attribute]
+
+        if custom_serializer_name
+          custom_serializer = get_custom_serializer_class(custom_serializer_name, options)
+          if custom_serializer.respond_to? :custom_scope
+            custom_serializer.custom_scope
+          else
+            nil
+          end
+        else
+          nil
+        end
+      end
+
+      # Gets flattened fields from a Field Set Alias
+      # @param field_set_alias [Symbol] to retrieve aliased field_sets for
+      # @param include_relations [Boolean]
+      # @param include_nested_field_sets [Boolean]
+      # @return [Array] of symbols
+      def exposed_aliases(field_set_alias = :all, include_relations = false, include_nested_field_sets = false)
+        return include_nested_field_sets ? field_set_alias : [field_set_alias] unless normalized_field_sets = config.normalized_field_sets[field_set_alias]
+        result = normalized_field_sets[include_relations ? :fields : :attributes]
+        return result if include_nested_field_sets
+        result.keys.map(&:to_sym).sort
+      end
+
+      # This method returns a ActiveRecord model updated to match a JSON of hash values
+      # @param resource [ActiveRecord] to hydrate
+      # @param attribute [Hash] subset of the values returned by {resource.as_json}
+      # @return [ActiveRecord] resource
+      def from_hash(resource, attributes, options = {})
+        ActiveFacets::Serializer::Facade.new(self, resource, options).from_hash(attributes)
+      end
+
+      # This method returns a JSON of hash values representing the resource(s)
+      # @param resource [ActiveRecord || Array] CollectionProxy object ::or:: a collection of resources
+      # @param options [Hash] collection of values required that are not available in lexical field_set
+      # @return [JSON] representing the resource
+      def as_json(resources, options = {})
+        resource_itterator(resources) do |resource|
+          facade = ActiveFacets::Serializer::Facade.new(self, resource, options)
+          facade.as_json
+        end
+      end
+
+      # Memoized instance getter
+      # @return [Config]
+      def config
+        @config ||= self.class.config
+      end
+
+      ### TODO --jdc ^^ START REFLECTOR
+      # move all this to config or resource manager
+
+      # Constantizes the appropriate resource serializer class
+      # @return [Class]
+      def resource_class
+        @resource_class ||= config.resource_class
+      end
+
+      # Constantizes an appropriate resource serializer class for relations
+      # @param field [Symbol] to find relation reflection for
+      # @return [Reflection | nil]
+      def get_association_reflection(field)
+        @association_reflections ||= {}
+        @association_reflections[field] ||= resource_class.reflect_on_association(resource_attribute_name(field).to_sym)
+      end
+
+      # Constantizes an appropriate resource serializer class
+      # @param field [Symbol] to test as relation and find serializer class for
+      # @return [Class | nil]
+      def get_association_serializer_class(field, options)
+        @association_serializers ||= {}
+        unless @association_serializers.key? field
+          @association_serializers[field] = nil
+          #return nil if field isn't an association
+          if reflection = get_association_reflection(field)
+            #return nil if association doesn't have a custom class
+            @association_serializers[field] = ActiveFacets::ResourceManager.instance.serializer_for(reflection.klass, options)
+          end
+        end
+        @association_serializers[field]
+      end
+
+      # Constantizes an appropriate attribute serializer class
+      # @param attribute [Symbol] base_name of attribute serializer class to find
+      # @param options [Hash]
+      # @return [Class | nil]
+      def get_custom_serializer_class(attribute, options)
+        @custom_serializers ||= {}
+        @custom_serializers[attribute] ||= ActiveFacets::ResourceManager.instance.attribute_serializer_class_for(resource_class, attribute, options)
+      end
+
+      # Determines if public attribute maps to a private relation
+      # @param field [Symbol] public attribute name
+      # @return [Boolean]
+      def is_association?(field)
+        !!get_association_reflection(field)
+      end
+
+      # Renames attribute between resource.attribute_name and json.attribute_name
+      # @param field [Symbol] attribute name
+      # @param direction [Symbol] to apply translation
+      # @return [Symbol]
+      def resource_attribute_name(field, direction = :from)
+        (config.transforms(direction)[field] || field).to_sym
+      end
+
+      ### TODO ^^ END REFLECTOR
+
+      protected
+
+      # @return [Serializer::Base]
+      def initialize
+        config.compile! self
+      rescue SystemStackError => e
+        raise ActiveFacets::Errors::ConfigurationError.new(ActiveFacets::Errors::ConfigurationError::STACK_ERROR_MSG)
+      end
+
+      # Itterates a resource collection invoking block
+      # @param resource [ActiveRecord || Array] to traverse
+      # @param block [Block] to call for each resource
+      def resource_itterator(resource)
+        if resource.is_a?(Array)
+          resource.map do |resource|
+            yield resource
+          end.compact
+        else
+          yield resource
+        end
+      end
+
+      # Removes self.class_name from the end of self.module_name
+      # @return [String]
+      def module_base_name
+        @module_base_name ||= module_name.deconstantize
+      end
+
+      # Removes self.class_name from the end of self.class.name
+      # @return [String]
+      def module_name
+        @module_name ||= self.class.name.deconstantize
+      end
+    end
+  end
+end

data/lib/active_facets/serializer/facade.rb

@@ -0,0 +1,223 @@
+module ActiveFacets
+  module Serializer
+    class Facade
+      attr_accessor :serializer,  # Serializer:Base
+        :resource,                # Object to delegate to
+        :options,                 # Options Hash passed to as_json
+        :opts,                    # RCB specific options inside Options Hash
+        :fields,                  # Field Sets to apply
+        :field_overrides,         # Field Overrides to apply
+        :overrides,               # Field Overrides specific to resource
+        :version,                 # Serializer version to apply
+        :filters,                 # Filters to apply
+        :filters_enabled          # Apply Filters, override global setting
+
+      # @return [Serializer::Facade]
+      def initialize(serializer, resource, options = {})
+        self.serializer       = serializer
+        self.resource         = resource
+        self.options          = options
+        self.opts             = options[ActiveFacets.opts_key] || {}
+
+        self.fields           = opts[ActiveFacets.fields_key]
+        self.field_overrides  = opts[ActiveFacets.field_overrides_key] || {}
+        self.overrides        = ActiveFacets::ResourceManager.instance.resource_map(resource_class).inject({}) { |overrides, map_entry|
+          overrides.merge(field_overrides[map_entry] || {})
+        }
+
+        self.version          = opts[ActiveFacets.version_key]
+        self.filters          = opts[ActiveFacets.filters_key]
+        self.filters_enabled  = opts.key?(ActiveFacets.filters_force_key) ? opts[ActiveFacets.filters_force_key] : ActiveFacets.filters_enabled
+      end
+
+      # This method returns a JSON of hash values representing the resource
+      # @param resource [ActiveRecord || Array] CollectionProxy object ::or:: a collection of resources
+      # @param opts [Hash] collection of values required that are not available in lexical scope
+      # @return [JSON] representing the values returned by {resource.serialize} method
+      def as_json
+        ActiveFacets.document_cache.fetch(self) {
+          serialize!
+        }
+      end
+
+      # @return [String] a cache key that can be used to identify this resource
+      def cache_key
+        version.to_s +
+        resource.cache_key +
+        fields.to_s +
+        field_overrides.to_s +
+        filters.to_s
+      end
+
+      # This method returns a ActiveRecord model updated to match a JSON of hash values
+      # @param resource [ActiveRecord] to hydrate
+      # @param attribute [Hash] subset of the values returned by {resource.as_json}
+      # @return [ActiveRecord] resource
+      def from_hash(attributes)
+        hydrate! ActiveFacets.deep_copy(attributes)
+      end
+
+      private
+
+      # @return [Config]
+      def config
+        @config ||= serializer.config
+      end
+
+      # @return [Boolean]
+      def allowed_field?(field)
+        overrides.blank? || overrides[field.to_sym]
+      end
+
+      # Checks field to see if it is a relation that is valid have Field Sets applied to it
+      # @param expression [Symbol]
+      # @return [Boolean]
+      def is_expression_scopeable?(expression)
+        resource.persisted? && is_active_relation?(expression) && is_relation_scopeable?(expression)
+      end
+
+      # Checks field to see if expression is a relation
+      # @return [Boolean]
+      def is_active_relation?(expression)
+        #TODO -jdc let me know if anyone finds a better way to identify Proxy objects
+        #NOTE:: Proxy Collections use method missing for most actions; .scoped is the only reliable test
+        expression.is_a?(ActiveRecord::Relation) || (expression.is_a?(Array) && expression.respond_to?(:scoped))
+      end
+
+      # Checks expression to determine if filters are enabled
+      # @return [Boolean]
+      def is_relation_scopeable?(expression)
+        filters_enabled
+      end
+
+      #TODO --jdc this is a hack for assets. fix by making this class the primary entry point
+      # rather than serializers and pass in resource class, or better yet, enforce pseudo resource classes
+      # @return [Class]
+      def resource_class
+        resource.is_a?(ActiveRecord::Base) ? resource.class : serializer.resource_class
+      end
+
+      # This method returns a JSON of hash values representing the resource
+      # @return [JSON]
+      def serialize!
+        json = {}.with_indifferent_access
+
+        config.field_set_itterator(fields) do |scope, nested_scopes|
+          begin
+            json[scope] = get_resource_attribute scope, nested_scopes if allowed_field?(scope)
+          rescue ActiveFacets::Errors::AttributeError => e
+            # Deliberately do nothing. Ignore scopes that do not map to resource methods (or aliases)
+          end
+        end
+
+        apply_custom_serializers! json
+      end
+
+      # Gets serialized field from the resource
+      # @param field [Symbol]
+      # @param nested_scope [Mixed] Field Set to pass for relations
+      # @return [Mixed]
+      def get_resource_attribute(field, nested_field_set)
+        if config.namespaces.key? field
+          if ns = get_resource_attribute!(config.namespaces[field])
+            ns[serializer.resource_attribute_name(field).to_s]
+          else
+            nil
+          end
+        elsif config.extensions.key?(field)
+          field
+        elsif serializer.is_association?(field)
+          get_association_attribute(field, nested_field_set)
+        else
+          get_resource_attribute!(serializer.resource_attribute_name(field))
+        end
+      end
+
+      # Invokes a method on the resource to retrieve the attribute value
+      # @param attribute [Symbol] identifies
+      # @return [Object]
+      def get_resource_attribute!(attribute)
+        raise ActiveFacets::Errors::AttributeError.new("#{resource.class.name}.#{attribute} missing") unless resource.respond_to?(attribute,true)
+        resource.send(attribute)
+      end
+
+      # Retrieves scoped association from cache or record
+      # @param field [Symbol] attribute to get
+      # @return [Array | ActiveRelation] of ActiveRecord
+      def get_association_attribute(field, nested_field_set)
+        association = serializer.resource_attribute_name(field)
+
+        ActiveFacets.document_cache.fetch_association(self, association, opts) do
+          attribute = resource.send(association)
+          attribute = attribute.scope_filters(filters) if is_expression_scopeable?(attribute)
+          ActiveFacets.restore_opts_after(options, ActiveFacets.fields_key, nested_field_set) do
+            attribute.as_json(options)
+          end
+        end
+      end
+
+      # Modifies json by reference by applying custom serializers to all attributes registered with custom serializers
+      # @param json [JSON] structure
+      # @return [JSON]
+      def apply_custom_serializers!(json)
+        config.serializers.each do |scope, type|
+          scope_s = scope
+          json[scope_s] = ActiveFacets.restore_opts_after(options, ActiveFacets.fields_key, fields) do
+            serializer.get_custom_serializer_class(type, options).serialize(json[scope_s], resource, options)
+          end if json.key? scope_s
+        end
+
+        json
+      end
+
+      # This method returns a ActiveRecord model updated to match a JSON of hash values
+      # @param json [JSON] attributes identical to the values returned by {serialize}
+      # @return [ActiveRecord] resource
+      def hydrate!(json)
+        filter_allowed_keys! json, serializer.exposed_aliases
+        hydrate_scopes! json
+        json.each do |scope, value|
+          set_resource_attribute scope, value
+        end
+
+        resource
+      end
+
+      # Modifies json by reference to remove all attributes from json which aren't exposed
+      # @param json [JSON] structure
+      # @param keys [Array] of attributes
+      # @return [JSON]
+      def filter_allowed_keys!(json, keys)
+        values = json.with_indifferent_access
+        json.replace ( keys.inject({}.with_indifferent_access) { |results, key|
+          results[key] = values[key] if values.key?(key)
+          results
+        } )
+      end
+
+      # Modifies json by reference by applying custom hydration to all fields registered with custom serializers
+      # @param json [JSON] structure
+      # @return [JSON]
+      def hydrate_scopes!(json)
+        config.serializers.each do |scope, type|
+          scope_s = scope
+          json[scope_s] = serializer.get_custom_serializer_class(type, options).hydrate(json[scope], resource, options) if json.key? scope_s
+        end
+        json
+      end
+
+      # Sets the specified attribute on the resource
+      # @param field [Symbol] to set
+      # @param value [Mixed] to set
+      # @return [Mixed] for chaining
+      def set_resource_attribute(field, value)
+        if config.namespaces.key? field
+          resource.send(config.namespaces[field].to_s+"=", {}) unless resource.send(config.namespaces[field]).present?
+          resource.send(config.namespaces[field])[serializer.resource_attribute_name(field,:to).to_s] = value
+        else
+          resource.send("#{serializer.resource_attribute_name(field,:to)}=", value)
+        end
+      end
+    end
+  end
+end