activity_notification 2.4.1 → 2.5.1

data/lib/activity_notification/apis/notification_api.rb

@@ -1,7 +1,10 @@
+require 'activity_notification/apis/cascading_notification_api'
+
 module ActivityNotification
   # Defines API for notification included in Notification model.
   module NotificationApi
     extend ActiveSupport::Concern
+    include CascadingNotificationApi
 
     included do
       # Defines store_notification as private clas method
@@ -228,7 +231,8 @@ module ActivityNotification
           notify_later(target_type, notifiable, options)
         else
           targets = notifiable.notification_targets(target_type, options[:pass_full_options] ? options : options[:key])
-          unless targets.blank?
+          # Optimize blank check to avoid loading all records for ActiveRecord relations
+          unless targets_empty?(targets)
             notify_all(targets, notifiable, options)
           end
         end
@@ -269,10 +273,17 @@ module ActivityNotification
 
       # Generates notifications to specified targets.
       #
-      # @example Notify to all users
+      # For large target collections, this method uses batch processing to reduce memory consumption:
+      # - ActiveRecord::Relation: Uses find_each (loads in batches of 1000 records)
+      # - Mongoid::Criteria: Uses each with cursor batching
+      # - Arrays: Standard iteration (already in memory)
+      #
+      # @example Notify to all users (with ActiveRecord relation for memory efficiency)
       #   ActivityNotification::Notification.notify_all User.all, @comment
+      # @example Notify to all users with custom batch size
+      #   ActivityNotification::Notification.notify_all User.all, @comment, batch_size: 500
       #
-      # @param [Array<Object>] targets Targets to send notifications
+      # @param [ActiveRecord::Relation, Mongoid::Criteria, Array<Object>] targets Targets to send notifications
       # @param [Object] notifiable Notifiable instance
       # @param [Hash] options Options for notifications
       # @option options [String]                  :key                      (notifiable.default_notification_key) Key of the notification
@@ -284,23 +295,32 @@ module ActivityNotification
       # @option options [Boolean]                 :send_email               (true)                                Whether it sends notification email
       # @option options [Boolean]                 :send_later               (true)                                Whether it sends notification email asynchronously
       # @option options [Boolean]                 :publish_optional_targets (true)                                Whether it publishes notification to optional targets
+      # @option options [Integer]                 :batch_size               (1000)                                Batch size for ActiveRecord find_each (optional)
       # @option options [Hash<String, Hash>]      :optional_targets         ({})                                  Options for optional targets, keys are optional target name (:amazon_sns or :slack etc) and values are options
       # @return [Array<Notificaion>] Array of generated notifications
       def notify_all(targets, notifiable, options = {})
         if options[:notify_later]
           notify_all_later(targets, notifiable, options)
         else
-          targets.map { |target| notify_to(target, notifiable, options) }
+          # Optimize for large ActiveRecord relations by using batch processing
+          process_targets_in_batches(targets, notifiable, options)
         end
       end
       alias_method :notify_all_now, :notify_all
 
       # Generates notifications to specified targets later by ActiveJob queue.
       #
+      # Note: When passing ActiveRecord relations or Mongoid criteria to async jobs,
+      # they may be serialized to arrays before job execution, which can consume memory
+      # for large target sets. For very large datasets (10,000+ records), consider using
+      # notify_later with target_type instead, which generates notifications asynchronously
+      # without loading all targets upfront:
+      #   ActivityNotification::Notification.notify(:users, @comment, notify_later: true)
+      #
       # @example Notify to all users later
       #   ActivityNotification::Notification.notify_all_later User.all, @comment
       #
-      # @param [Array<Object>] targets Targets to send notifications
+      # @param [ActiveRecord::Relation, Mongoid::Criteria, Array<Object>] targets Targets to send notifications
       # @param [Object] notifiable Notifiable instance
       # @param [Hash] options Options for notifications
       # @option options [String]                  :key                      (notifiable.default_notification_key) Key of the notification
@@ -546,6 +566,59 @@ module ActivityNotification
         notification.after_store
         notification
       end
+
+      # Checks if targets collection is empty without loading all records
+      # @api private
+      # @param [Object] targets Targets collection (can be an ActiveRecord::Relation, Mongoid::Criteria, Array, etc.)
+      # @return [Boolean] True if targets is empty
+      def targets_empty?(targets)
+        # For ActiveRecord relations and Mongoid criteria, use exists? to avoid loading all records
+        if targets.respond_to?(:exists?)
+          !targets.exists?
+        else
+          # For arrays and other enumerables, use blank?
+          targets.blank?
+        end
+      end
+
+      # Processes targets in batches for memory efficiency with large collections
+      # @api private
+      # 
+      # For ActiveRecord::Relation, uses find_each which loads records in batches (default 1000).
+      # For Mongoid::Criteria, uses each which leverages MongoDB's cursor batching.
+      # For Arrays and other enumerables, uses standard iteration.
+      # 
+      # Note: When called from async jobs (notify_all_later), ActiveRecord relations may be
+      # serialized to arrays before reaching this method, which limits batch processing benefits.
+      # Consider using notify_later with target_type instead of notify_all_later with relations
+      # for large datasets in async scenarios.
+      #
+      # @param [Object] targets Targets collection (can be an ActiveRecord::Relation, Mongoid::Criteria, Array, etc.)
+      # @param [Object] notifiable Notifiable instance
+      # @param [Hash] options Options for notifications
+      # @option options [Integer] :batch_size (1000) Batch size for ActiveRecord find_each (optional)
+      # @return [Array<Notification>] Array of generated notifications
+      def process_targets_in_batches(targets, notifiable, options = {})
+        notifications = []
+        
+        # For ActiveRecord relations, use find_each to process in batches
+        # This loads records in batches (default 1000) to avoid loading all records into memory
+        if targets.respond_to?(:find_each)
+          batch_options = {}
+          batch_options[:batch_size] = options[:batch_size] if options[:batch_size]
+          
+          targets.find_each(**batch_options) do |target|
+            notification = notify_to(target, notifiable, options)
+            notifications << notification
+          end
+        else
+          # For arrays and other enumerables, use standard map approach
+          # Already in memory, so no batching benefit
+          notifications = targets.map { |target| notify_to(target, notifiable, options) }
+        end
+        
+        notifications
+      end
     end
 
     # :nocov:

data/lib/activity_notification/config.rb

@@ -82,6 +82,15 @@ module ActivityNotification
     #   @return [String] Email address as sender of notification email.
     attr_accessor :mailer_sender
 
+    # @overload mailer_cc
+    #   Returns carbon copy (CC) email address(es) for notification email
+    #   @return [String, Array<String>, Proc] CC email address(es) for notification email.
+    # @overload mailer_cc=(value)
+    #   Sets carbon copy (CC) email address(es) for notification email
+    #   @param [String, Array<String>, Proc] mailer_cc The new mailer_cc
+    #   @return [String, Array<String>, Proc] CC email address(es) for notification email.
+    attr_accessor :mailer_cc
+
     # @overload mailer
     #   Returns mailer class for email notification
     #   @return [String] Mailer class for email notification.
@@ -236,6 +245,7 @@ module ActivityNotification
       @subscribe_to_email_as_default            = nil
       @subscribe_to_optional_targets_as_default = nil
       @mailer_sender                            = nil
+      @mailer_cc                                = nil
       @mailer                                   = 'ActivityNotification::Mailer'
       @parent_mailer                            = 'ActionMailer::Base'
       @parent_job                               = 'ActiveJob::Base'

data/lib/activity_notification/mailers/helpers.rb

@@ -74,6 +74,7 @@ module ActivityNotification
             subject: :subject_for,
             from: :mailer_from,
             reply_to: :mailer_reply_to,
+            cc: :mailer_cc,
             message_id: nil
           }.each do |header_name, default_method|
             overridding_method_name = "overriding_notification_email_#{header_name.to_s}"
@@ -81,7 +82,12 @@ module ActivityNotification
                 @notification.notifiable.send(overridding_method_name, @target, key).present?
               @notification.notifiable.send(overridding_method_name, @target, key)
             elsif default_method
-              send(default_method, key)
+              # Special handling for methods that take target instead of key
+              if [:mailer_cc].include?(default_method)
+                send(default_method, @target)
+              else
+                send(default_method, key)
+              end
             else
               nil
             end
@@ -99,6 +105,26 @@ module ActivityNotification
           target.mailer_to
         end
 
+        # Returns carbon copy (CC) email address(es).
+        #
+        # @param [Object] target Target instance to notify
+        # @return [String, Array<String>, nil] CC email address(es) or nil
+        def mailer_cc(target)
+          if target.respond_to?(:mailer_cc)
+            target.mailer_cc
+          elsif ActivityNotification.config.mailer_cc.present?
+            if ActivityNotification.config.mailer_cc.is_a?(Proc)
+              # Get the notification key from current context
+              key = @notification ? @notification.key : nil
+              ActivityNotification.config.mailer_cc.call(key)
+            else
+              ActivityNotification.config.mailer_cc
+            end
+          else
+            nil
+          end
+        end
+
         # Returns sender email address as 'reply_to'.
         #
         # @param [String] key Key of the notification or batch notification email

data/lib/activity_notification/version.rb

@@ -1,3 +1,3 @@
 module ActivityNotification
-  VERSION = "2.4.1"
+  VERSION = "2.5.1"
 end

data/lib/generators/templates/activity_notification.rb

@@ -45,6 +45,14 @@ ActivityNotification.configure do |config|
   # note that it will be overwritten if you use your own mailer class with default "from" parameter.
   config.mailer_sender = 'please-change-me-at-config-initializers-activity_notification@example.com'
 
+  # Configure the carbon copy (CC) email address(es) for notification emails.
+  # You can set a single email address, an array of email addresses, or a Proc that returns either.
+  # Note that this can be overridden per target by defining a mailer_cc method in the target model,
+  # or per notification by defining overriding_notification_email_cc in the notifiable model.
+  # config.mailer_cc = 'admin@example.com'
+  # config.mailer_cc = ['admin@example.com', 'support@example.com']
+  # config.mailer_cc = ->(key){ key.include?('urgent') ? 'urgent@example.com' : nil }
+
   # Configure the class responsible to send e-mails.
   # config.mailer = "ActivityNotification::Mailer"