active_facets 1.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 63e1ea8c7c86286554a205c84e6ddc7224be9b00
+  data.tar.gz: dbc2ed04992db135f887f8bc56bc21ec0fe30f37
+SHA512:
+  metadata.gz: 773bafd97bc95b401a0b12dbc6a0edd5ac82f18f769e7dc2715725cc226fd6ca0888ed6ba7198b5532fcdb6d32df2bc68cd4f91901307660844dd4999ebda1b1
+  data.tar.gz: 99d24b3b9c658b458329ee385147f7aded91b1593ace925b5d1f50d35db62a69da21dc175a363bd2dbdefd84dfa0f766f07149de996b4dc2063163ca4ed9b9cf

data/MIT-LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Jay Crouch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,206 @@
+# ActiveFacets
+
+ActiveFacets is a Rails plugin that enables custom as_json serialization intended for APIs. It is designed for speed, and is magnitudes of order faster than jbuilder.
+
+The framework supports:
+* fields - define the fields you want to serialize, by resource type
+* field groups - configure sets of fields you want to refer to by alias, by resource type
+* versioning - describe serialization of resources by version, with automatic fallback
+* caching - optomize performance by composing documents from smaller documents
+* nested resources - serialize models and associations with one call chain
+* filters - restrict records from associations with custom scopes
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_facets'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install active_facets
+
+## Configuration
+
+And then execute:
+
+    $ rails g active_facets:install
+
+To add an initializer to your application.
+
+## Usage
+
+```ruby
+Parent.limit(2).as_json(af_opts: {
+  version: "2.3.8",
+  cache_force: true,
+  fields: [:basic, :extended, { children: [:minimal, :extension] }]
+  field_overrides: {
+    parent: [:id, :children, :foo, :bar],
+    child: [:fizz, :buzz]
+  },
+  filters: {
+    single_parent: true,
+    with_children_parent: 3,
+    active: :disabled
+  }
+})
+# =>
+[ {
+    id: 1,
+    created_at: 2343242342,
+    updated_at: "2014-03-23 00:23:32",
+    weight: 2432252,
+    children: [ {
+      fizz: 'care bear'
+    }, {
+      fizz: 'hello',
+      buzz: 'world'
+    } ]
+  }, {
+    id: 2,
+    created_at: 2343242777,
+    updated_at: "2014-04-24 01:34:25",
+    children: [ {
+      fizz: 'tamato'
+    } ]
+  }
+}
+```
+
+### Defaults
+
+All options are optional
+
+#### :version
+Version of serializer to marshal resources with. Defaults to:
+```ruby
+"1.0"
+```
+
+#### :cache_force
+Force serializers to ignore cached documents. Defaults to:
+```ruby
+false
+```
+
+#### :fields
+Attributes to marshal. See Field Sets. Defaults to:
+```ruby
+:basic
+```
+
+#### :field_overrides
+Attributes to marshal, by resource type. See Field Sets. Defaults to:
+```ruby
+{}
+```
+
+#### :filters
+Filters to apply when marshalling associations. See Field Sets. Defaults to:
+```ruby
+{}
+```
+
+### Serializer DSL
+
+```ruby
+class ParentSerializer
+  include ActiveFacets::Serializer::Base
+
+  # TRANSFORMS
+
+  # Transforms rename attributes and apply custom serializers to attributes data.
+
+  # Renames parent.kid_trackings to json['trackings'] on parent.as_json...
+  transform :trackings,               from: :kid_trackings
+
+  # Renames json['trackings'] to parent.kid_trackings on parent.from_hash...:
+  transform :trackings,               to: :kid_trackings
+
+  # Renames parent.kid_trackings to json['trackings'] on parent.as_json... & parent.from_hash...
+  transform :trackings,               as: :kid_trackings
+
+  # Converts json['created_at'] with TimeCustomAttributeSerializer on parent.as_json... & parent.from_hash...
+  transform :created_at,              with: :time
+
+  # Renames json['created_at'] to parent.data['weight'] on parent.as_json... & parent.from_hash...
+  transform :weight,                  within: :data
+
+  # Renames json['weighed'] to parent.data['weighed_at'] using TimeCustomAttributeSerializer converter on parent.as_json... & parent.from_hash...
+  transform :weighed,                 within: :data, with: :time, as: :wieghed_at
+
+
+
+  # EXTENSIONS
+
+  # Extensions decorate the json response when attribute data is not directly accessible from the resource.
+
+  # Decorates json['free_shipping_minimum'] on parent.as_json...
+  extension :free_shipping_minimum
+
+
+
+  # FIELD SETS
+
+  # Field sets indicate the desired fields to serialize for a given resource type.
+  # Field sets can be aliased, and reference aliases, recursively.
+  # Field sets can reference Field Sets defined for ActiveRecord Association resource types in a hierarchical structure
+
+  # NOTE:: make sure to define :basic and :minimal Field Sets for all resources
+  # :basic is implicitely added to all Field Sets that do not inclue :minimal during serialization
+
+  # Arrays map to collections
+  expose :timestamps,                 as: [:id, :created_at, :updated_at]
+  expose :basic,                      as: [:timestamps, :name]
+
+  # Hashes map to relations and the Field Sets declared on the relation
+  expose :deep,                       as: { trackings: :basic }
+
+  # Composite structures can be formed from Symbols, Arrays, and Hashes
+  expose :deep_basic,                 as: [:timestamps, :basic, { trackings: [:basic, :extended] }]
+
+
+
+  # EXPOSE_TIMESTAMPS
+
+  # expose_timestamps is equivalent to
+  # transform :created_at, with: :time
+  # transform :updated_at, with: :time
+  # expose :timestamps, as: [:id, :created_at, :updated_at]
+  expose_timestamps
+
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. To work with an interactive prompt including a dummy host application, run `bin/rails c` or `rails c` from the spec/dummy directory.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+To push or update an unreleased version, without pushing the `.gem` file, run `bin/update_version`.
+
+To configure a host application to use a local version of the gem without modifying the host application's Gemfile run from the root directory of the host application `bundle config local.active_facets /path/to/local/git/repository`
+
+To unconfigure a local version of the gem, run `bundle config --delete local.active_facets`
+
+## Roadmap
+Available at https://github.com/honest/active_facets/blob/master/ROADMAP.md
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/honest/active_facets. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,29 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ActiveFacets'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+
+

data/lib/active_facets.rb

@@ -0,0 +1,93 @@
+require 'w_g'
+require 'active_support/all'
+require 'active_record'
+
+require 'active_facets/errors/attribute_error'
+require 'active_facets/errors/configuration_error'
+require 'active_facets/errors/lookup_error'
+require 'active_facets/acts_as_active_facet'
+require 'active_facets/serializer/base'
+require 'active_facets/serializer/facade'
+require 'active_facets/config'
+require 'active_facets/document_cache'
+require 'active_facets/resource_manager'
+require 'active_facets/version'
+
+module ActiveFacets
+  mattr_accessor :opts_key,
+    :fields_key,
+    :field_overrides_key,
+    :version_key,
+    :filters_key,
+    :cache_force_key,
+    :filters_force_key,
+    :strict_lookups,
+    :preload_associations,
+    :cache_enabled,
+    :acts_as_active_facet_enabled,
+    :filters_enabled,
+    :default_cache_options,
+    :document_cache,
+    :default_version
+
+  self.default_version                = 1.0
+  self.opts_key                       = :af_opts
+  self.fields_key                     = :fields
+  self.field_overrides_key            = :field_overrides
+  self.version_key                    = :version
+  self.filters_key                    = :filters
+  self.cache_force_key                = :cache_force
+  self.filters_force_key              = :filters_force
+
+  self.strict_lookups                 = false
+  self.preload_associations           = false
+  self.filters_enabled                = false
+  self.cache_enabled                  = false
+  self.acts_as_active_facet_enabled   = false
+  self.default_cache_options          = { expires_in: 5.minutes }
+  self.document_cache                 = ActiveFacets::DocumentCache
+
+  def self.configure
+    yield(self)
+    ActiveRecord::Base.acts_as_active_facet if ActiveFacets.acts_as_active_facet_enabled
+  end
+
+  def self.global_filter(name)
+    ActiveFacets::ActsAsActiveFacet::Filters.global_filters[name] = Proc.new
+  end
+
+  def self.resource_mapper
+    ActiveFacets::ResourceManager.resource_mapper = Proc.new
+  end
+
+  def self.serializer_mapper
+    ActiveFacets::ResourceManager.serializer_mapper = Proc.new
+  end
+
+  def self.fields_from_options(options)
+    (options[ActiveFacets.opts_key] || {})[ActiveFacets.fields_key]
+  end
+
+  def self.options_with_fields(options, fields)
+    (options[ActiveFacets.opts_key] ||= {})[ActiveFacets.fields_key] = fields
+    options
+  end
+
+  def self.restore_opts_after(options, key, value)
+    opts = (options[ActiveFacets.opts_key] ||= {})
+    old = opts[key]
+    opts[key] = value
+    yield
+  ensure
+    opts[key] = old
+  end
+
+  def self.deep_copy(o)
+    Marshal.load(Marshal.dump(o))
+  end
+end
+
+ActiveRecord::Base.send :include, ActiveFacets::ActsAsActiveFacet
+
+
+

data/lib/active_facets/acts_as_active_facet.rb

@@ -0,0 +1,131 @@
+#NOTE:: strive for minimal method footprint because this mixes into ActiveRecord
+
+# TODO --jdc, change serializer scoped_includes, as_json & from_hash to be generic and add voerrides in initializer for www
+#  when serializing, access cattr to determine method name to invoke
+# add tests for the this module
+
+module ActiveFacets
+  module ActsAsActiveFacet
+    extend ActiveSupport::Concern
+    included do
+    end
+
+    module Filters
+      mattr_accessor :filters, :global_filters
+      self.filters, self.global_filters = {}, {}
+
+      def self.apply_globals_to(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
+      end
+
+      # @return [Hash] all filters registered on this resource (and superclass)
+      def self.registered_filters_for(receiver)
+        receiver_filters = filters[receiver.name] ||= {}
+        receiver_filters.reverse_merge(registered_filters_for(receiver.superclass)) if has_registered_filters_for?(receiver.superclass)
+        receiver_filters
+      end
+
+      def self.register_filter_for(receiver, filter_name, filter_method_name)
+        receiver_filters = filters[receiver.name] ||= {}
+        receiver_filters[filter_name.to_sym] = filter_method_name.to_sym
+        receiver_filters
+      end
+
+      def self.has_registered_filters_for?(receiver)
+        filters.key?(receiver.name)
+      end
+
+    end
+
+    module ClassMethods
+      def acts_as_active_facet(options = {})
+
+        # save to a local variable so its in scope during instance_eval below
+        acts_as_active_facet_options = options.deep_dup
+        acts_as_active_facet_options[:includes_method_name]          ||= :facet_includes
+        acts_as_active_facet_options[:apply_includes_method_name]    ||= :apply_facet_includes
+        acts_as_active_facet_options[:filter_method_name]            ||= :facet_filter
+        acts_as_active_facet_options[:apply_filters_method_name]     ||= :apply_facet_filters
+        acts_as_active_facet_options[:unserialize_method_name]       ||= :from_json
+        acts_as_active_facet_options[:serialize_method_name]         ||= :as_json
+
+        cattr_accessor :acts_as_active_facet_options
+        self.acts_as_active_facet_options = acts_as_active_facet_options
+
+        (class << self; self; end).instance_eval do
+
+          # Invokes ProxyCollection.includes with a safe translation of field_set
+          # @param facets [Object]
+          # @param options [Hash]
+          # @return [ProxyCollection]
+          define_method(acts_as_active_facet_options[:includes_method_name]) do |facets = :basic, options = {}|
+            ActiveFacets::ResourceManager.instance.serializer_for(self, options).scoped_includes(facets)
+          end
+
+          # Invokes ProxyCollection.includes with a safe translation of field_set
+          # @param field_set [Object]
+          # @param options [Hash]
+          # @return [ProxyCollection]
+          define_method(acts_as_active_facet_options[:apply_includes_method_name]) do |facets = :basic, options = {}|
+            includes(self.send(includes_method_name, facets, options))
+          end
+
+          # Registers a scope filter on this resource and subclasses
+          # @param filter_name [Symbol] filter name
+          # @param filter_method_name [Symbol] scope name
+          define_method(acts_as_active_facet_options[:filter_method_name]) do |filter_name, filter_method_name = nil, &filter_method|
+            filter_method_name ||= "registered_filter_#{filter_name}"
+            define_singleton_method(filter_method_name, filter_method) if filter_method
+
+            ActiveFacets::ActsAsActiveFacet::Filters.register_filter_for(self, filter_name, filter_method_name)
+          end
+
+          # Applies all filters registered with this resource on a ProxyCollection
+          # @param filter_values [Hash] keys = registerd filter name, values = filter arguments
+          define_method(acts_as_active_facet_options[:apply_filters_method_name]) do |filter_values = nil|
+            filter_values = (filter_values || {}).with_indifferent_access
+            ActiveFacets::ActsAsActiveFacet::Filters.registered_filters_for(self).inject(self) do |result, (k,v)|
+              filter = ActiveFacets::ResourceManager.instance.resource_map(self).detect { |map_entry|
+                filter_values.keys.include? "#{k}_#{map_entry}"
+              }
+              args = filter_values["#{k}_#{filter}"] || filter_values[k]
+              result.send(v, *args) || result
+            end
+          end
+
+          # Builds a new resource instance and unserializes it
+          # @param attributes [Hash]
+          # @param options [Hash]
+          # @return [Resource]
+          define_method(acts_as_active_facet_options[:unserialize_method_name]) do |attributes, options = {}|
+            self.new.send(acts_as_active_facet_options[:unserialize_method_name], attributes, options)
+          end
+        end
+
+        # Unserializes a resource
+        # @param attributes [Hash]
+        # @param options [Hash]
+        # @return [Resource]
+        define_method(acts_as_active_facet_options[:unserialize_method_name]) do |attributes, options = {}|
+          ActiveFacets::ResourceManager.instance.serializer_for(self.class, options).from_hash(self, attributes)
+        end
+
+        # Serializes a resource using facets
+        # Falls back to default behavior when RCB key is not present
+        # @param options [Hash]
+        # @return [Hash]
+        define_method(acts_as_active_facet_options[:serialize_method_name]) do |options = nil|
+          if options.present? && options.key?(ActiveFacets.opts_key) &&
+              (serializer = ActiveFacets::ResourceManager.instance.serializer_for(self.class, options)).present?
+            serializer.as_json(self, options)
+          else
+            super(options)
+          end
+        end
+      end
+    end
+  end
+end