grape-entity 0.4.8 → 0.10.2

data/Guardfile

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
+
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
 guard 'rspec', version: 2 do
   watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
   watch(%r{^spec/support/shared_versioning_examples.rb$}) { |_m| 'spec/' }
-  watch('spec/spec_helper.rb')  { 'spec/' }
+  watch('spec/spec_helper.rb') { 'spec/' }
 end
 
 guard 'bundler' do

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Michael Bleigh and Intridea, Inc.
+Copyright (c) 2010-2016 Michael Bleigh, Intridea, Inc., ruby-grape and Contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,10 +1,47 @@
-# Grape::Entity
-
 [![Gem Version](http://img.shields.io/gem/v/grape-entity.svg)](http://badge.fury.io/rb/grape-entity)
-[![Build Status](http://img.shields.io/travis/ruby-grape/grape-entity.svg)](https://travis-ci.org/ruby-grape/grape-entity)
-[![Dependency Status](https://gemnasium.com/ruby-grape/grape-entity.svg)](https://gemnasium.com/ruby-grape/grape-entity)
+![Ruby](https://github.com/ruby-grape/grape-entity/workflows/Ruby/badge.svg)
+[![Coverage Status](https://coveralls.io/repos/github/ruby-grape/grape-entity/badge.svg?branch=master)](https://coveralls.io/github/ruby-grape/grape-entity?branch=master)
 [![Code Climate](https://codeclimate.com/github/ruby-grape/grape-entity.svg)](https://codeclimate.com/github/ruby-grape/grape-entity)
 
+# Table of Contents
+
+- [Grape::Entity](#grapeentity)
+  - [Introduction](#introduction)
+    - [Example](#example)
+  - [Reusable Responses with Entities](#reusable-responses-with-entities)
+    - [Defining Entities](#defining-entities)
+      - [Basic Exposure](#basic-exposure)
+      - [Exposing with a Presenter](#exposing-with-a-presenter)
+      - [Conditional Exposure](#conditional-exposure)
+      - [Safe Exposure](#safe-exposure)
+      - [Nested Exposure](#nested-exposure)
+      - [Collection Exposure](#collection-exposure)
+      - [Merge Fields](#merge-fields)
+      - [Runtime Exposure](#runtime-exposure)
+      - [Unexpose](#unexpose)
+      - [Overriding exposures](#overriding-exposures)
+      - [Returning only the fields you want](#returning-only-the-fields-you-want)
+      - [Aliases](#aliases)
+      - [Format Before Exposing](#format-before-exposing)
+      - [Expose Nil](#expose-nil)
+      - [Default Value](#default-value)
+      - [Documentation](#documentation)
+    - [Options Hash](#options-hash)
+      - [Passing Additional Option To Nested Exposure](#passing-additional-option-to-nested-exposure)
+      - [Attribute Path Tracking](#attribute-path-tracking)
+    - [Using the Exposure DSL](#using-the-exposure-dsl)
+    - [Using Entities](#using-entities)
+    - [Entity Organization](#entity-organization)
+    - [Caveats](#caveats)
+  - [Installation](#installation)
+  - [Testing with Entities](#testing-with-entities)
+  - [Project Resources](#project-resources)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Copyright](#copyright)
+
+# Grape::Entity
+
 ## Introduction
 
 This gem adds Entity support to API frameworks, such as [Grape](https://github.com/ruby-grape/grape). Grape's Entity is an API focused facade that sits on top of an object model.
@@ -21,9 +58,10 @@ module API
       expose :text, documentation: { type: "String", desc: "Status update text." }
       expose :ip, if: { type: :full }
       expose :user_type, :user_id, if: lambda { |status, options| status.user.public? }
+      expose :location, merge: true
       expose :contact_info do
         expose :phone
-        expose :address, using: API::Entities::Address
+        expose :address, merge: true, using: API::Entities::Address
       end
       expose :digest do |status, options|
         Digest::MD5.hexdigest status.txt
@@ -73,6 +111,20 @@ The field lookup takes several steps
 * next try `object.fetch(exposure)`
 * last raise an Exception
 
+`exposure` is a Symbol by default. If `object` is a Hash with stringified keys, you can set the hash accessor at the entity-class level to properly expose its members:
+
+```ruby
+class Status < GrapeEntity
+  self.hash_access = :to_s
+
+  expose :code
+  expose :message
+end
+
+Status.represent({ 'code' => 418, 'message' => "I'm a teapot" }).as_json
+#=> { code: 418, message: "I'm a teapot" }
+```
+
 #### Exposing with a Presenter
 
 Don't derive your model classes from `Grape::Entity`, expose them using a presenter.
@@ -153,6 +205,40 @@ As example:
 
 ```
 
+#### Merge Fields
+
+Use `:merge` option to merge fields into the hash or into the root:
+
+```ruby
+expose :contact_info do
+  expose :phone
+  expose :address, merge: true, using: API::Entities::Address
+end
+
+expose :status, merge: true
+```
+
+This will return something like:
+
+```ruby
+{ contact_info: { phone: "88002000700", city: 'City 17', address_line: 'Block C' }, text: 'HL3', likes: 19 }
+```
+
+It also works with collections:
+
+```ruby
+expose :profiles do
+  expose :users, merge: true, using: API::Entities::User
+  expose :admins, merge: true, using: API::Entities::Admin
+end
+```
+
+Provide lambda to solve collisions:
+
+```ruby
+expose :status, merge: ->(key, old_val, new_val) { old_val + new_val if old_val && new_val }
+```
+
 #### Runtime Exposure
 
 Use a block or a `Proc` to evaluate exposure at runtime. The supplied block or
@@ -177,7 +263,7 @@ on the object the entity wraps.
 class ExampleEntity < Grape::Entity
   expose :attr_not_on_wrapped_object
   # ...
-private
+  private
 
   def attr_not_on_wrapped_object
     42
@@ -185,16 +271,17 @@ private
 end
 ```
 
-You have always access to the presented instance with `object`
+You always have access to the presented instance (`object`) and the top-level
+entity options (`options`).
 
 ```ruby
 class ExampleEntity < Grape::Entity
   expose :formatted_value
   # ...
-private
+  private
 
   def formatted_value
-    "+ X #{object.value}"
+    "+ X #{object.value} #{options[:y]}"
   end
 end
 ```
@@ -220,6 +307,22 @@ class MailingAddress < UserData
 end
 ```
 
+#### Overriding exposures
+
+If you want to add one more exposure for the field but don't want the first one to be fired (for instance, when using inheritance), you can use the `override` flag. For instance:
+
+```ruby
+class User < Grape::Entity
+  expose :name
+end
+
+class Employee < User
+  expose :name, as: :employee_name, override: true
+end
+```
+
+`User` will return something like this `{ "name" : "John" }` while `Employee` will present the same data as `{ "employee_name" : "John" }` instead of `{ "name" : "John", "employee_name" : "John" }`.
+
 #### Returning only the fields you want
 
 After exposing the desired attributes, you can choose which one you need when representing some object or collection by using the only: and except: options. See the example:
@@ -276,10 +379,134 @@ expose :replies, using: API::Entities::Status, as: :responses
 Apply a formatter before exposing a value.
 
 ```ruby
-format_with(:iso_timestamp) { |dt| dt.iso8601 }
-with_options(format_with: :iso_timestamp) do
-  expose :created_at
-  expose :updated_at
+module Entities
+  class MyModel < Grape::Entity
+    format_with(:iso_timestamp) do |date|
+      date.iso8601
+    end
+
+    with_options(format_with: :iso_timestamp) do
+      expose :created_at
+      expose :updated_at
+    end
+  end
+end
+```
+
+Defining a reusable formatter between multiples entities:
+
+```ruby
+module ApiHelpers
+  extend Grape::API::Helpers
+
+  Grape::Entity.format_with :utc do |date|
+    date.utc if date
+  end
+end
+```
+
+```ruby
+module Entities
+  class MyModel < Grape::Entity
+    expose :updated_at, format_with: :utc
+  end
+
+  class AnotherModel < Grape::Entity
+    expose :created_at, format_with: :utc
+  end
+end
+```
+
+#### Expose Nil
+
+By default, exposures that contain `nil` values will be represented in the resulting JSON as `null`.
+
+As an example, a hash with the following values:
+
+```ruby
+{
+  name: nil,
+  age: 100
+}
+```
+
+will result in a JSON object that looks like:
+
+```javascript
+{
+  "name": null,
+  "age": 100
+}
+```
+
+There are also times when, rather than displaying an attribute with a `null` value, it is more desirable to not display the attribute at all. Using the hash from above the desired JSON would look like:
+
+```javascript
+{
+  "age": 100
+}
+```
+
+In order to turn on this behavior for an as-exposure basis, the option `expose_nil` can be used. By default, `expose_nil` is considered to be `true`, meaning that `nil` values will be represented in JSON as `null`. If `false` is provided, then attributes with `nil` values will be omitted from the resulting JSON completely.
+
+```ruby
+module  Entities
+  class MyModel < Grape::Entity
+    expose :name, expose_nil: false
+    expose :age, expose_nil: false
+  end
+end
+```
+
+`expose_nil` is per exposure, so you can suppress exposures from resulting in `null` or express `null` values on a per exposure basis as you need:
+
+```ruby
+module  Entities
+  class MyModel < Grape::Entity
+    expose :name, expose_nil: false
+    expose :age # since expose_nil is omitted nil values will be rendered as null
+  end
+end
+```
+
+It is also possible to use `expose_nil` with `with_options` if you want to add the configuration to multiple exposures at once.
+
+```ruby
+module  Entities
+  class MyModel < Grape::Entity
+    # None of the exposures in the with_options block will render nil values as null
+    with_options(expose_nil: false) do
+      expose :name
+      expose :age
+    end
+  end
+end
+```
+
+When using `with_options`, it is possible to again override which exposures will render `nil` as `null` by adding the option on a specific exposure.
+
+```ruby
+module  Entities
+  class MyModel < Grape::Entity
+    # None of the exposures in the with_options block will render nil values as null
+    with_options(expose_nil: false) do
+      expose :name
+      expose :age, expose_nil: true # nil values would be rendered as null in the JSON
+    end
+  end
+end
+```
+
+#### Default Value
+
+This option can be used to provide a default value in case the return value is nil or empty.
+
+```ruby
+module  Entities
+  class MyModel < Grape::Entity
+    expose :name, default: ''
+    expose :age, default: 60
+  end
 end
 ```
 
@@ -311,7 +538,7 @@ present s, with: Status, user: current_user
 ```
 
 #### Passing Additional Option To Nested Exposure
-There are sometimes that you want to pass additional option or parameter to nested exposure. Assume that you need to expose an address for a contact info, but it has both two different format: **full** and **simple**. You can pass an additional `full_format` option to specify that if the nested entity should render address in `:full` format.
+Sometimes you want to pass additional options or parameters to nested a exposure. For example, let's say that you need to expose an address for a contact info and it has two different formats: **full** and **simple**. You can pass an additional `full_format` option to specify which format to render.
 
 ```ruby
 # api/contact.rb
@@ -327,12 +554,38 @@ end
 # api/address.rb
 expose :state, if: lambda {|instance, options| !!options[:full_format]}      # the new option could be retrieved in options hash for conditional exposure
 expose :city, if: lambda {|instance, options| !!options[:full_format]}
-expose :stree do |instance, options|
+expose :street do |instance, options|
   # the new option could be retrieved in options hash for runtime exposure
   !!options[:full_format] ? instance.full_street_name : instance.simple_street_name
 end
 ```
-**Notice**: In the above code, you should pay attention to [**Safe Exposure**](#safe-exposure) yourself, for example, `instance.address` might be `nil`, in this situation, it is better to expose it as nil directly.
+**Notice**: In the above code, you should pay attention to [**Safe Exposure**](#safe-exposure) yourself. For example, `instance.address` might be `nil`  and it is better to expose it as nil directly.
+
+#### Attribute Path Tracking
+
+Sometimes, especially when there are nested attributes, you might want to know which attribute
+is being exposed. For example, some APIs allow users to provide a parameter to control which fields
+will be included in (or excluded from) the response.
+
+GrapeEntity can track the path of each attribute, which you can access during conditions checking
+or runtime exposure via `options[:attr_path]`.
+
+The attribute path is an array. The last item of this array is the name (alias) of current attribute.
+If the attribute is nested, the former items are names (aliases) of its ancestor attributes.
+
+Example:
+
+```ruby
+class Status < Grape::Entity
+  expose :user  # path is [:user]
+  expose :foo, as: :bar  # path is [:bar]
+  expose :a do
+    expose :b, as: :xx do
+      expose :c  # path is [:a, :xx, :c]
+    end
+  end
+end
+```
 
 ### Using the Exposure DSL
 
@@ -352,7 +605,7 @@ The above will automatically create a `Status::Entity` class and define properti
 
 ### Using Entities
 
-With Grape, once an entity is defined, it can be used within endpoints, by calling `present`. The `present` method accepts two arguments, the `object` to be presented and the `options` associated with it. The options hash must always include `:with`, which defines the entity to expose.
+With Grape, once an entity is defined, it can be used within endpoints, by calling `present`. The `present` method accepts two arguments, the `object` to be presented and the `options` associated with it. The options hash must always include `:with`, which defines the entity to expose (unless namespaced entity classes are used, see [next section](#entity-organization)).
 If the entity includes documentation it can be included in an endpoint's description.
 
 ```ruby
@@ -388,7 +641,7 @@ class Status
 end
 ```
 
-If you organize your entities this way, Grape will automatically detect the `Entity` class and use it to present your models. In this example, if you added `present User.new` to your endpoint, Grape would automatically detect that there is a `Status::Entity` class and use that as the representative entity. This can still be overridden by using the `:with` option or an explicit `represents` call.
+If you organize your entities this way, Grape will automatically detect the `Entity` class and use it to present your models. In this example, if you added `present Status.new` to your endpoint, Grape would automatically detect that there is a `Status::Entity` class and use that as the representative entity. This can still be overridden by using the `:with` option or an explicit `represents` call.
 
 ### Caveats
 
@@ -455,4 +708,4 @@ MIT License. See [LICENSE](LICENSE) for details.
 
 ## Copyright
 
-Copyright (c) 2010-2014 Michael Bleigh, Intridea, Inc., and contributors.
+Copyright (c) 2010-2016 Michael Bleigh, Intridea, Inc., ruby-grape and Contributors.

data/Rakefile

@@ -1,22 +1,20 @@
+# frozen_string_literal: true
+
 require 'rubygems'
 require 'bundler'
-Bundler.setup :default, :test, :development
+
+Bundler.setup(:default, :development)
+
+require 'rake'
 
 Bundler::GemHelper.install_tasks
 
+require 'rspec/core'
 require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-end
 
-RSpec::Core::RakeTask.new(:rcov) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
-end
+RSpec::Core::RakeTask.new(:spec)
 
-task :spec
-require 'rainbow/ext/string' unless String.respond_to?(:color)
 require 'rubocop/rake_task'
 RuboCop::RakeTask.new(:rubocop)
 
-task default: [:rubocop, :spec]
+task default: %i[spec rubocop]

data/UPGRADING.md

@@ -0,0 +1,35 @@
+# Upgrading Grape Entity
+
+
+### Upgrading to >= 0.8.2
+
+Official support for ruby < 2.5 removed, ruby 2.5 only in testing mode, but no support.
+
+In Ruby 3.0: the block handling will be changed
+[language-changes point 3, Proc](https://github.com/ruby/ruby/blob/v3_0_0_preview1/NEWS.md#language-changes).
+This:
+```ruby
+expose :that_method_without_args, &:method_without_args
+```
+will be deprecated.
+
+Prefer to use this pattern for simple setting a value
+```ruby
+expose :method_without_args, as: :that_method_without_args
+```
+
+### Upgrading to >= 0.6.0
+
+#### Changes in Grape::Entity#inspect
+
+The `Grape::Entity#inspect` method will no longer serialize the entity presenter with its options and delegator, but the exposed entity itself, using `#serializable_hash`.
+
+See [#250](https://github.com/ruby-grape/grape-entity/pull/250) for more information.
+
+### Upgrading to >= 0.5.1
+
+#### Changes in NestedExposures.delete_if
+
+`Grape::Entity::Exposure::NestingExposure::NestedExposures.delete_if` always returns exposures, regardless of delete result (used to be `nil` in negative case).
+
+See [#203](https://github.com/ruby-grape/grape-entity/pull/203) for more information.

data/bench/serializing.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'grape-entity'
 require 'benchmark'
@@ -5,6 +7,7 @@ require 'benchmark'
 module Models
   class School
     attr_reader :classrooms
+
     def initialize
       @classrooms = []
     end
@@ -13,6 +16,7 @@ module Models
   class ClassRoom
     attr_reader :students
     attr_accessor :teacher
+
     def initialize(opts = {})
       @teacher = opts[:teacher]
       @students = []
@@ -21,6 +25,7 @@ module Models
 
   class Person
     attr_accessor :name
+
     def initialize(opts = {})
       @name = opts[:name]
     end
@@ -28,6 +33,7 @@ module Models
 
   class Teacher < Models::Person
     attr_accessor :tenure
+
     def initialize(opts = {})
       super(opts)
       @tenure = opts[:tenure]
@@ -36,6 +42,7 @@ module Models
 
   class Student < Models::Person
     attr_reader :grade
+
     def initialize(opts = {})
       super(opts)
       @grade = opts[:grade]

data/grape-entity.gemspec

@@ -1,4 +1,6 @@
-$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
 require 'grape_entity/version'
 
 Gem::Specification.new do |s|
@@ -12,19 +14,22 @@ Gem::Specification.new do |s|
   s.description = 'Extracted from Grape, A Ruby framework for rapid API development with great conventions.'
   s.license     = 'MIT'
 
-  s.rubyforge_project = 'grape-entity'
+  s.required_ruby_version = '>= 2.5'
 
-  s.add_runtime_dependency 'activesupport'
+  s.add_runtime_dependency 'activesupport', '>= 3.0.0'
+  # FIXME: remove dependecy
   s.add_runtime_dependency 'multi_json', '>= 1.3.2'
 
-  s.add_development_dependency 'rake'
+  s.add_development_dependency 'bundler'
   s.add_development_dependency 'maruku'
+  s.add_development_dependency 'pry' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')
+  s.add_development_dependency 'pry-byebug' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')
+  s.add_development_dependency 'rack-test'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec', '~> 3.9'
   s.add_development_dependency 'yard'
-  s.add_development_dependency 'rspec', '~> 2.9'
-  s.add_development_dependency 'bundler'
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.test_files    = `git ls-files -- {test,spec}/*`.split("\n")
   s.require_paths = ['lib']
 end

data/lib/grape-entity.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'grape_entity'

data/lib/grape_entity/condition/base.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Grape
+  class Entity
+    module Condition
+      class Base
+        def self.new(inverse, *args, &block)
+          super(inverse).tap { |e| e.setup(*args, &block) }
+        end
+
+        def initialize(inverse = false)
+          @inverse = inverse
+        end
+
+        def ==(other)
+          (self.class == other.class) && (inversed? == other.inversed?)
+        end
+
+        def inversed?
+          @inverse
+        end
+
+        def met?(entity, options)
+          @inverse ? unless_value(entity, options) : if_value(entity, options)
+        end
+
+        def if_value(_entity, _options)
+          raise NotImplementedError
+        end
+
+        def unless_value(entity, options)
+          !if_value(entity, options)
+        end
+      end
+    end
+  end
+end

data/lib/grape_entity/condition/block_condition.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Grape
+  class Entity
+    module Condition
+      class BlockCondition < Base
+        attr_reader :block
+
+        def setup(block)
+          @block = block
+        end
+
+        def ==(other)
+          super && @block == other.block
+        end
+
+        def if_value(entity, options)
+          entity.exec_with_object(options, &@block)
+        end
+      end
+    end
+  end
+end

data/lib/grape_entity/condition/hash_condition.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Grape
+  class Entity
+    module Condition
+      class HashCondition < Base
+        attr_reader :cond_hash
+
+        def setup(cond_hash)
+          @cond_hash = cond_hash
+        end
+
+        def ==(other)
+          super && @cond_hash == other.cond_hash
+        end
+
+        def if_value(_entity, options)
+          @cond_hash.all? { |k, v| options[k.to_sym] == v }
+        end
+
+        def unless_value(_entity, options)
+          @cond_hash.any? { |k, v| options[k.to_sym] != v }
+        end
+      end
+    end
+  end
+end

data/lib/grape_entity/condition/symbol_condition.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Grape
+  class Entity
+    module Condition
+      class SymbolCondition < Base
+        attr_reader :symbol
+
+        def setup(symbol)
+          @symbol = symbol
+        end
+
+        def ==(other)
+          super && @symbol == other.symbol
+        end
+
+        def if_value(_entity, options)
+          options[symbol]
+        end
+      end
+    end
+  end
+end