typed_eav 0.2.1 → 0.3.1

data/lib/typed_eav/field/typed_storage.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # One concern owns the entire native-typed-column storage seam.
+    #
+    # Field types declare WHICH typed column(s) hold their value via the
+    # class-level DSL (`value_column`, `value_columns`, `operators`,
+    # `operator_column`), and override three instance methods to compose
+    # multi-cell value shapes (`read_value`, `write_value`, `apply_default`).
+    # Snapshot/change-detection helpers (`value_changed?`, `before_snapshot`,
+    # `after_snapshot`) are concrete and derive from `value_columns`; they
+    # are NOT overridable — the snapshot shape is a versioning-coupled
+    # invariant.
+    #
+    # ## Class-level DSL
+    #
+    #   value_column :integer_value           # single-cell sugar; primary cell
+    #   value_columns :decimal_value, :string_value  # plural form
+    #   operators :eq, :gt, :is_null          # restrict supported operators
+    #   operator_column(:currency_eq)         # override to route ops to cells
+    #
+    # Both `value_column` and `value_columns` share the same `@value_columns`
+    # class instance variable. `value_column` returns the first element of
+    # `value_columns`, preserving the single-cell sugar shape.
+    #
+    # ## Override-point instance methods (the entire extension surface)
+    #
+    # - `read_value(record)` — compose the logical value from the cells.
+    # - `write_value(record, casted)` — unpack the casted value across cells.
+    # - `apply_default(record)` — populate cells from the field's default.
+    #
+    # The default implementations target `value_columns.first` (single-cell
+    # behavior). Multi-cell types override ALL THREE — overriding just one
+    # creates an asymmetry where reads see the multi-cell shape but writes
+    # / defaults populate only one column (or vice versa).
+    #
+    # ## Concrete (non-overridable) snapshot helpers
+    #
+    # - `value_changed?(record)` — true iff ANY value_columns column has a
+    #   saved_change_to_attribute? — used by the Value :update dispatch gate
+    #   so multi-cell types fire the event when only the second cell changed.
+    # - `before_snapshot(record, change_type)` — per-column hash keyed by
+    #   string column names. `:create` returns `{}`.
+    # - `after_snapshot(record, change_type)` — per-column hash keyed by
+    #   string column names. `:destroy` returns `{}`.
+    #
+    # Snapshot keys are stringified so query patterns like
+    # `WHERE before_value->>'integer_value' = '42'` work uniformly.
+    module TypedStorage
+      extend ActiveSupport::Concern
+
+      DEFAULT_OPERATORS_BY_COLUMN = {
+        boolean_value: %i[eq not_eq is_null is_not_null],
+        string_value: %i[eq not_eq contains not_contains starts_with ends_with is_null is_not_null],
+        text_value: %i[eq not_eq contains not_contains starts_with ends_with is_null is_not_null],
+        integer_value: %i[eq not_eq gt gteq lt lteq between is_null is_not_null],
+        decimal_value: %i[eq not_eq gt gteq lt lteq between is_null is_not_null],
+        date_value: %i[eq not_eq gt gteq lt lteq between is_null is_not_null],
+        datetime_value: %i[eq not_eq gt gteq lt lteq between is_null is_not_null],
+        json_value: %i[contains is_null is_not_null],
+      }.freeze
+      FALLBACK_OPERATORS = %i[eq not_eq is_null is_not_null].freeze
+
+      class_methods do
+        # Declare the typed column(s) this field type stores its value in.
+        #
+        # `value_column :col` — single-cell sugar; equivalent to
+        # `value_columns :col`. Returns `:col` when called without arguments.
+        # Raises NotImplementedError when called without arguments AND no
+        # column has been declared (the "subclass must declare" enforcement).
+        #
+        # Both `value_column` and `value_columns` write to the same
+        # `@value_columns` class instance variable on the declaring class
+        # (Ruby class ivars are NOT inherited, so each subclass that calls
+        # the setter installs its own). `Field::Percentage` re-declares
+        # `value_column :decimal_value` to work around this non-inheritance.
+        def value_column(column_name = nil)
+          if column_name
+            @value_columns = [column_name.to_sym]
+          else
+            cols = value_columns
+            cols.first
+          end
+        end
+
+        # Declare the typed columns this field type stores across (multi-cell
+        # form). Returns the configured Array when called without arguments.
+        # Raises NotImplementedError when no column(s) have been declared
+        # on this class — the same enforcement as `value_column`.
+        #
+        # The primary cell is `value_columns.first`; defaults for
+        # `read_value` / `write_value` / `apply_default` target it.
+        def value_columns(*cols)
+          if cols.any?
+            @value_columns = cols.map(&:to_sym)
+          else
+            @value_columns || raise(NotImplementedError,
+                                    "#{name} must declare `value_column :column_name`")
+          end
+        end
+
+        # The physical column this operator acts on. Defaults to
+        # `value_columns.first` for single-cell field types. Multi-cell
+        # types (Currency: `:currency_eq` → `:string_value`; everything
+        # else → `:decimal_value`) override this to route operators to
+        # different cells.
+        #
+        # Called by `QueryBuilder.filter` AFTER the
+        # `supported_operators.include?(operator)` validation gate, so
+        # `_operator` is always one the field explicitly supports.
+        def operator_column(_operator)
+          value_columns.first
+        end
+
+        # Operators this field type supports for querying. Defaults to the
+        # column-aware default set. Override via `.operators(*ops)`.
+        def supported_operators
+          @supported_operators || default_operators_for(value_columns.first)
+        end
+
+        def operators(*ops)
+          @supported_operators = ops.map(&:to_sym)
+        end
+
+        private
+
+        def default_operators_for(col)
+          DEFAULT_OPERATORS_BY_COLUMN.fetch(col, FALLBACK_OPERATORS)
+        end
+      end
+
+      # ── Override-point instance methods (the entire multi-cell surface) ──
+
+      # Returns the logical value for this field as stored on `value_record`.
+      # Default reads the primary cell. Override in multi-cell types to
+      # compose a hash (e.g., `Field::Currency` returns
+      # `{amount: r[:decimal_value], currency: r[:string_value]}`).
+      def read_value(value_record)
+        value_record[self.class.value_columns.first]
+      end
+
+      # Writes a casted value to `value_record`. Default writes the primary
+      # cell. Override in multi-cell types to unpack the casted value
+      # across multiple cells.
+      def write_value(value_record, casted)
+        value_record[self.class.value_columns.first] = casted
+      end
+
+      # Writes this field's configured default to `value_record`. Default
+      # writes `default_value` to the primary cell, bypassing Value#value=
+      # to avoid re-casting an already-cast default. Override in multi-cell
+      # types to populate multiple cells from a composite default.
+      def apply_default(value_record)
+        value_record[self.class.value_columns.first] = default_value
+      end
+
+      # ── Concrete snapshot helpers (NOT overridable) ──
+
+      # True iff ANY of the field's value_columns had a saved change in the
+      # just-committed save. Used by Value's :update dispatch gate so
+      # multi-cell types correctly fire the event when only the second cell
+      # changed (regression case Phase 5 D3).
+      def value_changed?(value_record)
+        self.class.value_columns.any? do |column|
+          value_record.saved_change_to_attribute?(column)
+        end
+      end
+
+      # Pre-change snapshot keyed by string column names.
+      # - :create  → {} (no before state)
+      # - :update  → {col => attribute_before_last_save(col)}
+      # - :destroy → {col => value_record[col]} (in-memory on the destroyed
+      #   AR record per Phase 03 P04 live-validation)
+      def before_snapshot(value_record, change_type)
+        case change_type.to_sym
+        when :create
+          {}
+        when :update
+          self.class.value_columns.to_h do |column|
+            [column.to_s, value_record.attribute_before_last_save(column.to_s)]
+          end
+        when :destroy
+          self.class.value_columns.to_h { |column| [column.to_s, value_record[column]] }
+        else
+          raise ArgumentError, "Unsupported change_type: #{change_type.inspect}"
+        end
+      end
+
+      # Post-change snapshot keyed by string column names.
+      # - :create / :update → {col => value_record[col]}
+      # - :destroy          → {} (no after state)
+      def after_snapshot(value_record, change_type)
+        case change_type.to_sym
+        when :create, :update
+          self.class.value_columns.to_h { |column| [column.to_s, value_record[column]] }
+        when :destroy
+          {}
+        else
+          raise ArgumentError, "Unsupported change_type: #{change_type.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/typed_eav/filter_query.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Multi-filter query orchestrator. Given a model + a list of filter hashes
+  # + an already-resolved scope tuple (or `EntityQuery::ALL_SCOPES`), composes
+  # an `ActiveRecord::Relation` by fanning out across filters and dispatching
+  # each per-filter predicate to `TypedEAV::QueryBuilder`.
+  #
+  #   FilterQuery.new(
+  #     model: Contact,
+  #     filters: [{ name: "age", op: :gt, value: 21 }],
+  #     scope: "t1",
+  #     parent_scope: nil,
+  #   ).to_relation
+  #
+  # ## Two altitudes (ADR-0002)
+  #
+  # `QueryBuilder` stays the per-field SQL primitive (knows nothing about
+  # multi-filter composition or scope collision). `FilterQuery` is the
+  # orchestrator that knows about input shape, partition lookup, collision
+  # precedence, and per-filter chaining.
+  #
+  # ## Scope shape
+  #
+  # `scope:` is either `EntityQuery::ALL_SCOPES` (atomic-bypass under
+  # `TypedEAV.unscoped { }` — the multimap branch) or a `String | nil`
+  # already-resolved scope value. `parent_scope:` is `String | nil`. Scope
+  # resolution and sentinel handling live in `EntityQuery#resolve_scope`;
+  # this class works on resolved tuples only.
+  class FilterQuery
+    FILTER_KEYS = %w[name n op operator value v].freeze
+    private_constant :FILTER_KEYS
+
+    def initialize(model:, filters:, scope:, parent_scope:)
+      @model        = model
+      @raw_filters  = filters
+      @scope        = scope
+      @parent_scope = parent_scope
+    end
+
+    def to_relation
+      filters = normalize_filters(@raw_filters)
+      defs    = lookup_definitions
+
+      if all_scopes?
+        apply_multimap_filters(filters, TypedEAV::Partition.definitions_multimap_by_name(defs))
+      else
+        apply_single_scope_filters(filters, TypedEAV::Partition.definitions_by_name(defs))
+      end
+    end
+
+    private
+
+    attr_reader :model
+
+    # ── Input normalization ─────────────────────────────────────────────
+
+    # Accepts splat args, a single Array, a single filter Hash, a hash-of-
+    # hashes (form params), or `ActionController::Parameters`. Returns an
+    # Array of plain Hashes (each a filter spec with :name/:n, :op/:operator,
+    # :value/:v keys).
+    def normalize_filters(filters)
+      flattened = filters.map { |f| coerce_to_h(f) }
+      flattened = expand_single_argument(flattened) if flattened.size == 1
+      Array(flattened)
+    end
+
+    def coerce_to_h(filter)
+      filter.respond_to?(:to_unsafe_h) ? filter.to_unsafe_h : filter
+    end
+
+    def expand_single_argument(filters)
+      inner = coerce_to_h(filters.first)
+      return inner            if inner.is_a?(Array)
+      return [inner]          unless inner.is_a?(Hash)
+      return [inner]          if filter_hash?(inner)
+
+      inner.values
+    end
+
+    def filter_hash?(hash)
+      hash.keys.any? { |k| FILTER_KEYS.include?(k.to_s) }
+    end
+
+    # ── Partition lookup ───────────────────────────────────────────────
+
+    def all_scopes?
+      @scope.equal?(TypedEAV::EntityQuery::ALL_SCOPES)
+    end
+
+    def lookup_definitions
+      if all_scopes?
+        TypedEAV::Partition.visible_fields(entity_type: model.name, mode: :all_partitions)
+      else
+        TypedEAV::Partition.visible_fields(
+          entity_type: model.name,
+          scope: @scope,
+          parent_scope: @parent_scope,
+        )
+      end
+    end
+
+    # ── Filter dispatch ────────────────────────────────────────────────
+
+    def apply_single_scope_filters(filters, fields_by_name)
+      filters.inject(model.all) do |query, filter|
+        spec  = parse_filter(filter)
+        field = fields_by_name[spec[:name]] || raise_unknown_field(spec[:name], fields_by_name.keys)
+        matching_ids = TypedEAV::QueryBuilder.entity_ids(field, spec[:operator], spec[:value])
+        query.where(id: matching_ids)
+      end
+    end
+
+    def apply_multimap_filters(filters, fields_multimap)
+      filters.inject(model.all) do |query, filter|
+        spec    = parse_filter(filter)
+        fields  = fields_multimap[spec[:name]]
+        raise_unknown_field(spec[:name], fields_multimap.keys) unless fields&.any?
+
+        union_ids = union_entity_ids(fields, spec[:operator], spec[:value])
+        query.where(id: union_ids)
+      end
+    end
+
+    # OR-across all field_ids that share the same name (across tenants),
+    # while preserving AND between filters via the chained `.where`. Use the
+    # underlying Value scope (`.filter`) and `pluck(:entity_id)` to collapse
+    # to a plain integer array we can union across tenants.
+    def union_entity_ids(fields, operator, value)
+      fields.flat_map { |f| TypedEAV::QueryBuilder.filter(f, operator, value).pluck(:entity_id) }.uniq
+    end
+
+    def parse_filter(filter)
+      h = filter.to_h.with_indifferent_access
+      {
+        name: (h[:n] || h[:name]).to_s,
+        operator: (h[:op] || h[:operator] || :eq).to_sym,
+        value: h.key?(:v) ? h[:v] : h[:value],
+      }
+    end
+
+    def raise_unknown_field(name, available)
+      raise ArgumentError,
+            "Unknown typed field '#{name}' for #{model.name}. " \
+            "Available fields: #{available.join(", ")}"
+    end
+  end
+end

data/lib/typed_eav/has_typed_eav/instance_methods.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module HasTypedEAV
+    # Per-record API mixed into host AR models by the `has_typed_eav` macro.
+    # Reads/writes typed values via field name, returns scope/parent_scope
+    # via the configured accessor methods, and builds the collision-collapsed
+    # per-instance definition map (delegating to `Partition.definitions_by_name`
+    # so the class-query path and the instance path share one source of truth).
+    module InstanceMethods
+      # The field definitions available for this record
+      def typed_eav_definitions
+        self.class.typed_eav_definitions(
+          scope: typed_eav_scope,
+          parent_scope: typed_eav_parent_scope,
+        )
+      end
+
+      # Current scope value (for multi-tenant)
+      def typed_eav_scope
+        return nil unless self.class.typed_eav_scope_method
+
+        send(self.class.typed_eav_scope_method)&.to_s
+      end
+
+      # Current parent_scope value (for two-level partitioning).
+      #
+      # Returns nil for models that did not declare `parent_scope_method:` —
+      # the method is defined unconditionally so callers (e.g. the Value-side
+      # cross-axis validator) can `respond_to?` and read uniformly without
+      # branching on `parent_scope_method` configuration. Mirrors the
+      # `&.to_s` normalization on `typed_eav_scope`.
+      def typed_eav_parent_scope
+        return nil unless self.class.typed_eav_parent_scope_method
+
+        send(self.class.typed_eav_parent_scope_method)&.to_s
+      end
+
+      # Build missing values with defaults for all available fields.
+      # Useful in forms to show all fields even when no value exists yet.
+      #
+      # Iterates the collision-collapsed view (`typed_eav_defs_by_name`)
+      # rather than the raw definitions list. Otherwise, when a record's
+      # scope partition has both a global (scope=NULL) and a same-name
+      # scoped field, `for_entity` returns BOTH rows and the form would
+      # render two inputs for the same name — but only the scoped one
+      # round-trips on save (it wins in `typed_eav_defs_by_name`).
+      def initialize_typed_values
+        existing_field_ids = typed_values.loaded? ? typed_values.map(&:field_id) : typed_values.pluck(:field_id)
+
+        typed_eav_defs_by_name.each_value do |field|
+          next if existing_field_ids.include?(field.id)
+
+          typed_values.build(field: field, value: field.default_value)
+        end
+
+        typed_values
+      end
+
+      # Bulk assign values by field NAME. Coexists with (rather than replaces)
+      # the `accepts_nested_attributes_for :typed_values` setter declared
+      # on the host model, which accepts entries keyed by field ID.
+      #
+      # The nested-attributes setter is the standard Rails form contract
+      # (forms post `field_id` as a hidden input per value row). This setter
+      # takes entries keyed by field *name* and translates them to field
+      # IDs before handing off to the nested-attributes setter. It also
+      # enforces the `types:` restriction declared on `has_typed_eav` and
+      # supports `_destroy: true` for removing a value by name.
+      #
+      #   record.typed_eav_attributes = [
+      #     { name: "age",       value: 30 },
+      #     { name: "email",     value: "test@example.com" },
+      #     { name: "old_field", _destroy: true },
+      #   ]
+      #
+      # Pick the one that fits: forms -> typed_values_attributes=, scripting
+      # -> typed_eav_attributes=. They can't both run in the same save.
+      def typed_eav_attributes=(attributes)
+        fields_by_name     = typed_eav_defs_by_name
+        values_by_field_id = typed_values.index_by(&:field_id)
+
+        nested = normalize_typed_eav_attributes(attributes).filter_map do |attrs|
+          build_or_update_typed_value(attrs, fields_by_name, values_by_field_id)
+        end
+
+        self.typed_values_attributes = nested if nested.any?
+      end
+
+      alias typed_eav= typed_eav_attributes=
+
+      # Get a specific field's value by name. Honors an already-loaded
+      # `typed_values` association so list-page callers that preloaded
+      # `typed_values: :field` don't trigger a fresh query per record.
+      #
+      # On a global+scoped name collision, prefer the value bound to the
+      # winning field_id (scoped wins). Without this guard, a stray value
+      # row attached to a shadowed global field would surface here even
+      # though writes route through the scoped winner.
+      def typed_eav_value(name)
+        winning    = typed_eav_defs_by_name[name.to_s]
+        # Skip orphans (`v.field` nil — definition deleted out from under
+        # the value via raw SQL or a missing FK cascade) so a stray row
+        # can't crash the read path with NoMethodError.
+        candidates = loaded_typed_values_with_fields.select { |v| v.field && v.field.name == name.to_s }
+        select_winning_value(candidates, winning)&.value
+      end
+
+      # Set a specific field's value by name
+      def set_typed_eav_value(name, value)
+        field = typed_eav_defs_by_name[name.to_s]
+        return unless field
+
+        existing = typed_values.detect { |v| v.field_id == field.id }
+        if existing
+          existing.value = value
+        else
+          typed_values.build(field: field, value: value)
+        end
+      end
+
+      # Hash of all field values: { "field_name" => value, ... }. Same
+      # preload semantics as `typed_eav_value` — respects already-loaded
+      # associations instead of rebuilding the relation.
+      #
+      # Collision-safe: on a global+scoped name overlap, the value attached
+      # to the winning field_id wins (scoped). Without this guard, a stray
+      # row tied to a shadowed global field could surface here even though
+      # writes route through the scoped winner.
+      def typed_eav_hash
+        winning_ids_by_name = typed_eav_defs_by_name.transform_values(&:id)
+
+        loaded_typed_values_with_fields.each_with_object({}) do |tv, hash|
+          # Skip orphans (`tv.field` nil — definition deleted out from under
+          # the value) so the hash isn't crashy when stale rows linger.
+          next unless tv.field
+
+          assign_hash_value(hash, tv, winning_ids_by_name)
+        end
+      end
+
+      private
+
+      # Selects the candidate value for `typed_eav_value`. On a collision,
+      # prefer the row attached to the winning field_id; otherwise fall back
+      # to the first orphan/non-collision candidate.
+      def select_winning_value(candidates, winning)
+        return candidates.first unless winning
+
+        candidates.detect { |v| (v.field_id || v.field&.id) == winning.id } || candidates.first
+      end
+
+      # Hash-builder helper for `typed_eav_hash`. When a winner is registered
+      # for the name, only its row may surface (scoped-beats-global). When
+      # no winner is registered (definition deleted while values remain),
+      # fall back to first-wins so the hash isn't lossy.
+      def assign_hash_value(hash, value_row, winning_ids_by_name)
+        name = value_row.field.name
+        winning_id = winning_ids_by_name[name]
+        effective_id = value_row.field_id || value_row.field&.id
+
+        if winning_id
+          hash[name] = value_row.value if effective_id == winning_id
+        else
+          hash[name] = value_row.value unless hash.key?(name)
+        end
+      end
+
+      # Normalize the input to `typed_eav_attributes=` into an Array of
+      # plain Hashes. Accepts ActionController::Parameters, hash-of-hashes
+      # (form params), Array, or any Enumerable.
+      def normalize_typed_eav_attributes(attributes)
+        attributes = attributes.to_h if attributes.respond_to?(:permitted?)
+        attributes = attributes.values if attributes.is_a?(Hash)
+        Array(attributes)
+      end
+
+      # Translate a single name-keyed attribute hash into the corresponding
+      # nested-attributes entry (id-keyed), or builds a new value row in-place.
+      # Returns nil when the field is unknown, the field type is excluded by
+      # the host's `types:` restriction, or when the new-row path already
+      # added to the association (no nested-attributes entry needed).
+      def build_or_update_typed_value(attrs, fields_by_name, values_by_field_id)
+        attrs = attrs.to_h.with_indifferent_access
+        field = fields_by_name[attrs[:name]]
+        return nil unless field
+        return nil if typed_eav_type_disallowed?(field)
+
+        existing = values_by_field_id[field.id]
+        return { id: existing&.id, _destroy: true } if destroy_flag?(attrs)
+        return { id: existing.id, value: attrs[:value] } if existing
+
+        typed_values.build(field: field, value: attrs[:value])
+        nil
+      end
+
+      def typed_eav_type_disallowed?(field)
+        allowed = self.class.allowed_typed_eav_types
+        allowed&.exclude?(field.field_type_name)
+      end
+
+      def destroy_flag?(attrs)
+        ActiveRecord::Type::Boolean.new.cast(attrs[:_destroy])
+      end
+
+      # Returns typed_values with their fields, preferring already-loaded
+      # associations. Callers on list pages should preload with
+      # `includes(typed_values: :field)`; this method keeps the happy path
+      # fast without forcing that contract.
+      def loaded_typed_values_with_fields
+        if typed_values.loaded?
+          # Don't re-query if the caller already preloaded; ensure each value's
+          # field is materialized (fall back to per-row load if the nested
+          # `:field` was not preloaded).
+          typed_values.to_a
+        else
+          typed_values.includes(:field).to_a
+        end
+      end
+
+      # Field definitions indexed by name with deterministic collision
+      # handling: when both a global (scope=NULL) and a scoped field share
+      # a name, the most-specific (scoped) definition wins. Delegates to
+      # `TypedEAV::Partition.definitions_by_name` so the class-query path
+      # and the instance path share one source of truth.
+      #
+      # ## Bulk-write memoization (Phase 06 plan 05)
+      #
+      # `bulk_set_typed_eav_values` sets `Thread.current[:typed_eav_bulk_defs_memo]`
+      # to a Hash before its records loop. We consult it here so the per-
+      # record `typed_eav_attributes=` call does NOT issue a fresh
+      # `typed_eav_definitions` SELECT per record. AR's per-block query
+      # cache (`ActiveRecord::Base.cache`) is invalidated by every write —
+      # 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,
+      # parent_scope]` tuple and reuses across every record in that tuple.
+      #
+      # Outside a bulk operation the memo is nil and we fall through to
+      # the standard read path — zero overhead.
+      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]
+          memo[key] ||= TypedEAV::Partition.definitions_by_name(typed_eav_definitions)
+        else
+          TypedEAV::Partition.definitions_by_name(typed_eav_definitions)
+        end
+      end
+    end
+  end
+end