jsonapi-scopes 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cef6f1279f2c02d4fa7c4672b6c74f7920c17875b05d2bad161d0e6c0776ce45
-  data.tar.gz: 0ffe8a25b91a4f5df7e58fa2cadc449912f654c3dddb9497403db5e66a8bffae
+  metadata.gz: 7de8095eaab5c863a6c9f5b400a7457cb89231751c5d1c7005a62b221e9399ad
+  data.tar.gz: b706f80a2097cc969e82b6a1b7894ce0ebc47dfa62dbacf5f5f44d167fbcfe00
 SHA512:
-  metadata.gz: b91918c357e2745abd0813d9b5ce181e8fd9e7262d000591fe5910cf2c3d97942ddc65fc659b00120abd89246d1e3b2e2075fe66d85091d0477fe5ea7617fd45
-  data.tar.gz: c6771c3aa0d76a0b4f176df986ca3bd556f6417723f6af5d6fcbc037415fce66333b8d56d163662c3093bbee5b70d42ea3e4b72b29acea29d4b03a30e06ae3d9
+  metadata.gz: ad5bf7eac4bb99005274a0d8d0fc83e87af270edea7af5b93666471fc8566d3d57a320e21e508c3680412b0d6566d7bde5416497e1020fdb7ff4b1ec8451cede
+  data.tar.gz: 14281865842d6ca46f28ee9c0ce6be5820a2f82fa2196df9ccfc28b7cd646e33015cb2bb9b685b661e59b968eaead5f3e9c674fd3b70ffea7f7a5bb326a7ead8

data/README.md

@@ -40,7 +40,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-You can use `apply_filter` in your controller to use the scopes defined with the previous `filter` method :
+You can use `apply_filter` in your controller to use the scopes defined with the previous `filter` method:
 
 ```ruby
 class ContactsController < ApplicationController
@@ -68,7 +68,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-You can use `apply_sort` in your controller :
+You can use `apply_sort` in your controller:
 
 ```ruby
 class ContactsController < ApplicationController
@@ -96,6 +96,50 @@ Or use negative sort `/contacts?sort=-firstname` to sort by firstname in `desc`
 You can even combine multiple sort `/contacts?sort=lastname,-firstname`
 
 
+### Included relationships
+This gem supports [request include params](https://jsonapi.org/format/#fetching-includes). It's very useful when you need to load related resources on client side.
+
+```ruby
+class Post < ActiveRecord::Base
+  include Jsonapi::Include
+
+  has_many :comments
+  belongs_to :author
+
+  allowed_includes 'comments', 'author.posts' # List of allowed includes
+end
+```
+
+You can use `apply_include` in your controller:
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts = Post.apply_include(params)
+  end
+end
+```
+
+`apply_include` accepts a second parameter to override data set with `allowed_includes` for a specific controller.
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts = Post.apply_sort(params, allowed: 'comments') # to allow only comments.
+    # Or @posts = Post.apply_sort(params, allowed: ['comments', 'author'])
+  end
+end
+```
+
+Then you can hit `/posts?include=comments`. You can even combine multiple includes like `/posts?include=comments,author`.
+
+The gem only handle `include` on the ActiveRecord level. If you want to serialize the data, you must do it in your controller.
+
+#### Nested relationships
+
+You can load nested relationships using the dot `.` notation:
+
+`/posts?include=author.posts`.
+
 ### Rescuing a Bad Request in Rails
 
 Jsonapi::scope raises a `Jsonapi::InvalidAttributeError` you can [rescue_from](https://guides.rubyonrails.org/action_controller_overview.html#rescue-from) in your `ApplicationController`.

data/lib/jsonapi/scopes.rb

@@ -3,3 +3,4 @@
 require 'jsonapi/exceptions'
 require 'jsonapi/scopes/filters'
 require 'jsonapi/scopes/sorts'
+require 'jsonapi/scopes/includes'

data/lib/jsonapi/scopes/includes.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jsonapi
+  module Include
+    extend ActiveSupport::Concern
+
+    included do
+      @allowed_includes ||= []
+    end
+
+    module ClassMethods
+      def allowed_includes(*fields)
+        @allowed_includes = fields
+      end
+
+      def apply_include(params = {}, options = { allowed: [] })
+        records = all
+        fields = params.dig(:include).to_s
+
+        return records if fields.blank?
+
+        allowed_fields = (Array.wrap(options[:allowed]).presence || @allowed_includes).map(&:to_s)
+
+        fields.split(',').each do |field|
+          raise InvalidAttributeError, "#{field} is not valid as include attribute." unless allowed_fields.include?(field)
+        end
+
+        records.includes(convert_includes_as_hash(fields))
+      end
+
+      private
+
+      def convert_includes_as_hash(includes)
+        includes.split(',').map(&:squish).each_with_object({}) do |value, hash|
+          params = value.split('.')
+          key = params.first.to_sym
+          hash[key] ||= {}
+
+          next if params.size <= 1
+
+          remaining_fields = params[1..-1].join('.')
+
+          hash[key].merge!(convert_includes_as_hash(remaining_fields))
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/scopes/version.rb

@@ -2,6 +2,6 @@
 
 module Jsonapi
   module Scopes
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-scopes
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Guillaume Briday
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-16 00:00:00.000000000 Z
+date: 2019-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -51,6 +51,7 @@ files:
 - lib/jsonapi/exceptions.rb
 - lib/jsonapi/scopes.rb
 - lib/jsonapi/scopes/filters.rb
+- lib/jsonapi/scopes/includes.rb
 - lib/jsonapi/scopes/sorts.rb
 - lib/jsonapi/scopes/version.rb
 homepage: https://github.com/guillaumebriday/jsonapi-scopes