activeitem 0.0.20 → 0.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 652850a906bc798042da7b5c3ea1396aeef9775057ad1199030354cff2b24b73
-  data.tar.gz: 55001585d52f922c371cd6ca6cc61beef3f6f5ea98e4ca268d0bfe1e6ebf8d5a
+  metadata.gz: a7d5990fc9c0532dc9a65f803bd9886c1769dc2b4c3071fd4748c079fa7559b3
+  data.tar.gz: 1c480246c6a898502eacedda1b456e003f54910a3f8562893cc5c070c06f168e
 SHA512:
-  metadata.gz: 64fb13d70a43f1f6a5668c3e93b6e1f24ceec853ea6f7d9e974a7fd5b53c7a2f8b66e9d582d6f12d10498a892a10895712092b1bbcac4929c6cad86fc164d770
-  data.tar.gz: e6495e6752c6b8ffc0b8ef98451141ad8816fe069e4e33a40c7b65f45b4bf02981390bfab503149fce243e354d9842e1ce02bfb9f75f270af40dc5593d51ab5a
+  metadata.gz: db67b991fe6c8c9ed9ce18a362dc15dfd9f1b46c63ed20a49e8b1f82bf0bb2dfe3738b1e2f7d7b29a31396e61d40ee3e6d528393b01a93a92bf81c2e9d9f234b
+  data.tar.gz: dc5a3c76df184f02bf6fa4f0cd040e9a98e42729326f35243b198fc2d7c8ae4e4a86429bdc457be7f7e9198892ba93aaddf5a4d5650806afcba6cb528d6d54e7

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 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
+
+- **GSI key type validation** — ActiveItem now validates that Global Secondary Index (GSI) key attributes have valid DynamoDB types at write time. Valid types are: String (non-empty), Numeric (Integer, Float, BigDecimal), and Binary (StringIO). Invalid types (Array, Hash, Boolean, Symbol, Date, Time, empty strings) now raise `ActiveItem::InvalidGsiKeyTypeError` immediately, with a helpful error message identifying the attribute and index. This catches common bugs like passing `Date.today` instead of `date.to_s`, or accidentally setting an array where a string was expected.
+
+  ```ruby
+  # Raises InvalidGsiKeyTypeError: Item#status has invalid type Array for GSI 'StatusIndex'
+  item = Item.new(status: ['a', 'b', 'c'])
+  item.save
+
+  # Raises InvalidGsiKeyTypeError for empty strings
+  item = Item.new(status: '')
+  item.save
+  ```
+
 ## 0.0.19
 
 ### Added

data/lib/active_item/base.rb

@@ -752,6 +752,8 @@ module ActiveItem
         item[dynamo_key] = collection.map(&:to_embedded_hash)
       end
 
+      validate_gsi_key_types!(item)
+
       item
     end
 
@@ -776,6 +778,9 @@ module ActiveItem
       embedded_changed = embedded_associations_changed?
       return if changes.empty? && !embedded_changed
 
+      # Validate GSI key types for changed attributes before building the update
+      validate_gsi_key_types_for_changes!
+
       run_embedded_callbacks(:update) if embedded_changed
       run_embedded_callbacks(:save) if embedded_changed
 
@@ -854,5 +859,102 @@ module ActiveItem
       raise ActiveItem::AccessDeniedError.new(model_name: self.class.name, table: table_name,
                                               operation: 'DeleteItem', original_error: e)
     end
+
+    # Validates that all GSI key attributes have valid types for DynamoDB.
+    # GSI keys can only be String, Number (Integer/Float/BigDecimal), or Binary (StringIO).
+    #
+    # @param item [Hash] The DynamoDB item being built
+    # @raise [InvalidGsiKeyTypeError] if any GSI key has an invalid type
+    def validate_gsi_key_types!(item)
+      return unless self.class.respond_to?(:indexes)
+
+      indexes = self.class.indexes
+      return if indexes.nil? || indexes.empty?
+
+      indexes.each do |index_name, config|
+        # Check partition key
+        partition_key = config[:partition_key]&.to_s
+        if partition_key && item.key?(partition_key)
+          value = item[partition_key]
+          validate_gsi_key_value!(partition_key, value, index_name) unless value.nil?
+        end
+
+        # Check sort key if present
+        sort_key = config[:sort_key]&.to_s
+        if sort_key && item.key?(sort_key)
+          value = item[sort_key]
+          validate_gsi_key_value!(sort_key, value, index_name) unless value.nil?
+        end
+      end
+    end
+
+    # Validates GSI key types for changed attributes during updates.
+    # Only validates the attributes that are being changed, not the entire item.
+    #
+    # @raise [InvalidGsiKeyTypeError] if any changed GSI key has an invalid type
+    def validate_gsi_key_types_for_changes!
+      return unless self.class.respond_to?(:indexes)
+
+      indexes = self.class.indexes
+      return if indexes.nil? || indexes.empty?
+
+      # Build a hash of changed dynamo keys and their new values
+      changed_dynamo_keys = {}
+      changes.each do |field, (_old_val, new_val)|
+        next if new_val.nil? # nil values are being removed, no type validation needed
+
+        dynamo_key = self.class.to_dynamo_key(field)
+        changed_dynamo_keys[dynamo_key] = new_val
+      end
+
+      return if changed_dynamo_keys.empty?
+
+      indexes.each do |index_name, config|
+        # Check partition key if it's being changed
+        partition_key = config[:partition_key]&.to_s
+        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
+        validate_gsi_key_value!(sort_key, changed_dynamo_keys[sort_key], index_name) if sort_key && changed_dynamo_keys.key?(sort_key)
+      end
+    end
+
+    # Validates that a single GSI key value has a valid type.
+    # DynamoDB GSI keys support: String, Number (Integer/Float/BigDecimal), Binary (StringIO).
+    # Empty strings are not allowed for GSI keys.
+    #
+    # @param attribute [String] The attribute name
+    # @param value [Object] The attribute value
+    # @param index_name [String] The GSI name (for error messages)
+    # @raise [InvalidGsiKeyTypeError] if the value has an invalid type
+    def validate_gsi_key_value!(attribute, value, index_name)
+      return if valid_gsi_key_type?(value)
+
+      raise InvalidGsiKeyTypeError.new(
+        model_name: self.class.name,
+        attribute: attribute,
+        index_name: index_name,
+        value: value
+      )
+    end
+
+    # Checks if a value is a valid type for a DynamoDB GSI key.
+    # Valid types: String (non-empty), Numeric (Integer, Float, BigDecimal), Binary (StringIO).
+    # Empty strings are explicitly rejected as DynamoDB does not allow them for key attributes.
+    #
+    # @param value [Object] The value to check
+    # @return [Boolean] true if the value is a valid GSI key type
+    def valid_gsi_key_type?(value)
+      case value
+      when String
+        !value.empty? # Empty strings are not allowed for GSI keys
+      when Integer, Float, BigDecimal, StringIO
+        # Numeric (Integer, Float, BigDecimal) and Binary (StringIO) are valid GSI key types
+        true
+      else
+        false
+      end
+    end
   end
 end

data/lib/active_item/errors.rb

@@ -82,4 +82,20 @@ module ActiveItem
       super(msg)
     end
   end
+
+  # Raised when a GSI key attribute has an invalid type.
+  # DynamoDB GSI keys must be String, Number (Integer/Float/BigDecimal), or Binary (StringIO).
+  class InvalidGsiKeyTypeError < StandardError
+    attr_reader :model_name, :attribute, :index_name, :value, :value_type
+
+    def initialize(model_name:, attribute:, index_name:, value:)
+      @model_name = model_name
+      @attribute = attribute
+      @index_name = index_name
+      @value = value
+      @value_type = value.class.name
+      super("#{model_name}##{attribute} has invalid type #{@value_type} for GSI '#{index_name}'. " \
+            'GSI keys must be String, Numeric (Integer/Float/BigDecimal), or Binary (StringIO).')
+    end
+  end
 end

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.20'
+  VERSION = '0.0.22'
 end

metadata

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