grape-roar 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 35902dfffe597a1d52445e821a2bfa9dd69659eb
-  data.tar.gz: b0e312c15b9f890086c4238e1cfc6bd21a939d73
+  metadata.gz: 275fcec452345c4903f635a7a4d3cf87ac5f662a
+  data.tar.gz: fa6541ccfd36c24e05460da5a5eb9f3c7b837f7e
 SHA512:
-  metadata.gz: 9764c7913adbb061397bc7a589ace6205e05d91ad4abcfcc6db4fe846789236e67938eda3cd47a78f1fd8b5af97dfd56d05553a2ad04fb03fdb00f1827d4220e
-  data.tar.gz: 4e2b82c862999d5f8e748624d7b8cfd099a5f3b4e057efc122bc2ecbdeb5e0aca356b034d28f393ec112bba45cbc2323406f38004765343eefb168f669ebea43
+  metadata.gz: 773562779d81ea01fdeb3cf9b51ebc85d222f39945204424a917b07586bfa3a7b426b220ba5aa8b5c2daf16797e001c795cba7114c976aed348e98d4c929da77
+  data.tar.gz: 3b3f6c811fa78c9b3215fd2c100d1acbd94cd2fe53b00812837b0674284f0668e34a6c3c355adaab69085056439765d3772a50a4b5ef8510c88332599d959637

data/.gitignore

@@ -2,3 +2,4 @@ Gemfile.lock
 doc
 pkg
 .bundle
+gemfiles/*.lock

data/.rspec

@@ -1,3 +1,4 @@
+--require spec_helper
 --color
 --format=documentation
 

data/.rubocop.yml

@@ -1,6 +1,10 @@
 AllCops:
+  TargetRubyVersion: 2.3
+  DisplayCopNames: true
   Exclude:
-    - vendor/**/*
     - bin/**/*
+    - gemfiles/**/*
+    - spec/**/*
+    - vendor/**/*
 
-inherit_from: .rubocop_todo.yml
+inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -1,20 +1,49 @@
-# This configuration was generated by `rubocop --auto-gen-config`
-# on 2014-12-18 10:52:56 -0500 using RuboCop version 0.28.0.
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2017-07-02 09:34:39 -0400 using RuboCop version 0.49.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 8
-# Configuration parameters: AllowURI, URISchemes.
+# Offense count: 7
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
+# URISchemes: http, https
 Metrics/LineLength:
-  Max: 304
+  Max: 108
 
-# Offense count: 13
+# Offense count: 14
 Style/Documentation:
-  Enabled: false
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/grape/roar/decorator.rb'
+    - 'lib/grape/roar/extensions/relations.rb'
+    - 'lib/grape/roar/extensions/relations/adapters.rb'
+    - 'lib/grape/roar/extensions/relations/adapters/active_record.rb'
+    - 'lib/grape/roar/extensions/relations/adapters/base.rb'
+    - 'lib/grape/roar/extensions/relations/adapters/mongoid.rb'
+    - 'lib/grape/roar/extensions/relations/dsl_methods.rb'
+    - 'lib/grape/roar/extensions/relations/mapper.rb'
+    - 'lib/grape/roar/extensions/relations/validations/active_record.rb'
+    - 'lib/grape/roar/extensions/relations/validations/misc.rb'
+    - 'lib/grape/roar/extensions/relations/validations/mongoid.rb'
+    - 'lib/grape/roar/formatter.rb'
+    - 'lib/grape/roar/representer.rb'
 
 # Offense count: 1
-# Configuration parameters: Exclude.
+# Configuration parameters: ExpectMatchingDefinition, Regex, IgnoreExecutableScripts, AllowedAcronyms.
+# AllowedAcronyms: CLI, DSL, ACL, API, ASCII, CPU, CSS, DNS, EOF, GUID, HTML, HTTP, HTTPS, ID, IP, JSON, LHS, QPS, RAM, RHS, RPC, SLA, SMTP, SQL, SSH, TCP, TLS, TTL, UDP, UI, UID, UUID, URI, URL, UTF8, VM, XML, XMPP, XSRF, XSS
 Style/FileName:
-  Enabled: false
+  Exclude:
+    - 'lib/grape-roar.rb'
+
+# Offense count: 3
+# Configuration parameters: NamePrefix, NamePrefixBlacklist, NameWhitelist.
+# NamePrefix: is_, has_, have_
+# NamePrefixBlacklist: is_, has_, have_
+# NameWhitelist: is_a?
+Style/PredicateName:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/grape/roar/extensions/relations/validations/active_record.rb'

data/.travis.yml

@@ -5,6 +5,32 @@ language: ruby
 cache: bundler
 
 rvm:
-  - ruby-head
-  - 2.2.2
-  - 2.3.1
+  - 2.4.1
+  - 2.3.4
+
+gemfile:
+  - Gemfile
+  - gemfiles/with_activerecord.gemfile
+  - gemfiles/with_mongoid.gemfile
+
+services:
+  - mongodb
+  - pg
+
+matrix:
+  include:
+    - env: SPEC_OPTS="--tag active_record"
+      gemfile: gemfiles/with_activerecord.gemfile
+      rvm: 2.4.1
+    - env: SPEC_OPTS="--tag mongoid"
+      gemfile: gemfiles/with_mongoid.gemfile
+      rvm: 2.4.1
+    - env: SPEC_OPTS="--tag active_record"
+      gemfile: gemfiles/with_activerecord.gemfile
+      rvm: 2.3.4
+    - env: SPEC_OPTS="--tag mongoid"
+      gemfile: gemfiles/with_mongoid.gemfile
+      rvm: 2.3.4
+
+
+script: bundle exec rake

data/Appraisals

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+appraise 'with-activerecord' do
+  gem 'activerecord', '>= 4.0.0', require: 'active_record'
+end
+
+appraise 'with-mongoid' do
+  gem 'mongoid', '>= 5.0.0', require: 'mongoid'
+end

data/CHANGELOG.md

@@ -1,17 +1,27 @@
+0.4.1 (07/14/2017)
+----
+
+* [#22](https://github.com/ruby-grape/grape-roar/pull/22): Adds Grape::Roar::Extensions::Relations.
+
+
 0.4.0 (02/18/2017)
 ------------------
+
 * [#21](https://github.com/ruby-grape/grape-roar/pull/21): Fixes serialization issue due to [representable](https://github.com/trailblazer/representable) API change, drop support for Ruby < `2.1.0` - [@mach-kernel](https://github.com/mach-kernel).
 
+
 0.3.0 (12/31/2014)
 ------------------
 
 * Added support for Roar 1.0 - [@dblock](https://github.com/dblock).
 
+
 0.2.0 (12/18/2014)
 ------------------
 
 * [#10](https://github.com/ruby-grape/grape-roar/pull/10): Support for Roar decorator - [@sdbondi](https://github.com/sdbondi).
 
+
 0.1.0 (7/17/2014)
 -----------------
 

data/Gemfile

@@ -1,17 +1,20 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec
 
 group :development do
-  gem 'rake', '~> 10.5.0'
+  gem 'appraisal', '2.2.0'
 end
 
 group :test do
-  gem 'rspec', '~> 3.1'
   gem 'rack-test'
+  gem 'rspec', '~> 3.1'
 end
 
 group :development, :test do
-  gem 'rubocop', '0.28.0'
   gem 'nokogiri', '1.6.3.1'
+  gem 'rake', '~> 10.5.0'
+  gem 'rubocop', '0.49.1'
 end

data/README.md

@@ -121,6 +121,224 @@ get 'products' do
 end
 ```
 
+### Relation Extensions
+
+If you use either `ActiveRecord` or `Mongoid`, you can use the `Grape::Roar::Extensions::Relations` DSL to expose the relationships in between your models as a HAL response. The DSL methods used are the same regardless of what your ORM/ODM is, as long as there exists [an adapter for it](#designing-adapters). 
+
+#### Designing Representers
+
+Arguments passed to `#relation` are forwarded to `roar`. Single member relations (e.g. `belongs_to`) are represented using `#property`, collections are represented using `#collection`; arguments provided to `#relation` will be passed through these methods (i.e. additional arguments [roar](https://github.com/trailblazer/roar) and [representable](http://trailblazer.to/gems/representable/3.0/api.html) accept).
+
+A default base URI is constructed from a `Grape::Request` by concatenating the `#base_url` and `#script_name` properties. The resource path is extracted from the name of the relation.
+
+Otherwise, the extensions attempt to look up the correct representer module/class for the objects (e.g. we infer the `extend` argument). You can always specify the correct representer to use on your own. 
+
+##### Example Models
+
+```ruby
+class Item < ActiveRecord::Base
+  belongs_to :cart
+end
+
+class Cart < ActiveRecord::Base
+  has_many :items  
+end
+```
+
+##### Example Representers
+
+```ruby
+class ItemEntity < Grape::Roar::Decorator
+  include Roar::JSON
+  include Roar::JSON::HAL
+  include Roar::Hypermedia
+
+  include Grape::Roar::Extensions::Relations
+
+  # Cart will be presented under the _embedded key
+  relation :belongs_to, :cart, embedded: true
+
+  link_self
+end
+
+class CartEntity < Grape::Roar::Decorator
+  include Roar::JSON
+  include Roar::JSON::HAL
+  include Roar::Hypermedia
+
+  include Grape::Roar::Extensions::Relations
+
+  # Items will be presented under the _links key
+  relation :has_many, :items, embedded: false
+
+  link_self
+end
+```
+
+Although this example uses `Grape::Roar::Decorator`, you can also use a module as show in prior examples above. If doing so, you no longer have to mix in `Grape::Roar::Representer`. 
+
+##### Example Item
+```javascript
+{
+    "_embedded": {
+        "cart": {
+            "_links": {
+                "self": {
+                    "href": "http://example.org/carts/1"
+                },
+                "items": [{
+                    "href": "http://example.org/items/1"
+                }]
+            }
+        }
+    },
+    "_links": {
+        "self": {
+            "href": "http://example.org/items/1"
+        }
+    }
+}
+```
+
+##### Example Cart
+```javascript
+{
+    "_links": {
+        "self": {
+            "href": "http://example.org/carts/1"
+        },
+        "items": [{
+            "href": "http://example.org/items/1"
+        }, {
+            "href": "http://example.org/items/2"
+        }, {
+            "href": "http://example.org/items/3"
+        }, {
+            "href": "http://example.org/items/4"
+        }, {
+            "href": "http://example.org/items/5"
+        }]
+    }
+}
+```
+
+#### Errors
+
+Should you incorrectly describe a relationship (e.g. you specify has_one but your model specifies has_many), an exception will be raised to notify you of the mismatch:
+
+```ruby
+Grape::Roar::Extensions::Relations::Exceptions::InvalidRelationError:
+  Expected Mongoid::Relations::Referenced::One, got Mongoid::Relations::Referenced::Many!
+```
+
+#### Change how URLs are presented
+
+The `opts` hash below is the same one as shown in prior examples.
+
+##### Override base URI mappings
+```ruby
+class BarEntity < Grape::Roar::Decorator
+  include Roar::JSON
+  include Roar::JSON::HAL
+  include Roar::Hypermedia
+
+  include Grape::Roar::Extensions::Relations
+
+  # This is our default implementation
+  map_base_url do |opts|
+    request = Grape::Request.new(opts[:env])
+    "#{request.base_url}#{request.script_name}"
+  end
+
+  relation :has_many, :bars, embedded: false
+end
+```
+
+##### Override resource URI mappings
+```ruby
+class BarEntity < Grape::Roar::Decorator
+  include Roar::JSON
+  include Roar::JSON::HAL
+  include Roar::Hypermedia
+
+  include Grape::Roar::Extensions::Relations
+
+  # This is our default implementation
+  map_resource_path do |_opts, object, relation_name|
+    "#{relation_name}/#{object.id}"
+  end
+
+  relation :has_many, :bars, embedded: false
+end
+```
+
+#### Designing Adapters
+
+If you have custom domain objects, you can create an adapter to make your models compatible with the DSL methods. Below is an example of the `ActiveRecord` adapter.
+
+##### Example: ActiveRecord Adapter
+
+```ruby
+module Extensions
+  module RelationalModels
+    module Adapter
+      class ActiveRecord < Base
+        include Validations::ActiveRecord
+
+        # We map your domain object to the correct adapter
+        # during runtime.
+        valid_for { |klass| klass < ::ActiveRecord::Base }
+
+        def collection_methods
+          @collection_methods ||= %i(has_many has_and_belongs_to_many)
+        end
+
+        def name_for_represented(represented)
+          klass_name = case represented
+                       when ::ActiveRecord::Relation
+                         represented.klass.name
+                       else
+                         represented.class.name
+                       end
+          klass_name.demodulize.pluralize.downcase
+        end
+
+        def single_entity_methods
+          @single_entity_methods ||= %i(has_one belongs_to)
+        end
+      end
+    end
+  end
+end
+```
+
+##### Validations
+
+Errors are handled by creating methods corresponding to those in `collection_methods` and `single_entity_methods`. For example, this is the validator for `belongs_to`:
+
+```ruby
+module ActiveRecord
+  include Validations::Misc
+
+  def belongs_to_valid?(relation)
+    relation = klass.reflections[relation]
+
+    return true if relation.is_a?(
+      ::ActiveRecord::Reflection::BelongsToReflection
+    )
+
+    # Provided by Validations::Misc
+    invalid_relation(
+      ::ActiveRecord::Reflection::BelongsToReflection,
+      relation.class
+    )
+  end
+end
+```
+
+After writing your validation methods, just mix them into your adapter. You can choose to not write validation methods; they are only invoked if your adapter responds to them. 
+
+
 Contributing
 ------------
 

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rubygems'
 require 'bundler'
 
@@ -13,4 +15,4 @@ end
 require 'rubocop/rake_task'
 RuboCop::RakeTask.new(:rubocop)
 
-task default: [:rubocop, :spec]
+task default: %i[rubocop spec]

data/gemfiles/with_activerecord.gemfile

@@ -0,0 +1,22 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", ">= 4.0.0", require: "active_record"
+
+group :development do
+  gem "appraisal", "2.2.0"
+end
+
+group :test do
+  gem "rack-test"
+  gem "rspec", "~> 3.1"
+end
+
+group :development, :test do
+  gem "nokogiri", "1.6.3.1"
+  gem "rake", "~> 10.5.0"
+  gem "rubocop", "0.49.1"
+end
+
+gemspec path: "../"