order_query 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5665c0c52a581228b9afdc57825cd1cfbec7dcae
-  data.tar.gz: a125032c1dfef35a5dfb251c0b4fb4d4f326c1d6
+  metadata.gz: d3d5bb8b4f22e2ed2f205ed413e75a41edd4348d
+  data.tar.gz: 1f216dcc1ec1d112126c68af4a20e28e949663de
 SHA512:
-  metadata.gz: 4a5e1c93db80ef5b81da56f2e551f283ac86c3502df3caf73b0f75f717c4a5cb42e7e31dcc9223eb2b05f565db05f57b613b85c5b6da04629708e1eba657d7b3
-  data.tar.gz: 94809f7775c4634d6f933095cc4671957d0c9fc17b7b7036adbf4c1d6c89b7c4ae9a45dace66c88cc0c42ae0610ff9f335ab7bf7721c4908c34da8aa5a7f8c5c
+  metadata.gz: c3f31357b9b6c3d53d3003c90fdce074bb80bd8f314d81c34e2f096da1d61b18d79b9ea053d3f103c11d962daa155ff4b941c54c23e1b91e7d3d170a43afc054
+  data.tar.gz: c1c644de117104e827dbc58422c313f77d892f2d6671533e852fa4e64ae26feb57274a1415b1f9a30696f943541501e522b6de7fd36f060fee1eb880ba165388

data/CHANGES.md

@@ -1,3 +1,9 @@
+## 0.4.0
+
+* Adds nulls ordering options `nulls: :first` and `nulls: :last`.
+* Now supports Rails 5.2.
+* Dropped support for Rails < 5 and Ruby < 2.3.
+
 ## 0.3.4
 
 * The `before` and `after` methods now accept a boolean argument that indicates 

data/Gemfile

@@ -1,5 +1,12 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec
 
+# TODO: remove these lines and update spec/gemfiles/rails_5_2.gemfile once
+#   Rails 5.2 is out.
+gem 'activerecord', '~> 5.2.0.rc1'
+gem 'activesupport', '~> 5.2.0.rc1'
+
 eval_gemfile './shared.gemfile'

data/README.md

@@ -1,4 +1,4 @@
-# order_query [![Build Status][travis-badge]][travis] [![Code Climate][codeclimate-badge]][codeclimate] [![Coverage Status][coverage-badge]][coverage]
+# order_query [![Build Status][travis-badge]][travis] [![Coverage Status][coverage-badge]][coverage]
 
 <a href="http://use-the-index-luke.com/no-offset">
   <img src="http://use-the-index-luke.com/img/no-offset.q200.png" alt="100% offset-free" align="right" width="106" height="106">
@@ -11,33 +11,35 @@ This gem finds the next or previous record(s) relative to the current one effici
 Add to Gemfile:
 
 ```ruby
-gem 'order_query', '~> 0.3.4'
+gem 'order_query', '~> 0.4.0'
 ```
 
 ## Usage
 
-Define a named list of attributes to order by with `order_query(name, *order)`:
+Use `order_query(scope_name, *order_option)` to create scopes and class methods
+in your model and specify how you want results ordered. A basic example:
 
 ```ruby
 class Post < ActiveRecord::Base
   include OrderQuery
   order_query :order_home,
-    [:pinned, [true, false]],
-    [:published_at, :desc]
+    [:pinned, [true, false]], # First sort by :pinned over t/f in :desc order
+    [:published_at, :desc] # Next sort :published_at in :desc order
 end
 ```
 
-Each attributes is specified as:
+Each order option specified in `order_query` is an array in the following form:
 
-1. Attribute name.
-2. Optionally, values to order by, such as `%w(high medium low)` or `[true, false]`.
-3. Sort direction, `:asc` or `:desc`. Default: `:asc`; `:desc` when values to order by are specified.
-4. Options:
+1. Symbol of the attribute name (required).
+2. An array of values to order by, such as `%w(high medium low)` or `[true, false]` (optional).
+3. Sort direction, `:asc` or `:desc` (optional). Default: `:asc`; `:desc` when values to order by are specified.
+4. A hash (optional):
 
 | option     | description                                                                |
 |------------|----------------------------------------------------------------------------|
 | unique     | Unique attribute. Default: `true` for primary key, `false` otherwise.      |
 | sql        | Customize column SQL.                                                      |
+| nulls      | If set to `:first` or `:last`, orders `NULL`s accordingly.                 |
 
 If no unique column is specified, `[primary_key, :asc]` is used. Unique column must be last.
 
@@ -66,11 +68,18 @@ p.next     #=> #<Post>
 p.position #=> 5
 ```
 
-The `before` and `after` methods also accept a boolean argument that indicates 
+The `before` and `after` methods also accept a boolean argument that indicates
 whether the relation should exclude the given point or not.
 By default the given point is excluded, if you want to include it,
 use `before(false)` / `after(false)`.
 
+If you want to obtain only a chunk (i.e., a page), use `before` or `after`
+with ActiveRecord's `limit` method:
+
+```ruby
+p.after.limit(20) #=> #<ActiveRecord::Relation>
+```
+
 Looping to the first / last record is enabled for `next` / `previous` by default. Pass `false` to disable:
 
 ```ruby
@@ -175,7 +184,5 @@ This project uses MIT license.
 [travis]: http://travis-ci.org/glebm/order_query
 [travis-badge]: http://img.shields.io/travis/glebm/order_query.svg
 [gemnasium]: https://gemnasium.com/glebm/order_query
-[codeclimate]: https://codeclimate.com/github/glebm/order_query
-[codeclimate-badge]: http://img.shields.io/codeclimate/github/glebm/order_query.svg
 [coverage]: https://codeclimate.com/github/glebm/order_query
-[coverage-badge]: https://codeclimate.com/github/glebm/order_query/badges/coverage.svg
+[coverage-badge]: https://api.codeclimate.com/v1/badges/82e424e9ee2acb02292c/test_coverage

data/Rakefile

@@ -1,14 +1,19 @@
+# frozen_string_literal: true
+
 begin
   require 'bundler/setup'
 rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
+require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
 
+# rubocop:disable Metrics/BlockLength,Style/StderrPuts
+
 desc 'Test all Gemfiles from spec/*.gemfile'
 task :test_all_gemfiles do
   require 'pty'
@@ -16,25 +21,29 @@ task :test_all_gemfiles do
   cmd      = 'bundle install --quiet && bundle exec rake --trace'
   statuses = Dir.glob('./spec/gemfiles/*{[!.lock]}').map do |gemfile|
     Bundler.with_clean_env do
-      env = {'BUNDLE_GEMFILE' => gemfile}
-      $stderr.puts "Testing #{File.basename(gemfile)}:\n  export #{env.map { |k, v| "#{k}=#{Shellwords.escape v}" } * ' '}; #{cmd}"
+      env = { 'BUNDLE_GEMFILE' => gemfile }
+      $stderr.puts "Testing #{File.basename(gemfile)}:
+  export #{env.map { |k, v| "#{k}=#{Shellwords.escape v}" } * ' '}; #{cmd}"
       PTY.spawn(env, cmd) do |r, _w, pid|
         begin
           r.each_line { |l| puts l }
-        rescue Errno::EIO
+        rescue Errno::EIO # rubocop:disable Lint/HandleExceptions
           # Errno:EIO error means that the process has finished giving output.
         ensure
           ::Process.wait pid
         end
       end
-      [$? && $?.exitstatus == 0, gemfile]
+      [$CHILD_STATUS&.exitstatus&.zero?, gemfile]
     end
   end
-  failed_gemfiles = statuses.reject(&:first).map { |(_status, gemfile)| gemfile }
+  failed_gemfiles = statuses.reject(&:first).map { |(_, gemfile)| gemfile }
   if failed_gemfiles.empty?
     $stderr.puts "✓ Tests pass with all #{statuses.size} gemfiles"
   else
-    $stderr.puts "❌ FAILING (#{failed_gemfiles.size} / #{statuses.size})\n#{failed_gemfiles * "\n"}"
+    $stderr.puts "❌ FAILING (#{failed_gemfiles.size} / #{statuses.size})
+#{failed_gemfiles * "\n"}"
     exit 1
   end
 end
+
+# rubocop:enable Metrics/BlockLength,Style/StderrPuts

data/lib/order_query.rb

@@ -1,12 +1,17 @@
+# frozen_string_literal: true
+
 require 'active_support'
 require 'active_record'
 require 'order_query/space'
 require 'order_query/point'
 
+# This gem finds the next or previous record(s) relative to the current one
+# efficiently using keyset pagination, e.g. for navigation or infinite scroll.
 module OrderQuery
   extend ActiveSupport::Concern
 
-  # @param [ActiveRecord::Relation] scope optional first argument (default: self.class.all)
+  # @param [ActiveRecord::Relation] scope optional first argument
+  #   (default: self.class.all)
   # @param [Array<Array<Symbol,String>>, OrderQuery::Spec] order_spec
   # @return [OrderQuery::Point]
   # @example
@@ -15,13 +20,15 @@ module OrderQuery
   #   next_user = user.seek(users, [:activated_at, :desc], [:id, :desc]).next
   def seek(*spec)
     fst = spec.first
-    if fst.nil? || fst.is_a?(ActiveRecord::Relation) || fst.is_a?(ActiveRecord::Base)
+    if fst.nil? || fst.is_a?(ActiveRecord::Relation) ||
+       fst.is_a?(ActiveRecord::Base)
       scope = spec.shift
     end
     scope ||= self.class.all
     scope.seek(*spec).at(self)
   end
 
+  # Top-level functions.
   module ClassMethods
     # @return [OrderQuery::Space]
     def seek(*spec)
@@ -31,7 +38,9 @@ module OrderQuery
     end
 
     #= DSL
+
     protected
+
     # @param [Symbol] name
     # @param [Array<Array<Symbol,String>>] order_spec
     # @example
@@ -60,7 +69,7 @@ module OrderQuery
     #     #<OrderQuery::Point...>
     def order_query(name, *spec)
       define_singleton_method(:"#{name}_space") { seek(*spec) }
-      class_eval <<-RUBY, __FILE__, __LINE__
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
         scope :#{name}, -> { #{name}_space.scope }
         scope :#{name}_reverse, -> { #{name}_space.scope_reverse }
         def self.#{name}_at(record)

data/lib/order_query/column.rb

@@ -1,41 +1,89 @@
-# coding: utf-8
+# frozen_string_literal: true
+
 require 'order_query/direction'
+require 'order_query/nulls_direction'
 require 'order_query/sql/column'
 module OrderQuery
   # An order column (sort column)
   class Column
-    attr_reader :name, :order_enum, :options
-    delegate :column_name, :quote, to: :@sql
+    attr_reader :name, :order_enum, :custom_sql
+    delegate :column_name, :quote, :scope, to: :@sql_builder
 
-    # @option spec [String] :unique    Mark the attribute as unique to avoid redundant columns
-    def initialize(spec, scope)
-      spec       = spec.dup
-      options    = spec.extract_options!
-      @name      = spec[0]
-      if spec[1].is_a?(Array)
-        @order_enum = spec.delete_at(1)
-        spec[1] ||= :desc
-      end
-      @direction = Direction.parse!(spec[1] || :asc)
-      @options   = options.reverse_merge(
-          unique:   name.to_s == scope.primary_key,
-          complete: true
+    # rubocop:disable Metrics/ParameterLists,Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    # rubocop:disable Metrics/MethodLength
+
+    # @param scope [ActiveRecord::Relation]
+    # @param attr_name [Symbol] the name of the column, or the method providing
+    #   the value to sort by.
+    # @param vals_and_or_dir [Array] optionally, values in the desired order,
+    #   and / or one of `:asc`, `:desc`. Default order is `:desc` if the values
+    #   are given (so the result is ordered like the values), `:asc` otherwise.
+    # @param unique [Boolean] mark the attribute as unique to avoid redundant
+    #   columns. Default: `true` for primary key.
+    # @param nulls [:first, :last, false] whether to consider NULLS to be
+    #   ordered first or last. If false, assumes that a column is not nullable
+    #   and raises [Errors::NonNullableColumnIsNullError] if a null is
+    #   encountered.
+    # @param sql [String, nil] a custom sql fragment.
+    def initialize(scope, attr_name, *vals_and_or_dir,
+                   unique: nil, nulls: false, sql: nil)
+      @name = attr_name
+      @order_enum = vals_and_or_dir.shift if vals_and_or_dir[0].is_a?(Array)
+      @direction = Direction.parse!(
+        vals_and_or_dir.shift || (@order_enum ? :desc : :asc)
       )
-      @unique    = @options[:unique]
-      @sql       = SQL::Column.new(self, scope)
+      unless vals_and_or_dir.empty?
+        fail ArgumentError,
+             "extra arguments: #{vals_and_or_dir.map(&:inspect) * ', '}"
+      end
+      @unique = unique.nil? ? (name.to_s == scope.primary_key) : unique
+      if @order_enum && (@order_enum[0].nil? || @order_enum[-1].nil?)
+        fail ArgumentError, '`nulls` cannot be set if a value is null' if nulls
+        @nullable = true
+        @nulls = if @order_enum[0].nil?
+                   @direction == :desc ? :first : :last
+                 else
+                   @direction == :desc ? :last : :first
+                 end
+      else
+        @nullable = !!nulls # rubocop:disable Style/DoubleNegation
+        @nulls = NullsDirection.parse!(
+          nulls || NullsDirection.default(scope, @direction)
+        )
+      end
+      @custom_sql = sql
+      @sql_builder = SQL::Column.new(scope, self)
     end
+    # rubocop:enable Metrics/ParameterLists,Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    # rubocop:enable Metrics/MethodLength
 
     def direction(reverse = false)
       reverse ? Direction.reverse(@direction) : @direction
     end
 
+    # @return [:first, :last]
+    def nulls_direction(reverse = false)
+      reverse ? NullsDirection.reverse(@nulls) : @nulls
+    end
+
+    # @return [:first, :last]
+    def default_nulls_direction(reverse = false)
+      NullsDirection.default(scope, direction(reverse))
+    end
+
+    def nullable?
+      @nullable
+    end
+
     def unique?
       @unique
     end
 
     # @param [Object] value
     # @param [:before, :after] side
-    # @return [Array] valid order values before / after passed (depending on the side)
+    # @return [Array] valid order values before / after the given value.
     # @example for [:difficulty, ['Easy', 'Normal', 'Hard']]:
     #  enum_side('Normal', :after) #=> ['Hard']
     #  enum_side('Normal', :after, false) #=> ['Normal', 'Hard']
@@ -57,11 +105,11 @@ module OrderQuery
 
     def inspect
       parts = [
-          @name,
-          (@order_enum.inspect if order_enum),
-          ('unique' if @unique),
-          (column_name if options[:sql]),
-          @direction
+        @name,
+        (@order_enum.inspect if order_enum),
+        ('unique' if @unique),
+        (column_name if @custom_sql),
+        @direction
       ].compact
       "(#{parts.join(' ')})"
     end

data/lib/order_query/direction.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 module OrderQuery
   # Responsible for handling :asc and :desc
   module Direction
-    extend self
+    module_function
 
-    DIRECTIONS = [:asc, :desc].freeze
+    DIRECTIONS = %i[asc desc].freeze
 
     def all
       DIRECTIONS
@@ -15,14 +17,14 @@ module OrderQuery
       all[(all.index(direction) + 1) % 2].to_sym
     end
 
-    # @param [:asc, :desc, String] direction
+    # @param [:asc, :desc] direction
     # @raise [ArgumentError]
     # @return [:asc, :desc]
     def parse!(direction)
-      if all.include?(direction)
-        direction
-      end or
-          raise ArgumentError.new("sort direction must be in #{all.map(&:inspect).join(', ')}, is #{direction.inspect}")
+      all.include?(direction) && direction or
+        fail ArgumentError,
+             "sort direction must be in #{all.map(&:inspect).join(', ')}, "\
+             "is #{direction.inspect}"
     end
   end
 end

data/lib/order_query/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OrderQuery
+  # All the exceptions that can be raised by order query methods.
+  module Errors
+    # Raised when a column that OrderQuery assumes to never contain NULLs
+    # contains a null.
+    class NonNullableColumnIsNullError < RuntimeError
+    end
+  end
+end

data/lib/order_query/nulls_direction.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OrderQuery
+  # Handles nulls :first and :last direction.
+  module NullsDirection
+    module_function
+
+    DIRECTIONS = %i[first last].freeze
+
+    def all
+      DIRECTIONS
+    end
+
+    # @param [:first, :last] direction
+    # @return [:first, :last]
+    def reverse(direction)
+      all[(all.index(direction) + 1) % 2].to_sym
+    end
+
+    # @param [:first, :last] direction
+    # @raise [ArgumentError]
+    # @return [:first, :last]
+    def parse!(direction)
+      all.include?(direction) && direction or
+        fail ArgumentError,
+             "`nulls` must be in #{all.map(&:inspect).join(', ')}, "\
+             "is #{direction.inspect}"
+    end
+
+    # @param scope [ActiveRecord::Relation]
+    # @param dir [:asc, :desc]
+    # @return [:first, :last] the default nulls order, based on the given
+    #   scope's connection adapter name.
+    def default(scope, dir)
+      case scope.connection_config[:adapter]
+      when /mysql|maria|sqlite|sqlserver/i
+        (dir == :asc ? :first : :last)
+      else
+        # Oracle, Postgres
+        (dir == :asc ? :last : :first)
+      end
+    end
+  end
+end

data/lib/order_query/point.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 require 'order_query/space'
 require 'order_query/sql/where'
+require 'order_query/errors'
 
 module OrderQuery
   # Search around a record in an order space
@@ -15,7 +18,8 @@ module OrderQuery
       @where_sql = SQL::Where.new(self)
     end
 
-    # @params [true, false] loop if true, consider last and first as adjacent (unless they are equal)
+    # @param [true, false] loop if true, loops as if the last and the first
+    #   records were adjacent, unless there is only one record.
     # @return [ActiveRecord::Base]
     def next(loop = true)
       unless_record_eq after.first || (first if loop)
@@ -31,20 +35,23 @@ module OrderQuery
       space.count - after.count
     end
 
-    # @param [true, false] strict choose if the given scope should include or not the record, default not to include it (strict true)
+    # @param [true, false] strict if false, the given scope will include the
+    #   record at this point.
     # @return [ActiveRecord::Relation]
     def after(strict = true)
       side :after, strict
     end
 
-    # @param [true, false] strict choose if the given scope should include or not the record, default not to include it (strict true)
+    # @param [true, false] strict if false, the given scope will include the
+    #   record at this point.
     # @return [ActiveRecord::Relation]
     def before(strict = true)
       side :before, strict
     end
 
     # @param [:before, :after] side
-    # @param [true, false] strict choose if the given scope should include or not the record, default not to include it (strict true)
+    # @param [true, false] strict if false, the given scope will include the
+    #   record at this point.
     # @return [ActiveRecord::Relation]
     def side(side, strict = true)
       query, query_args = @where_sql.build(side, strict)
@@ -56,8 +63,15 @@ module OrderQuery
       scope.where(query, *query_args)
     end
 
-    def value(cond)
-      record.send(cond.name)
+    # @param column [Column]
+    def value(column)
+      v = record.send(column.name)
+      if v.nil? && !column.nullable?
+        fail Errors::NonNullableColumnIsNullError,
+             "Column #{column.inspect} is NULL on record #{@record.inspect}. "\
+             'Set the `nulls` option to :first or :last.'
+      end
+      v
     end
 
     def inspect