order_query 0.3.3 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 2139f5b59c57d0163c85a86b23b79a3e6fd00a28
-  data.tar.gz: e879b1b335c61133b122c014e49b01acb83c907d
+SHA256:
+  metadata.gz: 6b0284712fbd8e451e7bb4f41a81dc410c8141bc6e3d670dae192e02565bfb9f
+  data.tar.gz: 6b76ba2002e94c9f320f124ac4ba12bf786e213f9f7fcbcae20ae47402054dce
 SHA512:
-  metadata.gz: a8c33923361af77ea70eaf89eed9486122ff82e70ebcb8dae13d8ee273155e0075a0207e59a7dc276a9d335548830b6a768db1575cc657e2d64c3ad58cbade63
-  data.tar.gz: a42483806ef779802cf97467ebd53fa95e2e97639ce709e51564320ae184e09274a6aaa001f5c7a4414897e4c6918816d5b680466fd6b784c2384bc288167272
+  metadata.gz: ddae4f82c3df302d84d2a7402aa5cc0aa2e6b4706a6d104b296ab5a33d036a121839fd01f42291364cc83347cc63e4a25e6776cbf776cf7e9c3e307818919f79
+  data.tar.gz: c1887c00922ab788bf659111e8ac55f7843c7a6dadfdf2d7948ca5ca1dd08a272142658e735c276d1b54c02b2fefb1d8fda1ebe49498d54cd76bc35435bda12a

data/CHANGES.md

@@ -1,3 +1,37 @@
+## 0.5.1
+
+* Rails 6.1 now supported.
+## 0.5.0
+
+* Rails 6 now supported.
+* Fixes support for `nil`s with explicit order, when a `nil` is neither
+  the first nor the last element of the explicit order,
+  e.g. `status: ['assigned', nil, 'fixed']`.
+  [#93b08877](https://github.com/glebm/order_query/commit/93b08877790a0ff02eea0d835def6ff3c40a83da)
+
+## 0.4.1
+
+* If a column had a `nulls:` option and there were multiple records with `NULL`,
+  all of these records but one were previously skipped. This is now fixed.
+  [#21](https://github.com/glebm/order_query/issues/21)
+
+## 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 
+  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)`.
+
+## 0.3.3
+
+* Now compatible with Rails 5 beta 1.
+
 ## 0.3.2
 
 * Optimization: do not wrap top-level disjunctive in `AND` when the column has an enumerated order. [Read more](https://github.com/glebm/order_query/issues/3#issuecomment-54764638).

data/Gemfile

@@ -1,5 +1,6 @@
-source 'https://rubygems.org'
+# frozen_string_literal: true
 
-gemspec
+source 'https://rubygems.org'
 
-eval_gemfile './shared.gemfile'
+eval_gemfile 'spec/gemfiles/rails_6_1.gemfile'
+eval_gemfile 'rubocop.gemfile'

data/MIT-LICENSE

@@ -1,4 +1,6 @@
-Copyright 2014 Gleb Mazovetskiy
+Copyright (c) 2014-2017 Gleb Mazovetskiy
+
+MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

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.3'
+gem 'order_query', '~> 0.5.1'
 ```
 
 ## 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,6 +68,18 @@ p.next     #=> #<Post>
 p.position #=> 5
 ```
 
+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
@@ -170,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,39 +1,49 @@
+# 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'
   require 'shellwords'
-  cmd      = 'bundle --quiet && bundle exec rake --trace'
+  cmd      = 'bundle install --quiet && bundle exec rake --trace'
   statuses = Dir.glob('./spec/gemfiles/*{[!.lock]}').map do |gemfile|
-    env = {'BUNDLE_GEMFILE' => gemfile}
-    cmd_with_env = "  (#{env.map { |k, v| "export #{k}=#{Shellwords.escape v}" } * ' '}; #{cmd})"
-    $stderr.puts "Testing\n#{cmd_with_env}"
-    PTY.spawn(env, cmd) do |r, _w, pid|
-      begin
-        r.each_line { |l| puts l }
-      rescue Errno::EIO
-        # Errno:EIO error means that the process has finished giving output.
-      ensure
-        ::Process.wait pid
+    Bundler.with_clean_env do
+      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 # rubocop:disable Lint/HandleExceptions
+          # Errno:EIO error means that the process has finished giving output.
+        ensure
+          ::Process.wait pid
+        end
       end
+      [$CHILD_STATUS&.exitstatus&.zero?, gemfile]
     end
-    [$? && $?.exitstatus == 0, cmd_with_env]
   end
-  failed_cmds = statuses.reject(&:first).map { |(_status, cmd_with_env)| cmd_with_env }
-  if failed_cmds.empty?
-    $stderr.puts '✓ Tests pass with all gemfiles'
+  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_cmds.size} / #{statuses.size})\n#{failed_cmds * "\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,45 +1,94 @@
-# 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&.include?(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']
-    def enum_side(value, side, strict = true)
+    def enum_side(value, side, strict = true) # rubocop:disable Metrics/AbcSize
       ord = order_enum
       pos = ord.index(value)
       if pos
@@ -57,11 +106,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