typed_eav 0.6.0 → 0.7.1

data/lib/typed_eav/query_builder.rb

@@ -3,16 +3,10 @@
 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.
+  # Field owns operand casting and operator validation before this layer builds
+  # Arel. Active Record supplies bind plumbing for the already-normalized
+  # typed value; no manual SQL CAST() calls or per-type query caster classes
+  # are needed here.
   #
   # Usage:
   #   QueryBuilder.filter(field, :gt, 42)
@@ -53,6 +47,8 @@ module TypedEAV
         arel_col = values_table[col]
 
         base = value_scope(field)
+        excluded = %i[is_null is_not_null contains not_contains starts_with ends_with]
+        operand = field.cast_query_operand(operator, value) unless excluded.include?(operator)
 
         case operator
         when :eq, :currency_eq
@@ -64,9 +60,9 @@ module TypedEAV
           # dispatch resolved correctly. The operator-validation gate at
           # the top of #filter still narrows :currency_eq to Field::Currency
           # only — no other field type accepts it.
-          eq_predicate(base, arel_col, col, value)
+          eq_predicate(base, arel_col, col, operand)
         when :not_eq
-          not_eq_predicate(base, arel_col, col, value)
+          not_eq_predicate(base, arel_col, col, operand)
         when :references
           # Phase 5 Reference field. `value` may be an Integer FK OR an
           # AR record instance — `field.cast` normalizes both to an
@@ -79,27 +75,21 @@ module TypedEAV
           # The :references operator is registered ONLY on Field::Reference
           # (the operator-validation gate above keeps it from leaking to
           # other types).
-          fk, invalid = field.cast(value)
-          if invalid || fk.nil?
+          if operand.nil?
             base.none
           else
-            base.where(arel_col.eq(fk))
+            base.where(arel_col.eq(operand))
           end
         when :gt
-          base.where(arel_col.gt(value))
+          base.where(arel_col.gt(operand))
         when :gteq
-          base.where(arel_col.gteq(value))
+          base.where(arel_col.gteq(operand))
         when :lt
-          base.where(arel_col.lt(value))
+          base.where(arel_col.lt(operand))
         when :lteq
-          base.where(arel_col.lteq(value))
+          base.where(arel_col.lteq(operand))
         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))
+          base.where(arel_col.between(operand))
         when :contains
           base.where(arel_col.matches("%#{sanitize_like(value)}%"))
         when :not_contains
@@ -114,10 +104,10 @@ module TypedEAV
           base.where.not(col => nil)
         when :any_eq
           # For json_value arrays: contains the given element
-          base.where("#{col} @> ?", [value].to_json)
+          base.where("#{col} @> ?", [operand].to_json)
         when :all_eq
           # For json_value arrays: contains all given elements
-          base.where("#{col} @> ?", Array(value).to_json)
+          base.where("#{col} @> ?", operand.to_json)
         else
           raise ArgumentError, "Unhandled operator: #{operator}"
         end

data/lib/typed_eav/registry.rb

@@ -25,12 +25,11 @@ module TypedEAV
       # Register an entity type with optional type restrictions and optional
       # versioning opt-in.
       #
-      # `versioned:` is the per-entity Phase 04 opt-in flag. When true, AND
-      # `Config.versioning = true` at engine load (gem-level master switch),
-      # the Phase 04 subscriber writes a TypedEAV::ValueVersion row per
-      # Value mutation on this entity_type. Default false — apps not using
-      # versioning pay zero cost (one Hash#dig per write at most when
-      # `Config.versioning = true`, nothing when off).
+      # `versioned:` is the per-entity opt-in flag. When true and the
+      # boot-latched transactional callbacks are installed, the version
+      # writer records a TypedEAV::ValueVersion row per Value mutation on
+      # this entity_type. Default false — apps not using versioning pay zero
+      # version-row work.
       #
       # Backward compat: existing callers `register(name, types: types)`
       # continue to work — the new kwarg defaults to false. The entry hash
@@ -69,8 +68,8 @@ module TypedEAV
       # Returns the stored boolean for opted-in entities; false for
       # unregistered entities (defensive — callers might query before
       # `has_typed_eav` runs in a particular load order). The Phase 04
-      # subscriber calls this on every Value write when `Config.versioning =
-      # true` — performance is one Hash#dig per write, negligible.
+      # transactional writer calls this only after its boot-latched callback
+      # has been installed; this lookup remains a small Hash#dig per write.
       #
       # `entities.dig(entity_type, :versioned)` returns nil when
       # `entities[entity_type]` is missing (no register call) OR when the

data/lib/typed_eav/version.rb

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

data/lib/typed_eav/versioned.rb

@@ -62,12 +62,14 @@ module TypedEAV
 
       # Re-register with versioned: true. Preserve the existing types:
       # restriction by reading the current Registry entry.
-      # has_typed_eav already called register(name, types: types,
-      # versioned: false) — we overwrite with versioned: true while
-      # keeping the same types. If the entry doesn't exist (defensive
-      # — shouldn't happen post-has_typed_eav), default types to nil.
-      existing = TypedEAV.registry.entities[name] || {}
-      TypedEAV.registry.register(name, types: existing[:types], versioned: true)
+      # has_typed_eav already registered the canonical Rails polymorphic
+      # name. Reuse it here so including this concern on an STI subclass
+      # enables versioning for the base entity_type actually stored on Value.
+      # If the entry doesn't exist (defensive — shouldn't happen post-
+      # has_typed_eav), default types to nil.
+      entity_type = polymorphic_name
+      existing = TypedEAV.registry.entities[entity_type] || {}
+      TypedEAV.registry.register(entity_type, types: existing[:types], versioned: true)
     end
   end
 end

data/lib/typed_eav/versioning/subscriber.rb

@@ -2,15 +2,15 @@
 
 module TypedEAV
   module Versioning
-    # The Phase 04 internal subscriber. Conditionally registered with
-    # EventDispatcher.register_internal_value_change at engine boot via
-    # `TypedEAV::Versioning.register_if_enabled`. When registered, runs
-    # at slot 0 of the value-change subscriber chain.
+    # The transactional version writer. Conditionally installed on Value's
+    # create/update `after` and destroy `before` callbacks at engine boot via
+    # `TypedEAV::Versioning.register_if_enabled`; every write is therefore
+    # part of the source transaction.
     #
     # ## Contract
     #
-    # `call(value, change_type, context)` — called by EventDispatcher.
-    # Returns nil (return value is ignored by EventDispatcher; the
+    # `call(value, change_type, context)` — called by Value's lifecycle
+    # callback. Returns nil (the return value is ignored; the
     # method's job is the side effect of writing a ValueVersion row).
     #
     # Two-gate short-circuit (the master switch is enforced at
@@ -54,16 +54,13 @@ module TypedEAV
     # nil").
     module Subscriber
       class << self
-        # Public entry point. EventDispatcher calls this with the locked
-        # 3-arg signature `(value, change_type, context)`.
+        # Public entry point. Value's transactional callbacks call this with
+        # the locked 3-arg signature `(value, change_type, context)`.
         #
-        # NOTE: there is NO `Config.versioning` gate here. The subscriber
-        # is only registered with EventDispatcher when `Config.versioning`
-        # was true at engine `config.after_initialize` time (see
-        # `TypedEAV::Versioning.register_if_enabled`, invoked from
-        # lib/typed_eav/engine.rb's `config.after_initialize` block). If
-        # versioning is off, the subscriber is never registered and never
-        # reached. The remaining gates are:
+        # NOTE: there is NO `Config.versioning` gate here. The subscriber is
+        # installed only when `Config.versioning` was true at engine
+        # `config.after_initialize` time. If versioning is off, the callback
+        # is never installed and this method is never reached. The remaining gates are:
         #   1. field-presence (orphan guard — Value's field_id may have
         #      been NULLed by Phase 02's ON DELETE SET NULL cascade).
         #   2. per-entity opt-in (Registry.versioned?).
@@ -72,6 +69,8 @@ module TypedEAV
           return unless TypedEAV.registry.versioned?(value.entity_type)
 
           write_version_row(value, change_type, context)
+        ensure
+          value.consume_pending_version_group_id if value.respond_to?(:consume_pending_version_group_id)
         end
 
         private
@@ -85,15 +84,9 @@ module TypedEAV
           before_value = field.before_snapshot(value, change_type)
           after_value  = field.after_snapshot(value, change_type)
 
-          # CRITICAL: for :destroy events, write `value_id: nil`.
-          # By the time `after_commit on: :destroy` fires, the parent row
-          # in `typed_eav_values` has already been deleted (Postgres
-          # commits the DELETE before invoking after_commit callbacks).
-          # The FK is `ON DELETE SET NULL`, but at the moment we INSERT
-          # the version row, Postgres validates the FK against the
-          # current state of typed_eav_values — which no longer contains
-          # the parent. Writing `value.id` (still readable in-memory on
-          # the destroyed AR record) would FK-fail at INSERT.
+          # CRITICAL: for :destroy events, write `value_id: nil`. The row is
+          # written before the source DELETE and must not retain an identity
+          # that the FK will null when the Value is removed.
           #
           # The audit trail for destroy events stays queryable via:
           #   - entity_type + entity_id (host record identity)
@@ -102,8 +95,7 @@ module TypedEAV
           # `field_id` remains populated because destroying a Value does
           # not destroy its Field — `value.field_id` is a live reference.
           #
-          # For :create and :update events, `value_id: value.id` is
-          # correct (parent row exists at after_commit time).
+          # For :create and :update, `value_id: value.id` is correct.
           version_value_id = change_type == :destroy ? nil : value.id
 
           # Phase 06 bulk-operations correlation tag. Two delivery paths:
@@ -113,7 +105,7 @@ module TypedEAV
           #    on each affected Value object BEFORE `record.save`, INSIDE
           #    the per-record `with_context` block. Reading the snapshot
           #    here (not `current_context`) guarantees the UUID survives
-          #    the outer-transaction `after_commit` boundary — by the time
+          #    the source transaction boundary — by the time
           #    we run, the lexical `with_context` block has unwound and
           #    `current_context` would be empty, but the per-Value ivar
           #    persists. Mirrors the existing in-memory ivar pattern at
@@ -127,12 +119,16 @@ module TypedEAV
           #    request id). For those paths the Value ivar is unset; the
           #    `||` falls through to `context[:version_group_id]`. Also
           #    used as the belt-and-suspenders fallback for any future
-          #    after_commit-inside-savepoint dispatch path that bulk writes
+          #    savepoint path that bulk writes
           #    might leverage.
           #
           # When neither path supplies a UUID the column (added in
           # `db/migrate/20260506000001`) stays NULL — backward-compatible:
           # unchanged subscribers and unchanged callers continue to work.
+          pending_group_id = if value.respond_to?(:consume_pending_version_group_id)
+                               value.consume_pending_version_group_id
+                             end
+
           TypedEAV::ValueVersion.create!(
             value_id: version_value_id,
             field_id: value.field_id,
@@ -142,7 +138,7 @@ module TypedEAV
             before_value: before_value,
             after_value: after_value,
             context: context.to_h, # frozen → unfrozen jsonb-serializable hash
-            version_group_id: value.pending_version_group_id || context[:version_group_id],
+            version_group_id: pending_group_id || context[:version_group_id],
             change_type: change_type.to_s,
             changed_at: Time.current,
           )

data/lib/typed_eav/versioning.rb

@@ -1,23 +1,15 @@
 # frozen_string_literal: true
 
 module TypedEAV
-  # Phase 04 versioning namespace. Houses the Subscriber that writes
-  # TypedEAV::ValueVersion rows in response to Value lifecycle events
-  # dispatched by EventDispatcher.
+  # Transactional versioning namespace. Houses the Subscriber that writes
+  # TypedEAV::ValueVersion rows from Value lifecycle callbacks.
   #
   # ## Architecture
   #
   # - TypedEAV::Versioning::Subscriber.call(value, change_type, context)
-  #   is conditionally registered with
-  #   EventDispatcher.register_internal_value_change at engine boot via
-  #   `TypedEAV::Versioning.register_if_enabled`, which is invoked from
-  #   the `config.after_initialize` block in lib/typed_eav/engine.rb.
-  #   When TypedEAV.config.versioning is false (default), the helper
-  #   returns early — no callable is added to the dispatcher chain.
-  #   When true, the subscriber registers and runs FIRST in the value-
-  #   change subscriber chain (slot 0 by `after_initialize` block
-  #   declaration order — Phase 07 will declare its matview block LATER
-  #   in the same engine to keep matview at slot ≥ 1).
+  #   is conditionally installed on Value's transactional callbacks at engine
+  #   boot via `TypedEAV::Versioning.register_if_enabled`. The version row
+  #   therefore shares the source transaction.
   #
   # - The subscriber is gated by TWO checks at call time (both must
   #   pass for a version row to be written):
@@ -30,10 +22,9 @@ module TypedEAV
   #   the callable — when false, the subscriber is never registered in
   #   the first place.
   #
-  # - Errors raised by Subscriber.call PROPAGATE per the EventDispatcher
-  #   internal-vs-user error policy (03-CONTEXT.md §User-callback error
-  #   policy). Versioning corruption must be loud — silent failure
-  #   leaves the audit log inconsistent with the live row.
+  # - Errors raised by Subscriber.call propagate. Versioning corruption must
+  #   be loud — silent failure leaves the audit log inconsistent with the live
+  #   row.
   #
   # ## Public API surface
   #
@@ -52,43 +43,70 @@ module TypedEAV
     # this namespace shell — it does NOT recursively autoload nested
     # constants. Without the explicit declaration below, the engine's
     # config.after_initialize block (which references
-    # `TypedEAV::Versioning::Subscriber.method(:call)`) raises
+    # `TypedEAV::Versioning::Subscriber`) raises
     # `NameError: uninitialized constant TypedEAV::Versioning::Subscriber`
     # at boot time, breaking every host that enables versioning.
     autoload :Subscriber, "typed_eav/versioning/subscriber"
 
-    # Conditionally register the Subscriber with EventDispatcher's internal
-    # value-change subscriber chain. Called by the engine's
-    # `config.after_initialize` block (lib/typed_eav/engine.rb).
+    CALLBACKS = {
+      create: %i[_write_version_create after].freeze,
+      update: %i[_write_version_update after].freeze,
+      destroy: %i[_write_version_destroy before].freeze,
+    }.freeze
+
+    # Conditionally install the Subscriber on Value's transactional callbacks.
+    # Called by the engine's `config.after_initialize` block.
     #
     # Extracted into a class method (not inlined inside the after_initialize
-    # block) for testability: specs can call this against a freshly-cleared
-    # `EventDispatcher.value_change_internals` to exercise both branches
-    # (versioning on/off) in-process, without booting the engine. The
-    # slot-0 regression spec (plan 04-03 P03) and the zero-overhead
-    # verification spec (this plan, subscriber_spec engine-boot block) both
-    # rely on this seam.
+    # block) for testability: specs can call this seam in-process without
+    # booting a second Rails application.
     #
-    # Idempotent — safe to call multiple times. Calling twice with
-    # versioning on results in exactly ONE entry in
-    # `EventDispatcher.value_change_internals`. The idempotency check uses
-    # `Array#include?` against `Subscriber.method(:call)`; `Method#==`
-    # compares receiver+name (semantic equality), so two fresh
-    # `Subscriber.method(:call)` instances compare equal even though they
-    # are different Method objects. The engine block runs this exactly
-    # once per boot in production; the idempotency guard protects future
-    # code paths that might re-invoke for any reason.
+    # Idempotent — safe to call multiple times. Pool validation happens before
+    # any callback is installed, so a multi-database misconfiguration fails
+    # closed without partial activation.
     #
     # When `TypedEAV.config.versioning` is false (default), this method is
-    # a no-op: zero callable in `value_change_internals`, zero per-write
-    # dispatch cost. That is the locked CONTEXT line 17 contract.
+    # a no-op: no callback is installed and the disabled path adds no
+    # per-write predicate or dispatcher work.
     def self.register_if_enabled
       return unless TypedEAV.config.versioning
 
-      method_ref = TypedEAV::Versioning::Subscriber.method(:call)
-      return if TypedEAV::EventDispatcher.value_change_internals.include?(method_ref)
+      value_pool = TypedEAV::Value.connection_pool
+      version_pool = TypedEAV::ValueVersion.connection_pool
+      unless value_pool.equal?(version_pool)
+        raise ArgumentError, "TypedEAV versioning requires Value and ValueVersion to share a connection pool"
+      end
+
+      callback_chains = callback_chains_for_installation
+
+      callback_chains.each do |event, (filter, kind, chain)|
+        next if chain.any? { |callback| callback.filter == filter && callback.kind == kind }
+
+        TypedEAV::Value.set_callback(event, kind, filter, prepend: true)
+      end
+    end
+
+    def self.callback_chains_for_installation
+      CALLBACKS.to_h do |event, (filter, kind)|
+        chain = TypedEAV::Value.send(:get_callbacks, event).to_a
+        wrong_kind = chain.find { |callback| callback.filter == filter && callback.kind != kind }
+        if wrong_kind
+          raise ArgumentError,
+                "TypedEAV versioning callback #{filter.inspect} on #{event} has kind " \
+                "#{wrong_kind.kind.inspect}; expected #{kind.inspect}"
+        end
+
+        [event, [filter, kind, chain]]
+      end
+    end
+    private_class_method :callback_chains_for_installation
 
-      TypedEAV::EventDispatcher.register_internal_value_change(method_ref)
+    def self.atomic_callbacks_installed?
+      CALLBACKS.all? do |event, (filter, kind)|
+        TypedEAV::Value.send(:get_callbacks, event).to_a.any? do |callback|
+          callback.filter == filter && callback.kind == kind
+        end
+      end
     end
   end
 end

data/lib/typed_eav.rb

@@ -18,6 +18,7 @@ module TypedEAV
   autoload :FilterQuery
   autoload :BulkRead
   autoload :BulkWrite
+  autoload :BulkUpsert
   autoload :Partition
   autoload :QueryBuilder
   autoload :SchemaPortability
@@ -27,6 +28,7 @@ module TypedEAV
   autoload :ValueVersion
   autoload :Versioned
   autoload :Versioning
+  autoload :FieldDeletion
 
   # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typed_eav
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - dchuk
@@ -94,6 +94,7 @@ files:
 - db/migrate/20260506000001_add_version_group_id_to_typed_eav_value_versions.rb
 - db/migrate/20260507000000_add_label_to_typed_eav_fields.rb
 - db/migrate/20260712000000_enforce_parent_scope_invariant.rb
+- db/migrate/20260816000000_use_partial_covering_scalar_indexes.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
@@ -145,6 +146,7 @@ files:
 - lib/generators/typed_eav/scaffold/templates/views/typed_eav/values/inputs/_url.html.erb
 - lib/typed_eav.rb
 - lib/typed_eav/bulk_read.rb
+- lib/typed_eav/bulk_upsert.rb
 - lib/typed_eav/bulk_write.rb
 - lib/typed_eav/config.rb
 - lib/typed_eav/csv_mapper.rb
@@ -152,10 +154,12 @@ files:
 - lib/typed_eav/entity_query.rb
 - lib/typed_eav/event_dispatcher.rb
 - lib/typed_eav/field/typed_storage.rb
+- lib/typed_eav/field_deletion.rb
 - lib/typed_eav/filter_query.rb
 - lib/typed_eav/has_typed_eav.rb
 - lib/typed_eav/has_typed_eav/instance_methods.rb
 - lib/typed_eav/partition.rb
+- lib/typed_eav/partition/definition_batch.rb
 - lib/typed_eav/query_builder.rb
 - lib/typed_eav/registry.rb
 - lib/typed_eav/schema_portability.rb