jsonapi-scopes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d0e74cff9d6b5917c86fc154f8046fd388a843c451fa66b22d09332c6cc67a53
+  data.tar.gz: 76f8158ff9f126a0ef1ab84ee4bec8f82716ebf1c9dd5ec43894891db3be472e
+SHA512:
+  metadata.gz: 5555c208f5518bc0a8502e50eacf248f6f16844414838d6b43bcf156dabcdd3fe98d5600cea66b8bc1dbf794c6a194ff4052fd04932a85f244a989ee6598ffaa
+  data.tar.gz: dc3a47eedd3fcb472b702172f297a850156bd4e1e912fc4cb6d2db6b518397e39ee90ce26c5e8322c2a26b0bbb60487304f84b009523ce069f273c36daa9ec6c

data/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2019 Guillaume Briday
+
+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,96 @@
+[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/guillaumebriday)
+
+# Jsonapi::Scopes
+This gem provides an easy way to use a filter query parameter from the [jsonapi specification](https://jsonapi.org/recommendations/#filtering).
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jsonapi-scopes', git: 'https://github.com/guillaumebriday/jsonapi-scopes.git'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+## Usage
+
+### Filter
+The gem add a `filter` method to define public scopes.
+It acts as a regular scope.
+
+```ruby
+class Contact < ActiveRecord::Base
+  include Jsonapi::Filter
+
+  # Respond to `apply_filter`
+  filter :first_name, ->(value) {
+    where(first_name: value)
+  }
+
+  # Do NOT respond to `apply_filter`
+  scope :last_name, ->(value) {
+    where(last_name: value)
+  }
+end
+```
+
+You can use `apply_filter` in your controller to use the scopes defined with the previous `filter` method :
+
+```ruby
+class ContactsController < ApplicationController
+  def index
+    @contacts = Contact.apply_filter(params)
+  end
+end
+```
+
+Then you can hit `/contacts?filter[first_name]=Bruce` to filter contacts where the last name exactly match `Bruce`.
+
+But `/contacts?filter[last_name]=Wayne` will be completely ignored.
+
+### Sorting
+The gem add `default_sort` and `sortable_fields` methods to control sort options. **Both are optional** and can be overriding in controllers.
+
+```ruby
+class Contact < ActiveRecord::Base
+  include Jsonapi::Sort
+
+  sortable_fields :lastname, :firstname # List of allowed attributes
+  default_sort lastname: :desc, firstname: :asc # default hash with attributes and directions
+end
+```
+
+You can use `apply_sort` in your controller :
+
+```ruby
+class ContactsController < ApplicationController
+  def index
+    @contacts = Contact.apply_sort(params)
+  end
+end
+```
+
+`apply_sort` accepts a second parameter to override data set with `sortable_fields` and `default_sort` for a specific controller.
+```ruby
+class ContactsController < ApplicationController
+  def index
+    @contacts = Contact.apply_sort(params, allowed: :full_name, default: { full_name: :desc })
+    # Or @contacts = Contact.apply_sort(params, allowed: [:lastname, :full_name], default: { full_name: :desc })
+  end
+end
+```
+
+Then you can hit `/contacts?sort=lastname` to sort contacts by lastname.
+
+Or use negative sort `/contacts?sort=-firstname` to sort by firstname in `desc` direction.
+
+You can even combine multiple sort `/contacts?sort=lastname,-firstname`
+
+## Contributing
+Do not hesitate to contribute to the project by adapting or adding features ! Bug reports or pull requests are welcome.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Jsonapi::Scopes'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/lib/jsonapi/scopes.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'jsonapi/scopes/filters'
+require 'jsonapi/scopes/sorts'

data/lib/jsonapi/scopes/filters.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Jsonapi
+  module Filter
+    extend ActiveSupport::Concern
+
+    included do
+      @filters ||= []
+    end
+
+    module ClassMethods
+      attr_reader :filters
+
+      def filter(name, *args)
+        scope(name, *args)
+        @filters << name
+      end
+
+      def apply_filter(params)
+        records = self
+        filtering_params = params.dig(:filter) || {}
+
+        filtering_params.each do |key, value|
+          records = records.public_send(key, value) if @filters.include?(key.to_sym)
+        end
+
+        records
+      end
+    end
+  end
+end

data/lib/jsonapi/scopes/sorts.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Jsonapi
+  module Sort
+    extend ActiveSupport::Concern
+
+    included do
+      @sortable_fields ||= []
+      @default_sort ||= {}
+    end
+
+    module ClassMethods
+      def default_sort(sort)
+        @default_sort = sort
+      end
+
+      def sortable_fields(*fields)
+        @sortable_fields = fields
+      end
+
+      def apply_sort(params, options = { allowed: [], default: {} })
+        fields = params.dig(:sort)
+
+        allowed_fields = [options[:allowed]].flatten.presence || @sortable_fields
+        allowed_fields = allowed_fields.map(&:to_sym)
+
+        default_order = options[:default].presence || @default_sort
+        default_order = default_order.transform_keys(&:to_sym)
+
+        ordered_fields = convert_to_ordered_hash(fields)
+        filtered_fields = ordered_fields.select { |key, _| allowed_fields.include?(key) }
+
+        order = filtered_fields.presence || default_order
+
+        self.order(order)
+      end
+
+      private
+
+      def convert_to_ordered_hash(fields)
+        fields = fields.to_s.split(',').map(&:squish)
+
+        fields.each_with_object({}) do |field, hash|
+          if field.start_with?('-')
+            field = field[1..-1]
+            hash[field] = :desc
+          else
+            hash[field] = :asc
+          end
+        end.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/jsonapi/scopes/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jsonapi
+  module Scopes
+    VERSION = '0.1.0'
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: jsonapi-scopes
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Guillaume Briday
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-05-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  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: 
+email:
+- guillaumebriday@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/jsonapi/scopes.rb
+- lib/jsonapi/scopes/filters.rb
+- lib/jsonapi/scopes/sorts.rb
+- lib/jsonapi/scopes/version.rb
+homepage: https://github.com/guillaumebriday/jsonapi-scopes
+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: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: A gem to use filters and scopes for JSON:API.
+test_files: []