active_job-performs 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5741d785f1439dac15d6ec2734d40e5560013f69025977713771309c7f15c4c7
-  data.tar.gz: c01e5d7ebe8f599024cd5eba79011a959d2e31c8d5141b787b46d55b1150b73b
+  metadata.gz: 566acd14649609a2e16b658a93fe276f80609866c61fb37c11e720b581bc0f76
+  data.tar.gz: 5174b18e562c53966639bb16e3d729885d99f1ebe01163175a1513dded11cbff
 SHA512:
-  metadata.gz: 7ea09dcf8da5a0c7c1f5181ed70e07c3a3028d7d12c5c84cece6c6d59ab6a7921ea7ddc05180fd2b8f551332277a2e032bee0c057398a33b4e7f3a645f451c3f
-  data.tar.gz: 32899d17334f35819a1aa61ffa56c58a492d1b304a003b1e5d6156a26450087e2ac7083021a312269d2c2ee0519e43ad78d129629c6641036f5ad222130f6c3a
+  metadata.gz: f2fd767c6bd1c66d26a046e84dea4cd2ea0bfdb0ec50452699151e90fba9856b14875ab1a98371cf2727423a31871db4af432a965784a9cf61d92b58917ce0d2
+  data.tar.gz: cd9628dce5378c14ecae35da1fc83ae4487ea0ece02a5e4a78226572778ca7d370c5975e99ff880fa9bf030f026c244d1d3cf2abac838fb7d1bec373f7327cbf

data/Gemfile

@@ -16,4 +16,4 @@ gem "debug"
 gem "activejob",    ">= 7.1"
 gem "activerecord", ">= 7.1"
 
-gem "sqlite3"
+gem "sqlite3", "~> 1.4"

data/Gemfile.lock

@@ -1,22 +1,22 @@
 PATH
   remote: .
   specs:
-    active_job-performs (0.3.0)
+    active_job-performs (0.3.2)
       activejob (>= 6.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activejob (7.1.1)
-      activesupport (= 7.1.1)
+    activejob (7.1.3.4)
+      activesupport (= 7.1.3.4)
       globalid (>= 0.3.6)
-    activemodel (7.1.1)
-      activesupport (= 7.1.1)
-    activerecord (7.1.1)
-      activemodel (= 7.1.1)
-      activesupport (= 7.1.1)
+    activemodel (7.1.3.4)
+      activesupport (= 7.1.3.4)
+    activerecord (7.1.3.4)
+      activemodel (= 7.1.3.4)
+      activesupport (= 7.1.3.4)
       timeout (>= 0.4.0)
-    activesupport (7.1.1)
+    activesupport (7.1.3.4)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
@@ -26,46 +26,43 @@ GEM
       minitest (>= 5.1)
       mutex_m
       tzinfo (~> 2.0)
-    base64 (0.1.1)
-    bigdecimal (3.1.4)
-    concurrent-ruby (1.2.2)
+    base64 (0.2.0)
+    bigdecimal (3.1.8)
+    concurrent-ruby (1.3.3)
     connection_pool (2.4.1)
-    debug (1.8.0)
-      irb (>= 1.5.0)
-      reline (>= 0.3.1)
-    drb (2.1.1)
-      ruby2_keywords
+    debug (1.9.2)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    drb (2.2.1)
     globalid (1.2.1)
       activesupport (>= 6.1)
-    i18n (1.14.1)
+    i18n (1.14.5)
       concurrent-ruby (~> 1.0)
-    io-console (0.6.0)
-    irb (1.8.0)
-      rdoc (~> 6.5)
-      reline (>= 0.3.6)
-    minitest (5.16.3)
+    io-console (0.7.2)
+    irb (1.13.2)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    minitest (5.24.0)
     minitest-sprint (1.2.2)
       path_expander (~> 1.1)
-    mutex_m (0.1.2)
+    mutex_m (0.2.0)
     path_expander (1.1.1)
-    psych (5.1.0)
+    psych (5.1.2)
       stringio
-    rake (13.0.6)
-    rdoc (6.5.0)
+    rake (13.2.1)
+    rdoc (6.7.0)
       psych (>= 4.0.0)
-    reline (0.3.8)
+    reline (0.5.9)
       io-console (~> 0.5)
-    ruby2_keywords (0.0.5)
-    sqlite3 (1.6.4-arm64-darwin)
-    sqlite3 (1.6.4-x86_64-linux)
-    stringio (3.0.8)
-    timeout (0.4.0)
+    sqlite3 (1.7.3-arm64-darwin)
+    sqlite3 (1.7.3-x86_64-linux)
+    stringio (3.1.1)
+    timeout (0.4.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
 
 PLATFORMS
-  arm64-darwin-20
-  arm64-darwin-22
+  arm64-darwin
   x86_64-linux
 
 DEPENDENCIES
@@ -76,7 +73,7 @@ DEPENDENCIES
   minitest (~> 5.0)
   minitest-sprint
   rake (~> 13.0)
-  sqlite3
+  sqlite3 (~> 1.4)
 
 BUNDLED WITH
-   2.4.19
+   2.5.14

data/README.md

@@ -1,8 +1,80 @@
 # ActiveJob::Performs
 
-`ActiveJob::Performs` adds the `performs` macro to set up jobs by convention.
+`ActiveJob::Performs` adds a `performs` class method to make the model + job loop vastly more conventional. You use it like this:
 
-## Usage with `include GlobalID::Identification` objects
+```ruby
+class Post < ApplicationRecord
+  performs :publish
+  # Or `performs def publish`!
+
+  def publish
+    # Some logic to publish a post
+  end
+end
+```
+
+Then we build a job for the instance method and define a `post.publish_later` instance method, and more:
+
+```ruby
+class Post < ApplicationRecord
+  class Job < ApplicationJob; end # We build a general Job class to share configuration between method jobs.
+
+  # Individual method jobs inherit from the `Post::Job` defined above.
+  class PublishJob < Job
+    # We generate the required `perform` method passing in the `post` and calling `publish` on it.
+    def perform(post, *, **) = post.publish(*, **)
+  end
+
+  # On Rails 7.1, where `ActiveJob.perform_all_later` exists, we also generate
+  # a bulk method to enqueue many jobs at once. So you can do this:
+  #
+  #   Post.unpublished.in_batches.each(&:publish_later_bulk)
+  def self.publish_later_bulk
+    ActiveJob.perform_all_later all.map { PublishJob.new(_1) }
+  end
+
+  # We generate `publish_later` to wrap the job execution forwarding arguments and options.
+  def publish_later(*, **) = PublishJob.perform_later(self, *, **)
+
+  def publish
+    # Some logic to publish a post.
+  end
+end
+```
+
+## Benefits
+
+1. Conventional Jobs: they'll now mostly call instance methods like `publish_later` -> `publish`.
+1. Follows Rails' internal conventions: this borrows from `ActionMailbox::InboundEmail#process_later` calling `process` and `ActionMailer::Base#deliver_later` calling `deliver`.
+1. Clarity & less guess work: the `_later` methods standardize how you call jobs throughout your app, so you can instantly tell what's happening.
+1. Less tedium: getting an instance method run in the background is just now a `performs` call with some potential configuration.
+1. Fewer files to manage: you don't have to dig up something in `app/jobs` just to learn almost nothing from the boilerplate in there.
+1. Remaining jobs stand out: `app/jobs` is way lighter, so any jobs in there that don't fit the `performs` pattern now stand out way more.
+1. More consolidated logic: sometimes Job classes house model-level logic, but now it's all the way out in `app/jobs` instead of `app/models`, huh?
+
+> [!TIP]
+> On that last point, `performs` does put more logic back within your Active Records, so if you need further encapsulation to prevent them growing too large, consider checking out [active_record-associated_object](https://github.com/kaspth/active_record-associated_object).
+
+### Praise from people
+
+Here's what [@claudiob](https://github.com/claudiob) had to say after using `ActiveJob::Performs`:
+
+> I’ve been using active_job-performs for the last month and I love it love it love it!!
+>
+> Your thought process behind it is so thorough. I have a bunch of jobs now attached to models and my app/jobs folder… is empty!!
+>
+> This saves me a lot of mental hoops, I don’t have to switch between files anymore, everything is self-contained. Thank you!!!
+
+From [@andycroll](https://github.com/andycroll) in a [writeup](https://andycroll.com/ruby/launching-usingrails) about launching [UsingRails](https://usingrails.com):
+
+> I’ve also adopted a couple of gems—with exceptional Rails-level taste and author pedigree—that I hadn’t used in anger before, including `active_job-performs` from Kasper […]. Would recommend both.
+
+And [@nshki](https://github.com/nshki) after trying it:
+
+> Spent some time playing with [@kaspth](https://github.com/kaspth)'s [`ActiveRecord::AssociatedObject`](https://github.com/kaspth/active_record-associated_object) and `ActiveJob::Performs` and wow! The conventions these gems put in place help simplify a codebase drastically. I particularly love `ActiveJob::Performs`—it helped me refactor out all `ApplicationJob` classes I had and keep important context in the right domain model.
+
+## Usage
+### with `ActiveRecord::Base` & other `GlobalID::Identification` objects
 
 `ActiveJob::Performs` works with any object that has `include GlobalID::Identification` and responds to that interface.
 
@@ -14,7 +86,7 @@ class Post < ActiveRecord::Base
 
   # `performs` builds a `Post::PublishJob` and routes configs over to it.
   performs :publish, queue_as: :important, discard_on: SomeError do
-    retry_on TimeoutError, wait: :exponentially_longer
+    retry_on TimeoutError, wait: :polynomially_longer
   end
 
   def publish
@@ -34,7 +106,7 @@ class Post < ActiveRecord::Base
   class PublishJob < Job
     queue_as :important
     discard_on SomeError
-    retry_on TimeoutError, wait: :exponentially_longer
+    retry_on TimeoutError, wait: :polynomially_longer
 
     # We generate `perform` passing in the `post` and calling `publish` on it.
     def perform(post, *arguments, **options)
@@ -46,6 +118,10 @@ class Post < ActiveRecord::Base
   # a bulk method to enqueue many jobs at once. So you can do this:
   #
   #   Post.unpublished.in_batches.each(&:publish_later_bulk)
+  #
+  # Or pass in a subset of posts as an argument:
+  #
+  #   Post.publish_later_bulk Post.unpublished
   def self.publish_later_bulk
     ActiveJob.perform_all_later all.map { PublishJob.new(_1) }
   end
@@ -61,7 +137,7 @@ class Post < ActiveRecord::Base
 end
 ```
 
-We generate the `Post::Job` class above to share configuration between method level jobs. E.g. if you had a retract method that was setup very similar, you could do:
+We generate the `Post::Job` class above to share configuration between method level jobs. E.g. if you had a `retract` method that was setup very similar, you could do:
 
 ```ruby
 class Post < ActiveRecord::Base
@@ -99,6 +175,38 @@ class Post < ActiveRecord::Base
 end
 ```
 
+#### Establishing patterns across your app
+
+If there's an Active Record method that you'd like any model to be able to run from a background job, you can set them up in your `ApplicationRecord`:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+
+  # We're passing specific queues for monitoring, but you may not need or want them.
+  performs :touch,   queue_as: "active_record.touch"
+  performs :update,  queue_as: "active_record.update"
+  performs :destroy, queue_as: "active_record.destroy"
+end
+```
+
+Then a model could now run things like:
+
+```ruby
+record.touch_later
+record.touch_later :reminded_at, time: 5.minutes.from_now # Pass supported arguments to `touch`
+
+record.update_later reminded_at: 1.year.ago
+
+# Particularly handy to use on a record with many `dependent: :destroy` associations.
+# Plus if anything fails, the transaction will rollback and the job fails, so you can retry it later!
+record.destroy_later
+```
+
+You may not want this for `touch` and `update`, and maybe you'd rather architect your system in such a way that they don't have so many side-effects, but having the option can be handy!
+
+Also, I haven't tested all the Active Record methods, so please file an issue if you encounter any.
+
 #### Method suffixes
 
 `ActiveJob::Performs` supports Ruby's stylistic method suffixes, i.e. ? and ! respectively.
@@ -137,9 +245,22 @@ Additionally, in case the job is meant to be internal to the object, `performs :
 
 E.g. `private performs :some_method` will generate a private `some_method_later` method.
 
-### Usage with ActiveRecord::AssociatedObject
+#### Overriding the generated instance `_later` method
 
-The [`ActiveRecord::AssociatedObject`](https://github.com/kaspth/active_record-associated_object) gem also implements `GlobalID::Identification`, so you can do this too:
+The instance level `_later` methods, like `publish_later` above, are generated into an included module. So in case you have a condition where you'd like to prevent the enqueue, you can override the method and call `super`:
+
+```ruby
+class Post < ApplicationRecord
+  performs def publish
+    # …
+  end
+  def publish_later = some_condition? && super
+end
+```
+
+### Usage with `ActiveRecord::AssociatedObject`
+
+The [`ActiveRecord::AssociatedObject`](https://github.com/kaspth/active_record-associated_object) gem also implements `GlobalID::Identification`, so you use `performs` exactly like you would on Active Records:
 
 ```ruby
 class Post::Publisher < ActiveRecord::AssociatedObject
@@ -159,6 +280,11 @@ class Post::Publisher < ActiveRecord::AssociatedObject
 end
 ```
 
+> [!NOTE]
+> There's one difference with Active Record: you must pass in a set to `_later_bulk` methods. Like so:
+>
+> `Post::Publisher.publish_later_bulk Post::Publisher.first(10)`
+
 ### Passing `wait` to `performs`
 
 If there's a job you want to defer, `performs` can set it for each invocation:

data/lib/active_job/performs/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveJob
   module Performs
-    VERSION = "0.3.0"
+    VERSION = "0.3.2"
   end
 end

data/lib/active_job/performs.rb

@@ -46,15 +46,15 @@ module ActiveJob::Performs
         end
       RUBY
 
-      if ActiveJob.respond_to?(:perform_all_later) && respond_to?(:all)
+      if ActiveJob.respond_to?(:perform_all_later)
         class_eval <<~RUBY, __FILE__, __LINE__ + 1
-          def self.#{method}_later_bulk#{suffix}
-            ActiveJob.perform_all_later all.map { #{job}.scoped_by_wait(_1).new(_1) }
+          def self.#{method}_later_bulk#{suffix}(set#{" = all" if respond_to?(:all)})
+            ActiveJob.perform_all_later set.map { #{job}.scoped_by_wait(_1).new(_1) }
           end
         RUBY
       end
 
-      class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      performs_later_methods.class_eval <<~RUBY, __FILE__, __LINE__ + 1
         def #{method}_later#{suffix}(*arguments, **options)
           #{job}.scoped_by_wait(self).perform_later(self, *arguments, **options)
         end
@@ -73,6 +73,10 @@ module ActiveJob::Performs
       configs.each { job_class.public_send(_1, _2) }
       job_class.class_exec(&block) if block_given?
     end
+
+    def performs_later_methods
+      @performs_later_methods ||= Module.new.tap { include _1 }
+    end
 end
 
 ActiveSupport.on_load(:active_record) { extend ActiveJob::Performs }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_job-performs
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Kasper Timm Hansen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-04 00:00:00.000000000 Z
+date: 2024-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -62,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.18
 signing_key:
 specification_version: 4
 summary: ActiveJob::Performs adds the `performs` macro to set up jobs by convention.