activerecord-refined 0.10.2 → 0.11.0

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)

data/lib/active_record/refined/dialect.rb

@@ -8,11 +8,15 @@ module ActiveRecord
     # and asked, rather than branched on, for whatever a query builds
     # differently from one database to the next.  The base is the standard
     # spelling an unclassified adapter keeps; each subclass overrides only
-    # where its family departs from it.
+    # where its family departs from it.  Where no spelling is anyone's
+    # standard -- most of JSON -- the base refuses instead, and every family
+    # carries its own.
     #
     # The families are loaded as they are met: an application on PostgreSQL
     # never loads the Oracle class, whose adapter it will never resolve to.
     class Dialect
+      autoload :MysqlishJsonFunctions,
+               "active_record/refined/dialect/mysqlish_json_functions"
       autoload :Sqlite, "active_record/refined/dialect/sqlite"
       autoload :Postgresql, "active_record/refined/dialect/postgresql"
       autoload :MysqlCompat, "active_record/refined/dialect/mysql_compat"
@@ -84,10 +88,23 @@ module ActiveRecord
 
       # The scalar and datetime functions a family spells differently, or has
       # none of.  A name it does not list it spells like the method, upper
-      # cased; a nil says it has no equivalent, and the block raises.  The base
-      # -- an unclassified adapter -- keeps every standard name.
-      FUNCTIONS = {}.freeze
-
+      # cased; a nil says it has no equivalent, and the block raises.  The
+      # base -- an unclassified adapter -- keeps the names most families
+      # share and nils the ones that are one or two families' own: printf
+      # FORMAT, whose name MySQL hands to a different function entirely,
+      # RAND, DATE_TRUNC, NOW, LOG2 and the three bit aggregates.  A family
+      # that has one of them says so in a table of its own, since the tables
+      # shadow rather than merge.
+      FUNCTIONS = {
+        format: nil, rand: nil, date_trunc: nil, now: nil, log2: nil,
+        bit_and: nil, bit_or: nil, bit_xor: nil,
+      }.freeze
+
+      # The name this family spells a function with, asked for as the block
+      # builds the call; {FUNCTIONS} is where the answer is looked up.
+      # @param name [Symbol] the method's own name, as {BlockContext} has it
+      # @return [String]
+      # @raise [NotImplementedError] where the family has no equivalent
       def function_name(name, model)
         functions = self.class::FUNCTIONS
         return name.to_s.upcase unless functions.key?(name)
@@ -96,9 +113,19 @@ module ActiveRecord
                 "#{name} has no equivalent on #{model.connection_db_config.adapter}")
       end
 
+      # Whether the datetime value functions take a precision,
+      # `current_timestamp(3)`.  SQLite and SQL Server take none.
       def datetime_precision_supported? = true
+
+      # Whether the family has EXTRACT.  SQLite spells the fields as strftime
+      # formats and SQL Server as DATEPART, so neither answers to the name.
       def extract_supported? = true
+
+      # Whether a comparison can be quantified with ANY or ALL.  SQLite has
+      # neither.
       def quantifiers_supported? = true
+
+      # Whether a FULL OUTER JOIN can be written.  The MySQL family has none.
       def full_outer_join_supported? = true
 
       # The FILTER clause, which restricts an aggregate to the rows a condition
@@ -106,6 +133,16 @@ module ActiveRecord
       # built by the aggregate node.
       def filter_supported? = true
 
+      # The bitwise operators, & | ^ << >> and ~.  No SQL standard has them,
+      # so unlike the capabilities above the base refuses and each family
+      # that has the operators says so itself -- which of the seven is every
+      # one but Oracle, whose single bit operation is the BITAND function.
+      def bitwise_operators_supported? = false
+
+      # The array comparisons -- @>, <@ and && against an array column.
+      # The type and its operators are PostgreSQL's alone.
+      def array_comparisons_supported? = false
+
       # A lateral join is allowed to stand unless the family refuses it here.
       def check_lateral(_model); end
 
@@ -118,10 +155,13 @@ module ActiveRecord
           "bit_count has no equivalent on #{model.connection_db_config.adapter}"
       end
 
-      # The row an upsert could not insert.  PostgreSQL and SQLite name it;
-      # MySQL spells the same thing VALUES(column) and overrides.
-      def excluded(column, _model)
-        AST::Column.new(:excluded, column)
+      # The row an upsert could not insert.  `excluded` is PostgreSQL's name
+      # for it, which SQLite took over and the MySQL family spells
+      # VALUES(column), so each of the three carries its own; the families
+      # without an upsert have nothing for the name to stand in.
+      def excluded(_column, model)
+        raise NotImplementedError,
+          "excluded has no equivalent on #{model.connection_db_config.adapter}"
       end
 
       # true? / false? and their negations.  The standard spells them with the
@@ -157,26 +197,32 @@ module ActiveRecord
           Arel::Nodes::InfixOperation.new(subtract ? :- : :+, date, interval))
       end
 
-      # XOR, which no two families spell alike.  The standard is the two
-      # operations it is made of, naming each operand twice, as SQLite needs;
-      # PostgreSQL and the MySQL family have an operator and override.
+      # XOR, which no two families spell alike.  The default is the two
+      # operations it is made of, naming each operand twice -- built only
+      # from the & and | a family has just claimed through
+      # {#bitwise_operators_supported?}, so wherever it can be reached at
+      # all it works.  Of the five that claim them, SQLite alone keeps it;
+      # the rest have an operator of their own and override.
       def bitwise_xor(left, right)
         Arel::Nodes::Subtraction.new(
           Arel::Nodes::Grouping.new(Arel::Nodes::BitwiseOr.new(left, right)),
           Arel::Nodes::Grouping.new(Arel::Nodes::BitwiseAnd.new(left, right)))
       end
 
-      # --- Reading JSON.  The defaults are what an unclassified adapter gets,
-      #     which is SQLite's operators for a path and its functions elsewhere.
-
-      # dig / dig_text.  The standard is SQLite's -> and ->>, whose ->> keeps
-      # the value's type, so dig_text casts to text for a portable comparison.
-      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"))])
+      # --- Reading JSON.  No two families spell it alike and the standard
+      #     names only part of it, so the base refuses each piece and every
+      #     family carries its own; what an unclassified adapter would get
+      #     from any one family's spelling is a query that means nothing on
+      #     the next.
+
+      # dig / dig_text.  Nothing reaches every family: SQLite and PostgreSQL
+      # have operators of their own, MySQL its functions, and the two that
+      # spell it as SQL:2016's JSON_VALUE and JSON_QUERY -- Oracle and SQL
+      # Server -- differ over what a scalar leaf comes back as.  Every
+      # family overrides.
+      def json_path(_document, _dollar_path, _steps, _json_value, model)
+        raise NotImplementedError,
+          "dig has no equivalent on #{model.connection_db_config.adapter}"
       end
 
       # A Ruby value on the JSON side of a comparison belongs to a JSON type;
@@ -187,69 +233,94 @@ module ActiveRecord
           "#{model.connection_db_config.adapter}; dig_text gives the value"
       end
 
+      # contains?: whether the document holds what is given.  The standard has
+      # no equivalent; PostgreSQL has @> and the MySQL family JSON_CONTAINS,
+      # and both override.
       def json_contains(_document, _json, model)
         raise NotImplementedError,
           "contains? has no equivalent on #{model.connection_db_config.adapter}"
       end
 
-      def json_has_key(document, _name, path, _model)
-        Arel::Nodes::NamedFunction.new("json_type", [document, path]).not_eq(nil)
+      # key?: whether the object has the key.  SQL:2016 spells it
+      # JSON_EXISTS, which of the five only Oracle answers to; PostgreSQL has
+      # the ? operator, the MySQL family JSON_CONTAINS_PATH, SQLite json_type
+      # at the path and SQL Server JSON_PATH_EXISTS, so every family
+      # overrides.
+      #
+      # The key arrives spelled both ways -- bare in `name`, as a $ path in
+      # `path` -- since a family reads it as one or as the other.
+      def json_has_key(_document, _name, _path, model)
+        raise NotImplementedError,
+          "key? has no equivalent on #{model.connection_db_config.adapter}"
       end
 
-      def json_keys(document, _model)
-        Arel::Nodes::NamedFunction.new("JSON_KEYS", [document])
+      # keys: the keys of an object as a JSON array.  JSON_KEYS is the MySQL
+      # family's own; SQLite and PostgreSQL gather theirs through a subquery
+      # over their key-listing functions, and Oracle and SQL Server would
+      # reach them only through table unnests not written here.
+      def json_keys(_document, model)
+        raise NotImplementedError,
+          "keys has no equivalent on #{model.connection_db_config.adapter}"
       end
 
       # --- Writing JSON.  A Ruby document or boolean has to be told apart from
       #     a bare scalar, and embedded as the JSON it spells.
 
+      # The test the writing hooks share: a Hash, an Array or a boolean is a
+      # document, and anything else a bare scalar.
       def json_document_value?(value)
         value.is_a?(::Hash) || value.is_a?(::Array) || value == true || value == false
       end
 
       # A Ruby document or boolean written where one of the JSON functions
-      # wants JSON.  The standard marks the literal with JSON_EXTRACT($);
-      # SQLite has json() and Oracle FORMAT JSON, and both override.
-      def json_argument(value, _model)
-        json = Arel::Nodes.build_quoted(JSON.generate(value))
-        Arel::Nodes::NamedFunction.new("JSON_EXTRACT", [json, Arel::Nodes.build_quoted("$")])
+      # wants JSON.  Every family marks the literal its own way --
+      # JSON_EXTRACT($) on MySQL, json() on SQLite, FORMAT JSON on Oracle,
+      # JSON_QUERY on SQL Server -- and none of the marks is another's.
+      def json_argument(_value, model)
+        raise NotImplementedError,
+          "a document written as JSON has no equivalent on " \
+          "#{model.connection_db_config.adapter}"
       end
 
-      # bury: setting a value at a path.  The standard is JSON_SET; PostgreSQL
-      # has jsonb_set and Oracle JSON_TRANSFORM, and both override.
-      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)])
+      # bury: setting a value at a path.  The standard has no editing
+      # functions at all: JSON_SET is {MysqlishJsonFunctions}', jsonb_set
+      # PostgreSQL's, JSON_TRANSFORM Oracle's and JSON_MODIFY SQL Server's.
+      def json_set(_document, _steps, _dollar_path, _value, _expression, model)
+        raise NotImplementedError,
+          "bury has no equivalent on #{model.connection_db_config.adapter}"
       end
 
-      # except: removing keys.  The standard removes a path apiece with
-      # JSON_REMOVE; PostgreSQL subtracts an array of keys and Oracle removes
-      # through JSON_TRANSFORM, and both override.
-      def json_remove(document, dollar_paths, _steps, _model)
-        Arel::Nodes::NamedFunction.new(
-          "JSON_REMOVE",
-          [document, *dollar_paths.map { |path| Arel::Nodes.build_quoted(path) }])
+      # except: removing keys, for which the standard likewise has nothing.
+      # {MysqlishJsonFunctions} removes a path apiece with JSON_REMOVE,
+      # PostgreSQL subtracts an array of keys, Oracle and SQL Server edit
+      # through JSON_TRANSFORM and JSON_MODIFY.
+      def json_remove(_document, _dollar_paths, _steps, model)
+        raise NotImplementedError,
+          "except has no equivalent on #{model.connection_db_config.adapter}"
       end
 
-      # json_array / json_object built in the row.  The standard says JSON_ARRAY
-      # and JSON_OBJECT with the values (and keys alternating); PostgreSQL has
-      # the jsonb_build_* pair and Oracle a keyword syntax, and both override.
-      def json_build(kind, keys, args, _model)
-        Arel::Nodes::NamedFunction.new(
-          kind == :array ? "JSON_ARRAY" : "JSON_OBJECT", json_build_body(kind, keys, args))
+      # json_array / json_object built in the row.  JSON_ARRAY(a, b) is
+      # SQL:2016, but JSON_OBJECT is where the syntaxes part -- the standard
+      # pairs each key as KEY k VALUE v, {MysqlishJsonFunctions} alternates
+      # them, SQL Server writes k : v -- so the pair travels together and
+      # each family says its own; SQL Server's is not written here yet.
+      def json_build(kind, _keys, _args, model)
+        raise NotImplementedError,
+          "json_#{kind} has no equivalent on #{model.connection_db_config.adapter}"
       end
 
-      # A document or boolean built into json_array/json_object.  The standard
-      # marks it JSON as bury does; PostgreSQL casts to jsonb and overrides.
+      # A document or boolean built into json_array/json_object.  The default
+      # rides through {#json_argument}, and refuses or serves with it;
+      # PostgreSQL casts to jsonb and overrides.
       def json_build_argument(value, model)
         json_argument(value, model)
       end
 
       # json_arrayagg / json_objectagg gather rows into a document.  The
-      # standard names are JSON_ARRAYAGG and JSON_OBJECTAGG; SQLite and
-      # PostgreSQL have their own and override.
+      # names are SQL:2016's own, which the MySQL family and Oracle answer
+      # to, so unlike the rest of JSON the base keeps them; SQLite and
+      # PostgreSQL have names of their own, and SQL Server, which has no
+      # JSON aggregates, refuses.
       def json_aggregate_name(kind)
         kind == :arrayagg ? "JSON_ARRAYAGG" : "JSON_OBJECTAGG"
       end
@@ -286,6 +357,8 @@ module ActiveRecord
       # --- Grouping.  GROUPING SETS, ROLLUP and CUBE, which the standard has
       #     none of; PostgreSQL has all three and the MySQL family rollup alone.
 
+      # Whether the family has the kind of grouping asked for, one of
+      # `:grouping_sets`, `:rollup` and `:cube`.
       def grouping_supported?(_kind) = false
 
       # The MySQL family spells rollup WITH ROLLUP, trailing the group list
@@ -293,16 +366,9 @@ module ActiveRecord
       def grouping_by_with_rollup? = false
 
       protected
-        # 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
-
-        # The arguments to JSON_ARRAY/JSON_OBJECT: an array's values as they
-        # are, an object's keys alternating with them.
+        # The values of JSON_ARRAY as they are, JSON_OBJECT's keys
+        # alternating with theirs -- the shape MysqlishJsonFunctions and
+        # PostgreSQL's jsonb_build_* pair both take.
         def json_build_body(kind, keys, args)
           return args if kind == :array
           keys.zip(args).flat_map { |key, arg| [Arel::Nodes.build_quoted(key), arg] }