active_facet 1.2.8

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 12d1962bd14e00c927ee8d18634327e75add2241
+  data.tar.gz: bac02648674193b937c1c022e6527a9db1dccc24
+SHA512:
+  metadata.gz: 47843cbae2eed28b0f3bbae3407e8ccf1d543432139022387be4e780148bdbb607b594e6761f955cd6597e147b5289fc774ecf16406e35b7f7cc2744dc546e11
+  data.tar.gz: 3cc78a3c627e8e82c17f6d61dbab3f8067baf47e98ae384842bebb249afb8dc9817f63927374a31a00cbfb2b2e06647f49a12939dad92c6cba33386e6483be8c

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 @@
+# ActiveFacet
+
+ActiveFacet 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_facet'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install active_facet
+
+## Configuration
+
+And then execute:
+
+    $ rails g active_facet: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 ActiveFacet::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_facet /path/to/local/git/repository`
+
+To unconfigure a local version of the gem, run `bundle config --delete local.active_facet`
+
+## Roadmap
+Available at https://github.com/honest/active_facet/blob/master/ROADMAP.md
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/honest/active_facet. 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    = 'ActiveFacet'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+
+

data/lib/active_facet.rb

@@ -0,0 +1,98 @@
+require 'w_g'
+require 'active_support/all'
+require 'active_record'
+
+require 'active_facet/errors/attribute_error'
+require 'active_facet/errors/configuration_error'
+require 'active_facet/errors/lookup_error'
+require 'active_facet/filter'
+require 'active_facet/acts_as_active_facet'
+require 'active_facet/serializer/base'
+require 'active_facet/serializer/facade'
+require 'active_facet/config'
+require 'active_facet/document_cache'
+require 'active_facet/helper'
+require 'active_facet/version'
+
+module ActiveFacet
+  mattr_accessor :opts_key,
+    :fields_key,
+    :field_overrides_key,
+    :version_key,
+    :filters_key,
+    :cache_bypass_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_bypass_key               = :cache_bypass
+  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                 = ActiveFacet::DocumentCache
+  #TODO --jdc implement dependency injection for all classes
+
+  def self.configure
+    yield(self)
+    ActiveRecord::Base.acts_as_active_facet if ActiveFacet.acts_as_active_facet_enabled
+  end
+
+  def self.global_filter(name)
+    ActiveFacet::Filter.register_global(name, Proc.new)
+  end
+
+  def self.resource_mapper
+    ActiveFacet::Helper.resource_mapper = Proc.new
+  end
+
+  def self.serializer_mapper
+    ActiveFacet::Helper.serializer_mapper = Proc.new
+  end
+
+  def self.fields_from_options(options)
+    (options[ActiveFacet.opts_key] || {})[ActiveFacet.fields_key]
+  end
+
+  def self.options_with_fields(options, fields)
+    (options[ActiveFacet.opts_key] ||= {})[ActiveFacet.fields_key] = fields
+    options
+  end
+
+  #TODO --jdc move the below into helper
+  def self.restore_opts_after(options, key, value)
+    opts = (options[ActiveFacet.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, ActiveFacet::ActsAsActiveFacet
+
+
+

data/lib/active_facet/acts_as_active_facet.rb

@@ -0,0 +1,102 @@
+#NOTE:: strive for minimal method footprint because this mixes into ActiveRecord
+
+# Adds interface methods to resource classes
+module ActiveFacet
+  module ActsAsActiveFacet
+    extend ActiveSupport::Concern
+    included do
+    end
+
+    module ClassMethods
+      def acts_as_active_facet(options = {})
+        raise ActiveFacet::Errors::ConfigurationError.new(ActiveFacet::Errors::ConfigurationError::DUPLICATE_ACTS_AS_ERROR_MSG) if respond_to?(:acts_as_active_facet_options)
+        cattr_accessor :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
+
+        self.acts_as_active_facet_options = acts_as_active_facet_options
+
+        (class << self; self; end).instance_eval do
+
+          # Translates a Field Set into a deeply nested hash of included associations suitable for use by includes
+          # @param facets [Object]
+          # @param options [Hash]
+          # @return [Hash]
+          define_method(acts_as_active_facet_options[:includes_method_name]) do |facets = :basic, options = {}|
+            ActiveFacet::Helper.serializer_for(self, options).scoped_includes(facets)
+          end
+
+          # Invokes includes with all deeply nested associations found in the given 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(acts_as_active_facet_options[:includes_method_name], facets, options))
+          end
+
+          # Registers a Filter for this resource
+          # @param filter_name [Symbol]
+          # @param filter_method_name [Symbol]
+          # @return [Class] for chaining
+          define_method(acts_as_active_facet_options[:filter_method_name]) do |filter_name, filter_method_name = nil, &filter_method|
+            filter_method, filter_method_name = filter_method_name, nil if filter_method_name.is_a?(Proc)
+            filter_method_name ||= "registered_filter_#{filter_name}"
+            define_singleton_method(filter_method_name, filter_method) if filter_method
+            ActiveFacet::Filter.register(self, filter_name, filter_method_name)
+          end
+
+          # Applies all filters registered for this resource
+          # Arguments for filters are looked up by resource type, then without namespace
+          # @param filter_values [Hash] keys = registerd filter name, values = filter arguments
+          # @return [ProxyCollection]
+          define_method(acts_as_active_facet_options[:apply_filters_method_name]) do |filter_values = nil|
+            filter_values = (filter_values || {}).with_indifferent_access
+            ActiveFacet::Filter.registered_filters_for(self).inject(scoped) do |scope, (filter_name, filter_method_name)|
+              filter_resource_name = ActiveFacet::Helper.resource_map(self).detect { |filter_resource_name|
+                filter_values.keys.include? "#{filter_name}_#{filter_resource_name}"
+              }
+              args = filter_values["#{filter_name}_#{filter_resource_name}"] || filter_values[filter_name]
+              scope.send(filter_method_name, *args) || scope
+            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 = {}|
+          ActiveFacet::Helper.serializer_for(self.class, options).from_hash(self, attributes)
+        end
+
+        # Serializes a resource with given Facets
+        # Falls back to default behavior when 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?(ActiveFacet.opts_key) &&
+              (serializer = ActiveFacet::Helper.serializer_for(self.class, options)).present?
+            serializer.as_json(self, options)
+          else
+            super(options)
+          end
+        end
+      end
+    end
+  end
+end