activeitem 0.0.21 → 0.0.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 976cb7f41429d4ca2489b0a67a87f39ca3720bc223b02ad9c1d4e2e244f6a700
-  data.tar.gz: e5c0fd6be8a2ea1ccfc00793942d91973e53b9d434fec9b67e92b8da9660049d
+  metadata.gz: 3391ecc77f10aaffc7953d95d84691bdf4791ea11163fe45ba7b3b5be3b8418f
+  data.tar.gz: 02ad5cbf59628300f250fa972729ad503a53e197824350f7990e7d8cefd4281f
 SHA512:
-  metadata.gz: de5d8d0d4f7b6a986369e0604eec719dd686537009967b00302543abc507db28298b65222cb85e5fb22f9ee7e86568ec4934dc2f761956b6f880d89a74ad5456
-  data.tar.gz: 160ca85fad18fcd70b5650f274077c2a8fc841f6943b6d601a1effc13408c74ce037593c25dc6a58b4aa0a04f465b1616159719416d710e77fd10e1a2a134737
+  metadata.gz: b60d3ec30ab2f3f5a593c320d6af5764e793574b03e4389661325942d9e31d8c7b40b25532816ac0e1a5b8cfd4c5b49650ea413673d2686dd05a3841aeb0ae56
+  data.tar.gz: 37398daa0b3af333ed40fb9dc2ad4571d9044df57ebaefe7f20fd21a5c714676cce31925e5b8d5a9a6a847768b15e0e53eca8138ed7b89b38fbf17d8cc71b665

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.0.23
+
+### Added
+
+- **`read_attribute` / `write_attribute`** — ActiveItem now exposes the same attribute primitives as ActiveRecord. `write_attribute(:name, value)` records the change for dirty tracking; `read_attribute(:name)` returns the current value. Custom readers/writers can route through these instead of touching the ivar directly.
+
+### Fixed
+
+- **Custom attribute writers now persist on update, Rails-style** — Overriding a generated writer to coerce or normalize a value no longer silently drops the change. Generated readers/writers are now defined in an included module (like Rails' `GeneratedAttributeMethods`), so a hand-written `def foo=` can call `super` and get dirty tracking for free. Previously, a custom writer that assigned `@foo` directly left the attribute out of the changeset — `save` returned `true` with no error, but the update wrote nothing. Both `super` and `write_attribute` are now supported.
+
+  ```ruby
+  class Article < ActiveItem::Base
+    attr_accessor :tags, :payload
+
+    # Coerce to an Array, Rails-style: override and call super.
+    def tags=(value)
+      super(Array(value))
+    end
+
+    # Or be explicit with write_attribute.
+    def payload=(value)
+      write_attribute(:payload, value.is_a?(String) ? value : JSON.generate(value))
+    end
+  end
+  ```
+
+## 0.0.22
+
+### Changed
+
+- **Scoped `find` on associations** — `Relation#find(id)` now enforces association scope, matching Rails behavior. When called on an association (e.g., `@project.epics.find(id)`), it validates that the found record belongs to the association before returning it. If the record exists but belongs to a different parent, `ActiveItem::RecordNotFound` is raised. This prevents accidentally accessing records outside the association scope.
+
+  ```ruby
+  # Before: would return the epic even if it belonged to a different project
+  @project.epics.find(epic_id)
+
+  # After: raises RecordNotFound if epic.project_id != @project.id
+  @project.epics.find(epic_id)
+  ```
+
 ## 0.0.21
 
 ### Added

data/README.md

@@ -114,6 +114,38 @@ class Customer < ActiveItem::Base
 end
 ```
 
+### Custom Attribute Writers
+
+Like ActiveRecord, you can override a generated writer to coerce or normalize a
+value on assignment. Just route the assignment back through the generated
+writer — call `super`, or use `write_attribute`. Both record the change for
+dirty tracking, so `save` (and `update`) persist it. Assigning `@ivar` directly
+bypasses dirty tracking and the change is silently dropped on update.
+
+```ruby
+class Article < ActiveItem::Base
+  attr_accessor :tags, :payload
+
+  # Coerce to an Array, Rails-style: override and call super.
+  def tags=(value)
+    super(Array(value))
+  end
+
+  # Or be explicit with write_attribute.
+  def payload=(value)
+    write_attribute(:payload, value.is_a?(String) ? value : JSON.generate(value))
+  end
+end
+```
+
+`read_attribute(:name)` is available too, for custom readers:
+
+```ruby
+def display_name
+  read_attribute(:name).to_s.strip
+end
+```
+
 ## License
 
 MIT

data/lib/active_item/base.rb

@@ -100,15 +100,33 @@ module ActiveItem
 
           define_attribute_methods attr_name
 
-          define_method(attr_name) do
-            instance_variable_get("@#{attr_name}")
+          # Define the generated reader/writer in a dedicated module that is
+          # included into the model, rather than directly on the class. This
+          # mirrors Rails' GeneratedAttributeMethods: a hand-written
+          # `def foo=` on the model sits *above* the generated writer in the
+          # ancestor chain, so a custom writer can call `super` (or
+          # `write_attribute`) to get dirty tracking for free.
+          generated_attribute_methods.module_eval do
+            define_method(attr_name) do
+              read_attribute(attr_name)
+            end
+
+            define_method("#{attr_name}=") do |value|
+              write_attribute(attr_name, value)
+            end
           end
+        end
+      end
 
-          define_method("#{attr_name}=") do |value|
-            old_value = instance_variable_get("@#{attr_name}")
-            send("#{attr_name}_will_change!") if (old_value != value) && !changed_attributes.key?(attr_name)
-            instance_variable_set("@#{attr_name}", value)
-          end
+      # Per-class module that holds the generated attribute reader/writer
+      # methods. Included once, ahead of ActiveModel in the ancestor chain but
+      # behind the model class itself, so user-defined setters can `super`.
+      def generated_attribute_methods
+        @generated_attribute_methods ||= begin
+          mod = Module.new
+          include mod
+
+          mod
         end
       end
 
@@ -490,6 +508,50 @@ module ActiveItem
       end
     end
 
+    # Read the current value of an attribute by name.
+    #
+    # This is the Rails-like primitive that generated readers delegate to.
+    # Custom readers can call it (or `super`) instead of poking at the ivar
+    # directly.
+    #
+    #   def display_name
+    #     read_attribute(:name).to_s.strip
+    #   end
+    #
+    # @param attr_name [String, Symbol] the attribute name
+    # @return the attribute's current value
+    def read_attribute(attr_name)
+      instance_variable_get("@#{attr_name}")
+    end
+
+    # Write an attribute value, recording it for dirty tracking so `save`
+    # actually persists it.
+    #
+    # This is the single place dirty tracking happens for attributes, mirroring
+    # Rails' `write_attribute`. Generated writers delegate here, which means a
+    # custom writer gets dirty tracking for free by going through either
+    # `super` or `write_attribute` directly:
+    #
+    #   # coerce/normalize on assignment, Rails-style
+    #   def tags=(value)
+    #     super(Array(value))            # -> generated writer -> write_attribute
+    #   end
+    #
+    #   # or be explicit
+    #   def payload=(value)
+    #     write_attribute(:payload, value.is_a?(String) ? value : JSON.generate(value))
+    #   end
+    #
+    # @param attr_name [String, Symbol] the attribute name
+    # @param value the value to assign
+    # @return the assigned value
+    def write_attribute(attr_name, value)
+      attr_name = attr_name.to_s
+      old_value = instance_variable_get("@#{attr_name}")
+      mark_attribute_will_change(attr_name, old_value, value)
+      instance_variable_set("@#{attr_name}", value)
+    end
+
     def attribute_changed?(attr_name)
       super(attr_name.to_s)
     end
@@ -511,6 +573,18 @@ module ActiveItem
 
     private
 
+    # Record a pending change for dirty tracking. Guarded with `respond_to?`
+    # so it degrades gracefully for attributes that weren't declared via
+    # `attr_accessor` (and under test harnesses that stub the ORM), and skips
+    # re-recording an original value that's already been captured.
+    def mark_attribute_will_change(attr_name, old_value, new_value)
+      return if old_value == new_value
+      return if changed_attributes.key?(attr_name)
+      return unless respond_to?("#{attr_name}_will_change!", true)
+
+      send("#{attr_name}_will_change!")
+    end
+
     # Enroll this record's save operation in the current transaction.
     # Called when save is invoked inside a transaction block.
     def enroll_in_transaction
@@ -912,15 +986,11 @@ module ActiveItem
       indexes.each do |index_name, config|
         # Check partition key if it's being changed
         partition_key = config[:partition_key]&.to_s
-        if partition_key && changed_dynamo_keys.key?(partition_key)
-          validate_gsi_key_value!(partition_key, changed_dynamo_keys[partition_key], index_name)
-        end
+        validate_gsi_key_value!(partition_key, changed_dynamo_keys[partition_key], index_name) if partition_key && changed_dynamo_keys.key?(partition_key)
 
         # Check sort key if it's being changed
         sort_key = config[:sort_key]&.to_s
-        if sort_key && changed_dynamo_keys.key?(sort_key)
-          validate_gsi_key_value!(sort_key, changed_dynamo_keys[sort_key], index_name)
-        end
+        validate_gsi_key_value!(sort_key, changed_dynamo_keys[sort_key], index_name) if sort_key && changed_dynamo_keys.key?(sort_key)
       end
     end
 
@@ -953,9 +1023,8 @@ module ActiveItem
       case value
       when String
         !value.empty? # Empty strings are not allowed for GSI keys
-      when Integer, Float, BigDecimal
-        true
-      when StringIO
+      when Integer, Float, BigDecimal, StringIO
+        # Numeric (Integer, Float, BigDecimal) and Binary (StringIO) are valid GSI key types
         true
       else
         false

data/lib/active_item/relation.rb

@@ -294,18 +294,26 @@ module ActiveItem
 
     # Find by id within the current scope, or find by block (like Enumerable#find)
     #
+    # When called on an association (e.g., @project.epics.find(id)), validates that
+    # the found record belongs to the association's scope. This matches Rails behavior
+    # where association.find(id) only returns records belonging to that association.
+    #
     # @overload find(id)
     #   Find a record by ID within the current scope
     #   @param id [String] The ID to find
-    #   @return [Object, nil] The found record or nil
+    #   @return [Object] The found record
+    #   @raise [ActiveItem::RecordNotFound] If record not found or not in scope
     #
     # @overload find(&block)
     #   Find the first record matching the block condition (like Enumerable#find/detect)
     #   @yield [record] Evaluates the block for each record
     #   @return [Object, nil] The first record where block returns true, or nil
     #
-    # @example Find by ID
-    #   User.where(status: 'active').find('user-123')
+    # @example Find by ID (scoped to association)
+    #   @project.epics.find('epic-123')  # Only finds if epic belongs to @project
+    #
+    # @example Find by ID (unscoped)
+    #   Epic.where(status: 'active').find('epic-123')  # Finds any active epic
     #
     # @example Find by block
     #   User.where(status: 'active').find { |u| u.email.include?('@example.com') }
@@ -317,13 +325,20 @@ module ActiveItem
       elsif id
         # Use direct GetItem instead of scanning — O(1) vs O(n)
         record = resolved_model.find(id)
+
+        # When called on an association (has conditions), validate scope
+        # This ensures @project.epics.find(id) only returns epics belonging to @project
+        if conditions.any? && !conditions[:_empty]
+          foreign_key, expected_value = conditions.first
+          actual_value = record.send(foreign_key)
+          raise ActiveItem::RecordNotFound, "Couldn't find #{resolved_model.name} with id=#{id}" unless actual_value == expected_value
+        end
+
         preload_associations_for_records([record]) if includes_associations.any?
         record
       else
         raise ArgumentError, 'find requires either an ID or a block'
       end
-    rescue ActiveItem::RecordNotFound
-      nil
     end
 
     # Find by conditions within current scope

data/lib/active_item/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveItem
-  VERSION = '0.0.21'
+  VERSION = '0.0.23'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activeitem
 version: !ruby/object:Gem::Version
-  version: 0.0.21
+  version: 0.0.23
 platform: ruby
 authors:
 - Andy Davis
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel