activeitem 0.0.14 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54985c6329129ceac142d8f176c14dfcc68548992f7e00d54a116592ee2a9276
-  data.tar.gz: abee89f1984d42b3dd72991c5db573370ed356d4272be0bb0d4d21163a233f50
+  metadata.gz: 6460db8a74ca7bcb5d28c0bfdb7c4a6c1eba5c5d68318245612dad78d1d1d282
+  data.tar.gz: 9fe2d9707efa0a41b74fa1c07c5c24453605baa5d24e3f1880c248c92c5a03b0
 SHA512:
-  metadata.gz: 456eb037d79395d8a63916245a681af7ad4a98a933cb294226658bf532886a7feb4fa2f90a2593cd1df34d4b5abd6d9299b206af2ad72cb96a5f1aa4ce1d3334
-  data.tar.gz: a0626e95bf4d42f4b1f1c0c453223e50214cbad0be8de67e76539f42ff2c3449027bf78f62a6708303db14195c10558972b9715e7c2f9bbf95c080b5d4bcf509
+  metadata.gz: 61ad96dc3dd1a28bda5a9af288bd17e1eef4f11b450f08efae26c1ea8f8060819727dde8d855d562e0fbbf2e6012096e159952d44c0d22255abc2384d85d80a9
+  data.tar.gz: 741d0e3a257199f62373c16960bea2d90fe26e37e9f4dcb8516cfb049170caac8a237c90ef1ba17dde88b356218b12f7e5e7d5f4a9d96abee7f64225639762f8

data/lib/active_item/relation.rb

@@ -374,6 +374,39 @@ module ActiveItem
       record
     end
 
+    # Build a new record with the foreign key pre-set (does not save).
+    # Usage: conversation.messages.build(role: "user", body: "hello")
+    # @param attributes [Hash] Attributes for the new record
+    # @return [ActiveItem::Base] The unsaved record
+    def build(attributes = {})
+      foreign_key, foreign_value = conditions.first
+      resolved_model.new(attributes.merge(foreign_key => foreign_value))
+    end
+
+    # Build and save a new record with the foreign key pre-set.
+    # Returns the record (may be invalid — check .persisted? or .errors).
+    # Usage: conversation.messages.create(role: "user", body: "hello")
+    # @param attributes [Hash] Attributes for the new record
+    # @return [ActiveItem::Base] The record (saved if valid)
+    def create(attributes = {})
+      record = build(attributes)
+      record.save
+      reload
+      record
+    end
+
+    # Build and save a new record with the foreign key pre-set.
+    # Raises ActiveItem::RecordInvalid if validations fail.
+    # Usage: conversation.messages.create!(role: "user", body: "hello")
+    # @param attributes [Hash] Attributes for the new record
+    # @return [ActiveItem::Base] The persisted record
+    def create!(attributes = {})
+      record = build(attributes)
+      record.save!
+      reload
+      record
+    end
+
     # Returns the DynamoDB operation that would be executed, without running it.
     # Analogous to ActiveRecord's .to_sql — shows the operation type, table, index,
     # key conditions, filters, and limits in DynamoDB terms.
@@ -514,7 +547,8 @@ module ActiveItem
       if effective_index && normalized_conditions.any? && normalized_conditions.values.first.is_a?(Array)
         index_config = resolved_model.indexes[effective_index] || {}
         ruby_partition_key = normalized_conditions.keys.first.to_s
-        dynamo_partition_key = index_config[:partition_key]&.to_s || resolved_model.to_dynamo_key(ruby_partition_key)
+        raw_pk = index_config[:partition_key]&.to_s || ruby_partition_key
+        dynamo_partition_key = resolved_model.to_dynamo_key(raw_pk)
         return fanout_paginated_query(effective_index, normalized_conditions, index_config, dynamo_partition_key,
                                       normalized_conditions.values.first, cursor, per_page)
       end
@@ -526,6 +560,12 @@ module ActiveItem
       else
         paginated_scan_with_conditions(normalized_conditions, exclusive_start_key, per_page)
       end
+    rescue Aws::DynamoDB::Errors::ValidationException => e
+      raise unless e.message.include?('specified index')
+
+      warn "[ActiveItem] WARNING: Index not found on table '#{resolved_model.table_name}'. " \
+           'Falling back to table scan. Create the index: belt setup tables && belt deploy'
+      paginated_scan_with_conditions(normalized_conditions, exclusive_start_key, per_page)
     rescue Aws::DynamoDB::Errors::AccessDeniedException => e
       raise ActiveItem::AccessDeniedError.new(model_name: resolved_model.name, table: resolved_model.table_name,
                                               operation: 'PaginatedQuery', original_error: e)
@@ -573,7 +613,8 @@ module ActiveItem
       partition_value = normalized_conditions.values.first
 
       index_config = resolved_model.indexes[idx_name] || {}
-      dynamo_partition_key = index_config[:partition_key]&.to_s || resolved_model.to_dynamo_key(ruby_partition_key)
+      raw_pk = index_config[:partition_key]&.to_s || ruby_partition_key
+      dynamo_partition_key = resolved_model.to_dynamo_key(raw_pk)
 
       params = {
         table_name: resolved_model.table_name,
@@ -755,7 +796,7 @@ module ActiveItem
                   effective_index = index_name || resolved_model.send(:detect_index_for_conditions, normalized_conditions)
 
                   if effective_index && normalized_conditions.any?
-                    query_with_index_normalized(effective_index, normalized_conditions)
+                    query_with_index_or_fallback(effective_index, normalized_conditions)
                   else
                     scan_with_conditions_normalized(normalized_conditions)
                   end
@@ -805,6 +846,13 @@ module ActiveItem
       end
 
       limit_value ? [total, limit_value].min : total
+    rescue Aws::DynamoDB::Errors::ValidationException => e
+      raise unless e.message.include?('specified index')
+
+      warn "[ActiveItem] WARNING: Index not found on table '#{resolved_model.table_name}'. " \
+           'Falling back to table scan for count. Create the index: belt setup tables && belt deploy'
+      # Retry without the index
+      count_via_scan(normalized_conditions)
     rescue Aws::DynamoDB::Errors::AccessDeniedException => e
       raise ActiveItem::AccessDeniedError.new(model_name: resolved_model.name, table: resolved_model.table_name,
                                               operation: 'Count', original_error: e)
@@ -815,7 +863,8 @@ module ActiveItem
       partition_value = normalized_conditions.values.first
 
       index_config = resolved_model.indexes[idx_name] || {}
-      dynamo_partition_key = index_config[:partition_key]&.to_s || resolved_model.to_dynamo_key(ruby_partition_key)
+      raw_partition_key = index_config[:partition_key]&.to_s || ruby_partition_key
+      dynamo_partition_key = resolved_model.to_dynamo_key(raw_partition_key)
 
       params = {
         table_name: resolved_model.table_name,
@@ -878,6 +927,26 @@ module ActiveItem
       params
     end
 
+    # Fallback count via scan when an index is missing
+    def count_via_scan(normalized_conditions)
+      total = 0
+      exclusive_start_key = nil
+
+      loop do
+        params = build_count_scan_params(normalized_conditions)
+        params[:exclusive_start_key] = exclusive_start_key if exclusive_start_key
+        params[:limit] = limit_value if limit_value
+
+        response = resolved_model.dynamodb.scan(params)
+        total += response.count
+        exclusive_start_key = response.last_evaluated_key
+        break unless exclusive_start_key
+        break if limit_value && total >= limit_value
+      end
+
+      limit_value ? [total, limit_value].min : total
+    end
+
     # Build scan params for a count-only scan
     def build_count_scan_params(normalized_conditions)
       filter_parts = []
@@ -911,7 +980,8 @@ module ActiveItem
       partition_value = normalized_conditions.values.first
 
       index_config = resolved_model.indexes[idx_name] || {}
-      dynamo_partition_key = index_config[:partition_key]&.to_s || resolved_model.to_dynamo_key(ruby_partition_key)
+      raw_pk = index_config[:partition_key]&.to_s || ruby_partition_key
+      dynamo_partition_key = resolved_model.to_dynamo_key(raw_pk)
 
       params = {
         table_name: resolved_model.table_name,
@@ -1049,6 +1119,18 @@ module ActiveItem
       foreign_key.to_s == attr_name ? nil : foreign_key.to_s
     end
 
+    # Attempt a GSI query, falling back to a filtered scan if the index doesn't exist.
+    # Logs a warning when falling back so the developer knows to create the index.
+    def query_with_index_or_fallback(idx_name, normalized_conditions)
+      query_with_index_normalized(idx_name, normalized_conditions)
+    rescue Aws::DynamoDB::Errors::ValidationException => e
+      raise unless e.message.include?('specified index')
+
+      warn "[ActiveItem] WARNING: Index '#{idx_name}' not found on table '#{resolved_model.table_name}'. " \
+           'Falling back to table scan. Create the index for better performance: belt setup tables && belt deploy'
+      scan_with_conditions_normalized(normalized_conditions)
+    end
+
     def query_with_index_normalized(idx_name, normalized_conditions)
       # Get the partition key from conditions (Ruby snake_case)
       ruby_partition_key = normalized_conditions.keys.first.to_s
@@ -1057,7 +1139,9 @@ module ActiveItem
       # Get the actual DynamoDB partition key name from the index definition
       # The index definition stores the DynamoDB key name (which may be camelCase)
       index_config = resolved_model.indexes[idx_name] || {}
-      dynamo_partition_key = index_config[:partition_key]&.to_s || resolved_model.to_dynamo_key(ruby_partition_key)
+      raw_partition_key = index_config[:partition_key]&.to_s || ruby_partition_key
+      # Always convert to DynamoDB key format (camelCase) for the expression
+      dynamo_partition_key = resolved_model.to_dynamo_key(raw_partition_key)
 
       return fanout_query(idx_name, normalized_conditions, index_config, dynamo_partition_key, partition_value) if partition_value.is_a?(Array)
 

data/lib/active_item/version.rb

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

metadata

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