activerecord-refined 0.3.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f20876b4eb0b36ece84fc2f6a1c828461846b29bd829e279d31b22735cbf0c15
-  data.tar.gz: 4a717ffaf4991fa3a113ea4a6a619b16d431e8308e1869e22c988885022d450a
+  metadata.gz: ba52b9c3529288eeedb0f5ca06a28284669f5a89027d2e372155108f0447ecc1
+  data.tar.gz: bb6d96021512a8891577781aa8e2abb14c2dc7cb8716423270ce0ccd074ed8c9
 SHA512:
-  metadata.gz: 56734a22e7667270892abf1d6ab9fb0816a37043c5f1fe61a7367c40403f782af6dff7875b0f520ada5aef6ce89155f39919414a71d3abec279ccf3c538db578
-  data.tar.gz: f0aa350bbf6b80d1e36b156d2e997930195f2fcfe99c53ae449f3d0f44efe3870671c45bae52a7eac5f39c5f39adf129cbe5a1a1d3776b07eb8d29b1cfa470d2
+  metadata.gz: db9e3ca29892b86f19af39e59e7a52ff987b187df8cb03249ab3456f5bc16ce7d6570b7309f77f28d9600e9aeb21f3c6874b27a63e86d0efeed13bc567f07d9a
+  data.tar.gz: 3d65a461bab4a0c204702be0f532769c6fe7fafaa8106ea4e33994355b3fd3049ed2c5195f53460e9a9749007b5a133c7405ffdcd61485f3d07824e3fa686f9b

data/.github/workflows/sandbox.yml

@@ -0,0 +1,158 @@
+name: sandbox
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: sandbox-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sandbox
+
+    steps:
+      - uses: actions/checkout@v7
+
+      # The host Ruby cannot be 4.1: ruby_wasm's native extension depends on
+      # rb-sys, which does not build against Ruby 4.1's headers.  rbwasm is
+      # only a build tool -- the Ruby it produces is the one that matters.
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: false
+          working-directory: sandbox
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+
+      # The Ruby checkout and the build tree have to be cached together.  make
+      # decides by mtime, so restoring objects next to a freshly cloned Ruby
+      # would rebuild everything.
+      #
+      # The build directory is keyed on the gems that have C extensions, so
+      # Gemfile.lock covers it; RUBY_REV is pinned in bin/build-wasm, and the
+      # staged extension comes from ext/ and the sqlite3 gem.
+      #
+      # restore-keys is what keeps this worth caching -- a key change would
+      # otherwise mean a cold 16-minute build rather than two minutes -- but it
+      # also means a bad tree outlives the key that produced it, since the
+      # prefix still matches.  Editing a file in the key does not clear it;
+      # deleting the cache does.  bin/build-wasm rejects a ruby.wasm built from
+      # such a tree, so it fails the run rather than shipping.
+      - name: Restore the WASM build tree
+        uses: actions/cache@v6
+        with:
+          path: sandbox/build
+          key: wasm-${{ runner.os }}-${{ hashFiles('sandbox/Gemfile.lock', 'sandbox/bin/build-wasm', 'sandbox/ext/**') }}
+          restore-keys: wasm-${{ runner.os }}-
+
+      - run: bundle install --jobs 4
+      - run: npm ci
+
+      - name: Build ruby.wasm
+        run: ./bin/build-wasm
+
+      - name: Assemble the Ruby files served to the page
+        run: ./bin/prepare-rb
+
+      # Runs every example through the same WASI shim the page uses.  The
+      # larger stack is needed to compile ActiveRecord's relation.rb; see the
+      # note in sandbox/README.md.
+      - name: Check the examples
+        run: node --stack-size=4000 check-examples.mjs
+
+      # ruby.wasm is 40 MB, which a Cloudflare Pages asset may not be and which
+      # is nearly all of the bandwidth this page uses, so it is served from R2
+      # -- egress there is free -- and only the page itself from Pages.
+      #
+      # The key carries a hash of the binary, so a rebuild lands on a new URL
+      # and nothing has to be purged.  R2 serves what it is given and does not
+      # compress, hence gzip with the encoding recorded on the object: 40 MB
+      # becomes 12 MB on the wire.
+      #
+      # Without the secrets configured the upload is skipped and ruby.wasm
+      # rides along in the Pages artifact as before, which keeps forks working.
+      # Uploaded over R2's S3-compatible API rather than with wrangler, so that
+      # the token can be an Object Read & Write one scoped to this bucket.
+      # Those permissions exist only on the S3 API: wrangler goes through
+      # Cloudflare's REST API, which answers 403 to them and wants Admin Read &
+      # Write -- a token that can create and delete every bucket in the
+      # account, which is not what a public repository's CI should hold.
+      - name: Upload ruby.wasm to R2
+        id: r2
+        if: github.ref == 'refs/heads/master' && vars.R2_PUBLIC_URL != ''
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+          AWS_DEFAULT_REGION: auto
+          # R2 sends no checksum headers back, which newer AWS CLIs insist on.
+          AWS_REQUEST_CHECKSUM_CALCULATION: when_required
+          AWS_RESPONSE_CHECKSUM_VALIDATION: when_required
+        run: |
+          gzip -9 -c ruby.wasm > /tmp/ruby.wasm.gz
+
+          # One key, overwritten each time, since only the newest build is of
+          # any use.  That rules out caching it as immutable: the URL no longer
+          # changes with the contents, so a long max-age would go on serving
+          # the previous binary.  Five minutes bounds how stale a visitor's
+          # copy can be just after a deploy, and revalidation costs a 304
+          # rather than 12 MB.
+          aws s3api put-object \
+            --endpoint-url "https://${{ secrets.CLOUDFLARE_ACCOUNT_ID }}.r2.cloudflarestorage.com" \
+            --bucket "${{ vars.R2_BUCKET }}" \
+            --key ruby-head.wasm \
+            --body /tmp/ruby.wasm.gz \
+            --content-type application/wasm \
+            --content-encoding gzip \
+            --cache-control "public, max-age=300" \
+            --no-cli-pager
+
+          echo '{"rubyWasmUrl":"${{ vars.R2_PUBLIC_URL }}/ruby-head.wasm"}' > config.json
+          echo "uploaded=true" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sandbox
+          path: |
+            sandbox/index.html
+            sandbox/boot.rb
+            sandbox/examples.js
+            sandbox/manifest.json
+            sandbox/config.json
+            ${{ steps.r2.outputs.uploaded != 'true' && 'sandbox/ruby.wasm' || '' }}
+            sandbox/rb
+            sandbox/vendor/browser.umd.js
+          if-no-files-found: ignore
+          retention-days: 7
+
+  deploy:
+    if: github.ref == 'refs/heads/master'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: sandbox
+          path: site
+
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - id: deploy
+        uses: actions/deploy-pages@v5

data/.github/workflows/test.yml

@@ -7,10 +7,10 @@ on:
   pull_request:
 
 jobs:
-  test:
+  sqlite:
     runs-on: ubuntu-latest
     env:
-      # SQLite only here, so skip building the pg and mysql2 extensions.
+      # Nothing here loads pg or mysql2, so skip building the extensions.
       BUNDLE_WITHOUT: db
     steps:
       - uses: actions/checkout@v5
@@ -21,3 +21,57 @@ jobs:
           ruby-version: head
           bundler-cache: true
       - run: bundle exec rake test
+
+  postgresql:
+    runs-on: ubuntu-latest
+    env:
+      ADAPTER: postgresql
+      DB_USERNAME: postgres
+      DB_PASSWORD: postgres
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: head
+          bundler-cache: true
+      - run: bundle exec rake test
+
+  mysql:
+    runs-on: ubuntu-latest
+    env:
+      ADAPTER: mysql2
+      # The suite creates its own database, which MYSQL_USER would not be
+      # granted; root is the account that can.
+      DB_USERNAME: root
+      DB_PASSWORD: root
+    services:
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: root
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -proot"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: head
+          bundler-cache: true
+      - run: bundle exec rake test

data/LICENSE.txt

@@ -1,4 +1,5 @@
 Copyright (c) 2012 Akira Matsuda
+Copyright (c) 2026 Shugo Maeda
 
 MIT License
 
@@ -19,4 +20,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,5 +1,6 @@
 # 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)
 
 Adding clean and powerful query syntax on ActiveRecord using refinements.
@@ -13,6 +14,10 @@ Author.
 #   WHERE "authors"."age" BETWEEN 20 AND 40 AND "posts"."published" = TRUE
 ```
 
+**[Try it in your browser](https://shugo.github.io/activerecord-refined/)** —
+Ruby 4.1, ActiveRecord and SQLite run in the page, so the examples build real
+SQL and return real rows without a `ruby-master` build of your own.
+
 ## History
 
 This gem was formerly known as **activerecord-refinements**, created by Akira Matsuda
@@ -40,6 +45,10 @@ works again without monkey-patching `Symbol` globally.
 * Ruby 4.1 or later (for `Proc#refined`; not released yet, so a `ruby-master` build is needed for now)
 * ActiveRecord 7.0 or later
 
+The [sandbox](https://shugo.github.io/activerecord-refined/) is there to skip
+that build: it carries its own Ruby 4.1. `sandbox/` in this repository is what
+it is made of.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -87,6 +96,15 @@ 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")
+```
+
 `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:
@@ -100,7 +118,26 @@ Author.where { !exists?(Post.where { :posts[:author_id] == :authors[:id] }) }
 ```
 
 `like?` is case-sensitive `LIKE` on every adapter, including PostgreSQL, where
-Arel would otherwise reach for `ILIKE`.
+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 `%`
@@ -120,17 +157,24 @@ 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:
+`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 { :tags.member?(%w[ruby rails]) } # "tags" @> '{ruby,rails}'
-Article.where { :scores.member?(80) }           # "scores" @> '{80}'
+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.
@@ -155,8 +199,10 @@ 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?`:
+`!=` 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
@@ -186,18 +232,154 @@ Author.
 Author.left_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }
 ```
 
+`as` names the table within the query, which is what makes a self join
+expressible — the qualified columns in the block go by that name:
+
+```ruby
+Employee.joins(:employees, as: :managers) { :managers[:id] == :employees[:manager_id] }
+# SELECT "employees".* FROM "employees"
+#   INNER JOIN "employees" "managers" ON "managers"."id" = "employees"."manager_id"
+```
+
+### Common table expressions
+
+ActiveRecord'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` takes the CTE's name as a symbol, with `as` to select it under the
+model's own table name so the model's columns resolve:
+
+```ruby
+Node.with_recursive(
+  tree: [
+    Node.where { :id == root.id },
+    Node.joins(:tree) { :nodes[:parent_id] == :tree[:id] },
+  ]
+).from(:tree, as: :nodes)
+# WITH RECURSIVE "tree" AS (
+#   SELECT "nodes".* FROM "nodes" WHERE "nodes"."id" = 1
+#   UNION ALL
+#   SELECT "nodes".* FROM "nodes" INNER JOIN "tree" ON "nodes"."parent_id" = "tree"."id"
+# ) SELECT "nodes".* FROM "tree" AS "nodes"
+```
+
+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.
+
 ### Aggregates, functions and aliases
 
-`count`, `sum`, `avg`, `min` and `max` are available as methods, as are the scalar
-functions `upper`, `lower`, `length`, `trim`, `coalesce`, `abs` and `round`. Use `.as`
-for a column alias, and `.asc` / `.desc` for the sort direction. Return an array to
-select or order by multiple expressions.
+`count`, `sum`, `avg`, `min` and `max` are available as methods, as are the
+scalar functions below, with `fn` for anything else. Use `.as` for a column
+alias, and `.asc` / `.desc` for the sort direction. Return an array to select
+or order by multiple expressions.
+
+The scalar functions are real methods rather than anything caught dynamically,
+so a misspelling is a `NoMethodError` where you wrote it, and a name Ruby also
+answers to — `rand` — means the SQL one inside a block:
 
-Pass `:*` to `count` for `COUNT(*)`:
+```
+abs  acos  asin  atan  atan2  cast  ceil  char_length  coalesce  concat
+cos  current_date  current_time  current_timestamp  date_trunc  degrees
+exp  extract  floor  format  greatest  least  length  ln  localtime
+localtimestamp  log  log10  log2  lower  ltrim  mod  now  nullif  pi
+power  radians  rand  replace  round  rtrim  sign  sin  sqrt  substr  tan
+trim  trunc  upper
+```
+
+Most are spelled the same everywhere. Where they are not, the method names one
+meaning and each adapter gets its own spelling: `char_length`, `greatest` and
+`least` become `LENGTH`, `MAX` and `MIN` on SQLite, and `rand` is `RAND` on
+MySQL and `RANDOM` elsewhere, and `trunc` is `TRUNCATE` on MySQL, which
+insists on the second argument the others default to zero — SQLite's takes
+only the one. Where an adapter has no equivalent — `date_trunc` outside
+PostgreSQL, `now` and the `local*` pair on SQLite, `log2` on PostgreSQL,
+whose spelling is `log(2, x)` — the block raises `NotImplementedError`
+rather than leaving the database to reject the SQL.
+
+`current_date`, `current_time`, `current_timestamp`, `localtime` and
+`localtimestamp` come out without parentheses, as the grammar has them —
+written as calls, PostgreSQL and SQLite would reject them. What does go into
+parentheses is an optional precision — `current_timestamp(3)` — which
+`current_date` never takes and SQLite never accepts. `current_timestamp` is
+the portable spelling of what `now` means, and reaches SQLite where `now`
+does not:
+
+```ruby
+Post.where { :published_at <= current_timestamp }
+# SELECT "posts".* FROM "posts" WHERE "posts"."published_at" <= CURRENT_TIMESTAMP
+```
+
+`extract` and `cast` are grammar as well: the field and the type go where no
+value could. The field has to be a plain name, and the type has to look like
+a type — a plain name, at most parenthesized with lengths, so the adapters'
+own spellings like `double precision` or `decimal(10,2)` pass; anything else
+raises `ArgumentError`. The type is the adapter's own name for the type, and
+whether it exists is the database's to say. SQLite spells everything
+`extract` does as `strftime` formats, which no renaming carries, so `extract`
+raises there:
+
+```ruby
+Post.where { extract(:year, :created_at) == 2026 }
+# SELECT "posts".* FROM "posts" WHERE EXTRACT(YEAR FROM "posts"."created_at") = 2026
+
+Post.select { cast(:price, 'decimal(10,2)').as(:price) }
+# SELECT CAST("posts"."price" AS decimal(10,2)) AS price
+```
+
+`format` is printf formatting, and raises on MySQL, where a function of the
+same name does something else entirely: it puts separators in a number, and
+reads a printf template as the number zero rather than complaining. `fn` still
+reaches it, spelled as the different thing it is:
+
+```ruby
+Post.select { fn(:format, :amount, 2) }   # MySQL's, on purpose
+```
+
+Pass `:*` to `count` for `COUNT(*)`, and `distinct: true` for
+`COUNT(DISTINCT ...)`:
 
 ```ruby
 Author.group { :country }.having { count(:*) > 1 }
 # SELECT "authors".* FROM "authors" GROUP BY "authors"."country" HAVING COUNT(*) > 1
+
+Post.select { count(:author_id, distinct: true) }   # COUNT(DISTINCT "author_id")
+```
+
+Values are quoted by the adapter wherever they appear, as they are in
+ActiveRecord. Column aliases and `fn`'s function name are not — they are
+written into the SQL as given — so those two have to be plain names,
+optionally qualified by a schema in `fn`'s case. Anything else raises
+`ArgumentError` rather than reaching the query.
+
+`fn` reaches functions without a method of their own. Its name is emitted as
+written, so a case-sensitive one can be spelled exactly:
+
+```ruby
+Post.select { fn(:date_trunc, 'day', :created_at).as(:day) }
+# SELECT date_trunc('day', "posts"."created_at") AS day
+```
+
+`+`, `-`, `*` 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) }
+```
+
+`.asc` and `.desc` take `.nulls_first` / `.nulls_last`. MySQL has no such
+syntax, but Arel emulates it there, so the resulting order is the same
+everywhere:
+
+```ruby
+Author.order { :country.asc.nulls_last }
 ```
 
 ```ruby
@@ -216,7 +398,68 @@ Author.
   }
 ```
 
-See `examples/` for complete, runnable scripts.
+## Examples
+
+`examples/` holds runnable scripts, each printing the SQL it builds and, where
+the result is the point, the rows that come back. All but the last run against
+an in-memory SQLite database and need no setup.
+
+| | |
+| --- | --- |
+| `predicates.rb` | the `where` vocabulary: ranges, sets, NULL, text matching |
+| `subqueries.rb` | `in?` with a relation, `exists?`, scalar subqueries |
+| `expressions.rb` | arithmetic, aggregates, functions, `NULLS LAST` |
+| `complex_joins.rb` | compound `ON` clauses, outer joins, a self join |
+| `aggregations.rb` | `GROUP BY`, `HAVING` and aggregates across joins |
+| `ctes.rb` | `with` and `with_recursive` |
+| `postgresql.rb` | array columns, regular expressions, `ILIKE` (needs a server) |
+
+## Performance
+
+`benchmark/query_building.rb` compares building the same queries through the
+block DSL and through ActiveRecord'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, ActiveRecord 8.1.3, 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 |
+
+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 |
+
+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
+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.
+
+One memory cost sits outside the per-query numbers above: to run a block
+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
+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
+once, as normal code is — building query blocks with a string `eval` mints
+a fresh instruction sequence per pass, each earning a copy of its own, and
+the memo keeps both alive for the life of the process.
 
 ## Running the tests
 
@@ -237,12 +480,15 @@ 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:
+which is what CI's SQLite job does:
 
 ```sh
 bundle config set --local without db
 ```
 
+CI runs all three, one job per adapter, with PostgreSQL and MySQL as service
+containers.
+
 ## Releasing
 
 Pushing a `v*` tag runs `.github/workflows/push_gem.yml`, which builds the gem

data/activerecord-refined.gemspec

@@ -12,7 +12,9 @@ Gem::Specification.new do |gem|
   gem.summary       = 'ActiveRecord + Ruby 4.1 Proc#refined'
   gem.homepage      = 'https://github.com/shugo/activerecord-refined'
 
-  gem.files         = `git ls-files`.split($/)
+  # sandbox/ is a site, not part of the library: its Gemfile.lock and
+  # package-lock.json have no business in anyone's bundle.
+  gem.files         = `git ls-files`.split($/).grep_v(%r{^sandbox/})
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]