active_facet 1.2.8

data/lib/active_facet/config.rb

@@ -0,0 +1,267 @@
+#TODO --jdc rename field set to facet throughut project
+
+# Field = Symbol representing a json attribute that corresponds to resource attributes or extensions
+
+# Field Set = Nested, Mixed Collection of Fields, Aliases, and Relations (Strings, Symbols, Arrays and Hashes)
+#  e.g. [:a, {b: "c"}]
+
+# Normalized Field Set = Field Set with all Strings converted to Symbols, Aliases dealiased, and Arrays converted to Hashes
+
+# Field Set Alias = Symbol representing a Field Set
+
+module ActiveFacet
+  class Config
+
+    #TODO --decouple this class completely from serializer by moving reflection to resource_manager
+
+    # Boolean: state
+    attr_reader :compiled
+
+    # Serializer::Base
+    attr_reader :serializer
+
+    # Hash: compiled field sets
+    attr_reader :normalized_field_sets
+
+    # Hash: keys are public API attribute names, values are resource attribute names
+    attr_reader :transforms_from, :transforms_to
+
+    # Hash: API attribute names requiring custom serialization
+    attr_reader :serializers
+
+    # Hash: keys are resource attribute names storing nested JSON, values are nested attribute names
+    attr_reader :namespaces
+
+    # Hash: keys are defined extension values
+    attr_reader :extensions
+
+    # Class: Resource Class to serialize
+    attr_accessor :resource_class
+
+    # Store Facet
+    # @param field_set_alias [Symbol]
+    # @param field_set_alias [Facet]
+    def alias_field_set(field_set_alias, field_set)
+      self.compiled = false
+      field_sets[field_set_alias] = field_set
+    end
+
+    # Returns Field to resource attribute map
+    # @param direction [Symbol]
+    # @return [Hash]
+    def transforms(direction = :from)
+      direction == :from ? transforms_from : transforms_to
+    end
+
+    # (Memoized) Normalizes all Field Set Aliases
+    # @param serializer [Serializer::Base]
+    # @return [Config]
+    def compile!(serializer)
+      self.serializer = serializer
+      self.normalized_field_sets = { all: {} }.with_indifferent_access
+
+      #aggregate all compiled field_sets into the all collection
+      normalized_field_sets[:all][:fields] = field_sets.inject({}) do |result, (field_set_alias, field_set)|
+        result = merge_field_sets(result, dealias_field_set!(field_set, field_set_alias)[:fields])
+      end
+
+      #filter all compiled field_sets into a corresponding attributes collection
+      normalized_field_sets.each do |field_set_alias, normalized_field_set|
+        normalized_field_set[:attributes] = normalized_field_set[:fields].reject { |field_set, nested_field_sets|
+          serializer.send :is_association?, field_set
+        }
+      end
+
+      self.compiled = true
+      self
+    end
+
+    # Merges all ancestor accessors into self
+    # @return [Config]
+    def merge!(config)
+      self.compiled = false
+      self.resource_class ||= config.resource_class
+      transforms_from.merge!  config.transforms_from
+      transforms_to.merge!    config.transforms_to
+      serializers.merge!      config.serializers
+      namespaces.merge!       config.namespaces
+      field_sets.merge!       config.field_sets
+      extensions.merge!       config.extensions
+
+      self
+    end
+
+    # Invokes block on a Field Set with recursive, depth first traversal
+    # @param field_set [Field Set] to traverse
+    # @param block [Block] to call for each field
+    # @return [Hash] injection of block results
+    def field_set_itterator(field_set)
+      raise ActiveFacet::Errors::ConfigurationError.new(ActiveFacet::Errors::ConfigurationError::COMPILED_ERROR_MSG) unless compiled
+      internal_field_set_itterator(dealias_field_set!(default_field_set(field_set))[:fields], Proc.new)
+    end
+
+    protected
+
+    attr_accessor :field_sets
+
+    attr_writer :compiled, :serializer, :normalized_field_sets, :transforms_from, :transforms_to,
+      :serializers, :namespaces, :extensions
+
+    private
+
+    #TODO --jdc change Serializer::Base to convert all Strings to Symbols and remove indifferent_access
+    def initialize
+      self.compiled = false
+      self.transforms_from  = {}.with_indifferent_access
+      self.transforms_to    = {}.with_indifferent_access
+      self.serializers      = {}.with_indifferent_access
+      self.namespaces       = {}.with_indifferent_access
+      self.field_sets       = {}.with_indifferent_access
+      self.extensions       = {}.with_indifferent_access
+    end
+
+    # (Memoized) Convert all Field Set Aliases to their declarations and Normalize Field Set
+    # @param field_set [Symbol] to evaluate
+    # @param field_set_alias [String] key to associate the evaluated field set with
+    # @return [Normalized Field Set]
+    def dealias_field_set!(field_set, field_set_alias = nil)
+      field_set_alias ||= field_set.to_s.to_sym
+      normalized_field_sets[field_set_alias] ||= begin
+        { fields: normalize_field_set(dealias_field_set field_set) }
+      end
+    end
+
+    # Converts all Field Set Aliases in a Field Set into their declarations (see Serializer::Base DSL)
+    # Recursively evaluates all aliases embedded within declaration
+    # - Does not recursively evalute associations
+    # @param field_set [Symbol] to evaluate
+    # @return [Mixed]
+    def dealias_field_set(field_set)
+      case field_set
+      when :all
+        dealias_field_set serializer.exposed_aliases(:all, true, true)
+      when :all_attributes
+        dealias_field_set serializer.exposed_aliases
+      when Symbol, String
+        field_set = field_set.to_sym
+        aliased_field_set?(field_set) ? dealias_field_set(field_sets[field_set]) : field_set
+      when Array
+        field_set.map do |s|
+          dealias_field_set(s)
+        end
+      when Hash
+        field_set.inject({}) { |result, (k,v)|
+          v.blank? ? inject_field_set(result, dealias_field_set(k)) : result[k] = v #todo: symbolize
+          result
+        }
+      end
+    end
+
+    # Converts Field Set into a Normalized Field Set that can be idempotently itterated
+    # @param field_set [Symbol] to normalize
+    # @return [Normalized Field Set]
+    def normalize_field_set(field_set)
+      case field_set
+      when nil
+        {}
+      when Symbol, String
+        {field_set.to_sym => nil}
+      when Array
+        field_set.flatten.compact.inject({}) do |result, s|
+          result = merge_field_sets(result, s)
+        end
+      when Hash
+        field_set.inject({}) { |result, (k,v)| result[k.to_sym] = v; result }
+      end
+    end
+
+    # Adds :basic to a Field Set unless minimal is specified
+    # @param field_set [Field Set] field set to be serialized
+    # @return [Field Set]
+    def default_field_set(field_set)
+      minimal = detect_field_set(field_set, :minimal)
+      case field_set
+      when nil
+        :basic
+      when Symbol, String
+        minimal ? field_set.to_sym : [field_set.to_sym, :basic]
+      when Array
+        minimal ? field_set : field_set + [:basic]
+      when Hash
+        field_set[:basic] = nil unless minimal
+        field_set
+      else
+        raise ActiveFacet::Errors::ConfigurationError.new(ActiveFacet::Errors::ConfigurationError::FIELD_SET_ERROR_MSG)
+      end
+    end
+
+    # Iterrates the first level of Field Set checking for key
+    # @param field_set [Field Set]
+    # @return [Boolean]
+    def detect_field_set(field_set, key)
+      case field_set
+      when nil
+        false
+      when Symbol
+        field_set == key
+      when String
+        field_set.to_sym == key
+      when Array
+        field_set.detect { |s| detect_field_set(s, key) }
+      when Hash
+        field_set.detect { |s, n| detect_field_set(s, key) }.try(:[], 0)
+      else
+        raise ActiveFacet::Errors::ConfigurationError.new(ActiveFacet::Errors::ConfigurationError::FIELD_SET_ERROR_MSG)
+      end
+    end
+
+    # Invokes block on Fields in a Field Set with recursive, depth first traversal
+    # Skips fields already processed
+    # @param field_set [Field Set] to traverse
+    # @param block [Block] to call for each field_set
+    # @return [Hash] injection of block results
+    def internal_field_set_itterator(field_set, block)
+      field_set.each do |field, nested_field_set|
+        block.call(field, nested_field_set)
+      end
+    end
+
+    # Adds a Field into a Normalized Field Set
+    # @param field_set [Normalized Field Set]
+    # @param key [Field Set]
+    # @return [Hash]
+    def inject_field_set(field_set, key)
+      case key
+      when Symbol, String
+        field_set[key.to_sym] = {}
+      when Hash
+        field_set.merge! key
+      when Array
+        key.each { |k| inject_field_set(field_set, k) }
+      end
+    end
+
+    # Tells if the Field is a Field Set Alias
+    # @param field_set [Symbol] to evaluate
+    # @return [Boolean]
+    def aliased_field_set?(field_set)
+      return false unless field_sets.key? field_set
+      v = field_sets[field_set]
+      !v.is_a?(Symbol) || v != field_set
+    end
+
+    # Recursively merges two Field Sets
+    # @param a [Symbol] to merge
+    # @param b [Symbol] to merge
+    # @return [Field Set]
+    def merge_field_sets(a, b)
+      na = normalize_field_set(a)
+      nb = normalize_field_set(b)
+      nb.inject(na.dup) do |result, (field_set, nested_field_sets)|
+        result[field_set] = merge_field_sets(na[field_set], nested_field_sets)
+        result
+      end
+    end
+
+  end
+end

data/lib/active_facet/document_cache.rb

@@ -0,0 +1,52 @@
+# A really dump cache interface that caches everything when enabled.
+# Extend and conditionally cache documents.
+module ActiveFacet
+  class DocumentCache
+    CACHE_PREFIX = 'af_doc_cache'
+
+    # Fetches a JSON document representing the facade
+    # @param facade [Object] to cache
+    # @param options [Hash] for Rails.cache.fetch
+    # @param &block [Proc] for cache miss
+    # @return [Object]
+    def self.fetch(facade, options = {})
+      return yield unless cacheable?(facade)
+
+      force = facade.opts[ActiveFacet.cache_force_key] || options[:force] || ActiveFacet::default_cache_options[:force]
+      cache_key = digest_key(facade)
+      if force || !(result = Rails.cache.fetch(cache_key))
+        result = yield
+        Rails.cache.write(cache_key, ::Oj.dump(result), ActiveFacet::default_cache_options.merge(options).merge(force: force))
+        result
+      else
+        ::Oj.load(result)
+      end
+    end
+
+    # Fetches a JSON document representing the association specified for the resource in the facade
+    # @param facade [Object] to cache
+    # @param options [Hash] for Rails.cache.fetch
+    # @param &block [Proc] for cache miss
+    # @return [Object]
+    def self.fetch_association(facade, association, options = {})
+      # override and implement
+      yield
+    end
+
+    private
+
+    # Salts and hashes facade cache_key
+    # @param facade [Facade] to generate key for
+    # @return [String]
+    def self.digest_key(facade)
+      Digest::MD5.hexdigest(CACHE_PREFIX + facade.cache_key.to_s)
+    end
+
+    # Tells if the resource to be serialized can be cached
+    # @param facade [Facade] to inspect
+    # @return [Boolean]
+    def self.cacheable?(facade)
+      ActiveFacet.cache_enabled && facade.opts[ActiveFacet.cache_bypass_key].blank?
+    end
+  end
+end

data/lib/active_facet/errors/attribute_error.rb

@@ -0,0 +1,6 @@
+module ActiveFacet
+  module Errors
+    class AttributeError < StandardError
+    end
+  end
+end

data/lib/active_facet/errors/configuration_error.rb

@@ -0,0 +1,16 @@
+module ActiveFacet
+  module Errors
+    class ConfigurationError < StandardError
+
+      RESOURCE_ERROR_MSG            = 'unable to identify resource class'
+      STACK_ERROR_MSG               = "self referencing attribute declaration"
+      ALL_ATTRIBUTES_ERROR_MSG      = "publish name (:all_attributes) reserved"
+      ALL_FIELDS_ERROR_MSG          = "publish name (:all) reserved"
+      COMPILED_ERROR_MSG            = "field set configuration not compiled"
+      FIELD_SET_ERROR_MSG           = "invalid field set"
+      ACTS_AS_ERROR_MSG             = "filters can only be defined on acts_as_active_facet resources"
+      DUPLICATE_ACTS_AS_ERROR_MSG   = "acts_as_active_facet_options already exists"
+
+    end
+  end
+end

data/lib/active_facet/errors/lookup_error.rb

@@ -0,0 +1,6 @@
+module ActiveFacet
+  module Errors
+    class LookupError < StandardError
+    end
+  end
+end

data/lib/active_facet/filter.rb

@@ -0,0 +1,62 @@
+# Maps filters to resource classes without adding methods to the resource classes directly
+module ActiveFacet
+  class Filter
+
+    # filters holds the resource/filter map for each resource
+    # registered_filters holds the resource/filter map for each resource and all superclasses
+    # global_filters queues a collection of filters that can be defined
+    #   on any resource classes having called included and called acts_as_active_facet_options
+    cattr_accessor :filters, :registered_filters, :global_filters
+    self.filters, self.registered_filters, self.global_filters = {}, {}, {}
+
+    # Queues a filter to be applied to resource classes
+    # @param filter_name [Symbol]
+    # @param filter_method [Proc] method body code which implements the filter
+    # @return [Proc] for chaining
+    def self.register_global(filter_name, filter_method)
+      global_filters[filter_name.to_sym] = filter_method
+    end
+
+    # Tells that the receiver class implements a filter
+    # @param receiver [Class] resource class
+    # @param filter_name [Symbol]
+    # @param filter_method_name [Symbol] name of method defined on receiver instances which implments the filter
+    # @return [Class] for chaining
+    def self.register(receiver, filter_name, filter_method_name)
+      raise ActiveFacet::Errors::ConfigurationError.new(ActiveFacet::Errors::ConfigurationError::ACTS_AS_ERROR_MSG) unless filterable?(receiver)
+      receiver_filters = filters[receiver.name] ||= {}
+      receiver_filters[filter_name.to_sym] = filter_method_name.to_sym
+      receiver
+    end
+
+    # Register queued filters for given resource class
+    # @param receiver [Class] resource class
+    # @return [Class] for chaining
+    def self.apply_globals_to(receiver)
+      raise ActiveFacet::Errors::ConfigurationError.new(ActiveFacet::Errors::ConfigurationError::ACTS_AS_ERROR_MSG) unless filterable?(receiver)
+      global_filters.each do |filter_name, filter_method|
+        filter_method_name = receiver.acts_as_active_facet_options[:filter_method_name]
+        receiver.send(filter_method_name, filter_name, filter_method)
+      end
+      receiver
+    end
+
+    # Returns the list of filters the resource class implements
+    # Memoized
+    # @param receiver [Class] resource class
+    # @return [Hash] all filters registered on this resource (and superclass)
+    def self.registered_filters_for(receiver)
+      registered_filters[receiver.name] ||= begin
+        receiver_filters = filters[receiver.name] ||= {}
+        receiver_filters.reverse_merge!(registered_filters_for(receiver.superclass)) if filterable?(receiver.superclass)
+        receiver_filters
+      end
+    end
+
+    # Tells if any filters can be registered for the given resource class
+    # @return [Boolean]
+    def self.filterable?(receiver)
+      receiver.ancestors.include? ActiveFacet::ActsAsActiveFacet
+    end
+  end
+end

data/lib/active_facet/helper.rb

@@ -0,0 +1,116 @@
+# Implements varius methods that bind serializers and resources together
+module ActiveFacet
+  class Helper
+    # Memoizes resource_mapper results
+    cattr_accessor :memoized_resource_map
+    self.memoized_resource_map = {}
+
+    # Memoizes serializer_mapper results
+    cattr_accessor :memoized_serializers
+    self.memoized_serializers = {}
+
+    # Default resource mapping scheme, can be replaced with a custom implementation
+    # @param resource_class [Class]
+    # @return [Array] of Strings for use by filters and field configurations
+    def self.default_resource_mapper(resource_class)
+      map = []
+      until(resource_class.superclass == BasicObject) do
+        map << resource_class.name.tableize
+        resource_class = resource_class.superclass
+      end
+      map
+    end
+
+    # Holds reference to resource_mapper method (configurable)
+    cattr_accessor :resource_mapper
+    self.resource_mapper = method(:default_resource_mapper)
+
+    # Fetches the set of keys the resource_class might appear as for Filters and Fields
+    # Memoized
+    # @param resource_class [Object]
+    # @return [Array] of Strings
+    def self.resource_map(resource_class)
+      memoized_resource_map[resource_class] ||= begin
+        resource_mapper.call(resource_class)
+      end
+    end
+
+    # Default serializer mapping scheme, can be overrided with config
+    # Memoized
+    # @param resource_class [Class]
+    # @return [Serializer::Base | Class]
+    def self.default_serializer_mapper(resource_class, serializer, type, version, options)
+      key = [resource_class.name, serializer.to_s, type.to_s.camelcase, version].join(".")
+      return memoized_serializers[key] if memoized_serializers.key?(key)
+      memoized_serializers[key] = internal_serializer_mapper(resource_class, serializer, type, version, options)
+    end
+
+    # Holds reference to serializer_mapper method (configurable)
+    cattr_accessor :serializer_mapper
+    self.serializer_mapper = method(:default_serializer_mapper)
+
+    # TODO --jdc implement recursive superclass/parentclass lookup
+    # Default serializer mapping scheme, can be overrided with config
+    # @param resource_class [Class]
+    # @return [Serializer::Base | Class]
+    def self.internal_serializer_mapper(resource_class, serializer, type, version, options)
+      case type
+      when :serializer
+        [
+          'V' + version.to_i.to_s + '::' + resource_class.name.camelcase + '::' + resource_class.name.camelcase + type.to_s.camelcase,
+          'V' + version.to_i.to_s + '::' + resource_class.name.camelcase + type.to_s.camelcase,
+        ].each { |name|
+          klass = name.safe_constantize
+          return klass.new if klass.present?
+        }
+      else
+        [
+          'V' + version.to_i.to_s + '::' + resource_class.name.camelcase + '::' + serializer + type.to_s.camelcase,
+          'V' + version.to_i.to_s + '::' + serializer + type.to_s.camelcase,
+        ].find { |name|
+          klass = name.safe_constantize
+          return klass if klass.present?
+        }
+      end
+    end
+
+    # Fetches the serializer registered for a resource_class
+    # @param resource_class [Object] to find serializer for
+    # @param options [Hash] context
+    # @return [Serializer::Base]
+    def self.serializer_for(resource_class, options)
+      fetch_serializer(resource_class, resource_class.name.demodulize.to_s.camelcase, :serializer, options)
+    end
+
+    # Fetches the attribute serializer registered for the given resource_class
+    # @param resource_class [Object] to find attribute serializer class for
+    # @param attribute_class_name [String] to find attribute serializer class for
+    # @param options [Hash] context
+    # @return [Class]
+    def self.attribute_serializer_class_for(resource_class, attribute_name, options)
+      fetch_serializer(resource_class, attribute_name.to_s.camelcase, :attribute_serializer, options)
+    end
+
+    # Retrieves the first serializer successfully described by the parameters
+    # @param resource_class [Class] the class of the resource to serialize
+    # @param serializer [String] name of the base_class of the resource to serialize
+    # @param type [String] type of serializer to look for (attribute vs. resource)
+    # @param options [Hash] context
+    # @return [Serializer::Base | Class]
+    def self.fetch_serializer(resource_class, serializer, type, options)
+      version = extract_version_from_opts(options)
+      unless result = serializer_mapper.call(resource_class, serializer, type, version, options)
+        error_message = "Unable to locate serializer for:: " + [resource_class.name, serializer, type, version].to_s
+        Rails.logger.debug error_message
+        raise ActiveFacet::Errors::LookupError.new(error_message) if ActiveFacet.strict_lookups
+      end
+      result
+    end
+
+    # Safely extracts version from options hash
+    # @return [Numeric]
+    def self.extract_version_from_opts(options)
+      ((options.try(:[], ActiveFacet.opts_key) || {})[ActiveFacet.version_key] || ActiveFacet.default_version).to_f
+    end
+  end
+end