inquery 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9ab3cd729d1ad08041f09d90c2d3f95925dd4ba5
+  data.tar.gz: 00f6185d8d34785c27ba9c936b618188f0caa57b
+SHA512:
+  metadata.gz: 57bac62a978855077de4f05449c4eebc1128cc72ecad1781104c614f6876dea8bc46aab2a2e95f7d57169a7506fb726510edfa6591bf54dd8306afb420a25939
+  data.tar.gz: e05f7bc9e5f42c3fdf53f1170cbc0a9c5004ec760d5a0982e645f79ae1cb9b606a9d3095d51ee8a9483b3dcf9e51a488e1f1aa6a207ef0ab9e5902960a43efd5

data/.gitignore

@@ -0,0 +1,16 @@
+/bin/ruby
+/.bundle
+.DS_Store
+*.tmproj
+tmtags
+/Gemfile.lock
+*~
+\#*
+.\#*
+*.swp
+/vendor/gems/*
+/vendor/bundle/*
+/spec/reports
+/.yardoc
+.idea
+/*.gem

data/.releaser_config

@@ -0,0 +1,4 @@
+version_file: VERSION
+always_from_master: true
+yard_path: doc
+gem_style: github

data/.rubocop.yml

@@ -0,0 +1,42 @@
+AllCops:
+  Exclude:
+    - 'local/**/*'
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - '*.gemspec'
+
+  DisplayCopNames: true
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: False
+
+Metrics/CyclomaticComplexity:
+  Enabled: False
+
+Metrics/PerceivedComplexity:
+  Enabled: False
+
+Metrics/LineLength:
+  Max: 160
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/RedundantReturn:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+  EnforcedStyle: compact
+  SupportedStyles:
+    - nested
+    - compact

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+ - 2.0
+ - 2.2
+ - 2.3.0
+script:
+ - bundle install
+ - bundle exec rake test
+ - bundle exec rubocop

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown --readme=README.md --no-private lib/**/*.rb

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify gem dependencies in the .gemspec file
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Sitrox
+
+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 @@
+# Inquery
+
+A skeleton that allows extracting queries into atomic, reusable classes.
+
+## Installation
+
+To install the **Inquery** gem:
+
+```sh
+$ gem install inquery
+```
+
+To install it using `bundler` (recommended for any application), add it
+to your `Gemfile`:
+
+```ruby
+gem 'inquery'
+```
+
+## Basic usage
+
+```ruby
+class FetchUsersWithACar < Inquery::Query
+  schema(
+    color: :symbol
+  )
+
+  def call
+    User.joins(:cars).where(cars: { color: osparams.color })
+  end
+end
+
+FetchUsersWithACar.run
+# => [<User id: 1 ...]
+```
+
+Inquery offers its functionality trough two query base classes: {Inquery::Query}
+and {Inquery::Query::Chainable}. See the following sections for detailed
+explanations.
+
+## Basic queries
+
+Basic queries inherit from {Inquery::Query}. They receive an optional set of
+parameters and commonly return a relation / AR result. An optional `process`
+method lets you perform additional result processing steps if needed (i.e.
+converting the result to a hash or similar).
+
+For this basic functionality, inherit from {Inquery::Query} and overwrite
+the `call` and optionally the `process` method:
+
+```ruby
+class FetchRedCarsAsJson
+  # The `call` method must be overwritten for every query. It is usually called
+  # via `run`.
+  def call
+    Car.where(color: 'red')
+  end
+
+  # The `process` method can optionally be overwritten. The base implementation
+  # just returns the unprocessed `results` argument.
+  def process(results)
+    results.to_json
+  end
+end
+```
+
+Queries can be called in various ways:
+
+```ruby
+# Instantiates the query class and runs `call` and `process`.
+FetchRedCarsAsJson.run(params = {})
+
+# Instantiates the query class and runs `call`. No result processing
+# is done.
+FetchRedCarsAsJson.call(params = {})
+
+# You can also instantiate the query class manually.
+FetchRedCarsAsJson.new(params = {}).run
+
+# Or just run the `call` method without `process`.
+FetchRedCarsAsJson.new(params = {}).call
+```
+
+Note that it's perfectly fine for some queries to return `nil`, i.e. if they're
+writing queries that don't fetch any results.
+
+## Chainable queries
+
+Chainable queries are queries that input and output an Active Record relation.
+You can access the given relation using the method `relation`:
+
+```ruby
+class Queries::User::FetchActive < Inquery::Query::Chainable
+  def call
+    relation.where(active: 1)
+  end
+end
+```
+
+Input and output relations may or may not be of the same AR class (i.e. you
+could pass a relation of `Group`s and receive back a relation of corresponding
+`User`s).
+
+### Relation validation
+
+Chainable queries allow you to further specify and validate the relation it
+receives. This is done using the static `relation` method:
+
+```ruby
+class Queries::User::FetchActive < Inquery::Query::Chainable
+  # This will raise an exception when passing a relation which does not
+  # correspond to the `User` model.
+  relation class: 'User'
+
+  # ....
+end
+```
+
+The `relation` method accepts the following options:
+
+* `class`
+
+    Allows to restrict the class (attribute `klass`) of the relation.
+    Use `nil` to not perform any checks. The `class` attribute will also
+    be taken to infer a default if no relation is given and you didn't
+    specify any `default`.
+
+* `default`
+
+    This allows to specify a default relation that will be taken if no relation
+    is given. This must be specified as a Proc returning the relation. Set this
+    to `false` for no default. If this is set to `nil`, it will try to infer the
+    default from the option `class` (if given).
+
+* `fields`
+
+    Allows to restrict the number of fields / values the relation must select.
+    This is particularly useful if you're using the query as a subquery and need
+    it to return exactly one field. Use `nil` to not perform any checks.
+
+* `default_select`
+
+    If this is set to a symbol, the relation does not have any select fields
+    specified (`select_values` is empty) and `fields` is > 0, it will
+    automatically select the given field. This option defaults to `:id`. Use
+    `nil` to disable this behavior.
+
+### Using query classes as regular scopes
+
+Chainable queries can also be used as regular AR model scopes:
+
+```ruby
+class User < ActiveRecord::Base
+  scope :active, Queries::User::FetchActive
+end
+
+class Queries::User::FetchActive < Inquery::Query::Chainable
+  # Note that specifying either `class` or `default` is mandatory when using
+  # this query class as a scope. The reason for this is that, if the scope is
+  # otherwise empty, the class will receive `nil` from AR and therefore has no
+  # way of knowing which default class to take.
+  relation class: 'User'
+
+  def call
+    relation.where(active: 1)
+  end
+end
+```
+
+This approach allows to you use short and descriptive code like `User.active`
+but have the possibly complex query code hidden in a separate, reusable class.
+
+Note that when using classes as scopes, the `process` method will be ignored.
+
+### Using the given relation as subquery
+
+In simple cases and all the examples above, we just extend the given relation
+and return it again. It is also possible however to just use the given relation
+as a subquery and return a completely new relation:
+
+
+```ruby
+class FetchUsersInGroup < Inquery::Query::Chainable
+  # Here we do not specify any specific class, as we don't care for it as long
+  # as the relation returns exactly one field.
+  relation fields: 1
+
+  def call
+    return ::User.where(%(
+      id IN (
+        SELECT user_id FROM GROUPS_USERS WHERE group_id IN (
+          #{relation.to_sql}
+        )
+      )
+    ))
+  end
+end
+```
+
+This query could then be called in the following ways:
+
+```ruby
+FetchUsersInGroup.run(
+  GroupsUser.where(user_id: 1).select(:group_id)
+)
+
+# In this example, we're not specifying any select for the relation we pass to
+# the query class. This is fine because the query automatically defaults to
+# selecting `id` if exactly one field is required (`fields: 1`) and no select is
+# specifyed. You can control this further with the option `default_select`.
+FetchUsersInGroup.run(Group.where(color: 'red'))
+```
+
+## Parameters
+
+Both query classes can be parameterized using a hash called `params`. It is
+recommended to specify and validate input parameters in every query. For this
+purpose, Inquery provides the `schema` method witch integrates the
+[Schemacop](https://github.com/sitrox/schemacop) validation Gem:
+
+```ruby
+class SomeQueryClass < Inquery::Query
+  schema(
+    some_param: :integer,
+    some_other_param: {
+      hash: {
+        some_field: :string
+      }
+    }
+  )
+
+  # ...
+end
+```
+
+The schema is validated at query class instantiation. An exception will be
+raised if the given params do not match the schema specified. See documentation
+of the Schemacop Gem for more information on how to specify schemas.
+
+Parameters can be accessed using either `params` or `osparams`. The method
+`osparams` automatically wraps `params` in an `OpenStruct` for more convenient
+access.
+
+```ruby
+class SomeQueryClass < Inquery::Query
+  def run
+    User.where(
+      active: params[:active],
+      username: osparams.search
+    )
+  end
+end
+```
+
+## Rails integration
+
+While it is optional, Inquery has been written from the ground up to be
+perfectly integrated into any Rails application. It has proven to be a winning
+concept to extract all complex queries into separate classes that are
+independently executable and testable.
+
+### Directory structure
+
+While not enforced, it is encouraged to use the following structure for storing
+your query classes:
+
+* All domain-specific query classes reside in `app/queries`.
+* They're in the module `Queries`.
+* Queries are further grouped by the model they return (and not the model
+  they receive). For instance, a class fetching all active users could be
+  located at `Queries::User::FetchActive` and would reside under
+  `app/queries/user/fetch_active.rb`.
+
+There are some key benefits to this approach:
+
+* As it should, domain-specific code is located within `app/`.
+* As queries are grouped by the model they return and consistently named,
+  they're easy to locate and it does not take much thought where to put and
+  how to name new query classes.
+* As there is a single file per query class, it's a breeze to list all
+  queries, i.e. to check their naming for consistency.
+* If you're using the same layout for your unit tests, it is absolutely
+  clear where to find the corresponding unit tests for each one of your
+  query classes.
+
+## Copyright
+
+Copyright (c) 2016 Sitrox. See `LICENSE` for further details.

data/RUBY_VERSION

@@ -0,0 +1 @@
+ruby-2.0.0-p353

data/Rakefile

@@ -0,0 +1,36 @@
+task :gemspec do
+  gemspec = Gem::Specification.new do |spec|
+    spec.name          = 'inquery'
+    spec.version       = IO.read('VERSION').chomp
+    spec.authors       = ['Sitrox']
+    spec.summary       = %(
+      A skeleton that allows extracting queries into atomic, reusable classes.
+    )
+    spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+    spec.executables   = []
+    spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+    spec.require_paths = ['lib']
+
+    spec.add_development_dependency 'bundler', '~> 1.3'
+    spec.add_development_dependency 'rake'
+    spec.add_development_dependency 'sqlite3'
+    spec.add_development_dependency 'haml'
+    spec.add_development_dependency 'yard'
+    spec.add_development_dependency 'rubocop', '0.35.1'
+    spec.add_development_dependency 'redcarpet'
+    spec.add_dependency 'minitest'
+    spec.add_dependency 'activesupport'
+    spec.add_dependency 'activerecord'
+    spec.add_dependency 'schemacop', '>= 1.0.1'
+  end
+
+  File.open('inquery.gemspec', 'w') { |f| f.write(gemspec.to_ruby.strip) }
+end
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/inquery/**/*_test.rb'
+  t.verbose = false
+  t.libs << 'test'
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1