typed_eav 0.1.0

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    class Text < Base
+      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/text_array.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    class TextArray < Base
+      value_column :json_value
+      # :contains was declared here but QueryBuilder implements it with
+      # Arel `matches` (SQL LIKE), which doesn't work against jsonb arrays.
+      # Use :any_eq for element membership (it maps to JSONB @>).
+      operators :any_eq, :all_eq, :is_null, :is_not_null
+
+      store_accessor :options, :min_size, :max_size
+
+      def array_field? = true
+
+      def cast(raw)
+        return [nil, false] if raw.nil?
+
+        # Drop nil/blank/whitespace-only elements so required-check and size
+        # validation compare against real content rather than HTML form stubs
+        # (e.g. an empty row in a dynamic list posts as "" or "   ").
+        elements = Array(raw).filter_map do |v|
+          next nil if v.nil?
+
+          s = v.to_s
+          s.strip.empty? ? nil : s
+        end
+        [elements.presence, false]
+      end
+
+      def validate_typed_value(record, val)
+        validate_array_size(record, val)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TypedEAV
+  module Field
+    class Url < Base
+      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)
+        [raw&.to_s&.strip, false]
+      end
+
+      def url_format_valid?(val)
+        URL_FORMAT.match?(val)
+      end
+
+      def validate_typed_value(record, val)
+        validate_length(record, val)
+        validate_pattern(record, val) if pattern.present?
+        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

data/app/models/typed_eav/option.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  class Option < ApplicationRecord
+    self.table_name = "typed_eav_options"
+
+    belongs_to :field,
+               class_name: "TypedEAV::Field::Base",
+               inverse_of: :field_options
+
+    validates :label, presence: true
+    validates :value, presence: true, uniqueness: { scope: :field_id }
+
+    scope :sorted, -> { order(sort_order: :asc, label: :asc, id: :asc) }
+
+    after_commit :clear_field_option_cache
+
+    private
+
+    def clear_field_option_cache
+      field&.clear_option_cache!
+    end
+  end
+end

data/app/models/typed_eav/section.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  class Section < ApplicationRecord
+    self.table_name = "typed_eav_sections"
+
+    has_many :fields,
+             class_name: "TypedEAV::Field::Base",
+             inverse_of: :section,
+             dependent: :nullify
+
+    validates :name, presence: true
+    validates :code, presence: true, uniqueness: { scope: %i[entity_type scope] }
+    validates :entity_type, presence: true
+
+    scope :active, -> { where(active: true) }
+    # Mirror Field::Base.for_entity: scoped rows plus global (scope=NULL) rows
+    # so global sections are visible across partitions while scoped sections
+    # stay isolated. Pass the section's scope key as a string.
+    scope :for_entity, lambda { |entity_type, scope: nil|
+      where(entity_type: entity_type, scope: [scope, nil].uniq)
+    }
+    scope :sorted, -> { order(sort_order: :asc, name: :asc) }
+  end
+end

data/app/models/typed_eav/value.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  class Value < ApplicationRecord
+    self.table_name = "typed_eav_values"
+
+    # ── Associations ──
+
+    belongs_to :entity, polymorphic: true, inverse_of: :typed_values
+    belongs_to :field,
+               class_name: "TypedEAV::Field::Base",
+               inverse_of: :values
+
+    # ── Validations ──
+
+    validates :field, uniqueness: { scope: %i[entity_type entity_id] }
+    validate :validate_value
+    validate :validate_entity_matches_field
+    validate :validate_field_scope_matches_entity
+    validate :validate_json_size
+
+    # ── Value access ──
+    #
+    # The magic here is that we delegate to the correct typed column
+    # based on what the field type declares. ActiveRecord handles all
+    # casting through the column's type (schema-inferred).
+    #
+    # So `value = "42"` on an integer field writes 42 to integer_value,
+    # and `value` reads it back as a Ruby Integer. No custom caster needed
+    # for storage - the database column type IS the caster.
+
+    def value
+      return nil unless field
+
+      self[value_column]
+    end
+
+    def value=(val)
+      if field
+        # Cast through the field type, then write to the native column.
+        # Rails will further cast via the column type on save.
+        casted, invalid = field.cast(val)
+        self[value_column] = casted
+        @cast_was_invalid = invalid
+      else
+        # Field not yet assigned - stash for later
+        @pending_value = val
+      end
+    end
+
+    # Which column this value lives in
+    def value_column
+      field.class.value_column
+    end
+
+    # ── Callbacks ──
+
+    after_initialize :apply_pending_value
+
+    private
+
+    def apply_pending_value
+      return unless @pending_value && field
+
+      self.value = @pending_value
+      @pending_value = nil
+    end
+
+    def validate_value
+      return unless field
+
+      if @cast_was_invalid
+        errors.add(:value, :invalid)
+        @cast_was_invalid = false
+        return
+      end
+
+      val = value
+
+      # Required check. Treat blank strings and empty arrays as missing so
+      # required fields can't be saved as effectively empty.
+      if field.required? && blank_typed_value?(val)
+        errors.add(:value, :blank)
+        return
+      end
+
+      return if val.nil?
+
+      # Delegate to the field type's own validation (polymorphic dispatch).
+      # Each Field::* class implements validate_typed_value(record, val)
+      # with its type-specific constraints; shared helpers live on Field::Base.
+      field.validate_typed_value(self, val)
+    end
+
+    def blank_typed_value?(val)
+      return true if val.nil?
+      # Whitespace-only strings count as blank even inside arrays so a
+      # required TextArray can't slip through with `[" "]` or `["", nil]`.
+      return val.all? { |e| blank_array_element?(e) } if val.is_a?(Array)
+      return val.strip.empty? if val.is_a?(String)
+
+      false
+    end
+
+    def blank_array_element?(element)
+      return true if element.nil?
+      return element.strip.empty? if element.is_a?(String)
+
+      element.respond_to?(:empty?) && element.empty?
+    end
+
+    MAX_JSON_BYTES = 1_000_000 # 1MB
+    private_constant :MAX_JSON_BYTES
+
+    def validate_json_size
+      return unless field && value_column == :json_value
+
+      val = self[:json_value]
+      return if val.nil?
+
+      return unless val.to_json.bytesize > MAX_JSON_BYTES
+
+      errors.add(:value, "is too large (maximum 1MB)")
+    end
+
+    def validate_entity_matches_field
+      return unless field && entity_type
+      return if entity_type == field.entity_type
+
+      errors.add(:entity, :invalid)
+    end
+
+    # Cross-tenant guard: when nested attributes let a client submit a raw
+    # field_id, the entity_type match above is not enough — another tenant's
+    # field with the same entity_type but a different scope would still
+    # attach. Reject unless the field's scope matches the entity's
+    # typed_eav_scope (globals, scope=NULL, remain shared).
+    def validate_field_scope_matches_entity
+      return unless field && entity
+      return if field.scope.nil?
+      return unless entity.respond_to?(:typed_eav_scope)
+
+      entity_scope = entity.typed_eav_scope
+      return if entity_scope && field.scope == entity_scope.to_s
+
+      errors.add(:field, :invalid)
+    end
+  end
+end

data/db/migrate/20260330000000_create_typed_eav_tables.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+class CreateTypedEAVTables < ActiveRecord::Migration[7.1]
+  def change
+    # ──────────────────────────────────────────────────
+    # Sections: optional UI grouping for fields
+    # ──────────────────────────────────────────────────
+    create_table :typed_eav_sections do |t|
+      t.string :name, null: false
+      t.string :code, null: false
+      t.string :entity_type, null: false
+      t.string :scope
+      t.integer :sort_order
+      t.boolean :active, null: false, default: true
+
+      t.timestamps
+
+      # Paired partial unique indexes. PostgreSQL treats NULLs as distinct in
+      # a plain unique index, so a single `[entity_type, code, scope]` index
+      # would allow duplicate global (scope IS NULL) rows. Split into
+      # (scope NOT NULL) and (scope IS NULL) partials to protect both.
+      t.index %i[entity_type code scope],
+              unique: true,
+              where: "scope IS NOT NULL",
+              name: "idx_te_sections_unique_scoped"
+      t.index %i[entity_type code],
+              unique: true,
+              where: "scope IS NULL",
+              name: "idx_te_sections_unique_global"
+      t.index %i[entity_type active], name: "idx_te_sections_entity_active"
+    end
+
+    # ──────────────────────────────────────────────────
+    # Field definitions (STI via `type` column)
+    # ──────────────────────────────────────────────────
+    create_table :typed_eav_fields do |t|
+      t.string :name, null: false
+      t.string :type, null: false # STI: TypedEAV::Field::Integer, etc.
+      t.string :entity_type, null: false     # polymorphic target model name
+      t.string :scope                        # optional tenant/context scoping
+
+      t.references :section, foreign_key: { to_table: :typed_eav_sections, on_delete: :nullify }
+
+      t.boolean :required, null: false, default: false
+      t.integer :sort_order
+
+      # Field-type-specific configuration (min/max/precision/allowed_values/etc.)
+      t.jsonb :options, null: false, default: {}
+
+      # Default value stored in the matching typed column format
+      t.jsonb :default_value_meta, null: false, default: {}
+
+      t.timestamps
+
+      # Paired partial unique indexes — see sections table comment for why
+      # scope=NULL rows need their own partial index on PostgreSQL.
+      t.index %i[name entity_type scope],
+              unique: true,
+              where: "scope IS NOT NULL",
+              name: "idx_te_fields_unique_scoped"
+      t.index %i[name entity_type],
+              unique: true,
+              where: "scope IS NULL",
+              name: "idx_te_fields_unique_global"
+      t.index :entity_type
+      t.index %i[entity_type scope sort_order name], name: "idx_te_fields_lookup"
+    end
+
+    # ──────────────────────────────────────────────────
+    # Options for select/enum fields
+    # ──────────────────────────────────────────────────
+    create_table :typed_eav_options do |t|
+      t.references :field, null: false, foreign_key: { to_table: :typed_eav_fields, on_delete: :cascade }
+      t.string :label, null: false
+      t.string :value, null: false
+      t.integer :sort_order
+
+      t.timestamps
+
+      t.index %i[field_id value], unique: true, name: "idx_te_options_field_value"
+    end
+
+    # ──────────────────────────────────────────────────
+    # Values: one row per entity+field, typed columns
+    # ──────────────────────────────────────────────────
+    create_table :typed_eav_values do |t|
+      t.references :entity, polymorphic: true, null: false, index: true
+      t.references :field, null: false, foreign_key: { to_table: :typed_eav_fields, on_delete: :cascade }
+
+      # ── Typed storage columns ──
+      # All value columns are nullable on purpose: only one is populated per
+      # row (the one matching the field's type), and a NULL in the others is
+      # the "this column doesn't apply" marker. The Rails/ThreeStateBooleanColumn
+      # warning doesn't apply to EAV-style tables.
+      t.text     :string_value
+      t.text     :text_value
+      t.boolean  :boolean_value # rubocop:disable Rails/ThreeStateBooleanColumn
+      t.bigint   :integer_value
+      t.decimal  :decimal_value, precision: 30, scale: 10
+      t.date     :date_value
+      t.datetime :datetime_value
+      t.jsonb    :json_value
+
+      t.timestamps
+
+      # Uniqueness: one value per entity per field
+      t.index %i[entity_type entity_id field_id],
+              unique: true,
+              name: "idx_te_values_entity_field"
+
+      # Query performance: field + typed column indexes (covering for index-only scans)
+      t.index %i[field_id integer_value],  name: "idx_te_values_field_int",  include: %i[entity_id entity_type]
+      t.index %i[field_id decimal_value],  name: "idx_te_values_field_dec",  include: %i[entity_id entity_type]
+      t.index %i[field_id date_value],     name: "idx_te_values_field_date", include: %i[entity_id entity_type]
+      t.index %i[field_id datetime_value], name: "idx_te_values_field_dt",   include: %i[entity_id entity_type]
+      t.index %i[field_id boolean_value],  name: "idx_te_values_field_bool", include: %i[entity_id entity_type]
+      t.index %i[field_id string_value],
+              name: "idx_te_values_field_str",
+              using: :btree,
+              opclass: { string_value: :text_pattern_ops },
+              include: %i[entity_id entity_type]
+
+      # Partial GIN index for JSONB containment (`@>`) used by :any_eq /
+      # :all_eq on array/multi-select fields. NULL-heavy rows (scalar field
+      # values) stay out of the index.
+      t.index :json_value,
+              using: :gin,
+              where: "json_value IS NOT NULL",
+              name: "idx_te_values_json_gin"
+    end
+  end
+end

data/lib/generators/typed_eav/install/install_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TypedEAV
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      namespace "typed_eav:install"
+      source_root File.expand_path("../../..", __dir__)
+
+      desc "Copies TypedEAV migrations to your application"
+
+      def copy_migrations
+        rake "typed_eav:install:migrations"
+      end
+
+      def show_post_install
+        say ""
+        say "TypedEAV installed. Next steps:", :green
+        say ""
+        say "  1. Run migrations:  bin/rails db:migrate"
+        say "  2. Add to a model:  has_typed_eav"
+        say "  3. Generate scaffold: bin/rails generate typed_eav:scaffold"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/typed_eav/scaffold/scaffold_generator.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TypedEAV
+  module Generators
+    class ScaffoldGenerator < ::Rails::Generators::Base
+      namespace "typed_eav:scaffold"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates controller, views, helper, and Stimulus controllers for managing typed fields"
+
+      def copy_controller
+        copy_file "controllers/typed_eav_controller.rb", "app/controllers/typed_eav_controller.rb"
+        copy_file "controllers/concerns/typed_eav_controller_concern.rb",
+                  "app/controllers/concerns/typed_eav_controller_concern.rb"
+      end
+
+      def copy_initializer
+        copy_file "config/initializers/typed_eav.rb", "config/initializers/typed_eav.rb"
+      end
+
+      def copy_helper
+        copy_file "helpers/typed_eav_helper.rb", "app/helpers/typed_eav_helper.rb"
+      end
+
+      def copy_views
+        directory "views", "app/views"
+      end
+
+      def copy_javascript
+        directory "javascript/controllers", "app/javascript/controllers"
+      end
+
+      def add_routes
+        route <<~ROUTES
+          resources :typed_eav_fields, controller: "typed_eav" do
+            resources :field_options, controller: "typed_eav", only: [] do
+              collection do
+                post :add_option
+                delete :remove_option
+              end
+            end
+          end
+        ROUTES
+      end
+
+      def show_post_install
+        say ""
+        say "Scaffold generated. You can now manage fields at /typed_eav_fields", :green
+        say ""
+        say "Next steps:", :yellow
+        say ""
+        say "  1. WIRE THE ADMIN AUTH HOOK (security-critical):", :red
+        say ""
+        say "       Edit app/controllers/typed_eav_controller.rb and replace"
+        say "       `authorize_typed_eav_admin!` with your auth check. The"
+        say "       default returns `head :not_found` (fail-closed). Defining"
+        say "       this method in ApplicationController does NOT override it."
+        say ""
+        say "         def authorize_typed_eav_admin!"
+        say "           return if current_user&.admin?"
+        say "           head :not_found"
+        say "         end"
+        say ""
+        say "  2. Configure ambient scope resolution for multi-tenancy:", :yellow
+        say ""
+        say "       Edit config/initializers/typed_eav.rb and uncomment the"
+        say "       scope_resolver pattern that matches your app (acts_as_tenant"
+        say "       is auto-detected; no config needed if you use it)."
+        say ""
+        say "  3. Include the concern in controllers that use typed-eav",
+            :yellow
+        say "     search params (your host model's controller, usually):",
+            :yellow
+        say ""
+        say "       class ProductsController < ApplicationController"
+        say "         include TypedEAVControllerConcern"
+        say "         helper TypedEAVHelper"
+        say "         ..."
+        say "       end"
+        say ""
+        say "  4. Render typed field inputs in your entity forms:", :yellow
+        say ""
+        say "       <%= render_typed_value_inputs(form: f, record: @record) %>"
+        say ""
+        say "     Permit nested attributes in your host controller", :yellow
+        say "     (the `value: []` form is required for array/multi-select):",
+            :yellow
+        say ""
+        say "       params.require(:contact).permit("
+        say "         :name,"
+        say "         typed_values_attributes: ["
+        say "           :id, :field_id, :_destroy, :value, { value: [] }"
+        say "         ]"
+        say "       )"
+        say ""
+        say "  5. Add a search form to filter entities by typed fields:",
+            :yellow
+        say ""
+        say "       <%= render_typed_eav_search(fields: Model.typed_eav_definitions, url: search_path) %>"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/typed_eav/scaffold/templates/config/initializers/typed_eav.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# TypedEAV configuration.
+#
+# `scope_resolver` is the single integration point for multi-tenancy /
+# partitioning. It's a callable that returns the current partition value
+# (a tenant id, account id, workspace id — whatever your app uses) or nil.
+#
+# Class-level queries like `Contact.where_typed_eav(...)` consult this
+# resolver when no explicit `scope:` kwarg or `TypedEAV.with_scope(...)`
+# block is active. If the resolver returns nil and the model declared
+# `has_typed_eav scope_method: ...`, queries raise
+# `TypedEAV::ScopeRequired` (fail-closed).
+#
+# Pick ONE of the patterns below and uncomment it:
+
+TypedEAV.configure do |c|
+  # --- DEFAULT ---
+  # If the `acts_as_tenant` gem is loaded, the default resolver reads
+  # `ActsAsTenant.current_tenant` with zero configuration. If you use AAT,
+  # no change is needed here.
+
+  # --- Rails CurrentAttributes ---
+  # c.scope_resolver = -> { Current.account&.id }
+
+  # --- Custom Current-like class ---
+  # c.scope_resolver = -> { MyApp::Tenancy.current_workspace_id }
+
+  # --- Subdomain / session / thread-local ---
+  # c.scope_resolver = -> { Thread.current[:org_id] }
+
+  # --- Disable ambient resolution entirely (explicit `scope:` kwarg only) ---
+  # c.scope_resolver = nil
+
+  # --- Fail-closed mode ---
+  # When true (default), scoped-model queries raise if no scope resolves.
+  # Set to false for gradual adoption — when no scope resolves, queries
+  # see ONLY global fields (those defined with `scope: nil`), not other
+  # partitions' fields. To query across all partitions, use the explicit
+  # escape hatch: `TypedEAV.unscoped { ... }`.
+  # c.require_scope = true
+
+  # --- Custom field types ---
+  # c.register_field_type :phone, "MyApp::Fields::Phone"
+end

data/lib/generators/typed_eav/scaffold/templates/controllers/concerns/typed_eav_controller_concern.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module TypedEAVControllerConcern
+  extend ActiveSupport::Concern
+
+  included do
+    helper_method :typed_eav_filter_params
+  end
+
+  # Permitted filter params for search forms.
+  # Expects: params[:f] = [{ n: "field_name", op: "eq", v: "value" }, ...]
+  def typed_eav_filter_params
+    @typed_eav_filter_params ||=
+      params.permit(f: [:n, :name, :op, :operator, :v, :value, { v: [], value: [] }])[:f] || {}
+  end
+
+  private
+
+  # Strip leading blank element from array params (HTML multi-select quirk)
+  def compact_array_param(value)
+    return value unless value.is_a?(Array)
+    value.first == "" ? value[1..] : value
+  end
+end