squirrell 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e8db40497e5ea5d4b0be64e4f118fc6acdd798f
-  data.tar.gz: 552b660a72a079f1ac2bf4b53cbb0639b472e8b0
+  metadata.gz: 1a678310855fbf171850f32bb38fad77e5e0855c
+  data.tar.gz: 9536ceacaa2b2d8d30f4275e30b1251e1ddca1eb
 SHA512:
-  metadata.gz: beb3ebe622552e184725616d5b607f14cccaac5101984a179eac6a6a47d1934df36e193fe28e74ca9044678c9137174046c4760eaa1e89946f00c1c21ff485cb
-  data.tar.gz: 9afb120cc06c7446187b982a9e81ea77a63822e158016bced2b37b326584bdc0b5227e2cf8f24de453d9ebad6c2d3caf296172a5d391edd50e68bfd1f6753898
+  metadata.gz: cafec340ad62336b249689666f495091dd528e7ee142e00275701d236018d3d98a1119e2b909b786d83353e2f14539c956759a5c9d5a9979b993634cad4b9312
+  data.tar.gz: 13c3f68f51a122364f6cbca51af918f70bd7c6e0ee4bb21bb5bd59f24807419cef2a55dce590d513a2319751aa0dfd4580f13d93dde78f64f16a8a3d6ba1c981

data/README.md

@@ -1,6 +1,8 @@
 # Squirrell
 
-Squirrell is a completely non-magical library intended to make it easier to simplify your relationship with ActiveRecord.
+[![Gem Version](https://badge.fury.io/rb/squirrell.svg)](http://badge.fury.io/rb/squirrell)
+
+Squirrell is a kinda 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.
@@ -30,11 +32,11 @@ An executor responds to `:call`, accepts a single argument, and executes that ar
 It doesn't really have to execute a SQL query, though.
 It just probably should.
 
-To configure Squirrell, you can do a block:
+To configure Squirrell, you can do a block in an initializer somewhere:
 
 ```ruby
-Squirrell.configure do |sqrrll|
-  sqrrll.executor = -> (sql) { ActiveRecord::Base.connection.execute(sql) }
+Squirrell.configure do |sqrl|
+  sqrl.executor = -> (sql) { ActiveRecord::Base.connection.execute(sql) }
 end
 ```
 
@@ -68,7 +70,7 @@ class UserFinder
   requires :id
 
   def finder
-    User.find(@id)
+    User.find(id)
   end
 
   def process(result)
@@ -80,6 +82,7 @@ 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.
+`attr_readers` are provided for them, so you can refer to them without `@`.
 
 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.
@@ -96,8 +99,8 @@ class WizardByElementAndPet
 
   def arel
     wizards = Wizard.arel_table
-    wizards.where(wizards[:pet].eq(@pet))
-           .where(wizards[:element].eq(@element))
+    wizards.where(wizards[:pet].eq(pet))
+           .where(wizards[:element].eq(element))
            .project(wizards[:id])
   end
 end
@@ -115,7 +118,7 @@ class HeroByName
   requires :name
 
   def raw_sql
-    "SELECT heroes.id FROM heroes WHERE heroes.name = '#{@name}'"
+    "SELECT heroes.id FROM heroes WHERE heroes.name = '#{name}'"
   end
 end
 ```
@@ -137,7 +140,7 @@ class HeroByName
 end
 
 HeroByName.find(name: "Finn")
-# => [#<Hero:0x0987123 @name="Finn" @weapon="Grass Sword", etc...]
+# => [#<Hero:0x0987123 name="Finn" weapon="Grass Sword", etc...]
 ```
 
 Squirrell allows you to define optional permitted parameters:
@@ -154,12 +157,12 @@ def PermissionExample
 SELECT *
 FROM users
   INNER JOIN posts ON users.id = posts.user_id
-WHERE users.id = #{@user_id} #{has_post?}
+WHERE users.id = #{user_id} #{has_post?}
 SQL
   end
 
   def has_post?
-    @post_id ? "AND posts.id = #{@post_id}" : ""
+    post_id ? "AND posts.id = #{post_id}" : ""
   end
 end
 ```
@@ -176,6 +179,56 @@ Squirrell has a generator for queries.
 * `--type=` can either be `raw_sql`, `finder`, or `arel`.
 * The remaining elements are the required parameters for the query.
 
+## Testing Squirrells
+
+Mocking Squirrels is really easy. `expect(QueryObject).to receive(:find).and_return(results)` will capture the desired behavior in calling classes.
+
+Testing Squirrells has two components: testing that the interaction with the database works as expected, and testing that the post-processing method works as expected.
+
+For basic ActiveRecord finders, it's not really necessary to test `.find`.
+ActiveRecord is well-tested and unlikely to be cause problems.
+For Arel and raw SQL queries that have a bit more complexity, you'll likely want to actually touch the database in these tests.
+
+```ruby
+describe HeroByName do
+  before :all do
+    let(:finn) { create(:hero, name: "Finn") }
+    let(:jake) { create(:hero, name: "Jake") }
+  end
+
+  it 'finds by name' do
+    result = HeroByName.find(name: "Finn")
+    expect(result).to include(finn)
+    expect(result).to_not include(jake)
+  end
+end
+```
+
+You can gain access to the underlying Squirrell with `.new`, which lets you test the `process` method and any other methods you choose to define on the class.
+
+```ruby
+describe MathQuery do
+  class MathQuery
+    include Squirrell
+
+    requires :math
+
+    def process(result)
+      result * 5
+    end
+  end
+
+  let(:subject) { MathQuery.new }
+
+  it 'multiples result by 5' do
+    expect(subject.process(5)).to eq(10)
+  end
+end
+```
+
+Generally, it'll be easiest to use and test the code if `process` is a pure function of it's input.
+If you need to refer to those values, you can pass the parameters in to `new`: `MathQuery.new(math: "so cool")`.
+
 ## 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.

data/lib/squirrell.rb

@@ -1,5 +1,8 @@
 require 'squirrell/version'
+require 'squirrell/class_methods'
+require 'squirrell/instance_methods'
 
+# Including this module gives a few convenience methods for query objects.
 module Squirrell
   class << self
     attr_accessor :requires
@@ -18,61 +21,26 @@ module Squirrell
     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
-
+  # Errors raised when the executor doesn't respond to call.
   class ExecutorError < ArgumentError; end
+
+  # Error raised when result of `arel` doesn't respond to `to_sql`
   class InvalidArelError < ArgumentError; end
 
+  # Error raised when a required parameter is not passed.
+  class MissingParameterError < ArgumentError; end
+
+  # Error raised when a parameter passed into `.find` is not included in either
+  # requires or permits.
+  class UnusedParameter < 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
+    klass.extend ClassMethods
+    klass.include InstanceMethods
   end
 end

data/lib/squirrell/class_methods.rb

@@ -0,0 +1,32 @@
+module Squirrell
+  # Class methods for Squirrell objects.
+  module ClassMethods
+    def requires(*args)
+      Squirrell.requires[self] = args
+      define_readers args
+    end
+
+    def permits(*args)
+      Squirrell.permits[self] = args
+      define_readers args
+    end
+
+    def find(args = {})
+      do_query(new(args))
+    end
+
+    private
+
+    def do_query(object)
+      result = object.finder || Squirrell.executor.call(object.raw_sql)
+      object.process(result)
+    end
+
+    def define_readers(args)
+      args.each do |arg|
+        attr_reader arg
+      end
+    end
+  end
+end
+

data/lib/squirrell/instance_methods.rb

@@ -0,0 +1,43 @@
+module Squirrell
+  # Instance methods for Squirrell objects.
+  module InstanceMethods
+    # Override this method to do raw_sql.
+    def raw_sql
+      sql = arel
+      fail InvalidArelError unless sql.respond_to? :to_sql
+      sql.to_sql
+    end
+
+    # Override this method to do arel.
+    # Note: If you've overridden raw_sql, it won't work.
+    def arel
+      nil
+    end
+
+    # Override this method to skip SQL execution.
+    def finder
+      nil
+    end
+
+    # Override this method to process results after query execution.
+    def process(results)
+      results
+    end
+
+    def initialize(args = {})
+      return self if args.empty?
+      Squirrell.requires[self.class].each do |k|
+        unless args.keys.include? k
+          fail MissingParameterError, "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 UnusedParameter, "Unspecified parameters: #{args}" if args.any?
+    end
+  end
+end

data/lib/squirrell/version.rb

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

data/squirrell.gemspec

@@ -9,7 +9,6 @@ Gem::Specification.new do |spec|
   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'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: squirrell
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Matt Parsons
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-06-21 00:00:00.000000000 Z
+date: 2015-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -120,6 +120,8 @@ files:
 - lib/generators/sqrl/query/query_generator.rb
 - lib/generators/sqrl/query/templates/query_template.rb.erb
 - lib/squirrell.rb
+- lib/squirrell/class_methods.rb
+- lib/squirrell/instance_methods.rb
 - lib/squirrell/version.rb
 - squirrell.gemspec
 homepage: https://www.github.com/parsonsmatt/squirrell