activerecord-refined 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 244cb4019b7a281420222cdb796acac66c917b2178ae8a18126bcb67fca38b9d
-  data.tar.gz: 7e2120422a33273b64568ef1609a7e648a12c6190bf85ded8cc2ff281f292a7c
+  metadata.gz: f20876b4eb0b36ece84fc2f6a1c828461846b29bd829e279d31b22735cbf0c15
+  data.tar.gz: 4a717ffaf4991fa3a113ea4a6a619b16d431e8308e1869e22c988885022d450a
 SHA512:
-  metadata.gz: 8652b0d6ed1f957a72f014521ca3b6a9fedf2c8735771c81784724d7255a9714926a20411f7adb978211fe5ff05bddb64f41e2acc547df98ae3c0ab8ed48a308
-  data.tar.gz: ef23c519fa95df0a88f133d8e2f4161493a2879297e1de1d409e5578ebe74ca4597a8811fe89d5ee7ea806987d6a1fdda71e1cec487caaed9becfc7fcca9e26a
+  metadata.gz: 56734a22e7667270892abf1d6ab9fb0816a37043c5f1fe61a7367c40403f782af6dff7875b0f520ada5aef6ce89155f39919414a71d3abec279ccf3c538db578
+  data.tar.gz: f0aa350bbf6b80d1e36b156d2e997930195f2fcfe99c53ae449f3d0f44efe3870671c45bae52a7eac5f39c5f39adf129cbe5a1a1d3776b07eb8d29b1cfa470d2

data/.github/workflows/push_gem.yml

@@ -0,0 +1,45 @@
+name: push gem
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  push:
+    if: github.repository == 'shugo/activerecord-refined'
+    runs-on: ubuntu-latest
+
+    environment:
+      name: release
+      url: https://rubygems.org/gems/activerecord-refined
+
+    permissions:
+      # release-gem pushes the tag, and needs id-token to identify itself to
+      # RubyGems.org instead of an API key.
+      contents: write
+      id-token: write
+
+    env:
+      # Nothing here loads pg or mysql2, and building them needs client
+      # libraries the runner would have to install first.
+      BUNDLE_WITHOUT: db
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # release-gem sets up its own short-lived git credentials.
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          # Not `ruby`: the gemspec requires 4.1.0.dev for Proc#refined, so
+          # bundler refuses to resolve on a released Ruby.
+          ruby-version: head
+          bundler-cache: true
+
+      # Runs `rake release`, which builds the gem and pushes it. The tag it
+      # would create already exists here, so that step is skipped.
+      - uses: rubygems/release-gem@v1
+        with:
+          attestations: false

data/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: test
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      # SQLite only here, so skip building the pg and mysql2 extensions.
+      BUNDLE_WITHOUT: db
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          # Proc#refined has not been released yet, so master is the only
+          # Ruby that can run this.
+          ruby-version: head
+          bundler-cache: true
+      - run: bundle exec rake test

data/.gitignore

@@ -2,6 +2,7 @@
 *.rbc
 .bundle
 .config
+.ruby-version
 .yardoc
 Gemfile.lock
 InstalledFiles
@@ -12,6 +13,7 @@ lib/bundler/man
 pkg
 rdoc
 spec/reports
+t.rb
 test/tmp
 test/version_tmp
 tmp

data/Gemfile

@@ -2,3 +2,11 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in activerecord-refined.gemspec
 gemspec
+
+# Only ADAPTER=postgresql and ADAPTER=mysql2 need these, and building them
+# needs the client libraries installed.  `rake test` runs on SQLite, so a
+# checkout without them is still usable: bundle config set --local without db
+group :db do
+  gem 'mysql2'
+  gem 'pg'
+end

data/README.md

@@ -1,11 +1,13 @@
 # ActiveRecord::Refined
 
+[![test](https://github.com/shugo/activerecord-refined/actions/workflows/test.yml/badge.svg)](https://github.com/shugo/activerecord-refined/actions/workflows/test.yml)
+
 Adding clean and powerful query syntax on ActiveRecord using refinements.
 
 ```ruby
 Author.
   joins(:posts) { :posts[:author_id] == :authors[:id] }.
-  where { (:authors[:age] == (20..40)) & (:posts[:published] == true) }
+  where { :authors[:age].in?(20..40) & (:posts[:published] == true) }
 # SELECT "authors".* FROM "authors"
 #   INNER JOIN "posts" ON "posts"."author_id" = "authors"."id"
 #   WHERE "authors"."age" BETWEEN 20 AND 40 AND "posts"."published" = TRUE
@@ -68,20 +70,108 @@ denotes a qualified column.
 
 ```ruby
 Author.where { :age >= 18 }
-Author.where { :name =~ 'A%' }              # LIKE
-Author.where { :name !~ '%test%' }          # NOT LIKE
-Author.where { :age == (20..40) }           # BETWEEN
-Author.where { :country == %w[JP US] }      # IN
-Author.where { :country != %w[JP US] }      # NOT IN
+Author.where { :name.like?('A%') }          # LIKE
+Author.where { :age.in?(20..40) }           # BETWEEN
+Author.where { :age.between?(20, 40) }      # BETWEEN
+Author.where { :age.in?(18..) }             # >= 18
+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`.
+
+`start_with?`, `end_with?` and `include?` are shortcuts for the usual `like?`
+patterns. Unlike `like?`, they treat their argument as a literal string, so `%`
+and `_` in it are escaped rather than matched as wildcards:
+
+```ruby
+Author.where { :name.start_with?('A') }     # LIKE 'A%'
+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.
+
+```ruby
+Author.where { :name =~ '^A' }              # REGEXP / ~
+Author.where { :name !~ '^A' }              # NOT REGEXP / !~
+Author.where { :name =~ /son$/ }            # a Regexp literal works too
+```
+
+Only a literal's source crosses over; the database has its own dialect and no
+equivalent of Ruby's flags. Dropping one would silently change what the query
+matches, so `/son$/i` raises instead — pass the pattern as a string if the
+database can express what you mean.
+
+`==` always means SQL `=`, and passes its value through untouched. A Range or an
+Array therefore compares against a PostgreSQL range or array column, the same
+way ActiveRecord's own `where(period: from...to)` does for those column types:
+
+```ruby
+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:
+parentheses around each comparison necessary, though the `?` methods above need
+none:
 
 ```ruby
 Author.where { (:age >= 18) & ((:country == 'JP') | (:country == 'US')) }
-Author.where { !((:age == (0..17)) | :country.null?) }
+Author.where { !(:age.in?(0..17) | :country.null?) }
+Author.where { !:country.in?(%w[JP US]) }   # NOT (country IN ('JP', 'US'))
+Author.where { !:name.like?('%test%') }     # NOT (name LIKE '%test%')
 ```
 
 ### Joins
@@ -103,6 +193,13 @@ functions `upper`, `lower`, `length`, `trim`, `coalesce`, `abs` and `round`. Use
 for a column alias, and `.asc` / `.desc` for the sort direction. Return an array to
 select or order by multiple expressions.
 
+Pass `:*` to `count` for `COUNT(*)`:
+
+```ruby
+Author.group { :country }.having { count(:*) > 1 }
+# SELECT "authors".* FROM "authors" GROUP BY "authors"."country" HAVING COUNT(*) > 1
+```
+
 ```ruby
 Author.
   joins(:posts) { :posts[:author_id] == :authors[:id] }.
@@ -121,6 +218,42 @@ Author.
 
 See `examples/` for complete, runnable scripts.
 
+## Running the tests
+
+The tests only build SQL, but they need a live connection to do it. SQLite is
+the default; set `ADAPTER` to run the same suite against another one.
+
+```sh
+rake test                    # sqlite3
+ADAPTER=postgresql rake test
+ADAPTER=mysql2 rake test
+rake test:all                # all three in turn
+```
+
+PostgreSQL and MySQL are reached on `127.0.0.1` as the current user with no
+password, which is how the devcontainer sets them up. Override with
+`DB_HOST`, `DB_USERNAME` and `DB_PASSWORD`. The `activerecord_refined_test`
+database is created on first use.
+
+The `pg` and `mysql2` gems are in the Gemfile's `db` group, since building them
+needs the client libraries installed. Skip them if SQLite is all you need,
+which is what CI does:
+
+```sh
+bundle config set --local without db
+```
+
+## Releasing
+
+Pushing a `v*` tag runs `.github/workflows/push_gem.yml`, which builds the gem
+and publishes it through RubyGems.org's trusted publishing, so no API key is
+stored anywhere.
+
+```sh
+bump patch --tag # or bump {major,minor} etc.
+git push --follow-tags
+```
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1,8 +1,25 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
+ADAPTERS = %w[sqlite3 postgresql mysql2].freeze
+
 Rake::TestTask.new do |t|
   t.test_files = FileList['test/test_*.rb']
 end
 
+namespace :test do
+  ADAPTERS.each do |adapter|
+    desc "Run the tests against #{adapter}"
+    task adapter do
+      puts "==== #{adapter} ===="
+      ENV['ADAPTER'] = adapter
+      Rake::Task[:test].reenable
+      Rake::Task[:test].invoke
+    end
+  end
+
+  desc "Run the tests against every adapter in turn"
+  task all: ADAPTERS
+end
+
 task default: :test

data/examples/aggregations.rb

@@ -0,0 +1,91 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'active_record'
+require 'activerecord-refined'
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Migration.verbose = false
+
+class Setup < ActiveRecord::Migration[8.1]
+  def up
+    create_table(:authors) {|t| t.string :name; t.integer :age; t.string :country }
+    create_table(:posts)   {|t| t.string :title; t.integer :author_id; t.integer :likes; t.boolean :published }
+    create_table(:comments){|t| t.string :body; t.integer :post_id; t.integer :score }
+  end
+end
+Setup.new.up
+
+class Author < ActiveRecord::Base
+  has_many :posts
+end
+
+class Post < ActiveRecord::Base
+  belongs_to :author
+  has_many :comments
+end
+
+class Comment < ActiveRecord::Base
+  belongs_to :post
+end
+
+# 1. Post statistics per author
+#    JOIN + GROUP BY + aggregate functions + AS + HAVING + ORDER BY
+query1 =
+  Author.
+    joins(:posts) { :posts[:author_id] == :authors[:id] }.
+    where { :posts[:published] == true }.
+    group { :authors[:id] }.
+    having { count(:posts[:id]) > 1 }.
+    order { count(:posts[:id]).desc }.
+    select {
+      [
+        upper(:authors[:name]).as(:author),
+        count(:posts[:id]).as(:post_count),
+        avg(:posts[:likes]).as(:avg_likes),
+        max(:posts[:likes]).as(:top_likes),
+      ]
+    }
+
+puts "--- 1. Per-author post stats (GROUP BY / aggregates / AS / HAVING / ORDER BY) ---"
+puts query1.to_sql
+puts
+
+# 2. Author count per country (NULL is folded into 'unknown')
+#    coalesce function + GROUP BY + aggregates + multiple ORDER BY
+query2 =
+  Author.
+    group { coalesce(:country, 'unknown') }.
+    order { [count(:id).desc, coalesce(:country, 'unknown').asc] }.
+    select {
+      [
+        coalesce(:country, 'unknown').as(:country),
+        count(:id).as(:author_count),
+        avg(:age).as(:avg_age),
+      ]
+    }
+
+puts "--- 2. Authors per country (coalesce / GROUP BY / multi ORDER BY) ---"
+puts query2.to_sql
+puts
+
+# 3. Aggregate comment scores across a multi-level JOIN
+#    authors -> posts -> comments, compound WHERE + GROUP BY + HAVING + ORDER BY
+query3 =
+  Author.
+    joins(:posts) { :posts[:author_id] == :authors[:id] }.
+    joins(:comments) { :comments[:post_id] == :posts[:id] }.
+    where { !:posts[:title].include?('draft') & (:comments[:score] >= 0) }.
+    group { :authors[:id] }.
+    having { sum(:comments[:score]) > 10 }.
+    order { sum(:comments[:score]).desc }.
+    select {
+      [
+        :authors[:name].as(:author),
+        count(:comments[:id]).as(:comment_count),
+        sum(:comments[:score]).as(:total_score),
+      ]
+    }
+
+puts "--- 3. Comment score aggregation across multi-table JOIN ---"
+puts query3.to_sql
+puts

data/examples/complex_joins.rb

@@ -0,0 +1,69 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'active_record'
+require 'activerecord-refined'
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Migration.verbose = false
+
+class Setup < ActiveRecord::Migration[8.1]
+  def up
+    create_table(:authors) {|t| t.string :name; t.integer :age; t.string :country }
+    create_table(:posts)   {|t| t.string :title; t.integer :author_id; t.integer :likes; t.boolean :published }
+    create_table(:comments){|t| t.string :body; t.integer :post_id; t.integer :score }
+  end
+end
+Setup.new.up
+
+class Author < ActiveRecord::Base
+  has_many :posts
+end
+
+class Post < ActiveRecord::Base
+  belongs_to :author
+  has_many :comments
+end
+
+class Comment < ActiveRecord::Base
+  belongs_to :post
+end
+
+# 1. INNER JOIN + compound WHERE conditions (AND / OR / BETWEEN / IN)
+query1 =
+  Author.
+    joins(:posts) { :posts[:author_id] == :authors[:id] }.
+    where {
+      (:authors[:age].in?(20..40) & (:posts[:published] == true)) |
+        :authors[:country].in?(%w[JP US])
+    }
+
+puts "--- 1. INNER JOIN with compound conditions ---"
+puts query1.to_sql
+puts
+
+# 2. Multi-level JOIN (authors -> posts -> comments) + negated LIKE / IN
+query2 =
+  Author.
+    joins(:posts) { :posts[:author_id] == :authors[:id] }.
+    joins(:comments) { :comments[:post_id] == :posts[:id] }.
+    where {
+      !:posts[:title].include?('draft') &
+        !:comments[:score].in?([0, -1]) &
+        (:authors[:age] >= 18)
+    }
+
+puts "--- 2. Multi-table JOIN with negated LIKE / IN ---"
+puts query2.to_sql
+puts
+
+# 3. LEFT OUTER JOIN + NOT / range conditions
+query3 =
+  Author.
+    left_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }.
+    where {
+      !(:posts[:likes].in?(0..9) | (:posts[:published] == false))
+    }
+
+puts "--- 3. LEFT OUTER JOIN with negation ---"
+puts query3.to_sql
+puts