activerecord-refined 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2343da1bdb5b8fdad1b6671f516c3a56173629d2ad433d93c4a22218deeef1fe
-  data.tar.gz: f2f2cd301e6541409ffe472c0ec68b8551a5762aba89b64c266bb435df60182f
+  metadata.gz: f20876b4eb0b36ece84fc2f6a1c828461846b29bd829e279d31b22735cbf0c15
+  data.tar.gz: 4a717ffaf4991fa3a113ea4a6a619b16d431e8308e1869e22c988885022d450a
 SHA512:
-  metadata.gz: 4fe091dac0872b9cfbffbdb5bb88d75dfb627e5cf26b29d6256e7bbc9845f5dad4fae4b41de66562ca4079160442f21849b04d0736df20340ba0c317b9ee5f3d
-  data.tar.gz: fba70971662ad06f2383d51aa53e81a681f2716108a40a0f2f6ebda278526e10517be1159bd2b5715e2da963a33fdc5615ee5acfcd9253782b0526b9cc3cbacb
+  metadata.gz: 56734a22e7667270892abf1d6ab9fb0816a37043c5f1fe61a7367c40403f782af6dff7875b0f520ada5aef6ce89155f39919414a71d3abec279ccf3c538db578
+  data.tar.gz: f0aa350bbf6b80d1e36b156d2e997930195f2fcfe99c53ae449f3d0f44efe3870671c45bae52a7eac5f39c5f39adf129cbe5a1a1d3776b07eb8d29b1cfa470d2

data/README.md

@@ -78,6 +78,27 @@ Author.where { :country.in?(%w[JP US]) }    # IN
 Author.where { :country.null? }             # IS NULL
 ```
 
+`in?` also takes a relation as a subquery. Without an explicit select list the
+subquery selects the relation's primary key, the same way ActiveRecord's own
+`where(id: relation)` does:
+
+```ruby
+Author.where { :id.in?(Post.published.select(:author_id)) }
+# "authors"."id" IN (SELECT "posts"."author_id" FROM "posts" WHERE ...)
+```
+
+`exists?` takes a relation and becomes `EXISTS (SELECT ...)`. Correlate the
+subquery with the outer table through qualified columns — its `where` block
+goes through the DSL like any other:
+
+```ruby
+Author.where { exists?(Post.where { :posts[:author_id] == :authors[:id] }) }
+# EXISTS (SELECT "posts".* FROM "posts" WHERE "posts"."author_id" = "authors"."id")
+
+Author.where { !exists?(Post.where { :posts[:author_id] == :authors[:id] }) }
+# NOT (EXISTS (...))
+```
+
 `like?` is case-sensitive `LIKE` on every adapter, including PostgreSQL, where
 Arel would otherwise reach for `ILIKE`.
 
@@ -91,6 +112,25 @@ Author.where { :name.end_with?('son') }     # LIKE '%son'
 Author.where { :name.include?('test') }     # LIKE '%test%'
 ```
 
+Like their String namesakes, `start_with?` and `end_with?` take any number of
+literals; matching any one of them is enough:
+
+```ruby
+Author.where { :name.start_with?('A', 'B') }
+# (name LIKE 'A%' OR name LIKE 'B%')
+```
+
+`member?` tests containment in a PostgreSQL array column. The two flavors of
+"does it contain this?" split by name the way Ruby's own classes do: `include?`
+is String's substring match, `member?` is Enumerable's element test, which
+String does not have. Pass an array to require every element:
+
+```ruby
+Article.where { :tags.member?('ruby') }         # "tags" @> '{ruby}'
+Article.where { :tags.member?(%w[ruby rails]) } # "tags" @> '{ruby,rails}'
+Article.where { :scores.member?(80) }           # "scores" @> '{80}'
+```
+
 `=~` and `!~` match a regular expression: `REGEXP` and `NOT REGEXP` on MySQL,
 `~` and `!~` on PostgreSQL. SQLite has no regexp operator of its own, so it
 raises there.
@@ -115,6 +155,14 @@ Reservation.where { :period == (from...to) }   # daterange = '[from,to)'
 Article.where { :tags == %w[ruby rails] }      # text[] = '{ruby,rails}'
 ```
 
+For the same reason `== nil` raises `ArgumentError`: `= NULL` is never true in
+SQL, so a NULL test has to be spelled as one. Use `null?`:
+
+```ruby
+Author.where { :country.null? }             # country IS NULL
+Author.where { !:country.null? }            # NOT (country IS NULL)
+```
+
 Combine predicates with `&`, `|` and `!`. Ruby's operator precedence makes the
 parentheses around each comparison necessary, though the `?` methods above need
 none:
@@ -202,21 +250,10 @@ and publishes it through RubyGems.org's trusted publishing, so no API key is
 stored anywhere.
 
 ```sh
-# bump Activerecord::Refined::VERSION and commit it, then
-git tag v0.4.0
-git push origin v0.4.0
+bump patch --tag # or bump {major,minor} etc.
+git push --follow-tags
 ```
 
-This needs a trusted publisher registered once at
-<https://rubygems.org/gems/activerecord-refined/trusted_publishers>:
-
-| Field | Value |
-| --- | --- |
-| Repository owner | `shugo` |
-| Repository name | `activerecord-refined` |
-| Workflow filename | `push_gem.yml` |
-| Environment | `release` |
-
 ## Contributing
 
 1. Fork it

data/lib/active_record/refined/ast.rb

@@ -5,11 +5,20 @@ module ActiveRecord
       # expressions. Imported into the Symbol refinement with
       # Refinement#import_methods, so every method must be defined with def.
       module Predications
+        # == and != mean SQL = and <>, and = NULL is never true there, so nil
+        # is rejected rather than silently rewritten to IS NULL.  null? builds
+        # its node directly and stays clear of this check.
         def ==(other)
+          if other.nil?
+            raise ArgumentError, "== does not take nil; use null? instead"
+          end
           Comparison.new(self, :==, other)
         end
 
         def !=(other)
+          if other.nil?
+            raise ArgumentError, "!= does not take nil; use !null? instead"
+          end
           Comparison.new(self, :!=, other)
         end
 
@@ -53,17 +62,27 @@ module ActiveRecord
           Like.new(self, pattern)
         end
 
-        def start_with?(prefix)
-          Like.new(self, "#{Like.escape(prefix)}%", Like::ESCAPE)
+        def start_with?(*prefixes)
+          if prefixes.empty?
+            raise ArgumentError, "start_with? needs at least one prefix"
+          end
+          Like.any(self, prefixes.map {|prefix| "#{Like.escape(prefix)}%" })
         end
 
-        def end_with?(suffix)
-          Like.new(self, "%#{Like.escape(suffix)}", Like::ESCAPE)
+        def end_with?(*suffixes)
+          if suffixes.empty?
+            raise ArgumentError, "end_with? needs at least one suffix"
+          end
+          Like.any(self, suffixes.map {|suffix| "%#{Like.escape(suffix)}" })
         end
 
         def include?(substring)
           Like.new(self, "%#{Like.escape(substring)}%", Like::ESCAPE)
         end
+
+        def member?(element)
+          Member.new(self, element)
+        end
       end
 
       class Node
@@ -215,7 +234,8 @@ module ActiveRecord
         end
       end
 
-      # IN for a list of values, BETWEEN for a range.
+      # IN for a list of values, BETWEEN for a range, IN (SELECT ...) for a
+      # relation.
       class In < Predicate
         attr_reader :operand, :values
 
@@ -228,9 +248,49 @@ module ActiveRecord
           arel_operand = to_arel_operand(operand, table)
           case values
           when Range then arel_operand.between(values)
+          when ActiveRecord::Relation then arel_operand.in(subquery(values))
           else arel_operand.in(values)
           end
         end
+
+        private
+
+        # The same treatment ActiveRecord's own RelationHandler gives a
+        # relation used as a value: without an explicit select list the
+        # subquery selects the model's primary key.
+        def subquery(relation)
+          if relation.eager_loading?
+            relation = relation.send(:apply_join_dependency)
+          end
+          if relation.select_values.empty?
+            model = relation.model
+            if model.composite_primary_key?
+              raise ArgumentError,
+                "Cannot map composite primary key #{model.primary_key} to IN"
+            end
+            relation = relation.select(relation.table[model.primary_key])
+          end
+          relation.arel
+        end
+      end
+
+      # EXISTS (SELECT ...) for a relation.  Correlate the subquery with the
+      # outer table through qualified columns.  EXISTS only asks whether a row
+      # comes back, so unlike In there is no select list to fix up.
+      class Exists < Predicate
+        attr_reader :relation
+
+        def initialize(relation)
+          @relation = relation
+        end
+
+        def to_arel(_table)
+          subquery = relation
+          if subquery.eager_loading?
+            subquery = subquery.send(:apply_join_dependency)
+          end
+          subquery.arel.exists
+        end
       end
 
       class Like < Predicate
@@ -243,6 +303,13 @@ module ActiveRecord
           ActiveRecord::Base.sanitize_sql_like(string, ESCAPE)
         end
 
+        # ORs one LIKE per pattern, for the shortcuts that accept several
+        # literals the way String#start_with? does.
+        def self.any(operand, patterns)
+          patterns.map {|pattern| new(operand, pattern, ESCAPE) }.
+            inject {|left, right| Or.new(left, right) }
+        end
+
         attr_reader :operand, :pattern, :escape
 
         def initialize(operand, pattern, escape = nil)
@@ -258,6 +325,43 @@ module ActiveRecord
         end
       end
 
+      # Containment in a PostgreSQL array column.  The two flavors of "does it
+      # contain this?" split by name the way Ruby's own classes do: include? is
+      # String's substring match (LIKE), member? is Enumerable's element test,
+      # which String does not have.  The elements are rendered as an array
+      # literal, which PostgreSQL coerces to the column's element type, so any
+      # expression works as the operand and no schema lookup is needed.
+      class Member < Predicate
+        attr_reader :operand, :elements
+
+        def initialize(operand, element)
+          @operand = operand
+          @elements = element.is_a?(::Array) ? element : [element]
+        end
+
+        def to_arel(table)
+          arel_operand = to_arel_operand(operand, table)
+          arel_operand.contains(Arel::Nodes.build_quoted(array_literal))
+        end
+
+        private
+
+        # PostgreSQL array input syntax: elements joined by commas inside
+        # braces, and an element is double-quoted whenever it is empty, spells
+        # NULL, or contains a character the parser treats specially.
+        def array_literal
+          encoded = elements.map do |value|
+            s = value.to_s
+            if s.empty? || s.casecmp?("null") || s.match?(/[\s{},"\\]/)
+              "\"#{s.gsub(/["\\]/) {|c| "\\#{c}" }}\""
+            else
+              s
+            end
+          end
+          "{#{encoded.join(',')}}"
+        end
+      end
+
       # Regular expression match: REGEXP on MySQL, ~ on PostgreSQL.  SQLite has
       # no regexp operator built in, so Arel raises NotImplementedError there.
       class Match < Predicate

data/lib/active_record/refined.rb

@@ -40,6 +40,10 @@ module ActiveRecord
       SCALAR_FUNCTIONS.each do |name|
         define_method(name) {|*args| AST::Function.new(name.to_s.upcase, args) }
       end
+
+      def exists?(relation)
+        AST::Exists.new(relation)
+      end
     end
 
     module QueryMethods

data/lib/activerecord-refined/version.rb

@@ -1,5 +1,5 @@
 module Activerecord
   module Refined
-    VERSION = '0.3.2'
+    VERSION = '0.3.3'
   end
 end

data/test/test_block_syntax.rb

@@ -81,6 +81,35 @@ class TestBlockSyntax < Minitest::Test
       User.where { :name.include?('der') }.to_sql)
   end
 
+  # Like their String namesakes, start_with? and end_with? take any number
+  # of literals; matching any one of them is enough.
+  def test_start_with_multiple
+    assert_sql(
+      /WHERE \("users"."name" LIKE 'ma%' ESCAPE '\\' OR "users"."name" LIKE 'no%' ESCAPE '\\'\)/,
+      User.where { :name.start_with?('ma', 'no') }.to_sql)
+  end
+
+  def test_end_with_multiple
+    assert_sql(
+      /WHERE \("users"."name" LIKE '%z' ESCAPE '\\' OR "users"."name" LIKE '%love' ESCAPE '\\'\)/,
+      User.where { :name.end_with?('z', 'love') }.to_sql)
+  end
+
+  # The OR arrives grouped, so a following & applies to the whole list.
+  def test_start_with_multiple_combined
+    assert_sql(
+      /WHERE \("users"."name" LIKE 'ma%' ESCAPE '\\' OR "users"."name" LIKE 'no%' ESCAPE '\\'\) AND "users"."age" > 18/,
+      User.where { :name.start_with?('ma', 'no') & (:age > 18) }.to_sql)
+  end
+
+  def test_start_with_no_arguments
+    assert_raises(ArgumentError) { User.where { :name.start_with? } }
+  end
+
+  def test_end_with_no_arguments
+    assert_raises(ArgumentError) { User.where { :name.end_with? } }
+  end
+
   def test_start_with_escapes_wildcards
     assert_sql(/WHERE "users"."name" LIKE '100\\%\\_%' ESCAPE '\\'/,
       User.where { :name.start_with?('100%_') }.to_sql)
@@ -91,6 +120,56 @@ class TestBlockSyntax < Minitest::Test
       User.where { :name.include?('100%') }.to_sql)
   end
 
+  def test_member
+    assert_sql(/WHERE "users"."tags" @> '\{ruby\}'/,
+      User.where { :tags.member?('ruby') }.to_sql)
+  end
+
+  def test_member_qualified
+    assert_sql(/WHERE "users"."tags" @> '\{ruby\}'/,
+      User.where { :users[:tags].member?('ruby') }.to_sql)
+  end
+
+  def test_member_negated
+    assert_sql(/WHERE NOT \("users"."tags" @> '\{ruby\}'\)/,
+      User.where { !:tags.member?('ruby') }.to_sql)
+  end
+
+  def test_member_multiple_elements
+    assert_sql(/WHERE "users"."tags" @> '\{ruby,rails\}'/,
+      User.where { :tags.member?(%w[ruby rails]) }.to_sql)
+  end
+
+  # MySQL additionally escapes the double quotes inside its string literal,
+  # so the exact spelling is only asserted where the operator is real.
+  def test_member_quotes_special_elements
+    skip_without_array_columns
+    assert_sql(/WHERE "users"."tags" @> '\{"with,comma"\}'/,
+      User.where { :tags.member?('with,comma') }.to_sql)
+  end
+
+  # include? is a substring match even on an array column; only member?
+  # means containment.
+  def test_include_is_like_even_on_array_columns
+    skip_without_array_columns
+    assert_sql(/WHERE "users"."tags" LIKE '%ruby%' ESCAPE '\\'/,
+      User.where { :tags.include?('ruby') }.to_sql)
+  end
+
+  # Elements survive the trip through the array literal: % is an ordinary
+  # character there, a comma stays inside its element, and quotes and
+  # backslashes are escaped.
+  def test_member_matches_elements_literally
+    skip_without_array_columns
+    User.delete_all
+    User.create!(name: 'literal', tags: ['100%', 'with,comma', 'q"uote', 'back\\slash'])
+    User.create!(name: 'lookalike', tags: ['100200', 'with', 'comma'])
+    assert_equal(['literal'], User.where { :tags.member?('100%') }.pluck(:name))
+    assert_equal(['literal'], User.where { :tags.member?('with,comma') }.pluck(:name))
+    assert_equal(['literal'], User.where { :tags.member?('q"uote') }.pluck(:name))
+    assert_equal(['literal'], User.where { :tags.member?('back\\slash') }.pluck(:name))
+  end
+
   def test_regexp
     skip_without_regexp_support
     assert_sql(/WHERE "users"."name" #{regexp_operator} '\^ma'/,
@@ -161,6 +240,16 @@ class TestBlockSyntax < Minitest::Test
       User.where { :users[:name].null? }.to_sql)
   end
 
+  def test_equal_nil_is_rejected
+    e = assert_raises(ArgumentError) { User.where { :name == nil } }
+    assert_match(/null\?/, e.message)
+  end
+
+  def test_not_equal_nil_is_rejected
+    e = assert_raises(ArgumentError) { User.where { :name != nil } }
+    assert_match(/null\?/, e.message)
+  end
+
   def test_in
     assert_sql(/WHERE "users"."age" IN \(1, 2, 3\)/,
       User.where { :age.in?([1, 2, 3]) }.to_sql)
@@ -176,6 +265,70 @@ class TestBlockSyntax < Minitest::Test
       User.where { !:age.in?([1, 2, 3]) }.to_sql)
   end
 
+  def test_in_subquery
+    assert_sql(
+      /WHERE "authors"."id" IN \(SELECT "posts"."author_id" FROM "posts" WHERE "posts"."title" = 'pub'\)/,
+      Author.where { :id.in?(Post.where(title: 'pub').select(:author_id)) }.to_sql)
+  end
+
+  # A relation without an explicit select list selects its primary key, the
+  # same way ActiveRecord's own where(id: relation) does.
+  def test_in_subquery_selects_primary_key_by_default
+    assert_sql(/WHERE "authors"."id" IN \(SELECT "posts"."id" FROM "posts"\)/,
+      Author.where { :id.in?(Post.all) }.to_sql)
+  end
+
+  def test_not_in_subquery
+    assert_sql(/WHERE NOT \("authors"."id" IN \(SELECT "posts"."author_id" FROM "posts"\)\)/,
+      Author.where { !:id.in?(Post.select(:author_id)) }.to_sql)
+  end
+
+  # The subquery correlates with the outer table through qualified columns,
+  # and its own where block goes through the DSL too.
+  def test_exists
+    assert_sql(
+      /WHERE EXISTS \(SELECT "posts"\.\* FROM "posts" WHERE "posts"."author_id" = "authors"."id"\)/,
+      Author.where { exists?(Post.where { :posts[:author_id] == :authors[:id] }) }.to_sql)
+  end
+
+  def test_not_exists
+    assert_sql(/WHERE NOT \(EXISTS \(SELECT "posts"\.\* FROM "posts"\)\)/,
+      Author.where { !exists?(Post.all) }.to_sql)
+  end
+
+  def test_exists_combined
+    assert_sql(
+      /WHERE "authors"."name" = 'matz' AND EXISTS \(SELECT "posts"\.\* FROM "posts" WHERE "posts"."title" = 'pub'\)/,
+      Author.where { (:name == 'matz') & exists?(Post.where(title: 'pub')) }.to_sql)
+  end
+
+  def test_exists_execution
+    Author.delete_all
+    Post.delete_all
+    with_post = Author.create!(name: 'with_post')
+    Author.create!(name: 'without')
+    Post.create!(title: 'pub', author_id: with_post.id)
+    correlated = -> { Post.where { :posts[:author_id] == :authors[:id] } }
+    assert_equal(['with_post'],
+      Author.where { exists?(correlated.call) }.pluck(:name))
+    assert_equal(['without'],
+      Author.where { !exists?(correlated.call) }.pluck(:name))
+  end
+
+  def test_in_subquery_execution
+    Author.delete_all
+    Post.delete_all
+    published = Author.create!(name: 'published')
+    drafting = Author.create!(name: 'drafting')
+    Post.create!(title: 'pub', author_id: published.id)
+    Post.create!(title: 'draft', author_id: drafting.id)
+    subquery = -> { Post.where(title: 'pub').select(:author_id) }
+    assert_equal(['published'],
+      Author.where { :id.in?(subquery.call) }.pluck(:name))
+    assert_equal(['drafting'],
+      Author.where { !:id.in?(subquery.call) }.pluck(:name))
+  end
+
   # == passes a Range or an Array through as a value rather than expanding it,
   # so that it compares against a PostgreSQL range or array column. The SQL
   # literal depends on the column type, so assert on the Arel node instead.

data/test/test_helper.rb

@@ -62,6 +62,10 @@ module SqlAssertions
     skip "#{ADAPTER} has no regexp operator" unless REGEXP_OPERATORS.key?(ADAPTER)
   end
 
+  def skip_without_array_columns
+    skip "#{ADAPTER} has no array columns" unless ADAPTER == 'postgresql'
+  end
+
   def regexp_operator
     Regexp.escape(REGEXP_OPERATORS.fetch(ADAPTER).first)
   end
@@ -105,7 +109,11 @@ class CreateAllTables < ActiveRecord::Migration[8.1]
     drop_table(:users, if_exists: true)
     drop_table(:authors, if_exists: true)
     drop_table(:posts, if_exists: true)
-    create_table(:users) {|t| t.string :name; t.integer :age}
+    create_table(:users) do |t|
+      t.string :name
+      t.integer :age
+      t.string :tags, array: true if ADAPTER == 'postgresql'
+    end
     create_table(:authors) {|t| t.string :name}
     create_table(:posts) {|t| t.string :title; t.integer :author_id}
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-refined
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
   - Shugo Maeda