delayable 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c001bbe027f6b3996e3fc497c5b72a7e32a9f53fca0a6a6f4f04c928231289bc
-  data.tar.gz: 9978c0fa7bce102c9105abfb72d54f674e4e8795fc0331a4181d776ef4e92dbd
+  metadata.gz: fbc0e3130501e50157a5dd2807576126022d145f89a3a005eb596b41c3456ecf
+  data.tar.gz: 729e2cf6548e11b220d7f8f19da46e55c1e520de3046ced844c5b858e4b1b2e5
 SHA512:
-  metadata.gz: ab775ae0fe6c43a1e9c59547f8837c80240d5c5ddda4cef7e7f404496b3f89dde80c838bce19350837ef7ed23eb6cf11a4f5e0741a6dc568e30a1b5fccea0964
-  data.tar.gz: 30e3510fa4f70edb0400fa469ada55255bf9552d6302d490b36b2878994ad58c3199b5d7ef1af86fe17dd0e3a1e3689edda6f7bd1a814de12fec95c30588474f
+  metadata.gz: 3bd0b541a0d948c9c320a0ed7caf4e8f5585a147ed551c7e1b1c397c119cf4a23969ac510888c0f985e1d7c00997fac896fbdc3aa850d9ba0dc0865670336bf2
+  data.tar.gz: c81b5c272398ea577e9030852410a7813a8abcad24d7ec3ea3843e36b1529a0dfd79647d80cfe12edc093dc298ea2963c45680894376405ee15d4c8a94e58fa0

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## Unreleased
+
+## 0.5.0 - 2026-08-03
+
+### Added
+
+- Added class-level `_all_later` helpers for delayed instance methods.
+- Added bulk enqueue support through `ActiveJob.perform_all_later`, with individual enqueue fallback for Rails 7.0 and adapters without bulk support.

data/README.md

@@ -1,10 +1,19 @@
 # Delayable
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+A Ruby gem that makes it easy to convert any method call into a background job using ActiveJob. Simply include the `Delayable` module and use the `delay` class method to mark methods that should be available for background execution.
+
+## Features
+
+- **Easy Background Jobs**: Convert any instance or class method into a background job with minimal setup
+- **Current Attributes Preservation**: Automatically preserves Rails `Current` attributes across job boundaries
+- **Flexible Configuration**: Configure queue names, delays, and concurrency limits per method
+- **Method Parameter Support**: Full support for regular arguments, keyword arguments, and blocks
+- **Bang Method Handling**: Automatic support for methods ending with `!`
+- **Bulk Enqueuing**: Enqueue the same instance method for many receivers at once
+- **ActiveJob Integration**: Seamlessly integrates with your existing ActiveJob setup
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -13,7 +22,7 @@ gem "delayable"
 
 And then execute:
 ```bash
-$ bundle
+$ bundle install
 ```
 
 Or install it yourself as:
@@ -21,8 +30,463 @@ Or install it yourself as:
 $ gem install delayable
 ```
 
+## Prerequisites
+
+Before using Delayable, ensure you have the following defined in your Rails application:
+
+1. **ApplicationJob**: Your base job class
+2. **Current**: A CurrentAttributes class for maintaining context
+
+```ruby
+# app/jobs/application_job.rb
+class ApplicationJob < ActiveJob::Base
+  # Your job configuration
+end
+
+# app/models/current.rb
+class Current < ActiveSupport::CurrentAttributes
+  attribute :user, :request_id, :user_agent
+  # Add other attributes as needed
+end
+```
+
+## Basic Usage
+
+### Instance Methods
+
+Include `Delayable` in your class and use the `delay` method to mark methods for background execution:
+
+```ruby
+class DataProcessor
+  include Delayable
+
+  def process_csv_import(file_path, user_id)
+    user = User.find(user_id)
+    CSV.foreach(file_path, headers: true) do |row|
+      user.records.create!(row.to_h)
+    end
+  end
+  delay :process_csv_import
+
+  def sync_external_data(api_endpoint, last_sync_time)
+    # Fetch and process data from external API
+    ExternalApiClient.new(api_endpoint).sync_data_since(last_sync_time)
+  end
+  delay :sync_external_data
+end
+
+# Usage
+processor = DataProcessor.new
+processor.process_csv_import_later("/tmp/users.csv", 123)
+processor.sync_external_data_later("https://api.example.com/data", 1.hour.ago)
+```
+
+### Bulk Instance Methods
+
+Every delayed instance method also gets a class-level `_all_later` helper. It creates one job per receiver and passes the same positional and keyword arguments to each:
+
+```ruby
+class Unit
+  include Delayable
+
+  def sync_channex_availability(date_from, date_to, channel:)
+    # Sync availability for this unit
+  end
+  delay :sync_channex_availability, queue: :integrations
+end
+
+Unit.sync_channex_availability_all_later(
+  units,
+  Date.current,
+  1.year.from_now.to_date,
+  channel: :channex
+)
+```
+
+The helper preserves `Current.attributes` and all generated job configuration. A configured wait applies to every job and can be overridden per bulk call:
+
+```ruby
+Unit.sync_channex_availability_all_later(
+  units,
+  date_from,
+  date_to,
+  channel: :channex,
+  wait: 30.seconds
+)
+```
+
+Bang methods use `_all_later!`, such as `Unit.refresh_all_later!(units)`. Delayable does not remove duplicate receivers; use `units.uniq` when needed. An empty collection returns without enqueuing anything.
+
+Bulk helpers are only generated for instance methods. Delayed class methods still use their regular `_later` helper.
+
+Delayable uses `ActiveJob.perform_all_later` when available (Rails 7.1+). A true bulk queue operation requires an ActiveJob adapter that implements `enqueue_all`; otherwise ActiveJob enqueues each job individually. On Rails 7.0, Delayable also falls back to individual enqueues.
+
+### Class Methods
+
+You can also delay class methods by setting the `class_method: true` option:
+
+```ruby
+class ReportGenerator
+  include Delayable
+
+  def self.generate_monthly_report(month, year)
+    # Generate report logic
+  end
+  delay :generate_monthly_report, class_method: true
+
+  def self.cleanup_old_reports!
+    # Cleanup logic
+  end
+  delay :cleanup_old_reports!, class_method: true
+end
+
+# Usage
+ReportGenerator.generate_monthly_report_later(12, 2023)
+ReportGenerator.cleanup_old_reports_later!
+```
+
+### Methods with Bang (!)
+
+Delayable automatically handles methods ending with `!`:
+
+```ruby
+class DataProcessor
+  include Delayable
+
+  def process_data!
+    # Processing logic
+  end
+  delay :process_data!
+end
+
+# Usage - note the bang is preserved in the delayed method name
+processor = DataProcessor.new
+processor.process_data_later!  # Creates ProcessDataBangJob
+```
+
+## Advanced Configuration
+
+### Queue Configuration
+
+Specify which queue to use for the background job:
+
+```ruby
+class DataProcessor
+  include Delayable
+
+  def process_csv_import(file_path)
+    # Large CSV processing logic
+  end
+  delay :process_csv_import, queue: :data_processing
+
+  def sync_external_api(endpoint)
+    # API synchronization logic
+  end
+  delay :sync_external_api, queue: :integrations
+end
+```
+
+### Delay Execution
+
+Set a default delay for job execution:
+
+```ruby
+class CacheManager
+  include Delayable
+
+  def warm_cache(cache_key)
+    # Pre-populate cache logic
+  end
+  delay :warm_cache, wait: 5.minutes
+
+  def cleanup_expired_entries
+    # Cache cleanup logic
+  end
+  delay :cleanup_expired_entries, wait: 1.hour
+end
+
+# You can also override the delay at call time
+manager = CacheManager.new
+manager.warm_cache_later("user_stats", wait: 30.seconds)  # Overrides the 5.minutes default
+```
+
+### Concurrency Limits
+
+Limit how many jobs of this type can run concurrently using SolidQueue's concurrency controls:
+
+```ruby
+class ResourceIntensiveTask
+  include Delayable
+
+  def process_large_file(file_path)
+    # Heavy processing that should be limited
+  end
+  delay :process_large_file, limits_concurrency: { to: 2 }
+
+  def generate_report(report_type)
+    # Report generation that should run one at a time per report type
+  end
+  delay :generate_report, limits_concurrency: { 
+    to: 1, 
+    key: ->(run_data, report_type) { "report_#{report_type}" }
+  }
+  
+  def process_batch(batch_id, options = {})
+    # Process a batch with concurrency control per batch
+  end
+  delay :process_batch, limits_concurrency: {
+    to: 3,
+    key: ->(_run_data, batch_id) { "batch_#{batch_id}" }
+  }
+end
+```
+
+**Important:** When using the `key` proc with `limits_concurrency`, the proc receives the delayed job arguments. The first argument is Delayable's internal `run_data` hash (`current_attributes` and `record`), followed by the arguments passed to your delayed method.
+
+**Note:** The `limits_concurrency` feature requires SolidQueue as your ActiveJob backend. Other job backends (Sidekiq, Resque, etc.) do not support this feature and will ignore the setting.
+
+## Current Attributes
+
+Delayable automatically preserves Rails `Current` attributes across job boundaries:
+
+```ruby
+class AuditLogger
+  include Delayable
+
+  def log_action(action, resource_id)
+    AuditLog.create!(
+      action: action,
+      resource_id: resource_id,
+      user: Current.user,      # This will be preserved from the original request
+      request_id: Current.request_id
+    )
+  end
+  delay :log_action
+end
+
+# In a controller
+class PostsController < ApplicationController
+  def create
+    Current.user = current_user
+    Current.request_id = request.id
+    
+    post = Post.create!(post_params)
+    
+    # The job will have access to Current.user and Current.request_id
+    AuditLogger.new.log_action_later("create", post.id)
+  end
+end
+```
+
+## Working with ActiveRecord Models
+
+Delayable works seamlessly with ActiveRecord models:
+
+```ruby
+class User < ApplicationRecord
+  include Delayable
+
+  def update_profile_completeness
+    score = calculate_completeness_score
+    update!(profile_completeness: score)
+  end
+  delay :update_profile_completeness
+
+  def calculate_metrics!
+    update!(
+      total_posts: posts.count,
+      total_comments: comments.count,
+      last_activity: Time.current
+    )
+  end
+  delay :calculate_metrics!
+
+  def archive_old_data!
+    # Archive user's old posts, comments, etc.
+    posts.where('created_at < ?', 1.year.ago).update_all(archived: true)
+    comments.where('created_at < ?', 1.year.ago).delete_all
+  end
+  delay :archive_old_data!
+end
+
+# Usage
+user = User.find(123)
+user.update_profile_completeness_later
+user.calculate_metrics_later!
+user.archive_old_data_later!
+```
+
+## Job Naming Convention
+
+Delayable automatically generates job class names based on your method names to ensure logging and debugging remain clear and meaningful:
+
+| Method Name | Method Type | Generated Job Class |
+|-------------|-------------|-------------------|
+| `process_data` | instance | `YourClass::ProcessDataJob` |
+| `process_data!` | instance | `YourClass::ProcessDataBangJob` |
+| `generate_report` | class | `YourClass::ClassGenerateReportJob` |
+| `cleanup!` | class | `YourClass::ClassCleanupBangJob` |
+
+This naming convention ensures that when you're monitoring job queues, reading logs, or debugging failed jobs, you can immediately understand what method was being executed and in what context. The job name directly corresponds to your original method, making it easy to trace issues back to your application code.
+
+## Error Handling
+
+Since Delayable creates standard ActiveJob jobs, you can use all the standard ActiveJob error handling mechanisms. Put defaults on `ApplicationJob`, or pass a block to `delay` to configure the generated job class:
+
+```ruby
+# In your ApplicationJob
+class ApplicationJob < ActiveJob::Base
+  retry_on StandardError, wait: :exponentially_longer, attempts: 5
+  discard_on ActiveRecord::RecordNotFound
+end
+
+class BookingSync
+  include Delayable
+
+  def sync_channex_bookings
+    # Sync bookings
+  end
+  delay :sync_channex_bookings,
+        limits_concurrency: {
+          to: 1,
+          key: ->(run_data) { "#{run_data[:record].to_global_id}-channex-bookings" }
+        } do
+    retry_on Channex::Api::ConnectionError,
+             wait: :polynomially_longer,
+             attempts: 5
+  end
+end
+```
+
+## Testing
+
+Delayable integrates with ActiveJob's testing helpers:
+
+```ruby
+require 'test_helper'
+
+class DataProcessorTest < ActiveSupport::TestCase
+  include ActiveJob::TestHelper
+
+  test "CSV import is enqueued" do
+    processor = DataProcessor.new
+    
+    assert_enqueued_jobs 1, only: DataProcessor::ProcessCsvImportJob do
+      processor.process_csv_import_later("/tmp/data.csv", 123)
+    end
+  end
+
+  test "CSV data is imported" do
+    processor = DataProcessor.new
+    
+    perform_enqueued_jobs do
+      processor.process_csv_import_later("/tmp/data.csv", 123)
+    end
+    
+    # Assert data was imported
+    user = User.find(123)
+    assert user.records.count > 0
+  end
+
+  test "current attributes are preserved" do
+    Current.user = users(:admin)
+    
+    perform_enqueued_jobs do
+      AuditLogger.new.log_action_later("test", 123)
+    end
+    
+    log = AuditLog.last
+    assert_equal users(:admin), log.user
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep Jobs Idempotent**: Design your delayed methods to be safely retried
+2. **Use Appropriate Queues**: Separate different types of work into different queues
+3. **Handle Failures Gracefully**: Use ActiveJob's retry and error handling features
+4. **Monitor Job Performance**: Use tools like Sidekiq's web UI or similar for your job backend
+5. **Test Background Behavior**: Always test both the enqueuing and execution of your jobs
+
+## Configuration Examples
+
+### Multiple Options Combined
+
+```ruby
+class ComplexProcessor
+  include Delayable
+
+  def process_batch(batch_id, options = {})
+    # Complex processing logic
+  end
+  delay :process_batch, 
+        queue: :batch_processing,
+        wait: 30.seconds,
+        limits_concurrency: { to: 3, key: ->(_run_data, batch_id) { "batch_#{batch_id}" } }
+end
+```
+
+### Dynamic Delays
+
+```ruby
+class NotificationSender
+  include Delayable
+
+  def send_reminder(user_id, urgency = :normal)
+    # Send reminder logic
+  end
+  delay :send_reminder
+
+  def send_reminder_with_delay(user_id, urgency = :normal)
+    delay_time = case urgency
+    when :urgent then 0.seconds
+    when :normal then 1.hour
+    when :low then 1.day
+    end
+    
+    send_reminder_later(user_id, urgency, wait: delay_time)
+  end
+end
+```
+
+## Troubleshooting
+
+### Debugging
+
+To see what jobs are being created, you can inspect the generated job classes:
+
+```ruby
+# In rails console
+DataProcessor::ProcessCsvImportJob.new.class.name
+# => "DataProcessor::ProcessCsvImportJob"
+
+DataProcessor::ProcessCsvImportJob.queue_name
+# => "default"
+```
+
+## Requirements
+
+- Ruby >= 3.4.0
+- Rails >= 7.0.4.3
+- ActiveJob configured with a backend (Sidekiq, Resque, etc.)
+- An ActiveJob adapter with `enqueue_all` support for a true bulk queue operation (optional)
+- **SolidQueue** (optional) - Required only if using `limits_concurrency` feature
+
 ## Contributing
-Contribution directions go here.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Add tests for your changes
+4. Make sure all tests pass (`bundle exec rake test`)
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create a new Pull Request
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/trobrock/delayable/CHANGELOG.md) for details about changes in each version.

data/lib/delayable/version.rb

@@ -1,3 +1,3 @@
 module Delayable
-  VERSION = '0.4.1'.freeze
+  VERSION = '0.5.0'.freeze
 end

data/lib/delayable.rb

@@ -12,28 +12,54 @@ module Delayable
   end
 
   class_methods do
-    def delay(method_name, class_method: false, wait: nil, limits_concurrency: nil, queue: :default)
+    def delay(method_name, class_method: false, wait: nil, limits_concurrency: nil, queue: :default, &job_configuration)
       job = const_set(
         delayable_job_name(method_name, class_method:),
-        delayable_job_class(method_name, class_method:, concurrency_limits: limits_concurrency, queue:)
+        delayable_job_class(
+          method_name,
+          class_method:,
+          concurrency_limits: limits_concurrency,
+          queue:,
+          &job_configuration
+        )
       )
 
       defined_wait = wait
+      build_job = method(:delayable_build_job)
+      extract_wait = method(:delayable_extract_wait)
+      enqueue_jobs = method(:delayable_enqueue_jobs)
       delayable_define_method(class_method:, method_name:) do |*arguments, **kwargs|
-        wait = kwargs.key?(:wait) ? kwargs.delete(:wait) : defined_wait
-        run_data = { current_attributes: Current.attributes, record: self }
-        job.set(wait:).perform_later(run_data, *arguments, **kwargs)
+        job_wait = extract_wait.call(kwargs, defined_wait)
+        build_job.call(job, self, job_wait, arguments, kwargs, enqueue: true)
+      end
+
+      return if class_method
+
+      delayable_define_bulk_method(method_name) do |receivers, *arguments, **kwargs|
+        receivers = receivers.to_a
+        next if receivers.empty?
+
+        job_wait = extract_wait.call(kwargs, defined_wait)
+        jobs = receivers.map { |receiver| build_job.call(job, receiver, job_wait, arguments, kwargs) }
+        enqueue_jobs.call(jobs)
       end
     end
 
     private
 
-    def delayable_job_class(method_name, class_method: false, concurrency_limits: nil, queue: :default)
+    def delayable_job_class(
+      method_name,
+      class_method: false,
+      concurrency_limits: nil,
+      queue: :default,
+      &job_configuration
+    )
       klass = self
       Class.new(ApplicationJob) do
         queue_as queue
 
-        limits_concurrency(**concurrency_limits) if concurrency_limits.is_a?(Hash)
+        limits_concurrency(**concurrency_limits) if concurrency_limits.is_a?(Hash) && respond_to?(:limits_concurrency)
+        class_eval(&job_configuration) if job_configuration
 
         define_method(:perform) do |run_data = {}, *arguments, **kwargs|
           Current.set(run_data[:current_attributes] || {}) do
@@ -43,6 +69,24 @@ module Delayable
       end
     end
 
+    def delayable_build_job(job, receiver, wait, arguments, kwargs, enqueue: false)
+      run_data = { current_attributes: Current.attributes, record: receiver }
+      return job.set(wait:).perform_later(run_data, *arguments, **kwargs) if enqueue
+
+      job.new(run_data, *arguments, **kwargs).set(wait:)
+    end
+
+    def delayable_extract_wait(kwargs, defined_wait)
+      kwargs.key?(:wait) ? kwargs.delete(:wait) : defined_wait
+    end
+
+    def delayable_enqueue_jobs(jobs)
+      return ActiveJob.perform_all_later(*jobs) if ActiveJob.respond_to?(:perform_all_later)
+
+      jobs.each(&:enqueue)
+      nil
+    end
+
     def delayable_job_name(method_name, class_method: false)
       class_name = bang_method?(method_name) ? "#{method_name.to_s.chomp('!').camelize}Bang" : method_name.to_s.camelize
       :"#{'Class' if class_method}#{class_name}Job"
@@ -50,8 +94,16 @@ module Delayable
 
     def delayable_define_method(class_method:, method_name:, &)
       define_method_type = class_method ? :define_singleton_method : :define_method
-      method_name = bang_method?(method_name) ? "#{method_name.to_s.chomp('!')}_later!" : "#{method_name}_later"
-      public_send(define_method_type, method_name, &)
+      public_send(define_method_type, delayable_method_name(method_name), &)
+    end
+
+    def delayable_define_bulk_method(method_name, &)
+      define_singleton_method(delayable_method_name(method_name, bulk: true), &)
+    end
+
+    def delayable_method_name(method_name, bulk: false)
+      suffix = bulk ? '_all_later' : '_later'
+      bang_method?(method_name) ? "#{method_name.to_s.chomp('!')}#{suffix}!" : "#{method_name}#{suffix}"
     end
 
     def bang_method?(method_name)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: delayable
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Trae Robrock
 bindir: exe
 cert_chain: []
-date: 2025-04-25 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -33,6 +33,7 @@ extra_rdoc_files: []
 files:
 - ".rubocop.yml"
 - ".ruby-version"
+- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - Rakefile