index_query_builder 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8af5c5d595d2eadb2940a4f1aaea38103970502e
-  data.tar.gz: a7a3cec53023cfab0ca2fb6b3fd0f37d1c81a910
+  metadata.gz: 3ea38e4a701413196312ab11d0477be169272c3b
+  data.tar.gz: 59431b3ac8e08468b91469a04eb79206355093a7
 SHA512:
-  metadata.gz: ca1644edcd841d1acd9b393538959bab3c5df58eababc66db5d8780ec32c4edf60c1b25cd4ae2f89d5e364af75a568b09b8c5c026c46d2deef7b1f06d8a27506
-  data.tar.gz: 559fa403af8cf4f64845f49d0c8f858bd4ab10746a5297272344f0bbcf8eb4e95dcb5990d8cae03baba79eeee11f9c928a572d40deb4f7096e3f391188a39f9a
+  metadata.gz: a107eef8cd790695cf35a119e4e145a28bc312d5f20df41a90b62926231d99c22182487b0b6ba4b4f3c31f39f093e629fb5cc2f97a508d37cd8c3781a7ecff2e
+  data.tar.gz: 55ce20fbdda01589d68161cb43164aeb1ea7c3deb958c910c14d33d80579fb3cb61fff6494358a8b09eb8e650ee98afdb33eff29701257a5c6406de8bebc633d

data/.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

data/.gitignore

@@ -48,3 +48,5 @@ build-iPhoneSimulator/
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
+
+config/database.yml

data/.rspec

@@ -0,0 +1 @@
+--colour

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    index_query_builder (0.0.1)
+    index_query_builder (0.0.2)
 
 GEM
   remote: https://rubygems.org/
@@ -49,13 +49,13 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  activerecord (~> 4.0.0)
-  activesupport (~> 4.0.0)
+  activerecord (~> 4.0, >= 4.0.0)
+  activesupport (~> 4.0, >= 4.0.0)
   bundler (~> 1.7)
   index_query_builder!
   pg (~> 0.18.1)
   rake (~> 10.0)
-  rspec (~> 3.3.0)
+  rspec (~> 3.3, >= 3.3.0)
 
 BUNDLED WITH
-   1.11.2
+   1.12.5

data/README.md

@@ -1,6 +1,6 @@
 # IndexQueryBuilder
 
-TODO: Write a gem description
+This gem provides a DSL on top of ActiveRecord to get collection of models for index pages with filters.
 
 ## Installation
 
@@ -20,17 +20,93 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Let's say you have the following schema:
+
+```ruby
+create_table :posts, force: true do |t|
+  t.text :title
+  t.integer :view_count
+end
+
+create_table :comments, force: true do |t|
+  t.integer :post_id
+  t.text :text
+end
+```
+
+And the following models
+
+```ruby
+class Post < ActiveRecord::Base
+  has_many :comments
+end
+
+class Comment < ActiveRecord::Base
+  belongs_to :post
+end
+```
+
+And you are building an index page for posts with the following requirements:
+* Posts should be ordered by `view_count`.
+* The user should be able to filter posts by texts in post's comments. For example, if `filters` is `{ comment_text: 'This post is amazing' }`, then we should return all the posts with a comment containing `'This post is amazing'`.
+* More filters will be added soon.
+
+Without Index Query Builder, you will probably have to do something like this.
+
+```ruby
+conditions_strings = []
+conditions_params = {}
+
+unless filters[:comment_text].blank?
+  conditions_strings << "comments.text ILIKE :comment_text"
+  conditions_params[:comment_text] = "%#{filters[:comment_text]}%"
+end
+
+conditions = (conditions_params.empty? ? "" : [conditions_strings.join(" AND "), conditions_params])
+
+joins_list = []
+joins_list << {:posts => :comment} if filters[:comment_text].present?
+
+posts = Post.where(conditions).joins(joins_list).order("expected_ship_at desc, id desc")
+```
+
+Or, with Index Query Builder, you can just write this.
+
+```ruby
+posts = IndexQueryBuilder.query Post, with: filters do |query|
+  query.filter_field [:comments, :text], contains: :comment_text
+  query.order_by "view_count DESC"
+end
+```
+
+## Operators
+
+Operators will apply where clauses to query *only if* the filter_name is present in filters hash.
+
+* :equal_to applies field_name = filter_value
+* :contains applies substring (ILIKE '%filter_value%')
+* :greater_than_or_equal_to applies field_name >= filter_value
+* :less_than applies field_name < filter_value
+* :present_if applies:
+    * field_name IS NOT NULL if filter_value
+    * field_name IS NULL if !filter_value
+
+Find more in the [docs](http://www.rubydoc.info/gems/index_query_builder)
 
 ## Running tests
 
-    $ cd bounded_contexts/index_query_builder
+It requires PostgreSQL.
+
+    $ cp config/database.yml.sample config/database.yml
+
+Update `config/database.yml` with your connection information.
+
     $ rake db:test:setup
     $ rspec
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/index_query_builder/fork )
+1. Fork it ( https://github.com/arturopie/index_query_builder/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/index_query_builder.rb

@@ -6,8 +6,8 @@ require "index_query_builder/version"
 
 # Simple DSL for building queries using filters.
 #
-#   This module makes it easy to fetch records from the database, specially
-#   for showing and filtering records in an index page
+# This module makes it easy to fetch records from the database, specially
+# for showing and filtering records in an index page
 #
 module IndexQueryBuilder
 
@@ -16,21 +16,20 @@ module IndexQueryBuilder
   # @param base_scope [Arel] used to build query on top of this scope
   # @param options [Hash]
   # @option :with [Hash] filters used to build query. Key is filter name, value is value for the filter
-  # @param &block yield to build query using IndexQueryBuilder's DSL
+  # @yield [QueryDefinition] Gives a QueryDefinition object that implements a DSL to define how to apply filters
   # @return [Arel] returns arel object to make it easy to extend query (e.g. add pagination, etc)
   #
   # ==== Example
   #
-  # receive_orders = IndexQueryBuilder.query ReceiveOrder.where(:site_id => site.id), with: { sku_code: 'ABC' } do |query|
-  #   query.filter_field :received
-  #   query.filter_field :reference, contains: :reference
-  #   query.filter_field :expected_delivery_at,
-  #     greater_than_or_equal_to: :from_expected_delivery_at, less_than: :to_expected_delivery_at
-  #   query.filter_field [:receive_order_items, :sku, :code], equal_to: :sku_code
-  #
-  #   query.order_by "expected_delivery_at DESC, receive_orders.id DESC"
-  # end
+  #   posts = IndexQueryBuilder.query Post.where(:user_id => user.id), with: { title: 'DSLs are awesome' } do |query|
+  #     query.filter_field :posted
+  #     query.filter_field :title, contains: :title
+  #     query.filter_field :posted_date,
+  #       greater_than_or_equal_to: :from_posted_date, less_than: :to_posted_date
+  #     query.filter_field [:comments, :author, :name], equal_to: :comment_author_name
   #
+  #     query.order_by "posted_date DESC, posts.created_at DESC"
+  #   end
   def self.query(base_scope, options={}, &block)
     query_definition = QueryDefinition.new
     block.call(query_definition)
@@ -46,21 +45,20 @@ module IndexQueryBuilder
   # @param base_scope [Arel] used to build query on top of this scope
   # @param options [Hash]
   # @option options [Hash] :with filters used to build query. Key is filter name, value is value for the filter
-  # @param &block yield to build query using IndexQueryBuilder's DSL
+  # @yield [QueryDefinition] Gives a QueryDefinition object that implements a DSL to define how to apply filters
   # @return [Arel] returns arel object to make it easy to extend query (e.g. add pagination, etc)
   #
   # ==== Example
   #
-  # receive_order_items = IndexQueryBuilder.query_children :receive_order_items, ReceiveOrder.scoped_by(site), with: filters do |query|
-  #   query.filter_field :received
-  #   query.filter_field :reference, contains: :reference
-  #   query.filter_field :expected_delivery_at,
-  #     greater_than_or_equal_to: :from_expected_delivery_at, less_than: :to_expected_delivery_at
-  #   query.filter_field [:receive_order_items, :sku, :code], equal_to: :sku_code
-  #
-  #   query.order_by "expected_delivery_at DESC, receive_orders.id DESC"
-  # end
+  #   comments = IndexQueryBuilder.query_children :comments, Comments, with: { title: 'DSLs are awesome' } do |query|
+  #     query.filter_field :posted
+  #     query.filter_field :title, contains: :title
+  #     query.filter_field :posted_date,
+  #       greater_than_or_equal_to: :from_posted_date, less_than: :to_posted_date
+  #     query.filter_field [:comments, :author, :name], equal_to: :comment_author_name
   #
+  #     query.order_by "comment_date DESC"
+  #   end
   def self.query_children(child_association, base_scope, options={}, &block)
     parents = query(base_scope.eager_load(child_association), options, &block)
 

data/lib/index_query_builder/query_definition.rb

@@ -18,30 +18,30 @@ module IndexQueryBuilder
     #
     # ==== Operators
     #
-    # Operators will apply where clauses to query *only if* the filter_name is present in filters hash.
+    # Operators will apply where clauses to query only if the filter_name is present in filters hash.
     #
     # [:equal_to]
-    #   Applies field_name = filter_value
+    #   Applies 'field_name = filter_value'
     # [:contains]
     #   Applies substring (ILIKE '%filter_value%')
     # [:greater_than_or_equal_to]
-    #   Applies field_name >= filter_value
+    #   Applies 'field_name >= filter_value'
     # [:less_than]
-    #   Applies field_name < filter_value
+    #   Applies 'field_name < filter_value'
     # [:present_if]
     #   Applies
-    #     field_name IS NOT NULL if filter_value
-    #     field_name IS NULL if filter_value
+    #   * 'field_name IS NOT NULL' if filter_value is truthy
+    #   * 'field_name IS NULL' if filter_value is falsey
     #
     # === Examples
     #
-    # <tt>query.filter_field :received</tt>
-    # <tt>query.filter_field :reference, contains: :reference</tt>
-    # <tt>query.filter_field [:vendor, :name], equal_to: :vendor_name</tt>
-    # <tt>query.filter_field [:receive_order_items, :sku, :code], equal_to: :sku_code</tt>
-    # <tt>query.filter_field :expected_delivery_at, greater_than_or_equal_to: :from_expected_delivery_at, less_than: :to_expected_delivery_at</tt>
-    # <tt>query.filter_field :expected_delivery_at, less_than_or_equal_to: :to_expected_delivery_at</tt>
-    # <tt>query.filter_field :outbound_trailer_id, present_if: :has_trailer</tt>
+    #   query.filter_field :received
+    #   query.filter_field :reference, contains: :reference
+    #   query.filter_field [:vendor, :name], equal_to: :vendor_name
+    #   query.filter_field [:receive_order_items, :sku, :code], equal_to: :sku_code
+    #   query.filter_field :expected_delivery_at, greater_than_or_equal_to: :from_expected_delivery_at, less_than: :to_expected_delivery_at
+    #   query.filter_field :expected_delivery_at, less_than_or_equal_to: :to_expected_delivery_at
+    #   query.filter_field :outbound_trailer_id, present_if: :has_trailer
     #
     def filter_field(field_name, predicates={equal_to: field_name})
       predicates.each do |operator, filter|

data/lib/index_query_builder/version.rb

@@ -1,3 +1,3 @@
 module IndexQueryBuilder
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/index_query_builder_spec.rb

@@ -4,15 +4,15 @@ require 'integration_spec_helper'
 RSpec.describe IndexQueryBuilder do
   describe 'operator :contains' do
     it 'returns records containing filter value' do
-      Post.create!(title: "Using Rubymine because it's awesome")
-      Post.create!(title: "VIM is useless")
+      Post.create!(title: "This is a post I love")
+      Post.create!(title: "This is another post")
 
-      posts = IndexQueryBuilder.query Post.where(nil), with: { title: 'Rubymine' } do |query|
+      posts = IndexQueryBuilder.query Post.where(nil), with: { title: 'love' } do |query|
         query.filter_field :title, contains: :title
       end
 
       expect(posts.length).to eq(1)
-      expect(posts[0].title).to eq("Using Rubymine because it's awesome")
+      expect(posts[0].title).to eq("This is a post I love")
     end
 
     it 'filters using association' do
@@ -28,15 +28,15 @@ RSpec.describe IndexQueryBuilder do
 
   describe 'operator :equal_to' do
     it 'returns records equal to filter value' do
-      Post.create!(title: "Using Rubymine because it's awesome")
-      Post.create!(title: "VIM is useless")
+      Post.create!(title: "This is a post I love")
+      Post.create!(title: "This is another post")
 
-      posts = IndexQueryBuilder.query Post.where(nil), with: { title: "Using Rubymine because it's awesome" } do |query|
+      posts = IndexQueryBuilder.query Post.where(nil), with: { title: "This is a post I love" } do |query|
         query.filter_field :title, equal_to: :title
       end
 
       expect(posts.length).to eq(1)
-      expect(posts[0].title).to eq("Using Rubymine because it's awesome")
+      expect(posts[0].title).to eq("This is a post I love")
     end
 
     it 'filters using association' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: index_query_builder
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Arturo Pie
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-09 00:00:00.000000000 Z
+date: 2016-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -120,12 +120,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".editorconfig"
 - ".gitignore"
+- ".rspec"
 - Gemfile
 - Gemfile.lock
 - README.md
 - Rakefile
-- config/database.yml
+- config/database.yml.sample
 - index_query_builder.gemspec
 - lib/index_query_builder.rb
 - lib/index_query_builder/query_builder.rb