arel-extensions 9.0.0 → 9.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cac2b9e201296fa2c9e058f38cd0acf4835b134f2f98bb74f245af78b58f02c
-  data.tar.gz: 8b4be319b4037c1dfb2c54d6d9314a6add237ac60ec1fe2e6e1f0d396d67d1bb
+  metadata.gz: f3d568adf807cce6bc64a82bdf1ec35047475de73c85d0e4db25a8f452064869
+  data.tar.gz: 4a3724dca9138cf0d1220346d010254247ae92c4ebcfd8dae629d0455a2e6b5b
 SHA512:
-  metadata.gz: 36818826669a7004657c3362908fc8c11bb683fabbf93183dde33cb4a933ce3e5bd41da637cfd2c48906fab72d8ed22992802aa44daa69d7919cc3ccc62faffe
-  data.tar.gz: 17ae44d0099f00b6193f3e94aaa50830556e191d728bc3580b4164fae8f4b6b9f808cea2d3925ffe73cd5a30ea5501be6d393b428e23b01d6b4ee63dfd9d5d32
+  metadata.gz: 4f2f03dea174a2e6b4d708dc0a6fe7bb6e43af18135a4a4802fbb844278139bb7690d2d2dff38d9436767f49442d2483c1142dfa89c2555d92f97efc82813292
+  data.tar.gz: 85e605b87fb83bc2d36edd0ccab58fb85d15bebf0bbb4cf74b05a249354800664d5ae656f09141b7c0a50bb49e5c8b2d0649b331d5ac6d67b78cc378a0296e3f

data/CHANGELOG.md

@@ -1,4 +1,46 @@
-## [9.0.0] - Unreleased
+## [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
+- Fixed a SQL injection in the PostgreSQL visitor's JSON path handling
+  ([GHSA-75hc-9q9v-9cv2], CWE-89, high). `key`/`dig` path segments were
+  interpolated straight into a `#>'{...}'` array literal, so a segment
+  containing `}'` could close the literal and have the rest of it executed as
+  SQL. Most reachable through activerecord-filter, where a filter key like
+  `"metadata.<payload>"` on a json/jsonb column puts request input into `dig`.
+  Segments are now emitted as a quoted `#> array[...]`, which PostgreSQL folds
+  back to the same `text[]` constant (existing expression indexes still match).
+  Reported by [@saidM](https://github.com/saidM).
+- `cast_as` now validates the type name and raises `ArgumentError` unless it
+  looks like a type identifier. Not reachable from activerecord-filter, but it
+  was the same class of raw interpolation.
+
+### Changed
+- A path segment is now always a single segment: `key('a,b')` emits
+  `array['a,b']`, where the old raw `'{a,b}'` literal let PostgreSQL split it
+  on the comma into two segments. Use `dig('a', 'b')` for multi-segment paths.
+
+[GHSA-75hc-9q9v-9cv2]: https://github.com/malomalo/arel-extensions/security/advisories/GHSA-75hc-9q9v-9cv2
+
+## [9.0.0] - 2026-08-27
 
 ### Changed
 - Switched to independent Semantic Versioning. Prior releases tracked the Rails

data/README.md

@@ -56,21 +56,88 @@ 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 = User.arel_table[:data]
 
-data.key('name')            # data #>'{name}'   (aliases: data['name'], data.index('name'))
-data.dig('address', 'zip')  # data #>'{address,zip}'
+# Keys in a Object
+data['name']                # data #> array['name']
+data.key('name')            # data #> array['name']
+data.index('name')          # data #> array['name']
+
+# Integer index in a Array
+data[0]                     # data #> array['0']
+data.key(0)                 # data #> array['0']
+data.index(0)               # data #> array['0']
+
+# Dig and other operators
+data.dig('address', 'zip')  # data #> array['address','zip']
+data.dig('tags', -1)        # data #> array['tags','-1']
 data.has_key('name')        # data ? 'name'
 data.has_keys('a', 'b')     # data ?& array['a','b']
 data.has_any_key('a', 'b')  # data ?| array['a','b']
-data.cast_as('int')         # (data)::int
 ```
 
+A segment may be an integer, which PostgreSQL reads as an array index (negative
+counts from the end); out of range yields `NULL`.
+
+Path segments are quoted, so they are safe to build from untrusted input.
+PostgreSQL folds the array back to `'{address,zip}'::text[]`, so expression
+indexes written against the literal form still match.
+
+### Casting
+
+```ruby
+User.arel_table[:id].cast_as('text')            # (users.id)::text
+User.arel_table[:created_at].cast_as('date')    # (users.created_at)::date
+data.dig('age').cast_as('int')                  # (data #> array['age'])::int
+```
+
+A type name can't be quoted or bound, so `cast_as` accepts only something that
+looks like one; optionally schema qualified, with a modifier. For example:
+`text`, `varchar(255)`, `numeric(10,2)`, `timestamp(6) with time zone`,
+`int[]`, `public.geometry`. An `ArgumentError` will be raised otherwise.
+
 ### Full-text search
 
 ```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.0'
+    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/postgresql_extensions.rb

@@ -39,24 +39,24 @@ module Arel
         collector
       end
 
-      def visit_Arel_Attributes_Key(o, collector, last_key = true)
-        if o.relation.is_a?(Arel::Attributes::Key)
-          visit_Arel_Attributes_Key(o.relation, collector, false)
-          if last_key
-            collector << o.name.to_s
-            collector << "}'"
-          else
-            collector << o.name.to_s
-            collector << ","
-          end
-        else
-          visit(o.relation, collector)
-          collector << "\#>'{" << o.name.to_s
-          collector << (last_key ? "}'" : ",")
+      # Path segments are emitted as a quoted `array[...]` rather than
+      # interpolated into a `'{...}'` array literal, so a segment can never
+      # break out of the path and inject SQL (GHSA-75hc-9q9v-9cv2). PostgreSQL
+      # const-folds the array back to `'{a,b}'::text[]`, so expression indexes
+      # on the literal form still match.
+      def visit_Arel_Attributes_Key(o, collector)
+        keys = []
+        node = o
+        while node.is_a?(Arel::Attributes::Key)
+          keys.unshift(quote(node.name.to_s))
+          node = node.relation
         end
+
+        visit(node, collector)
+        collector << " #> array[" << keys.join(',') << "]"
         collector
       end
-
+      
       def visit_Arel_Nodes_HasKey(o, collector)
         right = o.right
 
@@ -84,10 +84,24 @@ module Arel
         collector
       end
 
+      # A type name can't be bound or quoted, so only allow something that
+      # actually looks like one -- optionally schema qualified, with a modifier
+      # and/or array suffix. Keeps user input from reaching the SQL as-is.
+      CAST_TYPE = /\A
+        [a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?  # type, optionally schema qualified
+        (\(\d+(\s*,\s*\d+)?\))?                # "varchar(255)", "numeric(10,2)"
+        (\ [a-z]+)*                            # "timestamp with time zone"
+        (\(\d+(\s*,\s*\d+)?\))?                # "character varying(255)"
+        (\[\])*                                # "int[]"
+      \z/xi
+      
       def visit_Arel_Attributes_Cast(o, collector)
+        type = o.name.to_s
+        raise ArgumentError, "invalid cast type: #{type.inspect}" unless CAST_TYPE.match?(type)
+
         collector << "("
         visit(o.relation, collector)
-        collector << ")::#{o.name}"
+        collector << ")::#{type}"
         collector
       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.0
+  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