activeitem 0.0.13 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e20ffb5a359af1d27e15e389e30505d40a742edbe2c9c98ab76e4498fd70239e
-  data.tar.gz: 031b9d01ad6f636f1fb27c4752e36b10eedecf2d3909b2e11939f4c49368db4a
+  metadata.gz: 2706d94d7f88c19fdb9fc14d8a9408d1f8dc088a5eabf2e583d60351173b9870
+  data.tar.gz: 41c8e00d8b5a45ec26b58123efc86437795e1921c59dc8c44f3a770727496702
 SHA512:
-  metadata.gz: a6bc6e95cc4f1a87c81bf6afc15191a43bbdd037ac8fdf98dd2216585ab21903eaca17c30b6ce9e41f1e4ae5f4a01c31d8992cab1a628d132e7c0e9dadf911f2
-  data.tar.gz: 19b6490facb7f9b3fa4224ab7e97867b65fde49fa99da5c202eec89db36f1da6b7dc70ec1bae53d5fc5f4003a2628db0f071120f88b6ec1a1074d4eada5a0646
+  metadata.gz: 41689642db2d18371ae7f9c7987a72d001f3aa18d5e7bb3f0a7248100e5de2a8aa6cb039742057c176bfb6f9eeaa02a240847d50c64f6f02c54372da6c069020
+  data.tar.gz: 5c1a35c85c0b6d641fd630681fccb4995637eb733c50eada9a197a1c2fd503cc62855c1ad14eb81e19ccf324e1da2941ab93cbf87b72e5116285b8b5e49ed7a8

data/lib/active_item/associations.rb

@@ -52,6 +52,12 @@ module ActiveItem
         end
 
         association_name = name.to_sym
+
+        if options[:through]
+          define_has_many_through(association_name, options)
+          return
+        end
+
         class_name = options[:class_name] || name.to_s.singularize.camelize
         foreign_key = options[:foreign_key] || "#{self.name.underscore}_id"
         index_name = options[:index]
@@ -72,12 +78,36 @@ module ActiveItem
         end
       end
 
+      private
+
+      def define_has_many_through(association_name, options)
+        through_name = options[:through].to_sym
+        source_name = options[:source]&.to_sym || association_name.to_s.singularize.to_sym
+        class_name = options[:class_name] || association_name.to_s.singularize.camelize
+
+        self._associations = _associations.merge(
+          association_name => {
+            type: :has_many_through, through: through_name, source: source_name,
+            class_name: class_name
+          }
+        )
+
+        define_method(association_name) { load_has_many_through_association(association_name) }
+
+        define_method(:"#{association_name}_count") do
+          _preloaded_counts.key?(association_name) ? _preloaded_counts[association_name] : send(association_name).length
+        end
+      end
+
+      public
+
       def belongs_to(name, options = {})
         association_name = name.to_sym
         class_name = options[:class_name] || name.to_s.camelize
         foreign_key = options[:foreign_key] || "#{name}_id"
         remote_primary_key = options[:primary_key]
         optional = options.fetch(:optional, false)
+        index_option = options.fetch(:index, true)
 
         self._associations = _associations.merge(
           association_name => {
@@ -91,6 +121,8 @@ module ActiveItem
 
         validates foreign_key_sym, presence: true unless optional
 
+        register_belongs_to_index(association_name, foreign_key, index_option)
+
         define_method(association_name) { load_belongs_to_association(association_name) }
 
         define_method("#{association_name}=") { |record| set_belongs_to_association(association_name, record) }
@@ -101,6 +133,21 @@ module ActiveItem
         define_method(default_foreign_key) { send(foreign_key) }
         define_method("#{default_foreign_key}=") { |value| send("#{foreign_key}=", value) }
       end
+
+      def register_belongs_to_index(association_name, foreign_key, index_option)
+        return if index_option == false
+
+        index_name = if index_option.is_a?(String)
+                       index_option
+                     else
+                       "#{association_name.to_s.camelize}Index"
+                     end
+
+        @_belongs_to_indexes ||= {}
+        @_belongs_to_indexes = @_belongs_to_indexes.merge(
+          index_name => { partition_key: foreign_key }
+        )
+      end
     end
 
     private
@@ -129,6 +176,35 @@ module ActiveItem
       end
     end
 
+    # Load a has_many :through association.
+    # Two queries: GSI query on join table → batch_find on target table.
+    def load_has_many_through_association(name)
+      config = self.class._associations[name]
+      return Relation.new(Object, conditions: { _empty: true }) unless config
+
+      # If preloaded (via includes), return cached records
+      return Relation.new(nil, preloaded_records: _preloaded_associations[name], class_name: config[:class_name]) if _preloaded_associations.key?(name)
+
+      through_name = config[:through]
+      source_name = config[:source]
+      target_class = safe_constantize_model(config[:class_name])
+
+      # Query 1: Load intermediate records via the through association
+      intermediate_records = send(through_name).to_a
+
+      # Determine the foreign key on the join model that points to the target
+      # Convention: source_name + "_id" (e.g., :author → "author_id")
+      target_foreign_key = "#{source_name}_id"
+      target_ids = intermediate_records.filter_map { |r| r.send(target_foreign_key) }.uniq
+
+      return Relation.new(nil, preloaded_records: [], class_name: config[:class_name]) if target_ids.empty?
+
+      # Query 2: Batch load target records
+      target_records = target_class.batch_find(target_ids)
+
+      Relation.new(nil, preloaded_records: target_records, class_name: config[:class_name])
+    end
+
     def load_belongs_to_association(name)
       config = self.class._associations[name]
       return nil unless config

data/lib/active_item/query_helpers.rb

@@ -327,7 +327,7 @@ module ActiveItem
       if index_definitions
         @index_definitions = index_definitions
       else
-        RECENT_INDEX.merge(@index_definitions || {})
+        RECENT_INDEX.merge(@_belongs_to_indexes || {}).merge(@index_definitions || {})
       end
     end
 

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.
@@ -1557,6 +1590,8 @@ module ActiveItem
         preload_belongs_to(records, assoc_name, assoc_config)
       when :has_many
         preload_has_many_records(records, assoc_name, assoc_config)
+      when :has_many_through
+        preload_has_many_through(records, assoc_name, assoc_config)
       end
     end
 
@@ -1567,12 +1602,16 @@ module ActiveItem
 
       case mode
       when :count
-        unless assoc_config[:type] == :has_many
+        unless %i[has_many has_many_through].include?(assoc_config[:type])
           raise ArgumentError,
                 "count preloading only supported for has_many (got #{assoc_config[:type]} for #{assoc_name})"
         end
 
-        preload_has_many_counts(records, assoc_name, assoc_config)
+        if assoc_config[:type] == :has_many_through
+          preload_has_many_through_counts(records, assoc_name, assoc_config)
+        else
+          preload_has_many_counts(records, assoc_name, assoc_config)
+        end
       when :records
         preload_symbol_association(records, assoc_name)
       else
@@ -1800,6 +1839,71 @@ module ActiveItem
         record._preloaded_associations[assoc_name] = associated
       end
     end
+
+    # Preload has_many :through associations efficiently.
+    # 3 total queries for N parent records:
+    #   1. Load all intermediate (join) records for all parents (parallel GSI queries)
+    #   2. Collect unique target IDs from intermediates
+    #   3. Single batch_find for all target records
+    #
+    # @param records [Array] Parent records
+    # @param assoc_name [Symbol] Association name (e.g., :authors)
+    # @param config [Hash] Association config from _associations
+    def preload_has_many_through(records, assoc_name, config)
+      through_name = config[:through]
+      source_name = config[:source]
+      target_class = safe_constantize_model(config[:class_name])
+
+      through_config = resolved_model._associations[through_name]
+      raise ArgumentError, "Unknown through association: #{through_name}" unless through_config
+
+      # Step 1: Preload the intermediate association on all records
+      preload_has_many_records(records, through_name, through_config)
+
+      # Step 2: Collect all target IDs from intermediate records
+      target_foreign_key = "#{source_name}_id"
+      all_target_ids = []
+      intermediate_by_parent = {}
+
+      records.each do |record|
+        intermediates = record._preloaded_associations[through_name] || []
+        ids = intermediates.filter_map { |r| r.send(target_foreign_key) }
+        intermediate_by_parent[record.id] = ids
+        all_target_ids.concat(ids)
+      end
+
+      all_target_ids.uniq!
+
+      # Step 3: Single batch_find for all target records
+      target_records_by_id = if all_target_ids.any?
+                               target_class.batch_find(all_target_ids).to_h { |r| [r.id, r] }
+                             else
+                               {}
+                             end
+
+      # Cache resolved target records on each parent
+      records.each do |record|
+        ids = intermediate_by_parent[record.id] || []
+        associated = ids.filter_map { |tid| target_records_by_id[tid] }
+        record._preloaded_associations[assoc_name] = associated
+      end
+    end
+
+    # Preload has_many :through counts efficiently.
+    # Uses the intermediate association's count per parent (avoids loading target records).
+    def preload_has_many_through_counts(records, assoc_name, config)
+      through_name = config[:through]
+      through_config = resolved_model._associations[through_name]
+      raise ArgumentError, "Unknown through association: #{through_name}" unless through_config
+
+      # Count of through records == count of target records (1:1 via join)
+      preload_has_many_counts(records, through_name, through_config)
+
+      # Copy the through counts as the through-association counts
+      records.each do |record|
+        record._preloaded_counts[assoc_name] = record._preloaded_counts[through_name] || 0
+      end
+    end
   end
 
   # WhereChain enables the where.not(...) syntax

data/lib/active_item/version.rb

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

metadata

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