squirrell 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3e8db40497e5ea5d4b0be64e4f118fc6acdd798f
+  data.tar.gz: 552b660a72a079f1ac2bf4b53cbb0639b472e8b0
+SHA512:
+  metadata.gz: beb3ebe622552e184725616d5b607f14cccaac5101984a179eac6a6a47d1934df36e193fe28e74ca9044678c9137174046c4760eaa1e89946f00c1c21ff485cb
+  data.tar.gz: 9afb120cc06c7446187b982a9e81ea77a63822e158016bced2b37b326584bdc0b5227e2cf8f24de453d9ebad6c2d3caf296172a5d391edd50e68bfd1f6753898

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

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

data/.ruby-gemset

@@ -0,0 +1 @@
+squirrell

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.2.2

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,42 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+directories %w(. lib spec)
+  .select { |d| Dir.exist?(d) ? d : UI.warning("Directory #{d} does not exist") }
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Matt Parsons
+
+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,191 @@
+# Squirrell
+
+Squirrell is a completely non-magical library intended to make it easier to simplify your relationship with ActiveRecord.
+ActiveRecord provides an immense amount of flexibility and power, and it's really easy to let this functionality become more-and-more intense.
+Controllers doing arbitrary `where`s, other models doing a `find_by`, maybe even a hidden finder in the views somewhere.
+This level of decoupling makes things difficult to test and obscures the lines in your application.
+
+Squirrell makes it easy to create finders and query objects that respond very well to testing and are easy to mock.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'squirrell'
+```
+
+### Rails
+
+Run the install generator to copy the initializer, add `app/queries` to Rails autoload, and provide an example query:
+
+    $ rails generate sqrl:install
+
+## Usage
+
+### Configuring Squirrell
+
+If you want to use any raw SQL or Arel querying, you'll need to provide Squirrell with an executor.
+An executor responds to `:call`, accepts a single argument, and executes that argument as a SQL query.
+It doesn't really have to execute a SQL query, though.
+It just probably should.
+
+To configure Squirrell, you can do a block:
+
+```ruby
+Squirrell.configure do |sqrrll|
+  sqrrll.executor = -> (sql) { ActiveRecord::Base.connection.execute(sql) }
+end
+```
+
+### Using a Squirrell query class
+
+Squirrell query classes have a very limited external interface.
+They respond to `.find` and return the result of the query.
+As a result, they're very easy to mock: `allow(ComplexQuery).to receive(:find).and_return(your_stubs)`
+
+(hah hah, silly squirrell)
+
+Examples:
+
+```ruby
+UserFinder.find(id: 6)
+WizardByElementAndPet.find(element: :ice, pet: :penguin)
+HeroByName.find(name: "Finn")
+```
+
+### Defining a Squirrell
+
+There are currently three queries supported by Squirrell: `#finder`, `#arel`, and `#raw_sql`.
+
+Finders are the simplest.
+They just return the result of the `#finder` method.
+
+```ruby
+class UserFinder
+  include Squirrell
+
+  requires :id
+
+  def finder
+    User.find(@id)
+  end
+
+  def process(result)
+    result.map { |user| "Happy birthday, #{user.name}!" }
+  end
+end
+```
+
+The `requires :id` line indicates what parameters must be passed to `find`.
+An error will be raised if a required parameter is missing or if an extra parameter is passed.
+The symbols in the hash are made into instance variables of the same name.
+
+After the finding method gets called, `#process` gets called with the result of the query.
+In the previous example, `result` would be an array, and it would convert the found users into a string wishing them a happy birthday.
+The return value of `process` is ultimately what the return value of `UserFinder.find` will be.
+
+Arel finders are meant to be used in conjunction with the Arel gem.
+In truth, the only requirement is that the return value of the `#arel` method respond to `:to_sql`.
+
+```ruby
+class WizardByElementAndPet
+  include Squirrell
+
+  requires :element, :pet
+
+  def arel
+    wizards = Wizard.arel_table
+    wizards.where(wizards[:pet].eq(@pet))
+           .where(wizards[:element].eq(@element))
+           .project(wizards[:id])
+  end
+end
+```
+
+Finally, Squirrell can do raw SQL.
+Define `#raw_sql` on the Squirrell class and it'll use the executor.
+The string returned by `raw_sql` is passed directly to the executor.
+Currently, it doesn't do anything clever to escape it.
+
+```ruby
+class HeroByName
+  include Squirrell
+
+  requires :name
+
+  def raw_sql
+    "SELECT heroes.id FROM heroes WHERE heroes.name = '#{@name}'"
+  end
+end
+```
+
+Sometimes, you just want to return a bunch of models, and the finder has you totally covered.
+Other times, the array-of-arrays or array-of-column-hashes are all you need.
+When that isn't the case, Squirrell provides a `#process` hook that receives the result of the query and can do whatever it wants with it.
+
+```ruby
+class HeroByName
+  # ...
+  def process(result)
+    puts result
+    # => #<PG::Result:0x981723098 status=PGRES_TUPLES_OK etc....>
+    puts result.values
+    # => [["1"],["42"]]
+    Hero.find(result.values.flatten)
+  end
+end
+
+HeroByName.find(name: "Finn")
+# => [#<Hero:0x0987123 @name="Finn" @weapon="Grass Sword", etc...]
+```
+
+Squirrell allows you to define optional permitted parameters:
+
+```ruby
+def PermissionExample
+  include Squirrell
+
+  requires :user_id
+  permits :post_id
+
+  def raw_sql
+    <<SQL
+SELECT *
+FROM users
+  INNER JOIN posts ON users.id = posts.user_id
+WHERE users.id = #{@user_id} #{has_post?}
+SQL
+  end
+
+  def has_post?
+    @post_id ? "AND posts.id = #{@post_id}" : ""
+  end
+end
+```
+
+Generally, this makes for more complex queries. If you're finding that you're customizing with a bunch of `permits`, you may want to make a new query object.
+
+### Rails Generator
+
+Squirrell has a generator for queries.
+
+    $ rails generate sqrl:query QueryName --type=raw_sql id name
+
+* `QueryName` is the name of the query object.
+* `--type=` can either be `raw_sql`, `finder`, or `arel`.
+* The remaining elements are the required parameters for the query.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/squirrell/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`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'squirrell'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/sqrl/install/install_generator.rb

@@ -0,0 +1,19 @@
+require 'rails/generators'
+
+module Sqrl
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+
+      desc 'Creates Squirrell initializer'
+      def copy_initializer
+        template 'squirrell_initializer.rb', 'config/initializers/squirrell.rb'
+      end
+
+      desc 'Creates Example Query'
+      def example_query
+        template 'example_query.rb', 'app/queries/example_query.rb'
+      end
+    end
+  end
+end

data/lib/generators/sqrl/install/templates/example_query.rb

@@ -0,0 +1,35 @@
+class ExampleQuery
+  include Squirrell
+
+  # Requires indicates the parameters necessary for the query.
+  # Called like: `ExampleQuery.find(id: 5, name: "alice", email: "cto@fancycorp.com")`
+  # The values will be made available to queries as instance variables of the
+  # same name.
+  requires :id, :name, :email
+
+  # process handles the result of the query before passing it to the caller.
+  # It's defined by default like this.
+  def process(result)
+    result
+  end
+
+  # `#finder` execute the code in the method and pass directly to `#process`.
+  # Great for ActiveRecord `find_by`, `where`, etc.
+  def finder
+    User.find_by(id: @id, name: @name, email: @email)
+  end
+
+  # `#arel` is where you might put Arel code. As long as the return value of
+  # the method responds to `to_sql`, you're good. The code will be converted to
+  # SQL, executed, and passed into process.
+  def arel
+    users = User.arel_table
+    users.where(users[:name].eq(@name))
+      .project(users[:email])
+  end
+
+  # `#raw_sql` is for raw sql code. It gets executed and passed to process.
+  def raw_sql
+    "SELECT * FROM users WHERE name = '#{@name}'"
+  end
+end

data/lib/generators/sqrl/install/templates/squirrell_initializer.rb

@@ -0,0 +1,5 @@
+Squirrell.configure do |sqrl|
+  # executor is any object that responds to `call`. It will be called with
+  # the generated SQL. An example for ActiveRecord is provided:
+  sqrl.executor = -> (query) { ActiveRecord::Base.connection.execute(query) }
+end

data/lib/generators/sqrl/query/query_generator.rb

@@ -0,0 +1,29 @@
+require 'rails/generators'
+
+module Sqrl
+  module Generators
+    class QueryGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+
+      class_option :type, type: :string, default: 'finder', desc: 'finder/raw_sql/arel'
+      argument :requires, type: :array, default: ['id'], desc: 'Required parameters'
+
+      desc 'Creates a query'
+      def create_query
+        path = "app/queries/#{file_name}.rb"
+
+        template 'query_template.rb.erb', path
+      end
+
+      private
+
+      def require_syms
+        requires.map { |s| ":#{s}" } * ', '
+      end
+
+      def query_type
+        options[:type] || 'finder'
+      end
+    end
+  end
+end

data/lib/generators/sqrl/query/templates/query_template.rb.erb

@@ -0,0 +1,13 @@
+class <%= class_name %>
+  include Squirrell
+
+  requires <%= require_syms %>
+  
+  def <%= query_type %>
+
+  end
+
+  def process(result)
+    result
+  end
+end

data/lib/squirrell.rb

@@ -0,0 +1,78 @@
+require 'squirrell/version'
+
+module Squirrell
+  class << self
+    attr_accessor :requires
+    attr_accessor :permits
+    attr_reader :executor
+
+    def executor=(e)
+      unless e.respond_to? :call
+        fail ExecutorError, 'Executor must respond to `#call`'
+      end
+      @executor = e
+    end
+  end
+
+  def self.configure
+    yield self
+  end
+
+  def raw_sql
+    sql = arel
+    fail InvalidArelError unless sql.respond_to? :to_sql
+    sql.to_sql
+  end
+
+  def process(results)
+    results
+  end
+
+  class ExecutorError < ArgumentError; end
+  class InvalidArelError < ArgumentError; end
+
+  def self.included(klass)
+    Squirrell.requires ||= {}
+    Squirrell.requires[klass] = []
+    Squirrell.permits ||= {}
+    Squirrell.permits[klass] = []
+
+    def klass.requires(*args)
+      Squirrell.requires[self] = args
+    end
+
+    def klass.permits(*args)
+      Squirrell.permits[self] = args
+    end
+
+    def initialize(args)
+      Squirrell.requires[self.class].each do |k|
+        unless args.keys.include? k
+          fail ArgumentError, "Missing required parameter: #{k}"
+        end
+        instance_variable_set "@#{k}", args.delete(k)
+      end
+
+      Squirrell.permits[self.class].each do |k|
+        instance_variable_set "@#{k}", args.delete(k) if args.keys.include? k
+      end
+
+      fail ArgumentError if args.any?
+    end
+
+    def klass.find(args = {})
+      do_query(new(args))
+    end
+
+    def klass.do_query(object)
+      result = nil
+      if object.respond_to? :finder
+        result = object.finder
+      else
+        sql = object.raw_sql
+        result = Squirrell.executor.call(sql)
+      end
+      object.process(result)
+    end
+  end
+end

data/lib/squirrell/version.rb

@@ -0,0 +1,3 @@
+module Squirrell
+  VERSION = '0.1.0'
+end

data/squirrell.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'squirrell/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'squirrell'
+  spec.version       = Squirrell::VERSION
+  spec.authors       = ['Matt Parsons']
+  spec.email         = ['parsonsmatt@gmail.com']
+
+
+  spec.summary       = 'A kinda magical gem for query objects'
+  spec.homepage      = 'https://www.github.com/parsonsmatt/squirrell'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.8'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'guard', '~> 2.12'
+  spec.add_development_dependency 'rspec', '~> 3.3'
+  spec.add_development_dependency 'guard-rspec', '~> 4.5'
+  spec.add_development_dependency 'rubocop'
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: squirrell
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matt Parsons
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-06-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- parsonsmatt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-gemset"
+- ".ruby-version"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/generators/sqrl/install/install_generator.rb
+- lib/generators/sqrl/install/templates/example_query.rb
+- lib/generators/sqrl/install/templates/squirrell_initializer.rb
+- lib/generators/sqrl/query/query_generator.rb
+- lib/generators/sqrl/query/templates/query_template.rb.erb
+- lib/squirrell.rb
+- lib/squirrell/version.rb
+- squirrell.gemspec
+homepage: https://www.github.com/parsonsmatt/squirrell
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: A kinda magical gem for query objects
+test_files: []