activerecord-refined 0.6.1 → 0.8.0

data/lib/active_record/refined/ast.rb

@@ -217,15 +217,23 @@ module ActiveRecord
 
         # Reading inside a JSON document, by the name of what Hash does.  A
         # string or symbol steps into an object, an integer into an array, and
-        # what comes back is the value rather than the JSON, since that is what
-        # a comparison wants.  dig_json keeps it JSON, for a document to be dug
-        # into further or compared whole.
+        # what comes back is still JSON, the way Hash#dig hands back the
+        # structure itself -- for a document to be dug into further or asked
+        # the JSON questions.  dig_text gives the value as text instead,
+        # which is what a comparison wants.
         def dig(*path)
+          JsonPath.new(self, path, as_json: true)
+        end
+
+        def dig_text(*path)
           JsonPath.new(self, path)
         end
 
-        def dig_json(*path)
-          JsonPath.new(self, path, as_json: true)
+        # Keys taken out of a JSON document, by the name of what Hash does,
+        # and taking keys as Hash#except takes them.  Like bury it gives back
+        # the document changed rather than writing it anywhere.
+        def except(*keys)
+          JsonExcept.new(self, keys)
         end
 
         # What dig reads, bury sets: the last argument is the value and the
@@ -359,7 +367,7 @@ module ActiveRecord
       # A literal standing where an expression would: `select { value(0).as(:depth) }`.
       #
       # Values reach the SQL quoted wherever they appear as an operand, but the
-      # top of a select list is ActiveRecord's, and a bare string there is SQL
+      # top of a select list is Active Record's, and a bare string there is SQL
       # rather than a string.  Saying `value` is how you ask for the other
       # meaning, and it carries the predications with it, so a literal can be
       # compared and combined like anything else.
@@ -441,7 +449,7 @@ module ActiveRecord
         end
 
         # What a `when` is until its `then` arrives.  A Node so that using it
-        # as one says what is missing rather than reaching ActiveRecord as
+        # as one says what is missing rather than reaching Active Record as
         # something it cannot read.
         class Pending < Node
           def initialize(kase, condition)
@@ -474,20 +482,23 @@ module ActiveRecord
         end
 
         # PostgreSQL takes the steps as a text array, where every element is
-        # quoted so that a comma or a brace in a key is part of it.
-        def steps_array
-          "{#{path.map {|step| %("#{escape_step(step)}") }.join(',')}}"
+        # quoted so that a comma or a brace in a key is part of it.  except
+        # writes its keys the same way, which are steps of no one path.
+        def steps_array(steps = path)
+          "{#{steps.map {|step| %("#{escape_step(step)}") }.join(',')}}"
         end
 
         # MySQL and SQLite take a path expression instead, where an integer is
         # a subscript and a name that is not plain has to be quoted.
         def dollar_path
-          path.inject(+'$') do |so_far, step|
-            next so_far << "[#{step}]" if step.is_a?(::Integer)
-            name = step.to_s
-            so_far << '.' << (name.match?(/\A[[:alpha:]_][[:alnum:]_]*\z/) ?
-                              name : %("#{escape_step(step)}"))
-          end
+          path.inject(+'$') {|so_far, step| so_far << dollar_step(step) }
+        end
+
+        def dollar_step(step)
+          return "[#{step}]" if step.is_a?(::Integer)
+          name = step.to_s
+          '.' + (name.match?(/\A[[:alpha:]_][[:alnum:]_]*\z/) ?
+                 name : %("#{escape_step(step)}"))
         end
 
         def escape_step(step)
@@ -503,10 +514,85 @@ module ActiveRecord
       #
       # The path is turned into a string either way, so a key with a space or
       # a quote in it travels as itself rather than having to be refused.
+      # What a dug value may be compared with.  dig_text gives text on every
+      # adapter, and what a text value compared with a number means is a
+      # question the three answer three ways: `dig_text(:n) == 5` is true on
+      # SQLite, an error on PostgreSQL and true on MySQL, while
+      # `dig_text(:flag) == true` is true, an error, and false.  cast is what
+      # says which type was meant, and then all three agree.
+      #
+      # dig is refused the other way about: the JSON for a string carries
+      # its quotes, so `dig(:name) == 'alice'` is false on SQLite, an
+      # error on PostgreSQL and true on MySQL.  dig_text is the one that
+      # gives the value.
+      #
+      # A string against dig_text, and anything the block itself built -- a
+      # column, a function, another dug value -- go through untouched.
+      module JsonComparable
+        %i[== != < <= > >=].each do |operator|
+          define_method(operator) do |other|
+            check_comparable(other)
+            super(other)
+          end
+        end
+
+        def in?(values) = super(check_each(values))
+        def not_in?(values) = super(check_each(values))
+        def between?(min, max) = super(*check_each([min, max]))
+        def not_between?(min, max) = super(*check_each([min, max]))
+
+        private
+
+        # nil is left to the comparison itself, which says to use null?, and
+        # so is anything the block built rather than wrote as a literal.
+        def check_comparable(other)
+          return if other.nil? || other.is_a?(Node) || other.is_a?(::Symbol) ||
+                    other.is_a?(Arel::Nodes::Node) ||
+                    other.is_a?(Arel::Attributes::Attribute) ||
+                    other.is_a?(ActiveRecord::Relation)
+          return if other.is_a?(::String) && !as_json
+
+          raise ArgumentError, as_json ?
+            "dig gives JSON, and comparing it with #{other.inspect} " \
+            "means something different on every adapter; dig_text gives the value" :
+            "dig_text gives text, and comparing it with #{other.inspect} means " \
+            "something different on every adapter; cast it to the type meant"
+        end
+
+        def check_each(values)
+          case values
+          when ActiveRecord::Relation then values
+          when ::Range then [values.begin, values.end].each {|v| check_comparable(v) }
+          else values.each {|value| check_comparable(value) }
+          end
+          values
+        end
+      end
+
+      # The JSON operations read a document, and what dig gives is one:
+      # `dig(:author).key?(:email)` and `dig(:tags).contains?(...)` are the
+      # same question asked of a part of it, and the adapters answer them
+      # alike.  What dig_text gives is text, and reading that as a document
+      # again is where they part company: SQLite parses it back and MySQL
+      # takes it as written, where PostgreSQL has no such function for text.
+      module JsonDocument
+        %i[dig dig_text key? contains? bury except].each do |name|
+          define_method(name) do |*args|
+            unless as_json
+              raise ArgumentError,
+                "dig_text gives text, and #{name} reads JSON; dig keeps it"
+            end
+            super(*args)
+          end
+        end
+      end
+
       class JsonPath < Node
         include Predications
         include Arithmetics
         include JsonSteps
+        include JsonComparable
+        include JsonDocument
 
         attr_reader :operand, :path, :as_json
 
@@ -530,8 +616,8 @@ module ActiveRecord
             extracted = Arel::Nodes::InfixOperation.new(
               as_json ? :"->" : :"->>", document, Arel::Nodes.build_quoted(dollar_path))
             # SQLite's ->> gives back the value with its type, where the other
-            # two give text.  Cast so that `dig(:n) == '5'` means the same
-            # thing everywhere, and a number wants a cast everywhere too.
+            # two give text.  Cast so that `dig_text(:n) == '5'` means the
+            # same thing everywhere, and a number wants a cast everywhere too.
             as_json ? extracted : Arel::Nodes::NamedFunction.new(
               'CAST', [Arel::Nodes::As.new(extracted, Arel::Nodes::SqlLiteral.new('text'))])
           end
@@ -595,6 +681,55 @@ module ActiveRecord
         end
       end
 
+      # Keys taken out of a JSON document.  PostgreSQL subtracts them, the
+      # other two remove a path apiece.
+      class JsonExcept < Node
+        include Predications
+        include JsonSteps
+
+        attr_reader :operand, :keys
+
+        def initialize(operand, keys)
+          @operand = operand
+          @keys = check_keys(keys)
+        end
+
+        def to_arel(table, model)
+          document = to_arel_operand(operand, table, model)
+          return Arel::Nodes::InfixOperation.new(:-, document, key_array) if
+            AST.adapter_family(model) == :postgresql
+
+          Arel::Nodes::NamedFunction.new(
+            'JSON_REMOVE',
+            [document, *keys.map {|key| Arel::Nodes.build_quoted("$#{dollar_step(key)}") }])
+        end
+
+        private
+
+        # jsonb has three subtractions -- a key, an array of keys, an element
+        # by index -- and an array literal written without a type is read as
+        # the first of them: `meta - '{draft}'` takes out the key spelled
+        # {draft}, which is nothing, and says nothing about it.
+        def key_array
+          Arel::Nodes::NamedFunction.new(
+            'CAST',
+            [Arel::Nodes::As.new(Arel::Nodes.build_quoted(steps_array(keys)),
+                                 Arel::Nodes::SqlLiteral.new('text[]'))])
+        end
+
+        # Keys, as Hash#except takes them: an index into an array is not what
+        # the name says anywhere, and is bury's business through a path.
+        def check_keys(keys)
+          raise ArgumentError, 'except needs a key' if keys.empty?
+          keys.each do |key|
+            next if key.is_a?(::String) || key.is_a?(::Symbol)
+            raise ArgumentError,
+              "except takes keys of the document, not #{key.inspect}"
+          end
+          keys
+        end
+      end
+
       # JSON containment: whether the document holds what is given.
       class JsonContains < Predicate
         attr_reader :operand, :value
@@ -1128,7 +1263,7 @@ module ActiveRecord
 
       # A plain SQL comparison. The value is passed through as it is, so a Range
       # or an Array compares against a PostgreSQL range or array column, the way
-      # ActiveRecord's own force_equality? types do.
+      # Active Record's own force_equality? types do.
       class Comparison < Predicate
         OPERATOR_MAP = {
           :== => :eq, :!= => :not_eq,
@@ -1187,7 +1322,7 @@ module ActiveRecord
       end
 
       # A relation standing for a set of values, which is what IN and the
-      # quantifiers each take.  The treatment is ActiveRecord's own
+      # quantifiers each take.  The treatment is Active Record's own
       # RelationHandler's: without an explicit select list the subquery
       # selects the model's primary key.
       module SetSubquery

data/lib/active_record/refined.rb

@@ -251,7 +251,7 @@ module ActiveRecord
       #
       #   select { [:id, value(0).as(:depth)] }
       #
-      # Needed because the top of a select list is ActiveRecord's, and a bare
+      # Needed because the top of a select list is Active Record's, and a bare
       # string there is SQL rather than a string.  Numbers have a shorthand --
       # `0.as(:depth)` -- since nothing else could be meant by one.
       def value(literal)
@@ -367,7 +367,7 @@ module ActiveRecord
         end
       end
 
-      # A symbol names a table, which ActiveRecord's own from only takes as a
+      # A symbol names a table, which Active Record's own from only takes as a
       # string.  With `as` it is selected under another name; when that name
       # is the model's own, from_cte says the same thing without repeating it.
       def from(value, subquery_name = nil, as: nil)
@@ -383,7 +383,7 @@ module ActiveRecord
       end
 
       # Selects a CTE in place of the model's own table.  The alias is not a
-      # choice -- ActiveRecord keeps qualifying columns with the table name,
+      # choice -- Active Record keeps qualifying columns with the table name,
       # so the model's is the only name that works -- which is why it is
       # taken from the model rather than asked for:
       # with_recursive(tree: [...]).from_cte(:tree)
@@ -432,7 +432,7 @@ module ActiveRecord
         self
       end
 
-      # ActiveRecord generates these for the values it knows about; this one
+      # Active Record generates these for the values it knows about; this one
       # is ours, and lives in the same place so that it survives a spawn.
       def distinct_on_values
         @values.fetch(:distinct_on, ActiveRecord::QueryMethods::FROZEN_EMPTY_ARRAY)
@@ -443,13 +443,32 @@ module ActiveRecord
         @values[:distinct_on] = columns
       end
 
+      # Marks the relation for a lateral join, which lets it see the row being
+      # joined to -- the top few rows of each group, and the like.  In SQL the
+      # keyword modifies the subquery, not the join, so it is said on the
+      # relation: left_outer_joins(top_post.lateral, as: :top).
+      def lateral
+        spawn.lateral!
+      end
+
+      def lateral!
+        self.lateral_value = true
+        self
+      end
+
+      def lateral_value
+        @values[:lateral]
+      end
+
+      def lateral_value=(value)
+        assert_modifiable!
+        @values[:lateral] = value
+      end
+
       # `as` names the table within the query, which is what makes a self
       # join expressible: joins(:employees, as: :managers) { ... }.
-      #
-      # `lateral` joins a relation instead of a table, and lets it see the row
-      # being joined to -- the top few rows of each group, and the like.
-      def joins(*args, as: nil, lateral: false, &block)
-        if lateral
+      def joins(*args, as: nil, &block)
+        if args.first.is_a?(ActiveRecord::Relation)
           super(build_lateral_join(args.first, Arel::Nodes::InnerJoin, as, &block))
         elsif block
           super(build_join_node(args.first, Arel::Nodes::InnerJoin, as, &block))
@@ -459,8 +478,8 @@ module ActiveRecord
         end
       end
 
-      def left_outer_joins(*args, as: nil, lateral: false, &block)
-        if lateral
+      def left_outer_joins(*args, as: nil, &block)
+        if args.first.is_a?(ActiveRecord::Relation)
           joins(build_lateral_join(args.first, Arel::Nodes::OuterJoin, as, &block))
         elsif block
           joins(build_join_node(args.first, Arel::Nodes::OuterJoin, as, &block))
@@ -470,6 +489,36 @@ module ActiveRecord
         end
       end
 
+      # The other two outer joins, which Active Record has no method for and
+      # Arel has the nodes for.  The rules are joins': the block is the ON,
+      # `as` names the table within the query, a relation marked `lateral`
+      # joins as one.  An association name is not among them -- what Active
+      # Record reads out of one is an inner or a left join and nothing else.
+      def right_outer_joins(*args, as: nil, &block)
+        outer_joins(:right_outer_joins, Arel::Nodes::RightOuterJoin,
+                    args, as, &block)
+      end
+
+      def full_outer_joins(*args, as: nil, &block)
+        check_full_outer_support
+        outer_joins(:full_outer_joins, Arel::Nodes::FullOuterJoin,
+                    args, as, &block)
+      end
+
+      # CROSS JOIN: every row of one table against every row of the other, so
+      # unlike the joins above there is no condition to give and no block to
+      # write it in.
+      #
+      #   Post.cross_joins(:authors)
+      #   Post.cross_joins(:posts, as: :others)
+      def cross_joins(*args, as: nil, &block)
+        if block
+          raise ArgumentError,
+            'a cross join has no condition; joins is the one that takes a block'
+        end
+        joins(build_cross_join(args.first, as))
+      end
+
       private
 
       def build_arel(...)
@@ -521,8 +570,9 @@ module ActiveRecord
       # which is the usual shape -- what the subquery is allowed to see is
       # what makes it lateral, and that is said inside it.
       def build_lateral_join(relation, join_class, alias_name, &block)
-        unless relation.is_a?(ActiveRecord::Relation)
-          raise ArgumentError, "a lateral join takes a relation to join against"
+        unless relation.lateral_value
+          raise ArgumentError,
+            "a relation joins laterally; mark it: joins(sub.lateral, as: :top)"
         end
         unless alias_name
           raise ArgumentError, "a lateral join needs a name: joins(..., as: :top)"
@@ -551,6 +601,37 @@ module ActiveRecord
         raise NotImplementedError, "a lateral join has no equivalent on #{database}"
       end
 
+      # MySQL has no FULL OUTER JOIN, and neither has MariaDB; SQLite has had
+      # one since 3.39 and PostgreSQL always.
+      def check_full_outer_support
+        return unless AST.adapter_family(klass) == :mysql
+        raise NotImplementedError, 'a full outer join has no equivalent on MySQL'
+      end
+
+      def outer_joins(called, join_class, args, alias_name, &block)
+        if args.first.is_a?(ActiveRecord::Relation)
+          return joins(build_lateral_join(args.first, join_class, alias_name, &block))
+        end
+        return joins(build_join_node(args.first, join_class, alias_name, &block)) if block
+
+        raise ArgumentError,
+          "#{called} takes a table and the block that joins it; an association " \
+          'is what joins and left_outer_joins read'
+      end
+
+      # Arel has a node for every other join and none for this one, and INNER
+      # JOIN with no ON -- which is a cross join on SQLite and MySQL -- is a
+      # syntax error on PostgreSQL.  So the SQL is written here, the second
+      # place in the gem that writes any: the keyword is fixed and the names
+      # are quoted by the adapter, so nothing of the caller's is in it.
+      def build_cross_join(target_table, alias_name)
+        joined = klass.with_connection do |connection|
+          name = connection.quote_table_name(target_table.to_s)
+          alias_name ? "#{name} #{connection.quote_table_name(alias_name.to_s)}" : name
+        end
+        Arel::Nodes::StringJoin.new(Arel.sql("CROSS JOIN #{joined}"))
+      end
+
       def build_join_node(target_table, join_class, alias_name, &block)
         ast = evaluate_block(&block)
         arel_table = Arel::Table.new(target_table)

data/lib/activerecord-refined/version.rb

@@ -1,5 +1,5 @@
 module Activerecord
   module Refined
-    VERSION = '0.6.1'
+    VERSION = '0.8.0'
   end
 end

data/lib/activerecord-refined.rb

@@ -9,6 +9,8 @@ ActiveRecord::QueryMethods.prepend ActiveRecord::Refined::QueryMethods
 # update_all and its kind are Relation's own rather than QueryMethods'.
 ActiveRecord::Relation.prepend ActiveRecord::Refined::Writes
 
-# The methods above are ActiveRecord's own, so a model already forwards them
-# to its relation.  These two are new, and have to be added to that list.
-ActiveRecord::Base.singleton_class.delegate :from_cte, :distinct_on, to: :all
+# The methods above are Active Record's own, so a model already forwards them
+# to its relation.  These are new, and have to be added to that list.
+ActiveRecord::Base.singleton_class.delegate(
+  :from_cte, :distinct_on, :lateral,
+  :right_outer_joins, :full_outer_joins, :cross_joins, to: :all)