order_as_specified 1.2 → 1.7

data/CHANGELOG.md

@@ -1,3 +1,37 @@
+# Unreleased (`master`)
+
+# 1.7
+
+This release adds support for `nil` values in the ordering list. Thanks to
+[yfulmes](https://github.com/yfulmes) for requesting this feature!
+
+# 1.6
+
+We are dropping official support for Ruby 2.3 and below, though they may
+continue to work.
+
+This release adds support for ordering by `Range`s. Big thanks to
+[Karl-Aksel Puulmann](https://github.com/macobo) for adding this functionality!
+
+# 1.5
+
+This release improves performance by switching to use `CASE` statements. Huge
+thanks to [Yen-Nan (Maso) Lin](https://github.com/masolin) for this improvement!
+
+# 1.4
+
+This release removes deprecation warnings for ActiveRecord 5.2 users, and drops
+support for ActiveRecord 4.x. Many thanks to
+[George Protacio-Karaszi](https://github.com/GeorgeKaraszi) for pointing out
+this issue!
+
+# 1.3
+
+This release adds support for ActiveRecord 5.1. Many thanks to
+[cohki0305](https://github.com/cohki0305) for identifying the issue,
+[Billy Ferguson](https://github.com/fergyfresh) for investigating it, and
+especially to [Alex Heeton](https://github.com/heeton) for fixing it.
+
 # 1.2
 
 This release contains an important change: `order_as_specified` is no longer

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+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, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at engineering@panoramaed.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -1,6 +1,12 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in order_as_specified.gemspec
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+# Specify your gem's dependencies in unique_attributes.gemspec
 gemspec
 
-gem "activerecord", ENV["AR_VERSION"] if ENV["AR_VERSION"]
+group :development do
+  gem "panolint", github: "panorama-ed/panolint", branch: "main"
+end

data/README.md

@@ -1,4 +1,7 @@
-[![Code Climate](https://codeclimate.com/github/panorama-ed/order_as_specified/badges/gpa.svg)](https://codeclimate.com/github/panorama-ed/order_as_specified) [![Test Coverage](https://codeclimate.com/github/panorama-ed/order_as_specified/badges/coverage.svg)](https://codeclimate.com/github/panorama-ed/order_as_specified) [![Build Status](https://travis-ci.org/panorama-ed/order_as_specified.svg)](https://travis-ci.org/panorama-ed/order_as_specified) [![Inline docs](http://inch-ci.org/github/panorama-ed/order_as_specified.png)](http://inch-ci.org/github/panorama-ed/order_as_specified) [![Gem Version](https://badge.fury.io/rb/order_as_specified.svg)](http://badge.fury.io/rb/order_as_specified)
+[![Code Coverage](https://codecov.io/gh/panorama-ed/order_as_specified/branch/master/graph/badge.svg)](https://codecov.io/gh/panorama-ed/order_as_specified)
+[![Build Status](https://travis-ci.com/panorama-ed/order_as_specified.svg)](https://travis-ci.com/panorama-ed/order_as_specified)
+[![Inline docs](http://inch-ci.org/github/panorama-ed/order_as_specified.png)](http://inch-ci.org/github/panorama-ed/order_as_specified)
+[![Gem Version](https://badge.fury.io/rb/order_as_specified.svg)](http://badge.fury.io/rb/order_as_specified)
 
 # OrderAsSpecified
 
@@ -26,8 +29,8 @@ TestObject.order_as_specified(language: ["es", "en", "fr"])
 
 Other gems like `ranked-model`, `acts_as_sortable`, etc. assume you want the
 same ordering each time, and store data to keep track of this in the database.
-They're great at what they do, but if your desired ordering changes, or if you
-don't always want an ordering, this gem is your friend.
+They're great at what they do, but if you want to change the ordering, or if
+you don't always want an ordering, this gem is your friend.
 
 ## Installation
 
@@ -139,6 +142,20 @@ TestObject.order_as_specified(language: ["fr", "es"])
    ]>
 ```
 
+The order can also include `nil` attributes:
+
+```ruby
+TestObject.order_as_specified(language: ["es", nil, "fr"])
+=> #<ActiveRecord::Relation [
+     #<TestObject id: 3, language: "es">,
+     #<TestObject id: 1, language: nil>,
+     #<TestObject id: 4, language: nil>,
+     #<TestObject id: 2, language: "fr">
+   ]>
+```
+
+### `distinct_on`
+
 In databases that support it (such as PostgreSQL), you can also use an option to
 add a `DISTINCT ON` to your query when you would otherwise have duplicates:
 
@@ -151,10 +168,32 @@ TestObject.order_as_specified(distinct_on: true, language: ["fr", "en"])
    ]>
 ```
 
-Note that if a `nil` value is passed in the ordering an error is raised, because
-databases do not have good or consistent support for ordering with `NULL` values
-in an arbitrary order, so we don't permit this behavior instead of allowing an
-unexpected result.
+### `case_insensitive`
+
+If you want objects to come back in an order that is case-insensitive, you can
+pass the `case_insensitive: true` value to the `order_as_specified` call, as in:
+
+```ruby
+TestObject.order_as_specified(case_insensitive: true, language: ["fr", "en"])
+=> #<ActiveRecord::Relation [
+     #<TestObject language: "fr">
+     #<TestObject language: "FR">
+     #<TestObject language: "EN">
+     #<TestObject language: "en">
+   ]>
+```
+
+## Limitations
+
+Databases may have limitations on the underlying number of fields you can have
+in an `ORDER BY` clause. For example, in PostgreSQL if you pass in more than
+1664 list elements you'll [receive this error](https://github.com/panorama-ed/order_as_specified/issues/34):
+
+```ruby
+PG::ProgramLimitExceeded: ERROR: target lists can have at most 1664 entries
+```
+
+That's a database limitation that this gem cannot avoid, unfortunately.
 
 ## Documentation
 
@@ -169,8 +208,7 @@ We have documentation on [RubyDoc](http://www.rubydoc.info/github/panorama-ed/or
 5. Create a new Pull Request
 
 **Make sure your changes have appropriate tests (`bundle exec rspec`)
-and conform to the Rubocop style specified.** We use
-[overcommit](https://github.com/causes/overcommit) to enforce good code.
+and conform to the Rubocop style specified.**
 
 ## License
 

data/RELEASING.md

@@ -0,0 +1,14 @@
+# Releasing
+
+## These are steps for the maintainer to take to release a new version of this gem.
+
+1. Create a new branch for bumping the version.
+1. On the new branch, update the VERSION constant in `lib/order_as_specified/version.rb`.
+1. Update the Changelog.
+1. Commit the change: `git add -A && git commit -m 'Bump to vX.X'`.
+1. Make a PR.
+1. Merge the PR.
+1. Add a tag: `git tag -am "vX.X" vX.X`.
+1. Push the tag: `git push --tags`
+1. Push to rubygems: `gem build order_as_specified.gemspec && gem push *.gem && rm *.gem`
+1. Celebrate!

data/lib/order_as_specified.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "order_as_specified/version"
 require "order_as_specified/error"
 
@@ -5,31 +7,44 @@ require "order_as_specified/error"
 # the database in an arbitrary order, without having to store anything extra
 # in the database. Simply `extend` it into your class and then you can use the
 # `order_as_specified` class method.
-
 module OrderAsSpecified
   # @param hash [Hash] the ActiveRecord arguments hash
   # @return [ActiveRecord::Relation] the objects, ordered as specified
   def order_as_specified(hash)
     distinct_on = hash.delete(:distinct_on)
+    case_insensitive = hash.delete(:case_insensitive)
+
     params = extract_params(hash)
+    return all if params[:values].empty?
 
-    table = connection.quote_table_name(params[:table])
-    attribute = connection.quote_column_name(params[:attribute])
+    table = Arel::Table.new(params[:table])
+    node = Arel::Nodes::Case.new
 
-    # We have to explicitly quote for now because SQL sanitization for ORDER BY
-    # queries isn't in less current versions of Rails.
-    # See: https://github.com/rails/rails/pull/13008
-    conditions = params[:values].map do |value|
-      raise OrderAsSpecified::Error, "Cannot order by `nil`" if value.nil?
+    params[:values].each_with_index do |value, index|
+      attribute = table[params[:attribute]]
+      condition =
+        if value.is_a?(Range)
+          if value.first >= value.last
+            raise OrderAsSpecified::Error, "Range needs to be increasing"
+          end
 
-      # Sanitize each value to reduce the risk of SQL injection.
-      "#{table}.#{attribute}=#{sanitize(value)}"
+          attribute.between(value)
+        elsif case_insensitive
+          attribute.matches(value)
+        else
+          attribute.eq(value)
+        end
+
+      node.when(condition).then(index)
     end
 
-    scope = order(conditions.map { |cond| "#{cond} DESC" }.join(", "))
+    node.else(node.conditions.size)
+    scope = order(Arel::Nodes::Ascending.new(table.grouping(node)))
 
     if distinct_on
-      scope = scope.select("DISTINCT ON (#{conditions.join(', ')}) #{table}.*")
+      distinct = Arel::Nodes::DistinctOn.new(node)
+      table_alias = connection.quote_table_name(table.name)
+      scope = scope.select(Arel.sql("#{distinct.to_sql} #{table_alias}.*"))
     end
 
     scope
@@ -43,13 +58,15 @@ module OrderAsSpecified
   # @param table [String/Symbol] the name of the table, default: the class table
   # @param hash [Hash] the ActiveRecord-style arguments, such as:
   #   { other_objects: { id: [1, 5, 3] } }
-  def extract_params(table = table_name, hash)
-    raise "Could not parse params" unless hash.size == 1
+  def extract_params(hash, table = table_name)
+    unless hash.size == 1
+      raise OrderAsSpecified::Error, "Could not parse params"
+    end
 
     key, val = hash.first
 
     if val.is_a? Hash
-      extract_params(key, hash[key])
+      extract_params(hash[key], key)
     else
       {
         table: table,

data/lib/order_as_specified/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OrderAsSpecified
   class Error < StandardError
   end

data/lib/order_as_specified/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OrderAsSpecified
-  VERSION = "1.2"
+  VERSION = "1.7"
 end

data/order_as_specified.gemspec

@@ -1,5 +1,6 @@
-# coding: utf-8
-lib = File.expand_path("../lib", __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "order_as_specified/version"
 
@@ -19,14 +20,16 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activerecord", ">= 4.0.1"
+  spec.add_dependency "activerecord", ">= 5.0.0"
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "mysql2"
+  spec.add_development_dependency "pg"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rspec-rails"
 
-  spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "codeclimate-test-reporter", "~> 0.4"
-  spec.add_development_dependency "overcommit", "~> 0.23"
-  spec.add_development_dependency "pg", ">= 0.18"
-  spec.add_development_dependency "rspec", "~> 3.2"
-  spec.add_development_dependency "rspec-rails", "~> 3.2"
-  spec.add_development_dependency "rubocop", "~> 0.29"
-  spec.add_development_dependency "sqlite3", ">= 1.3"
+  # Older versions of Rails locked in the SQLite3 version, so we have to
+  # explicitly specify the version here
+  sqlite3 = ENV["ACTIVERECORD_VERSION"] == "~> 5.0.0" ? "~> 1.3.13" : "~> 1.4"
+  spec.add_development_dependency "sqlite3", sqlite3
 end

data/spec/config/database.yml

@@ -5,5 +5,15 @@ sqlite3_test:
 
 postgresql_test:
   adapter: postgresql
+  host: localhost
   database: order_as_specified_test
   username: postgres
+  password: postgres
+
+mysql_test:
+  adapter: mysql2
+  host: 127.0.0.1
+  encoding: utf8
+  database: order_as_specified_test
+  username: mysql
+  password: mysql

data/spec/config/test_setup_migration.rb

@@ -1,9 +1,15 @@
-class TestSetupMigration < ActiveRecord::Migration
+# frozen_string_literal: true
+
+VersionedMigration = ActiveRecord::Migration[ActiveRecord::Migration.current_version] # rubocop:disable Layout/LineLength
+
+class TestSetupMigration < VersionedMigration
   def up
-    return if ActiveRecord::Base.connection.data_source_exists?(:test_classes)
+    db_connection = ActiveRecord::Base.connection
+    return if db_connection.try(:data_source_exists?, :test_classes)
 
     create_table :test_classes do |t|
       t.string :field
+      t.float :number_field
     end
 
     create_table :association_test_classes do |t|

data/spec/mysql_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "shared/order_as_specified_examples"
+require "config/test_setup_migration"
+
+RSpec.describe "MySQL" do
+  before :all do # rubocop:disable RSpec/BeforeAfterAll
+    ActiveRecord::Base.establish_connection(:mysql_test)
+    TestSetupMigration.migrate(:up)
+  end
+
+  after(:all) { ActiveRecord::Base.remove_connection } # rubocop:disable RSpec/BeforeAfterAll
+
+  include_examples ".order_as_specified"
+end

data/spec/order_as_specified_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Instead of defining specs here, we define them in
 # shared/order_as_specified_examples.rb. We then have a different spec file for
 # each supported database adapter, whch runs the shared RSpec tests found in

data/spec/postgresql_spec.rb

@@ -1,14 +1,16 @@
+# frozen_string_literal: true
+
 require "spec_helper"
 require "shared/order_as_specified_examples"
 require "config/test_setup_migration"
 
 RSpec.describe "PostgreSQL" do
-  before :all do
+  before :all do # rubocop:disable RSpec/BeforeAfterAll
     ActiveRecord::Base.establish_connection(:postgresql_test)
     TestSetupMigration.migrate(:up)
   end
 
-  after(:all) { ActiveRecord::Base.remove_connection }
+  after(:all) { ActiveRecord::Base.remove_connection } # rubocop:disable RSpec/BeforeAfterAll
 
   include_examples ".order_as_specified"
 
@@ -21,25 +23,28 @@ RSpec.describe "PostgreSQL" do
     end
 
     let(:shuffled_objects) do
-      fields = 3.times.map { |i| "Field #{i}" } * 2
-      5.times.map { |i| TestClass.create(field: fields[i]) }.shuffle
+      fields = Array.new(3) { |i| "Field #{i}" } * 2
+      Array.new(5) { |i| TestClass.create(field: fields[i]) }.shuffle
     end
 
     it "returns distinct objects" do
       expect(subject.length).to eq 3
     end
 
-    context "input safety" do
+    describe "input safety" do
       before(:each) { TestClass.create(field: "foo") }
 
       it "sanitizes column values" do
-        # Attempt to inject code to add a 'hi' field to each record. If the SQL inputs
-        # are properly sanitized, the code will be ignored and the returned model
-        # instances will not respond to #hi. If not, the code will execute and
-        # each of the returned model instances will have a #hi method to access the
-        # new field.
+        # Attempt to inject code to add a 'hi' field to each record. If the SQL
+        # inputs are properly sanitized, the code will be ignored and the
+        # returned model instances will not respond to #hi. If not, the code
+        # will execute and each of the returned model instances will have a #hi
+        #  method to access the new field.
         bad_value = "foo') field, 'hi'::varchar AS hi FROM test_classes --"
-        record = TestClass.order_as_specified(distinct_on: true, field: [bad_value]).to_a.first
+        record = TestClass.order_as_specified(
+          distinct_on: true,
+          field: [bad_value]
+        ).to_a.first
         expect(record).to_not respond_to(:hi)
       end
 
@@ -48,10 +53,17 @@ RSpec.describe "PostgreSQL" do
         quoted_table = AssociationTestClass.connection.quote_table_name(table)
 
         column = "id"
-        quoted_column = AssociationTestClass.connection.quote_column_name(column)
+        quoted_column = AssociationTestClass.
+                        connection.
+                        quote_column_name(column)
+
+        sql = TestClass.order_as_specified(
+          distinct_on: true,
+          table => { column => ["foo"] }
+        ).to_sql
 
-        sql = TestClass.order_as_specified(distinct_on: true, table => { column => ["foo"] }).to_sql
-        expect(sql).to include("DISTINCT ON (#{quoted_table}.#{quoted_column}")
+        pattern = /DISTINCT ON \(\s*CASE WHEN #{quoted_table}.#{quoted_column}/
+        expect(sql).to match(pattern)
       end
     end
   end