activerecord-refined 0.10.2 → 0.12.0

data/lib/active_record/refined/block_syntax.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# BigDecimal is refined below and is a bundled gem, so nothing loads it
+# before this file does.
+require "bigdecimal"
+require "active_record/refined/ast"
+
+module ActiveRecord
+  module Refined
+    # What a symbol answers to inside a block.  A symbol names a column
+    # there -- `:age` is `"users"."age"` -- and the methods below build a
+    # condition, an expression or an ordering from it.  Every one of them is
+    # a refinement, so it exists inside a `where`, `select`, `having`,
+    # `order`, `group`, `joins`, `update_all` or `upsert_all` block and
+    # nowhere else.
+    #
+    # The comparisons and the rest of the conditions are listed under
+    # {AST::Predications}, the arithmetic under {AST::Arithmetics}; a number
+    # or a string in a block takes `as` too, for a literal in a select list
+    # -- `0.as(:depth)`.  A number may stand on the left of an operator when
+    # an expression stands on the right; before a bare column it is written
+    # `value(20) - :quantity`.
+    #
+    # @example A column compared, aliased and ordered
+    #   Author.where { :age >= 18 }
+    #   Author.select { :name.as(:author) }
+    #   Author.order { :age.desc.nulls_last }
+    # @example A column of another table, and a collation
+    #   Author.joins(:posts) { :posts[:author_id] == :authors[:id] }
+    #   Author.where { :name.collate(:nocase) == "alice" }
+    module BlockSyntax
+      # @!parse include AST::Predications
+      # @!parse include AST::Arithmetics
+
+      # @!method as(alias_name, quote: true)
+      #   The column under an alias: `AS "name"`.  A number or a string takes
+      #   it too, for a literal in a select list; {BlockContext#value} carries
+      #   the literals that have no `as` of their own.  The alias is quoted,
+      #   so the name asked for is the name that comes back on every adapter;
+      #   `quote: false` writes it bare, for a schema that wants the folding,
+      #   and then it has to be a plain name.
+      #   @param alias_name [Symbol, String]
+      #   @param quote [Boolean]
+      #   @return [AST::As]
+      #   @example
+      #     Author.select { :name.as(:author) }   # "authors"."name" AS "author"
+      #     Node.select { [:id, 0.as(:depth)] }   # 0 AS "depth"
+      #     Post.select { [:title, "draft".as(:state)] }   # 'draft' AS "state"
+
+      # @!method asc
+      #   An ascending ordering, which takes `nulls_first` and `nulls_last`.
+      #   @return [AST::Ordering]
+      #   @example
+      #     Author.order { :country.asc.nulls_last }
+
+      # @!method desc
+      #   A descending ordering, which takes `nulls_first` and `nulls_last`.
+      #   @return [AST::Ordering]
+      #   @example
+      #     Post.order { :likes.desc }
+
+      # @!method collate(name)
+      #   The column under a collation, for a comparison or an ordering:
+      #   `"name" COLLATE nocase`.  The name is the database's own and not
+      #   portable; PostgreSQL quotes it, the others take it bare and refuse
+      #   one that is not a plain identifier.
+      #   @param name [Symbol, String] the collation's name
+      #   @return [AST::Collate]
+      #   @example
+      #     Author.where { :name.collate(:nocase) == "alice" }
+      #     Author.order { :name.collate(:"en-US-x-icu").asc }   # PostgreSQL
+
+      # @!method [](column_name)
+      #   A column of another table: `:posts[:author_id]` is
+      #   `"posts"."author_id"`, for a join condition or a query over a join.
+      #   @param column_name [Symbol]
+      #   @return [AST::Column]
+      #   @example
+      #     Author.joins(:posts) { :posts[:author_id] == :authors[:id] }
+
+      refine Symbol do
+        import_methods AST::Predications
+        import_methods AST::Arithmetics
+
+        def as(alias_name, quote: true)
+          AST::As.new(self, alias_name, quote: quote)
+        end
+
+        def asc
+          AST::Ordering.new(self, :asc)
+        end
+
+        def desc
+          AST::Ordering.new(self, :desc)
+        end
+
+        def collate(name)
+          AST::Collate.new(self, name)
+        end
+
+        def [](column_name)
+          AST::Column.new(self, column_name)
+        end
+      end
+
+      # Shorthand for `value(0).as(:depth)` and the like, and the named
+      # bitwise operations with the number on the left.  BigDecimal is a
+      # number here because that is what a decimal column's values are.
+      [Integer, Float, BigDecimal].each do |klass|
+        refine klass do
+          import_methods AST::NumericArithmetics
+
+          def as(alias_name, quote: true)
+            AST::As.new(AST::Value.new(self), alias_name, quote: quote)
+          end
+        end
+      end
+
+      # A string is a value here as it is in every other position of a block;
+      # SQL is asked for by name, with sql().
+      refine String do
+        def as(alias_name, quote: true)
+          AST::As.new(AST::Value.new(self), alias_name, quote: quote)
+        end
+      end
+    end
+  end
+end

data/lib/active_record/refined/dialect/mysql_compat.rb

@@ -6,10 +6,14 @@ module ActiveRecord
       # What MySQL and MariaDB share, which is most of it; the two part company
       # only in the Mysql and Mariadb subclasses.
       class MysqlCompat < Dialect
+        include MysqlishJsonFunctions
+
+        # @private
         FUNCTIONS = { trunc: "TRUNCATE", date_trunc: nil, format: nil }.freeze
 
         def full_outer_join_supported? = false
         def filter_supported? = false
+        def bitwise_operators_supported? = true
 
         def bit_count(expr, _model)
           AST::Function.new("BIT_COUNT", [expr])
@@ -41,6 +45,18 @@ module ActiveRecord
             "JSON_CONTAINS_PATH", [document, Arel::Nodes.build_quoted("one"), path])
         end
 
+        def json_keys(document, _model)
+          Arel::Nodes::NamedFunction.new("JSON_KEYS", [document])
+        end
+
+        # A Ruby document or boolean written where the JSON functions want
+        # JSON is marked as it by reading it out whole: JSON_EXTRACT($).
+        def json_argument(value, _model)
+          json = Arel::Nodes.build_quoted(JSON.generate(value))
+          Arel::Nodes::NamedFunction.new(
+            "JSON_EXTRACT", [json, Arel::Nodes.build_quoted("$")])
+        end
+
         def json_aggregate_filter_supported? = false
 
         # GROUP_CONCAT, its separator a keyword after the operand and after

data/lib/active_record/refined/dialect/mysqlish_json_functions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Refined
+    class Dialect
+      # The JSON editing and building functions MySQL and SQLite spell
+      # alike: JSON_SET and JSON_REMOVE over a $ path, and JSON_ARRAY and
+      # JSON_OBJECT with each key alternating with its value.  The spellings
+      # are MySQL's, which SQLite's json1 took over, and standard in
+      # neither sense of the word -- SQL:2016 gives JSON_OBJECT a KEY k
+      # VALUE v syntax and has no editing functions at all -- so they live
+      # here as a family likeness for the two to include, not in the base
+      # as a default for everyone.
+      module MysqlishJsonFunctions
+        def json_set(document, _steps, dollar_path, value, expression, model)
+          Arel::Nodes::NamedFunction.new(
+            "JSON_SET",
+            [document, Arel::Nodes.build_quoted(dollar_path),
+             json_set_value(value, expression, model)])
+        end
+
+        def json_remove(document, dollar_paths, _steps, _model)
+          Arel::Nodes::NamedFunction.new(
+            "JSON_REMOVE",
+            [document, *dollar_paths.map { |path| Arel::Nodes.build_quoted(path) }])
+        end
+
+        def json_build(kind, keys, args, _model)
+          Arel::Nodes::NamedFunction.new(
+            kind == :array ? "JSON_ARRAY" : "JSON_OBJECT",
+            json_build_body(kind, keys, args))
+        end
+
+        private
+          # The value beside a path in JSON_SET: an expression as it is, a
+          # document or boolean as JSON, a bare scalar quoted.
+          def json_set_value(value, expression, model)
+            return expression if expression
+            return Arel::Nodes.build_quoted(value) unless json_document_value?(value)
+            json_argument(value, model)
+          end
+      end
+    end
+  end
+end

data/lib/active_record/refined/dialect/oracle.rb

@@ -6,6 +6,7 @@ module ActiveRecord
       # Oracle, reached through oracle_enhanced.  Loaded only when a query is
       # built for it.
       class Oracle < Dialect
+        # @private
         FUNCTIONS = {
           char_length: "LENGTH",
           degrees: nil, radians: nil, pi: nil, log2: nil, log10: nil,
@@ -44,13 +45,6 @@ module ActiveRecord
           Arel::Nodes::NamedFunction.new("JSON_EXISTS", [document, path])
         end
 
-        # No JSON_KEYS, and the keys reach only through a JSON_TABLE unnest not
-        # written yet.
-        def json_keys(_document, model)
-          raise NotImplementedError,
-            "keys has no equivalent on #{model.connection_db_config.adapter}"
-        end
-
         def json_argument(value, model)
           Arel.sql("#{quote(JSON.generate(value), model)} FORMAT JSON")
         end

data/lib/active_record/refined/dialect/postgresql.rb

@@ -5,6 +5,10 @@ module ActiveRecord
     class Dialect
       # PostgreSQL, and the adapters that answer for the same server.
       class Postgresql < Dialect
+        def array_comparisons_supported? = true
+        def bitwise_operators_supported? = true
+
+        # @private
         FUNCTIONS = { log2: nil, rand: "RANDOM" }.freeze
 
         # PostgreSQL counts the bits of a bit string rather than a number, so
@@ -19,6 +23,10 @@ module ActiveRecord
           Arel::Nodes::InfixOperation.new("#", left, right)
         end
 
+        def excluded(column, _model)
+          AST::Column.new(:excluded, column)
+        end
+
         def json_path(document, _dollar_path, steps, json_value, _model)
           Arel::Nodes::InfixOperation.new(
             json_value ? :"#>" : :"#>>", document, Arel::Nodes.build_quoted(steps))

data/lib/active_record/refined/dialect/sql_server.rb

@@ -6,12 +6,21 @@ module ActiveRecord
       # Microsoft SQL Server, reached through the sqlserver adapter over
       # tiny_tds.  Loaded only when a query is built for it.
       class SqlServer < Dialect
-        # LEN is its length; it has no printf FORMAT, no per-row random it
-        # would spell RAND, no date_trunc, and none of the bit aggregates.
-        # Of the datetime value functions it has CURRENT_TIMESTAMP alone:
-        # the other four are reserved words there that stand for nothing.
+        # LEN is its length, CEILING its ceil, ATN2 its atan2, and LOG --
+        # natural by default -- its ln; SUBSTRING insists on the length, so
+        # substr wants all three arguments here.  It has no printf FORMAT, no
+        # per-row random it would spell RAND, no date_trunc, no NOW or LOG2,
+        # none of the bit aggregates, no MOD beside the % operator, and no
+        # numeric TRUNC.  log is nil for a sharper reason: its LOG(x, base)
+        # takes the arguments in the other order, so a rename would quietly
+        # swap them.  Of the datetime value functions it has
+        # CURRENT_TIMESTAMP alone: the other four are reserved words there
+        # that stand for nothing.
+        # @private
         FUNCTIONS = {
-          char_length: "LEN",
+          char_length: "LEN", length: "LEN", substr: "SUBSTRING",
+          ceil: "CEILING", atan2: "ATN2", ln: "LOG",
+          mod: nil, trunc: nil, log: nil, log2: nil, now: nil,
           format: nil, rand: nil, date_trunc: nil,
           bit_and: nil, bit_or: nil, bit_xor: nil,
           current_date: nil, current_time: nil, localtime: nil, localtimestamp: nil,
@@ -20,6 +29,15 @@ module ActiveRecord
         # No FILTER clause, so the aggregate node builds the CASE instead.
         def filter_supported? = false
 
+        # The operators are all here, the shifts included -- CI executes them.
+        def bitwise_operators_supported? = true
+
+        # ^ is XOR here as on MySQL, sparing the (a | b) - (a & b) the base
+        # spells for SQLite's sake.
+        def bitwise_xor(left, right)
+          Arel::Nodes::BitwiseXor.new(left, right)
+        end
+
         # No EXTRACT (it has DATEPART), and its datetime value functions take
         # no precision.
         def extract_supported? = false
@@ -60,6 +78,12 @@ module ActiveRecord
             "string_agg over a window has no equivalent on #{model.connection_db_config.adapter}"
         end
 
+        # No JSON aggregates, so the SQL:2016 names the base keeps would
+        # reach the server as functions it does not have.
+        def json_aggregate_name(kind)
+          raise NotImplementedError, "json_#{kind} has no equivalent on SQL Server"
+        end
+
         # dig_text reads a scalar out with JSON_VALUE; dig keeps JSON with
         # JSON_QUERY, which returns a fragment and NULL for a scalar leaf.
         def json_path(document, dollar_path, _steps, json_value, _model)

data/lib/active_record/refined/dialect/sqlite.rb

@@ -6,6 +6,9 @@ module ActiveRecord
       # SQLite: the fewest of the extras, and a JSON path through its own
       # operators.
       class Sqlite < Dialect
+        include MysqlishJsonFunctions
+
+        # @private
         FUNCTIONS = {
           char_length: "LENGTH", greatest: "MAX", least: "MIN",
           now: nil, date_trunc: nil, rand: "RANDOM",
@@ -16,6 +19,7 @@ module ActiveRecord
         def datetime_precision_supported? = false
         def extract_supported? = false
         def quantifiers_supported? = false
+        def bitwise_operators_supported? = true
 
         def check_lateral(model)
           raise NotImplementedError,
@@ -32,6 +36,21 @@ module ActiveRecord
             date_only ? "date" : "datetime", [date, Arel::Nodes.build_quoted(modifier)])
         end
 
+        # -> keeps the value's type where ->> gives text, so dig_text casts
+        # to text only to make the comparison portable.
+        def json_path(document, dollar_path, _steps, json_value, _model)
+          extracted = Arel::Nodes::InfixOperation.new(
+            json_value ? :"->" : :"->>", document, Arel::Nodes.build_quoted(dollar_path))
+          return extracted if json_value
+          Arel::Nodes::NamedFunction.new(
+            "CAST", [Arel::Nodes::As.new(extracted, Arel::Nodes::SqlLiteral.new("text"))])
+        end
+
+        # json_type at the path answers NULL where nothing stands there.
+        def json_has_key(document, _name, path, _model)
+          Arel::Nodes::NamedFunction.new("json_type", [document, path]).not_eq(nil)
+        end
+
         def json_keys(document, model)
           sql = compile(document, model)
           Arel.sql("CASE WHEN json_type(#{sql}) = 'object' " \
@@ -47,6 +66,10 @@ module ActiveRecord
           kind == :arrayagg ? "json_group_array" : "json_group_object"
         end
 
+        def excluded(column, _model)
+          AST::Column.new(:excluded, column)
+        end
+
         # group_concat, with the ORDER BY inside the call from 3.44 on.
         def string_agg(operand, separator, orders, _string, model)
           string_agg_call("group_concat", operand, separator, orders, model)