activerecord-refined 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f77f34a31719d6697c0d77c378392a6bffa95f033345272e981c51f3fb6f977
-  data.tar.gz: bed64c1983fd76634d924a28a690e3b54705f9a948bf06735314ddd91bed0037
+  metadata.gz: 8ee6cc682434a9d10c523f5df80085c460ba44fc6fa8653304a38fbd0cf85c83
+  data.tar.gz: 55185eb38377c3ba4cb57136a68157531527f8ec7ea4e5cc568c95be88cdf2a1
 SHA512:
-  metadata.gz: cd03b6d8647c0aef54927c5c68f6c7145ebfcdfa1223abc9b9650905dbaf21281b05678cd708889297a75dfc388e17b886358ebd6db445948b209d1e84d9f6f1
-  data.tar.gz: 2d971fb7ea3f757569b3a8e0127c52693afd20a5eeb15523dd58d2747376f2e426833ef71a343c880e9d225fb9f1a37f1a3f16f1998ac96fb6341e7c5f3f8fb6
+  metadata.gz: 5dc45baffd355d00a918c144ae802c4f8f5ab2288b792bf1660f16978d65fd909e449b9c65a14fff834a89011eb632b2428c1fd9abaf5bdc5705f557e336551a
+  data.tar.gz: b6b35bebfc29eaba5c793268fc7e343aed5323e7078c81a25a1add336969e415b0951fe6d92bc8abe4e513151bfe3c94acadefd2d59a5a320fd2bb2f5f9778bc

data/.yardopts

@@ -1,6 +1,6 @@
 --markup markdown
 --no-private
---title "ActiveRecord::Refined"
+--title "activerecord-refined"
 --readme docs/index.md
 lib/**/*.rb
 -

data/README.md

@@ -1,4 +1,4 @@
-# ActiveRecord::Refined
+# activerecord-refined
 
 [![gem](https://img.shields.io/gem/v/activerecord-refined.svg)](https://rubygems.org/gems/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)
@@ -14,21 +14,12 @@ Author.
 #   WHERE "authors"."age" BETWEEN 20 AND 40 AND "posts"."published" = TRUE
 ```
 
-Inside a block, symbols denote columns of the receiver's table, and
-`:table[:column]` denotes a qualified column. That holds in every position —
-on the right of a comparison too, so `:age == :retirement_age` compares two
-columns. A value is written as its literal, an enum's as its string; a symbol
-naming no column of the model is refused rather than compared against nothing
-anyone meant.
-
-**[Try it in your browser](https://shugo.github.io/activerecord-refined/)** —
-Ruby 4.1, Active Record, SQLite and PostgreSQL run in the page, so the examples
-build real SQL and return real rows without a `ruby-master` build of your own.
+**[Try it in your browser](https://shugo.github.io/activerecord-refined/)**
 
 ## Requirements
 
 * Ruby 4.1 or later (for `Proc#refined`; not released yet, so a `ruby-master` build is needed for now)
-* Active Record 7.0 or later
+* Active Record 7.2 or later
 
 ## Installation
 
@@ -92,28 +83,28 @@ block DSL and through Active Record's other argument styles. Only query
 construction (through `to_sql`) is measured — every style produces the same
 SQL, so execution costs the same regardless.
 
-Queries built per second (ruby 4.1.0dev, Active Record 8.1.3, one machine —
+Queries built per second (ruby 4.1.0dev, Active Record 8.1.3.1, one machine —
 treat the ratios, not the absolute numbers, as the result):
 
 | query | string | arel | block (this gem) | hash | relation and/or |
 | --- | --- | --- | --- | --- | --- |
-| simple equality | 42.5k | 42.0k | 37.7k | 31.5k | — |
-| range (BETWEEN) | — | 34.6k | 32.7k | 24.8k | — |
-| LIKE | 41.5k | 41.0k | 36.8k | — | — |
-| compound AND/OR | 34.4k | 27.7k | 24.4k | — | 11.9k |
+| simple equality | 40.9k | 40.5k | 36.1k | 31.5k | — |
+| range (BETWEEN) | — | 33.7k | 31.8k | 24.7k | — |
+| LIKE | 40.1k | 39.9k | 36.4k | — | — |
+| compound AND/OR | 32.8k | 26.7k | 23.4k | — | 11.4k |
 
 Allocated memory per built query:
 
 | query | arel | block (this gem) | hash | string | relation and/or |
 | --- | --- | --- | --- | --- | --- |
-| simple equality | 2,600 B | 2,832 B | 3,328 B | 3,448 B | — |
-| compound AND/OR | 3,208 B | 3,584 B | — | 4,680 B | 9,120 B |
+| simple equality | 2,176 B | 2,392 B | 2,576 B | 2,976 B | — |
+| compound AND/OR | 2,744 B | 3,104 B | — | 4,144 B | 7,152 B |
 
 In short: the block DSL is 6–13% slower than hand-written Arel (which it
 compiles to), a little faster than hash conditions, and both faster and
 leaner than `where(...).and(where(...).or(where(...)))` relation chains,
 which pay for structural-compatibility checks and relation copies. The
-`Proc#refined` call itself costs about 150 ns of the ~25 μs build — the
+`Proc#refined` call itself costs about 170 ns of the ~28 μs build — the
 re-interpretation of the block is not where the time goes. Against a
 database round trip of tens to hundreds of microseconds, none of these
 differences are visible in an application.
@@ -123,8 +114,8 @@ under the refinements, `Proc#refined` deep-copies its instruction sequence,
 nested blocks included. The copy is made lazily on the refined proc's first
 call and memoized per block and refinement list for the life of the process,
 so it is paid once per `where { ... }` call site, not per query — the
-benchmark measures the copy at the size of the original (568 bytes for the
-simple-equality block, 888 bytes for the compound one), and a thousand
+benchmark measures the copy at the size of the original (552 bytes for the
+simple-equality block, 872 bytes for the compound one), and a thousand
 further calls from the same call site copy nothing. Steady state, an
 application holds one extra copy of each distinct query block's bytecode:
 a few hundred bytes per call site. "Per call site" assumes blocks compiled
@@ -187,6 +178,12 @@ CI runs one job per adapter with the servers as service containers, Oracle
 and SQL Server included — those two have no local server here and run on CI
 alone, their clients opted in the same way.
 
+Coverage is opt-in: `COVERAGE=1 rake test` writes an HTML report to
+`coverage/`, and `COVERAGE=1 rake test:all` merges the adapters' runs into
+one — the number worth reading, since a dialect's lines are reached only by
+its own adapter's leg. The Oracle and SQL Server dialects stay mostly
+uncovered locally for the same reason their tests run on CI alone.
+
 ## Releasing
 
 Pushing a `v*` tag runs `.github/workflows/push_gem.yml`, which builds the gem

data/activerecord-refined.gemspec

@@ -3,11 +3,11 @@
 
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "activerecord-refined/version"
+require "active_record/refined/version"
 
 Gem::Specification.new do |gem|
   gem.name          = "activerecord-refined"
-  gem.version       = Activerecord::Refined::VERSION
+  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"
@@ -25,10 +25,11 @@ Gem::Specification.new do |gem|
   # ruby-master builds, which sort before the 4.1.0 release.
   gem.required_ruby_version = ">= 4.1.0.dev"
 
-  gem.add_dependency "activerecord", [">= 7.0"]
+  gem.add_dependency "activerecord", [">= 7.2"]
   gem.add_development_dependency "sqlite3", [">= 0"]
   gem.add_development_dependency "minitest", [">= 0"]
   gem.add_development_dependency "rake", [">= 0"]
+  gem.add_development_dependency "simplecov", [">= 0"]
   # What cuts a release: `bump patch --tag`, then push with --follow-tags.
   gem.add_development_dependency "bump", [">= 0"]
   # What benchmark/query_building.rb measures with.

data/docs/conditions.md

@@ -196,7 +196,9 @@ 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:
+none. Leaving them off is mostly refused, but beside `true`, `false` or `nil`
+it is Ruby's own `&` that runs, and the condition to its right is lost without
+a word: `:active == true & cond` is `:active == true`.
 
 ```ruby
 Author.where { (:age >= 18) & ((:country == "JP") | (:country == "US")) }

data/docs/expressions.md

@@ -9,15 +9,18 @@ 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.
+A number may stand on the left of an expression, and Ruby's own arithmetic
+is untouched. Before a bare column, though, the number is written with
+`value`: to Ruby, `20 - :quantity` is a number minus a symbol, and the number
+has no way to know the symbol is a column. `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 }
+Item.select { greatest(value(20) - :quantity, 0).as(:shortfall) }
+Item.select { (100 - (:price * :quantity)).as(:headroom) }
+Item.where { :price * BigDecimal("1.08") > 500 }
 ```
 
 `bitwise_and`, `bitwise_or`, `^`, `~`, `<<` and `>>` are SQL's bitwise

data/docs/index.md

@@ -1,4 +1,4 @@
-# ActiveRecord::Refined
+# activerecord-refined
 
 Adding clean and powerful query syntax on Active Record using refinements.
 

data/examples/expressions.rb

@@ -58,17 +58,17 @@ show("an aggregate over an expression",
   LineItem.select { sum(:price * :quantity).as(:total) },
   LineItem.select { sum(:price * :quantity).as(:total) }.first.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.  BigDecimal
-# is a number here too -- what a decimal column's values are.
-show("the number on the left, and a BigDecimal",
-  LineItem.select { [:sku, (12 - :quantity).as(:to_the_dozen)] },
-  LineItem.select { [:sku, (12 - :quantity).as(:to_the_dozen)] }.
+# A number may stand on the left of an expression; before a bare column it
+# is written with value().  BigDecimal is a number here too -- what a
+# decimal column's values are.
+show("the number on the left",
+  LineItem.select { [:sku, (value(12) - :quantity).as(:to_the_dozen)] },
+  LineItem.select { [:sku, (value(12) - :quantity).as(:to_the_dozen)] }.
     map { |i| [i.sku, i.to_the_dozen] })
 
 show("a tax through BigDecimal, exact on the wire",
-  LineItem.select { [:sku, (BigDecimal("1.1") * :price).as(:taxed)] },
-  LineItem.select { [:sku, (BigDecimal("1.1") * :price).as(:taxed)] }.
+  LineItem.select { [:sku, (BigDecimal("1.1") * (:price * :quantity)).as(:taxed)] },
+  LineItem.select { [:sku, (BigDecimal("1.1") * (:price * :quantity)).as(:taxed)] }.
     map { |i| [i.sku, i.taxed] })
 
 # A duration moves a date.  Each adapter spells the move its own way; SQLite

data/lib/active_record/refined/ast/arithmetics.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Refined
+    module AST
+      # The arithmetic and the bitwise operations on a column or an
+      # expression.  Ruby puts the operators above the comparisons, so
+      # `:price * :quantity > 100` groups the way it reads.  A number may
+      # stand on the left of an expression, `20 - (:a + :b)`, but before a
+      # bare column it is written as a value: `value(20) - :quantity`.
+      #
+      # Bitwise AND and OR are named, not spelled `&` and `|`: those two are
+      # AND and OR between conditions and mean nothing else anywhere.  The
+      # rest keep their operators, with {#bitwise_xor} and {#bitwise_not}
+      # beside `^` and `~` for a reader who would rather have the name.
+      # Oracle, which has no bitwise operators at all, refuses every one.
+      #
+      # @example
+      #   LineItem.where { :price * :quantity > 1000 }
+      #   LineItem.select { :flags.bitwise_and(4).as(:featured) }
+      #
+      # Arithmetic builders shared by symbols, qualified columns and
+      # expressions.  Imported into the Symbol refinement like Predications,
+      # so every method must be defined with def.
+      module Arithmetics
+        # `+`; with an Active Support duration on the right, a date moved: `:due_on + 3.days`.
+        # @return [AST::Arithmetic]
+        def +(other)
+          Arithmetic.new(self, :+, other)
+        end
+
+        # `-`; with a duration on the right, a date moved back.
+        # @return [AST::Arithmetic]
+        def -(other)
+          Arithmetic.new(self, :-, other)
+        end
+
+        # `*`.
+        # @return [AST::Arithmetic]
+        def *(other)
+          Arithmetic.new(self, :*, other)
+        end
+
+        # `/`.
+        # @return [AST::Arithmetic]
+        def /(other)
+          Arithmetic.new(self, :/, other)
+        end
+
+        # `&` is AND, and a column is not a condition, so this refuses:
+        # {#bitwise_and} is the SQL operator, and `.true?` makes a boolean
+        # column a condition.
+        # @raise [ArgumentError]
+        def &(other)
+          AST.refuse_logical(:&, "AND", "bitwise_and", other)
+        end
+
+        # `|` is OR, and refuses here as `&` does.
+        # @raise [ArgumentError]
+        def |(other)
+          AST.refuse_logical(:|, "OR", "bitwise_or", other)
+        end
+
+        # Bitwise AND: `"flags" & 4`.  It is spelled as a name because `&`
+        # is AND, and a method binds tighter than any comparison, so nothing
+        # has to be parenthesised to be compared.
+        # @return [AST::Bitwise]
+        # @example
+        #   Post.where { :flags.bitwise_and(4) > 0 }
+        def bitwise_and(other)
+          Bitwise.new(self, :&, other)
+        end
+
+        # Bitwise OR.
+        # @return [AST::Bitwise]
+        def bitwise_or(other)
+          Bitwise.new(self, :|, other)
+        end
+
+        # Bitwise XOR: `#` on PostgreSQL, `^` on MySQL, and the two operations it is made of on SQLite.
+        # @return [AST::Bitwise]
+        def ^(other)
+          Bitwise.new(self, :^, other)
+        end
+
+        # {#^} under a name.
+        # @return [AST::Bitwise]
+        def bitwise_xor(other)
+          Bitwise.new(self, :^, other)
+        end
+
+        # A shift left.
+        # @return [AST::Bitwise]
+        def <<(other)
+          Bitwise.new(self, :<<, other)
+        end
+
+        # A shift right.
+        # @return [AST::Bitwise]
+        def >>(other)
+          Bitwise.new(self, :>>, other)
+        end
+
+        # Bitwise NOT.
+        # @return [AST::BitwiseNot]
+        def ~
+          BitwiseNot.new(self)
+        end
+
+        # {#~} under a name.  `!` is not the one to reach for: it is Ruby's
+        # own on a column and answers `false`, which no query ever wanted.
+        # @return [AST::BitwiseNot]
+        def bitwise_not
+          BitwiseNot.new(self)
+        end
+      end
+
+      # The named bitwise operations for a number on the left, imported into
+      # the numeric refinements: 4.bitwise_and(:flags).  The operators reach
+      # an expression on the right through {Node#coerce} instead.
+      # @private
+      module NumericArithmetics
+        def bitwise_and(other)
+          Bitwise.new(self, :&, other)
+        end
+
+        def bitwise_or(other)
+          Bitwise.new(self, :|, other)
+        end
+
+        def bitwise_xor(other)
+          Bitwise.new(self, :^, other)
+        end
+      end
+    end
+  end
+end