typed_eav 0.7.0 → 0.8.0

data/lib/typed_eav/bulk_read.rb

@@ -6,58 +6,119 @@ module TypedEAV
   # `HasTypedEAV::InstanceMethods#typed_eav_hash`. N+1-free regardless of
   # record count or field count.
   #
-  # ## Pipeline (one batched definition query + one bulk value preload)
+  # `fields:` is an optional projection of field names. A nil selection keeps
+  # the all-fields behavior; a non-nil selection is normalized to unique
+  # strings, and only the selected winning definitions' values are loaded.
+  # Unknown names are ignored, as are names that are not defined for a
+  # particular record's partition tuple. An empty selection returns one empty
+  # inner hash per record without querying definitions or values.
+  #
+  # `source: :database` (the default) always reads a fresh Value graph. The
+  # explicit `source: :preloaded` mode projects only the already-loaded
+  # `typed_values` targets and their loaded `field` associations; it never
+  # falls back to an association query. Incomplete preload requirements raise
+  # `ArgumentError` before projection. The preloaded mode is therefore a
+  # snapshot of caller-owned in-memory records and can include unsaved Value
+  # assignments; it never saves or mutates those records.
+  #
+  # ## Pipeline
   #
   #   1. validate_records!    — nil -> ArgumentError; single-class invariant
   #   2. group_by_tuple       — `[typed_eav_scope, typed_eav_parent_scope]`
-  #   3. winning_ids_by_tuple — one exact-partition definition query, then
-  #                             `Partition.definitions_by_name` per tuple
-  #   4. preload_values       — single SELECT across ALL records
+  #   3. winning_ids_by_tuple — one `Partition::DefinitionBatch` query, then
+  #                             extract the winning field ids per tuple
+  #   4. load_values          — fresh `:database` SELECT across ALL records,
+  #                             restricted to selected field IDs when
+  #                             `fields:` is used; or `:preloaded` association
+  #                             targets after a strict loaded-state check
   #   5. build_result_hash    — per-record inner hash; orphan-skip + winning-id
   #                             precedence mirrored from the instance path.
   #
   # ## Query bound
   #
-  #   - 1 SELECT typed_eav_values WHERE entity_type=? AND entity_id IN (?)
-  #   - 1 SELECT typed_eav_fields WHERE id IN (?)           (via includes)
-  #   - 1 SELECT typed_eav_fields for the union of requested partitions
-  #
-  # Total: 3 queries — independent of record count and partition cardinality.
+  # Database mode performs up to three SELECTs — one bulk Value query, one
+  # field-association query for those values, and one definition query for the
+  # union of requested partitions. The preloaded mode performs one fresh
+  # definition SELECT and reads Value/field association targets in memory;
+  # `fields: []` bypasses even that definition query. Both bounds are
+  # independent of record count and partition cardinality.
   #
   # ## Single-class invariant
   #
-  # The polymorphic value query (`entity_type: host_class.name`) targets ONE
-  # class; mixed-class input would silently miss rows of the other class. STI
-  # subclasses pass via `records.all?(host_class)`.
+  # The polymorphic value query targets the host's canonical Rails
+  # `polymorphic_name`, so an STI subclass reads rows stored for its base
+  # class. Mixed, unrelated input would still be invalid; STI subclasses pass
+  # via `records.all?(host_class)`.
   class BulkRead
-    def initialize(host_class:, records:)
+    def initialize(host_class:, records:, fields: nil, source: :database)
       @host_class = host_class
       @records    = records
+      @fields     = fields
+      @source     = source
     end
 
     def to_hash
+      validate_source!
+
       records = coerce_records
       return {} if records.empty?
 
       validate_record_classes!(records)
 
-      tuples_by_record = group_by_tuple(records)
-      winning_ids_by_tuple = winning_ids_by_tuple(tuples_by_record.values.uniq)
-      values_by_record_id = preload_values(records)
+      selected_names = normalize_fields
+      return empty_results(records) if selected_names == []
 
-      build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id)
+      tuples_by_record = group_by_tuple(records)
+      winning_ids_by_tuple = winning_ids_by_tuple(tuples_by_record.values.uniq, selected_names)
+      values_by_record_id = if @source == :preloaded
+                              preloaded_values(records, tuples_by_record, winning_ids_by_tuple, selected_names)
+                            else
+                              preload_values(records, winning_ids_by_tuple, selected_names)
+                            end
+
+      build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id, selected_names)
     end
 
     private
 
     attr_reader :host_class
 
+    def validate_source!
+      return if %i[database preloaded].include?(@source)
+
+      raise ArgumentError, "typed_eav_hash_for source must be :database or :preloaded"
+    end
+
+    def normalize_fields
+      return nil if @fields.nil?
+
+      names = if @fields.is_a?(String) || @fields.is_a?(Symbol)
+                [@fields]
+              elsif @fields.respond_to?(:to_a)
+                @fields.to_a
+              else
+                raise ArgumentError, "typed_eav_hash_for fields must be an Enumerable of String/Symbol names"
+              end
+
+      names.map do |name|
+        next name if name.is_a?(String)
+        next name.to_s if name.is_a?(Symbol)
+
+        raise ArgumentError,
+              "typed_eav_hash_for fields must contain only String or Symbol names; got #{name.inspect}"
+      end.uniq
+    end
+
     def coerce_records
       raise ArgumentError, "typed_eav_hash_for requires an Enumerable of records, got nil" if @records.nil?
 
       @records.to_a
     end
 
+    def empty_results(records)
+      records.to_h { |record| [record.id, {}] }
+    end
+
     def validate_record_classes!(records)
       return if records.all?(host_class)
 
@@ -72,60 +133,82 @@ module TypedEAV
       records.index_with { |r| [r.typed_eav_scope, r.typed_eav_parent_scope] }
     end
 
-    def winning_ids_by_tuple(tuples)
-      definitions_by_tuple = batched_definitions(tuples).group_by do |definition|
-        [definition.scope, definition.parent_scope]
-      end
+    def winning_ids_by_tuple(tuples, selected_names)
+      TypedEAV::Partition::DefinitionBatch
+        .resolve(entity_type: host_class.polymorphic_name, tuples: tuples)
+        .transform_values do |fields_by_name|
+          fields_by_name.each_with_object({}) do |(name, field), winners|
+            next if selected_names&.exclude?(name)
 
-      tuples.to_h do |tuple|
-        s, ps = tuple
-        candidate_tuples = [[nil, nil], [s, nil], [s, ps]].uniq
-        visible = candidate_tuples.flat_map { |candidate| definitions_by_tuple.fetch(candidate, []) }
-        [tuple, TypedEAV::Partition.definitions_by_name(visible).transform_values(&:id)]
-      end
+            winners[name] = field.id
+          end
+        end
     end
 
-    def batched_definitions(tuples)
-      tuples.each { |scope, parent_scope| validate_tuple!(scope, parent_scope) }
-      relation = TypedEAV::Field::Base.where(entity_type: host_class.name)
-      requested = tuples.map { |scope, parent_scope| { "scope" => scope, "parent_scope" => parent_scope } }
-      relation.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
+    def preload_values(records, winning_ids_by_tuple, selected_names)
+      relation = TypedEAV::Value
+                 .includes(:field)
+                 .where(entity_type: host_class.polymorphic_name, entity_id: records.map(&:id))
+
+      if selected_names
+        field_ids = winning_ids_by_tuple.values.flat_map(&:values).uniq
+        return {} if field_ids.empty?
+
+        relation = relation.where(field_id: field_ids)
+      end
+
+      rows = relation.to_a
+      rows.group_by(&:entity_id)
     end
 
-    def validate_tuple!(scope, parent_scope)
-      return if TypedEAV::ScopeTuple.invariant_satisfied?(scope, parent_scope)
+    # Reuse a caller's fully-preloaded association graph without allowing an
+    # accidental association reader to issue an N+1 query. `target` is used
+    # deliberately: unlike `record.typed_values`, it never loads an unloaded
+    # association. For a selected projection, filter each target by the
+    # winning field IDs before checking field associations; unselected Values
+    # therefore need not have their `field` association loaded. The all-fields
+    # path retains the stricter check over every Value, including orphan rows
+    # whose loaded field target is nil.
+    def preloaded_values(records, tuples_by_record, winning_ids_by_tuple, selected_names)
+      unloaded_records = records.reject { |record| record.association(:typed_values).loaded? }
+      if unloaded_records.any?
+        raise ArgumentError,
+              "typed_eav_hash_for source: :preloaded requires the typed_values association " \
+              "to be preloaded for every record"
+      end
 
-      raise ArgumentError, "parent_scope cannot be set when scope is blank"
+      records.to_h do |record|
+        values = record.association(:typed_values).target
+        if selected_names
+          tuple = tuples_by_record.fetch(record)
+          selected_ids = winning_ids_by_tuple.fetch(tuple, {}).values
+          values = values.select { |value| selected_ids.include?(effective_field_id(value)) }
+        end
+
+        unloaded_values = values.reject { |value| value.association(:field).loaded? }
+        if unloaded_values.any?
+          raise ArgumentError,
+                "typed_eav_hash_for source: :preloaded requires the field association " \
+                "to be preloaded for every typed value"
+        end
+
+        [record.id, values]
+      end
     end
 
-    def preload_values(records)
-      rows = TypedEAV::Value
-             .includes(:field)
-             .where(entity_type: host_class.name, entity_id: records.map(&:id))
-             .to_a
-      rows.group_by(&:entity_id)
+    def effective_field_id(value)
+      return value.field_id if value.field_id
+
+      association = value.association(:field)
+      association.loaded? ? association.target&.id : nil
     end
 
-    def build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id)
+    def build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id, selected_names)
       records.each_with_object({}) do |record, result|
         tuple_key            = tuples_by_record[record]
         winning_ids_by_name  = winning_ids_by_tuple.fetch(tuple_key, {})
         rows                 = values_by_record_id.fetch(record.id, [])
-        result[record.id]    = inner_hash_for(rows, winning_ids_by_name)
+        result[record.id]    = inner_hash_for(rows, winning_ids_by_name, selected_names)
       end
     end
 
@@ -136,12 +219,17 @@ module TypedEAV
     # for the name, only its row may surface (scoped-beats-global collision
     # precedence). When no winner is registered (definition deleted while
     # values remain), fall back to first-wins so the hash isn't lossy.
-    def inner_hash_for(value_rows, winning_ids_by_name)
+    def inner_hash_for(value_rows, winning_ids_by_name, selected_names)
       value_rows.each_with_object({}) do |tv, inner|
         next unless tv.field
 
         name = tv.field.name
         winning_id = winning_ids_by_name[name]
+        # A selected field ID may be visible for another record's partition
+        # tuple because the value preload spans all requested records. In a
+        # projection, a name without a winner for this tuple is absent rather
+        # than eligible for the all-fields stale-row fallback below.
+        next if selected_names && !winning_id
         next assign_with_precedence(inner, name, tv, winning_id) if winning_id
 
         inner[name] = tv.value unless inner.key?(name)

data/lib/typed_eav/bulk_upsert.rb

@@ -8,7 +8,8 @@ module TypedEAV
   # persistence callbacks, versioning, or per-record error isolation. Callers must
   # acknowledge those semantics explicitly. It pre-casts and validates every
   # row in a transaction unit before issuing one upsert batch on the host
-  # model's connection. Scope resolution and field casting remain authoritative.
+  # model's connection. Field definitions for every tuple in that unit resolve
+  # in one batch; scope precedence and field casting remain authoritative.
   module BulkUpsert
     TYPE_COLUMNS = %i[
       string_value text_value boolean_value integer_value decimal_value date_value datetime_value json_value
@@ -36,19 +37,14 @@ module TypedEAV
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- tuple grouping, validation, and row construction are one durability unit.
       def write_unit(host_class, records, values_by_field_name)
         tuples = records.map { |record| [record.typed_eav_scope, record.typed_eav_parent_scope] }.uniq
-        fields_by_tuple = tuples.to_h do |tuple|
-          # Use the exact tuple at the partition layer. EntityQuery treats
-          # explicit scope kwargs as ALL_SCOPES inside TypedEAV.unscoped;
-          # that administrative bypass must not cross-contaminate tenants.
-          fields = TypedEAV::Partition.definitions_by_name(
-            TypedEAV::Partition.visible_fields(
-              entity_type: host_class.polymorphic_name,
-              scope: tuple[0],
-              parent_scope: tuple[1],
-            ),
-          )
-          [tuple, fields]
-        end
+        # Resolve every exact tuple in this transaction unit with one query.
+        # The shared resolver preserves global/scope/full-tuple precedence per
+        # tuple and never observes EntityQuery's administrative ALL_SCOPES
+        # bypass, so tenants remain isolated inside an unscoped block.
+        fields_by_tuple = TypedEAV::Partition::DefinitionBatch.resolve(
+          entity_type: host_class.polymorphic_name,
+          tuples: tuples,
+        )
         rows = records.flat_map do |record|
           fields = fields_by_tuple.fetch([record.typed_eav_scope, record.typed_eav_parent_scope])
           values_by_field_name.filter_map do |name, raw|

data/lib/typed_eav/entity_query.rb

@@ -94,6 +94,139 @@ module TypedEAV
     end
     # rubocop:enable Metrics/ParameterLists
 
+    # Order this host relation by a scalar typed field in SQL.
+    #
+    #   Contact.order_typed_eav("score")
+    #   Contact.where(active: true).order_typed_eav("score", direction: :desc)
+    #
+    # `direction:` accepts :asc or :desc. `nulls:` accepts :first or :last
+    # and defaults to :last for both directions. Missing value rows and rows
+    # whose selected typed cell is explicitly NULL are both SQL NULLs and
+    # therefore share the requested placement. Equal values are ordered by
+    # the host primary key ascending so pagination has a stable tie-break.
+    #
+    # The method keeps the caller's current relation scope (including normal
+    # Active Record filters, limits, and offsets) through Rails relation
+    # delegation. Typed ordering has explicit precedence and replaces any
+    # prior host ordering while retaining those filters and pagination.
+    #
+    # Scope kwargs choose the visible field definition and follow the same
+    # ambient/explicit/nil resolution as `where_typed_eav`; they do not add a
+    # host tenant predicate. Applications should keep host filtering in the
+    # caller relation. `TypedEAV.unscoped` is rejected because ordering across
+    # multiple same-name partition definitions is ambiguous; use an explicit
+    # scope when one field definition must win.
+    #
+    # Only single-cell scalar fields backed by the native scalar columns are
+    # supported. Collection and multi-cell fields raise ArgumentError rather
+    # than silently choosing one physical cell.
+    # rubocop:disable Metrics/ParameterLists -- mirrors the existing query wrappers' public partition kwargs.
+    def order_typed_eav(name, direction: :asc, nulls: :last, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      resolved = resolve_scope(scope, parent_scope)
+      effective_scope, effective_parent = scope_pair(resolved)
+
+      TypedEAV::ScalarQuery.new(
+        model: self,
+        name: name,
+        direction: direction,
+        nulls: nulls,
+        scope: effective_scope,
+        parent_scope: effective_parent,
+      ).order_relation
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Return distinct values for a scalar typed field without hydrating host
+    # or Value records. Values are ordered by the native database column and
+    # limited before they are transferred to Ruby; an explicit NULL is
+    # returned as `nil`, while hosts with no value row are absent.
+    #
+    # `scope:` and `parent_scope:` choose the visible field definition with
+    # the same ambient/explicit/nil semantics as `where_typed_eav`. They do
+    # not add host predicates; keep tenant or other host filtering in the
+    # caller relation. The current relation's filters, limit, and offset are
+    # applied through a host-ID subquery.
+    # rubocop:disable Metrics/ParameterLists -- mirrors the existing query wrappers' public partition kwargs.
+    def distinct_typed_eav_values(name, limit: 100, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      resolved = resolve_scope(scope, parent_scope)
+      effective_scope, effective_parent = scope_pair(resolved)
+
+      TypedEAV::ScalarQuery.new(
+        model: self,
+        name: name,
+        scope: effective_scope,
+        parent_scope: effective_parent,
+      ).distinct_values(limit: limit)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Count exact distinct values for a scalar typed field. The count is
+    # calculated in SQL, including one explicit-NULL category as `nil`; hosts
+    # without a value row remain absent. Caller relation filters and
+    # pagination are applied through the same host-ID subquery as the bounded
+    # distinct-value API.
+    # rubocop:disable Metrics/ParameterLists -- mirrors the existing query wrappers' public partition kwargs.
+    def count_distinct_typed_eav_values(name, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      resolved = resolve_scope(scope, parent_scope)
+      effective_scope, effective_parent = scope_pair(resolved)
+
+      TypedEAV::ScalarQuery.new(
+        model: self,
+        name: name,
+        scope: effective_scope,
+        parent_scope: effective_parent,
+      ).count_distinct_values
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Return an insertion-ordered `{ value => host_count }` hash for a scalar
+    # typed field. Values are grouped and counted in SQL using distinct host
+    # identities; explicit NULL is represented by a `nil` key and hosts with
+    # no value row are omitted. The result is ordered by the native value
+    # column with NULL last and capped by `limit:` before transfer to Ruby.
+    #
+    # The caller relation's filters, joins, distinctness, limit, and offset
+    # determine the host-ID subquery. Scope kwargs only choose the visible
+    # field definition and do not add host predicates.
+    # rubocop:disable Metrics/ParameterLists -- mirrors the existing query wrappers' public partition kwargs.
+    def typed_eav_value_counts(name, limit: 100, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      resolved = resolve_scope(scope, parent_scope)
+      effective_scope, effective_parent = scope_pair(resolved)
+
+      TypedEAV::ScalarQuery.new(
+        model: self,
+        name: name,
+        scope: effective_scope,
+        parent_scope: effective_parent,
+      ).value_counts(limit: limit)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Compute a database-backed numeric aggregate for a typed field.
+    # `operation:` is required and accepts :min, :max, or :sum. Integer fields return
+    # Integer results; Decimal and Percentage fields return BigDecimal
+    # results. Missing rows and explicit NULL cells are ignored. Empty
+    # min/max queries return nil, while empty sums return the typed zero.
+    #
+    # The caller relation's filters, joins, distinctness, limit, and offset
+    # are preserved through a host-ID subquery. Scope kwargs choose the
+    # visible definition and do not add host predicates. Only Integer,
+    # Decimal, and Percentage field families are supported; references,
+    # text, collections, and multi-cell fields raise ArgumentError.
+    # rubocop:disable Metrics/ParameterLists -- mirrors the existing query wrappers' public partition kwargs.
+    def aggregate_typed_eav(name, operation:, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      resolved = resolve_scope(scope, parent_scope)
+      effective_scope, effective_parent = scope_pair(resolved)
+
+      TypedEAV::ScalarQuery.new(
+        model: self,
+        name: name,
+        scope: effective_scope,
+        parent_scope: effective_parent,
+      ).aggregate(operation: operation)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
     # Returns field definitions for this entity type.
     #
     # `scope:` and `parent_scope:` behavior:
@@ -103,10 +236,10 @@ module TypedEAV
     def typed_eav_definitions(scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
       resolved = resolve_scope(scope, parent_scope)
       if resolved.equal?(ALL_SCOPES)
-        TypedEAV::Partition.visible_fields(entity_type: name, mode: :all_partitions)
+        TypedEAV::Partition.visible_fields(entity_type: polymorphic_name, mode: :all_partitions)
       else
         s, ps = resolved
-        TypedEAV::Partition.visible_fields(entity_type: name, scope: s, parent_scope: ps)
+        TypedEAV::Partition.visible_fields(entity_type: polymorphic_name, scope: s, parent_scope: ps)
       end
     end
 
@@ -115,8 +248,27 @@ module TypedEAV
     # `HasTypedEAV::InstanceMethods#typed_eav_hash`. N+1-free regardless of
     # record count or field count. See `TypedEAV::BulkRead` for the pipeline
     # and query bound.
-    def typed_eav_hash_for(records)
-      TypedEAV::BulkRead.new(host_class: self, records: records).to_hash
+    #
+    # `fields:` optionally limits the projection to selected String/Symbol
+    # names. Names are normalized to strings and de-duplicated; unknown names
+    # and names absent from a record's partition are ignored. Omitting
+    # `fields:` preserves the existing all-fields behavior. Passing `[]`
+    # returns one empty inner hash per supplied record without querying field
+    # definitions or values.
+    #
+    # `source: :database` (default) performs a fresh batched read even when
+    # the records already have typed values loaded. `source: :preloaded` is an
+    # explicit snapshot mode: `typed_values` and every retained value's
+    # `field` association must already be loaded, otherwise `ArgumentError` is
+    # raised instead of introducing an N+1 query. It reuses unsaved in-memory
+    # values and never saves or mutates caller records.
+    def typed_eav_hash_for(records, fields: nil, source: :database)
+      TypedEAV::BulkRead.new(
+        host_class: self,
+        records: records,
+        fields: fields,
+        source: source,
+      ).to_hash
     end
 
     # Bulk write API. Sets the same `values_by_field_name` Hash on every

data/lib/typed_eav/filter_query.rb

@@ -106,10 +106,10 @@ module TypedEAV
 
     def lookup_definitions
       if all_scopes?
-        TypedEAV::Partition.visible_fields(entity_type: model.name, mode: :all_partitions)
+        TypedEAV::Partition.visible_fields(entity_type: model.polymorphic_name, mode: :all_partitions)
       else
         TypedEAV::Partition.visible_fields(
-          entity_type: model.name,
+          entity_type: model.polymorphic_name,
           scope: @scope,
           parent_scope: @parent_scope,
         )