yaqb 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52b5538714ede2b23c96104bb339eddac611bfdf8562c648bb29094840c409e7
-  data.tar.gz: 78c09abab32cf2a75b1533cde2937d28dbea1bd86c9918fcd5b362bccf3eb29b
+  metadata.gz: 21e2ed937f7b14a5ab0dfcb64a183e1d4cc127ae194fc38482e1dec50b217a08
+  data.tar.gz: 924a57354b4b4e6934aaaf3455aa4fab0aec368c5f2fae1085c59a49344d3648
 SHA512:
-  metadata.gz: b4a0aa3013b84a22f77b41e8b8d80a677cf96ded8e901635a8d683bc551d3c6b9a620a57e77e4c7df1b871b29046e4e2cb6b2dba2cb4ee82fc0fbf423f844d71
-  data.tar.gz: 7e1a4174fae0e07b22d5b601f57652fd8e2b0564af1422b7c488904b8c78c078a2ac44e3558f2177ed647a250fc31a4200c90a54e73cbe2b71e8080e21e29d83
+  metadata.gz: 7bdfcdf4eede2b9df3e2520a64d825346c58b121e0dbd0495af39d4f9601232594090a770928bd956614e952fe2790e707c45675f9ce35daf3ba67d8961f9834
+  data.tar.gz: abca46cd2bfbd8e02bfbbfe5e8f31313e0511e29f70448cffb95c55b0720e79cc886a758e245ac643b5fde4d79539ac936b84a94eb1f86d61674c601c7592ed7

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    yaqb (0.5.0)
+    yaqb (0.5.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,14 +1,21 @@
 # Yaqb
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/yaqb`. To experiment with that code, run `bin/console` for an interactive prompt.
+#### Yet Another Query Builder
+Yaqb is query builder that will filter, sort and paginate your ActiveRecord collections.
 
-TODO: Delete this and the text above, and describe your gem
+In addition to query building, presenters are used to manage what a consumer of your API can query.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+In your Gemfile
 
 ```ruby
+# Choose your preferred pagination gem
+gem 'kaminari' # or
+gem 'will_paginate' # or
+gem 'pagy'
+
+# Then add
 gem 'yaqb'
 ```
 
@@ -20,9 +27,76 @@ Or install it yourself as:
 
     $ gem install yaqb
 
+## Configuration
+
+By default, Yaqb will detect if you are using Kaminari, WillPaginate, or Pagy. If you want to change any of the configurable settings, you may do so:
+
+```ruby
+Yaqb.configure do |config|
+  # If for whatever reason you are using multiple pagination gems, you can manually set which gem to use.
+  config.paginator = :kaminari # :will_paginate, :pagy
+end
+```
+
 ## Usage
 
-TODO: Write usage instructions here
+### Controllers
+
+In your controller, you will need to include the following the module: `Yaqb::Base`
+
+```ruby
+class ApplicationController < ActionController::Base # or ActionController::API
+  include Yaqb::Base
+end
+
+# And then to use Yaqb
+
+class BooksController < ApplicationController
+  def index
+    # #orchestrate expects a collection and a presenter.
+    # #orchestrate return a results object meaning you will have access to the following methods:
+    # #scope - This is your collection after being filtered, sorted and paginated
+    # #links - This returns a hash of links based on the paginated results.
+    result = orchestrate(Books.all, BookPresenter)
+
+    # Depending on your serializer you can render your data as so:
+    # BluePrinter gem by procore is being here:
+    render json: BookBlueprint.render(request.scope, root: :data, meta: { links: request.links })
+  end
+end
+```
+
+### Presenters
+
+Presenters will allow you to control what a consumer of your API can sort and filter by.
+
+Your Presenter class will need to inherit from `Yaqb::Presenter`
+
+```ruby
+class BookPresenter < Yaqb::Presenter
+  sort_by :id, :title, :created_at, :updated_at
+  filter_by :id, :title
+end
+```
+
+### Handling Errors
+
+By default Yaqb will rescue from `QueryBuilderError` and return that error to the consumer
+
+Given the following API call:
+
+`GET https://api.example.com/v1/books?per=a`
+
+The following response will be returned
+
+```json
+{
+  "error": {
+    "message": "Invalid pagination params. Only numbers are supported for \"page\" and \"per\"",
+    "invalid_params": "per=a"
+  }
+}
+```
 
 ## Development
 

data/lib/yaqb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yaqb
-  VERSION = '0.5.0'
+  VERSION = '0.5.1'
 end

data/yaqb.gemspec

@@ -19,6 +19,8 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.3.0'
   spec.requirements << 'Kaminari'
+  spec.requirements << 'WillPaginate'
+  spec.requirements << 'Pagy'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yaqb
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Ronald Chacon
@@ -122,6 +122,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - Kaminari
+- WillPaginate
+- Pagy
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4