order_query 0.3.3 → 0.5.1

data/lib/order_query/nulls_direction.rb

@@ -0,0 +1,53 @@
+# 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 connection_adapter(scope)
+      when /mysql|maria|sqlite|sqlserver/i
+        (dir == :asc ? :first : :last)
+      else
+        # Oracle, Postgres
+        (dir == :asc ? :last : :first)
+      end
+    end
+
+    def connection_adapter(scope)
+      if scope.respond_to?(:connection_db_config)
+        # Rails >= 6.1.0
+        scope.connection_db_config.adapter
+      else
+        scope.connection_config[:adapter]
+      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,26 @@ module OrderQuery
       space.count - after.count
     end
 
+    # @param [true, false] strict if false, the given scope will include the
+    #   record at this point.
     # @return [ActiveRecord::Relation]
-    def after
-      side :after
+    def after(strict = true)
+      side :after, strict
     end
 
+    # @param [true, false] strict if false, the given scope will include the
+    #   record at this point.
     # @return [ActiveRecord::Relation]
-    def before
-      side :before
+    def before(strict = true)
+      side :before, strict
     end
 
     # @param [:before, :after] side
+    # @param [true, false] strict if false, the given scope will include the
+    #   record at this point.
     # @return [ActiveRecord::Relation]
-    def side(side)
-      query, query_args = @where_sql.build(side)
+    def side(side, strict = true)
+      query, query_args = @where_sql.build(side, strict)
       scope = if side == :after
                 space.scope
               else
@@ -53,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

data/lib/order_query/space.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'order_query/column'
 require 'order_query/sql/order_by'
 module OrderQuery
@@ -8,14 +10,20 @@ module OrderQuery
     delegate :count, :empty?, to: :@base_scope
 
     # @param [ActiveRecord::Relation] base_scope
-    # @param [Array<Array<Symbol,String>>, OrderQuery::Spec] order_spec
+    # @param [Array<Array<Symbol,String>>] order_spec
+    # @see Column#initialize for the order_spec element format.
     def initialize(base_scope, order_spec)
-      @base_scope   = base_scope
-      @columns   = order_spec.map { |cond_spec| Column.new(cond_spec, base_scope) }
+      @base_scope = base_scope
+      @columns = order_spec.map do |cond_spec|
+        Column.new(base_scope, *cond_spec)
+      end
       # add primary key if columns are not unique
       unless @columns.last.unique?
-        raise ArgumentError.new('Unique column must be last') if @columns.detect(&:unique?)
-        @columns << Column.new([base_scope.primary_key], base_scope)
+        if @columns.detect(&:unique?)
+          fail ArgumentError, 'Unique column must be last'
+        end
+
+        @columns << Column.new(base_scope, base_scope.primary_key)
       end
       @order_by_sql = SQL::OrderBy.new(@columns)
     end
@@ -27,12 +35,13 @@ module OrderQuery
 
     # @return [ActiveRecord::Relation] scope ordered by columns
     def scope
-      @scope ||= @base_scope.order(@order_by_sql.build)
+      @scope ||= @base_scope.order(Arel.sql(@order_by_sql.build))
     end
 
     # @return [ActiveRecord::Relation] scope ordered by columns in reverse
     def scope_reverse
-      @scope_reverse ||= @base_scope.order(@order_by_sql.build_reverse)
+      @scope_reverse ||= @base_scope
+                         .order(Arel.sql(@order_by_sql.build_reverse))
     end
 
     # @return [ActiveRecord::Base]
@@ -46,7 +55,8 @@ module OrderQuery
     end
 
     def inspect
-      "#<OrderQuery::Space @columns=#{@columns.inspect} @base_scope=#{@base_scope.inspect}>"
+      "#<OrderQuery::Space @columns=#{@columns.inspect} "\
+      "@base_scope=#{@base_scope.inspect}>"
     end
   end
 end

data/lib/order_query/sql/column.rb

@@ -1,20 +1,24 @@
+# frozen_string_literal: true
+
 module OrderQuery
   module SQL
+    # A column in the given scope.
     class Column
-      attr_reader :column, :scope
+      attr_reader :scope, :column
 
-      def initialize(column, scope)
-        @column = column
+      def initialize(scope, column)
         @scope = scope
+        @column = column
       end
 
       def column_name
         @column_name ||= begin
-          sql = column.options[:sql]
+          sql = column.custom_sql
           if sql
             sql.respond_to?(:call) ? sql.call : sql
           else
-            connection.quote_table_name(scope.table_name) + '.' + connection.quote_column_name(column.name)
+            "#{connection.quote_table_name(scope.table_name)}."\
+            "#{connection.quote_column_name(column.name)}"
           end
         end
       end

data/lib/order_query/sql/order_by.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 module OrderQuery
   module SQL
+    # Constructs SQL for ORDER BY.
     class OrderBy
       # @param [Array<Column>]
       def initialize(columns)
@@ -31,23 +34,65 @@ module OrderQuery
         end
       end
 
-      def column_clause_ray(col, reverse = false)
-        "#{col.column_name} #{sort_direction_sql(col, reverse)}".freeze
+      def column_clause_ray(col, reverse = false,
+                            with_null_clause = needs_null_sort?(col, reverse))
+        clauses = []
+        # TODO: use NULLS FIRST/LAST where supported.
+        clauses << order_by_nulls_sql(col, reverse) if with_null_clause
+        clauses << "#{col.column_name} #{sort_direction_sql(col, reverse)}"
+        clauses.join(', ').freeze
       end
 
+      # rubocop:disable Metrics/AbcSize
+
       def column_clause_enum(col, reverse = false)
-        enum = col.order_enum
-        # Collapse boolean enum to `ORDER BY column ASC|DESC`
-        if enum == [false, true] || enum == [true, false]
-          return column_clause_ray col, reverse ^ enum.last
+        # Collapse booleans enum to `ORDER BY column ASC|DESC`
+        return optimize_enum_bools(col, reverse) if optimize_enum_bools?(col)
+        if optimize_enum_bools_nil?(col)
+          return optimize_enum_bools_nil(col, reverse)
+        end
+
+        clauses = []
+        with_nulls = false
+        if col.order_enum.include?(nil)
+          with_nulls = true
+        elsif needs_null_sort?(col, reverse)
+          clauses << order_by_nulls_sql(col, reverse)
+        end
+        clauses.concat(col.order_enum.map do |v|
+          "#{order_by_value_sql col, v, with_nulls} " \
+            "#{sort_direction_sql(col, reverse)}"
+        end)
+        clauses.join(', ').freeze
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def needs_null_sort?(col, reverse,
+                           nulls_direction = col.nulls_direction(reverse))
+        return false unless col.nullable?
+
+        nulls_direction != col.default_nulls_direction(reverse)
+      end
+
+      def order_by_nulls_sql(col, reverse)
+        if col.default_nulls_direction !=
+           (col.direction == :asc ? :first : :last)
+          reverse = !reverse
         end
-        enum.map { |v|
-          "#{order_by_value_sql col, v} #{sort_direction_sql(col, reverse)}"
-        }.join(', ').freeze
+        "#{col.column_name} IS NULL #{sort_direction_sql(col, reverse)}"
       end
 
-      def order_by_value_sql(col, v)
-        "#{col.column_name}=#{col.quote v}"
+      def order_by_value_sql(col, v, with_nulls = false)
+        if with_nulls
+          if v.nil?
+            "#{col.column_name} IS NULL"
+          else
+            "#{col.column_name} IS NOT NULL AND " \
+               "#{col.column_name}=#{col.quote v}"
+          end
+        else
+          "#{col.column_name}=#{col.quote v}"
+        end
       end
 
       # @return [String]
@@ -59,6 +104,35 @@ module OrderQuery
       def join_order_by_clauses(clauses)
         clauses.join(', ').freeze
       end
+
+      private
+
+      def optimize_enum_bools?(col)
+        col.order_enum == [false, true] || col.order_enum == [true, false]
+      end
+
+      def optimize_enum_bools(col, reverse)
+        column_clause_ray(col, col.order_enum[-1] ^ reverse)
+      end
+
+      ENUM_SET_TRUE_FALSE_NIL = Set[false, true, nil]
+
+      def optimize_enum_bools_nil?(col)
+        Set.new(col.order_enum) == ENUM_SET_TRUE_FALSE_NIL &&
+          !col.order_enum[1].nil?
+      end
+
+      def optimize_enum_bools_nil(col, reverse)
+        last_bool_true = if col.order_enum[-1].nil?
+                           col.order_enum[-2]
+                         else
+                           col.order_enum[-1]
+                         end
+        reverse_override = last_bool_true ^ reverse
+        with_nulls_sort =
+          needs_null_sort?(col, reverse_override, col.nulls_direction(reverse))
+        column_clause_ray(col, reverse_override, with_nulls_sort)
+      end
     end
   end
 end

data/lib/order_query/sql/where.rb

@@ -1,7 +1,8 @@
-# coding: utf-8
+# frozen_string_literal: true
+
 module OrderQuery
   module SQL
-    # Build where clause for searching around a record in an order space
+    # Builds where clause for searching around a record in an order space.
     class Where
       attr_reader :point
 
@@ -13,19 +14,24 @@ module OrderQuery
 
       # Join column pairs with OR, and nest within each other with AND
       # @param [:before or :after] side
-      # @return [query, parameters] WHERE columns matching records strictly before / after this one
+      # @return [query, parameters] WHERE columns matching records strictly
+      #   before / after this one.
+      #
       #   sales < 5 OR
       #   sales = 5 AND (
       #     invoice < 3 OR
       #     invoices = 3 AND (
       #       ... ))
-      def build(side)
+      def build(side, strict = true)
         # generate pairs of terms such as sales < 5, sales = 5
-        terms = @columns.map { |col|
-          [where_side(col, side, true), where_tie(col)].reject { |x| x == WHERE_IDENTITY }
-        }
+        terms = @columns.map.with_index do |col, i|
+          be_strict = i != @columns.size - 1 ? true : strict
+          [where_side(col, side, be_strict), where_tie(col)].reject do |x|
+            x == WHERE_IDENTITY
+          end
+        end
         # group pairwise with OR, and nest with AND
-        query = foldr_terms terms.map { |pair| join_terms 'OR'.freeze, *pair }, 'AND'.freeze
+        query = foldr_terms terms.map { |pair| join_terms 'OR', *pair }, 'AND'
         if ::OrderQuery.wrap_top_level_or
           # wrap in a redundant AND clause for performance
           query = wrap_top_level_or query, terms, side
@@ -47,7 +53,8 @@ module OrderQuery
       # joins terms with an operator, empty terms are skipped
       # @return [query, parameters]
       def join_terms(op, *terms)
-        [terms.map(&:first).reject(&:empty?).join(" #{op} "), terms.map(&:second).reduce([], :+)]
+        [terms.map(&:first).reject(&:empty?).join(" #{op} "),
+         terms.map(&:second).reduce([], :+)]
       end
 
       def wrap_term_with_parens(t)
@@ -65,8 +72,11 @@ module OrderQuery
       # Read more at https://github.com/glebm/order_query/issues/3
       def wrap_top_level_or(query, terms, side)
         top_term_i = terms.index(&:present?)
-        if top_term_i && terms[top_term_i].length == 2 && !(col = @columns[top_term_i]).order_enum
-          join_terms 'AND'.freeze, where_side(col, side, false), wrap_term_with_parens(query)
+        if top_term_i && terms[top_term_i].length == 2 &&
+           !(col = @columns[top_term_i]).order_enum
+          join_terms 'AND',
+                     where_side(col, side, false),
+                     wrap_term_with_parens(query)
         else
           query
         end
@@ -82,36 +92,61 @@ module OrderQuery
       end
 
       # @param [:before or :after] side
-      # @return [query, params] return query fragment for column values before / after the current one
-      def where_side(col, side, strict = true, value = point.value(col))
+      # @return [query, params] return query fragment for column values
+      #   before / after the current one.
+      def where_side(col, side, strict, value = point.value(col))
         if col.order_enum
           where_in col, col.enum_side(value, side, strict)
+        elsif value.nil?
+          where_null col, side, strict
         else
           where_ray col, value, side, strict
         end
       end
 
       def where_in(col, values)
-        case values.length
-          when 0
-            WHERE_IDENTITY
-          when 1
-            where_eq col, values[0]
-          else
-            ["#{col.column_name} IN (?)".freeze, [values]]
-        end
+        join_terms 'OR',
+                   (values.include?(nil) ? where_eq(col, nil) : WHERE_IDENTITY),
+                   case (non_nil_values = values - [nil]).length
+                   when 0
+                     WHERE_IDENTITY
+                   when 1
+                     where_eq col, non_nil_values
+                   else
+                     ["#{col.column_name} IN (?)", [non_nil_values]]
+                   end
       end
 
       def where_eq(col, value = point.value(col))
-        [%Q(#{col.column_name} = ?).freeze, [value]]
+        if value.nil?
+          ["#{col.column_name} IS NULL", []]
+        else
+          ["#{col.column_name} = ?", [value]]
+        end
+      end
+
+      RAY_OP = { asc: '>', desc: '<' }.freeze
+      NULLS_ORD = { first: 'IS NOT NULL', last: 'IS NULL' }.freeze
+
+      def where_null(col, mode, strict)
+        if strict && col.nulls_direction(mode == :before) != :last
+          ["#{col.column_name} IS NOT NULL", []]
+        else
+          WHERE_IDENTITY
+        end
       end
 
-      RAY_OP = {asc: '>'.freeze, desc: '<'.freeze}.freeze
-      def where_ray(col, from, mode, strict = true)
-        ["#{col.column_name} #{RAY_OP[col.direction(mode == :before)]}#{'=' unless strict} ?".freeze, [from]]
+      def where_ray(col, from, mode, strict)
+        ["#{col.column_name} "\
+         "#{RAY_OP[col.direction(mode == :before)]}#{'=' unless strict} ?",
+         [from]].tap do |ray|
+          if col.nullable? && col.nulls_direction(mode == :before) == :last
+            ray[0] = "(#{ray[0]} OR #{col.column_name} IS NULL)"
+          end
+        end
       end
 
-      WHERE_IDENTITY = [''.freeze, [].freeze].freeze
+      WHERE_IDENTITY = ['', [].freeze].freeze
 
       private
 
@@ -120,8 +155,8 @@ module OrderQuery
       # Read more about folds:
       # * http://www.haskell.org/haskellwiki/Fold
       # * http://en.wikipedia.org/wiki/Fold_(higher-order_function)
-      def foldr_i(z, xs, &f)
-        xs.reverse_each.each_with_index.inject(z) { |b, (a, i)| f.call a, b, i }
+      def foldr_i(z, xs)
+        xs.reverse_each.each_with_index.inject(z) { |b, (a, i)| yield a, b, i }
       end
     end
   end