typed_eav 0.2.1 → 0.3.0

data/app/models/typed_eav/field/currency.rb

@@ -5,21 +5,21 @@ module TypedEAV
     # Two-cell field type: stores `{amount: BigDecimal, currency: String}`
     # across decimal_value (amount) + string_value (currency ISO 4217 code).
     #
-    # Phase 05 contract:
-    # - value_columns: [:decimal_value, :string_value] — propagates through
-    #   versioning's snapshot loop (Phase 04) and the Value
-    #   _dispatch_value_change_update filter so a change to either cell
+    # Multi-cell contract:
+    # - `value_columns :decimal_value, :string_value` — both cells propagate
+    #   through versioning's snapshot loop and the Value
+    #   `_dispatch_value_change_update` filter so a change to either cell
     #   correctly fires the :update event.
-    # - operator_column: :currency_eq → :string_value; everything else →
-    #   :decimal_value. Routed via QueryBuilder.filter (plan 05-01).
-    # - read_value / write_value / apply_default_to: paired overrides
-    #   that compose / unpack the {amount, currency} hash across the two
-    #   physical columns. Without all three, single-cell defaults would
-    #   write a Hash to decimal_value and raise TypeMismatch.
-    # - cast: Hash input only. Bare Numeric/String is invalid — explicit
-    #   currency dimension is required at write time. Silently defaulting
-    #   to default_currency would invite bugs where users forget the
-    #   currency dimension entirely.
+    # - `operator_column` routes `:currency_eq` → `:string_value` and every
+    #   other supported op → `:decimal_value`. QueryBuilder reads this.
+    # - `read_value` / `write_value` / `apply_default` are the three
+    #   overrides paired with the multi-cell declaration. Without all three,
+    #   single-cell defaults would write a Hash to decimal_value and raise
+    #   TypeMismatch at save time.
+    # - `cast` requires a Hash input. Bare Numeric/String is invalid —
+    #   explicit currency dimension is required at write time. Silently
+    #   defaulting to default_currency would invite bugs where users forget
+    #   the currency dimension entirely.
     #
     # Operators (explicit narrowing — does NOT inherit string-search ops
     # like :contains/:starts_with from decimal_value's default since those
@@ -39,9 +39,10 @@ module TypedEAV
     # - allowed_currencies: Array<String> of ISO codes. When set,
     #   validate_typed_value enforces inclusion.
     class Currency < Base
-      value_column :decimal_value
-      storage_contract_class TypedEAV::CurrencyStorageContract
+      AMOUNT_COLUMN = :decimal_value
+      CURRENCY_COLUMN = :string_value
 
+      value_columns AMOUNT_COLUMN, CURRENCY_COLUMN
       operators(*%i[eq gt lt gteq lteq between currency_eq is_null is_not_null])
 
       store_accessor :options, :default_currency, :allowed_currencies
@@ -49,12 +50,45 @@ module TypedEAV
       validates :default_currency, format: { with: /\A[A-Z]{3}\z/ }, allow_nil: true
       validate :allowed_currencies_format
 
-      def self.value_columns
-        storage_contract_class.value_columns
+      # Route `:currency_eq` to the currency-code cell; every other supported
+      # operator targets the amount cell. The operator-validation gate in
+      # QueryBuilder.filter has already narrowed `operator` to the set
+      # declared above by the time this runs.
+      def self.operator_column(operator)
+        operator == :currency_eq ? CURRENCY_COLUMN : AMOUNT_COLUMN
       end
 
-      def self.operator_column(operator)
-        storage_contract_class.query_column(operator)
+      # Compose the logical Hash from the two cells. Returns `nil` only
+      # when BOTH cells are nil — a half-populated row still round-trips
+      # as the partial Hash so validation can surface the missing dimension.
+      def read_value(value_record)
+        amount = value_record[AMOUNT_COLUMN]
+        currency = value_record[CURRENCY_COLUMN]
+        return nil if amount.nil? && currency.nil?
+
+        { amount: amount, currency: currency }
+      end
+
+      # Unpack the casted Hash across the two cells. `nil` clears both.
+      def write_value(value_record, casted)
+        if casted.nil?
+          value_record[AMOUNT_COLUMN] = nil
+          value_record[CURRENCY_COLUMN] = nil
+        else
+          value_record[AMOUNT_COLUMN] = casted[:amount]
+          value_record[CURRENCY_COLUMN] = casted[:currency]
+        end
+      end
+
+      # Populate both cells from the field's configured default. Mirrors
+      # `write_value`'s Hash decomposition; tolerates string-keyed defaults
+      # for jsonb round-trip (`default_value_meta` stores raw config).
+      def apply_default(value_record)
+        default = default_value
+        return unless default.is_a?(Hash)
+
+        value_record[AMOUNT_COLUMN] = default[:amount] || default["amount"]
+        value_record[CURRENCY_COLUMN] = default[:currency] || default["currency"]
       end
 
       # Cast Hash input → [{amount: BigDecimal, currency: String}, false]

data/app/models/typed_eav/field/date.rb

@@ -2,11 +2,26 @@
 
 module TypedEAV
   module Field
-    class Date < Base
+    # Date-typed field with optional min_date/max_date guards. Declares
+    # its own `date_value` storage and `:min_date`/`:max_date`
+    # `store_accessor`. `validate_date_range` is inherited from
+    # `Field::RangeBounded`.
+    #
+    # Latent-bug fix (per ADR-0004): the
+    # `validates :max_date, comparison: { greater_than_or_equal_to: :min_date }`
+    # macro now applies here (previously only Integer/Decimal carried it).
+    # A Date field configured with `max_date < min_date` fails at
+    # field-save instead of saving silently.
+    class Date < RangeBounded
       value_column :date_value
 
       store_accessor :options, :min_date, :max_date
 
+      validates :max_date,
+                comparison: { greater_than_or_equal_to: :min_date },
+                allow_nil: true,
+                if: :min_date
+
       def cast(raw)
         return [nil, false] if raw.nil?
 

data/app/models/typed_eav/field/date_time.rb

@@ -2,11 +2,26 @@
 
 module TypedEAV
   module Field
-    class DateTime < Base
+    # DateTime-typed field with optional min_datetime/max_datetime
+    # guards. Declares its own `datetime_value` storage and
+    # `:min_datetime`/`:max_datetime` `store_accessor`.
+    # `validate_datetime_range` is inherited from `Field::RangeBounded`.
+    #
+    # Latent-bug fix (per ADR-0004): the
+    # `validates :max_datetime, comparison: { greater_than_or_equal_to: :min_datetime }`
+    # macro now applies here (previously only Integer/Decimal carried
+    # it). A DateTime field configured with `max_datetime < min_datetime`
+    # fails at field-save instead of saving silently.
+    class DateTime < RangeBounded
       value_column :datetime_value
 
       store_accessor :options, :min_datetime, :max_datetime
 
+      validates :max_datetime,
+                comparison: { greater_than_or_equal_to: :min_datetime },
+                allow_nil: true,
+                if: :min_datetime
+
       def cast(raw)
         return [nil, false] if raw.nil?
         return [raw, false] if raw.is_a?(::Time)

data/app/models/typed_eav/field/decimal.rb

@@ -2,7 +2,15 @@
 
 module TypedEAV
   module Field
-    class Decimal < Base
+    # Decimal-typed field with optional min/max guards and optional
+    # `precision_scale` rounding. Declares its own `decimal_value`
+    # storage and `:min`/`:max`/`:precision_scale` `store_accessor`; the
+    # `validate :max, comparison:` macro guards against inverted bounds
+    # at field-save. `validate_range` is inherited from
+    # `Field::RangeBounded`. `Field::Percentage` extends this class to
+    # add the 0..1 invariant (chain depth becomes
+    # `Percentage < Decimal < RangeBounded < Base`).
+    class Decimal < RangeBounded
       value_column :decimal_value
 
       store_accessor :options, :min, :max, :precision_scale

data/app/models/typed_eav/field/email.rb

@@ -2,12 +2,20 @@
 
 module TypedEAV
   module Field
-    class Email < Base
+    # Email-typed field. Inherits `string_value` storage shape, the
+    # `min_length` / `max_length` / `pattern` `store_accessor`, the
+    # `max_gte_min_length` guard, and the `validate_pattern_syntax` guard
+    # from `Field::ValidatedString`. Adds the `EMAIL_FORMAT` regex and
+    # layers the format check onto `validate_typed_value` via `super`.
+    #
+    # Latent-bug fix (per ADR-0004): `max_gte_min_length` (previously
+    # only on Text) now applies here — an Email field configured with
+    # `max_length < min_length` fails at field-save.
+    class Email < ValidatedString
+      # Re-declare value_column for Ruby class-ivar non-inheritance — see
+      # comment on Field::Text. STI dispatch is unaffected.
       value_column :string_value
 
-      store_accessor :options, :min_length, :max_length, :pattern
-      validate :validate_pattern_syntax
-
       EMAIL_FORMAT = /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/
 
       def cast(raw)
@@ -21,20 +29,9 @@ module TypedEAV
       end
 
       def validate_typed_value(record, val)
-        validate_length(record, val)
-        validate_pattern(record, val) if pattern.present?
+        super
         record.errors.add(:value, "is not a valid email address") unless email_format_valid?(val)
       end
-
-      private
-
-      def validate_pattern_syntax
-        return if pattern.blank?
-
-        Regexp.new(pattern)
-      rescue RegexpError => e
-        errors.add(:pattern, "is invalid: #{e.message}")
-      end
     end
   end
 end

data/app/models/typed_eav/field/integer.rb

@@ -2,7 +2,12 @@
 
 module TypedEAV
   module Field
-    class Integer < Base
+    # Integer-typed field with optional min/max guards. Declares its own
+    # `integer_value` storage and `:min`/`:max` `store_accessor`; the
+    # `validate :max, comparison:` macro guards against inverted bounds
+    # at field-save. `validate_range` is inherited from
+    # `Field::RangeBounded`.
+    class Integer < RangeBounded
       value_column :integer_value
 
       store_accessor :options, :min, :max

data/app/models/typed_eav/field/long_text.rb

@@ -2,6 +2,15 @@
 
 module TypedEAV
   module Field
+    # Long-text-typed field stored in the `text_value` column. Kept as a
+    # direct child of `Field::Base` (per ADR-0004 — array types,
+    # LongText, File, Image, Reference all stay direct children; only
+    # Text/Email/Url moved into the new `Field::ValidatedString` family).
+    # Inlines its own min_length / max_length check rather than joining
+    # the ValidatedString family because LongText does NOT carry the
+    # `:pattern` option, the `max_gte_min_length` guard, or the
+    # `validate_pattern_syntax` guard — the family base would attach
+    # validation surface LongText doesn't want.
     class LongText < Base
       value_column :text_value
 
@@ -12,7 +21,14 @@ module TypedEAV
       end
 
       def validate_typed_value(record, val)
-        validate_length(record, val)
+        opts = options_hash
+        str = val.to_s
+        if opts[:min_length] && str.length < opts[:min_length].to_i
+          record.errors.add(:value, :too_short, count: opts[:min_length])
+        end
+        return unless opts[:max_length] && str.length > opts[:max_length].to_i
+
+        record.errors.add(:value, :too_long, count: opts[:max_length])
       end
     end
   end

data/app/models/typed_eav/field/multi_select.rb

@@ -2,21 +2,24 @@
 
 module TypedEAV
   module Field
+    # Multi-choice option-set field. Stores the chosen values as a JSON
+    # array in `json_value`. Inherits `optionable? = true`, the
+    # public-facing sorted `allowed_values` helper, and the protected
+    # `validate_multi_option_inclusion` helper from `Field::Optionable`.
+    # Stays a direct child of `Field::Base` — Optionable is a concern
+    # (mixin), not an intermediate STI class, because Select and
+    # MultiSelect don't share a `value_column`.
+    #
+    # `validate_array_size` is called directly from `Field::Base`
+    # (cross-family outlier; also used by `Field::IntegerArray`).
     class MultiSelect < Base
+      include Optionable
+
       value_column :json_value
       operators :any_eq, :all_eq, :is_null, :is_not_null
 
-      def optionable? = true
       def array_field? = true
 
-      def allowed_values
-        if field_options.loaded?
-          field_options.sort_by { |o| [o.sort_order || 0, o.label.to_s] }.map(&:value)
-        else
-          field_options.sorted.pluck(:value)
-        end
-      end
-
       def cast(raw)
         return [nil, false] if raw.nil?
 

data/app/models/typed_eav/field/optionable.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # Concern (mixin) for field types whose valid values are constrained
+    # to an enumeration of `Field::Option` rows.
+    #
+    # Included by: `Field::Select`, `Field::MultiSelect`. Both leaves stay
+    # as direct children of `Field::Base` — Select uses `string_value`,
+    # MultiSelect uses `json_value`. Inheritance can't unify storage for
+    # both, so we use a concern instead of an intermediate class.
+    #
+    # Provides:
+    #
+    # - `optionable?` overridden to `true` (default on `Field::Base` is
+    #   `false`).
+    # - `allowed_values` — the public-facing, **sorted** option-values
+    #   helper. When `field_options` is loaded, sorts in memory by
+    #   `[sort_order || 0, label]`; otherwise issues a `sorted.pluck`
+    #   query. Matches the per-leaf implementation that was duplicated
+    #   verbatim between Select and MultiSelect pre-refactor.
+    # - `validate_option_inclusion` / `validate_multi_option_inclusion`
+    #   protected helpers (moved from `Field::Base`). Both call into
+    #   `allowed_option_values` (the validator-facing fast path that still
+    #   lives on `Field::Base`) so they avoid the sort overhead on the hot
+    #   validation path.
+    #
+    # Public extension point: external authors can `include
+    # TypedEAV::Field::Optionable` to opt into the option-set surface
+    # without joining the Select/MultiSelect inheritance chain (see
+    # README §"Custom field types").
+    module Optionable
+      extend ActiveSupport::Concern
+
+      def optionable? = true
+
+      def allowed_values
+        if field_options.loaded?
+          field_options.sort_by { |o| [o.sort_order || 0, o.label.to_s] }.map(&:value)
+        else
+          field_options.sorted.pluck(:value)
+        end
+      end
+
+      protected
+
+      def validate_option_inclusion(record, val)
+        return if allowed_option_values.include?(val&.to_s)
+
+        record.errors.add(:value, :inclusion)
+      end
+
+      def validate_multi_option_inclusion(record, val)
+        invalid = Array(val).map(&:to_s) - allowed_option_values
+        record.errors.add(:value, :inclusion) if invalid.any?
+      end
+    end
+  end
+end

data/app/models/typed_eav/field/percentage.rb

@@ -23,10 +23,10 @@ module TypedEAV
     # - decimal_places: Integer >= 0 (default 2). Format-time precision.
     # - display_as: :fraction | :percent (default :fraction).
     class Percentage < Decimal
-      # Re-declare value_column :decimal_value. ColumnMapping's value_column
-      # stores the column on `@value_column` (a class instance variable on
-      # the declaring class) — Ruby class instance variables are NOT
-      # inherited through subclass lookup, so `Percentage.value_column`
+      # Re-declare value_column :decimal_value. TypedStorage's `value_column`
+      # / `value_columns` setters write to `@value_columns` (a class instance
+      # variable on the declaring class) — Ruby class instance variables are
+      # NOT inherited through subclass lookup, so `Percentage.value_column`
       # would raise NotImplementedError without this re-declaration.
       # Re-declaring with the same column is BC-safe and explicit; STI
       # behavior (the `type` column stores "TypedEAV::Field::Percentage")
@@ -38,9 +38,9 @@ module TypedEAV
       validate :decimal_places_format
       validate :display_as_inclusion
 
-      # Inherits supported_operators (DEFAULT_OPERATORS_BY_COLUMN
+      # Inherits supported_operators (TypedStorage::DEFAULT_OPERATORS_BY_COLUMN
       # [:decimal_value]) and cast (BigDecimal parse) from Decimal.
-      # Inherits read_value / write_value / apply_default_to defaults from
+      # Inherits read_value / write_value / apply_default defaults from
       # Field::Base via Decimal's chain.
 
       def validate_typed_value(record, val)

data/app/models/typed_eav/field/range_bounded.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # Intermediate STI base for field families that constrain a single
+    # comparable value by `min`/`max` bounds.
+    #
+    # Leaves: `Field::Integer`, `Field::Decimal`, `Field::Date`,
+    # `Field::DateTime`. `Field::Percentage` keeps its `< Decimal` chain
+    # (so the new full chain is
+    # `Percentage < Decimal < RangeBounded < Base`).
+    #
+    # Does NOT declare a `value_column` — each leaf still owns its typed
+    # column (`integer_value`, `decimal_value`, `date_value`,
+    # `datetime_value`). The family is identified by "has min/max bounds",
+    # not by storage shape.
+    #
+    # Hoists the protected `validate_range` / `validate_date_range` /
+    # `validate_datetime_range` helpers previously kept on `Field::Base`.
+    # Each leaf declares its own `store_accessor` (`:min`/`:max` for
+    # Integer/Decimal; `:min_date`/`:max_date` for Date;
+    # `:min_datetime`/`:max_datetime` for DateTime) and its own
+    # `validates :max, comparison: { greater_than_or_equal_to: :min }`
+    # macro using the appropriate key names. Adding the macro to
+    # Date/DateTime in-slice closes a latent-bug gap previously only
+    # caught on Integer/Decimal.
+    #
+    # Public extension point: external authors can subclass this directly
+    # if they want a typed numeric/temporal column with min/max guards
+    # (see README §"Custom field types"). STI dispatch is unaffected.
+    class RangeBounded < Base
+      protected
+
+      def validate_range(record, val)
+        opts = options_hash
+        record.errors.add(:value, :greater_than_or_equal_to, count: opts[:min]) if opts[:min] && val < opts[:min].to_d
+        return unless opts[:max] && val > opts[:max].to_d
+
+        record.errors.add(:value, :less_than_or_equal_to, count: opts[:max])
+      end
+
+      def validate_date_range(record, val)
+        opts = options_hash
+        if opts[:min_date]
+          min = ::Date.parse(opts[:min_date])
+          record.errors.add(:value, :greater_than_or_equal_to, count: opts[:min_date]) if val < min
+        end
+        if opts[:max_date]
+          max = ::Date.parse(opts[:max_date])
+          record.errors.add(:value, :less_than_or_equal_to, count: opts[:max_date]) if val > max
+        end
+      rescue ::Date::Error
+        record.errors.add(:base, "field has invalid date configuration")
+      end
+
+      def validate_datetime_range(record, val)
+        opts = options_hash
+        if opts[:min_datetime]
+          min = ::Time.zone.parse(opts[:min_datetime])
+          record.errors.add(:value, :greater_than_or_equal_to, count: opts[:min_datetime]) if val < min
+        end
+        if opts[:max_datetime]
+          max = ::Time.zone.parse(opts[:max_datetime])
+          record.errors.add(:value, :less_than_or_equal_to, count: opts[:max_datetime]) if val > max
+        end
+      rescue ArgumentError
+        record.errors.add(:base, "field has invalid datetime configuration")
+      end
+    end
+  end
+end

data/app/models/typed_eav/field/select.rb

@@ -2,20 +2,19 @@
 
 module TypedEAV
   module Field
+    # Single-choice option-set field. Stores the chosen value in
+    # `string_value`. Inherits `optionable? = true`, the public-facing
+    # sorted `allowed_values` helper, and the protected
+    # `validate_option_inclusion` helper from `Field::Optionable`. Stays a
+    # direct child of `Field::Base` — Optionable is a concern (mixin), not
+    # an intermediate STI class, because Select and MultiSelect don't
+    # share a `value_column`.
     class Select < Base
+      include Optionable
+
       value_column :string_value
       operators :eq, :not_eq, :is_null, :is_not_null
 
-      def optionable? = true
-
-      def allowed_values
-        if field_options.loaded?
-          field_options.sort_by { |o| [o.sort_order || 0, o.label.to_s] }.map(&:value)
-        else
-          field_options.sorted.pluck(:value)
-        end
-      end
-
       def cast(raw)
         [raw&.to_s, false]
       end

data/app/models/typed_eav/field/text.rb

@@ -2,40 +2,22 @@
 
 module TypedEAV
   module Field
-    class Text < Base
+    # String-typed field with optional length / pattern guards. Storage,
+    # `store_accessor`, numericality validators, `max_gte_min_length`,
+    # `validate_pattern_syntax`, and the default `validate_typed_value`
+    # (length + pattern) all come from `Field::ValidatedString`. Text adds
+    # only `cast` (raw → String).
+    class Text < ValidatedString
+      # Re-declare value_column to populate Text's own @value_columns class
+      # instance variable — Ruby class ivars are NOT inherited through
+      # subclass lookup (the same workaround `Field::Percentage` uses
+      # against `Field::Decimal`). BC-safe and explicit; STI dispatch is
+      # unaffected (the `type` column still stores "TypedEAV::Field::Text").
       value_column :string_value
 
-      store_accessor :options, :min_length, :max_length, :pattern
-
-      validates :min_length, numericality: { only_integer: true, greater_than_or_equal_to: 0 }, allow_nil: true
-      validates :max_length, numericality: { only_integer: true, greater_than: 0 }, allow_nil: true
-      validate :max_gte_min_length
-      validate :validate_pattern_syntax
-
       def cast(raw)
         [raw&.to_s, false]
       end
-
-      def validate_typed_value(record, val)
-        validate_length(record, val)
-        validate_pattern(record, val) if pattern.present?
-      end
-
-      private
-
-      def max_gte_min_length
-        return unless min_length && max_length
-
-        errors.add(:max_length, "must be >= min_length") if max_length < min_length
-      end
-
-      def validate_pattern_syntax
-        return if pattern.blank?
-
-        Regexp.new(pattern)
-      rescue RegexpError => e
-        errors.add(:pattern, "is invalid: #{e.message}")
-      end
     end
   end
 end

data/app/models/typed_eav/field/url.rb

@@ -4,12 +4,21 @@ require "uri"
 
 module TypedEAV
   module Field
-    class Url < Base
+    # URL-typed field. Inherits `string_value` storage shape, the
+    # `min_length` / `max_length` / `pattern` `store_accessor`, the
+    # `max_gte_min_length` guard, and the `validate_pattern_syntax` guard
+    # from `Field::ValidatedString`. Adds the `URL_FORMAT` regex
+    # (http/https only) and layers the format check onto
+    # `validate_typed_value` via `super`.
+    #
+    # Latent-bug fix (per ADR-0004): `max_gte_min_length` (previously
+    # only on Text) now applies here — a Url field configured with
+    # `max_length < min_length` fails at field-save.
+    class Url < ValidatedString
+      # Re-declare value_column for Ruby class-ivar non-inheritance — see
+      # comment on Field::Text. STI dispatch is unaffected.
       value_column :string_value
 
-      store_accessor :options, :min_length, :max_length, :pattern
-      validate :validate_pattern_syntax
-
       URL_FORMAT = /\A#{URI::DEFAULT_PARSER.make_regexp(%w[http https])}\z/
 
       def cast(raw)
@@ -21,20 +30,9 @@ module TypedEAV
       end
 
       def validate_typed_value(record, val)
-        validate_length(record, val)
-        validate_pattern(record, val) if pattern.present?
+        super
         record.errors.add(:value, "is not a valid URL") unless url_format_valid?(val)
       end
-
-      private
-
-      def validate_pattern_syntax
-        return if pattern.blank?
-
-        Regexp.new(pattern)
-      rescue RegexpError => e
-        errors.add(:pattern, "is invalid: #{e.message}")
-      end
     end
   end
 end