eav_field 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad4c68d056641acdb72729aa099b55285fb948de48ed41511fdb2472f1a6292c
-  data.tar.gz: 74be0f6ec80589ee374f5604fe347d97a5e07bf4933ab7bc5b6ac8cbe7dc8302
+  metadata.gz: b896c149cbc241d3b66424de96a67efe6c0c8681b9e2e30236e75e2139483904
+  data.tar.gz: 86a6a9238de4349fd387806ffd1e26b859c03b09de5cdd8265d2f2088e950dbf
 SHA512:
-  metadata.gz: afedd539adaa261644b67ab9078edb02e845a1189abfaa31e975d74bc5a8284b361da247564fdc0149cca96812ba75bafd23d0f55c0f5eacc07fa0ff974f6bf6
-  data.tar.gz: 359ba7b4509ed4f67723922a37c8849c5ca15ce5ef78abd7f63dbca9ada9040ccea75c165b8359564e95fbdad40cd7a811e6e92b5cac94ef4532cbf9787013db
+  metadata.gz: 686203fd2a23f9ef7d5d3aa6067cd361d1314e3aa47bda04a49c1fead8f387dbbbb8136e718f9872d78d5025f5fae5c46a9f09bd93bdc196898febd18af209fc
+  data.tar.gz: 3bdc289b5159e9aa213254dfd55758d72444b1006a40c650d64760cb35c21c1c75649459afed43f61a9c14ee162377a916f7564abae30b82c8bb1f091e4b3f3c

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.0 — Unreleased
+
+- Add persisted minimum/maximum, length, and allowed-choice validation rules with owner errors and validated defaults.
+- Add application-defined `validate_eav_field` blocks with inheritance and support for defaults.
+- Add typed comparisons, ranges, inclusion, inequality, and missing-row filters.
+- Add EAV sorting with effective defaults and explicit null placement.
+- Add collection preloading, owner definition snapshots, and execution-local definition cache blocks.
+- Invalidate local definition caches on changes, commits, and rollbacks; provide explicit refresh for external or bulk changes.
+- Add an upgrade generator for existing 0.1.0 installations and preserve stored values during SQLite rollback.
+
 ## 0.1.0 — 2026-10-09
 
 - Add `has_eav_fields` for existing Active Record models.

data/README.md

@@ -4,6 +4,8 @@ EavField adds an entity-attribute-value (EAV) system to existing Active Record m
 
 Requires Ruby 3.2+ and Active Record/Railties 7.1–8.x. The gem constrains JSON to 2.x for compatibility with these Rails versions. The development suite uses SQLite and Minitest.
 
+The published release is 0.1.0. This checkout prepares 0.2.0 with validation rules, advanced queries, sorting, and collection preloading. Use a local path or the GitHub dependency below to try these additions before publication.
+
 ## Install in a Rails application
 
 Add the gem to your application's `Gemfile`:
@@ -22,6 +24,12 @@ bin/rails db:migrate
 
 For local gem development, replace the dependency with `gem "eav_field", path: "../eav_field"`, adjusting the path to this checkout.
 
+To use the upcoming 0.2.0 code from GitHub:
+
+```ruby
+gem "eav_field", github: "Mouados-byte/eav_field", branch: "main"
+```
+
 The generator creates `eav_field_definitions` and `eav_field_values`. Owner IDs use `bigint` by default. For PostgreSQL UUID owners, generate with `--entity-id-type=uuid`; for string IDs, use `--entity-id-type=string`. All participating models must have IDs compatible with the selected column type.
 
 Opt in on any existing model:
@@ -32,6 +40,17 @@ class Product < ApplicationRecord
 end
 ```
 
+## Upgrade an existing 0.1.0 installation
+
+After updating the dependency to the 0.2.0 code, generate and run the additive migration:
+
+```sh
+bin/rails generate eav_field:upgrade
+bin/rails db:migrate
+```
+
+This adds the nullable `validation_rules` JSON column and preserves definitions and values. Existing definitions start without extra rules. Fresh installations already include this column; run only `eav_field:install` for those. Roll back the upgrade migration before switching the application back to 0.1.0. Rolling back discards validation rules but preserves stored values.
+
 ## Define and use fields
 
 Create definitions after migrating, for example in a Rails console or data migration:
@@ -85,7 +104,43 @@ product.save!
 product.eav_fields[:color] # => "black"
 ```
 
-Definition names, types, and entity scopes are immutable after creation. Defaults and `required` flags can be updated through `Product.eav_field_definitions`. Adding a required definition affects validation of existing owners on their next save.
+Definition names, types, and entity scopes are immutable after creation. Defaults, `required` flags, and `validation_rules` can be updated through `Product.eav_field_definitions`. Adding or tightening a rule affects existing owners on their next validation; it does not rewrite stored values.
+
+## Validation rules
+
+```ruby
+Product.define_eav_field(:weight, type: :decimal, min: 0, max: "100.5")
+Product.define_eav_field(:size, type: :string, choices: %w[small medium large])
+Product.define_eav_field(:serial, type: :string, min_length: 3, max_length: 20)
+Product.define_eav_field(:released_on, type: :date, min: "2026-01-01")
+
+product.eav_fields[:weight] = -1
+product.valid?                      # => false
+product.errors["eav_fields.weight"] # => ["must be greater than or equal to 0"]
+```
+
+`min` and `max` are inclusive and support integer, decimal, date, and datetime fields. `min_length` and `max_length` count characters in strings and text. `choices` accepts a nonempty array of values matching the field's type; each choice must also satisfy the bounds and length rules. Optional `nil` values skip these rules; use `required: true` to reject missing values. Unknown or incompatible rules and defaults that violate rules are rejected when saving the definition.
+
+Type errors still raise immediately on assignment. Rule violations participate in owner validation, so forms can display errors before saving. Direct value saves also enforce the persisted rules. To edit rules, replace the definition's hash:
+
+```ruby
+Product.eav_field_definitions.find_by!(name: "weight")
+  .update!(validation_rules: { min: 1, max: 200 })
+```
+
+Keep custom validators in model code. They run when validating an owner, receive its effective value including defaults, and can add ordinary Rails errors:
+
+```ruby
+class Product < ApplicationRecord
+  has_eav_fields
+
+  validate_eav_field(:quantity) do |record, value|
+    record.errors.add("eav_fields.quantity", "must be even") if value && value.odd?
+  end
+end
+```
+
+Multiple blocks accumulate and are inherited by subclasses. Registering a block does not create a definition; define the field separately after migration. Custom blocks run through owner validation, so save the owner when using them.
 
 ## Query fields
 
@@ -93,9 +148,47 @@ Definition names, types, and entity scopes are immutable after creation. Default
 Product.with_eav_field(:color, "blue")
 Product.where(name: "Chair").with_eav_field(:weight, "1.25")
 Product.with_eav_field(:color, "blue").with_eav_field(:available, false)
+Product.with_eav_field(:weight, gt: "1.25", lte: "10")
+Product.with_eav_field(:weight, 1...10)
+Product.with_eav_field(:color, in: %w[blue green])
+Product.with_eav_field(:color, missing: true)
+Product.order_by_eav_field(:weight, :asc, nulls: :last).order(:id)
+```
+
+These return chainable Active Record relations and use persisted values. Matching defaults include owners without a stored override; explicit null overrides remain distinct from non-null defaults. Filter inputs are type-cast but need not satisfy validation rules: `gt: 0` is valid even if a field requires `min: 5`.
+
+| Operator | Behavior |
+| --- | --- |
+| `eq`, `not_eq` | Equality and inequality; a positional value means `eq`. |
+| `gt`, `gte`, `lt`, `lte` | Numeric, date, or datetime comparisons. |
+| `in` | Match a typed array of values; `nil` matches null values; an empty array matches nothing. |
+| `between` | A Ruby range or inclusive `[lower, upper]` pair; exclusive and open-ended ranges are supported. A positional range means `between`. |
+| `missing` | `true` means no stored row, even when a default exists; `false` means a stored row exists, including an explicit null. Use this operator alone. |
+
+Multiple operators in one call use AND. Supply either a positional value or keyword operators. Inequality follows SQL null semantics: `not_eq: "blue"` excludes nulls; `not_eq: nil` selects non-null effective values. JSON supports `missing` filters; other comparisons and sorting raise `EavField::UnsupportedQuery` because their behavior differs between adapters.
+
+Sorting uses effective defaults, preserves explicit null overrides, and supports `:asc`/`:desc` and `nulls: :first`/`:last`. It appends to existing ordering. Add a normal column such as `.order(:id)` to break ties. String ordering follows the database's collation.
+
+## Efficient loading and definition caching
+
+```ruby
+products = Product.preload_eav_fields(Product.where(name: "Chair").limit(100))
+products.each do |product|
+  puts product.eav_fields[:color]
+  puts product.eav_fields[:weight]
+end
+
+Product.with_eav_definition_cache do
+  Product.with_eav_field(:color, "blue").count
+  Product.with_eav_field(:weight, gt: 1).count
+end
 ```
 
-These return chainable Active Record relations with typed equality comparisons. Matching defaults include owners without a stored override; explicit null overrides remain distinct from non-null defaults. Queries use persisted values. JSON equality raises `EavField::UnsupportedQuery` because JSON comparisons differ between database adapters.
+`preload_eav_fields` returns an array, batches value loading, and shares one definition snapshot across the records. Repeated reads of preloaded fields require no queries. Pass owners from one model or its STI subclasses; unsaved changes are preserved. For large exports, call it for each `find_in_batches` batch.
+
+Owners cache their definition snapshot on first use. `with_eav_definition_cache` additionally shares definitions within an execution-local block, including class-level lookups. Nested blocks share the same cache, which is removed when the outer block exits.
+
+Definition creates, updates, deletes, commits, and rollbacks through Active Record callbacks invalidate snapshots in the current process. Loaded owners retain snapshots of changes made by another process, just as loaded associations do. Refresh them with `product.reload_eav_field_definitions` or `product.reload`; call `Product.reset_eav_field_cache` after bulk changes that bypass callbacks. These caches do not retain definition records globally across requests or database connections.
 
 ## Persistence and lifecycle
 
@@ -117,7 +210,7 @@ bundle exec rake test       # Minitest, including real Rails installation and ro
 bundle exec rubocop         # Lint and check formatting.
 bundle exec rubocop -a      # Apply safe formatting corrections.
 bundle exec rake            # Tests and lint together.
-bundle exec rake build      # Build pkg/eav_field-0.1.0.gem.
+bundle exec rake build      # Build pkg/eav_field-0.2.0.gem.
 ```
 
 To check a different Rails series:

data/lib/eav_field/attribute_definition.rb

@@ -13,7 +13,14 @@ module EavField
     validates :required, inclusion: { in: [ true, false ] }
 
     before_validation :normalize_default
+    before_validation :normalize_validation_rules
     validate :identity_is_immutable, on: :update
+    validate :default_satisfies_rules
+
+    after_save :invalidate_definition_cache
+    after_destroy :invalidate_definition_cache
+    after_commit :invalidate_definition_cache
+    after_rollback :invalidate_definition_cache
 
     def cast(value)
       Types.cast(data_type, value)
@@ -23,8 +30,35 @@ module EavField
       cast(default_value)
     end
 
+    def validation_errors(value)
+      errors = ValidationRules.new(data_type, validation_rules || {}).errors_for(cast(value))
+      errors.unshift("can't be blank") if required? && Types.missing?(value)
+      errors
+    end
+
     private
 
+    def normalize_validation_rules
+      return unless Types::COLUMNS.key?(data_type)
+
+      input = validation_rules.nil? ? {} : validation_rules
+      self.validation_rules = ValidationRules.new(data_type, input).rules
+    rescue InvalidValue => error
+      errors.add(:validation_rules, error.message)
+    end
+
+    def default_satisfies_rules
+      return if default_value.nil? || errors.any? || !Types::COLUMNS.key?(data_type)
+
+      ValidationRules.new(data_type, validation_rules || {}).errors_for(default).each do |message|
+        errors.add(:default_value, message)
+      end
+    end
+
+    def invalidate_definition_cache
+      DefinitionCache.invalidate(entity_type)
+    end
+
     def normalize_default
       return unless Types::COLUMNS.key?(data_type)
 

data/lib/eav_field/definition_cache.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module EavField
+  # Cache records on owners and within explicit blocks, never for an entire process.
+  module DefinitionCache
+    STATE_KEY = :eav_field_definition_cache
+    @versions = Hash.new(0)
+    @mutex = Mutex.new
+
+    class Snapshot
+      def initialize(model)
+        @model = model.base_class
+        @key = DefinitionCache.key(@model.polymorphic_name)
+      end
+
+      def definitions
+        version = DefinitionCache.version(@key)
+        if @version != version
+          @definitions = @model.eav_field_definitions.to_a.index_by(&:name).freeze
+          @version = version
+        end
+        @definitions
+      end
+
+      def find!(name)
+        definitions.fetch(name.to_s) do
+          raise UnknownField, "Unknown EAV field #{name.inspect} for #{@model.name}"
+        end
+      end
+
+      def reload
+        @version = nil
+        definitions
+        self
+      end
+    end
+
+    module_function
+
+    def key(entity_type)
+      [ AttributeDefinition.connection_pool, entity_type ]
+    end
+
+    def version(key)
+      @mutex.synchronize { @versions[key] }
+    end
+
+    def invalidate(entity_type)
+      @mutex.synchronize { @versions[key(entity_type)] += 1 }
+    end
+
+    def fetch(model)
+      cache = ActiveSupport::IsolatedExecutionState[STATE_KEY]
+      return Snapshot.new(model) unless cache
+
+      cache[key(model.polymorphic_name)] ||= Snapshot.new(model)
+    end
+
+    def active?
+      !!ActiveSupport::IsolatedExecutionState[STATE_KEY]
+    end
+
+    def with
+      previous = ActiveSupport::IsolatedExecutionState[STATE_KEY]
+      ActiveSupport::IsolatedExecutionState[STATE_KEY] = previous || {}
+      yield
+    ensure
+      ActiveSupport::IsolatedExecutionState[STATE_KEY] = previous
+    end
+  end
+end

data/lib/eav_field/has_fields.rb

@@ -4,6 +4,10 @@ module EavField
   module HasFields
     extend ActiveSupport::Concern
 
+    included do
+      class_attribute :eav_field_validators, instance_accessor: false, default: {}.freeze
+    end
+
     class_methods do
       def has_eav_fields
         association = reflect_on_association(:eav_values)
@@ -12,7 +16,7 @@ module EavField
 
         has_many :eav_values, -> { includes(:attribute_definition) }, as: :entity,
           class_name: "EavField::Value", inverse_of: :entity, autosave: true, dependent: :destroy
-        validate :validate_required_eav_fields
+        validate :validate_eav_fields
       end
 
       def eav_field_definitions
@@ -20,28 +24,56 @@ module EavField
         AttributeDefinition.where(entity_type: polymorphic_name)
       end
 
-      def define_eav_field(name, type:, required: false, default: nil)
+      def define_eav_field(name, type:, required: false, default: nil, **rules)
         eav_field_definitions.create!(name: name.to_s, data_type: type.to_s,
-          required: required, default_value: default)
+          required: required, default_value: default, validation_rules: rules)
       end
 
       def find_eav_field!(name)
+        return DefinitionCache.fetch(self).find!(name) if DefinitionCache.active?
+
         eav_field_definitions.find_by(name: name.to_s) ||
           raise(UnknownField, "Unknown EAV field #{name.inspect} for #{self.name}")
       end
 
-      def with_eav_field(name, value)
-        definition = find_eav_field!(name)
-        raise UnsupportedQuery, "JSON field equality is not portable across databases" if definition.data_type == "json"
+      def with_eav_field(name, value = Query::UNSET, **conditions)
+        Query.new(self, find_eav_field!(name)).filter(value, conditions)
+      end
+
+      def order_by_eav_field(name, direction = :asc, nulls: :last)
+        Query.new(self, find_eav_field!(name)).order(direction, nulls: nulls)
+      end
+
+      def validate_eav_field(name, &validator)
+        raise ArgumentError, "A validator block is required" unless validator
+
+        validators = [ *eav_field_validators[name.to_s], validator ].freeze
+        self.eav_field_validators = eav_field_validators.merge(name.to_s => validators).freeze
+      end
+
+      def with_eav_definition_cache(&block)
+        ensure_eav_fields_enabled!
+        DefinitionCache.with(&block)
+      end
+
+      def reset_eav_field_cache
+        ensure_eav_fields_enabled!
+        DefinitionCache.invalidate(polymorphic_name)
+      end
 
-        cast_value = definition.cast(value)
-        entries = Value.where(attribute_definition_id: definition.id, entity_type: polymorphic_name)
-        matching = entries.where(Types.column_for(definition.data_type) => cast_value).select(:entity_id)
-        result = where(primary_key => matching)
-        if cast_value == definition.default
-          result = result.or(where.not(primary_key => entries.select(:entity_id)))
+      def preload_eav_fields(records)
+        ensure_eav_fields_enabled!
+        records = records.to_a
+        unless records.all? { |record| record.is_a?(base_class) }
+          raise ArgumentError, "Records must belong to #{base_class.name}"
         end
-        result
+        return records if records.empty?
+
+        snapshot = DefinitionCache.fetch(self)
+        snapshot.definitions
+        ActiveRecord::Associations::Preloader.new(records: records, associations: :eav_values).call
+        records.each { |record| record.instance_variable_set(:@eav_definition_snapshot, snapshot) }
+        records
       end
 
       private
@@ -63,27 +95,27 @@ module EavField
       raise ArgumentError, "eav_fields must be a hash" unless fields.respond_to?(:each_pair)
 
       assignments = fields.each_pair.map do |name, value|
-        definition = self.class.find_eav_field!(name)
+        definition = eav_definition_snapshot.find!(name)
         [ definition, definition.cast(value) ]
       end
       assignments.each { |definition, value| assign_eav_value(definition, value) }
     end
 
     def read_eav_field(name)
-      definition = self.class.find_eav_field!(name)
+      definition = eav_definition_snapshot.find!(name)
       entry = eav_entry_for(definition)
       entry ? entry.value : definition.default
     end
 
     def write_eav_field(name, value)
-      definition = self.class.find_eav_field!(name)
+      definition = eav_definition_snapshot.find!(name)
       assign_eav_value(definition, definition.cast(value))
       value
     end
 
     # Removing an override restores the definition's default on the next read.
     def delete_eav_field(name)
-      definition = self.class.find_eav_field!(name)
+      definition = eav_definition_snapshot.find!(name)
       entry = eav_entry_for(definition)
       previous_value = entry ? entry.value : definition.default
       entry&.mark_for_destruction
@@ -93,14 +125,28 @@ module EavField
     def eav_fields_snapshot
       entries = eav_values.reject { |entry| entry.marked_for_destruction? || entry.destroyed? }
         .index_by(&:attribute_definition_id)
-      self.class.eav_field_definitions.each_with_object({}.with_indifferent_access) do |definition, fields|
+      eav_definition_snapshot.definitions.each_value.with_object({}.with_indifferent_access) do |definition, fields|
         entry = entries[definition.id]
         fields[definition.name] = entry ? entry.value : definition.default
       end
     end
 
+    def reload(...)
+      super.tap { @eav_definition_snapshot&.reload }
+    end
+
+    def reload_eav_field_definitions
+      eav_definition_snapshot.reload
+      self
+    end
+
     private
 
+    def eav_definition_snapshot
+      self.class.send(:ensure_eav_fields_enabled!)
+      @eav_definition_snapshot ||= DefinitionCache.fetch(self.class)
+    end
+
     def eav_entry_for(definition)
       eav_values.detect do |entry|
         entry.attribute_definition_id == definition.id && !entry.marked_for_destruction? && !entry.destroyed?
@@ -116,14 +162,20 @@ module EavField
         entry = deleted_entry.reload if deleted_entry
       end
       entry ||= eav_values.build(attribute_definition: definition)
+      entry.attribute_definition = definition
       entry.value = value
     end
 
-    def validate_required_eav_fields
-      self.class.eav_field_definitions.where(required: true).each do |definition|
+    def validate_eav_fields
+      eav_definition_snapshot.definitions.each_value do |definition|
         entry = eav_entry_for(definition)
         value = entry ? entry.value : definition.default
-        errors.add("eav_fields.#{definition.name}", "can't be blank") if Types.missing?(value)
+        definition.validation_errors(value).each do |message|
+          errors.add("eav_fields.#{definition.name}", message)
+        end
+        Array(self.class.eav_field_validators[definition.name]).each do |validator|
+          validator.call(self, value)
+        end
       end
     end
   end

data/lib/eav_field/query.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module EavField
+  class Query
+    UNSET = Object.new.freeze
+    OPERATORS = %i[ eq not_eq gt gte lt lte in between missing ].freeze
+
+    def initialize(model, definition)
+      @model = model
+      @definition = definition
+      @scope = model.all
+      @entries = Value.where(attribute_definition_id: definition.id, entity_type: model.polymorphic_name)
+      @column = Value.arel_table[Types.column_for(definition.data_type)]
+    end
+
+    def filter(value, conditions)
+      conditions = normalize_conditions(value, conditions)
+      if conditions.key?(:missing)
+        unless conditions.size == 1 && [ true, false ].include?(conditions[:missing])
+          raise UnsupportedQuery, "missing must be a boolean and used on its own"
+        end
+        ids = @entries.select(:entity_id)
+        return conditions[:missing] ? @scope.where.not(@model.primary_key => ids) : @scope.where(@model.primary_key => ids)
+      end
+      ensure_scalar!
+
+      predicates = []
+      default_predicates = []
+      default = Arel::Nodes.build_quoted(@definition.default, @column)
+      conditions.each do |operator, input|
+        predicates << predicate_for(@column, operator, input)
+        default_predicates << predicate_for(default, operator, input)
+      end
+      matching = @entries.where(predicates.reduce(&:and)).select(:entity_id)
+      result = @scope.where(@model.primary_key => matching)
+      # Evaluate fallback defaults in SQL using the same operators as stored values.
+      missing = @scope.where.not(@model.primary_key => @entries.select(:entity_id))
+        .where(default_predicates.reduce(&:and))
+      result.or(missing)
+    end
+
+    def order(direction, nulls:)
+      ensure_scalar!
+      direction = direction.to_s
+      nulls = nulls.to_s
+      raise UnsupportedQuery, "Direction must be asc or desc" unless %w[ asc desc ].include?(direction)
+      raise UnsupportedQuery, "nulls must be first or last" unless %w[ first last ].include?(nulls)
+
+      owner = @model.arel_table
+      values = Value.arel_table.alias("eav_sort_#{@definition.id}")
+      join = owner.join(values, Arel::Nodes::OuterJoin).on(
+        values[:entity_id].eq(owner[@model.primary_key])
+          .and(values[:entity_type].eq(@model.polymorphic_name))
+          .and(values[:attribute_definition_id].eq(@definition.id))
+      ).join_sources
+      default = Arel::Nodes.build_quoted(@definition.default, @column)
+      effective = Arel::Nodes::Case.new.when(values[:id].eq(nil)).then(default)
+        .else(values[Types.column_for(@definition.data_type)])
+      null_order = Arel::Nodes::Case.new.when(effective.eq(nil)).then(nulls == "last" ? 1 : 0)
+        .else(nulls == "last" ? 0 : 1).asc
+      @scope.joins(join).order(null_order, direction == "asc" ? effective.asc : effective.desc)
+    end
+
+    private
+
+    def normalize_conditions(value, conditions)
+      unless value.equal?(UNSET)
+        raise UnsupportedQuery, "Pass a value or operators, not both" if conditions.any?
+
+        conditions = value.is_a?(Range) ? { between: value } : { eq: value }
+      end
+      unknown = conditions.keys - OPERATORS
+      if conditions.empty? || unknown.any?
+        raise UnsupportedQuery, "Supported operators: #{OPERATORS.join(', ')}"
+      end
+      conditions
+    end
+
+    def ensure_scalar!
+      raise UnsupportedQuery, "JSON field comparisons and sorting are not portable across databases" if @definition.data_type == "json"
+    end
+
+    def predicate_for(column, operator, input)
+      case operator
+      when :eq, :not_eq
+        value = @definition.cast(input)
+        operator == :eq ? column.eq(value) : column.not_eq(value)
+      when :in
+        inclusion_predicate(column, input)
+      when :between
+        range_predicate(column, input)
+      else
+        comparison_predicate(column, operator, input)
+      end
+    end
+
+    def inclusion_predicate(column, input)
+      raise UnsupportedQuery, "in requires an array" unless input.is_a?(Array)
+
+      values = input.map { |value| @definition.cast(value) }.uniq
+      predicate = column.in(values.compact)
+      predicate = predicate.or(column.eq(nil)) if values.include?(nil)
+      predicate
+    end
+
+    def comparison_predicate(column, operator, input)
+      ensure_ordered!
+      value = @definition.cast(input)
+      raise UnsupportedQuery, "Comparison bounds cannot be nil" if value.nil?
+
+      arel_operator = { gt: :gt, gte: :gteq, lt: :lt, lte: :lteq }.fetch(operator)
+      column.public_send(arel_operator, value)
+    end
+
+    def range_predicate(column, input)
+      ensure_ordered!
+      unless input.is_a?(Range) || (input.is_a?(Array) && input.size == 2)
+        raise UnsupportedQuery, "between requires a range or a two-element array"
+      end
+
+      lower, upper = input.is_a?(Range) ? [ input.begin, input.end ] : input
+      raise UnsupportedQuery, "A range needs at least one bound" if lower.nil? && upper.nil?
+
+      conditions = []
+      conditions << comparison_predicate(column, :gte, lower) unless lower.nil?
+      upper_operator = input.is_a?(Range) && input.exclude_end? ? :lt : :lte
+      conditions << comparison_predicate(column, upper_operator, upper) unless upper.nil?
+      conditions.reduce(&:and)
+    end
+
+    def ensure_ordered!
+      unless ValidationRules::ORDERED_TYPES.include?(@definition.data_type)
+        raise UnsupportedQuery, "Ordered comparisons require a numeric, date, or datetime field"
+      end
+    end
+  end
+end

data/lib/eav_field/railtie.rb

@@ -4,6 +4,7 @@ module EavField
   class Railtie < Rails::Railtie
     generators do
       require "generators/eav_field/install/install_generator"
+      require "generators/eav_field/upgrade/upgrade_generator"
     end
   end
 end

data/lib/eav_field/validation_rules.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module EavField
+  class ValidationRules
+    ORDERED_TYPES = %w[ integer decimal date datetime ].freeze
+    KEYS = %w[ min max min_length max_length choices ].freeze
+
+    attr_reader :rules
+
+    def initialize(type, input)
+      @type = type.to_s
+      raise InvalidValue, "Validation rules must be a hash" unless input.is_a?(Hash)
+
+      @rules = input.transform_keys(&:to_s)
+      unknown = @rules.keys - KEYS
+      raise InvalidValue, "Unknown validation rules: #{unknown.join(', ')}" if unknown.any?
+
+      normalize_bounds
+      normalize_lengths
+      normalize_choices
+    end
+
+    def errors_for(value)
+      return [] if value.nil?
+
+      errors = constraint_errors(value)
+      if rules.key?("choices") && !rules["choices"].any? { |choice| Types.cast(@type, choice) == value }
+        errors << "is not included in the allowed choices"
+      end
+      errors
+    end
+
+    private
+
+    def constraint_errors(value)
+      return [] if value.nil?
+
+      errors = []
+      if rules.key?("min") && value < Types.cast(@type, rules["min"])
+        errors << "must be greater than or equal to #{rules['min']}"
+      end
+      if rules.key?("max") && value > Types.cast(@type, rules["max"])
+        errors << "must be less than or equal to #{rules['max']}"
+      end
+      if rules.key?("min_length") && value.length < rules["min_length"]
+        errors << "is too short (minimum is #{rules['min_length']} characters)"
+      end
+      if rules.key?("max_length") && value.length > rules["max_length"]
+        errors << "is too long (maximum is #{rules['max_length']} characters)"
+      end
+      errors
+    end
+
+    def normalize_bounds
+      bounds = rules.keys & %w[ min max ]
+      return if bounds.empty?
+      raise InvalidValue, "Minimum and maximum require a numeric, date, or datetime field" unless ORDERED_TYPES.include?(@type)
+
+      bounds.each do |key|
+        raise InvalidValue, "#{key} cannot be nil" if rules[key].nil?
+
+        rules[key] = Types.dump(@type, rules[key])
+      end
+      if bounds.size == 2 && Types.cast(@type, rules["min"]) > Types.cast(@type, rules["max"])
+        raise InvalidValue, "Minimum cannot exceed maximum"
+      end
+    end
+
+    def normalize_lengths
+      lengths = rules.keys & %w[ min_length max_length ]
+      return if lengths.empty?
+      raise InvalidValue, "Length rules require a string or text field" unless %w[ string text ].include?(@type)
+
+      lengths.each do |key|
+        unless rules[key].is_a?(Integer) && rules[key] >= 0
+          raise InvalidValue, "#{key} must be a nonnegative integer"
+        end
+      end
+      if lengths.size == 2 && rules["min_length"] > rules["max_length"]
+        raise InvalidValue, "Minimum length cannot exceed maximum length"
+      end
+    end
+
+    def normalize_choices
+      return unless rules.key?("choices")
+      unless rules["choices"].is_a?(Array) && !rules["choices"].empty?
+        raise InvalidValue, "Choices must be a nonempty array"
+      end
+
+      rules["choices"] = rules["choices"].map { |choice| Types.dump(@type, choice) }.uniq
+      if rules["choices"].any? { |choice| constraint_errors(Types.cast(@type, choice)).any? }
+        raise InvalidValue, "Choices must satisfy the field's bounds and length rules"
+      end
+    end
+  end
+end

data/lib/eav_field/value.rb

@@ -38,11 +38,13 @@ module EavField
       if Types::COLUMNS.values.any? { |column| column != active_column && !self[column].nil? }
         errors.add(:value, "must use only the column matching its field type")
       end
-      attribute_definition.cast(value)
-      if attribute_definition.required? && Types.missing?(value)
-        errors.add(:value, "can't be blank")
+      definition = if entity && entity.class.polymorphic_name == attribute_definition.entity_type
+        entity.send(:eav_definition_snapshot).find!(attribute_definition.name)
+      else
+        attribute_definition
       end
-    rescue InvalidValue => error
+      definition.validation_errors(value).each { |message| errors.add(:value, message) }
+    rescue InvalidValue, UnknownField => error
       errors.add(:value, error.message)
     end
   end

data/lib/eav_field/version.rb

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

data/lib/eav_field.rb

@@ -8,9 +8,12 @@ require "active_support/core_ext/hash/indifferent_access"
 require "eav_field/version"
 require "eav_field/errors"
 require "eav_field/types"
+require "eav_field/validation_rules"
 require "eav_field/attribute_definition"
+require "eav_field/definition_cache"
 require "eav_field/value"
 require "eav_field/field_set"
+require "eav_field/query"
 require "eav_field/has_fields"
 
 ActiveSupport.on_load(:active_record) do

data/lib/generators/eav_field/install/templates/create_eav_field_tables.rb.tt

@@ -8,6 +8,7 @@ class CreateEavFieldTables < ActiveRecord::Migration[<%= migration_version %>]
       t.string :data_type, limit: 20, null: false
       t.boolean :required, default: false, null: false
       t.json :default_value
+      t.json :validation_rules
       t.timestamps
     end
 

data/lib/generators/eav_field/upgrade/templates/add_eav_field_validation_rules.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class AddEavFieldValidationRules < ActiveRecord::Migration[<%= migration_version %>]
+  # SQLite cannot disable foreign keys inside a transaction. Its table rebuild
+  # would otherwise cascade-delete values when rolling back this column.
+  disable_ddl_transaction!
+
+  def up
+    add_column :eav_field_definitions, :validation_rules, :json
+  end
+
+  def down
+    if connection.adapter_name == "SQLite"
+      if connection.transaction_open?
+        raise ActiveRecord::IrreversibleMigration, "Run this SQLite rollback outside an existing transaction"
+      end
+
+      connection.disable_referential_integrity do
+        remove_column :eav_field_definitions, :validation_rules, :json
+      end
+    else
+      remove_column :eav_field_definitions, :validation_rules, :json
+    end
+  end
+end

data/lib/generators/eav_field/upgrade/upgrade_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record/migration"
+
+module EavField
+  module Generators
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Upgrade EavField 0.1 tables to support persisted validation rules."
+
+      def copy_migration
+        migration_template "add_eav_field_validation_rules.rb.tt", "db/migrate/add_eav_field_validation_rules.rb"
+      end
+
+      private
+
+      def migration_version
+        "#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eav_field
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mouad Imam
@@ -82,15 +82,20 @@ files:
 - README.md
 - lib/eav_field.rb
 - lib/eav_field/attribute_definition.rb
+- lib/eav_field/definition_cache.rb
 - lib/eav_field/errors.rb
 - lib/eav_field/field_set.rb
 - lib/eav_field/has_fields.rb
+- lib/eav_field/query.rb
 - lib/eav_field/railtie.rb
 - lib/eav_field/types.rb
+- lib/eav_field/validation_rules.rb
 - lib/eav_field/value.rb
 - lib/eav_field/version.rb
 - lib/generators/eav_field/install/install_generator.rb
 - lib/generators/eav_field/install/templates/create_eav_field_tables.rb.tt
+- lib/generators/eav_field/upgrade/templates/add_eav_field_validation_rules.rb.tt
+- lib/generators/eav_field/upgrade/upgrade_generator.rb
 homepage: https://github.com/Mouados-byte/eav_field
 licenses:
 - MIT
@@ -100,7 +105,7 @@ metadata:
   source_code_uri: https://github.com/Mouados-byte/eav_field
   documentation_uri: https://github.com/Mouados-byte/eav_field#readme
   bug_tracker_uri: https://github.com/Mouados-byte/eav_field/issues
-  changelog_uri: https://github.com/Mouados-byte/eav_field/blob/v0.1.0/CHANGELOG.md
+  changelog_uri: https://github.com/Mouados-byte/eav_field/blob/v0.2.0/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: