tint 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1354ca3ff0a496a512ab36ec8513968d975a3e2f
+  data.tar.gz: a5dad281f2b83296fa3d7ea158e1821d63aaf66e
+SHA512:
+  metadata.gz: a048c65f0003c91bef770a00aaa9e145501ae8306832d30b1c9aa4dfad91f2c5e2193a4d4b3aa29e1e5dd7dfef503c2c242b16b02eb4d35cecf91bde4bc2aa55
+  data.tar.gz: cc74836e050c7657a236eb74f095368fb1c577eb3ab0843e26017f5a9c148c41c5b0e3fc5b89ae369bc221067674b131c3bbba50743977b2e75849e29db1f367

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+spec/tmp
+spec/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Aleck Greenham
+
+MIT License
+
+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,204 @@
+# Tint
+
+Easily define object decorators for JSON APIs using simple declarative syntax 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'tint'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tint
+
+## Usage
+
+You can use Tint by creating a decorator class that inherits from `Tint::Decorator`
+
+## Defining attributes
+
+To include methods and attributes available on the decorated object, simply list them using `attributes`. 
+
+```ruby
+# decorators/user_decorator.rb
+class UserDecorator < Tint::Decorator
+  attributes :username, :first_name, :last_name 
+end
+```
+
+You can map attributes to different names on the decorator by providing a hash as the final argument 
+ 
+```ruby
+# decorators/user_decorator.rb
+class UserDecorator < Tint::Decorator
+  attributes :username, :first_name, last_name: :surname # object.surname will be available as ['last_name']
+end
+```
+
+## Defining custom methods
+
+Tint will use a decorator instance method in preference to one defined on the decorated object, so it is possible to customise how a particular attribute appears. The original definition of the attribute is available via the `object` instance variable.
+
+```ruby
+class ProductDecorator < Tint::Decorator
+  attributes :id, :description, :price
+  
+  def price
+    "$" + object.price  
+  end
+end
+```
+
+It's also possible to define methods that are not available on the decorated object at all.
+
+```ruby
+class ProductDecorator < Tint::Decorator
+  attributes :id, :description, :on_sale
+  
+  def on_sale
+    SaleItems.include?(object)  
+  end
+end
+```
+
+## Defining associations
+
+The `decorates_association` method is used for declaring associations and delegating them to other decorators.
+
+```ruby
+# decorators/product_decorator.rb
+class ProductDecorator < Tint::Decorator
+  attributes :id, :description
+end
+
+# decorators/user_decorator.rb
+class UserDecorator < Tint::Decorator
+  attributes :username
+  
+  decorates_association :products
+end
+```
+
+By default, `decorates_association` uses the name of the association to guess the decorator it should use. In this case it will use `ProductDecorator`, but if you wished to render with `SpecialProductDecorator`, the `with` option may be used:
+ 
+```ruby
+decorates_association :product, with: SpecialProductDecorator
+```
+
+Multiple associations can be defined in the same statement using `decorates_associations`. Either, using interpolation to locate the correct decorator for each:
+
+```ruby
+decorates_associations :product, :address
+```
+
+Or using the same decorator (in this case, `AddressDecorator`):
+
+```ruby
+decorates_associations :previous_address, :current_address, with: AddressDecorator
+```
+
+## Eager loading associations
+
+When you declare a new association using `decorates_association` or `decorates_associations`, Tint automatically eager loads the associations when the decorator is rendered as JSON and automatically prevents many N+1 queries. It does this by maintaining a list `eager_loads` which is available on all decorators.
+ 
+```ruby
+class UserDecorator < Tint::Decorator
+  attributes :username
+  
+  decorates_association :products
+end
+ 
+ 
+UserDecorator.eager_loads # [:products]
+```
+
+If you need to manually add to the list of associations which are eager loaded for any reason, you can do so using the `eager_load` method
+ 
+```ruby
+class UserDecorator < Tint::Decorator
+  attributes :username
+  
+  decorates_association :products
+  
+  eager_load :addresses
+end
+
+UserDecorator.eager_loads # [:products, :addresses]
+```
+
+## Decorating a single instance
+
+Tint maintains the interface defined by Draper for decorating objects. To decorate a single object, use the `decorate` method. 
+
+Using the `UserDecorator` defined above:
+
+```ruby
+# controllers/users_controller.rb
+
+class UsersController < ApplicationController
+
+  def show
+    @user = User.find(params[:id]) #<User username: "john_doe", first_name: "John", surname: "Doe">
+     
+    render json: UserDecorator.decorate(@user) # { username: "john_doe", firstName: "John", lastName: "Doe" }
+  end
+  
+end
+```
+
+`decorate` also accepts an optional has of options. For more information about the supported options, see the [Draper documentation](https://github.com/drapergem/draper#adding-context).
+ 
+ 
+## Decorating a collection
+
+The `decorate_collection` method is used for decorating an instance of ActiveRecord::Relation (or any class that implements the same interface). It accepts all of the same options as the `decorate` method.
+
+```ruby
+# controllers/users_controller.rb
+
+class UsersController < ApplicationController
+
+  def index
+    @users = User.all
+     
+    render json: UserDecorator.decorate_collection(@users) # [ { username: "john_doe", firstName: "John", lastName: "Doe" }, ... ]
+  end
+  
+end
+```
+    
+## Configuration
+
+By default, Tint camelizes attribute names, however it's possible to configure Tint to use any of the following capitalization conventions:
+  
+```ruby
+Tint.configuration do |config|
+  # attribute_naMe123 ==> attributeNaMe123 (Default)
+  # config.attribute_capitalization = :camel_case
+
+  # attribute_naMe123 ==> attribute_na_me123
+  # config.attribute_capitalization = :snake_case
+
+  # attribute_naMe123 ==> attribute-naMe123
+  # config.attribute_capitalization = :kebab_case
+
+  # Converts symbols to strings
+  # config.attribute_capitalization = :none
+end
+```
+
+## Running the test suite
+
+The test suite may be run simply using
+
+    rspec
+
+## Contributions
+
+Tint remains in its infancy and all pull requests, issues and feedback are welcome and appreciated.
+

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/tint.rb

@@ -0,0 +1,18 @@
+module Tint
+  class << self
+    attr_accessor :camelize_attribute_names
+
+    def configuration
+      if block_given?
+        yield(Tint)
+      end
+    end
+
+    alias :config :configuration
+  end
+
+  @attribute_capitalization = :camel_case
+end
+
+require "tint/version"
+require "tint/decorator"

data/lib/tint/decorator.rb

@@ -0,0 +1,139 @@
+require 'draper'
+require_relative 'json_conversion.rb'
+
+module Tint
+  class Decorator < Draper::Decorator
+    include JsonConversion
+
+    def initialize(object, options = {})
+      super(object, options)
+    end
+
+    def column_names
+      object.class.column_names
+    end
+
+    def persisted?
+      object.persisted?
+    end
+
+    class << self
+      attr_accessor :_attributes, :eager_loads
+
+      def attributes(*options)
+        @_attributes ||= Set.new
+
+        return unless options && options.any?
+
+        mapped_attrs = options.extract_options!
+
+        link_mappings_to_object(mapped_attrs)
+
+        delegated_attrs = options
+
+        link_delegations_to_object(delegated_attrs)
+      end
+
+      def eager_load(*schema)
+        @_attributes ||= Set.new
+        @eager_loads ||= []
+
+        schema.each do |schema_item|
+          @eager_loads.push(schema_item)
+        end
+      end
+
+      def decorates_association(association_name, options = {})
+        options[:with] ||= (association_name.to_s.camelize.singularize + 'Decorator').constantize
+
+        super(association_name, options)
+
+        attributes(association_name)
+        association_eager_loads = options[:with].eager_loads
+
+        if association_eager_loads.present?
+          eager_load({ association_name =>  association_eager_loads})
+        else
+          eager_load(association_name)
+        end
+      end
+
+      def decorates_associations(*arguments)
+        options = arguments.extract_options!
+        association_list = arguments
+
+        association_list.each do |association_name|
+          decorates_association(association_name, options.dup)
+        end
+      end
+
+      def decorate_collection(collection, options = {})
+        collection_with_eager_loads =
+            if collection.respond_to?(:includes) && eager_loads.present?
+              collection.includes(*eager_loads)
+            else
+              collection
+            end
+
+        super(collection_with_eager_loads, options)
+      end
+
+      def decorate(object, options = {})
+        object_class = object.class
+
+        unless already_eager_loaded_associations?(object)
+          object =
+              if responds_to_methods?(object_class, :includes, :find) && eager_loads.present?
+                object_class.includes(*eager_loads).find(object.id)
+              else
+                object
+              end
+        end
+
+        super(object, options)
+      end
+
+      private
+
+      def already_eager_loaded_associations?(object)
+        if object.respond_to?(:association_cache)
+          object.association_cache.any?
+        else
+          true
+        end
+      end
+
+      def responds_to_methods?(object, *methods)
+        methods.each do |method_name|
+          return false unless object.respond_to?(method_name)
+        end
+
+        true
+      end
+
+      def link_delegations_to_object(delegated_attrs)
+        delegated_attrs.each do |delegate_method|
+          @_attributes.add(delegate_method)
+
+          unless method_defined?(delegate_method)
+            define_method(delegate_method) do
+              object.send(delegate_method)
+            end
+          end
+        end
+      end
+
+      def link_mappings_to_object(mapped_attrs)
+        mapped_attrs.each do |decorator_attribute, object_method|
+          @_attributes.add(decorator_attribute)
+
+          define_method(decorator_attribute) do
+            object.send(object_method)
+          end
+        end
+      end
+    end
+
+
+  end
+end

data/lib/tint/json_conversion.rb

@@ -0,0 +1,71 @@
+module Tint
+  module JsonConversion
+    def to_json(options={})
+      as_json.to_json(options)
+    end
+
+    def as_json(options={})
+      attributes_for_json
+    end
+
+    private
+
+    module AttributeNameStrategy
+      class Stringify
+        class << self
+          def transform(attribute_name)
+            attribute_name.to_s
+          end
+        end
+      end
+
+      class Camelize
+        class << self
+          def transform(attribute_name)
+            Stringify.transform(attribute_name).camelize(:lower)
+          end
+        end
+      end
+
+      class Snakize
+        class << self
+          def transform(attribute_name)
+            Stringify.transform(attribute_name).underscore
+          end
+        end
+      end
+
+      class Kebabize
+        class << self
+          def transform(attribute_name)
+            Stringify.transform(attribute_name).dasherize
+          end
+        end
+      end
+    end
+
+    def attributes_for_json
+      strategy =
+        case Tint.camelize_attribute_names
+        when :camel_case
+          AttributeNameStrategy::Camelize
+        when :snake_case
+          AttributeNameStrategy::Snakize
+        when :kebab_case
+          AttributeNameStrategy::Kebabize
+        else
+          AttributeNameStrategy::Stringify
+        end
+
+      self.class._attributes.inject({}) do |memo, key_and_value|
+        key, _ = key_and_value
+
+        unless (value = self.send(key)).nil?
+          memo[strategy.transform(key)] = value.respond_to?(:as_json) ? value.as_json : value
+        end
+
+        memo
+      end
+    end
+  end
+end

data/lib/tint/version.rb

@@ -0,0 +1,3 @@
+module Tint
+  VERSION = "0.0.1"
+end

data/spec/support/active_record_mock.rb

@@ -0,0 +1,5 @@
+class ActiveRecordMock
+  def attributes
+    instance_variables
+  end
+end

data/spec/tint/decorator_spec.rb

@@ -0,0 +1,158 @@
+require 'tint'
+require_relative '../support/active_record_mock'
+
+RSpec.describe Tint::Decorator do
+  subject{ decorator_class.decorate(object).as_json }
+
+  let(:object_class) do
+    Class.new(ActiveRecordMock) do
+      attr_reader :attr1, :attr2
+
+      def initialize(attr1, attr2)
+        @attr1, @attr2 = attr1, attr2
+      end
+    end
+  end
+
+  let(:object) { object_class.new('one', 'two') }
+
+  describe "::attributes" do
+    context "when only delegations are defined" do
+      let(:decorator_class) do
+        Class.new(Tint::Decorator) do
+          attributes :attr1, :attr2
+        end
+      end
+
+      it "delegates attributes of the same name to the object" do
+        expect(subject['attr1']).to eql('one')
+        expect(subject['attr2']).to eql('two')
+      end
+    end
+
+    context "when delegations and mappings are defined" do
+      let(:decorator_class) do
+        Class.new(Tint::Decorator) do
+          attributes :attr1, decorated1: :attr2
+        end
+      end
+
+      it "delegates attributes of the same name to the object" do
+        expect(subject['attr1']).to eql('one')
+        expect(subject['decorated1']).to eql('two')
+      end
+    end
+
+    context "when only mappings are defined" do
+      let(:decorator_class) do
+        Class.new(Tint::Decorator) do
+          attributes decorated1: :attr1, decorated2: :attr2
+        end
+      end
+
+      it "delegates attributes of the same name to the object" do
+        expect(subject['decorated1']).to eql('one')
+        expect(subject['decorated2']).to eql('two')
+      end
+    end
+  end
+
+  describe "::decorates_association" do
+    let(:associated_decorator) do
+      Class.new(Tint::Decorator) do
+        attributes :attr1
+      end
+    end
+
+    let(:associated_object) do
+      Class.new(ActiveRecordMock) do
+        attr_reader :attr1
+
+        def initialize(attribute_value)
+          @attr1 = attribute_value
+        end
+      end
+    end
+
+    let(:main_object) do
+      Class.new(Tint::Decorator) do
+        attr_reader :associated
+
+        def initialize(associated)
+          @associated = associated
+        end
+      end
+    end
+
+    let(:object) { main_object.new(associated_object.new('value')) }
+
+    context "when no with option is provided" do
+      let(:decorator_class) do
+        Class.new(Tint::Decorator) do
+          decorates_association :associated
+        end
+      end
+
+      before(:each) do
+        Object.const_set('AssociatedDecorator', associated_decorator)
+      end
+
+      it "attempts to use a decorator with the same name as the association" do
+        expect(subject['associated']['attr1']).to eql('value')
+      end
+
+      after(:each) do
+        Object.send(:remove_const, 'AssociatedDecorator')
+      end
+    end
+
+    context "when a with option is provided" do
+      let(:explicitly_referenced_decorator) do
+        Class.new(Tint::Decorator) do
+          attributes decorated1: :attr1
+        end
+      end
+
+      let(:decorator_class) do
+        Class.new(Tint::Decorator) do
+          decorates_association :associated, with: ExplicitlyReferencedDecorator
+        end
+      end
+
+      before(:each) do
+        Object.const_set('ExplicitlyReferencedDecorator', explicitly_referenced_decorator)
+      end
+
+      it "uses the specified decorator" do
+        expect(subject['associated']['decorated1']).to eql('value')
+      end
+
+      after(:each) do
+        Object.send(:remove_const, 'ExplicitlyReferencedDecorator')
+      end
+    end
+  end
+
+  describe "::eager_load" do
+    it "adds the associations to the list to eager load" do
+
+      eager_load_schemas = [
+          [:associated],
+          [ { associated1: [:associated2] } ],
+          [ { associated1: { associated2: [:associated3] } } ],
+          [ :associated1, { associated2: [:associated3] } ]
+      ]
+
+      eager_load_schemas.each do |eager_load_schema|
+        decorator_class =
+            Class.new(Tint::Decorator) do
+              eager_load *eager_load_schema
+            end
+
+        eager_load_schema.each do |schema|
+          expect(decorator_class.eager_loads).to include(schema)
+        end
+      end
+    end
+  end
+end

data/tint.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'tint/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "tint"
+  spec.version       = Tint::VERSION
+  spec.authors       = ["Aleck Greenham"]
+  spec.email         = ["greenhama13@gmail.com"]
+  spec.summary       = "Declarative object decorators for JSON APIs"
+  spec.description   = "Easily define object decorators for JSON APIs using simple declarative syntax"
+  spec.homepage      = "https://github.com/greena13/tint"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "draper", "~> 2.1"
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 0"
+  spec.add_development_dependency "rspec", "~> 0"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: tint
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Aleck Greenham
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-01-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: draper
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Easily define object decorators for JSON APIs using simple declarative
+  syntax
+email:
+- greenhama13@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/tint.rb
+- lib/tint/decorator.rb
+- lib/tint/json_conversion.rb
+- lib/tint/version.rb
+- spec/support/active_record_mock.rb
+- spec/tint/decorator_spec.rb
+- tint.gemspec
+homepage: https://github.com/greena13/tint
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Declarative object decorators for JSON APIs
+test_files:
+- spec/support/active_record_mock.rb
+- spec/tint/decorator_spec.rb