typed_eav 0.1.0

data/lib/typed_eav/query_builder.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Replaces the per-type Finder class hierarchy from active_fields.
+  #
+  # Because values live in native typed columns, ActiveRecord already knows
+  # the column types from the schema. Arel predicates (eq, gt, lt, matches, etc.)
+  # automatically go through the column's ActiveRecord::Type for casting.
+  #
+  # This means:
+  #   where(integer_value: "42")  ->  Rails casts "42" to 42 automatically
+  #   arel[:date_value].gt(value) ->  Rails casts string dates to Date objects
+  #
+  # No manual CAST() calls. No per-type caster classes for queries.
+  # One module handles all field types.
+  #
+  # Usage:
+  #   QueryBuilder.filter(field, :gt, 42)
+  #   # => ActiveRecord::Relation scoped to matching values
+  #
+  #   QueryBuilder.filter(field, :contains, "hello")
+  #   # => ILIKE query against the field's string_value column
+  #
+  class QueryBuilder
+    class << self
+      # Returns an ActiveRecord::Relation of TypedEAV::Value records
+      # matching the given field, operator, and comparison value.
+      #
+      # The relation is suitable for subquery use:
+      #   Model.where(id: QueryBuilder.filter(field, :gt, 5).select(:entity_id))
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength -- one operator-dispatch case statement; flattening keeps the supported-operators list scannable in one place.
+      def filter(field, operator, value)
+        col = field.class.value_column
+        operator = operator.to_sym
+
+        # Validate operator is supported by this field type
+        supported = field.class.supported_operators
+        unless supported.include?(operator)
+          raise ArgumentError,
+                "Operator :#{operator} is not supported for #{field.class.name}. " \
+                "Supported operators: #{supported.map { |o| ":#{o}" }.join(", ")}"
+        end
+
+        arel_col = values_table[col]
+
+        base = value_scope(field)
+
+        case operator
+        when :eq
+          eq_predicate(base, arel_col, col, value)
+        when :not_eq
+          not_eq_predicate(base, arel_col, col, value)
+        when :gt
+          base.where(arel_col.gt(value))
+        when :gteq
+          base.where(arel_col.gteq(value))
+        when :lt
+          base.where(arel_col.lt(value))
+        when :lteq
+          base.where(arel_col.lteq(value))
+        when :between
+          unless value.respond_to?(:first) && value.respond_to?(:last)
+            raise ArgumentError,
+                  ":between expects a Range or two-element Array"
+          end
+
+          base.where(arel_col.between(value.first..value.last))
+        when :contains
+          base.where(arel_col.matches("%#{sanitize_like(value)}%"))
+        when :not_contains
+          base.where(arel_col.does_not_match("%#{sanitize_like(value)}%"))
+        when :starts_with
+          base.where(arel_col.matches("#{sanitize_like(value)}%"))
+        when :ends_with
+          base.where(arel_col.matches("%#{sanitize_like(value)}"))
+        when :is_null
+          base.where(col => nil)
+        when :is_not_null
+          base.where.not(col => nil)
+        when :any_eq
+          # For json_value arrays: contains the given element
+          base.where("#{col} @> ?", [value].to_json)
+        when :all_eq
+          # For json_value arrays: contains all given elements
+          base.where("#{col} @> ?", Array(value).to_json)
+        else
+          raise ArgumentError, "Unhandled operator: #{operator}"
+        end
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+      # Convenience: returns entity IDs matching the filter.
+      # Useful for subqueries: Model.where(id: QueryBuilder.entity_ids(field, :gt, 5))
+      def entity_ids(field, operator, value)
+        filter(field, operator, value).distinct.select(:entity_id)
+      end
+
+      private
+
+      def values_table
+        TypedEAV::Value.arel_table
+      end
+
+      # Base scope: values for this specific field
+      def value_scope(field)
+        TypedEAV::Value.where(field: field)
+      end
+
+      # NULL-safe equality: AR `where(col => nil)` already emits IS NULL, and
+      # `where(col => true/false)` already emits IS TRUE/FALSE on PG, so the
+      # same `base.where(col => value)` covers booleans and other types.
+      def eq_predicate(base, _arel_col, col, value)
+        base.where(col => value)
+      end
+
+      # NULL-safe inequality: includes NULL rows (they're "not equal" to any value)
+      def not_eq_predicate(base, arel_col, col, value)
+        if value.nil?
+          base.where.not(col => nil)
+        else
+          # NOT col = value OR col IS NULL
+          # Without the OR, NULLs are excluded (SQL tri-valued logic)
+          base.where(arel_col.not_eq(value).or(arel_col.eq(nil)))
+        end
+      end
+
+      def sanitize_like(value)
+        value.to_s.gsub(/[%_\\]/) { |m| "\\#{m}" }
+      end
+    end
+  end
+end

data/lib/typed_eav/registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support/configurable"
+
+module TypedEAV
+  # Registry of entity types (host ActiveRecord models) that have opted
+  # into typed fields via `has_typed_eav`. Tracks optional field-type
+  # restrictions per entity.
+  #
+  # Populated automatically when a host model calls `has_typed_eav`;
+  # read by Field::Base#validate_type_allowed_for_entity to enforce
+  # restrictions on field creation.
+  class Registry
+    include ActiveSupport::Configurable
+
+    config_accessor(:entities) { {} }
+
+    class << self
+      # Register an entity type with optional type restrictions.
+      def register(entity_type, types: nil)
+        entities[entity_type] = { types: types }
+      end
+
+      # All registered entity type names.
+      def entity_types
+        entities.keys
+      end
+
+      # Field-type restrictions for a given entity, or nil if unrestricted.
+      def allowed_types_for(entity_type)
+        entry = entities[entity_type]
+        return nil unless entry
+
+        entry[:types]
+      end
+
+      # Whether a field type class is allowed for an entity.
+      def type_allowed?(entity_type, field_type_class)
+        allowed = allowed_types_for(entity_type)
+        return true if allowed.nil?
+
+        type_name = field_type_class.name.demodulize.underscore.to_sym
+        allowed.include?(type_name)
+      end
+
+      # Clear all registrations (test isolation).
+      def reset!
+        entities.clear
+      end
+    end
+  end
+end

data/lib/typed_eav/version.rb

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

data/lib/typed_eav.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "active_support/inflector"
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym "EAV"
+end
+
+require_relative "typed_eav/version"
+require_relative "typed_eav/engine"
+
+module TypedEAV
+  extend ActiveSupport::Autoload
+
+  autoload :Config
+  autoload :Registry
+  autoload :HasTypedEAV
+  autoload :QueryBuilder
+
+  # Raised when a model declared `has_typed_eav scope_method: ...` but no
+  # scope can be resolved at query time and `config.require_scope` is truthy.
+  class ScopeRequired < StandardError; end
+
+  THREAD_SCOPE_STACK = :typed_eav_scope_stack
+  THREAD_UNSCOPED    = :typed_eav_unscoped
+  private_constant :THREAD_SCOPE_STACK, :THREAD_UNSCOPED
+
+  class << self
+    def config
+      yield Config if block_given?
+      Config
+    end
+
+    alias configure config
+
+    def registry = Registry
+
+    # Current ambient scope value. Resolution order:
+    #   1. Inside `unscoped { }`      → nil (hard bypass)
+    #   2. Innermost `with_scope(v)`  → v
+    #   3. Configured `scope_resolver` callable
+    #   4. nil
+    #
+    # Returns a string (via normalize), or nil when nothing resolves.
+    def current_scope
+      return nil if Thread.current[THREAD_UNSCOPED]
+
+      stack = Thread.current[THREAD_SCOPE_STACK]
+      return normalize_scope(stack.last) if stack.present?
+
+      normalize_scope(Config.scope_resolver&.call)
+    end
+
+    # Run the block with `value` as the ambient scope, restoring the prior
+    # stack on exit (exception-safe). Nests cleanly.
+    def with_scope(value)
+      stack = (Thread.current[THREAD_SCOPE_STACK] ||= [])
+      stack.push(value)
+      yield
+    ensure
+      stack&.pop
+    end
+
+    # Run the block with scope enforcement disabled. Queries return results
+    # across all scopes. Use for admin tools, migrations, and tests.
+    def unscoped
+      prev = Thread.current[THREAD_UNSCOPED]
+      Thread.current[THREAD_UNSCOPED] = true
+      yield
+    ensure
+      Thread.current[THREAD_UNSCOPED] = prev
+    end
+
+    # True when inside an `unscoped { }` block.
+    def unscoped?
+      !!Thread.current[THREAD_UNSCOPED]
+    end
+
+    # Coerce resolver/with_scope/explicit-kwarg inputs into the string shape
+    # stored in the `scope` column. Accepts raw scalars or AR records.
+    def normalize_scope(value)
+      return nil if value.nil?
+
+      value.respond_to?(:id) ? value.id.to_s : value.to_s
+    end
+  end
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: typed_eav
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Darrin Chuk
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: Add dynamic custom fields to ActiveRecord models at runtime using native
+  database typed columns instead of jsonb blobs. Hybrid EAV with real indexes, real
+  types, real query performance.
+email:
+- me@dchuk.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/models/typed_eav/application_record.rb
+- app/models/typed_eav/field/base.rb
+- app/models/typed_eav/field/boolean.rb
+- app/models/typed_eav/field/color.rb
+- app/models/typed_eav/field/date.rb
+- app/models/typed_eav/field/date_array.rb
+- app/models/typed_eav/field/date_time.rb
+- app/models/typed_eav/field/decimal.rb
+- app/models/typed_eav/field/decimal_array.rb
+- app/models/typed_eav/field/email.rb
+- app/models/typed_eav/field/integer.rb
+- app/models/typed_eav/field/integer_array.rb
+- app/models/typed_eav/field/json.rb
+- app/models/typed_eav/field/long_text.rb
+- app/models/typed_eav/field/multi_select.rb
+- app/models/typed_eav/field/select.rb
+- app/models/typed_eav/field/text.rb
+- app/models/typed_eav/field/text_array.rb
+- app/models/typed_eav/field/url.rb
+- app/models/typed_eav/option.rb
+- app/models/typed_eav/section.rb
+- app/models/typed_eav/value.rb
+- db/migrate/20260330000000_create_typed_eav_tables.rb
+- lib/generators/typed_eav/install/install_generator.rb
+- lib/generators/typed_eav/scaffold/scaffold_generator.rb
+- lib/generators/typed_eav/scaffold/templates/config/initializers/typed_eav.rb
+- lib/generators/typed_eav/scaffold/templates/controllers/concerns/typed_eav_controller_concern.rb
+- lib/generators/typed_eav/scaffold/templates/controllers/typed_eav_controller.rb
+- lib/generators/typed_eav/scaffold/templates/helpers/typed_eav_helper.rb
+- lib/generators/typed_eav/scaffold/templates/javascript/controllers/array_field_controller.js
+- lib/generators/typed_eav/scaffold/templates/javascript/controllers/typed_eav_form_controller.js
+- lib/generators/typed_eav/scaffold/templates/views/shared/_array_field.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/edit.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/finders/_form.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_boolean.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_color.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_common_fields.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_date.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_date_array.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_date_time.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_decimal.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_decimal_array.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_email.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_integer.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_integer_array.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_json.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_long_text.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_multi_select.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_select.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_text.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_text_array.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_url.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/index.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/new.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/show.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_boolean.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_color.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_date.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_date_array.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_date_time.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_decimal.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_decimal_array.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_email.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_integer.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_integer_array.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_json.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_long_text.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_multi_select.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_select.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_text.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_text_array.html.erb
+- lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_url.html.erb
+- lib/typed_eav.rb
+- lib/typed_eav/column_mapping.rb
+- lib/typed_eav/config.rb
+- lib/typed_eav/engine.rb
+- lib/typed_eav/has_typed_eav.rb
+- lib/typed_eav/query_builder.rb
+- lib/typed_eav/registry.rb
+- lib/typed_eav/version.rb
+homepage: https://github.com/dchuk/typed_eav
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dchuk/typed_eav
+  source_code_uri: https://github.com/dchuk/typed_eav
+  changelog_uri: https://github.com/dchuk/typed_eav/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dchuk/typed_eav/issues
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Typed custom fields for ActiveRecord models
+test_files: []