activeitem 0.0.1 → 0.0.2

data/lib/active_item/errors.rb

@@ -4,6 +4,7 @@ module ActiveItem
   class RecordNotFound < StandardError; end
   class TransactionError < StandardError; end
 
+  # Raised when an IAM policy denies a DynamoDB operation on a table.
   class AccessDeniedError < StandardError
     attr_reader :model_name, :table, :operation, :original_error
 
@@ -13,10 +14,12 @@ module ActiveItem
       @operation = operation
       @original_error = original_error
       super("#{model_name} is not allowed to #{operation} on #{table}. " \
-            "Ensure the IAM role has access to this table.")
+            'Ensure the IAM role has access to this table.')
     end
   end
 
+  # Raised when a record cannot be deleted because dependent associations
+  # with :restrict_with_exception still exist.
   class DeleteRestrictionError < StandardError
     attr_reader :association_name
 

data/lib/active_item/logging.rb

@@ -9,6 +9,8 @@ module ActiveItem
     def debug(*); end
   end
 
+  # Provides a +dynamo_logger+ helper that delegates to the globally
+  # configured ActiveItem logger.
   module Logging
     private
 

data/lib/active_item/model_loader.rb

@@ -3,21 +3,13 @@
 require 'active_support/inflector'
 
 module ActiveItem
+  # Utility for resolving association class names to constants, attempting
+  # common model file paths when the constant is not yet loaded.
   module ModelLoader
     def safe_constantize_model(class_name)
-      return class_name.constantize if Object.const_defined?(class_name)
+      raise ArgumentError, "Invalid class name: #{class_name}" unless class_name.match?(/\A[A-Z][A-Za-z0-9]*(::[A-Z][A-Za-z0-9]*)*\z/)
 
-      file_name = class_name.underscore
-      # Try common model paths
-      ['.', 'models', 'app/models'].each do |dir|
-        path = File.join(dir, "#{file_name}.rb")
-        if File.exist?(path)
-          require path
-          break
-        end
-      end
-
-      class_name.constantize
+      class_name.safe_constantize || raise(NameError, "Unknown model: #{class_name}")
     end
   end
 end

data/lib/active_item/pagination.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
 module ActiveItem
+  # Cursor-based pagination for in-memory arrays of ActiveItem records.
+  # Provides a +paginate_array+ helper and a +PaginatedResult+ wrapper.
   module Pagination
     DEFAULT_PER_PAGE = 25
     MAX_PER_PAGE = 100
 
     def self.paginate_array(items, cursor = nil, per_page: DEFAULT_PER_PAGE)
-      per_page = [[per_page.to_i, 1].max, MAX_PER_PAGE].min
+      per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
 
       if cursor && !cursor.empty?
         cursor_time, cursor_id = cursor.split('|', 2)
-        items = items.drop_while { |i| ([(i.created_at || ''), i.id] <=> [cursor_time, cursor_id]) >= 0 }
+        items = items.drop_while { |i| ([i.created_at || '', i.id] <=> [cursor_time, cursor_id]) >= 0 }
       end
 
       page_items = items.first(per_page)
@@ -21,6 +23,7 @@ module ActiveItem
       PaginatedResult.new(items: page_items, next_cursor: next_cursor, per_page: per_page)
     end
 
+    # Enumerable wrapper around a page of results with cursor metadata.
     class PaginatedResult
       include Enumerable
 
@@ -40,10 +43,10 @@ module ActiveItem
         { next_cursor: next_cursor, has_more: has_more?, per_page: per_page }
       end
 
-      def each(&block) = items.each(&block)
+      def each(&) = items.each(&)
       def length = items.length
-      alias_method :size, :length
-      alias_method :count, :length
+      alias size length
+      alias count length
       def empty? = items.empty?
       def to_a = items
     end

data/lib/active_item/query_helpers.rb

@@ -1,13 +1,15 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 require_relative 'relation'
 
 module ActiveItem
+  # Class-level query interface providing find, where, batch operations,
+  # counting, existence checks, and automatic GSI index detection.
   module QueryHelpers
-
     def find(id)
       record = get({ primary_key.to_s => id })
       raise ActiveItem::RecordNotFound, "Couldn't find #{name} with '#{primary_key}'=#{id}" unless record
+
       instantiate(record)
     end
 
@@ -38,24 +40,23 @@ module ActiveItem
           items = response.responses[table_name] || []
           results.concat(items.map { |item| instantiate(item) })
 
-          # Check for unprocessed keys and retry with exponential backoff
+          # Check for unprocessed keys and retry with exponential backoff + jitter
           unprocessed = response.unprocessed_keys
-          if unprocessed&.any?
-            retries += 1
-            break if retries > max_retries
-
-            sleep(0.05 * (2**retries)) # Exponential backoff: 100ms, 200ms, 400ms...
-            request = unprocessed
-          else
-            break
-          end
+          break unless unprocessed&.any?
+
+          retries += 1
+          break if retries > max_retries
+
+          sleep(0.05 * (2**retries) * (0.5 + (rand * 0.5)))
+          request = unprocessed
+
         end
       end
 
       results
     rescue Aws::DynamoDB::Errors::AccessDeniedException => e
       raise ActiveItem::AccessDeniedError.new(model_name: name, table: table_name,
-                                                operation: 'BatchGetItem', original_error: e)
+                                              operation: 'BatchGetItem', original_error: e)
     end
 
     # Batch write multiple records using DynamoDB's BatchWriteItem
@@ -100,15 +101,14 @@ module ActiveItem
           response = dynamodb.batch_write_item(request_items: request)
 
           unprocessed = response.unprocessed_items
-          if unprocessed&.any?
-            retries += 1
-            break if retries > max_retries
-
-            sleep(0.05 * (2**retries))
-            request = unprocessed
-          else
-            break
-          end
+          break unless unprocessed&.any?
+
+          retries += 1
+          break if retries > max_retries
+
+          sleep(0.05 * (2**retries) * (0.5 + (rand * 0.5)))
+          request = unprocessed
+
         end
       end
 
@@ -116,7 +116,7 @@ module ActiveItem
       records
     rescue Aws::DynamoDB::Errors::AccessDeniedException => e
       raise ActiveItem::AccessDeniedError.new(model_name: name, table: table_name,
-                                                operation: 'BatchWriteItem', original_error: e)
+                                              operation: 'BatchWriteItem', original_error: e)
     end
 
     def find_by(**conditions)
@@ -228,10 +228,6 @@ module ActiveItem
       all.first
     end
 
-    def last
-      all.last
-    end
-
     # Count records with optional conditions or block
     #
     # @example Count all records
@@ -243,10 +239,10 @@ module ActiveItem
     # @example Count with block (Rails-like, loads all records)
     #   Customer.count { |c| c.email.include?('@gmail.com') }  # => 15
     #
-    def count(**conditions, &block)
+    def count(**conditions, &)
       if block_given?
         # Block provided - load all records and count with Ruby
-        all.count(&block)
+        all.count(&)
       elsif conditions.empty?
         # No conditions, no block - use efficient DynamoDB COUNT
         response = dynamodb.scan(
@@ -278,22 +274,16 @@ module ActiveItem
     # @return [Boolean] true if a record exists matching the conditions
     def exists?(id_or_conditions = nil, **conditions)
       # Handle single ID parameter: Customer.exists?('cust-123')
-      if id_or_conditions.is_a?(String) && conditions.empty?
-        return !!get({ primary_key.to_s => id_or_conditions })
-      end
+      return !!get({ primary_key.to_s => id_or_conditions }) if id_or_conditions.is_a?(String) && conditions.empty?
 
       # Merge positional hash with keyword arguments if both provided
-      if id_or_conditions.is_a?(Hash)
-        conditions = id_or_conditions.merge(conditions)
-      end
+      conditions = id_or_conditions.merge(conditions) if id_or_conditions.is_a?(Hash)
 
       # If checking by primary key only, use the efficient get operation
-      if conditions.keys.size == 1 && conditions.key?(primary_key.to_sym)
-        return !!get({ primary_key.to_s => conditions[primary_key.to_sym] })
-      end
+      return !!get({ primary_key.to_s => conditions[primary_key.to_sym] }) if conditions.keys.size == 1 && conditions.key?(primary_key.to_sym)
 
       # For other conditions, use where with limit 1 and count
-      where(**conditions).limit(1).count > 0
+      where(**conditions).limit(1).any?
     end
 
     def delete_all
@@ -340,16 +330,10 @@ module ActiveItem
 
       # First, try to find an index with the converted partition key
       indexes.each do |index_name, config|
-        if config[:partition_key].to_s == dynamo_partition_key
-          return index_name
-        end
-      end
+        return index_name if config[:partition_key].to_s == dynamo_partition_key
 
-      # Also try the original Ruby key (for legacy indexes defined with snake_case)
-      indexes.each do |index_name, config|
-        if config[:partition_key].to_s == ruby_partition_key
-          return index_name
-        end
+        # Also try the original Ruby key (for legacy indexes defined with snake_case)
+        return index_name if config[:partition_key].to_s == ruby_partition_key
       end
 
       # If not found, check if this is an association-based attribute
@@ -360,9 +344,7 @@ module ActiveItem
         dynamo_resolved_key = to_dynamo_key(resolved_key)
         indexes.each do |index_name, config|
           pk = config[:partition_key].to_s
-          if pk == dynamo_resolved_key || pk == resolved_key
-            return index_name
-          end
+          return index_name if pk == dynamo_resolved_key || pk == resolved_key
         end
       end
 
@@ -388,7 +370,7 @@ module ActiveItem
       foreign_key = association_config[:foreign_key]
 
       # If the foreign key is different from the attribute name, return it
-      foreign_key.to_s != attr_name ? foreign_key.to_s : nil
+      foreign_key.to_s == attr_name ? nil : foreign_key.to_s
     end
 
     # Build a condition expression for a single attribute
@@ -416,15 +398,11 @@ module ActiveItem
       dynamo_attr = to_dynamo_key(attr_str)
 
       # Handle nil - use attribute_not_exists (DynamoDB doesn't support = NULL)
-      if val.nil?
-        return ["attribute_not_exists(#attr#{idx})", { "#attr#{idx}" => dynamo_attr }, {}]
-      end
+      return ["attribute_not_exists(#attr#{idx})", { "#attr#{idx}" => dynamo_attr }, {}] if val.nil?
 
       # Handle case-insensitive search with ilike option
       # Uses DynamoDB's `contains` function with downcased value
-      if ilike && val.is_a?(String)
-        return build_ilike_condition(dynamo_attr, val, idx)
-      end
+      return build_ilike_condition(dynamo_attr, val, idx) if ilike && val.is_a?(String)
 
       # Handle ActiveItem model objects - extract primary key value
       # This allows queries like: Container.where(parent_container: some_container)
@@ -437,24 +415,16 @@ module ActiveItem
       end
 
       # Handle nested hash syntax: { address: { zip_code: '12345' } }
-      if val.is_a?(Hash)
-        return build_nested_hash_conditions(dynamo_attr, val, idx)
-      end
+      return build_nested_hash_conditions(dynamo_attr, val, idx) if val.is_a?(Hash)
 
       # Handle dot notation: 'address.zip_code'
-      if attr_str.include?('.')
-        return build_dot_notation_condition(attr_str, val, idx)
-      end
+      return build_dot_notation_condition(attr_str, val, idx) if attr_str.include?('.')
 
       # Handle Range values (BETWEEN, >=, <=)
-      if val.is_a?(Range)
-        return build_range_condition(dynamo_attr, val, idx)
-      end
+      return build_range_condition(dynamo_attr, val, idx) if val.is_a?(Range)
 
       # Handle array values (IN clause)
-      if val.is_a?(Array)
-        return build_in_condition(dynamo_attr, val, idx)
-      end
+      return build_in_condition(dynamo_attr, val, idx) if val.is_a?(Array)
 
       # Simple equality condition (use placeholder for reserved words)
       build_simple_condition(dynamo_attr, val, idx)
@@ -468,7 +438,7 @@ module ActiveItem
     # @param val [String] Search value (will be downcased)
     # @param idx [Integer] Index for unique placeholder names
     # @return [Array<String, Hash, Hash>] [expression, attribute_names, attribute_values]
-    def build_ilike_condition(attr, val, idx)
+    def build_ilike_condition(attr, _val, idx)
       # For case-insensitive search, we can't rely on DynamoDB's case-sensitive contains()
       # Instead, we'll return a condition that matches more broadly and filter in Ruby
       # We use attribute_exists to ensure the field exists, then filter everything in Ruby
@@ -494,15 +464,12 @@ module ActiveItem
         if nested_val.is_a?(Hash)
           # Recursively handle deeper nesting
           expr, names, values = build_nested_hash_conditions(full_path, nested_val, idx)
-          expressions << expr
-          all_names.merge!(names)
-          all_values.merge!(values)
         else
           expr, names, values = build_dot_notation_condition(full_path, nested_val, idx)
-          expressions << expr
-          all_names.merge!(names)
-          all_values.merge!(values)
         end
+        expressions << expr
+        all_names.merge!(names)
+        all_values.merge!(values)
       end
 
       [expressions.join(' AND '), all_names, all_values]
@@ -632,6 +599,5 @@ module ActiveItem
         }
       end
     end
-
   end
 end