typed_eav 0.1.0 → 0.2.0

data/lib/typed_eav/partition.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Partition-aware visibility for schema objects keyed by the canonical
+  # `(entity_type, scope, parent_scope)` tuple.
+  #
+  # This module is deliberately explicit: callers pass already-resolved scope
+  # values. Ambient resolution (`TypedEAV.current_scope`, `with_scope`,
+  # `unscoped`) stays with the adapters that know their calling context.
+  module Partition
+    class << self
+      # All field definitions visible from a tuple: pure global rows,
+      # scope-only rows, and full-tuple rows. Passing mode: :all_partitions is
+      # the deliberate admin bypass; it is distinct from `scope: nil`, which
+      # means the global partition only.
+      def visible_fields(entity_type:, scope: nil, parent_scope: nil, mode: :partition)
+        validate_mode!(mode)
+        return TypedEAV::Field::Base.where(entity_type: entity_type) if mode == :all_partitions
+
+        validate_tuple!(scope, parent_scope)
+        TypedEAV::Field::Base.for_entity(entity_type, scope: scope, parent_scope: parent_scope)
+      end
+
+      # One visible field per name after collision resolution. Most-specific
+      # wins: full tuple beats scope-only, scope-only beats global.
+      def effective_fields_by_name(entity_type:, scope: nil, parent_scope: nil, mode: :partition)
+        fields = visible_fields(entity_type: entity_type, scope: scope, parent_scope: parent_scope, mode: mode)
+        if mode == :all_partitions
+          TypedEAV::HasTypedEAV.definitions_multimap_by_name(fields)
+        else
+          TypedEAV::HasTypedEAV.definitions_by_name(fields)
+        end
+      end
+
+      # All sections visible from the same tuple as field definitions.
+      def visible_sections(entity_type:, scope: nil, parent_scope: nil, mode: :partition)
+        validate_mode!(mode)
+        return TypedEAV::Section.where(entity_type: entity_type) if mode == :all_partitions
+
+        validate_tuple!(scope, parent_scope)
+        TypedEAV::Section.for_entity(entity_type, scope: scope, parent_scope: parent_scope)
+      end
+
+      def find_visible_section!(id, entity_type:, scope: nil, parent_scope: nil, mode: :partition)
+        visible_sections(entity_type: entity_type, scope: scope, parent_scope: parent_scope, mode: mode).find(id)
+      end
+
+      private
+
+      def validate_mode!(mode)
+        return if %i[partition all_partitions].include?(mode)
+
+        raise ArgumentError, "Unknown partition mode: #{mode.inspect}. Expected :partition or :all_partitions."
+      end
+
+      def validate_tuple!(scope, parent_scope)
+        return if parent_scope.blank?
+        return if scope.present?
+
+        raise ArgumentError, "parent_scope cannot be set when scope is blank"
+      end
+    end
+  end
+end

data/lib/typed_eav/query_builder.rb

@@ -30,10 +30,13 @@ module TypedEAV
       #   Model.where(id: QueryBuilder.filter(field, :gt, 5).select(:entity_id))
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength -- one operator-dispatch case statement; flattening keeps the supported-operators list scannable in one place.
       def filter(field, operator, value)
-        col = field.class.value_column
         operator = operator.to_sym
 
-        # Validate operator is supported by this field type
+        # Validate operator is supported by this field type. The gate runs
+        # BEFORE column resolution so an unsupported operator raises a
+        # descriptive ArgumentError instead of silently dispatching to
+        # `operator_column`'s default (which would point at the wrong
+        # column for multi-cell types).
         supported = field.class.supported_operators
         unless supported.include?(operator)
           raise ArgumentError,
@@ -41,15 +44,48 @@ module TypedEAV
                 "Supported operators: #{supported.map { |o| ":#{o}" }.join(", ")}"
         end
 
+        # Phase 05: route the operator to its physical column via field-side
+        # dispatch. Single-cell types (every built-in as of Phase 04) return
+        # `value_column` for every operator — BC-safe. Multi-cell types
+        # (Phase 05 Currency) route operators like `:eq` (amount) and
+        # `:currency_eq` (currency code) to different columns. See
+        # ColumnMapping#operator_column.
+        col = field.storage_contract.query_column(operator)
         arel_col = values_table[col]
 
         base = value_scope(field)
 
         case operator
-        when :eq
+        when :eq, :currency_eq
+          # :currency_eq (Phase 5 Currency) is semantically equality on the
+          # routed column — Currency's operator_column override has already
+          # routed `col` to :string_value, so reusing the eq_predicate is
+          # the canonical implementation. Without this branch, the case
+          # falls through to the `else` raise even though the column
+          # dispatch resolved correctly. The operator-validation gate at
+          # the top of #filter still narrows :currency_eq to Field::Currency
+          # only — no other field type accepts it.
           eq_predicate(base, arel_col, col, value)
         when :not_eq
           not_eq_predicate(base, arel_col, col, value)
+        when :references
+          # Phase 5 Reference field. `value` may be an Integer FK OR an
+          # AR record instance — `field.cast` normalizes both to an
+          # integer FK (a class-mismatched record marks the cast invalid
+          # via the second tuple element). Empty-relation semantics on
+          # invalid cast: returning `base.where(col => nil)` would
+          # collapse to :is_null which has different semantics ("rows
+          # without an FK at all" rather than "rows referencing this
+          # missing target"); `base.none` is the unambiguous "no match".
+          # The :references operator is registered ONLY on Field::Reference
+          # (the operator-validation gate above keeps it from leaking to
+          # other types).
+          fk, invalid = field.cast(value)
+          if invalid || fk.nil?
+            base.none
+          else
+            base.where(arel_col.eq(fk))
+          end
         when :gt
           base.where(arel_col.gt(value))
         when :gteq

data/lib/typed_eav/registry.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "active_support/configurable"
-
 module TypedEAV
   # Registry of entity types (host ActiveRecord models) that have opted
   # into typed fields via `has_typed_eav`. Tracks optional field-type
@@ -10,15 +8,38 @@ module TypedEAV
   # Populated automatically when a host model calls `has_typed_eav`;
   # read by Field::Base#validate_type_allowed_for_entity to enforce
   # restrictions on field creation.
+  #
+  # Implementation note: see Config for why the class-level accessor is
+  # hand-rolled rather than provided by ActiveSupport::Configurable.
   class Registry
-    include ActiveSupport::Configurable
-
-    config_accessor(:entities) { {} }
-
     class << self
-      # Register an entity type with optional type restrictions.
-      def register(entity_type, types: nil)
-        entities[entity_type] = { types: types }
+      # Mutable registry of entity_type => {types: [...]} entries. Lazy-init
+      # so first access seeds an empty Hash; reset! clears in place so the
+      # same Hash object is preserved across resets (callers that captured
+      # a reference don't end up with a stale snapshot).
+      def entities
+        @entities ||= {}
+      end
+      attr_writer :entities
+
+      # Register an entity type with optional type restrictions and optional
+      # versioning opt-in.
+      #
+      # `versioned:` is the per-entity Phase 04 opt-in flag. When true, AND
+      # `Config.versioning = true` at engine load (gem-level master switch),
+      # the Phase 04 subscriber writes a TypedEAV::ValueVersion row per
+      # Value mutation on this entity_type. Default false — apps not using
+      # versioning pay zero cost (one Hash#dig per write at most when
+      # `Config.versioning = true`, nothing when off).
+      #
+      # Backward compat: existing callers `register(name, types: types)`
+      # continue to work — the new kwarg defaults to false. The entry hash
+      # shape changes from `{ types: types }` to `{ types: types, versioned:
+      # versioned }`, but consumers (Registry.allowed_types_for,
+      # Registry.type_allowed?) only read the `:types` key, so they're
+      # unaffected.
+      def register(entity_type, types: nil, versioned: false)
+        entities[entity_type] = { types: types, versioned: versioned }
       end
 
       # All registered entity type names.
@@ -43,6 +64,24 @@ module TypedEAV
         allowed.include?(type_name)
       end
 
+      # Whether the entity type opted into Phase 04 versioning.
+      #
+      # Returns the stored boolean for opted-in entities; false for
+      # unregistered entities (defensive — callers might query before
+      # `has_typed_eav` runs in a particular load order). The Phase 04
+      # subscriber calls this on every Value write when `Config.versioning =
+      # true` — performance is one Hash#dig per write, negligible.
+      #
+      # `entities.dig(entity_type, :versioned)` returns nil when
+      # `entities[entity_type]` is missing (no register call) OR when the
+      # entry is `{ types: ..., versioned: nil }` (impossible by current
+      # register contract — kwarg default is false). The `|| false`
+      # normalizes to a strict boolean so callers can `if versioned?(...)`
+      # without three-way logic.
+      def versioned?(entity_type)
+        entities.dig(entity_type, :versioned) || false
+      end
+
       # Clear all registrations (test isolation).
       def reset!
         entities.clear

data/lib/typed_eav/schema_portability.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Export and import field + section definitions for an exact partition
+  # tuple. Value rows are intentionally out of scope.
+  module SchemaPortability
+    class << self
+      def export_schema(entity_type:, scope: nil, parent_scope: nil)
+        fields = TypedEAV::Field::Base
+                 .where(entity_type: entity_type, scope: scope, parent_scope: parent_scope)
+                 .includes(:field_options)
+                 .order(:sort_order)
+                 .map { |field| export_field_entry(field) }
+
+        sections = TypedEAV::Section
+                   .where(entity_type: entity_type, scope: scope, parent_scope: parent_scope)
+                   .order(:sort_order)
+                   .map { |section| export_section_entry(section) }
+
+        {
+          "schema_version" => 1,
+          "entity_type" => entity_type,
+          "scope" => scope,
+          "parent_scope" => parent_scope,
+          "fields" => fields,
+          "sections" => sections,
+        }
+      end
+
+      def import_schema(hash, on_conflict: :error)
+        validate_schema_version!(hash)
+        validate_conflict_policy!(on_conflict)
+
+        result = { "created" => 0, "updated" => 0, "skipped" => 0, "unchanged" => 0, "errors" => [] }
+
+        TypedEAV::Field::Base.transaction do
+          Array(hash["fields"]).each do |entry|
+            import_field_entry(entry, on_conflict, result)
+          end
+
+          Array(hash["sections"]).each do |entry|
+            import_section_entry(entry, on_conflict, result)
+          end
+        end
+
+        result
+      end
+
+      private
+
+      # rubocop:disable Metrics/AbcSize -- flat projection is the canonical field export shape.
+      def export_field_entry(field)
+        entry = {
+          "name" => field.name,
+          "type" => field.type,
+          "entity_type" => field.entity_type,
+          "scope" => field.scope,
+          "parent_scope" => field.parent_scope,
+          "required" => field.required,
+          "sort_order" => field.sort_order,
+          "field_dependent" => field.field_dependent,
+          "options" => field.options,
+          "default_value_meta" => field.default_value_meta,
+        }
+
+        if field.optionable?
+          options_rows = if field.field_options.loaded?
+                           field.field_options.sort_by do |option|
+                             [option.sort_order || 0, option.label.to_s, option.id]
+                           end
+                         else
+                           field.field_options.sorted
+                         end
+          entry["options_data"] = options_rows.map do |option|
+            { "label" => option.label, "value" => option.value, "sort_order" => option.sort_order }
+          end
+        end
+
+        entry
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def export_section_entry(section)
+        {
+          "name" => section.name,
+          "code" => section.code,
+          "entity_type" => section.entity_type,
+          "scope" => section.scope,
+          "parent_scope" => section.parent_scope,
+          "sort_order" => section.sort_order,
+          "active" => section.active,
+        }
+      end
+
+      def validate_schema_version!(hash)
+        return if hash["schema_version"] == 1
+
+        raise ArgumentError,
+              "Unsupported schema_version: #{hash["schema_version"].inspect}. " \
+              "Expected 1. Re-export from a current typed_eav version."
+      end
+
+      def validate_conflict_policy!(on_conflict)
+        valid_policies = %i[error skip overwrite]
+        return if valid_policies.include?(on_conflict)
+
+        raise ArgumentError,
+              "Unsupported on_conflict: #{on_conflict.inspect}. " \
+              "Supported: #{valid_policies.map { |policy| ":#{policy}" }.join(", ")}."
+      end
+
+      def import_field_entry(entry, on_conflict, result)
+        existing = TypedEAV::Field::Base.find_by(
+          name: entry["name"],
+          entity_type: entry["entity_type"],
+          scope: entry["scope"],
+          parent_scope: entry["parent_scope"],
+        )
+
+        if existing
+          reject_type_swap!(existing, entry)
+
+          if field_export_row_equal?(existing, entry)
+            result["unchanged"] += 1
+            return
+          end
+
+          case on_conflict
+          when :error
+            raise_divergent_field!(entry)
+          when :skip
+            result["skipped"] += 1
+          when :overwrite
+            overwrite_field!(existing, entry)
+            result["updated"] += 1
+          end
+        else
+          create_field!(entry)
+          result["created"] += 1
+        end
+      end
+
+      def reject_type_swap!(existing, entry)
+        return if existing.type == entry["type"]
+
+        raise ArgumentError,
+              "Cannot change field '#{entry["name"]}' from #{existing.type} to #{entry["type"]}: " \
+              "data-loss guard. The gem cannot infer a safe migration of existing typed values " \
+              "across *_value columns. Manually destroy and recreate the field if the type change " \
+              "is intentional."
+      end
+
+      def raise_divergent_field!(entry)
+        raise ArgumentError,
+              "Field '#{entry["name"]}' already exists for #{entry["entity_type"]} " \
+              "(scope=#{entry["scope"].inspect}, parent_scope=#{entry["parent_scope"].inspect}) " \
+              "and its attributes diverge from the incoming schema. " \
+              "Pass on_conflict: :skip or :overwrite to import over the existing field, " \
+              "or re-export from the source environment to confirm the divergence is intentional."
+      end
+
+      def overwrite_field!(existing, entry)
+        existing.assign_attributes(
+          required: entry["required"],
+          sort_order: entry["sort_order"],
+          field_dependent: entry["field_dependent"],
+          options: entry["options"],
+        )
+        existing.default_value_meta = entry["default_value_meta"]
+        existing.save!
+
+        return unless existing.optionable?
+
+        existing.field_options.destroy_all
+        Array(entry["options_data"]).each do |option|
+          existing.field_options.create!(
+            label: option["label"],
+            value: option["value"],
+            sort_order: option["sort_order"],
+          )
+        end
+      end
+
+      def create_field!(entry)
+        field = TypedEAV::Field::Base.create!(entry.except("options_data"))
+        return unless field.optionable?
+
+        Array(entry["options_data"]).each do |option|
+          field.field_options.create!(
+            label: option["label"],
+            value: option["value"],
+            sort_order: option["sort_order"],
+          )
+        end
+      end
+
+      # rubocop:disable Metrics/MethodLength -- mirrors field import for section rows without option replacement.
+      def import_section_entry(entry, on_conflict, result)
+        existing = TypedEAV::Section.find_by(
+          code: entry["code"],
+          entity_type: entry["entity_type"],
+          scope: entry["scope"],
+          parent_scope: entry["parent_scope"],
+        )
+
+        if existing
+          if section_export_row_equal?(existing, entry)
+            result["unchanged"] += 1
+            return
+          end
+
+          case on_conflict
+          when :error
+            raise_divergent_section!(entry)
+          when :skip
+            result["skipped"] += 1
+          when :overwrite
+            existing.update!(
+              name: entry["name"],
+              sort_order: entry["sort_order"],
+              active: entry["active"],
+            )
+            result["updated"] += 1
+          end
+        else
+          TypedEAV::Section.create!(entry)
+          result["created"] += 1
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def raise_divergent_section!(entry)
+        raise ArgumentError,
+              "Section '#{entry["code"]}' already exists for #{entry["entity_type"]} " \
+              "(scope=#{entry["scope"].inspect}, parent_scope=#{entry["parent_scope"].inspect}) " \
+              "and its attributes diverge from the incoming schema. " \
+              "Pass on_conflict: :skip or :overwrite to import over the existing section, " \
+              "or re-export from the source environment to confirm the divergence is intentional."
+      end
+
+      def field_export_row_equal?(existing, incoming)
+        export_field_entry(existing) == incoming
+      end
+
+      def section_export_row_equal?(existing, incoming)
+        export_section_entry(existing) == incoming
+      end
+    end
+  end
+end

data/lib/typed_eav/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedEAV
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/typed_eav/versioned.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Mixin that opts a host entity into Phase 04 versioning AFTER it has
+  # already called `has_typed_eav`. Equivalent in effect to passing
+  # `versioned: true` directly to `has_typed_eav`, but useful for:
+  #   - Codebases that group versioning concerns separately from the
+  #     `has_typed_eav` macro (e.g., audited models in a `Auditable`
+  #     mixin pattern).
+  #   - Apps that conditionally include versioning via Rails initializers
+  #     based on environment (`include TypedEAV::Versioned if Rails.env.production?`).
+  #
+  # ## Usage
+  #
+  #   class Contact < ActiveRecord::Base
+  #     has_typed_eav scope_method: :tenant_id, types: %i[text integer]
+  #     include TypedEAV::Versioned
+  #   end
+  #
+  # The order matters: `has_typed_eav` first, `include TypedEAV::Versioned`
+  # second. The concern's `included` hook re-registers the entity with
+  # `versioned: true`, preserving the existing `types:` restriction by
+  # reading the current Registry entry. If `has_typed_eav` was not called
+  # first, the included hook raises ArgumentError with a clear message.
+  #
+  # Why post-`has_typed_eav` (not standalone): `has_typed_eav` sets up
+  # the `has_many :typed_values` association, defines `typed_eav_scope` /
+  # `typed_eav_parent_scope` accessors, and includes the InstanceMethods
+  # mixin. Without that infrastructure, Phase 04 versioning has nothing
+  # to version — the host model can't even hold typed values. So
+  # `Versioned` is a *post*-step, not a replacement (Scout §2 confirmed
+  # this design).
+  #
+  # ## Equivalent to `has_typed_eav versioned: true`
+  #
+  # The two forms produce identical Registry state:
+  #   has_typed_eav versioned: true
+  #   # OR
+  #   has_typed_eav
+  #   include TypedEAV::Versioned
+  #
+  # The kwarg form is preferred for new code (one declaration, less to
+  # remember). The concern form is for codebases with established
+  # mixin-based feature wiring conventions.
+  module Versioned
+    extend ActiveSupport::Concern
+
+    included do
+      # Precondition: has_typed_eav must have run first.
+      # has_typed_eav sets `typed_eav_scope_method` as a class_attribute
+      # (lib/typed_eav/has_typed_eav.rb:115-116) — even when scope_method
+      # is nil, the class_attribute is defined. We test for the presence
+      # of the class_attribute reader as the canonical "did has_typed_eav
+      # run" check. `respond_to?` distinguishes "method defined" from
+      # "method missing" without false-positives from nil values.
+      unless respond_to?(:typed_eav_scope_method)
+        raise ArgumentError,
+              "include TypedEAV::Versioned requires `has_typed_eav` to have run first on #{name}. " \
+              "Add `has_typed_eav` (with any options you need) BEFORE `include TypedEAV::Versioned`. " \
+              "Alternatively, pass `versioned: true` directly to has_typed_eav."
+      end
+
+      # Re-register with versioned: true. Preserve the existing types:
+      # restriction by reading the current Registry entry.
+      # has_typed_eav already called register(name, types: types,
+      # versioned: false) — we overwrite with versioned: true while
+      # keeping the same types. If the entry doesn't exist (defensive
+      # — shouldn't happen post-has_typed_eav), default types to nil.
+      existing = TypedEAV.registry.entities[name] || {}
+      TypedEAV.registry.register(name, types: existing[:types], versioned: true)
+    end
+  end
+end