elasticsearch_query 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e046e13523ec5f641a624c51a7676c0407e53985
-  data.tar.gz: 5049e0aea93d2b18077b63c6c7af875eadd7568d
+  metadata.gz: 1abd0e1f72b653412d2ec2ef4f290369791e5a2d
+  data.tar.gz: 35edb681d3dd0f024b5ea6c5d6c2a14432365a1e
 SHA512:
-  metadata.gz: 1c597f1a86af453cd714ccb25c0e67da3db35875162caca2b6a66f0d186815192175c2429f0cf4d6f8528b588b4580ebf0f42183479a4b65847147d3b041d35a
-  data.tar.gz: 380550d41d26078648f5ad92133d5a662f2ee5158dfc73464846c7f6167a1718be51584c9356b18cf3a138ec14b577323688bd459d557c90bcceb6e36360ed04
+  metadata.gz: 4965a348cc695976ba36d96c36c19344037071933fc87b04177198a2465b06e21e2444b47094a282da2fda670d5ecb1074c7bf7274a6527b94d0624f6e3e49a2
+  data.tar.gz: 0ec0f9e80067bda0b510cdec72ca8b8b954d84189f06375a8e4df66f6f67b206925314dcab54666ebdf199e1ba9c18e9cf2a9ede4ccb3f77ad57a04cd1293be5

data/README.md

@@ -1,8 +1,8 @@
 # ElasticsearchQuery
 
-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/elasticsearch_query`. To experiment with that code, run `bin/console` for an interactive prompt.
+`ElasticsearchQuery` is a tranformer from [`JSONAPI`](http://jsonapi.org) style params hash into an [`Elasticseatch-ruby`](https://github.com/elastic/elasticsearch-ruby)-compatible object that can easily be fed into `client.search`
 
-TODO: Delete this and the text above, and describe your gem
+*Note*: This gem was written for use with a [modified](https://github.com/tiagopog/jsonapi-utils/pull/90) [`JSONAPI::Utils`](https://github.com/tiagopog/jsonapi-utils/) and uses several concepts from it (Paginator interface, param structure), but has no hard dependencies.
 
 ## Installation
 
@@ -22,7 +22,79 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Using the gem is pretty strightforward. You have to set up 2 things: the paginator, and the range parser (if your API accepts range filters)
+
+*NOTE*: This gem assumes that params come in the form of
+```ruby
+{
+  filter: { key: :value },
+  sort: "sort,-other_sort"
+}.merge( your_pagination_format_here )
+```
+
+### Example
+
+If you are using the above mentioned [modified `JSONAPI::Utils`](https://github.com/tiagopog/jsonapi-utils/pull/90), Your controller action would look like:
+
+```ruby
+class MyApiController < ApplicationController
+  def index
+    # to_unsafe_h is here in order to support any version of rails/other frameworks that just get a hash for params
+    @results = MyModel.search_from_params( params.to_unsafe_h )
+    jsonapi_render json: @results
+  end
+end
+```
+
+### Configuration
+
+As mentioned earlier the config is assignment of a paginator class (required) and a range formatter class (optional)
+
+```ruby
+# in your config/initializers/elasticsearch_query.rb
+ElasticsearchQuery::Query.paginator_class = MyPaginator
+ElasticsearchQuery::FilterFormatter::Range.parser = MyRangeParser
+```
+
+#### Paginator
+
+Most APIs want paged results. But since your interface is your own and not super relevant to how the query is contructed, it needs to duck the following type:
+
+```ruby
+class MyPaginator
+  def initialize( params )
+    @params = params
+  end
+
+  def to_hash
+    { size: size,
+      from: from }
+  end
+end
+```
+
+What the params look like and how you extract the page size and offset(`from`) are up to you. 
+
+#### RangeFormatter
+
+If your API has values that are filterable by range (e.g. `created_at`) `ElasticsearchQuery` can supprt those values; all you have to do is set up how to parse the parameter.
+
+```ruby
+class MyRangeParser
+  def initialize( value )
+    @value = value
+  end
+
+  # if your values come in as beginning-to-end for some reason
+  def parse
+    value.split "-to-"
+  end
+end
+```
+
+The result of `MyRangeParser#parse` method **MUST** respond to `#first` and `#last`, so things like `Array` and `Range` are great things to return, but if yoiu want to roll your own, have at it.
+
+*Note*: This gem assumes that infinity and negative infinity are represented as `inf` and `neginf`. 
 
 ## Development
 
@@ -32,7 +104,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/elasticsearch_query. 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/gaorlov/elasticsearch_query. 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
 
@@ -40,4 +112,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the ElasticsearchQuery project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/elasticsearch_query/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the ElasticsearchQuery project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/gaorlov/elasticsearch_query/blob/master/CODE_OF_CONDUCT.md).

data/lib/elasticsearch_query/sort.rb

@@ -1,8 +1,7 @@
 module ElasticsearchQuery
   class Sort
-    def initialize( params = {}, default = "" )
+    def initialize( params = {} )
       @params  = params
-      @default = default
     end
 
     def to_hash
@@ -18,11 +17,11 @@ module ElasticsearchQuery
 
     def sorts
       @sorts ||= begin
-        sorts = @params.fetch( :sort, @default ).split(',')
+        sorts = @params.fetch( :sort, "" ).split(',')
 
         sorts.each_with_object([]) do |field, arr|
           desc, field   = field.match(/^([-_])?(\w+)$/i)[1..2]
-          arr << { field => desc&.empty? ? :asc : :desc }
+          arr << { field => desc ? :desc : :asc }
         end
       end
     end

data/lib/elasticsearch_query/version.rb

@@ -1,3 +1,3 @@
 module ElasticsearchQuery
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: elasticsearch_query
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Greg Orlov