grape-roar 0.4.0 → 0.5.0

data/README.md

@@ -1,20 +1,43 @@
 Grape::Roar
-------------
+-----------
 
 [![Gem Version](http://img.shields.io/gem/v/grape-roar.svg)](http://badge.fury.io/rb/grape-roar)
-[![Build Status](http://img.shields.io/travis/ruby-grape/grape-roar.svg)](https://travis-ci.org/ruby-grape/grape-roar)
-[![Dependency Status](https://gemnasium.com/ruby-grape/grape-roar.svg)](https://gemnasium.com/ruby-grape/grape-roar)
-[![Code Climate](https://codeclimate.com/github/ruby-grape/grape-roar.svg)](https://codeclimate.com/github/ruby-grape/grape-roar)
+[![test](https://github.com/ruby-grape/grape-roar/actions/workflows/test.yml/badge.svg)](https://github.com/ruby-grape/grape-roar/actions/workflows/test.yml)
+[![test-activerecord](https://github.com/ruby-grape/grape-roar/actions/workflows/test-activerecord.yml/badge.svg)](https://github.com/ruby-grape/grape-roar/actions/workflows/test-activerecord.yml)
+[![test-mongodb](https://github.com/ruby-grape/grape-roar/actions/workflows/test-mongodb.yml/badge.svg)](https://github.com/ruby-grape/grape-roar/actions/workflows/test-mongodb.yml)
 
 Use [Roar](https://github.com/apotonick/roar) with [Grape](https://github.com/intridea/grape).
 
-Demo
-----
-
-The [grape-with-roar](https://github.com/ruby-grape/grape-with-roar) project deployed [here on heroku](http://grape-with-roar.herokuapp.com).
-
-Installation
-------------
+## Table of Contents
+
+- [Demo](#demo)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Tell your API to use Grape::Formatter::Roar](#tell-your-api-to-use-grapeformatterroar)
+  - [Use Grape’s Present](#use-grapes-present)
+  - [Accessing the Request Inside a Representer](#accessing-the-request-inside-a-representer)
+  - [Decorators](#decorators)
+  - [Relation Extensions](#relation-extensions)
+    - [Designing Representers](#designing-representers)
+      - [Example Models](#example-models)
+      - [Example Representers](#example-representers)
+      - [Example Item](#example-item)
+      - [Example Cart](#example-cart)
+    - [Errors](#errors)
+    - [Change how URLs are presented](#change-how-urls-are-presented)
+      - [Override base URI mappings](#override-base-uri-mappings)
+      - [Override resource URI mappings](#override-resource-uri-mappings)
+    - [Designing Adapters](#designing-adapters)
+      - [Example: ActiveRecord Adapter](#example-activerecord-adapter)
+      - [Validations](#validations)
+- [Contributing](#contributing)
+- [Copyright and License](#copyright-and-license)
+
+## Demo
+
+See [grape-with-roar](https://github.com/ruby-grape/grape-with-roar).
+
+## Installation
 
 Add the `grape`, `roar` and `grape-roar` gems to Gemfile.
 
@@ -26,8 +49,7 @@ gem 'grape-roar'
 
 If you're upgrading from an older version of this gem, please see [UPGRADING](UPGRADING.md).
 
-Usage
------
+## Usage
 
 ### Tell your API to use Grape::Formatter::Roar
 
@@ -121,14 +143,229 @@ get 'products' do
 end
 ```
 
-Contributing
-------------
+### 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::Association::Referenced::HasOne, got Mongoid::Association::Referenced::HasMany!
+```
+
+#### 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
+        # at 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
 
 See [CONTRIBUTING](CONTRIBUTING.md).
 
-Copyright and License
----------------------
+## Copyright and License
 
 MIT License, see [LICENSE](LICENSE) for details.
 
-(c) 2012-2014 [Daniel Doubrovkine](https://github.com/dblock) & Contributors, [Artsy](https://artsy.net)
+(c) 2012-2025 [Daniel Doubrovkine](https://github.com/dblock) & Contributors, [Artsy](https://artsy.net)

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/grape-roar.gemspec

@@ -1,5 +1,6 @@
-# -*- encoding: utf-8 -*-
-require File.expand_path('../lib/grape/roar/version', __FILE__)
+# frozen_string_literal: true
+
+require File.expand_path('lib/grape/roar/version', __dir__)
 
 Gem::Specification.new do |gem|
   gem.authors       = ['Daniel Doubrovkine']
@@ -11,12 +12,13 @@ Gem::Specification.new do |gem|
 
   gem.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   gem.files         = `git ls-files`.split("\n")
-  gem.test_files    = `git ls-files -- {spec}/*`.split("\n")
   gem.name          = 'grape-roar'
   gem.require_paths = ['lib']
   gem.version       = Grape::Roar::VERSION
 
   gem.add_dependency 'grape'
+  gem.add_dependency 'multi_json'
   gem.add_dependency 'roar', '~> 1.1.0'
   gem.required_ruby_version = '>= 2.1.0'
+  gem.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/grape/roar/decorator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'roar/decorator'
 
 module Grape

data/lib/grape/roar/extensions/relations/adapters/active_record.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Grape
+  module Roar
+    module Extensions
+      module Relations
+        module Adapters
+          class ActiveRecord < Base
+            include Validations::ActiveRecord
+
+            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
+  end
+end

data/lib/grape/roar/extensions/relations/adapters/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Grape
+  module Roar
+    module Extensions
+      module Relations
+        module Adapters
+          class Base
+            class << self
+              def valid_for?(klass)
+                valid_proc.call(klass)
+              rescue StandardError
+                false
+              end
+
+              def valid_for(&block)
+                @valid_proc = block
+              end
+
+              private
+
+              attr_reader :valid_proc
+            end
+
+            def initialize(klass)
+              @klass = klass
+            end
+
+            def collection_methods
+              raise NotImplementedError
+            end
+
+            def name_for_represented(_represented)
+              raise NotImplementedError
+            end
+
+            def single_entity_methods
+              raise NotImplementedError
+            end
+
+            private
+
+            attr_reader :klass
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/roar/extensions/relations/adapters/mongoid.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Grape
+  module Roar
+    module Extensions
+      module Relations
+        module Adapters
+          class Mongoid < Base
+            include Validations::Mongoid
+
+            valid_for { |klass| klass < ::Mongoid::Document }
+
+            def collection_methods
+              @collection_methods ||= %i[
+                embeds_many has_many has_and_belongs_to_many
+              ]
+            end
+
+            def name_for_represented(represented)
+              klass_name = if represented.instance_of?(
+                ::Enumerable
+              )
+                             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 embeds_one]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/roar/extensions/relations/adapters.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'grape/roar/extensions/relations/adapters/base'
+require 'grape/roar/extensions/relations/adapters/active_record' if defined?(ActiveRecord)
+require 'grape/roar/extensions/relations/adapters/mongoid' if defined?(Mongoid)
+
+module Grape
+  module Roar
+    module Extensions
+      module Relations
+        module Adapters
+          def self.for(klass)
+            (constants - [:Base]).inject(nil) do |m, c|
+              obj = const_get(c)
+              obj.valid_for?(klass) ? obj.new(klass) : m
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/roar/extensions/relations/dsl_methods.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Grape
+  module Roar
+    module Extensions
+      module Relations
+        module DSLMethods
+          def link_relation(relation, is_collection = false, dsl = self)
+            send(is_collection ? :links : :link, relation) do |opts|
+              data = represented.send(relation)
+
+              mapped = Array.wrap(data).map do |object|
+                href = [dsl.map_base_url.call(opts),
+                        dsl.map_resource_path.call(opts, object, relation)].join('/')
+
+                is_collection ? { href: href } : href
+              end
+
+              is_collection ? mapped : mapped.first
+            end
+          end
+
+          def link_self
+            relational_mapper[:self] = { relation_kind: :self }
+          end
+
+          def map_base_url(&block)
+            @map_base_url ||= if block.nil?
+                                proc do |opts|
+                                  request = Grape::Request.new(opts[:env])
+                                  "#{request.base_url}#{request.script_name}"
+                                end
+                              else
+                                block
+                              end
+          end
+
+          def map_self_url(dsl = self)
+            link :self do |opts|
+              resource_path = dsl.name_for_represented(represented)
+              [dsl.map_base_url.call(opts),
+               "#{resource_path}/#{represented.try(:id)}"].join('/')
+            end
+          end
+
+          def map_resource_path(&block)
+            @map_resource_path ||= if block.nil?
+                                     proc do |_opts, object, relation_name|
+                                       "#{relation_name}/#{object.id}"
+                                     end
+                                   else
+                                     block
+                                   end
+          end
+
+          def name_for_represented(represented)
+            relational_mapper.adapter.name_for_represented(represented)
+          end
+
+          def relation(relation_kind, rname, opts = {})
+            relational_mapper[rname] = opts.merge(relation_kind: relation_kind)
+          end
+
+          def represent(object, _options)
+            object.extend(self) unless is_a?(Class)
+            map_relations(object) unless relations_mapped
+            is_a?(Class) ? super : object
+          end
+
+          private
+
+          attr_reader :relations_mapped
+
+          def map_relations(object)
+            relational_mapper.decorate(object.class)
+            @relations_mapped = true
+          end
+
+          def relational_mapper
+            @relational_mapper ||= Mapper.new(self)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape/roar/extensions/relations/exceptions.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Grape
+  module Roar
+    module Extensions
+      module Relations
+        module Exceptions
+          class InvalidRelationError < StandardError; end
+          class UnsupportedRelationError < StandardError; end
+        end
+      end
+    end
+  end
+end

data/lib/grape/roar/extensions/relations/mapper.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Grape
+  module Roar
+    module Extensions
+      module Relations
+        class Mapper
+          extend Forwardable
+
+          def initialize(entity)
+            @entity = entity
+            @config = {}
+          end
+
+          def adapter
+            @adapter ||= Adapters.for(model_klass)
+          end
+
+          def decorate(klass)
+            @model_klass = klass
+
+            config.each_pair do |relation, opts|
+              representer_for(relation.to_s, opts) unless opts.key(:extend)
+              map_relation(relation, opts)
+            end
+          end
+
+          def_delegators :@config, :[], :[]=
+
+          private
+
+          attr_reader :config, :entity, :model_klass
+
+          def find_representer(base, target_name, const)
+            const = base.const_get(const)
+            return false if const.nil? || !const.is_a?(Module)
+
+            (const < ::Roar::JSON::HAL) && const.name
+                                                .downcase
+                                                .include?(target_name.singularize)
+          end
+
+          def map_collection(relation, opts)
+            return entity.link_relation(relation, true) unless opts.fetch(:embedded, false)
+
+            entity.collection(relation, opts)
+          end
+
+          def map_relation(relation, opts)
+            map = if adapter.collection_methods.include?(opts[:relation_kind])
+                    :map_collection
+                  elsif adapter.single_entity_methods
+                               .include?(opts[:relation_kind]) || opts[:relation_kind] == :self
+                    :map_single_entity
+                  else
+                    raise Exceptions::UnsupportedRelationError,
+                          'No such relation supported'
+                  end
+
+            send(map, relation, opts)
+            validate_relation(relation, opts[:relation_kind])
+          end
+
+          def map_single_entity(relation, opts)
+            return entity.map_self_url if opts[:relation_kind] == :self
+            return entity.link_relation(relation) unless opts.fetch(:embedded, false)
+
+            entity.property(relation, opts)
+          end
+
+          def representer_for(relation, opts)
+            base_path = entity.name.deconstantize
+            base_path = base_path.empty? ? Object : base_path.safe_constantize
+            return if base_path.nil?
+
+            to_extend = base_path.constants
+                                 .find(&method(:find_representer).curry[
+                                   base_path, relation
+                                 ])
+
+            opts.merge!(extend: "#{base_path}::#{to_extend}".safe_constantize)
+          end
+
+          def validate_relation(relation, kind)
+            validator_method = "#{kind}_valid?"
+            return true unless adapter.respond_to?(validator_method)
+
+            adapter.send(validator_method, relation.to_s)
+          end
+        end
+      end
+    end
+  end
+end