torque-postgresql 4.0.1 → 4.1.0

data/lib/torque/postgresql/predicate_builder/composite_handler.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module PredicateBuilder
+      # Turns a hash of columns into a proper set of conditions over a composite
+      # column, handing each of them back to the predicate builder so that the
+      # whole +where+ vocabulary works inside a composite
+      class CompositeHandler
+        class << self
+          # Values that this handler knows how to deal with, checked before the
+          # attribute itself because it is way cheaper
+          def candidate?(value, type)
+            return false unless Adapter::OID::Composite.from(type)
+
+            case value
+            when ::Hash, Attributes::Composite then true
+            when ::Array then value.any? { |entry| candidate?(entry, type) }
+            else false
+            end
+          end
+
+          # Whether the value describes columns, instead of whole records
+          def columns?(value)
+            value.is_a?(::Hash) || (value.is_a?(::Array) && value.all?(::Hash))
+          end
+        end
+
+        def initialize(predicate_builder)
+          @predicate_builder = predicate_builder
+        end
+
+        def call(attribute, type, value)
+          @composite = Adapter::OID::Composite.from(type)
+          array = type.is_a?(ARRAY_OID)
+          record = !self.class.columns?(value)
+
+          return call_for_record(attribute, value, array) if record
+          return call_for_array(attribute, value) if array
+
+          conditions_for(attribute, value)
+        end
+
+        # The type of a single column of the composite type
+        def type_of(name)
+          columns = @composite.columns
+          name = name.to_s
+
+          raise ArgumentError, <<~MSG.squish unless columns.key?(name)
+            Unable to build a condition for "#{name}" because it is not a
+            column of the "#{@composite.name}" composite type.
+          MSG
+
+          [columns[name]]
+        end
+
+        private
+
+          attr_reader :predicate_builder, :composite
+
+          # Whole records cannot be sent as anonymous binds, because the
+          # comparison operators resolve them to the +record+ pseudo type, so
+          # they are always casted to the type they belong to
+          def call_for_record(attribute, value, array)
+            name = attribute.name
+            cast = composite.name
+
+            return attribute.eq(FN.bind(name, value, composite).pg_cast(cast)) unless array
+
+            if value.is_a?(::Array)
+              list = FN.bind(name, value, ARRAY_OID.new(composite))
+              return attribute.overlaps(list.pg_cast(cast, true))
+            end
+
+            entry = FN.bind(name, value, composite).pg_cast(cast)
+            FN.infix(:"=", entry, FN.any(attribute))
+          end
+
+          # Entries of an array of composite values can only be matched one by
+          # one, so the conditions are checked against each unnested entry
+          def call_for_array(attribute, value)
+            source = Arel::Nodes::Ref.new(composite.name)
+            entries = ::Arel::Nodes::TableAlias.new(FN.unnest(attribute), composite.name)
+
+            manager = ::Arel::SelectManager.new
+            manager.from(entries)
+            manager.project(::Arel.sql('1'))
+            manager.where(conditions_for(source, value))
+            manager.exists
+          end
+
+          # A list of values means that any of them is a match
+          def conditions_for(source, value)
+            return group_for(source, value) unless value.is_a?(::Array)
+
+            groups = value.map { |entry| group_for(source, entry) }
+            groups.reduce(:or)
+          end
+
+          def group_for(source, entry)
+            entry = entry.to_h unless entry.is_a?(::Hash)
+            table = PredicateTable.new(self, source, Arel::Nodes::Column)
+            nodes = predicate_builder.with(table).build_from_hash(entry.stringify_keys)
+            ::Arel::Nodes::Grouping.new(nodes.reduce(:and))
+          end
+      end
+    end
+  end
+end

data/lib/torque/postgresql/predicate_builder/ltree_handler.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module PredicateBuilder
+      # A condition over an ltree column is rarely a plain equality, so the value
+      # decides which operator to use: a plain path is compared with +=+, while
+      # anything carrying an lquery marker is matched with +~+
+      class LtreeHandler
+        class << self
+          # An Array is always a single value here, either the labels of a path
+          # or the items of a pattern, so it never means a list of values the
+          # way the regular handlers would take it. Objects that describe their
+          # own path are claimed as well, otherwise a record would be reduced to
+          # its primary key before it had the chance to describe itself
+          def candidate?(value, type)
+            return false unless type.is_a?(Adapter::OID::Ltree)
+
+            value.is_a?(::Array) || value.is_a?(LQuery) ||
+              LTree.compatible?(value) || LQuery.marker?(value)
+          end
+        end
+
+        def initialize(predicate_builder)
+          @predicate_builder = predicate_builder
+        end
+
+        def call(attribute, type, value)
+          return attribute.eq(FN.bind_with(attribute, type.cast(value))) \
+            unless LQuery.marker?(value)
+
+          attribute.matches_lquery(pattern_for(attribute, value))
+        end
+
+        private
+
+          def pattern_for(attribute, value)
+            type = Adapter::OID::Lquery.new
+            FN.bind(attribute.name, type.cast(value), type).pg_cast('lquery')
+          end
+      end
+    end
+  end
+end

data/lib/torque/postgresql/predicate_builder/struct_handler.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module PredicateBuilder
+      # Turns a hash of properties into a proper set of conditions over the
+      # document that holds them, handing each of them back to the predicate
+      # builder so that the whole +where+ vocabulary works inside a struct
+      class StructHandler
+        # Properties are extracted as text, so only the ones whose type has a
+        # counterpart on the database are casted before being compared
+        PLAIN_TYPES = %i[string text].freeze
+
+        class << self
+          # Only a hash describes properties, everything else is left alone so
+          # that whole documents are still compared as documents
+          def candidate?(value, type)
+            value.is_a?(::Hash) && type.is_a?(Adapter::OID::Struct) &&
+              !type.is_a?(Adapter::OID::StructList)
+          end
+        end
+
+        def initialize(predicate_builder)
+          @predicate_builder = predicate_builder
+        end
+
+        def call(attribute, struct, value)
+          raise ArgumentError, <<~MSG.squish unless struct.type == :jsonb
+            Unable to build a condition over "#{attribute.name}" because json
+            columns cannot be queried by their properties. Use jsonb instead.
+          MSG
+
+          @struct = struct
+          table = PredicateTable.new(self, attribute, Arel::Nodes::Property)
+          nodes = predicate_builder.with(table).build_from_hash(value.stringify_keys)
+
+          ::Arel::Nodes::Grouping.new(nodes.reduce(:and))
+        end
+
+        # The type of a single property, plus what it has to be casted to once
+        # it is extracted from the document as text
+        def type_of(name)
+          klass = @struct.klass
+          name = name.to_s
+
+          raise ArgumentError, <<~MSG.squish if klass.strict? && !klass.attribute_names.include?(name)
+            Unable to build a condition for "#{name}" because it is not a
+            declared property of #{klass.name}.
+          MSG
+
+          type = klass.attribute_types[name]
+          [type, cast_for(type)]
+        end
+
+        private
+
+          attr_reader :predicate_builder
+
+          def cast_for(type)
+            name = type&.type
+            return if name.nil? || PLAIN_TYPES.include?(name)
+
+            ActiveRecord::Base.connection.type_to_sql(name)
+          end
+      end
+    end
+  end
+end

data/lib/torque/postgresql/predicate_builder.rb

@@ -2,6 +2,9 @@
 
 require_relative 'predicate_builder/array_handler'
 
+require_relative 'predicate_builder/composite_handler'
+require_relative 'predicate_builder/ltree_handler'
+require_relative 'predicate_builder/struct_handler'
 require_relative 'predicate_builder/regexp_handler'
 require_relative 'predicate_builder/arel_attribute_handler'
 require_relative 'predicate_builder/enumerator_lazy_handler'
@@ -28,6 +31,29 @@ module Torque
           register_handler(::Arel::Attributes::Attribute, ArelAttributeHandler.new(self))
         end
       end
+
+      # Values described as a hash of columns or properties are turned into
+      # conditions over the column that holds them. Whole values are left to
+      # the regular handlers, so that they are compared as a single value
+      def build(attribute, value, operator = nil)
+        type = table.type(attribute.name)
+        handler = handler_for_document(type, value)
+        return super if handler.nil?
+
+        handler.new(self).call(attribute, type, value)
+      end
+
+      private
+
+        def handler_for_document(type, value)
+          if PostgreSQL.config.composite.enabled && CompositeHandler.candidate?(value, type)
+            CompositeHandler
+          elsif PostgreSQL.config.struct.enabled && StructHandler.candidate?(value, type)
+            StructHandler
+          elsif PostgreSQL.config.ltree.enabled && LtreeHandler.candidate?(value, type)
+            LtreeHandler
+          end
+        end
     end
 
     ::ActiveRecord::PredicateBuilder.prepend(PredicateBuilder)

data/lib/torque/postgresql/predicate_table.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    # Mimics ActiveRecord::TableMetadata so that the parts of a value that holds
+    # other values, like the columns of a composite type or the properties of a
+    # document, can be treated as the columns of the value they belong to. That
+    # is what allows each of them to be handed back to the predicate builder
+    #
+    # The handler is the one that knows how to resolve a name, and the node is
+    # the one that knows how to reach it
+    class PredicateTable
+      def initialize(handler, source, node)
+        @handler = handler
+        @source = source
+        @node = node
+      end
+
+      def arel_table
+        self
+      end
+
+      def [](name)
+        @node.new(@source, name, *@handler.type_of(name))
+      end
+
+      def type(name)
+        @handler.type_of(name).first
+      end
+
+      # Anything that gets here is meant to be resolved as a part of the value,
+      # which is what +type_of+ is there to accept or reject
+      def has_column?(*)
+        true
+      end
+
+      def primary_key
+        nil
+      end
+
+      # Rails 8.1 renamed this, so both names answer for the supported versions
+      def associated_with(*)
+        false
+      end
+
+      alias associated_with? associated_with
+
+      def aggregated_with?(*)
+        false
+      end
+
+      def polymorphic_association?
+        false
+      end
+
+      def through_association?
+        false
+      end
+    end
+  end
+end

data/lib/torque/postgresql/railtie.rb

@@ -85,6 +85,32 @@ module Torque
               end
             end
 
+            ## Struct Enabled Setup
+            if (config = torque_config.struct).enabled
+              require_relative 'adapter/oid/struct'
+              require_relative 'adapter/oid/struct_list'
+              require_relative 'adapter/oid/struct_set'
+
+              require_relative 'attributes/struct'
+
+              Attributes::Struct.include_on(ActiveRecord::Base)
+            end
+
+            ## Composite Enabled Setup
+            if (config = torque_config.composite).enabled
+              require_relative 'adapter/oid/composite'
+              require_relative 'attributes/composite'
+
+              ar_type.register(:composite, Adapter::OID::Composite, adapter: :postgresql)
+
+              config.namespace ||= ::Object.const_set('Composite', Module.new)
+
+              # Define a method to find composite classes based on the namespace
+              config.namespace.define_singleton_method(:const_missing) do |name|
+                Attributes::Composite.lookup(name)
+              end
+            end
+
             ## Geometry Enabled Setup
             if (config = torque_config.geometry).enabled
               require_relative 'adapter/oid/box'
@@ -110,6 +136,15 @@ module Torque
               ar_type.register(:interval, Adapter::OID::Interval, adapter: :postgresql)
             end
 
+            ## LTree Enabled Setup
+            if (config = torque_config.ltree).enabled
+              require_relative 'adapter/oid/ltree'
+              require_relative 'adapter/oid/lquery'
+
+              ar_type.register(:ltree,  Adapter::OID::Ltree,  adapter: :postgresql)
+              ar_type.register(:lquery, Adapter::OID::Lquery, adapter: :postgresql)
+            end
+
             ## Full Text Search Enabled Setup
             if (config = torque_config.full_text_search).enabled
               require_relative 'attributes/full_text_search'

data/lib/torque/postgresql/relation/inheritance.rb

@@ -6,13 +6,33 @@ module Torque
       module Inheritance
 
         # :nodoc:
-        def cast_records_values
-          @values.fetch(:cast_records, FROZEN_EMPTY_ARRAY)
+        def expand_records_values
+          @values.fetch(:expand_records, FROZEN_EMPTY_ARRAY)
         end
         # :nodoc:
-        def cast_records_values=(value)
+        def expand_records_values=(value)
           assert_modifiable!
-          @values[:cast_records] = value
+          @values[:expand_records] = value
+        end
+
+        # :nodoc:
+        def expand_records_eager_load_value
+          @values.fetch(:expand_records_eager_load, nil)
+        end
+        # :nodoc:
+        def expand_records_eager_load_value=(value)
+          assert_modifiable!
+          @values[:expand_records_eager_load] = value
+        end
+
+        # :nodoc:
+        def expand_records_scoped_value
+          @values.fetch(:expand_records_scoped, nil) || {}
+        end
+        # :nodoc:
+        def expand_records_scoped_value=(value)
+          assert_modifiable!
+          @values[:expand_records_scoped] = value
         end
 
         # :nodoc:
@@ -25,6 +45,8 @@ module Torque
           @values[:itself_only] = value
         end
 
+        RECORD_CLASS_TOKEN = :_regclass
+
         delegate :quote_table_name, :quote_column_name, to: :connection
 
         # Specify that the results should come only from the table that the
@@ -38,46 +60,90 @@ module Torque
 
         # Like #itself_only, but modifies relation in place.
         def itself_only!(*)
+          raise_itself_only_conflict! if expand_records_values.present?
+
           self.itself_only_value = true
           self
         end
 
-        # Enables the casting of all returned records. The result will include
-        # all the information needed to instantiate the inherited models
+        # Load the columns that only exist on the inherited tables, so that
+        # records come out complete and writable. Defaults to every dependent
+        # that adds columns
+        #
+        #   Activity.expand_records
+        #   # Runs one additional query per inherited table
         #
-        #   Activity.cast_records
-        #   # The result list will have many different classes, for all
-        #   # inherited models of activities
-        def cast_records(*types, **options)
-          spawn.cast_records!(*types, **options)
+        #   Activity.expand_records(ActivityBook, eager_load: true)
+        #   # Runs a single query using outer joins
+        def expand_records(*types, **options)
+          spawn.expand_records!(*types, **options)
         end
 
-        # Like #cast_records, but modifies relation in place
-        def cast_records!(*types, **options)
-          where!(regclass.pg_cast(:varchar).in(types.map(&:table_name))) if options[:filter]
-          self.select_extra_values += [regclass.as(_record_class_attribute.to_s)]
-          self.cast_records_values = (types.present? ? types : model.casted_dependents.values)
+        # Like #expand_records, but modifies relation in place
+        def expand_records!(*types, eager_load: false, filter: false)
+          raise_itself_only_conflict! if itself_only_value === true
+
+          types = types.presence || model.inheritance_expandable_dependents.values
+
+          where!(regclass.pg_cast(:varchar).in(types.map(&:table_name))) if filter
+          self.expand_records_values = types
+          self.expand_records_eager_load_value = eager_load
           self
         end
 
+        # Accept the record class marker as a column, which is the only way an
+        # explicit selection can still produce casted records
+        #
+        #   Activity.select(:_regclass, :id, :title)
+        def select(*fields)
+          return super if fields.empty?
+          return super(*fields, build_record_class_marker) if fields.delete(RECORD_CLASS_TOKEN)
+
+          super
+        end
+
         private
 
+          def raise_itself_only_conflict!
+            raise InheritanceError.new(<<~MSG.squish)
+              Reading from ONLY a table never returns records from its
+              inherited tables, so itself_only and expand_records cannot be
+              combined.
+            MSG
+          end
+
           # Hook arel build to add any necessary table
           def build_arel(*)
             arel = super
             arel.only if self.itself_only_value === true
-            build_inheritances(arel)
+
+            arel.project(build_record_class_marker) if inheritance_discriminated?
+            build_inheritances(arel) if self.expand_records_eager_load_value
             arel
           end
 
+          def inheritance_discriminated?
+            return false if self.itself_only_value === true
+            return false if select_values.present?
+            return false unless from_clause.empty?
+
+            model.physically_inheritances?
+          end
+
+          def build_record_class_marker
+            regclass.as(_record_class_column_name)
+          end
+
           # Build all necessary data for inheritances
           def build_inheritances(arel)
-            return if self.cast_records_values.empty?
+            return if self.expand_records_values.empty?
 
-            mergeable = inheritance_mergeable_attributes
+            columns = build_inheritances_joins(arel, self.expand_records_values)
+            # The joins are still needed, but an explicit select owns the projection
+            return if columns.empty? || select_values.present?
 
-            columns = build_inheritances_joins(arel, self.cast_records_values)
-            columns = columns.map do |column, arel_tables|
+            mergeable = inheritance_mergeable_attributes
+            projections = columns.map do |column, arel_tables|
               next arel_tables.first[column] if arel_tables.size == 1
 
               if mergeable.include?(column)
@@ -87,8 +153,7 @@ module Torque
               end
             end
 
-            columns.push(build_auto_caster_marker(arel, self.cast_records_values))
-            self.select_extra_values += columns.flatten if columns.any?
+            arel.project(*projections.flatten)
           end
 
           # Build as many left outer join as necessary for each dependent table
@@ -111,15 +176,68 @@ module Torque
             columns
           end
 
-          def build_auto_caster_marker(arel, types)
-            attribute = regclass.pg_cast(:varchar).in(types.map(&:table_name))
-            attribute.as(self.class._auto_cast_attribute.to_s)
-          end
-
           def regclass
             arel_table['tableoid'].pg_cast(:regclass)
           end
 
+        module Expansion
+          def preload_associations(records)
+            super
+            return if expand_records_scoped_value.blank?
+
+            expand_records_scoped_value.each do |base_model, targets|
+              preloaded_association_names.each do |name|
+                reflection = model.reflect_on_association(name)
+                next if reflection.nil? || reflection.polymorphic? || !(reflection.klass <= base_model)
+
+                loaded = records.flat_map { |record| record.association(name).target }
+                PostgreSQL::Inheritance::Expander.new(reflection.klass, loaded.compact, targets).call
+              end
+            end
+          end
+
+          private
+
+            # Records only carry the columns of the queried table, so
+            # expanding has to happen after they have been instantiated
+            def exec_queries
+              records = super
+              warn_about_missing_record_class(records)
+              return records if expand_records_values.empty? || expand_records_eager_load_value
+
+              PostgreSQL::Inheritance::Expander.new(model, records, expand_records_values).call
+              records.each(&:readonly!) if readonly_value
+              records
+            end
+
+            def preloaded_association_names
+              list = preload_values + (eager_loading? ? [] : includes_values)
+              list.flat_map { |entry| entry.is_a?(Hash) ? entry.keys : entry }
+            end
+
+            # Warn once per query that actually lost the real class, instead of
+            # once per explicit select that merely omits the marker
+            def warn_about_missing_record_class(records)
+              return unless model.physically_inheritances?
+              return if records.empty? || group_values.present? || distinct_value || select_values.empty?
+              return unless from_clause.empty?
+              return if itself_only_value === true
+              return if select_values.any? { |value| record_class_marker?(value) }
+              return if records.any? { |record| record.class != model }
+
+              warn(<<~MSG.squish)
+                #{model.name} was queried with an explicit select that omits
+                :_regclass, so its records will not be instantiated as their
+                real class.
+              MSG
+            end
+
+            def record_class_marker?(value)
+              return value.right.to_s == _record_class_column_name if value.is_a?(::Arel::Nodes::As)
+              value.is_a?(String) && value.include?(_record_class_column_name)
+            end
+
+        end
       end
     end
   end

data/lib/torque/postgresql/relation/merger.rb

@@ -46,18 +46,34 @@ module Torque
             end
           end
 
-          # Merge settings related to inheritance tables
+          # Merge settings related to inheritance tables, going through the
+          # public operations so that their conflicts are still detected
           def merge_inheritance
             return unless relation.is_a?(Relation::Inheritance)
 
-            relation.itself_only_value = true if other.itself_only_value.present?
+            relation.itself_only! if other.itself_only_value.present?
 
-            if other.cast_records_values.present?
-              relation.cast_records_values += other.cast_records_values
-              relation.cast_records_values.uniq!
+            return if other.expand_records_values.blank?
+
+            if relation.model == other.model
+              types = (relation.expand_records_values + other.expand_records_values).uniq
+              relation.expand_records!(*types, eager_load: other.expand_records_eager_load_value)
+            else
+              raise_eager_load_conflict! if other.expand_records_eager_load_value
+
+              relation.expand_records_scoped_value = relation.expand_records_scoped_value
+                .merge(other.model => other.expand_records_values) { |_, a, b| (a + b).uniq }
             end
           end
 
+          def raise_eager_load_conflict!
+            raise InheritanceError.new(<<~MSG.squish)
+              Expanding the records of a different model happens through a
+              preload, which has no query to eager load the inherited tables
+              into, so the two cannot be merged.
+            MSG
+          end
+
           # Merge settings related to buckets
           def merge_buckets
             return unless defined?(Relation::Buckets) && relation.is_a?(Relation::Buckets)