query_helper 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9748c7b95202e187a62f4e889db450dbd6a406aac6f342d6fb0ae5f532e77f98
-  data.tar.gz: bc3f05f3093a0730758d05d7fab7485960b4d0dfbd489982e3dbbe996f51fb15
+  metadata.gz: 93112cb7974e069da9db1dbf08d4a0f3511076a6991195e669747567f2d2caa7
+  data.tar.gz: a242199dcea3eaa67c50792cf0b76cbe9fc9826a81f231649c81120969923cc9
 SHA512:
-  metadata.gz: 833e99acbbac34e55b2c99c03977c707792c1e1ed1b86d65a347d2184c01f96894cc5e41c40dab0e81f4b7463511ab63cd1ade1d9f7b36a6b689a9bfcece5df7
-  data.tar.gz: 73ccb427fc984585951c099fd311ebe5f83ff20d927f6e196b69e0d5f899b7e55e42a027de87424c3e986b94e767aa3faceab106f8aacd07cae1341f6b78c79e
+  metadata.gz: ab24ee9a256fbb9282e3adbe79db6436235000a7be0e1f166b570d6b413c412a9f3e2d5b285938630671db1efadd7e4ed9bf13e4aa84326fb28efb060b4d2df7
+  data.tar.gz: c08788615159a1da5fb4a218095ca5b7497360dbf7a074522d9f5f46cdffcca96cb40b4b9ba27ce905112b909dae0de42e8682292af0f0840d807b32831456d0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    query_helper (0.0.0)
+    query_helper (0.1.0)
       activerecord (~> 5.0)
       activesupport (~> 5.0)
 

data/README.md

@@ -2,7 +2,7 @@
 [![TravisCI](https://travis-ci.org/iserve-products/query_helper.svg?branch=master)](https://travis-ci.org/iserve-products/query_helper)
 [![Gem Version](https://badge.fury.io/rb/query_helper.svg)](https://badge.fury.io/rb/query_helper)
 
-Ruby Gem developed and used at Pattern to paginate, sort, filter, and include associations on sql and active record queries.
+QueryHelper is a ruby gem used to paginate, sort, and filter your API calls in Ruby on Rails using URL params in your HTTP requests.  It currently only supports Postgres.  
 
 ## Installation
 
@@ -20,278 +20,118 @@ Or install it yourself as:
 
     $ gem install query_helper
 
-## Use
+## Quick Use
 
-### SQL Queries
+### Step 1: Update Base Controller to use the QueryHelper Concern
 
-#### Initialize
-
-To create a new sql query object run
-
-```ruby
-QueryHelper::Sql.new(
-  model:,             # required
-  query:,             # required
-  query_params: ,     # optional
-  column_mappings: ,  # optional
-  filters: ,          # optional
-  sorts: ,            # optional
-  page: ,             # optional
-  per_page: ,         # optional
-  single_record: ,    # optional, default: false
-  associations: ,     # optional
-  as_json_options: ,  # optional
-  run:                # optional, default: true
-)
-```
-
-The following arguments are accepted when creating a new objects
-
-<table>
-<tr>
-<th>Argument</th>
-<th>Description</th>
-<th>Example</th>
-</tr>
-<tr>
-<td>model</td>
-<td>the model to run the query against</td>
-<td>
-<pre lang="ruby">
-Parent
-</pre>
-</td>
-</tr>
-<tr>
-<td>query</td>
-<td>the custom sql string to be executed</td>
-<td>
-<pre lang="ruby">
-'select * from parents'
-</pre>
-</td>
-</tr>
-<tr>
-<td>query_params</td>
-<td>a hash of bind variables to be embedded into the sql query</td>
-<td>
-<pre lang="ruby">
-{
-  age: 20,
-  name: 'John'
-}
-</pre>
-</td>
-</tr>
-<tr>
-<td>column_mappings</td>
-<td>A hash that translates aliases to sql expressions</td>
-<td>
-<pre lang="ruby">
-{
-  "age" => "parents.age"
-  "children_count" => {
-    sql_expression: "count(children.id)",
-    aggregate: true
-  }
-}
-</pre>
-</td>
-</tr>
-<tr>
-<td>filters</td>
-<td>a list of filters in the form of `{"comparate_alias"=>{"operator_code"=>"value"}}`</td>
-<td>
-<pre lang="ruby">
-{
-  "age" => { "lt" => 100 },
-  "children_count" => { "gt" => 0 }
-}
-</pre>
-</td>
-</tr>
-<tr>
-<td>sorts</td>
-<td>a comma separated string with a list of sort values</td>
-<td>
-<pre lang="ruby">
-"age:desc,name:asc:lowercase"
-</pre>
-</td>
-</tr>
-<tr>
-<td>page</td>
-<td>the page you want returned</td>
-<td>
-<pre lang="ruby">
-5
-</pre>
-</td>
-</tr>
-<tr>
-<td>per_page</td>
-<td>the number of results per page</td>
-<td>
-<pre lang="ruby">
-20
-</pre>
-</td>
-</tr>
-<tr>
-<td>single_record</td>
-<td>whether or not you expect the record to return a single result, if toggled, only the first result will be returned</td>
-<td>
-<pre lang="ruby">
-false
-</pre>
-</td>
-</tr>
-<tr>
-<td>associations</td>
-<td>a list of activerecord associations you'd like included in the payload </td>
-<td>
-<pre lang="ruby">
-
-</pre>
-</td>
-</tr>
-<tr>
-<td>as_json_options</td>
-<td>a list of as_json options you'd like run before returning the payload</td>
-<td>
-<pre lang="ruby">
-
-</pre>
-</td>
-</tr>
-<tr>
-<td>run</td>
-<td>whether or not you'd like to run the query on initilization</td>
-<td>
-<pre lang="ruby">
-false
-</pre>
-</td>
-</tr>
-</table>
-
-### Active Record Queries
-
-To run an active record query execute
 ```ruby
-QueryHelper.run_active_record_query(active_record_call, query_helpers, valid_columns, single_record)
+class ApplicationController < ActionController::API
+  include QueryHelper::QueryHelperConcern
+  before_action :create_query_helper
+end
 ```
-active_record_call: Valid active record syntax (i.e. ```Object.where(state: 'Active')```)
-query_helpers: See docs below
-valid_columns: Default is [].  Pass in an array of columns you want to allow sorting and filtering on.
-single_record: Default is false.  Pass in true to format payload as a single object instead of a list of objects
 
+Adding this code creates a `QueryHelper` object preloaded with pagination, filtering, sorting, and association information included in the URL.  This object can be accessed by using the `@query_helper` instance variable from within your controllers.
 
-model: A valid ActiveRecord model
-query: A string containing your custom SQL query
-query_params: a symbolized hash of binds to be included in your SQL query
-query_helpers: See docs below
-valid_columns: Default is [].  Pass in an array of columns you want to allow sorting and filtering on.
-single_record: Default is false.  Pass in true to format payload as a single object instead of a list of objects
+### Step 2: Use QueryHelper to run active record and sql queries within your controller
 
-## Query Helpers
-query_helpers is a symbolized hash passed in with information about pagination, associations, filtering and sorting.
-
-### Pagination
-There are two pagination keys you can pass in as part of the query_helpers objects
+#### Active Record Example
 
 ```ruby
-{
-  page: 1,
-  per_page: 20
-}
-```
+class ResourceController < ApplicationController
 
-If at least one of these keys is present, paginated results will be returned.
+  def index
+    @query_helper.update(
+      model: UserNotificationSetting,
+      query: "select * from resources r where r.user_id = :user_id",
+      bind_variables: { user_id: current_user().id }
+    )
 
-### Sorting
-Sorting is controlled by the `sort` key in the query_helpers object
+    render json: @query_helper.results()
+  end
 
-```ruby
-{
-    sort: "column_name:sort_direction"
-}
+end
 ```
-Sort direction can be either asc or desc.  If you wish to lowercase string before sorting include the following:
+
+#### Raw SQL Example
+
 ```ruby
-{
-    sort: "name:desc:lowercase"
-}
+class ResourceController < ApplicationController
+
+  def index
+    @query_helper.query = Resource.all
+    render json: @query_helper.results()
+  end
+
+end
 ```
 
-### Filtering
-Filtering is controlled by the `filter` object in the query_helpers hash
+You can also use the `@query_helper.update()` method to update the QueryHelper with an ActiveRecord object
 
 ```ruby
-{
-  filter: {
-    "column_1" => {
-      "gte" => 20,
-      "lt" => 40
-    },
-    "column_2" => {
-      "eql" => "my_string"
-    },
-    "column_3" => {
-      "like" => "my_string%"
-    },
-    "column_4" => {
-      "in" => "item1,item2,item3"
-    }
-}
+@query_helper.update(
+  query: Resource.all
+)
 ```
 
-The following operator codes are valid
+### Step 3: Paginate, Sort, Filter, and Include Associations using URL params
 
-```
-“gte”: >=
-“lte”: <=
-“gt”: >
-“lt”: <
-“eql”: =
-“noteql”: !=
-"like": like
-“in”: in
-“notin” not in
-“null”: “is null” or “is not null” (pass in true or false as the value)
-```
+#### Pagination
 
-### Associations
+`page=1`
 
-To include associated objects in the payload, pass in the following as part of the query_helpers hash:
+`per_page=20`
 
-```ruby
-{
-  include: ['associated_object_1', 'associated_object_2']
-}
-```
+`http://www.example.com/resources?page=1&per_page=25`
 
-### Example
+#### Sorting
+
+`sort=column:direction`
+
+Single Sort: `http://www.example.com/resources?sort=resource_name:desc`
+
+Multiple Sorts: `http://www.example.com/resources?sort=resource_name:desc,resource_age:asc`
+
+Lowercase Sort: `http://www.example.com/resources?sort=resource_name:desc:lowercase`
+
+#### Filtering
+
+`filter[column][operator_code]=value`
+
+Single Filter: `http://www.example.com/resources?filter[resource_age][gt]=50`
+
+Multiple Filters: `http://www.example.com/resources?filter[resource_age][gt]=50&[resource_name][eql]=banana_resource`
+
+Operator Code | SQL Operator
+--- | ---
+gte | >=
+lte | <=
+gt | >
+lt | <
+eql | =
+noteql | !=
+like | like
+in | in
+notin | not in
+null | is null *or* is not null
+
+Note: For the null operator code, toggle *is null* operator with true and *is not null* operator with false
+
+#### Associations
+
+Include ActiveRecord associations in the payload.  The association must be defined in the model.
+
+`include=association`
+
+Single Association: `http://www.example.com/resources?include=child_resource`
+
+Multiple Associations: `http://www.example.com/resources?include[]=child_resource&include[]=parent_resource`
 
-The following is an example of a query_helpers object that can be passed into the sql and active record methods
 
-```ruby
-query_helpers = {
-  page: 1,
-  per_page: 20,
-  sort: "name:desc"
-  include: ["child"]
-  filter: {
-    "id" => {
-      "gte" => 20,
-      "lt" => 40
-    }
-}
-```
 
 ## Payload Formats
 
-The QueryHelper gem will return results in one of three formats
+The QueryHelper gem will return the following payload
 
 ### Paginated List Payload
 ```json
@@ -330,30 +170,39 @@ The QueryHelper gem will return results in one of three formats
 }
 ```
 
-### List Payload
-```json
-{
-  "data": [
-    {
-      "id": 1,
-      "attribute_1": "string_attribute",
-      "attribute_2": 12345,
-      "attribute_3": 0.3423212
-    },
-    {
-      "id": 2,
-      "attribute_1": "string_attribute",
-      "attribute_2": 12345,
-      "attribute_3": 0.3423212
-    },
-    {
-      "id": 3,
-      "attribute_1": "string_attribute",
-      "attribute_2": 12345,
-      "attribute_3": 0.3423212
-    },
-  ]
-}
+## Advanced Options
+
+### Associations
+
+You can preload additional and include additional associations in your payload besides what's defined in the `include` url parameter.
+
+```ruby
+@query_helper.update(
+  associations: ['association1']
+)
+```
+
+### as_json options
+
+You can pass in additional as_json options to be included in the payload.
+
+```ruby
+@query_helper.update(
+  as_json_options: { methods: [:last_ran_at] }
+)
+```
+
+### Single Record Queries
+If you only want to return a single result, but still want to be able to use some of the other functionality of QueryHelper, you can set `single_record` to true in the QueryHelper object.
+
+```ruby
+@query_helper.single_record = true
+```
+or
+```ruby
+@query_helper.update(
+  single_record: true
+)
 ```
 
 ### Single Record Payload
@@ -370,7 +219,7 @@ The QueryHelper gem will return results in one of three formats
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/query_helper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/iserve_products/query_helper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 

data/lib/query_helper/filter.rb

@@ -70,10 +70,13 @@ class QueryHelper
 
     def mofify_criterion
       # lowercase strings for comparison
-      @criterion.downcase! if criterion.class == String && criterion.scan(/[a-zA-Z]/).any?
+      @criterion.downcase! if @criterion.class == String && @criterion.scan(/[a-zA-Z]/).any?
 
       # turn the criterion into an array for in and notin comparisons
-      @criterion = criterion.split(",") if ["in", "notin"].include?(operator_code) && criterion.class == String
+      @criterion = @criterion.split(",") if ["in", "notin"].include?(@operator_code) && @criterion.class == String
+
+      # Add wildcards for like comparisons
+      @criterion = "%#{@criterion}%" if @operator_code == "like"
     end
 
     def modify_comparate

data/lib/query_helper/query_helper_concern.rb

@@ -1,5 +1,4 @@
 require 'active_support/concern'
-require "query_helper/sql_filter"
 
 class QueryHelper
   module QueryHelperConcern
@@ -24,7 +23,7 @@ class QueryHelper
       end
 
       def create_query_helper_associations
-
+        QueryHelper::Associations.process_association_params(params[:include])
       end
 
       def query_helper_params

data/lib/query_helper/sql_manipulator.rb

@@ -10,7 +10,8 @@ class QueryHelper
       where_clauses: nil,
       having_clauses: nil,
       order_by_clauses: nil,
-      include_limit_clause: false
+      include_limit_clause: false,
+      additional_select_clauses: []
     )
       @parser = SqlParser.new(sql)
       @sql = @parser.sql.dup
@@ -18,23 +19,23 @@ class QueryHelper
       @having_clauses = having_clauses
       @order_by_clauses = order_by_clauses
       @include_limit_clause = include_limit_clause
+      @additional_select_clauses = additional_select_clauses
     end
 
     def build
       insert_having_clauses()
       insert_where_clauses()
-      insert_total_count_select_clause()
+      insert_select_clauses()
       insert_order_by_and_limit_clause()
       @sql.squish
     end
 
     private
 
-    def insert_total_count_select_clause
-      return unless @include_limit_clause
-      total_count_clause = " ,count(*) over () as _query_full_count "
-      @sql.insert(@parser.insert_select_index, total_count_clause)
-      # Potentially update parser here
+    def insert_select_clauses
+      total_count_clause = "count(*) over () as _query_full_count"
+      @additional_select_clauses << total_count_clause if @include_limit_clause
+      @sql.insert(@parser.insert_select_index, " , #{@additional_select_clauses.join(", ")} ") if @additional_select_clauses.length > 0
     end
 
     def insert_where_clauses

data/lib/query_helper/sql_sort.rb

@@ -3,11 +3,12 @@ require "query_helper/invalid_query_error"
 class QueryHelper
   class SqlSort
 
-    attr_accessor :column_maps
+    attr_accessor :column_maps, :select_strings
 
     def initialize(sort_string: "", column_maps: [])
       @sort_string = sort_string
       @column_maps = column_maps
+      @select_strings = []
     end
 
     def parse_sort_string
@@ -38,6 +39,8 @@ class QueryHelper
         case modifier
         when "lowercase"
           sql_expression = "lower(#{sql_expression})"
+          # When select distincts are used, the order by clause must be included in the select clause
+          @select_strings << sql_expression
         end
 
         sql_strings << "#{sql_expression} #{direction}"

data/lib/query_helper/version.rb

@@ -1,3 +1,3 @@
 class QueryHelper
-  VERSION = "0.0.0"
+  VERSION = "0.1.0"
 end

data/lib/query_helper.rb

@@ -24,7 +24,7 @@ class QueryHelper
     page: nil, # define the page you want returned
     per_page: nil, # define how many results you want per page
     single_record: false, # whether or not you expect the record to return a single result, if toggled, only the first result will be returned
-    associations: nil, # a list of activerecord associations you'd like included in the payload
+    associations: [], # a list of activerecord associations you'd like included in the payload
     as_json_options: nil, # a list of as_json options you'd like run before returning the payload
     custom_mappings: {}, # custom keyword => sql_expression mappings
     api_payload: false # Return the paginated payload or simply return the result array
@@ -52,10 +52,24 @@ class QueryHelper
     end
   end
 
-  def update_query(query: nil, model:nil, bind_variables: {})
+  def update(
+    query: nil,
+    model: nil,
+    bind_variables: {},
+    filters: [],
+    associations: [],
+    as_json_options: nil,
+    single_record: nil,
+    custom_mappings: nil
+  )
     @model = model if model
     @query = query if query
     @bind_variables.merge!(bind_variables)
+    filters.each{ |f| add_filter(**f) }
+    @associations = @associations | associations
+    @single_record = single_record if single_record
+    @as_json_options = as_json_options if as_json_options
+    @custom_mappings = custom_mappings if custom_mappings
   end
 
   def add_filter(operator_code:, criterion:, comparate:)
@@ -68,6 +82,7 @@ class QueryHelper
 
     # Create column maps to be used by the filter and sort objects
     column_maps = create_column_maps()
+
     @sql_filter.column_maps = column_maps
     @sql_sort.column_maps = column_maps
 
@@ -83,7 +98,8 @@ class QueryHelper
       where_clauses: @sql_filter.where_clauses,
       having_clauses:  @sql_filter.having_clauses,
       order_by_clauses: @sql_sort.parse_sort_string,
-      include_limit_clause: @page && @per_page ? true : false
+      include_limit_clause: @page && @per_page ? true : false,
+      additional_select_clauses:  @sql_sort.select_strings
     )
     @executed_query = manipulator.build()
     @results = @model.find_by_sql([@executed_query, @bind_variables]) # Execute Sql Query

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: query_helper
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Evan McDaniel
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-23 00:00:00.000000000 Z
+date: 2019-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler