arlj 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 674e9b2df96b4850dc128bc5de58252833a7ba95
+  data.tar.gz: aa92466cd390f09ad567acbad0a05a13cdfa995f
+SHA512:
+  metadata.gz: f6498872bd416cb091ab5a69ded518af390097483583a72bb00217598373da17f608f2234ce49376978673acbd7b5e479120f1567f261ba0270ad43e449b1253
+  data.tar.gz: 6ed666eb60114b8225dd5ad04e51cc07094cbd81e3be9f8170af3c38e30606c2c7424f2c58aa651dcb17ac6bc4488b52547a9dbbd3f6737260c72c7ffd1ff368

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 fengb
+
+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,94 @@
+# Arlj - ActiveRecord Left Join
+
+Make left joins feel like first-class citizens in ActiveRecord.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'arlj'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install arlj
+
+## Usage
+
+Load Arlj into your class:
+
+```ruby
+class Parent < ActiveRecord::Base
+  extend Arlj
+end
+```
+
+Or extend all of ActiveRecord models:
+
+```ruby
+ActiveRecord::Base.extend Arlj
+```
+
+Then begin to left join!
+
+```ruby
+puts Parent.arlj(:children).group('records.id').select('COUNT(children.id)').to_sql
+=> SELECT COUNT(children.id)
+     FROM "parents"
+     LEFT OUTER JOIN "children"
+                  ON "children"."parent_id" = "parents"."id"
+    GROUP BY records.id
+```
+
+`arlj` is purposely low level to be extra chainable.
+
+Arlj also adds an aggregation syntax:
+
+```ruby
+Parent.arlj_aggregate(:children, 'COUNT(*)', 'SUM(col)' => 'total').select('children_count', 'total').to_sql
+=> SELECT children_count
+        , total
+     FROM "parents"
+     LEFT OUTER JOIN (SELECT "children"."parent_id"
+                           , COUNT("children"."id") AS children_count
+                           , SUM("children"."col") AS total
+                        FROM "children"
+                       GROUP BY "children"."parent_id") arlj_aggregate_children
+                  ON arlj_aggregate_children."parent_id" = "parents"."id"
+```
+
+`arlj_aggregate` currently uses a subquery to hide its aggregation. It's not the
+most efficient implementation but it does offer a much better chaining
+experience than using `group` at the top level.
+
+Arlj can also alias `arlj` and `arlj_aggregate` to `left_joins` and
+`left_joins_aggregate` respectively:
+
+```ruby
+class Parent < ActiveRecord::Base
+  extend Arlj::LeftJoins
+end
+
+Parent.left_joins(:children).group('records.id').select('COUNT(children.id)')
+Parent.left_joins_aggregate(:children, 'COUNT(*)', 'SUM(col)' => 'total')
+```
+
+## TODO
+
+* Relations with conditions
+* `LEFT JOIN [...] ON`
+* `has_and_belongs_to_many`
+* `has_many :through =>`
+
+## Contributing
+
+1. Fork it ( https://github.com/fengb/arlj/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,2 @@
+require "bundler/gem_tasks"
+

data/arlj.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'arlj/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'arlj'
+  spec.version       = Arlj::VERSION
+  spec.authors       = ['Benjamin Feng']
+  spec.email         = ['contact@fengb.info']
+  spec.summary       = %q{ActiveRecord Left Join}
+  spec.description   = %q{Make left joins feel like first-class citizens in ActiveRecord.}
+  spec.homepage      = 'https://github.com/fengb/arlj'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'activerecord', '>= 3.1'
+  spec.add_runtime_dependency 'memoist',      '~> 0.11.0'
+
+  spec.add_development_dependency 'bundler',  '~> 1.7'
+  spec.add_development_dependency 'rake',     '~> 10.0'
+  spec.add_development_dependency 'rspec',    '~> 3.0'
+  spec.add_development_dependency 'temping',  '~> 3.2'
+end

data/lib/arlj/left_joins.rb

@@ -0,0 +1,10 @@
+require 'arlj'
+
+module Arlj
+  module LeftJoins
+    include Arlj
+
+    alias_method :left_joins, :arlj
+    alias_method :left_joins_aggregate, :arlj_aggregate
+  end
+end

data/lib/arlj/version.rb

@@ -0,0 +1,3 @@
+module Arlj
+  VERSION = "0.0.1"
+end

data/lib/arlj.rb

@@ -0,0 +1,98 @@
+require 'memoist'
+
+module Arlj
+  autoload :LeftJoins, 'arlj/left_joins'
+  autoload :VERSION,   'arlj/version'
+
+  extend Memoist
+
+  def arlj(assoc)
+    # Example snippet:
+    #  LEFT JOIN [assoc]
+    #         ON [assoc].source_id = source.id
+
+    refl = reflect_on_association(assoc)
+    sources = arlj_arel_sources(refl.klass.arel_table, refl.foreign_key)
+    joins(sources)
+  end
+
+  # Example usage:
+  #   arlj_aggregate(other, 'count(*)', 'sum(col)' => target_name)
+  def arlj_aggregate(assoc, *args)
+    # Example snippet:
+    #  LEFT JOIN(SELECT source_id, [func]([column]) AS [target_name]
+    #              FROM [assoc]
+    #             GROUP BY [assoc].source_id) arlj_aggregate_[assoc]
+    #         ON [assoc].source_id = source.id
+
+    sources = arlj_aggregate_sources(assoc, *args)
+    joins(sources)
+  end
+
+  private
+
+  THUNK_PATTERN = /^([a-zA-Z]*)\((.*)\)$/
+  AGGREGATE_FUNCTIONS = {
+    'sum'     => 'sum',
+    'average' => 'average',
+    'avg'     => 'average',
+    'maximum' => 'maximum',
+    'max'     => 'maximum',
+    'minimum' => 'minimum',
+    'min'     => 'minimum',
+    'count'   => 'count',
+  }.freeze
+  def parse_thunk(refl, assoc, arel, thunk, name=nil)
+    matchdata = THUNK_PATTERN.match(thunk)
+    if matchdata.nil?
+      raise "'#{thunk}' not parsable - must be of format 'func(column)'"
+    end
+
+    func = AGGREGATE_FUNCTIONS[matchdata[1].downcase]
+    if func.nil?
+      raise "'#{matchdata[1]}' not recognized - must be one of #{AGGREGATE_FUNCTIONS.keys}"
+    end
+
+    if matchdata[2] == '*'
+      column = refl.active_record_primary_key
+      name ||= "#{assoc}_#{func}"
+    else
+      column = matchdata[2]
+      name ||= "#{assoc}_#{func}_#{column}"
+    end
+    arel[column].send(func).as(name)
+  end
+
+  def arlj_aggregate_sources(assoc, *args)
+    options = args.extract_options!
+
+    refl = reflect_on_association(assoc)
+    refl_arel = refl.klass.arel_table
+
+    join_name = "arlj_aggregate_#{refl.table_name}"
+
+    columns = [refl_arel[refl.foreign_key]]
+    args.each do |thunk|
+      columns << parse_thunk(refl, assoc, refl_arel, thunk)
+    end
+    options.each do |thunk, name|
+      columns << parse_thunk(refl, assoc, refl_arel, thunk, name)
+    end
+
+    subq_arel =
+      refl_arel.project(columns).
+                from(refl_arel).
+                group(refl_arel[refl.foreign_key]).
+                as(join_name)
+
+    arlj_arel_sources(subq_arel, refl.foreign_key)
+  end
+  memoize :arlj_aggregate_sources
+
+  def arlj_arel_sources(arel, foreign_key)
+    arel_join =
+      arel_table.join(arel, Arel::Nodes::OuterJoin).
+                   on(arel[foreign_key].eq(arel_table[self.primary_key]))
+    arel_join.join_sources
+  end
+end

data/spec/arlj_spec.rb

@@ -0,0 +1,69 @@
+require 'spec_helper'
+
+require 'arlj'
+require 'temping'
+
+RSpec.describe Arlj do
+  Temping.create :parent do
+    with_columns do |t|
+      t.string :name
+    end
+
+    extend Arlj
+
+    has_many :children
+  end
+
+  Temping.create :child do
+    with_columns do |t|
+      t.integer :parent_id
+      t.integer :col
+    end
+  end
+
+  before(:all) do
+    @parent = Parent.create(name: 'John')
+    (1..10).each do |n|
+      @parent.children.create(col: n)
+    end
+
+    @parent_no_child = Parent.create(name: 'Jane')
+  end
+
+  describe '#arlj' do
+    it 'joins the other table' do
+      counts = Parent.arlj(:children).
+                      group('parents.id').
+                      pluck('COUNT(children.id)')
+      assert{ counts.sort == [0, 10] }
+    end
+  end
+
+  describe '#arlj_aggregate' do
+    specify 'COUNT(*)' do
+      children_count = Parent.arlj_aggregate(:children, 'count(*)').pluck('children_count').first
+      assert{ children_count == @parent.children.size }
+    end
+
+    specify 'sum(col)' do
+      children_sum_col = Parent.arlj_aggregate(:children, 'SUM(col)').pluck('children_sum_col').first
+      assert{ children_sum_col == @parent.children.sum(:col) }
+    end
+
+    specify 'SUM(col) => name' do
+      sum = Parent.arlj_aggregate(:children, 'sum(col)' => 'sum').pluck('sum').first
+      assert{ sum == @parent.children.sum(:col) }
+    end
+
+    specify 'FAKE(col) raises error' do
+      error = rescuing{ Parent.arlj_aggregate(:children, 'FAKE(col)') }
+      assert{ error }
+    end
+
+    specify 'COUNT(*) => count, SUM(col) => sum' do
+      array = Parent.arlj_aggregate(:children, 'count(*)' => 'count', 'sum(col)' => 'sum').pluck('count', 'sum').first
+      assert{ array[0] == @parent.children.size }
+      assert{ array[1] == @parent.children.sum(:col) }
+    end
+  end
+end

data/spec/left_joins_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+require 'arlj/left_joins'
+
+RSpec.describe Arlj::LeftJoins do
+  class LjParent < Parent
+    extend Arlj::LeftJoins
+  end
+
+  specify '#left_joins does arlj stuff' do
+    counts = LjParent.left_joins(:children).
+                    group('parents.id').
+                    pluck('COUNT(children.id)')
+    assert{ counts.sort == [0, 10] }
+  end
+
+  specify '#left_joins_aggregate does arlj_aggregate stuff' do
+    children_count = LjParent.left_joins_aggregate(:children, 'count(*)').
+                              pluck('children_count').
+                              first
+    assert{ children_count == 10 }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'active_record'
+require 'wrong/adapters/rspec'
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+
+RSpec.configure do |c|
+  c.include Wrong
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: arlj
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Benjamin Feng
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: memoist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: temping
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: Make left joins feel like first-class citizens in ActiveRecord.
+email:
+- contact@fengb.info
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- arlj.gemspec
+- lib/arlj.rb
+- lib/arlj/left_joins.rb
+- lib/arlj/version.rb
+- spec/arlj_spec.rb
+- spec/left_joins_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/fengb/arlj
+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.2.2
+signing_key: 
+specification_version: 4
+summary: ActiveRecord Left Join
+test_files:
+- spec/arlj_spec.rb
+- spec/left_joins_spec.rb
+- spec/spec_helper.rb