activerecord-refined 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: affe44abbced76ea15b8c057f44292e5aefb0c8be7bc0012805278b08be7881c
-  data.tar.gz: 54b11073068080d169b005a4f2fdee825a8b03e0910459c5fef5555e24430edd
+  metadata.gz: 9dec7847f9abff657ab248a17613b08464164fcef0780db94ab5f97de8727dd5
+  data.tar.gz: a544f3202bd459206ad8e94827b18f09f66d8da912c9ba1f130d75b5d1646e02
 SHA512:
-  metadata.gz: 13103ed15da63fadedf60ec4f5f91ee0ba4c22440250aa9c7f48c9df2ccb0b72194225592ddf1dbca449d898fb33f5051fa30f906add9e533917c271b3b6283f
-  data.tar.gz: 97c9c10eeb67c3dbbbdd7e896e13eb4c49be50dd2312d92ee4289ab8a9c96d5159c06ea940f19a9871f33e877f71de8eb96c7d2d43399eb9097fd19505d4d35f
+  metadata.gz: 821537f17ddd8cba223cb45b4e9b6f1bd1bc19cccb4c615686f0f16959cc615c8b3d10225b1a9e632dff291abb87291827bed1b62857648378f46b7d2e947463
+  data.tar.gz: ee7269d0bb16a09a7ec938557303e00133e96723c9341e8bbf58d890c2fd5dbffc6fa016a88bfd8383f78a32448a4522c982cefd68dde0e478e64de10c9b751a

data/.github/workflows/sandbox.yml

@@ -128,7 +128,7 @@ jobs:
         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
+      # larger stack is needed to compile Active Record's relation.rb; see the
       # note in sandbox/README.md.
       - name: Check the examples
         run: node --stack-size=4000 check-examples.mjs

data/README.md

@@ -3,7 +3,7 @@
 [![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.
+Adding clean and powerful query syntax on Active Record using refinements.
 
 ```ruby
 Author.
@@ -15,7 +15,7 @@ Author.
 ```
 
 **[Try it in your browser](https://shugo.github.io/activerecord-refined/)** —
-Ruby 4.1, ActiveRecord, SQLite and PostgreSQL run in the page, so the examples
+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.
 
 ## History
@@ -43,7 +43,7 @@ works again without monkey-patching `Symbol` globally.
 ## Requirements
 
 * 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
+* Active Record 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
@@ -123,7 +123,7 @@ answers false there. `not_true?` is therefore "false or never set" and
 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 ActiveRecord's own
+subquery selects the relation's primary key, the same way Active Record's own
 `where(id: relation)` does:
 
 ```ruby
@@ -245,7 +245,7 @@ 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:
+way Active Record's own `where(period: from...to)` does for those column types:
 
 ```ruby
 Reservation.where { :period == (from...to) }   # daterange = '[from,to)'
@@ -294,6 +294,27 @@ Employee.joins(:employees, as: :managers) { :managers[:id] == :employees[:manage
 #   INNER JOIN "employees" "managers" ON "managers"."id" = "employees"."manager_id"
 ```
 
+`right_outer_joins` and `full_outer_joins` are the two Active Record has no
+method for, and they take what `joins` takes. An association name is not among
+it: what Active Record reads out of one is an inner or a left join and nothing
+else, so these two want the block that says how to join.
+
+```ruby
+Author.right_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }
+Author.full_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }
+```
+
+MySQL has no `FULL OUTER JOIN` and neither has MariaDB, so `full_outer_joins`
+raises `NotImplementedError` there. SQLite has had one since 3.39.
+
+`cross_joins` is every row of one table against every row of the other. There
+is no condition to give, so it takes no block — `as` still names the table:
+
+```ruby
+Post.cross_joins(:authors)              # FROM "posts" CROSS JOIN "authors"
+Post.cross_joins(:posts, as: :others)   # FROM "posts" CROSS JOIN "posts" "others"
+```
+
 ### Keeping one row per group
 
 `distinct_on` is PostgreSQL's `DISTINCT ON`: the first row of each group the
@@ -318,7 +339,7 @@ Post.from(ranked, :posts).where { :rn == 1 }
 ```
 
 The subquery is named after the model's own table for the reason `from_cte`
-is: ActiveRecord goes on qualifying columns with that name, so `where` needs
+is: Active Record goes on qualifying columns with that name, so `where` needs
 to find it.
 
 ### Grouping several ways at once
@@ -345,16 +366,17 @@ the block raises `NotImplementedError` on both.
 
 ### Lateral joins
 
-`lateral: true` joins a relation rather than a table, and lets it see the row
-being joined to. That is what makes the top row of each group reachable in one
-query:
+A relation marked `lateral` joins in place of a table, and sees the row being
+joined to — in SQL the keyword modifies the subquery, not the join, so that is
+where it is written. It is what makes the top row of each group reachable in
+one query:
 
 ```ruby
 top_post = Post.select { :title }.
   where { :posts[:author_id] == :authors[:id] }.
   order { :likes.desc }.limit(1)
 
-Author.left_outer_joins(top_post, as: :top, lateral: true).
+Author.left_outer_joins(top_post.lateral, as: :top).
   select { [:name, :top[:title].as(:top_post)] }
 # SELECT "name", "top"."title" AS "top_post" FROM "authors"
 #   LEFT OUTER JOIN LATERAL (SELECT "title" FROM "posts"
@@ -372,7 +394,7 @@ writes it, so the SQL is written here instead.
 
 ### Common table expressions
 
-ActiveRecord's `with` and `with_recursive` need nothing from this gem: a CTE
+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.
 
@@ -403,8 +425,8 @@ the shape of a tree comes out of a flat table. The `0` is a value rather than
 SQL — see [`value`](#aggregates-functions-and-aliases) below for why a number
 can say `.as` directly.
 
-The alias on the last line is there for ActiveRecord's sake, not SQL's:
-written by hand that line would be `SELECT * FROM tree`. ActiveRecord goes on qualifying
+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:
 
@@ -511,7 +533,7 @@ Post.select { fn(:date_trunc, 'day', :created_at).as(:day) }
 ```
 
 Values are quoted by the adapter wherever they appear, as they are in
-ActiveRecord, and so is a column alias. That is what makes the name asked for
+Active Record, and so is a column alias. That is what makes the name asked for
 the name that comes back: unquoted, PostgreSQL folds a capital away where the
 other two keep it, so one block would mean two things. It also leaves nothing
 to refuse — a name that would have been SQL becomes an identifier with a
@@ -626,7 +648,7 @@ 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 ActiveRecord reads a string in `select` as SQL,
+`concat(:name, '-x')` — but Active Record reads a string in `select` as SQL,
 so `value` is how you ask for the other meaning. It carries the predications
 and arithmetic with it, so a literal can be compared and combined like
 anything else. Numbers have a shorthand, since nothing else could be meant by
@@ -717,6 +739,16 @@ Post.where { cast(:meta.dig(:n), 'integer') > 6 }   # 'signed' on MySQL
 
 The type is the adapter's own name for it, here as everywhere `cast` is used.
 
+Comparing a dug value with anything but a string raises `ArgumentError` rather
+than being left to the adapters, which answer it three ways: `dig(:n) == 5` is
+true on SQLite, an error on PostgreSQL and true on MySQL, and
+`dig(:flag) == true` is true, an error and false. `cast` is what says which
+type was meant, and then all three agree. `dig_json` is refused the other way
+about — the JSON for a string carries its quotes, so `dig_json(:name) ==
+'alice'` is false, an error and true — and `dig` is the one that gives the
+value. A column, a function or another dug value on the right goes through
+untouched; only a Ruby literal is refused.
+
 `bury` sets what `dig` reads: the last argument is the value and the rest are
 the path to it. The document comes back changed rather than being written
 anywhere, so `update_all` is what makes it stick:
@@ -736,8 +768,47 @@ Ruby method; it is the name Ruby considered for the other end of `dig`, and
 SQL has no one name to borrow here, since PostgreSQL says `jsonb_set` where
 the others say `JSON_SET`.
 
+`except` takes keys out again, and takes them as `Hash#except` does — keys of
+the document, however many, rather than a path, which is `bury`'s way of
+reaching further in. It gives back the document changed, so it chains with
+`bury` and goes where `bury` goes:
+
+```ruby
+Post.update_all { { meta: :meta.except(:draft) } }
+# SET "meta" = "meta" - CAST('{"draft"}' AS text[])
+# ...          JSON_REMOVE("meta", '$.draft')   elsewhere
+
+Post.update_all { { meta: :meta.bury(:author, :name, 'alice').except(:tmp) } }
+```
+
+A key that is not there is not an error, as it is not to `Hash#except`. The
+cast is not decoration: `jsonb` has three subtractions — a key, an array of
+keys, an element by index — and an array literal written without a type is
+read as the first of them, so `"meta" - '{draft}'` takes out the key spelled
+`{draft}`, which is nothing, and says nothing about it.
+
 `dig_json` keeps the JSON, for a document to be dug into further or compared
-whole. `contains?` has no equivalent on SQLite and raises `NotImplementedError`
+whole — so the JSON operations read what it gives, which is the same question
+asked of a part of the document rather than of all of it:
+
+```ruby
+Post.where { :meta.dig_json(:author).key?(:email) }
+Post.where { :meta.dig_json(:author).dig(:name) == 'alice' }
+Post.update_all { { meta: :meta.dig_json(:author).bury(:name, 'alice') } }
+```
+
+Containment reads it too, on the adapters that have containment at all:
+
+```ruby
+Post.where { :meta.dig_json(:tags).contains?(['ruby']) }
+```
+
+Asking the same of `dig` raises `ArgumentError`: what it gives is text, and
+reading text back as a document is where the adapters part company — SQLite
+parses it, MySQL takes it as written, and PostgreSQL has no such function for
+text at all.
+
+`contains?` has no equivalent on SQLite and raises `NotImplementedError`
 there — later than the rest, since the adapter is only known when the SQL is
 built. On PostgreSQL, `contains?` and `key?` want a `jsonb` column; the
 `json` type carries neither operator.
@@ -783,7 +854,7 @@ Post.select { sum(:likes).over.order(:created_at).rows(0..).as(:remaining) }
 ```
 
 `range` says `RANGE` where `rows` says `ROWS`, and a window has one frame or
-none. Named windows — `WINDOW w AS (...)` — have no clause in ActiveRecord to
+none. Named windows — `WINDOW w AS (...)` — have no clause in Active Record to
 live in, so they are not here.
 
 ### Aliases and ordering
@@ -817,7 +888,7 @@ Author.
 
 ### Writing
 
-`update_all` reads its hash the way ActiveRecord does — `update_all(likes: :likes)`
+`update_all` reads its hash the way Active Record does — `update_all(likes: :likes)`
 sets the column to the symbol itself. The block reads a symbol as the column it
 names, as every other block here does, which is what lets the new value be
 worked out from the old:
@@ -839,23 +910,23 @@ Tally.upsert_all(rows, unique_by: :page) { { hits: :hits + excluded(:hits) } }
 
 PostgreSQL and SQLite name that row `excluded`; MySQL spells the same thing
 `VALUES(column)`, and the block comes out as whichever the adapter reads.
-ActiveRecord's own `on_duplicate:` takes SQL text and nothing else, so this is
+Active Record's own `on_duplicate:` takes SQL text and nothing else, so this is
 the one place the DSL writes SQL out itself rather than handing Arel a tree —
 and the two cannot both be given.
 
 `insert_all` has no block: its values are literals by construction.
-ActiveRecord type-casts each one on the way into the `VALUES` list, so an
+Active Record type-casts each one on the way into the `VALUES` list, so an
 expression does not become SQL there — it becomes nothing, silently. Use
 `upsert_all` where a row's value has to be worked out.
 
 ## Performance
 
 `benchmark/query_building.rb` compares building the same queries through the
-block DSL and through ActiveRecord's other argument styles. Only query
+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, ActiveRecord 8.1.3, one machine —
+Queries built per second (ruby 4.1.0dev, Active Record 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 |
@@ -930,7 +1001,7 @@ 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.
+bundle exec bump patch --tag # or bump {major,minor} etc.
 git push --follow-tags
 ```
 

data/activerecord-refined.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |gem|
   gem.version       = Activerecord::Refined::VERSION
   gem.authors       = ["Shugo Maeda"]
   gem.email         = ["shugo@ruby-lang.org"]
-  gem.description   = 'Adding clean and powerful query syntax on AR using refinements'
-  gem.summary       = 'ActiveRecord + Ruby 4.1 Proc#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'
 
   # sandbox/ is a site, not part of the library: its Gemfile.lock and
@@ -28,4 +28,6 @@ Gem::Specification.new do |gem|
   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']
 end

data/benchmark/query_building.rb

@@ -1,5 +1,5 @@
 # Compares the cost of building the same queries through this gem's block
-# DSL and through ActiveRecord's other argument styles: hash conditions,
+# DSL and through Active Record's other argument styles: hash conditions,
 # string conditions, raw Arel, and relation and/or chains.  Only query
 # construction (through to_sql) is measured; every style produces the same
 # SQL, which the script prints first as a sanity check.

data/examples/complex_joins.rb

@@ -80,3 +80,33 @@ query4 =
 puts "--- 4. Self join through an alias ---"
 puts query4.to_sql
 puts
+
+# 5. The joins Active Record has no method for.  RIGHT OUTER keeps the rows of
+#    the table joined rather than the one selected from; FULL OUTER keeps
+#    both, which MySQL has no spelling for and this gem refuses there.
+query5 =
+  Author.
+    right_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }.
+    select { [:authors[:name].as(:author), :posts[:title].as(:post)] }
+
+puts "--- 5. RIGHT OUTER JOIN ---"
+puts query5.to_sql
+puts
+
+# An association is what joins and left_outer_joins read out; these two want
+# the block that says how to join.
+begin
+  Author.right_outer_joins(:posts)
+rescue ArgumentError => e
+  puts '--- and it says so without one ---'
+  puts "  #{e.message}"
+  puts
+end
+
+# 6. CROSS JOIN: every row against every row, so there is no condition to
+#    give and no block to write it in.  `as` still names the table.
+puts '--- 6. CROSS JOIN ---'
+puts Author.cross_joins(:posts).to_sql
+puts Author.cross_joins(:authors, as: :others).
+  select { [:authors[:name].as(:a), :others[:name].as(:b)] }.to_sql
+puts

data/examples/ctes.rb

@@ -34,8 +34,8 @@ Product.create!(name: 'apple', category_id: groceries.id, price: 2)
 #    rather than the string join Rails' own documentation reaches for.
 #    `from_cte` then selects the CTE under the model's table name.
 #
-#    That alias is ActiveRecord's requirement rather than SQL's: by hand the
-#    last line would be `SELECT * FROM tree`.  ActiveRecord keeps qualifying
+#    That alias is Active Record's requirement rather than SQL's: by hand the
+#    last line would be `SELECT * FROM tree`.  Active Record keeps qualifying
 #    columns with the model's table name, so without it `where` and `find_by`
 #    look for a table the query does not have.  `count`, `order` and `select`
 #    never qualify and would work either way, which makes it easy to miss.

data/examples/json.rb

@@ -48,8 +48,24 @@ show('dig in a condition',
   Document.where { :meta.dig(:author, :country) == 'JP' },
   Document.where { :meta.dig(:author, :country) == 'JP' }.pluck(:name))
 
+# A dug value is text, so a number goes through a cast.  Comparing it with
+# one instead is refused rather than left to the adapters, which answer that
+# three ways: true here, an error on PostgreSQL, true on MySQL.
+show('a number wants a cast',
+  Document.where { cast(:meta.dig(:views), 'integer') > 100 },
+  Document.where { cast(:meta.dig(:views), 'integer') > 100 }.pluck(:name))
+
+begin
+  Document.where { :meta.dig(:views) > 100 }
+rescue ArgumentError => e
+  puts '--- and without one it says so ---'
+  puts "  #{e.message}"
+  puts
+end
+
 # dig_json keeps the JSON, for a part of the document to be dug into further
-# or compared whole.  The quotes around the string are the sign of it.
+# or compared whole.  The quotes around the string are the sign of it -- and
+# the reason a Ruby value is refused on this side too.
 show('dig_json keeps the JSON',
   Document.select { [:name, :meta.dig_json(:author).as(:author)] },
   Document.select { [:name, :meta.dig_json(:author).as(:author)] }.
@@ -92,3 +108,15 @@ rescue ArgumentError => e
   puts "  #{e.message}"
   puts
 end
+
+# 4. Taking keys out again, as Hash#except does: keys of the document rather
+#    than a path, however many of them, and a key that is not there is no
+#    error.  The document comes back changed, so it chains with bury.
+show('the expression except builds',
+  Document.select { [:name, :meta.except(:views, :draft).as(:trimmed)] })
+
+Document.where { :name == 'guide' }.
+  update_all { {meta: :meta.bury(:author, :country, 'JP').except(:tags, :views)} }
+puts '--- buried and excepted in one statement ---'
+puts "  #{Document.find_by(name: 'guide').meta.inspect}"
+puts

data/examples/postgresql.rb

@@ -153,7 +153,7 @@ show('rollup is the nested case of the same thing',
 top = Article.select { :title }.
   where { :articles[:writer_id] == :writers[:id] }.
   order { :likes.desc }.limit(1)
-lateral = Writer.left_outer_joins(top, as: :top, lateral: true).
+lateral = Writer.left_outer_joins(top.lateral, as: :top).
   select { [:name, :top[:title].as(:top_article)] }
 show('the top article beside each writer',
   lateral,

data/examples/subqueries.rb

@@ -41,7 +41,7 @@ end
 
 # 1. in? takes a relation as a subquery.  With an explicit select list the
 #    subquery selects that column; without one it selects the primary key,
-#    the same way ActiveRecord's own where(id: relation) does.
+#    the same way Active Record's own where(id: relation) does.
 show('in? with a subquery',
   Author.where { :id.in?(Post.published.select(:author_id)) })
 

data/examples/windows.rb

@@ -88,7 +88,7 @@ end
 numbered = Sale.select {
   [:region, :day, :amount, row_number.over.partition(:region).order(:amount.desc).as(:place)]
 }
-# The subquery is named after the model's own table because ActiveRecord goes
+# The subquery is named after the model's own table because Active Record goes
 # on qualifying columns with that name, so where has to find it there.
 show('the biggest sale of each region',
   Sale.from(numbered, :sales).where { :place == 1 },

data/examples/writes.rb

@@ -27,7 +27,7 @@ Page.create!(path: '/about', hits: 3,  bonus: 0, title: 'about us')
 Page.create!(path: '/faq',   hits: 0,  bonus: 5, title: 'faq')
 
 # These statements run rather than being built, so unlike the other examples
-# the SQL is taken from the notification ActiveRecord sends for each one.
+# the SQL is taken from the notification Active Record sends for each one.
 def write(title)
   statements = []
   subscriber = ActiveSupport::Notifications.subscribe('sql.active_record') do |*, payload|
@@ -41,7 +41,7 @@ def write(title)
   puts
 end
 
-# 1. update_all.  ActiveRecord reads its hash as literals -- update_all(hits:
+# 1. update_all.  Active Record reads its hash as literals -- update_all(hits:
 #    :hits) would set the column to the symbol itself -- and the block reads a
 #    symbol as the column it names, which is what lets the new value be worked
 #    out from the old.
@@ -70,14 +70,14 @@ write('the old value and the new one added together') do
   Page.upsert_all(incoming, unique_by: :path) { {hits: :hits + excluded(:hits)} }
 end
 
-# Without a block, upsert_all overwrites -- that is ActiveRecord's own
+# Without a block, upsert_all overwrites -- that is Active Record's own
 # behaviour, and the block is what makes the old value reachable.
 write('and without a block it is a plain overwrite') do
   Page.upsert_all([{path: '/index', hits: 1, bonus: 0, title: 'HOME'}],
                   unique_by: :path)
 end
 
-# insert_all has no block: ActiveRecord type-casts each value into the VALUES
+# insert_all has no block: Active Record type-casts each value into the VALUES
 # list, so an expression there would become nothing rather than SQL.
 write('insert_all takes literals') do
   Page.insert_all([{path: '/legal', hits: 0, bonus: 0, title: 'legal'}])

data/lib/active_record/refined/ast.rb

@@ -228,6 +228,13 @@ module ActiveRecord
           JsonPath.new(self, path, as_json: true)
         end
 
+        # Keys taken out of a JSON document, by the name of what Hash does,
+        # and taking keys as Hash#except takes them.  Like bury it gives back
+        # the document changed rather than writing it anywhere.
+        def except(*keys)
+          JsonExcept.new(self, keys)
+        end
+
         # What dig reads, bury sets: the last argument is the value and the
         # rest are the path to it.  The document comes back changed rather
         # than being written anywhere, which update_all is for.
@@ -359,7 +366,7 @@ module ActiveRecord
       # A literal standing where an expression would: `select { value(0).as(:depth) }`.
       #
       # Values reach the SQL quoted wherever they appear as an operand, but the
-      # top of a select list is ActiveRecord's, and a bare string there is SQL
+      # top of a select list is Active Record's, and a bare string there is SQL
       # rather than a string.  Saying `value` is how you ask for the other
       # meaning, and it carries the predications with it, so a literal can be
       # compared and combined like anything else.
@@ -441,7 +448,7 @@ module ActiveRecord
         end
 
         # What a `when` is until its `then` arrives.  A Node so that using it
-        # as one says what is missing rather than reaching ActiveRecord as
+        # as one says what is missing rather than reaching Active Record as
         # something it cannot read.
         class Pending < Node
           def initialize(kase, condition)
@@ -474,20 +481,23 @@ module ActiveRecord
         end
 
         # PostgreSQL takes the steps as a text array, where every element is
-        # quoted so that a comma or a brace in a key is part of it.
-        def steps_array
-          "{#{path.map {|step| %("#{escape_step(step)}") }.join(',')}}"
+        # quoted so that a comma or a brace in a key is part of it.  except
+        # writes its keys the same way, which are steps of no one path.
+        def steps_array(steps = path)
+          "{#{steps.map {|step| %("#{escape_step(step)}") }.join(',')}}"
         end
 
         # MySQL and SQLite take a path expression instead, where an integer is
         # a subscript and a name that is not plain has to be quoted.
         def dollar_path
-          path.inject(+'$') do |so_far, step|
-            next so_far << "[#{step}]" if step.is_a?(::Integer)
-            name = step.to_s
-            so_far << '.' << (name.match?(/\A[[:alpha:]_][[:alnum:]_]*\z/) ?
-                              name : %("#{escape_step(step)}"))
-          end
+          path.inject(+'$') {|so_far, step| so_far << dollar_step(step) }
+        end
+
+        def dollar_step(step)
+          return "[#{step}]" if step.is_a?(::Integer)
+          name = step.to_s
+          '.' + (name.match?(/\A[[:alpha:]_][[:alnum:]_]*\z/) ?
+                 name : %("#{escape_step(step)}"))
         end
 
         def escape_step(step)
@@ -503,10 +513,85 @@ module ActiveRecord
       #
       # The path is turned into a string either way, so a key with a space or
       # a quote in it travels as itself rather than having to be refused.
+      # What a dug value may be compared with.  dig gives text on every
+      # adapter, and what a text value compared with a number means is a
+      # question the three answer three ways: `dig(:n) == 5` is true on
+      # SQLite, an error on PostgreSQL and true on MySQL, while
+      # `dig(:flag) == true` is true, an error, and false.  cast is what says
+      # which type was meant, and then all three agree.
+      #
+      # dig_json is refused the other way about: the JSON for a string carries
+      # its quotes, so `dig_json(:name) == 'alice'` is false on SQLite, an
+      # error on PostgreSQL and true on MySQL.  dig is the one that gives the
+      # value.
+      #
+      # A string against dig, and anything the block itself built -- a column,
+      # a function, another dug value -- go through untouched.
+      module JsonComparable
+        %i[== != < <= > >=].each do |operator|
+          define_method(operator) do |other|
+            check_comparable(other)
+            super(other)
+          end
+        end
+
+        def in?(values) = super(check_each(values))
+        def not_in?(values) = super(check_each(values))
+        def between?(min, max) = super(*check_each([min, max]))
+        def not_between?(min, max) = super(*check_each([min, max]))
+
+        private
+
+        # nil is left to the comparison itself, which says to use null?, and
+        # so is anything the block built rather than wrote as a literal.
+        def check_comparable(other)
+          return if other.nil? || other.is_a?(Node) || other.is_a?(::Symbol) ||
+                    other.is_a?(Arel::Nodes::Node) ||
+                    other.is_a?(Arel::Attributes::Attribute) ||
+                    other.is_a?(ActiveRecord::Relation)
+          return if other.is_a?(::String) && !as_json
+
+          raise ArgumentError, as_json ?
+            "dig_json gives JSON, and comparing it with #{other.inspect} " \
+            "means something different on every adapter; dig gives the value" :
+            "dig gives text, and comparing it with #{other.inspect} means " \
+            "something different on every adapter; cast it to the type meant"
+        end
+
+        def check_each(values)
+          case values
+          when ActiveRecord::Relation then values
+          when ::Range then [values.begin, values.end].each {|v| check_comparable(v) }
+          else values.each {|value| check_comparable(value) }
+          end
+          values
+        end
+      end
+
+      # The JSON operations read a document, and what dig_json gives is one:
+      # `dig_json(:author).key?(:email)` and `dig_json(:tags).contains?(...)`
+      # are the same question asked of a part of it, and the adapters answer
+      # them alike.  What dig gives is text, and reading that as a document
+      # again is where they part company: SQLite parses it back and MySQL
+      # takes it as written, where PostgreSQL has no such function for text.
+      module JsonDocument
+        %i[dig dig_json key? contains? bury except].each do |name|
+          define_method(name) do |*args|
+            unless as_json
+              raise ArgumentError,
+                "dig gives text, and #{name} reads JSON; dig_json keeps it"
+            end
+            super(*args)
+          end
+        end
+      end
+
       class JsonPath < Node
         include Predications
         include Arithmetics
         include JsonSteps
+        include JsonComparable
+        include JsonDocument
 
         attr_reader :operand, :path, :as_json
 
@@ -595,6 +680,55 @@ module ActiveRecord
         end
       end
 
+      # Keys taken out of a JSON document.  PostgreSQL subtracts them, the
+      # other two remove a path apiece.
+      class JsonExcept < Node
+        include Predications
+        include JsonSteps
+
+        attr_reader :operand, :keys
+
+        def initialize(operand, keys)
+          @operand = operand
+          @keys = check_keys(keys)
+        end
+
+        def to_arel(table, model)
+          document = to_arel_operand(operand, table, model)
+          return Arel::Nodes::InfixOperation.new(:-, document, key_array) if
+            AST.adapter_family(model) == :postgresql
+
+          Arel::Nodes::NamedFunction.new(
+            'JSON_REMOVE',
+            [document, *keys.map {|key| Arel::Nodes.build_quoted("$#{dollar_step(key)}") }])
+        end
+
+        private
+
+        # jsonb has three subtractions -- a key, an array of keys, an element
+        # by index -- and an array literal written without a type is read as
+        # the first of them: `meta - '{draft}'` takes out the key spelled
+        # {draft}, which is nothing, and says nothing about it.
+        def key_array
+          Arel::Nodes::NamedFunction.new(
+            'CAST',
+            [Arel::Nodes::As.new(Arel::Nodes.build_quoted(steps_array(keys)),
+                                 Arel::Nodes::SqlLiteral.new('text[]'))])
+        end
+
+        # Keys, as Hash#except takes them: an index into an array is not what
+        # the name says anywhere, and is bury's business through a path.
+        def check_keys(keys)
+          raise ArgumentError, 'except needs a key' if keys.empty?
+          keys.each do |key|
+            next if key.is_a?(::String) || key.is_a?(::Symbol)
+            raise ArgumentError,
+              "except takes keys of the document, not #{key.inspect}"
+          end
+          keys
+        end
+      end
+
       # JSON containment: whether the document holds what is given.
       class JsonContains < Predicate
         attr_reader :operand, :value
@@ -1128,7 +1262,7 @@ module ActiveRecord
 
       # A plain SQL comparison. The value is passed through as it is, so a Range
       # or an Array compares against a PostgreSQL range or array column, the way
-      # ActiveRecord's own force_equality? types do.
+      # Active Record's own force_equality? types do.
       class Comparison < Predicate
         OPERATOR_MAP = {
           :== => :eq, :!= => :not_eq,
@@ -1187,7 +1321,7 @@ module ActiveRecord
       end
 
       # A relation standing for a set of values, which is what IN and the
-      # quantifiers each take.  The treatment is ActiveRecord's own
+      # quantifiers each take.  The treatment is Active Record's own
       # RelationHandler's: without an explicit select list the subquery
       # selects the model's primary key.
       module SetSubquery

data/lib/active_record/refined.rb

@@ -251,7 +251,7 @@ module ActiveRecord
       #
       #   select { [:id, value(0).as(:depth)] }
       #
-      # Needed because the top of a select list is ActiveRecord's, and a bare
+      # Needed because the top of a select list is Active Record's, and a bare
       # string there is SQL rather than a string.  Numbers have a shorthand --
       # `0.as(:depth)` -- since nothing else could be meant by one.
       def value(literal)
@@ -367,7 +367,7 @@ module ActiveRecord
         end
       end
 
-      # A symbol names a table, which ActiveRecord's own from only takes as a
+      # A symbol names a table, which Active Record's own from only takes as a
       # string.  With `as` it is selected under another name; when that name
       # is the model's own, from_cte says the same thing without repeating it.
       def from(value, subquery_name = nil, as: nil)
@@ -383,7 +383,7 @@ module ActiveRecord
       end
 
       # Selects a CTE in place of the model's own table.  The alias is not a
-      # choice -- ActiveRecord keeps qualifying columns with the table name,
+      # choice -- Active Record keeps qualifying columns with the table name,
       # so the model's is the only name that works -- which is why it is
       # taken from the model rather than asked for:
       # with_recursive(tree: [...]).from_cte(:tree)
@@ -432,7 +432,7 @@ module ActiveRecord
         self
       end
 
-      # ActiveRecord generates these for the values it knows about; this one
+      # Active Record generates these for the values it knows about; this one
       # is ours, and lives in the same place so that it survives a spawn.
       def distinct_on_values
         @values.fetch(:distinct_on, ActiveRecord::QueryMethods::FROZEN_EMPTY_ARRAY)
@@ -443,13 +443,32 @@ module ActiveRecord
         @values[:distinct_on] = columns
       end
 
+      # Marks the relation for a lateral join, which lets it see the row being
+      # joined to -- the top few rows of each group, and the like.  In SQL the
+      # keyword modifies the subquery, not the join, so it is said on the
+      # relation: left_outer_joins(top_post.lateral, as: :top).
+      def lateral
+        spawn.lateral!
+      end
+
+      def lateral!
+        self.lateral_value = true
+        self
+      end
+
+      def lateral_value
+        @values[:lateral]
+      end
+
+      def lateral_value=(value)
+        assert_modifiable!
+        @values[:lateral] = value
+      end
+
       # `as` names the table within the query, which is what makes a self
       # join expressible: joins(:employees, as: :managers) { ... }.
-      #
-      # `lateral` joins a relation instead of a table, and lets it see the row
-      # being joined to -- the top few rows of each group, and the like.
-      def joins(*args, as: nil, lateral: false, &block)
-        if lateral
+      def joins(*args, as: nil, &block)
+        if args.first.is_a?(ActiveRecord::Relation)
           super(build_lateral_join(args.first, Arel::Nodes::InnerJoin, as, &block))
         elsif block
           super(build_join_node(args.first, Arel::Nodes::InnerJoin, as, &block))
@@ -459,8 +478,8 @@ module ActiveRecord
         end
       end
 
-      def left_outer_joins(*args, as: nil, lateral: false, &block)
-        if lateral
+      def left_outer_joins(*args, as: nil, &block)
+        if args.first.is_a?(ActiveRecord::Relation)
           joins(build_lateral_join(args.first, Arel::Nodes::OuterJoin, as, &block))
         elsif block
           joins(build_join_node(args.first, Arel::Nodes::OuterJoin, as, &block))
@@ -470,6 +489,36 @@ module ActiveRecord
         end
       end
 
+      # The other two outer joins, which Active Record has no method for and
+      # Arel has the nodes for.  The rules are joins': the block is the ON,
+      # `as` names the table within the query, a relation marked `lateral`
+      # joins as one.  An association name is not among them -- what Active
+      # Record reads out of one is an inner or a left join and nothing else.
+      def right_outer_joins(*args, as: nil, &block)
+        outer_joins(:right_outer_joins, Arel::Nodes::RightOuterJoin,
+                    args, as, &block)
+      end
+
+      def full_outer_joins(*args, as: nil, &block)
+        check_full_outer_support
+        outer_joins(:full_outer_joins, Arel::Nodes::FullOuterJoin,
+                    args, as, &block)
+      end
+
+      # CROSS JOIN: every row of one table against every row of the other, so
+      # unlike the joins above there is no condition to give and no block to
+      # write it in.
+      #
+      #   Post.cross_joins(:authors)
+      #   Post.cross_joins(:posts, as: :others)
+      def cross_joins(*args, as: nil, &block)
+        if block
+          raise ArgumentError,
+            'a cross join has no condition; joins is the one that takes a block'
+        end
+        joins(build_cross_join(args.first, as))
+      end
+
       private
 
       def build_arel(...)
@@ -521,8 +570,9 @@ module ActiveRecord
       # which is the usual shape -- what the subquery is allowed to see is
       # what makes it lateral, and that is said inside it.
       def build_lateral_join(relation, join_class, alias_name, &block)
-        unless relation.is_a?(ActiveRecord::Relation)
-          raise ArgumentError, "a lateral join takes a relation to join against"
+        unless relation.lateral_value
+          raise ArgumentError,
+            "a relation joins laterally; mark it: joins(sub.lateral, as: :top)"
         end
         unless alias_name
           raise ArgumentError, "a lateral join needs a name: joins(..., as: :top)"
@@ -551,6 +601,37 @@ module ActiveRecord
         raise NotImplementedError, "a lateral join has no equivalent on #{database}"
       end
 
+      # MySQL has no FULL OUTER JOIN, and neither has MariaDB; SQLite has had
+      # one since 3.39 and PostgreSQL always.
+      def check_full_outer_support
+        return unless AST.adapter_family(klass) == :mysql
+        raise NotImplementedError, 'a full outer join has no equivalent on MySQL'
+      end
+
+      def outer_joins(called, join_class, args, alias_name, &block)
+        if args.first.is_a?(ActiveRecord::Relation)
+          return joins(build_lateral_join(args.first, join_class, alias_name, &block))
+        end
+        return joins(build_join_node(args.first, join_class, alias_name, &block)) if block
+
+        raise ArgumentError,
+          "#{called} takes a table and the block that joins it; an association " \
+          'is what joins and left_outer_joins read'
+      end
+
+      # Arel has a node for every other join and none for this one, and INNER
+      # JOIN with no ON -- which is a cross join on SQLite and MySQL -- is a
+      # syntax error on PostgreSQL.  So the SQL is written here, the second
+      # place in the gem that writes any: the keyword is fixed and the names
+      # are quoted by the adapter, so nothing of the caller's is in it.
+      def build_cross_join(target_table, alias_name)
+        joined = klass.with_connection do |connection|
+          name = connection.quote_table_name(target_table.to_s)
+          alias_name ? "#{name} #{connection.quote_table_name(alias_name.to_s)}" : name
+        end
+        Arel::Nodes::StringJoin.new(Arel.sql("CROSS JOIN #{joined}"))
+      end
+
       def build_join_node(target_table, join_class, alias_name, &block)
         ast = evaluate_block(&block)
         arel_table = Arel::Table.new(target_table)

data/lib/activerecord-refined/version.rb

@@ -1,5 +1,5 @@
 module Activerecord
   module Refined
-    VERSION = '0.6.1'
+    VERSION = '0.7.0'
   end
 end

data/lib/activerecord-refined.rb

@@ -9,6 +9,8 @@ ActiveRecord::QueryMethods.prepend ActiveRecord::Refined::QueryMethods
 # update_all and its kind are Relation's own rather than QueryMethods'.
 ActiveRecord::Relation.prepend ActiveRecord::Refined::Writes
 
-# The methods above are ActiveRecord's own, so a model already forwards them
-# to its relation.  These two are new, and have to be added to that list.
-ActiveRecord::Base.singleton_class.delegate :from_cte, :distinct_on, to: :all
+# The methods above are Active Record's own, so a model already forwards them
+# to its relation.  These are new, and have to be added to that list.
+ActiveRecord::Base.singleton_class.delegate(
+  :from_cte, :distinct_on, :lateral,
+  :right_outer_joins, :full_outer_joins, :cross_joins, to: :all)

data/test/test_block_syntax.rb

@@ -697,7 +697,7 @@ class TestBlockSyntax < Minitest::Test
   end
 
   # A relation without an explicit select list selects its primary key, the
-  # same way ActiveRecord's own where(id: relation) does.
+  # same way Active Record'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)
@@ -878,6 +878,80 @@ class TestBlockSyntax < Minitest::Test
     assert_raises(ArgumentError) { Author.left_outer_joins(:posts, as: :p) }
   end
 
+  # The other two outer joins, which Active Record has no method for.  MySQL
+  # has no FULL OUTER JOIN either, and says so before the SQL is built.
+  def test_right_outer_joins_with_block
+    assert_sql(/RIGHT OUTER JOIN "posts" ON "posts"."author_id" = "authors"."id"/,
+      Author.right_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }.to_sql)
+  end
+
+  def test_full_outer_joins_with_block
+    skip_without_full_outer_joins
+    assert_sql(/FULL OUTER JOIN "posts" ON "posts"."author_id" = "authors"."id"/,
+      Author.full_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }.to_sql)
+  end
+
+  def test_full_outer_joins_says_where_it_cannot_go
+    skip "#{ADAPTER} has FULL OUTER JOIN" unless ADAPTER == 'mysql2'
+    e = assert_raises(NotImplementedError) do
+      Author.full_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }
+    end
+    assert_match(/no equivalent on MySQL/, e.message)
+  end
+
+  def test_right_outer_joins_with_alias
+    assert_sql(
+      /RIGHT OUTER JOIN "authors" (?:AS )?"mentors" ON "mentors"."id" = "authors"."id"/,
+      Author.right_outer_joins(:authors, as: :mentors) { :mentors[:id] == :authors[:id] }.to_sql)
+  end
+
+  # An association is what joins and left_outer_joins read; there is nothing
+  # for these two to read one as.
+  def test_the_other_outer_joins_need_a_block
+    e = assert_raises(ArgumentError) { Author.right_outer_joins(:posts) }
+    assert_match(/takes a table and the block/, e.message)
+    unless ADAPTER == 'mysql2'
+      assert_raises(ArgumentError) { Author.full_outer_joins(:posts) }
+    end
+  end
+
+  # CROSS JOIN: every row against every row, so there is no condition to give.
+  def test_cross_joins
+    assert_sql(/FROM "authors" CROSS JOIN "posts"/, Author.cross_joins(:posts).to_sql)
+  end
+
+  def test_cross_joins_with_alias
+    assert_sql(/CROSS JOIN "authors" "others"/,
+      Author.cross_joins(:authors, as: :others).to_sql)
+  end
+
+  def test_cross_joins_takes_no_block
+    e = assert_raises(ArgumentError) { Author.cross_joins(:posts) { :id == 1 } }
+    assert_match(/no condition/, e.message)
+  end
+
+  def test_cross_joins_execution
+    Author.delete_all
+    Post.delete_all
+    Author.create!(name: 'a')
+    Author.create!(name: 'b')
+    Post.create!(title: 'one')
+    Post.create!(title: 'two')
+    Post.create!(title: 'three')
+    assert_equal(6, Author.cross_joins(:posts).count)
+  end
+
+  def test_right_outer_joins_execution
+    Author.delete_all
+    Post.delete_all
+    author = Author.create!(name: 'a')
+    Post.create!(title: 'hers', author_id: author.id)
+    Post.create!(title: 'nobody\'s', author_id: nil)
+    assert_equal(['a', nil],
+      Author.right_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }.
+        order { :posts[:title] }.pluck(:'authors.name'))
+  end
+
   def test_joins_without_alias_still_delegates
     assert_sql(/INNER JOIN "posts" ON "posts"."author_id" = "authors"."id"/,
       Author.joins(:posts).to_sql)
@@ -892,7 +966,7 @@ class TestBlockSyntax < Minitest::Test
         pluck(:name).sort)
   end
 
-  # ActiveRecord's from only takes a table name as a string.
+  # Active Record's from only takes a table name as a string.
   def test_from_symbol
     assert_sql(/FROM "tree"/, Node.from(:tree).to_sql)
   end
@@ -1856,6 +1930,73 @@ class TestBlockSyntax < Minitest::Test
     assert_equal(%w[x y], value.is_a?(String) ? JSON.parse(value) : value)
   end
 
+  # What text compared with a number means is a question the three adapters
+  # answer three ways -- `dig(:n) == 5` is true on SQLite, an error on
+  # PostgreSQL and true on MySQL, and `dig(:flag) == true` is true, an error
+  # and false -- so the comparison is refused rather than left to them.
+  def test_dig_refuses_a_comparison_with_anything_but_text
+    e = assert_raises(ArgumentError) { Doc.where { :meta.dig(:n) == 5 } }
+    assert_match(/cast/, e.message)
+    assert_raises(ArgumentError) { Doc.where { :meta.dig(:n) != 5 } }
+    assert_raises(ArgumentError) { Doc.where { :meta.dig(:n) > 6 } }
+    assert_raises(ArgumentError) { Doc.where { :meta.dig(:flag) == true } }
+    assert_raises(ArgumentError) { Doc.where { :meta.dig(:n).in?([1, 2]) } }
+    assert_raises(ArgumentError) { Doc.where { :meta.dig(:n).between?(1, 9) } }
+  end
+
+  # A string is what a dug value compares to; so is anything the block built
+  # rather than wrote as a literal, since that is nobody's guess to make.
+  def test_dig_compares_with_text_and_with_expressions
+    seed_docs
+    assert_equal(['one'], Doc.where { :meta.dig(:n) == '5' }.pluck(:name))
+    assert_equal([], Doc.where { :meta.dig(:n) == :name }.pluck(:name))
+    assert_equal(['one'], Doc.where { :meta.dig(:n) == upper('5') }.pluck(:name))
+    type = integer_type
+    assert_equal(['one'], Doc.where { cast(:meta.dig(:n), type) == 5 }.pluck(:name))
+  end
+
+  # The JSON for a string carries its quotes, so the same comparison is
+  # refused the other way about: false on SQLite, an error on PostgreSQL and
+  # true on MySQL.
+  def test_dig_json_refuses_a_comparison_with_a_ruby_value
+    e = assert_raises(ArgumentError) { Doc.where { :meta.dig_json(:a) == 'deep' } }
+    assert_match(/dig gives the value/, e.message)
+    assert_raises(ArgumentError) { Doc.where { :meta.dig_json(:n) == 5 } }
+  end
+
+  # What dig_json gives is a document, so the JSON operations read it: the
+  # same question asked of a part rather than of the whole.
+  def test_the_json_operations_read_what_dig_json_kept
+    seed_docs
+    assert_equal(['one'], Doc.where { :meta.dig_json(:a).key?(:b) }.pluck(:name))
+    assert_equal(%w[one two], Doc.where { :meta.dig_json(:n).not_null? }.order(:name).pluck(:name))
+    assert_equal(['one'],
+      Doc.where { :meta.dig_json(:a).dig(:b) == 'deep' }.pluck(:name))
+    value = Doc.where { :name == 'one' }.
+      select { :meta.dig_json(:a).bury(:b, 'x').as(:v) }.first.v
+    assert_equal('x', (value.is_a?(String) ? JSON.parse(value) : value)['b'])
+  end
+
+  def test_containment_reads_what_dig_json_kept
+    skip_without_json_containment
+    seed_docs
+    assert_equal(['one'], Doc.where { :meta.dig_json(:tags).contains?(['x']) }.pluck(:name))
+    assert_equal([], Doc.where { :meta.dig_json(:tags).contains?(['z']) }.pluck(:name))
+  end
+
+  # Reading text back as a document is where the adapters part company:
+  # SQLite parses it, MySQL takes it as written, PostgreSQL has no such
+  # function for text at all.
+  def test_the_json_operations_are_refused_on_a_dug_value
+    e = assert_raises(ArgumentError) { Doc.where { :meta.dig(:a).key?(:b) } }
+    assert_match(/dig_json keeps it/, e.message)
+    assert_raises(ArgumentError) { Doc.where { :meta.dig(:a).contains?(b: 1) } }
+    assert_raises(ArgumentError) { Doc.select { :meta.dig(:a).dig(:b) } }
+    assert_raises(ArgumentError) { Doc.select { :meta.dig(:a).dig_json(:b) } }
+    assert_raises(ArgumentError) { Doc.select { :meta.dig(:a).bury(:b, 'x') } }
+    assert_raises(ArgumentError) { Doc.select { :meta.dig(:a).except(:b) } }
+  end
+
   def test_dig_from_a_qualified_column
     seed_docs
     assert_equal(['one'], Doc.where { :docs[:meta].dig(:a, :b) == 'deep' }.pluck(:name))
@@ -2012,7 +2153,7 @@ class TestBlockSyntax < Minitest::Test
   def test_lateral_join
     skip_without_lateral
     seed_for_lateral
-    rows = Author.joins(top_post, as: :top, lateral: true).
+    rows = Author.joins(top_post.lateral, as: :top).
       select { [:name, :top[:title].as(:v)] }.map {|r| [r.name, r.v] }
     assert_equal([['writes', 'b']], rows)
   end
@@ -2021,7 +2162,7 @@ class TestBlockSyntax < Minitest::Test
   def test_left_outer_lateral_join
     skip_without_lateral
     seed_for_lateral
-    rows = Author.left_outer_joins(top_post, as: :top, lateral: true).
+    rows = Author.left_outer_joins(top_post.lateral, as: :top).
       select { [:name, :top[:title].as(:v)] }.order { :name }.map {|r| [r.name, r.v] }
     assert_equal([['does not', nil], ['writes', 'b']], rows)
   end
@@ -2031,22 +2172,28 @@ class TestBlockSyntax < Minitest::Test
   def test_lateral_join_takes_an_on_clause
     skip_without_lateral
     seed_for_lateral
-    assert_equal(0, Author.joins(top_post, as: :top, lateral: true) {
+    assert_equal(0, Author.joins(top_post.lateral, as: :top) {
       :top[:title] == 'nothing'
     }.count)
-    assert_sql(/ON TRUE/, Author.joins(top_post, as: :top, lateral: true).to_sql)
+    assert_sql(/ON TRUE/, Author.joins(top_post.lateral, as: :top).to_sql)
   end
 
-  def test_lateral_join_needs_a_relation_and_a_name
-    e = assert_raises(ArgumentError) { Author.joins(:posts, as: :top, lateral: true) }
-    assert_match(/takes a relation/, e.message)
-    e = assert_raises(ArgumentError) { Author.joins(top_post, lateral: true) }
+  def test_lateral_join_needs_the_mark_and_a_name
+    e = assert_raises(ArgumentError) { Author.joins(top_post, as: :top) }
+    assert_match(/mark it/, e.message)
+    e = assert_raises(ArgumentError) { Author.joins(top_post.lateral) }
     assert_match(/needs a name/, e.message)
   end
 
+  def test_lateral_spawns
+    relation = top_post
+    assert(relation.lateral.lateral_value)
+    refute(relation.lateral_value)
+  end
+
   def test_lateral_join_says_where_it_cannot_go
     skip 'this one has LATERAL' if ADAPTER == 'postgresql' || (ADAPTER == 'mysql2' && !mariadb?)
-    e = assert_raises(NotImplementedError) { Author.joins(top_post, as: :top, lateral: true) }
+    e = assert_raises(NotImplementedError) { Author.joins(top_post.lateral, as: :top) }
     assert_match(/lateral join has no equivalent/, e.message)
   end
 
@@ -2151,6 +2298,44 @@ class TestBlockSyntax < Minitest::Test
     assert_raises(ArgumentError) { Doc.select { :meta.bury(1.5, 'v') } }
   end
 
+  # except takes keys out, by the name of what Hash does.  PostgreSQL
+  # subtracts them where the others remove a path apiece, and what comes back
+  # is the same document on all three.
+  def test_except_a_key
+    assert_equal({ 'a' => { 'b' => 'deep' }, 'tags' => %w[x y], 'odd key' => 1 },
+      buried { { meta: :meta.except(:n) } })
+  end
+
+  def test_except_several_keys
+    assert_equal({ 'a' => { 'b' => 'deep' } },
+      buried { { meta: :meta.except(:n, :tags, :'odd key') } })
+  end
+
+  # A key that is not there is not an error, as Hash#except has none for it.
+  def test_except_a_key_that_is_not_there
+    assert_equal(5, buried { { meta: :meta.except(:nothing) } }['n'])
+  end
+
+  # The document a bury gives back is one to take keys out of.
+  def test_except_after_bury
+    document = buried { { meta: :meta.bury(:fresh, 9).except(:n) } }
+    assert_equal(9, document['fresh'])
+    assert_nil(document['n'])
+  end
+
+  def test_except_in_a_select
+    seed_docs
+    value = Doc.where { :name == 'one' }.select { :meta.except(:n).as(:v) }.first.v
+    assert_nil((value.is_a?(String) ? JSON.parse(value) : value)['n'])
+  end
+
+  # An index is not what the name says anywhere, and a path is bury's.
+  def test_except_takes_keys
+    assert_raises(ArgumentError) { Doc.select { :meta.except } }
+    e = assert_raises(ArgumentError) { Doc.select { :meta.except(0) } }
+    assert_match(/keys of the document/, e.message)
+  end
+
   def test_default_where_syntax
     assert_sql(/WHERE "users"."name" = 'Ruby' AND "users"."age" = 19/,
       User.where(name: 'Ruby', age: 19).to_sql)

data/test/test_helper.rb

@@ -74,7 +74,12 @@ module SqlAssertions
     skip "#{ADAPTER} has no JSON containment" if ADAPTER == 'sqlite3'
   end
 
-  # MariaDB's json is a checked longtext, which ActiveRecord sees as a string
+  # MySQL is the one without a FULL OUTER JOIN, and so is MariaDB.
+  def skip_without_full_outer_joins
+    skip "#{ADAPTER} has no full outer join" if ADAPTER == 'mysql2'
+  end
+
+  # MariaDB's json is a checked longtext, which Active Record sees as a string
   # and does not serialise a hash into -- what would go in is Ruby's inspect,
   # which the check refuses.  MySQL's json is a type of its own and takes the
   # hash; handing that one a string would store the document as a JSON string

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-refined
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
   - Shugo Maeda
@@ -73,7 +73,23 @@ dependencies:
           - ">="
           - !ruby/object:Gem::Version
             version: "0"
-description: Adding clean and powerful query syntax on AR using refinements
+  - !ruby/object:Gem::Dependency
+    name: bump
+    requirement: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "0"
+    type: :development
+    prerelease: false
+    version_requirements: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "0"
+description: Adding clean and powerful query syntax on Active Record using refinements
 email:
   - shugo@ruby-lang.org
 executables: []
@@ -127,7 +143,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.1.0.dev
 specification_version: 4
-summary: "ActiveRecord + Ruby 4.1 Proc#refined"
+summary: Write Active Record queries as Ruby expressions
 test_files:
   - test/test_block_syntax.rb
   - test/test_helper.rb