typed_eav 0.1.0 → 0.2.1

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # 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
+    #   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.
+    #
+    # Operators (explicit narrowing — does NOT inherit string-search ops
+    # like :contains/:starts_with from decimal_value's default since those
+    # don't apply to amount-numeric or currency-code searches):
+    # - :eq, :gt, :lt, :gteq, :lteq, :between target the amount.
+    # - :currency_eq targets the currency code (registered ONLY on this
+    #   class — QueryBuilder's operator-validation gate rejects it on any
+    #   non-Currency field).
+    # - :is_null / :is_not_null target the amount column (a Currency value
+    #   is considered null when its amount is null).
+    #
+    # Options:
+    # - default_currency: String ISO 4217 code (e.g., "USD"). Used as the
+    #   currency fallback when cast input has amount but no currency.
+    #   Never applies as a global silent default — only when cast input
+    #   already has an amount and no explicit currency.
+    # - 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
+
+      operators(*%i[eq gt lt gteq lteq between currency_eq is_null is_not_null])
+
+      store_accessor :options, :default_currency, :allowed_currencies
+
+      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
+      end
+
+      def self.operator_column(operator)
+        storage_contract_class.query_column(operator)
+      end
+
+      # Cast Hash input → [{amount: BigDecimal, currency: String}, false]
+      # or [nil, false] for nil/blank, or [nil, true] for unparseable input.
+      # Bare Numeric or String input is [nil, true] — users MUST pass a
+      # hash to make the currency dimension explicit (locked plan-time
+      # decision; preventing silent default_currency reliance in the
+      # ergonomic-but-error-prone scalar-cast case).
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- one cast method with linear branches for nil/non-hash/amount-parse/currency-coercion/currency-shape; splitting hides the cast contract from a single read.
+      def cast(raw)
+        return [nil, false] if raw.nil? || (raw.respond_to?(:empty?) && raw.empty?)
+        return [nil, true] unless raw.is_a?(Hash)
+
+        amount_raw   = raw[:amount]   || raw["amount"]
+        currency_raw = raw[:currency] || raw["currency"]
+
+        amount_bd = nil
+        if amount_raw.present?
+          amount_bd = BigDecimal(amount_raw.to_s, exception: false)
+          return [nil, true] if amount_bd.nil?
+        end
+
+        currency_str = currency_raw.is_a?(String) ? currency_raw.upcase : nil
+        # default_currency fallback applies ONLY when the hash has an
+        # amount but no currency. When the hash has neither, the result is
+        # {amount: nil, currency: nil} — falsy enough that read_value
+        # returns nil. When the hash has only a currency, the fallback
+        # does NOT trigger (amount stays nil); validation will catch the
+        # co-population requirement at save time.
+        currency_str ||= default_currency if amount_bd && default_currency.present?
+        # Reject non-3-letter currency codes (validation also catches this
+        # on save; cast catches it earlier so :invalid is set on the cast
+        # result and Value#validate_value surfaces :invalid promptly).
+        return [nil, true] if currency_str && currency_str !~ /\A[A-Z]{3}\z/
+
+        [{ amount: amount_bd, currency: currency_str }, false]
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # Co-population validation + allowed_currencies inclusion.
+      # When val is a Hash, requires both :amount and :currency populated.
+      # When allowed_currencies is set, val[:currency] must be in the
+      # list. Without the co-population check, a half-populated row
+      # (amount-only or currency-only) would silently round-trip.
+      def validate_typed_value(record, val)
+        return if val.nil?
+
+        unless val.is_a?(Hash) && val[:amount].present? && val[:currency].present?
+          record.errors.add(:value, "must have both amount and currency")
+          return
+        end
+
+        allowed = options_hash[:allowed_currencies]
+        record.errors.add(:value, :inclusion) if allowed.present? && Array(allowed).exclude?(val[:currency])
+      end
+
+      private
+
+      def allowed_currencies_format
+        list = options_hash[:allowed_currencies]
+        return if list.nil?
+        return if list.is_a?(Array) && list.all? { |c| c.is_a?(String) && c =~ /\A[A-Z]{3}\z/ }
+
+        errors.add(:allowed_currencies, "must be an Array of 3-letter uppercase ISO codes")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # Active Storage-backed field type for non-image file attachments.
+    # Stores the attached blob's `signed_id` (a String) in `string_value`.
+    # Same shape as Field::Image — see image.rb for the full soft-detect
+    # rationale, signed_id storage choice, and option semantics.
+    #
+    # ## Image vs File
+    #
+    # Both classes share the same shared `:attachment` has_one_attached
+    # association on TypedEAV::Value (declared once in engine.rb's
+    # config.after_initialize block; see RESEARCH §Risk 3 for the rationale
+    # against per-class associations). The semantic distinction at runtime
+    # is `value.field.is_a?(TypedEAV::Field::Image)` vs `is_a?(File)`. The
+    # blob's content_type is the source of truth for image-vs-other-file.
+    #
+    # The on_image_attached hook (Phase 05) fires ONLY for Field::Image —
+    # File has no parallel hook by ROADMAP design. Apps that need a
+    # generic file-attached signal use on_value_change (Phase 03) or
+    # subscribe to ActiveSupport::Notifications directly.
+    #
+    # ## Namespace shadowing note
+    #
+    # `TypedEAV::Field::File` shadows Ruby's top-level `::File` constant
+    # inside the TypedEAV::Field namespace. Internal code that needs the
+    # Ruby File class (none in this file) must reference it as `::File`
+    # to avoid ambiguity. This is intentional and matches the gem's
+    # one-class-per-file STI convention; renaming to FileAttachment
+    # would diverge from Image (also a single-word noun).
+    class File < Base
+      value_column :string_value
+
+      operators(*%i[eq is_null is_not_null])
+
+      store_accessor :options, :allowed_content_types, :max_size_bytes
+
+      # See TypedEAV::Field::Image#cast for the full contract — File's
+      # cast is identical except for the NotImplementedError message.
+      def cast(raw)
+        unless defined?(::ActiveStorage::Blob)
+          raise NotImplementedError,
+                "TypedEAV::Field::File requires Active Storage. " \
+                "Add `gem 'activestorage'` to your Gemfile (already " \
+                "included via the `rails` meta-gem in Rails 7.1+) and " \
+                "run `bin/rails active_storage:install`."
+        end
+
+        return [nil, false] if raw.nil? || (raw.respond_to?(:empty?) && raw.empty?)
+        return [raw.signed_id, false] if raw.is_a?(::ActiveStorage::Blob)
+        return [raw, false] if raw.is_a?(String)
+
+        [nil, true]
+      end
+
+      # See TypedEAV::Field::Image#validate_typed_value for the full
+      # contract — File's validation is identical (it accepts the same
+      # allowed_content_types / max_size_bytes options). Apps that want
+      # image-only mime restrictions configure
+      # `allowed_content_types: ["image/*"]`; otherwise the field is a
+      # general-purpose attachment slot.
+      def validate_typed_value(record, val)
+        return if val.nil?
+        return unless defined?(::ActiveStorage::Blob)
+
+        blob = ::ActiveStorage::Blob.find_signed(val)
+        if blob.nil?
+          record.errors.add(:value, :invalid)
+          return
+        end
+
+        if allowed_content_types.present? && !content_type_matches?(blob.content_type)
+          record.errors.add(
+            :value,
+            "must be one of #{Array(allowed_content_types).join(", ")}",
+          )
+        end
+
+        return unless max_size_bytes.present? && blob.byte_size > max_size_bytes.to_i
+
+        record.errors.add(:value, "exceeds max size #{max_size_bytes} bytes")
+      end
+
+      private
+
+      def content_type_matches?(blob_content_type)
+        Array(allowed_content_types).any? do |pattern|
+          if pattern.end_with?("/*")
+            blob_content_type&.start_with?(pattern.sub("/*", "/"))
+          else
+            blob_content_type == pattern
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # Active Storage-backed field type for image attachments. Stores the
+    # attached blob's `signed_id` (a String) in `string_value`. The
+    # actual `:attachment` has_one_attached association lives on
+    # TypedEAV::Value (registered in lib/typed_eav/engine.rb's
+    # config.after_initialize block when ActiveStorage::Blob is defined).
+    #
+    # ## Phase 05 Gating Decision 1: lazy soft-detect
+    #
+    # The gem does NOT add `add_dependency 'activestorage'` to its gemspec.
+    # When Active Storage is absent at runtime, this class still LOADS
+    # (Zeitwerk autoloads it; constants are inspectable without forcing
+    # AS load). #cast and #validate_typed_value short-circuit / raise on
+    # invocation:
+    #
+    #   - #cast raises NotImplementedError with an actionable install
+    #     message (the only cast contract that can fail-fast — every
+    #     write path goes through cast).
+    #   - #validate_typed_value silently no-ops when AS is unloaded
+    #     (validation runs against blob lookup, which can't happen).
+    #
+    # Mirrors the acts_as_tenant precedent (Config::DEFAULT_SCOPE_RESOLVER
+    # in lib/typed_eav/config.rb lines 49-53) — `defined?(::ConstantName)`
+    # is the gem-wide soft-detect idiom.
+    #
+    # ## signed_id storage choice
+    #
+    # signed_id is a stable, portable, message-verified handle that
+    # survives blob replacement and decouples the gem's data shape from
+    # ActiveStorage's internal blob-id format. Storing the bare integer
+    # blob_id would couple the gem's persisted data to AS's primary-key
+    # type and prevent migrations like UUID-typed blobs. signed_id is
+    # always a String → string_value is the natural typed column.
+    #
+    # ## Operators
+    #
+    # Explicit narrowing to [:eq, :is_null, :is_not_null]. Numeric and
+    # string-pattern operators (:contains, :starts_with) don't apply to
+    # signed_id strings (they're message-signed opaque tokens). Presence
+    # checks via :is_null / :is_not_null are the canonical "does this
+    # entity have an attachment?" query.
+    #
+    # ## Options
+    #
+    # - allowed_content_types: Array<String> — content-type allowlist
+    #   for validate_typed_value. Supports exact matches ("image/png")
+    #   and wildcard families ("image/*").
+    # - max_size_bytes: Integer — maximum blob byte_size accepted by
+    #   validate_typed_value. Pass as Integer or numeric String; nil
+    #   disables the size cap.
+    #
+    # ## Attachment access
+    #
+    # Read-side: `value.attachment.attached?`, `value.attachment.blob`,
+    # `value.attachment.url` (Rails standard helpers — typed_eav doesn't
+    # wrap them).
+    # Write-side: `value.attachment.attach(io: ..., filename: ...,
+    # content_type: ...)`, then `value.update!(string_value: value
+    # .attachment.blob.signed_id)`. The signed_id assignment is what
+    # the typed_eav read path serves; the attachment association is the
+    # AS-native handle.
+    class Image < Base
+      value_column :string_value
+
+      operators(*%i[eq is_null is_not_null])
+
+      store_accessor :options, :allowed_content_types, :max_size_bytes
+
+      # Cast contract:
+      # - nil / blank → [nil, false]
+      # - String → treated as a signed_id; passthrough as [raw, false]
+      # - ActiveStorage::Blob → [blob.signed_id, false]
+      # - any other shape (File, Tempfile, IO, Hash) → [nil, true]
+      #   (apps must call value.attachment.attach(io: ...) directly,
+      #   then assign the blob's signed_id back through value=)
+      #
+      # Raises NotImplementedError when ::ActiveStorage::Blob is undefined.
+      # The raise lives in cast (not in the class body) so the constant
+      # itself loads cleanly under Zeitwerk even when AS is absent —
+      # consumers inspecting `TypedEAV::Field::Image.value_column` are
+      # not forced to install AS.
+      def cast(raw)
+        unless defined?(::ActiveStorage::Blob)
+          raise NotImplementedError,
+                "TypedEAV::Field::Image requires Active Storage. " \
+                "Add `gem 'activestorage'` to your Gemfile (already " \
+                "included via the `rails` meta-gem in Rails 7.1+) and " \
+                "run `bin/rails active_storage:install`."
+        end
+
+        return [nil, false] if raw.nil? || (raw.respond_to?(:empty?) && raw.empty?)
+        return [raw.signed_id, false] if raw.is_a?(::ActiveStorage::Blob)
+        return [raw, false] if raw.is_a?(String)
+
+        [nil, true]
+      end
+
+      # Validates a casted signed_id String. Looks up the blob via
+      # `ActiveStorage::Blob.find_signed` (returns nil for tampered/
+      # expired tokens — flagged as :invalid). When allowed_content_types
+      # is set, asserts blob.content_type matches one entry (exact or
+      # `image/*` wildcard). When max_size_bytes is set, asserts
+      # blob.byte_size <= the limit.
+      #
+      # Silently no-ops when Active Storage is unloaded — the raise
+      # happens in cast (the only path that reaches save) so this is
+      # defensive belt-and-suspenders. Without this guard, a soft-
+      # detect-aware host could call validate_typed_value directly via
+      # introspection and trigger NameError at runtime; the no-op
+      # preserves the lazy contract.
+      def validate_typed_value(record, val)
+        return if val.nil?
+        return unless defined?(::ActiveStorage::Blob)
+
+        blob = ::ActiveStorage::Blob.find_signed(val)
+        if blob.nil?
+          record.errors.add(:value, :invalid)
+          return
+        end
+
+        if allowed_content_types.present? && !content_type_matches?(blob.content_type)
+          record.errors.add(
+            :value,
+            "must be one of #{Array(allowed_content_types).join(", ")}",
+          )
+        end
+
+        return unless max_size_bytes.present? && blob.byte_size > max_size_bytes.to_i
+
+        record.errors.add(:value, "exceeds max size #{max_size_bytes} bytes")
+      end
+
+      private
+
+      # Match against allowed_content_types entries. An entry ending in
+      # `/*` (e.g., "image/*") matches any content type with the same
+      # family prefix; otherwise an exact string match is required.
+      def content_type_matches?(blob_content_type)
+        Array(allowed_content_types).any? do |pattern|
+          if pattern.end_with?("/*")
+            blob_content_type&.start_with?(pattern.sub("/*", "/"))
+          else
+            blob_content_type == pattern
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # Decimal subclass storing fractions in 0..1 (inclusive). The "percent"
+    # representation (e.g., "75.0%") is a format-time concern via
+    # `display_as: :percent` — the underlying decimal_value column always
+    # stores the fraction.
+    #
+    # STI: extends Field::Decimal (subclass-of-subclass). Rails AR resolves
+    # the `type` column to "TypedEAV::Field::Percentage" correctly because
+    # default STI behavior uses the leaf class name.
+    #
+    # Storage: decimal_value (inherited from Decimal — does NOT re-declare).
+    # Operators: inherits Decimal's default operator set
+    # (DEFAULT_OPERATORS_BY_COLUMN[:decimal_value]).
+    # Range: hard-coded 0..1; min/max options are NOT exposed via
+    # store_accessor (they would conflict with the 0-1 invariant).
+    # Decimal's `precision_scale` option is inherited but not exposed
+    # here either — it would govern storage rounding only.
+    #
+    # Options (all read-side only — do NOT change what gets stored):
+    # - 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`
+      # 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")
+      # is unaffected.
+      value_column :decimal_value
+
+      store_accessor :options, :decimal_places, :display_as
+
+      validate :decimal_places_format
+      validate :display_as_inclusion
+
+      # Inherits supported_operators (DEFAULT_OPERATORS_BY_COLUMN
+      # [:decimal_value]) and cast (BigDecimal parse) from Decimal.
+      # Inherits read_value / write_value / apply_default_to defaults from
+      # Field::Base via Decimal's chain.
+
+      def validate_typed_value(record, val)
+        # Inherits Decimal's range check (min/max — typically nil for
+        # Percentage since options are not exposed). Without `super`, a
+        # future addition of min/max to Percentage's options would
+        # silently bypass the range guard.
+        super
+        return if val.nil?
+
+        return if val.between?(0, 1)
+
+        record.errors.add(:value, "must be between 0.0 and 1.0")
+      end
+
+      # Format helper. Read-side only; does NOT alter what's stored in
+      # decimal_value.
+      #
+      # - display_as: :percent → returns "<val*100>%" rounded to
+      #   decimal_places (e.g., 0.75 with decimal_places: 1 → "75.0%").
+      # - display_as: :fraction (default) → returns val.to_s
+      #   (e.g., 0.75 → "0.75").
+      # - nil val → returns nil.
+      def format(val)
+        return nil if val.nil?
+
+        places = (decimal_places || 2).to_i
+        case display_as&.to_sym
+        when :percent
+          "#{(val * 100).round(places)}%"
+        else # :fraction or unset
+          val.to_s
+        end
+      end
+
+      private
+
+      def decimal_places_format
+        d = options_hash[:decimal_places]
+        return if d.nil?
+
+        d_int = Integer(d.to_s, exception: false)
+        return if d_int && d_int >= 0
+
+        errors.add(:decimal_places, "must be a non-negative integer")
+      end
+
+      def display_as_inclusion
+        d = options_hash[:display_as]
+        return if d.nil?
+        return if %w[fraction percent].include?(d.to_s)
+
+        errors.add(:display_as, "must be :fraction or :percent")
+      end
+    end
+  end
+end