activeitem 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a08a2b03026d0380bc6232ad035c49ca911bb5ee96c8e7d55de3dd23ebc3dcba
-  data.tar.gz: 1778c6afe64631e5f40ef13b69a761109475befffdea301cb4144a5ea0abc7bb
+  metadata.gz: 11aa0780a8b4e5d41d3010603fff7f4e86f2dd6226e443d1c969d461f115d9a5
+  data.tar.gz: fa289cbbd0677836e4933cb57392ca7027821e12df1f3eb1cacd8fb87b130ddc
 SHA512:
-  metadata.gz: c03b044f31d8a843fd37f066a6f5ae25a406165db25541a717e547bee044f20f09f45399dc4beaa133fb696611d86ee0938d09d9e67d3cdb50616e9493005c8b
-  data.tar.gz: 024f823d6e9d76a4e7f9b9a77ac1e9212d213a549e9fc735051e7fdc2c5ac507f28c894aa9d2d209b589a772f5db534063c3e33d7f8db64cc8eefeea02b8955d
+  metadata.gz: 8f04eda18abbbf4bf4ab2aae97ff933406dad0692157acb3a3d22b8ca2b4caec99c750489c719f194ddda05e07ee42a310a3bc387ae173364a696809cea87546
+  data.tar.gz: 48b5015fc97d6137b33ca2b3b92c308f3e9f993d8a6c083bc0255fbac5af6da5c9bba9998801450da6192e2c8b2d4d35c1e67f3ead284d1c8608e745c2be2bc8

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.0.2
+
+### Security
+
+- **[Critical]** Pagination cursor validation — decoded JSON is now validated to only contain flat key/value pairs with alphanumeric keys and string/numeric values. Prevents partition traversal via crafted cursors.
+- **[Critical]** Remove arbitrary file require from `model_loader.rb` — `safe_constantize_model` now uses `safe_constantize` with class name format validation instead of requiring files from disk.
+- **[Medium]** Add jitter to exponential backoff in batch operations to prevent thundering herd.
+- **[Low]** Replace `Object.const_get` with `safe_constantize` in `composed_of` to prevent constant hierarchy traversal.
+
+### Fixed
+
+- Fix `set_created_timestamp` callback not setting `@created_at`, causing DynamoDB `Invalid attribute value type` errors on create
+- Fix duplicate `id=` method definition (Lint/DuplicateMethods) by using `attr_reader :id` with a custom setter
+- Fix duplicate `last` method definition in QueryHelpers
+- Fix duplicate branch in Relation `includes` case statement (Lint/DuplicateBranch)
+- Use `Comparable#clamp` in Pagination and Relation (Style/ComparableClamp)
+
+### Added
+
+- Documentation comments for all public modules and classes (Style/Documentation)
+- `--workdir` option to CI DynamoDB service for `act` compatibility
+
 ## 0.0.1
 
 - Initial release

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Andy Davis
+Copyright (c) 2026 Stowzilla Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/active_item/associations.rb

@@ -5,6 +5,9 @@ require 'active_support/inflector'
 require_relative 'model_loader'
 
 module ActiveItem
+  # Provides has_many and belongs_to association macros with lazy loading,
+  # preloading support, and dependent record handling (destroy, nullify,
+  # restrict).
   module Associations
     extend ActiveSupport::Concern
     include ModelLoader
@@ -24,7 +27,7 @@ module ActiveItem
 
         case config[:dependent]
         when :restrict_with_exception
-          raise DeleteRestrictionError.new(name)
+          raise DeleteRestrictionError, name
         when :restrict_with_error
           error_message = config[:message] || "Cannot delete #{self.class.name} because dependent #{name} exist"
           errors.add(:base, error_message)
@@ -87,9 +90,7 @@ module ActiveItem
         )
 
         foreign_key_sym = foreign_key.to_sym
-        unless method_defined?(foreign_key_sym) || private_method_defined?(foreign_key_sym)
-          attr_accessor foreign_key_sym
-        end
+        attr_accessor foreign_key_sym unless method_defined?(foreign_key_sym) || private_method_defined?(foreign_key_sym)
 
         validates foreign_key_sym, presence: true unless optional
 
@@ -98,10 +99,10 @@ module ActiveItem
         define_method("#{association_name}=") { |record| set_belongs_to_association(association_name, record) }
 
         default_foreign_key = "#{association_name}_id"
-        if foreign_key.to_s != default_foreign_key
-          define_method(default_foreign_key) { send(foreign_key) }
-          define_method("#{default_foreign_key}=") { |value| send("#{foreign_key}=", value) }
-        end
+        return unless foreign_key.to_s != default_foreign_key
+
+        define_method(default_foreign_key) { send(foreign_key) }
+        define_method("#{default_foreign_key}=") { |value| send("#{foreign_key}=", value) }
       end
     end
 
@@ -111,19 +112,17 @@ module ActiveItem
       config = self.class._associations[name]
       return Relation.new(Object, conditions: { _empty: true }) unless config
 
-      if _preloaded_associations.key?(name)
-        return Relation.new(nil, preloaded_records: _preloaded_associations[name], class_name: config[:class_name])
-      end
+      return Relation.new(nil, preloaded_records: _preloaded_associations[name], class_name: config[:class_name]) if _preloaded_associations.key?(name)
 
       local_key_value = send(config[:primary_key])
       return Relation.new(nil, conditions: { _empty: true }, class_name: config[:class_name]) if local_key_value.nil?
 
       conditions = { config[:foreign_key].to_sym => local_key_value }
       relation = Relation.new(nil, conditions: conditions, index_name: config[:index],
-                              class_name: config[:class_name], owner: self)
+                                   class_name: config[:class_name], owner: self)
 
       if config[:scope]
-        if config[:scope].arity == 0
+        if config[:scope].arity.zero?
           relation.instance_exec(&config[:scope]) || relation
         else
           config[:scope].call(relation)
@@ -149,6 +148,7 @@ module ActiveItem
         record = klass.find(foreign_key_value)
       rescue ActiveItem::RecordNotFound
         raise unless config[:optional]
+
         record = nil
       end
       instance_variable_set(cache_var, record)

data/lib/active_item/base.rb

@@ -10,6 +10,9 @@ require 'active_model'
 require 'securerandom'
 
 module ActiveItem
+  # Base class for all ActiveItem models. Provides persistence, callbacks,
+  # validations, dirty tracking, and an ActiveRecord-like interface for
+  # DynamoDB tables.
   class Base
     include ActiveModel::Validations
     include ActiveSupport::Callbacks
@@ -29,14 +32,15 @@ module ActiveItem
     define_callbacks :save, :create, :update, :destroy, :validation
     define_model_callbacks :initialize, only: :after
 
-    attr_accessor :id, :created_at, :updated_at, :dbrecord
+    attr_reader :id
+    attr_accessor :created_at, :updated_at, :dbrecord
 
     def id=(value)
       @id = (value.to_s.strip.empty? ? nil : value)
     end
 
     set_callback :create, :before, :generate_primary_key
-    set_callback :create, :before, :set_created_timestamp
+    set_callback :create, :before, :assign_created_timestamp
     set_callback :destroy, :before, :check_dependent_associations
 
     def initialize(attributes = {})
@@ -46,11 +50,11 @@ module ActiveItem
       @_preloaded_associations = {}
       @new_record = true
 
-      if attributes.is_a?(Hash)
-        attributes.each do |key, value|
-          setter = "#{key}="
-          send(setter, value) if respond_to?(setter)
-        end
+      return unless attributes.is_a?(Hash)
+
+      attributes.each do |key, value|
+        setter = "#{key}="
+        send(setter, value) if respond_to?(setter)
       end
     end
 
@@ -63,9 +67,7 @@ module ActiveItem
     end
 
     def self.attribute_names
-      @attribute_names ||= begin
-        instance_methods.grep(/\A[a-z_][a-z0-9_]*=\z/).map { |m| m.to_s.chomp('=') }.sort
-      end
+      @attribute_names ||= instance_methods.grep(/\A[a-z_][a-z0-9_]*=\z/).map { |m| m.to_s.chomp('=') }.sort
     end
 
     def populate_attributes_from_item(item)
@@ -75,11 +77,11 @@ module ActiveItem
         value = nil
         found = false
         self.class.dynamo_key_variants(attr_name).each do |key|
-          if item.key?(key)
-            value = item[key]
-            found = true
-            break
-          end
+          next unless item.key?(key)
+
+          value = item[key]
+          found = true
+          break
         end
 
         instance_variable_set("@#{attr_name}", value) if found
@@ -105,11 +107,11 @@ module ActiveItem
             old_value = instance_variable_get("@#{attr_name}")
             instance_variable_set("@#{attr_name}", value)
 
-            if old_value != value && instance_variable_defined?(:@pending_changes)
-              @pending_changes ||= {}
-              @pending_changes[attr_name] ||= [old_value, nil]
-              @pending_changes[attr_name][1] = value
-            end
+            return unless old_value != value && instance_variable_defined?(:@pending_changes)
+
+            @pending_changes ||= {}
+            @pending_changes[attr_name] ||= [old_value, nil]
+            @pending_changes[attr_name][1] = value
           end
         end
       end
@@ -120,12 +122,12 @@ module ActiveItem
 
       def primary_key=(value)
         remove_method primary_key.to_sym
-        remove_method "#{primary_key}=".to_sym
+        remove_method :"#{primary_key}="
 
         @primary_key = value.to_s
 
         alias_method primary_key.to_sym, :id
-        alias_method "#{primary_key}=".to_sym, :id=
+        alias_method :"#{primary_key}=", :id=
       end
 
       def table_name
@@ -140,9 +142,7 @@ module ActiveItem
         @dynamodb ||= Aws::DynamoDB::Client.new(http_wire_trace: false)
       end
 
-      def dynamodb=(client)
-        @dynamodb = client
-      end
+      attr_writer :dynamodb
 
       def dynamo_attribute_map(mappings = nil)
         if mappings
@@ -155,6 +155,7 @@ module ActiveItem
       def to_dynamo_key(attr_name)
         attr_str = attr_name.to_s
         return dynamo_attribute_map[attr_str] if dynamo_attribute_map.key?(attr_str)
+
         attr_str.camelize(:lower)
       end
 
@@ -162,6 +163,7 @@ module ActiveItem
         key_str = dynamo_key.to_s
         reverse_map = dynamo_attribute_map.invert
         return reverse_map[key_str] if reverse_map.key?(key_str)
+
         key_str.underscore
       end
 
@@ -176,7 +178,7 @@ module ActiveItem
         normalized_item = normalize_dynamodb_values(item)
 
         record = allocate
-        record.instance_variable_set(:@id, normalized_item[self.primary_key])
+        record.instance_variable_set(:@id, normalized_item[primary_key])
         record.send(:populate_attributes_from_item, normalized_item)
         record.instance_variable_set(:@new_record, false)
         record.instance_variable_set(:@previously_changed, {})
@@ -209,43 +211,44 @@ module ActiveItem
       end
 
       # Callback DSL
-      def before_save(*args, &block)
+      def before_save(*args, &)
         options = args.extract_options!
         if options[:on]
           case options[:on].to_sym
-          when :create then set_callback(:create, :before, *args, &block)
-          when :update then set_callback(:update, :before, *args, &block)
+          when :create then set_callback(:create, :before, *args, &)
+          when :update then set_callback(:update, :before, *args, &)
           else raise ArgumentError, "Invalid on: option '#{options[:on]}'. Must be :create or :update"
           end
         else
-          set_callback(:save, :before, *args, &block)
+          set_callback(:save, :before, *args, &)
         end
       end
 
-      def after_save(*args, &block)
+      def after_save(*args, &)
         options = args.extract_options!
         if options[:on]
           case options[:on].to_sym
-          when :create then set_callback(:create, :after, *args, &block)
-          when :update then set_callback(:update, :after, *args, &block)
+          when :create then set_callback(:create, :after, *args, &)
+          when :update then set_callback(:update, :after, *args, &)
           else raise ArgumentError, "Invalid on: option '#{options[:on]}'. Must be :create or :update"
           end
         else
-          set_callback(:save, :after, *args, &block)
+          set_callback(:save, :after, *args, &)
         end
       end
 
-      def before_create(*args, &block) = set_callback(:create, :before, *args, &block)
-      def after_create(*args, &block) = set_callback(:create, :after, *args, &block)
-      def before_update(*args, &block) = set_callback(:update, :before, *args, &block)
-      def after_update(*args, &block) = set_callback(:update, :after, *args, &block)
-      def before_validation(*args, &block) = set_callback(:validation, :before, *args, &block)
-      def after_validation(*args, &block) = set_callback(:validation, :after, *args, &block)
-      def before_destroy(*args, &block) = set_callback(:destroy, :before, *args, &block)
-      def after_destroy(*args, &block) = set_callback(:destroy, :after, *args, &block)
+      def before_create(...) = set_callback(:create, :before, ...)
+      def after_create(...) = set_callback(:create, :after, ...)
+      def before_update(...) = set_callback(:update, :before, ...)
+      def after_update(...) = set_callback(:update, :after, ...)
+      def before_validation(...) = set_callback(:validation, :before, ...)
+      def after_validation(...) = set_callback(:validation, :after, ...)
+      def before_destroy(...) = set_callback(:destroy, :before, ...)
+      def after_destroy(...) = set_callback(:destroy, :after, ...)
 
       def scope(name, body)
-        raise ArgumentError, "scope body must be callable (Proc/Lambda)" unless body.respond_to?(:call)
+        raise ArgumentError, 'scope body must be callable (Proc/Lambda)' unless body.respond_to?(:call)
+
         _scopes[name.to_sym] = body
         define_singleton_method(name) { all.instance_exec(&body) }
       end
@@ -257,7 +260,8 @@ module ActiveItem
       private
 
       def default_table_name
-        raise "Cannot generate table name for anonymous class" unless name
+        raise 'Cannot generate table name for anonymous class' unless name
+
         ActiveItem.configuration.table_name_for(name)
       end
 
@@ -265,7 +269,7 @@ module ActiveItem
         super
         subclass.class_eval do
           alias_method primary_key.to_sym, :id
-          alias_method "#{primary_key}=".to_sym, :id=
+          alias_method :"#{primary_key}=", :id=
         end
       end
     end
@@ -279,12 +283,14 @@ module ActiveItem
     end
 
     def reload
-      raise "Cannot reload a new record" if new_record?
+      raise 'Cannot reload a new record' if new_record?
+
       fresh_record = self.class.find(id)
       raise "Record not found: #{self.class.name} with id #{id}" unless fresh_record
 
       self.class.attribute_names.each do |attr_name|
         next if attr_name == 'dbrecord'
+
         value = fresh_record.instance_variable_get("@#{attr_name}")
         instance_variable_set("@#{attr_name}", value)
       end
@@ -308,12 +314,17 @@ module ActiveItem
     def attributes
       attrs = {}
       pk_name = self.class.primary_key
-      pk_value = send(pk_name) rescue instance_variable_get("@#{pk_name}")
+      pk_value = begin
+        send(pk_name)
+      rescue StandardError
+        instance_variable_get("@#{pk_name}")
+      end
       attrs['id'] = pk_value
       attrs[pk_name] = pk_value
 
       self.class.attribute_names.each do |attr_name|
         next if attr_name == 'dbrecord'
+
         value = instance_variable_get("@#{attr_name}")
         attrs[attr_name] = value unless value.nil?
       end
@@ -324,11 +335,17 @@ module ActiveItem
     end
 
     def inspect
-      pk_value = send(self.class.primary_key) rescue id
+      begin
+        send(self.class.primary_key)
+      rescue StandardError
+        id
+      end
       attr_strs = self.class.attribute_names.filter_map do |attr|
         next if attr == 'dbrecord'
+
         value = instance_variable_get("@#{attr}")
         next if value.nil?
+
         "#{attr}: #{value.inspect}"
       end
       "#<#{self.class.name} #{attr_strs.join(', ')}>"
@@ -356,9 +373,10 @@ module ActiveItem
       end
 
       return false if result == false
+
       changes_applied
       true
-    rescue => e
+    rescue StandardError => e
       dynamo_logger.error("Failed to save #{self.class.name}: #{e.message}")
       raise e
     end
@@ -406,10 +424,11 @@ module ActiveItem
     def destroy
       result = run_callbacks(:destroy) { perform_destroy }
       return false if result == false
+
       true
     rescue DeleteRestrictionError
       false
-    rescue => e
+    rescue StandardError => e
       dynamo_logger.error("Failed to destroy #{self.class.name}: #{e.message}")
       errors.add(:base, e.message)
       false
@@ -418,7 +437,7 @@ module ActiveItem
     def delete
       perform_destroy
       true
-    rescue => e
+    rescue StandardError => e
       dynamo_logger.error("Failed to delete #{self.class.name}: #{e.message}")
       false
     end
@@ -426,11 +445,11 @@ module ActiveItem
     def assign_attributes(attributes)
       attributes.each do |key, value|
         setter = "#{key}="
-        if respond_to?(setter)
-          old_value = send(key)
-          @pending_changes[key.to_s] = [old_value, value] if old_value != value
-          send(setter, value)
-        end
+        next unless respond_to?(setter)
+
+        old_value = send(key)
+        @pending_changes[key.to_s] = [old_value, value] if old_value != value
+        send(setter, value)
       end
     end
 
@@ -457,7 +476,7 @@ module ActiveItem
     end
 
     def valid?(context = nil)
-      return super(context) if defined?(@running_validations) && @running_validations
+      return super if defined?(@running_validations) && @running_validations
 
       @running_validations = true
       begin
@@ -477,8 +496,8 @@ module ActiveItem
       instance_variable_set("@#{pk}", @id) if pk != 'id'
     end
 
-    def set_created_timestamp
-      @created_at ||= Time.now.utc.iso8601
+    def assign_created_timestamp
+      @created_at ||= Time.now.utc.iso8601 # rubocop:disable Naming/MemoizedInstanceVariableName
     end
 
     def dynamodb
@@ -508,11 +527,11 @@ module ActiveItem
 
       dynamo_logger.info("#{self.class.name} created (#{self.class.primary_key}: #{id})")
     rescue Aws::DynamoDB::Errors::ConditionalCheckFailedException
-      errors.add(:id, "already exists")
+      errors.add(:id, 'already exists')
       false
     rescue Aws::DynamoDB::Errors::AccessDeniedException => e
       raise ActiveItem::AccessDeniedError.new(model_name: self.class.name, table: table_name,
-                                                operation: 'PutItem', original_error: e)
+                                              operation: 'PutItem', original_error: e)
     end
 
     def build_dynamodb_item
@@ -521,6 +540,7 @@ module ActiveItem
       dynamodb_attributes.each do |attr|
         value = instance_variable_get("@#{attr}")
         next if value.nil?
+
         dynamo_key = self.class.to_dynamo_key(attr)
         item[dynamo_key] = value
       end
@@ -559,7 +579,7 @@ module ActiveItem
         end
       end
 
-      update_parts << "updatedAt = :updatedAt"
+      update_parts << 'updatedAt = :updatedAt'
       attr_values[':updatedAt'] = Time.now.utc.iso8601
 
       update_expression = "SET #{update_parts.join(', ')}"
@@ -576,7 +596,7 @@ module ActiveItem
       dynamodb.update_item(params)
     rescue Aws::DynamoDB::Errors::AccessDeniedException => e
       raise ActiveItem::AccessDeniedError.new(model_name: self.class.name, table: table_name,
-                                                operation: 'UpdateItem', original_error: e)
+                                              operation: 'UpdateItem', original_error: e)
     end
 
     def perform_destroy
@@ -585,7 +605,7 @@ module ActiveItem
       dynamo_logger.info("#{self.class.name} deleted (#{key}: #{send(key)})")
     rescue Aws::DynamoDB::Errors::AccessDeniedException => e
       raise ActiveItem::AccessDeniedError.new(model_name: self.class.name, table: table_name,
-                                                operation: 'DeleteItem', original_error: e)
+                                              operation: 'DeleteItem', original_error: e)
     end
   end
 end

data/lib/active_item/composed_of.rb

@@ -3,30 +3,34 @@
 require 'active_support/concern'
 
 module ActiveItem
+  # Implements value object composition, allowing models to aggregate multiple
+  # attributes into a single nested DynamoDB map and expose them as a Ruby
+  # value object.
   module ComposedOf
     extend ActiveSupport::Concern
 
     def populate_composed_attributes_from_item(item)
       self.class.compositions.each do |part_id, config|
         dynamo_key = self.class.to_dynamo_key(part_id.to_s)
-        vo_class = Object.const_get(config[:class_name])
-
-        if item[dynamo_key].is_a?(Hash)
-          vo = if vo_class.respond_to?(:from_dynamo_map)
-                 vo_class.from_dynamo_map(item[dynamo_key])
-               else
-                 kwargs = {}
-                 config[:mapping].each do |_model_attr, vo_attr|
-                   key = self.class.to_dynamo_key(vo_attr.to_s)
-                   kwargs[vo_attr] = item[dynamo_key][key] || item[dynamo_key][vo_attr.to_s]
-                 end
-                 vo_class.new(**kwargs)
+        vo_class = config[:class_name].safe_constantize
+        next unless vo_class
+
+        next unless item[dynamo_key].is_a?(Hash)
+
+        vo = if vo_class.respond_to?(:from_dynamo_map)
+               vo_class.from_dynamo_map(item[dynamo_key])
+             else
+               kwargs = {}
+               config[:mapping].each_value do |vo_attr|
+                 key = self.class.to_dynamo_key(vo_attr.to_s)
+                 kwargs[vo_attr] = item[dynamo_key][key] || item[dynamo_key][vo_attr.to_s]
                end
+               vo_class.new(**kwargs)
+             end
 
-          instance_variable_set("@_composed_#{part_id}", vo)
-          config[:mapping].each do |model_attr, vo_attr|
-            instance_variable_set("@#{model_attr}", vo.send(vo_attr))
-          end
+        instance_variable_set("@_composed_#{part_id}", vo)
+        config[:mapping].each do |model_attr, vo_attr|
+          instance_variable_set("@#{model_attr}", vo.send(vo_attr))
         end
       end
     end
@@ -46,7 +50,7 @@ module ActiveItem
           item[dynamo_key] = vo.to_dynamo_map
         else
           map = {}
-          config[:mapping].each do |_model_attr, vo_attr|
+          config[:mapping].each_value do |vo_attr|
             key = self.class.to_dynamo_key(vo_attr.to_s)
             map[key] = vo.send(vo_attr)
           end
@@ -86,6 +90,7 @@ module ActiveItem
 
       changes.each do |field, (_old_val, new_val)|
         next if composed_flat_keys.include?(field)
+
         dynamo_key = self.class.to_dynamo_key(field)
         if new_val.nil?
           remove_parts << "#field#{idx}"
@@ -98,7 +103,7 @@ module ActiveItem
         idx += 1
       end
 
-      changed_compositions.each do |part_id, _config|
+      changed_compositions.each_key do |part_id|
         remove_instance_variable("@_composed_#{part_id}") if instance_variable_defined?("@_composed_#{part_id}")
         vo = send(part_id)
         dynamo_key = self.class.to_dynamo_key(part_id.to_s)
@@ -132,9 +137,10 @@ module ActiveItem
       dynamodb.update_item(params)
     end
 
+    # Class-level DSL for declaring composed_of value objects on a model.
     module ClassMethods
       def compositions
-        @_compositions ||= {}
+        @compositions ||= {}
       end
 
       def composed_of(part_id, options = {})
@@ -151,7 +157,9 @@ module ActiveItem
           ivar = "@_composed_#{part_id}"
           return instance_variable_get(ivar) if instance_variable_defined?(ivar)
 
-          vo_class = Object.const_get(class_name)
+          vo_class = class_name.safe_constantize
+          raise NameError, "Unknown value object class: #{class_name}" unless vo_class
+
           values = mapping.map { |model_attr, _vo_attr| send(model_attr) }
 
           if allow_nil && values.all? { |v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
@@ -173,17 +181,20 @@ module ActiveItem
         define_method("#{part_id}=") do |value|
           ivar = "@_composed_#{part_id}"
 
+          vo_class = class_name.safe_constantize
+          raise NameError, "Unknown value object class: #{class_name}" unless vo_class
+
           if value.nil?
             mapping.each_key { |model_attr| send("#{model_attr}=", nil) }
             instance_variable_set(ivar, nil)
-          elsif value.is_a?(Object.const_get(class_name))
+          elsif value.is_a?(vo_class)
             mapping.each { |model_attr, vo_attr| send("#{model_attr}=", value.send(vo_attr)) }
             instance_variable_set(ivar, value)
           elsif converter
-            converted = converter.is_a?(Proc) ? converter.call(value) : Object.const_get(class_name).send(converter, value)
+            converted = converter.is_a?(Proc) ? converter.call(value) : vo_class.send(converter, value)
             send("#{part_id}=", converted)
           elsif value.is_a?(Hash)
-            vo = Object.const_get(class_name).new(**value.transform_keys(&:to_sym))
+            vo = vo_class.new(**value.transform_keys(&:to_sym))
             send("#{part_id}=", vo)
           else
             raise ArgumentError, "Cannot assign #{value.class} to #{part_id}. Expected #{class_name}, Hash, or nil."

data/lib/active_item/configuration.rb

@@ -3,6 +3,8 @@
 require 'logger'
 
 module ActiveItem
+  # Holds global settings for ActiveItem including logger, table prefix, and
+  # environment. Used to derive DynamoDB table names from model class names.
   class Configuration
     attr_accessor :logger, :table_prefix, :environment
 

data/lib/active_item/database_helpers.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'set'
-
 module ActiveItem
+  # Low-level DynamoDB operations (get, put, delete, query, scan) with
+  # automatic pagination and access-denied error wrapping.
   module DatabaseHelpers
     def get(key)
       response = dynamodb.get_item(table_name: table_name, key: key)
@@ -78,7 +78,7 @@ module ActiveItem
 
     def raise_access_denied(operation, original_error)
       raise ActiveItem::AccessDeniedError.new(model_name: name, table: table_name,
-                                                operation: operation, original_error: original_error)
+                                              operation: operation, original_error: original_error)
     end
   end
 end