activerecord-refined 0.8.1 → 0.10.0

data/activerecord-refined.gemspec

@@ -1,33 +1,52 @@
 # -*- encoding: utf-8 -*-
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'activerecord-refined/version'
+require "activerecord-refined/version"
 
 Gem::Specification.new do |gem|
   gem.name          = "activerecord-refined"
   gem.version       = Activerecord::Refined::VERSION
   gem.authors       = ["Shugo Maeda"]
   gem.email         = ["shugo@ruby-lang.org"]
-  gem.description   = 'Adding clean and powerful query syntax on Active Record using refinements'
-  gem.summary       = 'Write Active Record queries as Ruby expressions'
-  gem.homepage      = 'https://github.com/shugo/activerecord-refined'
+  gem.description   = "Adding clean and powerful query syntax on Active Record using refinements"
+  gem.summary       = "Write Active Record queries as Ruby expressions"
+  gem.homepage      = "https://github.com/shugo/activerecord-refined"
+  gem.license       = "MIT"
+  gem.metadata      = {
+    "documentation_uri" => "https://rubydoc.info/gems/activerecord-refined",
+  }
 
-  # sandbox/ is a site, not part of the library: its Gemfile.lock and
-  # package-lock.json have no business in anyone's bundle.  CLAUDE.md is
-  # addressed to whoever is working on the repository, not to anyone using it.
-  gem.files         = `git ls-files`.split($/).grep_v(%r{^sandbox/|^CLAUDE\.md$})
-  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.files         = `git ls-files -- lib docs examples README.md LICENSE.txt .yardopts activerecord-refined.gemspec`.split($/)
   gem.require_paths = ["lib"]
 
   # Proc#refined is available since Ruby 4.1. 4.1.0.dev is required to allow
   # ruby-master builds, which sort before the 4.1.0 release.
-  gem.required_ruby_version = '>= 4.1.0.dev'
+  gem.required_ruby_version = ">= 4.1.0.dev"
 
-  gem.add_dependency 'activerecord', ['>= 7.0']
-  gem.add_development_dependency 'sqlite3', ['>= 0']
-  gem.add_development_dependency 'minitest', ['>= 0']
-  gem.add_development_dependency 'rake', ['>= 0']
+  gem.add_dependency "activerecord", [">= 7.0"]
+  gem.add_development_dependency "sqlite3", [">= 0"]
+  gem.add_development_dependency "minitest", [">= 0"]
+  gem.add_development_dependency "rake", [">= 0"]
   # What cuts a release: `bump patch --tag`, then push with --follow-tags.
-  gem.add_development_dependency 'bump', ['>= 0']
+  gem.add_development_dependency "bump", [">= 0"]
+  # What benchmark/query_building.rb measures with.
+  gem.add_development_dependency "benchmark-ips", [">= 0"]
+  gem.add_development_dependency "memory_profiler", [">= 0"]
+  # The style is Rails' own: .rubocop.yml is theirs with this repository's
+  # paths, and these are the plugins it loads.
+  gem.add_development_dependency "rubocop", [">= 0"]
+  gem.add_development_dependency "rubocop-minitest", [">= 0"]
+  gem.add_development_dependency "rubocop-packaging", [">= 0"]
+  gem.add_development_dependency "rubocop-performance", [">= 0"]
+  gem.add_development_dependency "rubocop-rails", [">= 0"]
+  gem.add_development_dependency "rubocop-md", [">= 0"]
+  # What renders the reference: `yard server --reload` serves it locally, and
+  # rubydoc.info renders the same .yardopts.  The plugin turns the README's
+  # relative links to docs/*.md -- which GitHub follows as they are -- into
+  # links to YARD's file pages; where it is not installed, rubydoc.info among
+  # them, YARD says so and leaves the links relative.
+  gem.add_development_dependency "yard", [">= 0"]
+  gem.add_development_dependency "yard-markdown-relative-links", [">= 0"]
 end

data/docs/conditions.md

@@ -0,0 +1,206 @@
+# Conditions
+
+
+```ruby
+Author.where { :age >= 18 }
+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
+```
+
+`!` negates any of these. Where SQL has a negative of its own, so does the
+block, which is the same rows written the way they would be written by hand:
+
+```ruby
+Author.where { :country.not_null? }             # IS NOT NULL
+Author.where { :country.not_in?(%w[JP US]) }    # NOT IN
+Author.where { :age.not_between?(20, 40) }      # not between 20 and 40
+Author.where { :name.not_like?("A%") }          # NOT LIKE
+Author.where { :name.not_ilike?("a%") }         # NOT ILIKE / NOT LIKE
+
+Author.where { !:name.start_with?("A") }        # NOT (name LIKE 'A%')
+```
+
+Nothing turns on the choice: `NOT (country IS NULL)` and `country IS NOT NULL`
+select the same rows, NULLs included. `not_between?` is the one whose SQL
+looks unlike its name — Arel writes it as the two comparisons, `age < 20 OR
+age > 40`, which is again the same rows.
+
+A number compares as itself, the way a bound `?` does: `:age >= 99.5` says
+`>= 99.5`, where `where(age: 99.5..)` casts to the column's type and says
+`>= 99`, letting an age of 99 through a bound it does not satisfy. Everything
+that is not an `Integer`, `Float` or `BigDecimal` keeps the column's own
+serialization — an enum's name, a time's zone, a custom type's scaling — so a
+custom type that scales a number, money kept in cents, is the one place the
+number has to be written as the column stores it.
+
+A boolean column has `true?` and `false?`, which become SQL's `IS TRUE` and
+`IS FALSE`, and the two negations to go with them:
+
+```ruby
+Post.where { :published.true? }         # IS TRUE
+Post.where { :published.not_true? }     # IS NOT TRUE
+Post.where { :published.false? }        # IS FALSE
+Post.where { :published.not_false? }    # IS NOT FALSE
+```
+
+`published = TRUE` selects the same rows as `published IS TRUE`, so the
+difference is in the negation: `published = TRUE` is itself NULL for a row
+where the column is, and a NULL predicate selects nothing, while `IS TRUE`
+answers false there. `not_true?` is therefore "false or never set" and
+`!(:published == true)` only "false". Every adapter spells all four the same
+way and answers them alike.
+
+`in?` also takes a relation as a subquery. Without an explicit select list the
+subquery selects the relation's primary key, the same way Active Record'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 ...)
+```
+
+A relation on the right of a comparison is a scalar subquery. It has to select
+one value, so unlike `in?` there is no default select list and one is
+required:
+
+```ruby
+Author.where { :age >= Author.select { avg(:age) } }
+# "authors"."age" >= (SELECT AVG("authors"."age") FROM "authors")
+```
+
+`any` and `all` quantify that comparison instead, which is what lifts the
+one-row rule: `> any` asks whether the subquery holds a smaller value anywhere,
+`>= all` whether it holds a larger one nowhere.
+
+```ruby
+Author.where { :age > any(Author.where(country: "JP").select(:age)) }
+# "authors"."age" > ANY(SELECT "authors"."age" FROM "authors" WHERE ...)
+
+Author.where { :age >= all(Author.select(:age)) }
+# "authors"."age" >= ALL(SELECT "authors"."age" FROM "authors")
+```
+
+The select list follows `in?`'s rule rather than the scalar one: without an
+explicit select the subquery selects the primary key. `== any` is what `IN`
+says and `!= all` what `NOT IN` says, so what the quantifiers add is the four
+comparisons `IN` has no spelling for. SQLite has neither quantifier, and says
+so with `NotImplementedError` rather than leaving its parser to.
+
+`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`. `ilike?` is the one that asks for
+`ILIKE`; off PostgreSQL it is plain `LIKE`, which those adapters already match
+case-insensitively under their default collations. `casecmp?` is
+case-insensitive equality, folded on both sides rather than left to the
+collation, so it means the same thing everywhere:
+
+```ruby
+Author.where { :name.ilike?("ma%") }        # ILIKE 'ma%' / LIKE 'ma%'
+Author.where { :name.casecmp?("Alice") }     # LOWER(name) = LOWER('Alice')
+```
+
+`not_distinct_from?` and `distinct_from?` compare with NULL treated as a
+value, rather than as the unknown that makes `=` and `<>` neither true nor
+false. PostgreSQL spells this `IS [NOT] DISTINCT FROM`, SQLite `IS` / `IS NOT`
+and MySQL `<=>`, and the rows that come back are the same on all three:
+
+```ruby
+Author.where { :country.not_distinct_from?(params[:country]) }  # matches NULL to nil
+Author.where { :country.distinct_from?("JP") }                  # keeps the NULL rows
+```
+
+`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?`, `superset?`, `subset?` and `intersect?` compare against a
+PostgreSQL array column, each carrying the meaning of its Ruby namesake:
+`member?` is Enumerable's element test (which String does not have — that is
+what separates it from `include?`), `superset?` and `subset?` are Set's
+whole-array containment, and `intersect?` is Array's "any element in common":
+
+```ruby
+Article.where { :tags.member?("ruby") }            # tags @> '{ruby}'
+Article.where { :scores.member?(80) }              # scores @> '{80}'
+Article.where { :tags.superset?(%w[ruby rails]) }  # tags @> '{ruby,rails}'
+Article.where { :tags.subset?(%w[ruby rails go]) } # tags <@ '{ruby,rails,go}'
+Article.where { :tags.intersect?(%w[ruby go]) }    # tags && '{ruby,go}'
+```
+
+Like its namesake, `member?` takes one element — `[1, 2].member?([1])` is
+false in Ruby, so an Array argument raises rather than quietly meaning
+something `Array#member?` does not. Requiring every element is `superset?`.
+
+`=~` 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 Active Record'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}'
+```
+
+`!=` is SQL `!=` under the same rules, value passed through untouched.
+
+For the same reason `== nil` and `!= nil` raise `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:
+
+```ruby
+Author.where { (:age >= 18) & ((:country == "JP") | (:country == "US")) }
+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%')
+```

data/docs/ctes.md

@@ -0,0 +1,65 @@
+# Common table expressions
+
+
+Active Record's `with` and `with_recursive` need nothing from this gem: a CTE
+is joined by name like any other table, so its `ON` clause is a block, where
+Rails' own documentation reaches for a string join.
+
+`from_cte` takes the CTE's name and selects it under the model's own table
+name, so the model's columns resolve:
+
+```ruby
+Node.with_recursive(
+  tree: [
+    Node.where { :id == root.id }.
+      select { [:id, :name, :parent_id, 0.as(:depth)] },
+    Node.joins(:tree) { :nodes[:parent_id] == :tree[:id] }.
+      select { [:id, :name, :parent_id, (:tree[:depth] + 1).as(:depth)] },
+  ]
+).from_cte(:tree)
+# WITH RECURSIVE "tree" AS (
+#   SELECT "nodes"."id", "nodes"."name", "nodes"."parent_id", 0 AS depth
+#     FROM "nodes" WHERE "nodes"."id" = 1
+#   UNION ALL
+#   SELECT "nodes"."id", "nodes"."name", "nodes"."parent_id",
+#          ("tree"."depth" + 1) AS depth
+#     FROM "nodes" INNER JOIN "tree" ON "nodes"."parent_id" = "tree"."id"
+# ) SELECT "nodes".* FROM "tree" AS "nodes"
+```
+
+The anchor starts the count and the recursive member adds one, which is how
+the shape of a tree comes out of a flat table. The `0` is a value rather than
+SQL — see [`value`](functions.md) for why a number can say `.as` directly.
+
+The alias on the last line is there for Active Record's sake, not SQL's:
+written by hand that line would be `SELECT * FROM tree`. Active Record goes on qualifying
+columns with the model's table name, so without the alias that name is not in
+the query and anything qualifying a column fails:
+
+```ruby
+Node.with_recursive(tree: [...]).from(:tree).where(name: 'root')
+# PG::UndefinedTable: missing FROM-clause entry for table "nodes"
+```
+
+Since the model's name is the only one that works, `from_cte` takes it from
+the model rather than asking. It also checks that the name is one `with`
+declares, so a typo is an `ArgumentError` here rather than a query against a
+table nobody has — checked when the SQL is built, so the CTE may be declared
+later in the chain or by a scope merged into it.
+
+`from(:tree, as: :nodes)` is the same thing spelled out, without the check,
+and is what to reach for when the name wanted is not the model's.
+
+What makes this worth spelling out is how selectively it breaks. `count`,
+`order` and `select` never qualify, so they work without the alias on every
+adapter; it is `where` and `find_by` that stop. A query can therefore look
+right until the day a condition is added to it.
+
+A non-recursive CTE joins the same way:
+
+```ruby
+Node.with(roots: Node.where { :parent_id.null? }).
+  joins(:roots) { :roots[:id] == :nodes[:parent_id] }
+```
+
+`examples/ctes.rb` walks a category tree with these.

data/docs/expressions.md

@@ -0,0 +1,125 @@
+# Expressions
+
+
+`+`, `-`, `*` and `/` build arithmetic. Ruby puts them above the comparison
+operators, so an expression groups the way it reads:
+
+```ruby
+Item.where { :price * :quantity > 1000 }
+Item.select { sum(:price * :quantity).as(:total) }
+```
+
+The number may stand on the left — only a column or an expression on the
+right builds a query, so Ruby's own arithmetic is untouched — and
+`BigDecimal` is a number here, being what a decimal column's values are,
+quoted as the exact decimal on either side. A `Rational` is refused: no
+decimal spells `1/3r` exactly, and `to_d` is what says the decimal meant.
+
+```ruby
+Item.select { greatest(20 - :quantity, 0).as(:shortfall) }
+Item.where { BigDecimal("1.08") * :price > 500 }
+```
+
+`&`, `|`, `^`, `~`, `<<` and `>>` are SQL's bitwise operators. Between
+conditions `&` and `|` are AND and OR, and that is where they are defined,
+which leaves them free to mean here what SQL means by them:
+
+```ruby
+Post.where { :flags & 4 > 0 }
+# WHERE ("posts"."flags" & 4) > 0
+
+Post.select { (:flags | 4).as(:flags) }
+Post.select { (~:flags).as(:inverted) }
+```
+
+Each parenthesises itself, which is what keeps Ruby's grouping: PostgreSQL
+gives `&` and `|` the same precedence and reads `a | b & c` from the left,
+where Ruby reads the `&` first.
+
+A boolean column is refused rather than taken for the one bit it is stored as.
+MySQL and SQLite would quietly answer as `AND` would, PostgreSQL has no such
+operator at all, and one block meaning two things is worse than an
+`ArgumentError` saying that `true?` is what makes a boolean column a
+condition. A condition as an operand is refused for the same reason.
+
+XOR is the one the three do not share, and the one where guessing costs most:
+MySQL spells it `^`, which is exponentiation to PostgreSQL, and PostgreSQL
+spells it `#`, which is where a comment starts on MySQL — either way a wrong
+answer rather than an error. Each adapter gets its own, and SQLite, which has
+no XOR at all, gets the two operations it is made of, `(a | b) - (a & b)`.
+That names each operand twice, so keep them cheap.
+
+`bit_and`, `bit_or` and `bit_xor` are the aggregates of the first three, and
+`bit_count` counts the bits that are set. SQLite has none of the four.
+PostgreSQL counts the bits of a bit string rather than of a number, so the
+argument is cast there, to `bit(64)` because that is what makes a negative
+count as it does on MySQL:
+
+```ruby
+Post.group { :author_id }.select { bit_or(:flags).as(:flags) }
+# SELECT BIT_OR("posts"."flags") AS "flags" ... GROUP BY "posts"."author_id"
+
+Post.select { bit_count(:flags).as(:bits) }
+# MySQL:      BIT_COUNT("posts"."flags")
+# PostgreSQL: BIT_COUNT(CAST("posts"."flags" AS bit(64)))
+```
+
+`bit_xor` arrived in PostgreSQL 14. `~` is where the three disagree about the
+answer rather than the question: MySQL reads it back as the unsigned 64-bit
+number, the others as a negative one, and the bits are the same either way.
+
+One place asks for a value to be said out loud: the top of a select list.
+Everywhere else a bare literal is already a value — `where { :age > 18 }`,
+`concat(:name, '-x')` — but a bare string at the top of the list would be SQL
+to Active Record and a value everywhere else in the block, so it is refused
+rather than read either way: `sql` says the SQL, `value` the value. `value`
+carries the predications and arithmetic with it, so a literal can be compared
+and combined like anything else, and numbers and strings have a shorthand,
+since a literal that has been sent `as` has already said it is a value:
+
+```ruby
+Node.select { [:id, value(0).as(:depth)] }
+# SELECT "nodes"."id", 0 AS depth FROM "nodes"
+
+Node.select { [:id, 0.as(:depth)] }         # the same thing
+
+Post.select { [:title, "draft".as(:state)] }
+# SELECT "posts"."title", 'draft' AS state FROM "posts"
+```
+
+What the shorthand does not cover, `value` still spells: `value(true)`,
+`value(nil)`, or a literal that goes on to be compared rather than selected.
+
+`CASE` is grammar rather than a function, and has two shapes. With an operand, each `when` is
+something to compare it against; without one, each `when` carries a condition
+of its own. `case` is a Ruby keyword, so the method behind both is only
+reachable through the receiver — `self.case` — and each shape has a shorthand
+that does not need it:
+
+```ruby
+Author.select { :country.when("JP").then("Japan").else("elsewhere").as(:where) }
+# CASE "country" WHEN 'JP' THEN 'Japan' ELSE 'elsewhere' END AS where
+
+Author.select { case_when { :age >= 60 }.then("senior").else("adult").as(:band) }
+# CASE WHEN "age" >= 60 THEN 'senior' ELSE 'adult' END AS band
+
+Author.select { self.case(mod(:age, 10)).when(0).then("round").else("not").as(:v) }
+```
+
+A `when` takes a value or a block, and so do `then` and `else`; the block is
+there to read like the blocks around it, since an argument works just as well
+— `:age >= 60` has already become an expression by the time it is passed.
+Leaving the `else` off is SQL's own default, which is NULL. `when` and `then`
+come in pairs, and one without the other is an `ArgumentError` rather than
+something that reaches the database:
+
+```ruby
+Author.select {
+  case_when { :age < 18 }.then("minor").
+    when { :age >= 60 }.then("senior").
+    else("adult").as(:band)
+}
+
+Author.select { sum(case_when { :age >= 60 }.then(1).else(0)).as(:seniors) }
+# SUM(CASE WHEN "age" >= 60 THEN 1 ELSE 0 END) AS seniors
+```