activeitem 0.0.20 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 652850a906bc798042da7b5c3ea1396aeef9775057ad1199030354cff2b24b73
-  data.tar.gz: 55001585d52f922c371cd6ca6cc61beef3f6f5ea98e4ca268d0bfe1e6ebf8d5a
+  metadata.gz: 976cb7f41429d4ca2489b0a67a87f39ca3720bc223b02ad9c1d4e2e244f6a700
+  data.tar.gz: e5c0fd6be8a2ea1ccfc00793942d91973e53b9d434fec9b67e92b8da9660049d
 SHA512:
-  metadata.gz: 64fb13d70a43f1f6a5668c3e93b6e1f24ceec853ea6f7d9e974a7fd5b53c7a2f8b66e9d582d6f12d10498a892a10895712092b1bbcac4929c6cad86fc164d770
-  data.tar.gz: e6495e6752c6b8ffc0b8ef98451141ad8816fe069e4e33a40c7b65f45b4bf02981390bfab503149fce243e354d9842e1ce02bfb9f75f270af40dc5593d51ab5a
+  metadata.gz: de5d8d0d4f7b6a986369e0604eec719dd686537009967b00302543abc507db28298b65222cb85e5fb22f9ee7e86568ec4934dc2f761956b6f880d89a74ad5456
+  data.tar.gz: 160ca85fad18fcd70b5650f274077c2a8fc841f6943b6d601a1effc13408c74ce037593c25dc6a58b4aa0a04f465b1616159719416d710e77fd10e1a2a134737

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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,107 @@ 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
+        if partition_key && changed_dynamo_keys.key?(partition_key)
+          validate_gsi_key_value!(partition_key, changed_dynamo_keys[partition_key], index_name)
+        end
+
+        # 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
+      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
+        true
+      when StringIO
+        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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activeitem
 version: !ruby/object:Gem::Version
-  version: 0.0.20
+  version: 0.0.21
 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-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel