typed_eav 0.7.0 → 0.8.0

data/lib/typed_eav/has_typed_eav/dirty_tracking.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module HasTypedEAV
+    # Read-only, on-demand dirty tracking for typed Value rows that are part
+    # of a host association's in-memory target.
+    #
+    # Pending comparisons follow Active Record's own dirty state; saved
+    # snapshots use the host lifecycle, not a separate Value mutation registry.
+    # A typed Value
+    # retains its database snapshot through `attribute_in_database`, while
+    # autosave clears its ordinary dirty state after a successful host save.
+    # Consequently failed saves and outer transaction rollbacks retain the
+    # same correction-friendly state that Active Record exposes on the child.
+    #
+    # The association target is inspected without loading it. Named and
+    # nested assignment paths already place their touched Values in that
+    # target; callers using direct Value assignment should use a loaded
+    # `typed_values` association. A Value loaded independently from the host
+    # is intentionally outside this API because observing it would require an
+    # eager query of every Value row or a new global mutation registry.
+    module DirtyTracking
+      extend ActiveSupport::Concern
+
+      included do
+        # Register before has_typed_eav declares the autosave association.
+        # Active Model prepends after_* callbacks, so the later autosave
+        # callback executes after this capture. The public save wrappers
+        # restore prior state when a later save callback raises.
+        after_create :_typed_eav_capture_saved_changes
+        after_update :_typed_eav_capture_saved_changes
+        after_destroy :_typed_eav_clear_saved_changes
+      end
+
+      # Pending typed-value changes keyed by effective Field name.
+      #
+      # The returned hash and pairs are fresh objects. Before-values are
+      # reconstructed from the stored physical cells through the Field's
+      # public logical reader, so multi-cell fields retain the same shape as
+      # `typed_eav_value` rather than exposing storage-column details.
+      def typed_eav_changes
+        values = typed_eav_pending_values
+        return {} if values.empty?
+
+        names_by_field_id = typed_eav_effective_field_names
+        changes_by_field_id = typed_eav_change_pairs(values, names_by_field_id)
+
+        changes_by_field_id.each_with_object({}) do |(field_id, pair), changes|
+          name = names_by_field_id[field_id]
+          next unless name
+          next if pair[0] == pair[1]
+
+          changes[name] = pair.map(&:deep_dup)
+        end
+      end
+
+      # Logical changes from the most recent successful host save. The value
+      # is intentionally available in host `after_save` callbacks, where the
+      # child autosave has already consumed ordinary dirty state. This is
+      # successful-save state, not evidence that an outer transaction later
+      # committed and not a replacement for ValueVersion history.
+      def saved_typed_eav_changes
+        (@typed_eav_saved_changes || {}).deep_dup
+      end
+
+      # Bracket the complete public save call, including callbacks that run
+      # after the model's create/update callbacks. An around_save callback
+      # cannot rescue an after_save callback that is compiled outside its
+      # around sequence, but these wrappers can restore the previous snapshot
+      # for both false returns and raised errors.
+      def save(...)
+        _typed_eav_track_save { super }
+      end
+
+      def save!(...)
+        _typed_eav_track_save { super }
+      end
+
+      private
+
+      # Capture from the host lifecycle before autosave runs. Because this
+      # callback was registered before the association's autosave callback,
+      # before_save mutations and marked-for-destruction Values are still
+      # observable here.
+      def _typed_eav_capture_saved_changes
+        # A record-level rollback callback can be skipped after a later
+        # failed validation; use Rails' transaction-level callback instead.
+        self.class.current_transaction.after_rollback { _typed_eav_clear_saved_changes }
+        @typed_eav_saved_changes = typed_eav_changes.deep_dup
+      end
+
+      # Keep failed saves from replacing the last successful result. A normal
+      # return of false is handled here as well as exceptions raised by save
+      # callbacks or autosave. If the failed save opened a transaction that
+      # rolled back, Active Record may have cleared the snapshot before this
+      # wrapper resumes; restoring `previous` here preserves the failed-save
+      # contract. A successful save leaves the new snapshot in place until a
+      # later outer rollback callback clears it.
+      def _typed_eav_track_save
+        previous = @typed_eav_saved_changes
+        result = yield
+
+        @typed_eav_saved_changes = previous unless result
+        result
+      rescue StandardError
+        @typed_eav_saved_changes = previous
+        raise
+      end
+
+      def _typed_eav_clear_saved_changes
+        @typed_eav_saved_changes = {}
+      end
+
+      public
+
+      # Reload replaces the host's association target. Clear the separate
+      # saved snapshot at the same boundary so it cannot outlive the state it
+      # describes.
+      def reload(...)
+        super.tap { _typed_eav_clear_saved_changes }
+      end
+
+      private
+
+      # Reading `target` is the important lazy boundary: calling the public
+      # dirty API on an untouched host never issues a typed_values SELECT.
+      # `build` adds to target without marking the association loaded, so the
+      # direct-association path is covered as well.
+      def typed_eav_pending_values
+        typed_values.target.select do |value|
+          next false if value.destroyed?
+          next false if value.new_record? && value.marked_for_destruction?
+
+          typed_eav_value_pending?(value)
+        end
+      end
+
+      def typed_eav_value_pending?(value)
+        return true if value.marked_for_destruction? && value.persisted?
+        return false unless value.changed?
+
+        field = value.field
+        return false unless field
+
+        field.class.value_columns.any? do |column|
+          value.will_save_change_to_attribute?(column)
+        end
+      end
+
+      # Resolve names only after finding a changed Value. This keeps ordinary
+      # reads and saves free of definition queries while preserving the same
+      # collision precedence used by `typed_eav_value` and `typed_eav_hash`.
+      def typed_eav_effective_field_names
+        typed_eav_defs_by_name.each_with_object({}) do |(name, field), names|
+          names[field.id] = name
+        end
+      end
+
+      def typed_eav_change_pairs(values, names_by_field_id)
+        values.each_with_object({}) do |value, changes|
+          change = typed_eav_change_for(value, names_by_field_id)
+          next unless change
+
+          field_id, pair = change
+          merge_typed_eav_change(changes, field_id, pair)
+        end
+      end
+
+      def typed_eav_change_for(value, names_by_field_id)
+        field = value.field
+        field_id = value.field_id || field&.id
+        return unless field && field_id && names_by_field_id.key?(field_id)
+
+        before = typed_eav_before_value(value, field)
+        after = value.marked_for_destruction? ? nil : field.read_value(value)
+        return if before == after
+
+        [field_id, [before, after]]
+      end
+
+      # One Value row per field is the normal shape. Keep the first non-nil
+      # before-state when a target temporarily contains both an old marked row
+      # and a replacement build; this preserves the original persisted
+      # baseline while the final target row supplies the after-state.
+      def merge_typed_eav_change(changes, field_id, pair)
+        return changes[field_id] = pair unless changes.key?(field_id)
+
+        changes[field_id][0] = pair[0] if changes[field_id][0].nil? && !pair[0].nil?
+        changes[field_id][1] = pair[1]
+      end
+
+      # Use the original stored cells as a lightweight Value snapshot and
+      # invoke the Field's logical reader. This is intentionally not a second
+      # representation of multi-cell values; Field#read_value remains the
+      # single source of truth for both current and prior values.
+      def typed_eav_before_value(value, field)
+        return nil if value.new_record?
+
+        snapshot = value.dup
+        field.class.value_columns.each do |column|
+          snapshot[column] = value.attribute_in_database(column)
+        end
+        field.read_value(snapshot)
+      end
+    end
+  end
+end

data/lib/typed_eav/has_typed_eav/instance_methods.rb

@@ -262,7 +262,7 @@ module TypedEAV
       # because each record's INSERT clears the cache — so cache-do alone
       # cannot keep field-definition reads N+1-free across the bulk loop.
       # The thread-local memo is the explicit fallback documented in plan
-      # 06-05 §T3 notes; it pre-warms once per `[host_class, scope,
+      # 06-05 §T3 notes; it pre-warms once per `[polymorphic_name, scope,
       # parent_scope]` tuple and reuses across every record in that tuple.
       #
       # Outside a bulk operation the memo is nil and we fall through to
@@ -270,7 +270,7 @@ module TypedEAV
       def typed_eav_defs_by_name
         memo = Thread.current[:typed_eav_bulk_defs_memo]
         if memo
-          key = [self.class.name, typed_eav_scope, typed_eav_parent_scope]
+          key = [self.class.polymorphic_name, typed_eav_scope, typed_eav_parent_scope]
           memo[key] ||= TypedEAV::Partition.definitions_by_name(typed_eav_definitions)
         else
           TypedEAV::Partition.definitions_by_name(typed_eav_definitions)

data/lib/typed_eav/has_typed_eav.rb

@@ -31,15 +31,18 @@ module TypedEAV
   # ## Architecture (ADR-0002, 0.3.0 refactor)
   #
   # This file holds the macro entry + macro-time guards. Per-record API
-  # lives in `TypedEAV::HasTypedEAV::InstanceMethods`. Class-level query
+  # lives in `TypedEAV::HasTypedEAV::InstanceMethods`, with pending/saved
+  # change tracking in `TypedEAV::HasTypedEAV::DirtyTracking`. Class-level query
   # orchestration lives in `TypedEAV::EntityQuery` (extended onto the host
   # class), which delegates the heavy lifting to `TypedEAV::FilterQuery`
-  # (where_typed_eav) and `TypedEAV::BulkRead` (typed_eav_hash_for).
+  # (where_typed_eav), `TypedEAV::ScalarQuery` (ordering/summaries), and
+  # `TypedEAV::BulkRead` (typed_eav_hash_for).
   # `bulk_set_typed_eav_values` continues to delegate to `TypedEAV::BulkWrite`.
   module HasTypedEAV
     extend ActiveSupport::Concern
 
     autoload :InstanceMethods, "typed_eav/has_typed_eav/instance_methods"
+    autoload :DirtyTracking, "typed_eav/has_typed_eav/dirty_tracking"
 
     class_methods do
       # Register this model as having typed fields.
@@ -82,6 +85,7 @@ module TypedEAV
                                                   default: types && types.map(&:to_s).freeze
 
         include InstanceMethods
+        include DirtyTracking
         extend TypedEAV::EntityQuery
 
         has_many :typed_values,
@@ -93,7 +97,7 @@ module TypedEAV
 
         accepts_nested_attributes_for :typed_values, allow_destroy: true
 
-        TypedEAV.registry.register(name, types: types, versioned: versioned)
+        TypedEAV.registry.register(polymorphic_name, types: types, versioned: versioned)
       end
 
       private

data/lib/typed_eav/partition/definition_batch.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Partition
+    # Internal batched resolver for field definitions visible to many exact
+    # partition tuples. It performs one definition SELECT, then applies the
+    # same global -> scope -> full-tuple precedence as `definitions_by_name`
+    # independently for every requested tuple.
+    class DefinitionBatch
+      class << self
+        def resolve(entity_type:, tuples:)
+          new(entity_type: entity_type, tuples: tuples).resolve
+        end
+      end
+
+      def initialize(entity_type:, tuples:)
+        @entity_type = entity_type
+        @tuples = tuples.uniq
+      end
+
+      def resolve
+        tuples.each { |scope, parent_scope| validate_tuple!(scope, parent_scope) }
+        return {} if tuples.empty?
+
+        definitions_by_tuple = load_definitions.group_by do |definition|
+          [definition.scope, definition.parent_scope]
+        end
+
+        tuples.to_h do |tuple|
+          visible = candidate_tuples(tuple).flat_map { |candidate| definitions_by_tuple.fetch(candidate, []) }
+          [tuple, TypedEAV::Partition.definitions_by_name(visible)]
+        end
+      end
+
+      private
+
+      attr_reader :entity_type, :tuples
+
+      def load_definitions
+        requested = tuples.map { |scope, parent_scope| { "scope" => scope, "parent_scope" => parent_scope } }
+        TypedEAV::Field::Base.where(entity_type: entity_type).where(<<~SQL.squish, requested.to_json).to_a
+          typed_eav_fields.scope IS NULL AND typed_eav_fields.parent_scope IS NULL
+          OR EXISTS (
+            SELECT 1
+            FROM jsonb_to_recordset(?::jsonb) AS requested(scope text, parent_scope text)
+            WHERE (
+              typed_eav_fields.scope IS NOT DISTINCT FROM requested.scope
+              AND typed_eav_fields.parent_scope IS NOT DISTINCT FROM requested.parent_scope
+            )
+            OR (
+              typed_eav_fields.scope IS NOT DISTINCT FROM requested.scope
+              AND typed_eav_fields.parent_scope IS NULL
+            )
+          )
+        SQL
+      end
+
+      def candidate_tuples(tuple)
+        scope, parent_scope = tuple
+        [[nil, nil], [scope, nil], [scope, parent_scope]].uniq
+      end
+
+      def validate_tuple!(scope, parent_scope)
+        return if TypedEAV::ScopeTuple.invariant_satisfied?(scope, parent_scope)
+
+        raise ArgumentError, "parent_scope cannot be set when scope is blank"
+      end
+    end
+  end
+end

data/lib/typed_eav/partition.rb

@@ -8,6 +8,8 @@ module TypedEAV
   # values. Ambient resolution (`TypedEAV.current_scope`, `with_scope`,
   # `unscoped`) stays with the adapters that know their calling context.
   module Partition
+    autoload :DefinitionBatch, "typed_eav/partition/definition_batch"
+
     # Frozen orphan-parent ArgumentError message. Kept as a module constant
     # so both `visible_fields` and `visible_sections` raise the same string
     # without re-allocating per call. The string is the wire-stable BC error

data/lib/typed_eav/scalar_query.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # SQL-backed operations over one scalar typed field.
+  #
+  # Entity-level wrappers resolve ambient/explicit scope and preserve Rails'
+  # current relation delegation. This object owns the field-definition lookup,
+  # scalar support gate, and correlated value expression so no host or Value
+  # records are hydrated merely to order a relation.
+  class ScalarQuery
+    SCALAR_COLUMNS = %i[
+      boolean_value
+      date_value
+      datetime_value
+      decimal_value
+      integer_value
+      string_value
+      text_value
+    ].freeze
+    DIRECTIONS = %i[asc desc].freeze
+    NULL_PLACEMENTS = %i[first last].freeze
+    AGGREGATE_OPERATIONS = %i[min max sum].freeze
+
+    # rubocop:disable Metrics/ParameterLists -- the query object receives the resolved public API inputs explicitly.
+    def initialize(model:, name:, scope:, parent_scope:, direction: :asc, nulls: :last)
+      @model = model
+      @name = normalize_name(name)
+      @direction = normalize_option(direction, DIRECTIONS, "direction")
+      @nulls = normalize_option(nulls, NULL_PLACEMENTS, "nulls")
+      @scope = scope
+      @parent_scope = parent_scope
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def order_relation
+      raise_all_scopes!
+
+      field = field_for_name
+      column = scalar_column_for(field)
+      relation = @model.all
+      host_table = relation.arel_table
+      value_table = TypedEAV::Value.arel_table
+      value_query = value_subquery(value_table, host_table, column, field)
+
+      relation.reorder(
+        Arel.sql("(#{value_query.to_sql}) #{@direction.to_s.upcase} NULLS #{@nulls.to_s.upcase}"),
+        host_table[@model.primary_key].asc,
+      )
+    end
+
+    def distinct_values(limit:)
+      raise_all_scopes!
+
+      field = field_for_name
+      column = scalar_column_for(field)
+      relation = value_relation(field).select(column).distinct
+      relation = relation.order(Arel.sql("#{quoted_value_column(column)} ASC NULLS LAST"))
+
+      relation.limit(validate_limit(limit)).pluck(column)
+    end
+
+    def count_distinct_values
+      raise_all_scopes!
+
+      field = field_for_name
+      column = scalar_column_for(field)
+      distinct_relation = value_relation(field).select(column).distinct
+      aliased_relation = TypedEAV::Value.from(
+        "(#{distinct_relation.to_sql}) #{quoted_table_name("typed_eav_distinct_values")}",
+      )
+
+      aliased_relation.count
+    end
+
+    def value_counts(limit:)
+      raise_all_scopes!
+
+      field = field_for_name
+      column = scalar_column_for(field)
+      count_sql = Arel.sql("COUNT(DISTINCT #{quoted_value_column(:entity_id)})")
+
+      value_relation(field)
+        .group(column)
+        .order(Arel.sql("#{quoted_value_column(column)} ASC NULLS LAST"))
+        .limit(validate_limit(limit))
+        .pluck(column, count_sql)
+        .to_h
+    end
+
+    def aggregate(operation:)
+      raise_all_scopes!
+
+      operation = normalize_option(operation, AGGREGATE_OPERATIONS, "operation")
+      field = field_for_name
+      column = numeric_column_for(field)
+      relation = value_relation(field)
+
+      case operation
+      when :min then relation.minimum(column)
+      when :max then relation.maximum(column)
+      when :sum then relation.sum(column)
+      end
+    end
+
+    private
+
+    def normalize_name(name)
+      unless name.is_a?(String) || name.is_a?(Symbol)
+        raise ArgumentError, "typed field name must be a non-empty String or Symbol"
+      end
+
+      normalized = name.to_s
+      return normalized if normalized.present?
+
+      raise ArgumentError, "typed field name must be a non-empty String or Symbol"
+    end
+
+    def normalize_option(value, allowed, label)
+      normalized = value.to_sym if value.is_a?(String) || value.is_a?(Symbol)
+      return normalized if allowed.include?(normalized)
+
+      formatted = allowed.map { |option| ":#{option}" }.join(", ")
+      raise ArgumentError, "typed field #{label} must be one of #{formatted}"
+    end
+
+    def raise_all_scopes!
+      return unless @scope.equal?(TypedEAV::EntityQuery::ALL_SCOPES)
+
+      raise ArgumentError,
+            "typed scalar queries across all partitions are ambiguous; leave `TypedEAV.unscoped` " \
+            "and select an explicit scope"
+    end
+
+    def field_for_name
+      fields = TypedEAV::Partition.visible_fields(
+        entity_type: @model.polymorphic_name,
+        scope: @scope,
+        parent_scope: @parent_scope,
+      )
+      field = TypedEAV::Partition.definitions_by_name(fields)[@name]
+      return field if field
+
+      raise ArgumentError,
+            "Unknown typed field '#{@name}' for #{@model.name}. " \
+            "Available fields: #{TypedEAV::Partition.definitions_by_name(fields).keys.join(", ")}"
+    end
+
+    def scalar_column_for(field)
+      columns = field.class.value_columns
+      if columns.length != 1 || SCALAR_COLUMNS.exclude?(columns.first)
+        raise ArgumentError,
+              "Typed field '#{field.name}' (#{field.field_type_name}) is not a supported scalar field for typed queries"
+      end
+
+      columns.first
+    rescue NotImplementedError
+      raise ArgumentError,
+            "Typed field '#{field.name}' (#{field.field_type_name}) is not a supported scalar field for typed queries"
+    end
+
+    def numeric_column_for(field)
+      unless field.is_a?(TypedEAV::Field::Integer) || field.is_a?(TypedEAV::Field::Decimal)
+        raise ArgumentError,
+              "Typed field '#{field.name}' (#{field.field_type_name}) is not a supported numeric field"
+      end
+
+      columns = field.class.value_columns
+      if columns.length != 1 || %i[decimal_value integer_value].exclude?(columns.first)
+        raise ArgumentError,
+              "Typed field '#{field.name}' (#{field.field_type_name}) is not a supported numeric field"
+      end
+
+      columns.first
+    rescue NotImplementedError
+      raise ArgumentError,
+            "Typed field '#{field.name}' (#{field.field_type_name}) is not a supported numeric field"
+    end
+
+    def value_relation(field)
+      TypedEAV::Value.where(
+        field_id: field.id,
+        entity_type: @model.polymorphic_name,
+        entity_id: host_id_relation,
+      )
+    end
+
+    def host_id_relation
+      # `all` is intentional: EntityQuery's relation delegation exposes the
+      # caller relation through the model's current scope at this boundary.
+      # rubocop:disable Rails/RedundantActiveRecordAllMethod
+      relation = @model.all.unscope(:select)
+      # rubocop:enable Rails/RedundantActiveRecordAllMethod
+      alias_name = "typed_eav_host_ids"
+      qualified_primary_key = "#{quoted_table_name(alias_name)}.#{quoted_column_name(@model.primary_key)}"
+      wrapped_sql = "(#{relation.to_sql}) #{quoted_table_name(alias_name)}"
+
+      @model.base_class.unscoped.from(wrapped_sql).select(Arel.sql(qualified_primary_key))
+    end
+
+    def quoted_value_column(column)
+      "#{quoted_table_name(TypedEAV::Value.table_name)}.#{quoted_column_name(column)}"
+    end
+
+    def quoted_table_name(table_name)
+      TypedEAV::Value.connection.quote_table_name(table_name)
+    end
+
+    def quoted_column_name(column_name)
+      TypedEAV::Value.connection.quote_column_name(column_name)
+    end
+
+    def validate_limit(limit)
+      unless limit.is_a?(Integer) && limit.positive? && limit <= 1_000
+        raise ArgumentError, "typed scalar query limit must be a positive Integer no greater than 1000"
+      end
+
+      limit
+    end
+
+    def value_subquery(value_table, host_table, column, field)
+      predicate = value_table[:field_id].eq(field.id)
+                                        .and(value_table[:entity_type].eq(@model.polymorphic_name))
+                                        .and(value_table[:entity_id].eq(host_table[@model.primary_key]))
+
+      value_table.project(value_table[column]).where(predicate)
+    end
+  end
+end