arel-extensions 9.0.1 → 9.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99efadd34c12e304c5204c9dc2717bad533bfb20c9c280a036a8abc3110ab34a
-  data.tar.gz: 66c064d703b2531c7676e3a91bef9f0dd813355e24108c7966770ea1fba298ff
+  metadata.gz: f3d568adf807cce6bc64a82bdf1ec35047475de73c85d0e4db25a8f452064869
+  data.tar.gz: 4a3724dca9138cf0d1220346d010254247ae92c4ebcfd8dae629d0455a2e6b5b
 SHA512:
-  metadata.gz: 043be028082fea8d31c8b427db8a703b7f4a2f1916879e77455f05847086964840b4cae0886e73930ace056dc9e86bcb7c375c4794a64f5ac5a85c19d5f9b61b
-  data.tar.gz: 89d8e35f5503774cc499c93fa0cc9ea427dec2cecc27cd6ee01f5d52f9f66f9c278078c80c865d7fc4bac8362e9c860f7fe33b1a90b572c4823621cfe6be9ba3
+  metadata.gz: 4f2f03dea174a2e6b4d708dc0a6fe7bb6e43af18135a4a4802fbb844278139bb7690d2d2dff38d9436767f49442d2483c1142dfa89c2555d92f97efc82813292
+  data.tar.gz: 85e605b87fb83bc2d36edd0ccab58fb85d15bebf0bbb4cf74b05a249354800664d5ae656f09141b7c0a50bb49e5c8b2d0649b331d5ac6d67b78cc378a0296e3f

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [9.1.0] - 2026-09-10
+
+### Added
+
+- PostgreSQL's positional range operators on attributes: `strictly_left_of`
+  (`<<`), `strictly_right_of` (`>>`), `not_extend_right_of` (`&<`),
+  `not_extend_left_of` (`&>`) and `adjacent_to` (`-|-`).
+
+### Changed
+
+- The Sunstone visitor handles `Arel::Nodes::Not` in place of the
+  `Arel::Nodes::NotOverlaps` it used to name, which never existed — so
+  `attribute.overlaps(x).not` now serializes where nothing could before.
+
+### Fixed
+
+- `contained_by` now accepts a Ruby Range, so range columns work with all three
+  range predicates.
+
 ## [9.0.1] - 2026-08-30
 
 ### Security

data/README.md

@@ -56,8 +56,45 @@ A `RANDOM()` ordering node is also provided.
 tags = Post.arel_table[:tags]
 tags.contained_by(other)   # tags <@ other
 tags.excludes(other)       # NOT (tags @> other)
+
+# Any predicate negates with Arel's own #not:
+tags.overlaps(other).not   # NOT (tags && other)
+```
+
+### Range columns
+
+ActiveRecord types `tsrange`/`tstzrange`/`daterange`/`int4range`/`int8range`/
+`numrange` columns as `OID::Range`, so a plain Ruby Range serializes to a
+PostgreSQL range literal — no special node needed:
+
+```ruby
+period = Property.arel_table[:period]
+
+period.contains(t1...t2)      # "period" @> '[2026-01-01 00:00:00,2026-12-31 00:00:00)'
+period.overlaps(t1...t2)      # "period" && '[...)'
+period.contained_by(t1...t2)  # "period" <@ '[...)'
 ```
 
+`..` gives an inclusive upper bound (`']'`), `...` an exclusive one (`')'`), and
+a `nil` end is unbounded. PostgreSQL's exclusive *lower* bounds (`'('`) have no
+Ruby Range equivalent; build the range with a `NamedFunction` if you need one.
+
+Beyond containment and overlap, PostgreSQL's positional operators ask where two
+ranges sit relative to one another:
+
+```ruby
+period.strictly_left_of(other)     # period << other
+period.strictly_right_of(other)    # period >> other
+period.not_extend_right_of(other)  # period &< other
+period.not_extend_left_of(other)   # period &> other
+period.adjacent_to(other)          # period -|- other
+```
+
+`<<` and `>>` mean every element is lower (or higher) with no overlap. `&<` asks
+whether the left range stops at or before the right one's upper bound, and `&>`
+whether it starts at or after the right one's lower bound. `-|-` is true when the
+two abut — touching, with no gap and no overlap.
+
 ### JSON / JSONB predicates
 
 ```ruby

data/lib/arel/array_predications.rb

@@ -3,8 +3,16 @@
 module Arel
   module ArrayPredications
 
-    # Used by both JSON and ARRAY so it doesn't try to cast to array
+    # Used by both JSON and ARRAY so it doesn't try to cast to array — callers
+    # there pre-wrap the value themselves.
+    #
+    # A Ruby Range is the exception: it has no other reading, and leaving it
+    # unquoted made `contained_by` the one range predicate that could not take
+    # one (`contains` and `overlaps` come from Arel core, which quotes through
+    # the attribute). On a range column the attribute's type casts it to a
+    # PostgreSQL range literal.
     def contained_by(value)
+      value = Arel::Nodes.build_quoted(value, self) if value.is_a?(::Range)
       Arel::Nodes::ContainedBy.new(self, value)
     end
 

data/lib/arel/extensions/version.rb

@@ -2,6 +2,6 @@
 
 module Arel
   module Extensions
-    VERSION = '9.0.1'
+    VERSION = '9.1.0'
   end
 end

data/lib/arel/extensions.rb

@@ -9,10 +9,18 @@ require_relative "./nodes/intersects"
 require_relative "./nodes/within"
 require_relative "./nodes/excludes"
 require_relative "./nodes/contained_by"
+require_relative "./nodes/strictly_left_of"
+require_relative "./nodes/strictly_right_of"
+require_relative "./nodes/not_extend_right_of"
+require_relative "./nodes/not_extend_left_of"
+require_relative "./nodes/adjacent_to"
 
 require File.expand_path('../array_predications', __FILE__)
 Arel::Attributes::Attribute.include(Arel::ArrayPredications)
 
+require File.expand_path('../range_predications', __FILE__)
+Arel::Attributes::Attribute.include(Arel::RangePredications)
+
 require File.expand_path('../nodes/random', __FILE__)
 require File.expand_path(File.join(__FILE__, '../../../ext/arel/nodes/ascending'))
 require File.expand_path(File.join(__FILE__, '../../../ext/arel/nodes/descending'))

data/lib/arel/nodes/adjacent_to.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Arel
+  module Nodes
+    # PostgreSQL `-|-`. Do the two ranges abut — touching, with no gap and no overlap?
+    class AdjacentTo < InfixOperation
+      def initialize(left, right)
+        super(:"-|-", left, right)
+      end
+    end
+  end
+end

data/lib/arel/nodes/not_extend_left_of.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Arel
+  module Nodes
+    # PostgreSQL `&>`. Does the left range start at or after the right one's lower bound?
+    class NotExtendLeftOf < InfixOperation
+      def initialize(left, right)
+        super(:"&>", left, right)
+      end
+    end
+  end
+end

data/lib/arel/nodes/not_extend_right_of.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Arel
+  module Nodes
+    # PostgreSQL `&<`. Does the left range stop at or before the right one's upper bound?
+    class NotExtendRightOf < InfixOperation
+      def initialize(left, right)
+        super(:"&<", left, right)
+      end
+    end
+  end
+end

data/lib/arel/nodes/strictly_left_of.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Arel
+  module Nodes
+    # PostgreSQL `<<`. Is the left range strictly left of the right one — every element lower,
+    # with no overlap?
+    class StrictlyLeftOf < InfixOperation
+      def initialize(left, right)
+        super(:"<<", left, right)
+      end
+    end
+  end
+end

data/lib/arel/nodes/strictly_right_of.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Arel
+  module Nodes
+    # PostgreSQL `>>`. Is the left range strictly right of the right one — every element higher,
+    # with no overlap?
+    class StrictlyRightOf < InfixOperation
+      def initialize(left, right)
+        super(:">>", left, right)
+      end
+    end
+  end
+end

data/lib/arel/range_predications.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Arel
+  # PostgreSQL's positional range operators. Each takes a range and answers a
+  # question about where the two sit relative to one another, which `contains`,
+  # `overlaps` and `contained_by` cannot express.
+  #
+  # Operands are quoted through the attribute the way Arel core's `overlaps`
+  # does, so a Ruby Range works and an already-built node passes through.
+  module RangePredications
+
+    # <<
+    def strictly_left_of(value)
+      Arel::Nodes::StrictlyLeftOf.new(self, Arel::Nodes.build_quoted(value, self))
+    end
+
+    # >>
+    def strictly_right_of(value)
+      Arel::Nodes::StrictlyRightOf.new(self, Arel::Nodes.build_quoted(value, self))
+    end
+
+    # &<
+    def not_extend_right_of(value)
+      Arel::Nodes::NotExtendRightOf.new(self, Arel::Nodes.build_quoted(value, self))
+    end
+
+    # &>
+    def not_extend_left_of(value)
+      Arel::Nodes::NotExtendLeftOf.new(self, Arel::Nodes.build_quoted(value, self))
+    end
+
+    # -|-
+    def adjacent_to(value)
+      Arel::Nodes::AdjacentTo.new(self, Arel::Nodes.build_quoted(value, self))
+    end
+
+  end
+end

data/lib/arel/visitors/sunstone_extensions.rb

@@ -114,10 +114,18 @@ module Arel
         end
       end
 
-      def visit_Arel_Nodes_NotOverlaps o, collector
-        key = visit(o.left, collector)
-        value = { not_overlaps: visit(o.right, collector) }
-        
+      # A negated Overlaps — `attribute.overlaps(x).not` — is the only NOT this
+      # adapter knows how to serialize, so the negation is unwrapped here.
+      def visit_Arel_Nodes_Not o, collector
+        expr = o.expr
+
+        unless expr.is_a?(Arel::Nodes::Overlaps)
+          raise "Not Supported: NOT of #{expr.class}"
+        end
+
+        key = visit(expr.left, collector)
+        value = { not_overlaps: visit(expr.right, collector) }
+
         if key.is_a?(Hash)
           add_to_bottom_of_hash_or_array(key, value)
           key

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: arel-extensions
 version: !ruby/object:Gem::Version
-  version: 9.0.1
+  version: 9.1.0
 platform: ruby
 authors:
 - Jon Bracy
@@ -178,6 +178,7 @@ files:
 - lib/arel/extensions/version.rb
 - lib/arel/gis_predications.rb
 - lib/arel/json_predications.rb
+- lib/arel/nodes/adjacent_to.rb
 - lib/arel/nodes/binary_value.rb
 - lib/arel/nodes/contained_by.rb
 - lib/arel/nodes/excludes.rb
@@ -187,14 +188,19 @@ files:
 - lib/arel/nodes/has_keys.rb
 - lib/arel/nodes/hex_encoded_binary_value.rb
 - lib/arel/nodes/intersects.rb
+- lib/arel/nodes/not_extend_left_of.rb
+- lib/arel/nodes/not_extend_right_of.rb
 - lib/arel/nodes/random.rb
 - lib/arel/nodes/relation.rb
+- lib/arel/nodes/strictly_left_of.rb
+- lib/arel/nodes/strictly_right_of.rb
 - lib/arel/nodes/ts_match.rb
 - lib/arel/nodes/ts_query.rb
 - lib/arel/nodes/ts_rank.rb
 - lib/arel/nodes/ts_rank_cd.rb
 - lib/arel/nodes/ts_vector.rb
 - lib/arel/nodes/within.rb
+- lib/arel/range_predications.rb
 - lib/arel/ts_predications.rb
 - lib/arel/visitors/postgresql_extensions.rb
 - lib/arel/visitors/sunstone_extensions.rb