parelation 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 037f22447840bf0175afad3ffc9877399f52e45a
+  data.tar.gz: 245f4049e008a44245cc335f66efe0229e0702b3
+SHA512:
+  metadata.gz: 4974134e76747012c27f44408d9804040d15c183a03bc3258000e8e04734d46288ba5f1e2e1213cd906678830042e9913ffd6c7b65f196b68f73954e58f82180
+  data.tar.gz: af3bcdb37c9ba6f84e27855816c6317ab809b800a5fe6519a5e9f76555da0169f9ebdd26cc1d2f318c54908ce4b3d87534fc55e341485c48950761e0395f2403

data/.gemfiles/4.1.gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+gem "activerecord", "~> 4.1.0"
+gemspec path: "../"

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.DS_Store
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.0
+  - rbx-2.2
+gemfile:
+  - .gemfiles/4.1.gemfile

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Michael van Rooijen
+
+MIT License
+
+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,288 @@
+# Parelation
+
+[![Code Climate](https://codeclimate.com/github/meskyanichi/parelation.png)](https://codeclimate.com/github/meskyanichi/parelation)
+[![Build Status](https://travis-ci.org/meskyanichi/parelation.svg)](https://travis-ci.org/meskyanichi/parelation)
+
+Parelation, for Rails/ActiveRecord 4.1.0+, allows you to query your ActiveRecord-mapped database easily, securely and quite flexibly using simple GET requests. It's used in your controller layer where it uses HTTP GET parameters to build on the ActiveRecord::Relation chain. This provides the client-side with the out-of-the-box flexibility to perform fairly dynamic queries without having to write boilerplate on the server.
+
+This library was developed for- and extracted from [HireFire].
+
+### Compatibility
+
+- Rails/ActiveRecord 4.1.0+
+- Ruby (MRI) 2.0+
+- Ruby (RBX) 2.2+
+
+### Installation
+
+Compile and install the gem from source.
+
+```rb
+gem "parelation", github: "meskyanichi/parelation"
+```
+
+*This library won't be hosted on RubyGems.org until it's been tested more in development.*
+
+### Example
+
+Here's an example to get an idea of how it works. We'll fetch the `50` most recently created and `open` tickets, and we only want their `id`, `name` and `message` attributes.
+
+```js
+var params = {
+  "select[]": ["id", "name", "message"],
+  "where[state]": "open",
+  "order": "created_at:desc",
+  "limit": "50"
+}
+
+$.get("https://api.ticket.app/tickets", params, function(tickets){
+  console.log("Just fetched the 50 most recent and open tickets.")
+  $.each(tickets, function(ticket){
+    console.log("Ticket " + ticket.name + " loaded!")
+  })
+})
+```
+
+Simply include `Parelation::Helpers` and use the `parelate` method. This will ensure that the provided parameters are converted and applied to the `Ticket.all` criteria chain.
+
+```rb
+class Api::V1::TicketsController < ApplicationController
+  include Parelation::Helpers
+
+  def index
+    render json: parelate(Ticket.all)
+  end
+end
+```
+
+You can also scope results to the `current_user`:
+
+```rb
+class Api::V1::TicketsController < ApplicationController
+  include Parelation::Helpers
+
+  def index
+    render json: parelate(current_user.tickets)
+  end
+end
+```
+
+Using the same JavaScript, this'll now fetch the 50 most recent open tickets scoped to the `current_user`.
+
+
+### Parameter List (Reference)
+
+Here follows a list of all possible query syntaxes. We'll assume we have a Ticket model to query on.
+
+#### Select
+
+```
+/tickets?select[]=id&select[]=name&select[]=message
+```
+
+Translates to:
+
+```rb
+Ticket.select(:id, :name, :message)
+```
+
+#### Where
+
+```
+/tickets?where[state]=open
+```
+
+Translates to:
+
+```rb
+Ticket.where(state: "open")
+```
+
+You can also specify multiple multiple conditions:
+
+```
+/tickets?where[state][]=open&where[state][]=pending
+```
+
+Translates to:
+
+```rb
+Ticket.where(state: ["open", "pending"])
+```
+
+#### Where (directional)
+
+* `where_gt` (greater than `>`)
+* `where_gte` (greater than or equal to `>=`)
+* `where_lt` (less than `<`)
+* `where_lte` (less than or equal to `<=`)
+
+```
+/tickets?where_gt[created_at]=2014-01-01T00:00:00Z
+```
+
+Translates to:
+
+```rb
+Ticket.where("'tickets'.'created_at' > '2014-01-01 00:00:00.000000'")
+```
+
+You can also specify multiple conditions:
+
+```
+/tickets?where_gt[created_at]=2014-01-01T00:00:00Z&where_gt[updated_at]=2014-01-01T00:00:00Z
+```
+
+Translates to:
+
+```rb
+Ticket
+  .where("'tickets'.'created_at' > '2014-01-01 00:00:00.000000'")
+  .where("'tickets'.'updated_at' > '2014-01-01 00:00:00.000000'")
+```
+
+#### Query
+
+```
+/tickets?query[memory leak]=name
+```
+
+Translates to:
+
+```rb
+Ticket.where("'tickets'.'name' LIKE '%memory leak%'")
+```
+
+You can also specify multiple columns to scan:
+
+```
+/tickets?query[memory leak]=name&query[memory leak]=message
+```
+
+Translates to:
+
+```rb
+Ticket.where("(
+  'tickets'.'name' LIKE '%memory leak%' OR
+  'tickets'.'message' LIKE '%memory leak%'
+)")
+```
+
+#### Order
+
+```
+/tickets?order=created_at:desc
+```
+
+Translates to:
+
+```rb
+Ticket.order(created_at: :desc)
+```
+
+You can also specify multiple order-operations:
+
+```
+/tickets?order[]=created_at:desc&order[]=name:asc
+```
+
+Translates to:
+
+```rb
+Ticket.order(created_at: :desc, name: :asc)
+```
+
+#### Limit
+
+```
+/tickets?limit=50
+```
+
+Translates to:
+
+```rb
+Ticket.limit(50)
+```
+
+#### Offset
+
+```
+/tickets?offset=25
+```
+
+Translates to:
+
+```rb
+Ticket.offset(25)
+```
+
+
+### Error Handling
+
+When invalid parameters were sent, you can rescue the exception and return a message to the client.
+
+```rb
+class Api::V1::TicketsController < ApplicationController
+  include Parelation::Helpers
+
+  def index
+    render json: parelate(Ticket.all)
+  rescue Parelation::Errors::Parameter => error
+    render json: { error: error }, status: :bad_request
+  end
+end
+```
+
+This will tell client developers what parameter failed in the HTTP response. This exception generally occurs when there is a typo in the URL's parameters. Knowing which parameter failed (described in `error`) helps narrowing down the issue.
+
+
+### Contributing
+
+Contributions are welcome, but please conform to these requirements:
+
+- Ruby (MRI) 2.0+
+- Ruby (RBX) 2.2+
+- ActiveRecord 4.1.0+
+- 100% Spec Coverage
+  - Generated by when running the test suite
+- 100% [Passing Specs]
+  - Run test suite with `$ rspec spec`
+- 4.0 [Code Climate Score]
+  - Run `$ rubycritic lib` to generate the score locally and receive tips
+  - No code smells
+  - No duplication
+
+To start contributing, fork the project, clone it, and install the development dependencies:
+
+```
+git clone git@github.com:USERNAME/parelation.git
+cd parelation
+bundle
+```
+
+Ensure that everything works:
+
+```
+rspec spec
+rubycritic lib
+```
+
+Create a new branch and start hacking:
+
+```
+git checkout -b my-contributions
+```
+
+Submit a pull request.
+
+
+### Author / License
+
+Copyright (c) 2014 Michael van Rooijen ( [@meskyanichi] )<br />
+Released under the MIT [License].
+
+[@meskyanichi]: https://twitter.com/meskyanichi
+[HireFire]: http://hirefire.io
+[Passing Specs]: https://travis-ci.org/meskyanichi/parelation
+[Code Climate Score]: https://codeclimate.com/github/meskyanichi/parelation
+[License]: https://github.com/meskyanichi/parelation/blob/master/LICENSE

data/Rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/lib/parelation/applier.rb

@@ -0,0 +1,60 @@
+class Parelation::Applier
+
+  # @return [Array] the list of active criteria classes
+  #   that are used to narrow down database results.
+  #
+  CRITERIA = [
+    Parelation::Criteria::Select,
+    Parelation::Criteria::Limit,
+    Parelation::Criteria::Offset,
+    Parelation::Criteria::Order,
+    Parelation::Criteria::Query,
+    Parelation::Criteria::Where
+  ]
+
+  # @return [ActiveRecord::Relation]
+  #
+  attr_reader :chain
+
+  # @return [ActionController::Parameters, Hash]
+  #
+  attr_reader :params
+
+  # @param chain [ActionController::Relation] the base chain to build on.
+  # @param params [ActionController::Parameters, Hash] user input via params.
+  #
+  def initialize(chain, params)
+    @chain = chain
+    @params = params
+  end
+
+  # @return [ActiveRecord::Relation] the criteria-applied {#chain}.
+  #
+  def apply
+    @apply ||= apply_to_chain
+  end
+
+  private
+
+  # Iterates over each user-provided parameter and incrementally
+  # updates the {#chain} to incorporate the user-requested criteria.
+  #
+  # @return [ActiveRecord::Relation]
+  #
+  def apply_to_chain
+    params.each do |param, value|
+      CRITERIA.each do |criteria|
+        if criteria.match?(param)
+          begin
+            @chain = criteria.new(chain, param, value).call
+          rescue
+            raise Parelation::Errors::Parameter,
+              "the #{param} parameter is invalid"
+          end
+        end
+      end
+    end
+
+    chain
+  end
+end

data/lib/parelation/criteria/limit.rb

@@ -0,0 +1,24 @@
+class Parelation::Criteria::Limit
+  include Parelation::Criteria
+
+  # @param param [String]
+  # @return [TrueClass, FalseClass]
+  #
+  def self.match?(param)
+    !!(param =~ /^limit$/)
+  end
+
+  # @return [ActiveRecord::Relation]
+  #
+  def call
+    chain.limit(limit)
+  end
+
+  private
+
+  # Alias for {#value}.
+  #
+  def limit
+    value
+  end
+end

data/lib/parelation/criteria/offset.rb

@@ -0,0 +1,24 @@
+class Parelation::Criteria::Offset
+  include Parelation::Criteria
+
+  # @param param [String]
+  # @return [TrueClass, FalseClass]
+  #
+  def self.match?(param)
+    !!(param =~ /^offset$/)
+  end
+
+  # @return [ActiveRecord::Relation]
+  #
+  def call
+    chain.offset(offset)
+  end
+
+  private
+
+  # Alias for {#value}.
+  #
+  def offset
+    value
+  end
+end

data/lib/parelation/criteria/order/object.rb

@@ -0,0 +1,46 @@
+class Parelation::Criteria::Order::Object
+
+  # @return [String]
+  #
+  attr_reader :order
+
+  # @param order [String]
+  #
+  def initialize(order)
+    @order = order
+  end
+
+  # @return [Hash] returns criteria for {ActiveRecord::Relation}.
+  #
+  # @example
+  #   { created_at: :asc }
+  #
+  def criteria
+    { field => direction }
+  end
+
+  private
+
+  # @return [String] the name of the field to perform the ordering on.
+  #
+  def field
+    parts.first || ""
+  end
+
+  # @return [Symbol, nil] the direction to order {#field},
+  #   eiter :asc or :desc.
+  #
+  def direction
+    case parts.last
+    when "asc" then :asc
+    when "desc" then :desc
+    else nil
+    end
+  end
+
+  # @return [Array<String, nil>] the criteria chunks (separated by +:+).
+  #
+  def parts
+    @parts ||= order.split(":")
+  end
+end

data/lib/parelation/criteria/order.rb

@@ -0,0 +1,31 @@
+class Parelation::Criteria::Order
+  include Parelation::Criteria
+
+  require_relative "order/object"
+
+  # @param param [String]
+  # @return [TrueClass, FalseClass]
+  #
+  def self.match?(param)
+    !!(param =~ /^order$/)
+  end
+
+  # Applies the specified orderings to {#chain}.
+  #
+  # @return [ActiveRecord::Relation] the modified chain.
+  #
+  def call
+    orders.inject(chain) do |chain, order|
+      chain.order(order.criteria)
+    end
+  end
+
+  private
+
+  # @return [Array<Parelation::Criteria::Order::Object>] an
+  #   array of attributes to order.
+  #
+  def orders
+    @orders ||= [value].flatten.map { |order| Object.new(order) }
+  end
+end

data/lib/parelation/criteria/query.rb

@@ -0,0 +1,55 @@
+class Parelation::Criteria::Query
+  include Parelation::Criteria
+
+  # @param param [String]
+  # @return [TrueClass, FalseClass]
+  #
+  def self.match?(param)
+    !!(param =~ /^query$/)
+  end
+
+  # @return [ActiveRecord::Relation]
+  #
+  def call
+    chain.where(*criteria)
+  end
+
+  private
+
+  # @return [Array] containing {#chain} criteria.
+  #
+  def criteria
+    [sql] + args
+  end
+
+  # @return [String] an SQL statement based on the selected {#attributes}.
+  #
+  def sql
+    template = ->(field) { %Q{"#{chain.arel_table.name}"."#{field}" LIKE ?} }
+    attributes.map(&template).join(" OR ")
+  end
+
+  # @return [Array] containing the query, one for each field in {#attributes}.
+  #
+  def args
+    attributes.count.times.map { "%#{query}%" }
+  end
+
+  # @return [String] the "search" query to perform.
+  #
+  def query
+    @query ||= parts.first
+  end
+
+  # @return [Array<String>] an array of attributes to search in.
+  #
+  def attributes
+    @attributes ||= parts.last
+  end
+
+  # @return [Array] containing the query and attributes.
+  #
+  def parts
+    @parts ||= [value.keys.first, [value.values.first].flatten]
+  end
+end

data/lib/parelation/criteria/select.rb

@@ -0,0 +1,24 @@
+class Parelation::Criteria::Select
+  include Parelation::Criteria
+
+  # @param param [String]
+  # @return [TrueClass, FalseClass]
+  #
+  def self.match?(param)
+    !!(param =~ /^select$/)
+  end
+
+  # @return [ActiveRecord::Relation]
+  #
+  def call
+    chain.select(*attributes)
+  end
+
+  private
+
+  # Alias for {#value}.
+  #
+  def attributes
+    value
+  end
+end