activeitem 0.0.17 → 0.0.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a4b1c7cc7af49e67776f895886bdf472d1e801ab3280f3ea28101bd20b8a701
-  data.tar.gz: 7415931df8a26b187e4a9ab52586b67c7cea08f0fa3a476ab09b863c02250835
+  metadata.gz: 7992e08eadef33c715ba67e3869454bca7cf174cae56e419982b81de608075c6
+  data.tar.gz: dc1e6e803c91bb774f7e0c2edf43f6ca744ac10221bba26b8a5a4a4d7466f425
 SHA512:
-  metadata.gz: b8c97c1ffadb921d440702b5299cf4bb219ba97ad0351cef7bebfea1125e74bf027ddc0546e1a254da8d6da8952598bf170368404c6ab65074ecc8379bfaec3b
-  data.tar.gz: b9936169d15857e1423de8f622ddfe85b7be05458739f569ce1983dd6565f234ae2789f12978ac530106cc98203906a99b9666805d1e2e43c7e0a275e7c41d06
+  metadata.gz: ee3f192c4bc8d0ea583f85462cb28841092e0389ed7682b6cfec753f446b687174385f74b81fa58ddc411c34b7dea1fd348aeea243a1109b0ae1ae0915565036
+  data.tar.gz: f21580968c7db755fbc2c75e4cdb2cf8c9b3ab7f400a5a83954fb297215a78ec9adf4968f2ed3e526d771747c80460d50a8b7c23f70c6e2489a5d8e84f03b4a2

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.0.19
+
+### Added
+
+- **`validates_associated`** — Validates that associated records (loaded via `has_many`) are valid before saving the parent. Only checks in-memory/loaded records — does not trigger DB queries for unloaded associations.
+
+- **`accepts_nested_attributes_for`** — Define nested attribute writers for has_many associations. Supports create, update, and destroy of child records through the parent's save. Nested saves are now wrapped in a DynamoDB transaction for atomicity — if any child operation fails, none are committed.
+
+  ```ruby
+  class Conversation < ActiveItem::Base
+    has_many :messages
+    accepts_nested_attributes_for :messages, allow_destroy: true
+  end
+
+  conversation.messages_attributes = [
+    { role: 'user', body: 'Hello' },
+    { id: 'msg-1', body: 'Updated text' },
+    { id: 'msg-2', _destroy: true }
+  ]
+  conversation.save  # atomic: all children created/updated/destroyed together
+  ```
+
+- **`Relation#loaded?`** — Check whether a has_many relation's records have been loaded into memory.
+
+## 0.0.18
+
+### Added
+
+- **Transactional saves** — `save`, `save!`, `destroy`, and `destroy!` now automatically enroll in the current transaction when called inside a `Model.transaction` block. This enables an ActiveRecord-style implicit API:
+
+  ```ruby
+  Model.transaction do
+    record1.save!
+    record2.save!
+    record3.destroy!
+  end
+  ```
+
+  All operations are committed atomically at block end. The explicit API (`txn.put(record)`) continues to work for backwards compatibility.
+
+- **RecordInvalid exception** — `save!` now raises `ActiveItem::RecordInvalid` with the record attached, instead of a generic `StandardError`. This matches ActiveRecord behavior.
+
+- **Transaction.active?** — class method to check if code is executing inside a transaction block.
+
 ## 0.0.13
 
 ### Changed

data/lib/active_item/associations.rb

@@ -152,9 +152,92 @@ module ActiveItem
           index_name => { partition_key: dynamo_key }
         )
       end
-    end
 
-    private
+      # Allows nested attributes for associated records, similar to Rails.
+      # Defines a writer method that builds or updates child records through the parent.
+      #
+      # @example
+      #   class Conversation < ApplicationRecord
+      #     has_many :messages
+      #     accepts_nested_attributes_for :messages
+      #   end
+      #
+      #   conversation.messages_attributes = [
+      #     { role: 'user', body: 'Hello' },
+      #     { role: 'assistant', body: 'Hi there' }
+      #   ]
+      #   conversation.save  # saves parent and creates children
+      #
+      # @param associations [Array<Symbol>] Association names to accept nested attributes for
+      # @param options [Hash] Options (allow_destroy: true to enable _destroy flag)
+      def accepts_nested_attributes_for(*associations, **options)
+        associations.each do |association_name|
+          define_nested_attributes_writer(association_name, options)
+        end
+      end
+
+      private
+
+      def define_nested_attributes_writer(association_name, options)
+        writer_method = :"#{association_name}_attributes="
+        allow_destroy = options.fetch(:allow_destroy, false)
+
+        # Store pending nested records for saving after parent
+        define_method(writer_method) do |attributes_collection|
+          attributes_collection = attributes_collection.values if attributes_collection.is_a?(Hash)
+          @_nested_attributes ||= {}
+          @_nested_attributes[association_name] = { records: attributes_collection, allow_destroy: allow_destroy }
+        end
+
+        # Hook into save to persist nested records
+        define_method(:save_with_nested) do
+          result = save_without_nested
+          return result unless result
+
+          save_nested_attributes
+          result
+        end
+
+        define_method(:save_nested_attributes) do
+          return unless instance_variable_defined?(:@_nested_attributes) && @_nested_attributes
+
+          self.class.transaction do
+            @_nested_attributes.each do |assoc_name, config|
+              assoc_config = self.class._associations[assoc_name]
+              next unless assoc_config
+
+              target_class = safe_constantize_model(assoc_config[:class_name])
+              foreign_key = assoc_config[:foreign_key]
+
+              config[:records].each do |attrs|
+                attrs = attrs.transform_keys(&:to_sym)
+
+                if attrs[:_destroy] && config[:allow_destroy]
+                  if attrs[:id]
+                    record = target_class.find(attrs[:id])
+                    record.destroy!
+                  end
+                elsif attrs[:id]
+                  record = target_class.find(attrs[:id])
+                  record.assign_attributes(attrs.except(:id, :_destroy))
+                  record.save!
+                else
+                  target_class.create!(attrs.merge(foreign_key.to_sym => id))
+                end
+              end
+            end
+          end
+
+          @_nested_attributes = nil
+        end
+
+        # Wrap save to include nested attributes
+        return if method_defined?(:save_without_nested)
+
+        alias_method :save_without_nested, :save
+        alias_method :save, :save_with_nested
+      end
+    end
 
     def load_has_many_association(name)
       config = self.class._associations[name]

data/lib/active_item/base.rb

@@ -349,6 +349,9 @@ module ActiveItem
     def save(validate: true)
       return false if validate && !run_validations
 
+      # If inside a transaction block, enroll this save in the transaction
+      return enroll_in_transaction if Transaction.active?
+
       result = run_callbacks :save do
         if new_record?
           run_callbacks(:create) { perform_create }
@@ -368,7 +371,9 @@ module ActiveItem
     end
 
     def save!
-      raise StandardError, "Validation failed: #{errors.full_messages.join(', ')}" unless save
+      raise RecordInvalid.new(self), "Validation failed: #{errors.full_messages.join(', ')}" unless save
+
+      true
     end
 
     def self.create(attributes = {})
@@ -383,10 +388,39 @@ module ActiveItem
       obj
     end
 
+    # Execute a block within a transaction context.
+    #
+    # Supports two usage patterns:
+    #
+    # 1. Explicit API (block receives transaction):
+    #      Model.transaction do |txn|
+    #        txn.put(record1)
+    #        txn.update(record2)
+    #      end
+    #
+    # 2. Implicit API (transactional saves):
+    #      Model.transaction do
+    #        record1.save!
+    #        record2.save!
+    #        record3.destroy!
+    #      end
+    #
+    # In the implicit API, save/destroy calls are automatically enrolled.
+    # The transaction is committed when the block completes successfully.
+    # If an exception is raised, no changes are committed (all-or-nothing).
+    #
+    # @yield [Transaction] the transaction object (optional)
+    # @raise [TransactionError] if the transaction fails
     def self.transaction
       txn = Transaction.new
-      yield txn
-      txn.execute!
+      Transaction.current = txn
+      begin
+        # Support both explicit (yield txn) and implicit (no block param) APIs
+        yield txn if block_given?
+        txn.execute!
+      ensure
+        Transaction.current = nil
+      end
     end
 
     def self.transaction_find(items)
@@ -408,6 +442,9 @@ module ActiveItem
     end
 
     def destroy
+      # If inside a transaction block, enroll this destroy in the transaction
+      return enroll_destroy_in_transaction if Transaction.active?
+
       result = run_callbacks(:destroy) { perform_destroy }
       return false if result == false
 
@@ -421,7 +458,9 @@ module ActiveItem
     end
 
     def destroy!
-      destroy || raise(RecordNotDestroyed.new(nil, self))
+      raise RecordNotDestroyed.new(nil, self) unless destroy
+
+      true
     end
 
     def delete
@@ -460,6 +499,37 @@ module ActiveItem
 
     private
 
+    # Enroll this record's save operation in the current transaction.
+    # Called when save is invoked inside a transaction block.
+    def enroll_in_transaction
+      txn = Transaction.current
+
+      result = run_callbacks :save do
+        if new_record?
+          run_callbacks(:create) { txn.put(self) }
+        else
+          run_callbacks(:update) { txn.update(self) }
+        end
+      end
+
+      return false if result == false
+
+      # Mark changes as applied (will be committed when transaction executes)
+      # Note: @new_record stays true until transaction.execute! completes
+      true
+    end
+
+    # Enroll this record's destroy operation in the current transaction.
+    # Called when destroy is invoked inside a transaction block.
+    def enroll_destroy_in_transaction
+      txn = Transaction.current
+
+      result = run_callbacks(:destroy) { txn.delete(self) }
+      return false if result == false
+
+      true
+    end
+
     def generate_primary_key
       @id = nil if @id.to_s.strip.empty?
       @id ||= SecureRandom.uuid

data/lib/active_item/errors.rb

@@ -4,6 +4,17 @@ module ActiveItem
   class RecordNotFound < StandardError; end
   class TransactionError < StandardError; end
 
+  # Raised by save! when validations fail.
+  class RecordInvalid < StandardError
+    attr_reader :record
+
+    def initialize(record = nil)
+      @record = record
+      message = record ? "Validation failed: #{record.errors.full_messages.join(', ')}" : 'Validation failed'
+      super(message)
+    end
+  end
+
   # Raised when an IAM policy denies a DynamoDB operation on a table.
   class AccessDeniedError < StandardError
     attr_reader :model_name, :table, :operation, :original_error

data/lib/active_item/relation.rb

@@ -31,6 +31,11 @@ module ActiveItem
       @select_attributes = select_attributes # Projection expression attributes
     end
 
+    # Whether the relation's records have been loaded from DynamoDB.
+    def loaded?
+      @loaded
+    end
+
     # Chainable includes - preload associations to avoid N+1 queries
     #
     # Supports three forms:

data/lib/active_item/transaction.rb

@@ -3,15 +3,49 @@
 module ActiveItem
   # Wraps DynamoDB TransactWriteItems, allowing multiple put, update, and
   # delete operations to be committed atomically (up to 100 items).
+  #
+  # Supports two usage patterns:
+  #
+  # 1. Explicit API (original):
+  #      Model.transaction do |txn|
+  #        txn.put(record1)
+  #        txn.update(record2)
+  #      end
+  #
+  # 2. Implicit API (transactional saves):
+  #      Model.transaction do
+  #        record1.save!
+  #        record2.save!
+  #        record3.destroy!
+  #      end
+  #
+  # In the implicit API, save/destroy calls inside the block are automatically
+  # enrolled in the transaction and committed atomically at block end.
   class Transaction
     MAX_ITEMS = 100
 
     attr_reader :operations
 
+    class << self
+      # Thread-local storage for the current transaction context
+      def current
+        Thread.current[:activeitem_current_transaction]
+      end
+
+      def current=(txn)
+        Thread.current[:activeitem_current_transaction] = txn
+      end
+    end
+
     def initialize
       @operations = []
     end
 
+    # Check if we're inside a transaction block
+    def self.active?
+      !current.nil?
+    end
+
     def put(record, condition: nil)
       record.instance_variable_set(:@id, SecureRandom.uuid) unless record.id
       pk = record.class.primary_key

data/lib/active_item/validations.rb

@@ -50,5 +50,47 @@ module ActiveItem
     def validates_uniqueness_of(*attributes, **options)
       validates(*attributes, uniqueness: options.empty? || options)
     end
+
+    # Validates that the associated records are valid.
+    # If any associated record is invalid, errors are added to the parent.
+    #
+    # @example
+    #   class Conversation < ApplicationRecord
+    #     has_many :messages
+    #     validates_associated :messages
+    #   end
+    #
+    #   conversation.messages.build(role: "invalid")
+    #   conversation.valid? # => false
+    #   conversation.errors[:messages] # => ["is invalid"]
+    def validates_associated(*associations, **options)
+      validates(*associations, associated: options.empty? || options)
+    end
+  end
+
+  # ActiveModel validator that checks associated records are valid.
+  # Validates in-memory built records (via .build) and already-loaded records.
+  # Does not trigger a DB query — only checks what's already in memory.
+  class AssociatedValidator < ActiveModel::EachValidator
+    def validate_each(record, attribute, _value)
+      association_config = record.class._associations[attribute]
+      return unless association_config
+
+      associated = record.send(attribute)
+
+      # Only validate loaded/cached records — don't trigger a DB query
+      records = if associated.respond_to?(:loaded?) && associated.loaded?
+                  associated.to_a
+                else
+                  []
+                end
+
+      records.each do |child|
+        next if child.valid?
+
+        record.errors.add(attribute, :invalid, **options.except(:on))
+        break
+      end
+    end
   end
 end

data/lib/active_item/version.rb

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

metadata

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