active_job-performs 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4395366ab43af9510f569bcc141c9404a15fd2d6da529029eedc970c7a8f886
-  data.tar.gz: 9e239bf9a60e4e2785ae4b104f2cfd01e9b832729202f78ad9443c82046a7be6
+  metadata.gz: 360213ab324cae80fefcf276ecb9803ed8e4ec62166dc9eded626b67f8329b97
+  data.tar.gz: 92fa0c284711569f812da53e7acca9cbe15cea03aec0ccb9c2512465a7b93f39
 SHA512:
-  metadata.gz: 678c75e3a24b9faa407b01a063c15fadefc23747489b9e55db52641298385f2632b91268ae20ef9bf4964562e36ed5b6df99d46b1384605fb0ee694e29c0ae3d
-  data.tar.gz: 22231da5fc1856e480d00329e5a0cbf2482840d48eb2b2ea716751cbcc0d413d65169252aa8f3cc021b6f474e80f2a98912ce63bc1916ad2d2c1b29a3c7d273a
+  metadata.gz: 16fd7671e6eaeba29bac333597170661ca5333c3e14e3142ba910579316641dc2e2ba31f3fdd49508e5e0263a3fc67b34032e4ef61bb1b1a8dc3679a6a9ec26b
+  data.tar.gz: 353e3cf1bc646e32883352a2f4ebb80121987e415872ce9d0e32256fcbed7f559e66576a1ee15b71e2fec3930d54f362a5b8905cd502cac7daf4df7b618191e3

data/Gemfile.lock

@@ -1,22 +1,22 @@
 PATH
   remote: .
   specs:
-    active_job-performs (0.3.1)
+    active_job-performs (0.3.3)
       activejob (>= 6.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activejob (7.1.3.3)
-      activesupport (= 7.1.3.3)
+    activejob (7.1.3.4)
+      activesupport (= 7.1.3.4)
       globalid (>= 0.3.6)
-    activemodel (7.1.3.3)
-      activesupport (= 7.1.3.3)
-    activerecord (7.1.3.3)
-      activemodel (= 7.1.3.3)
-      activesupport (= 7.1.3.3)
+    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.3.3)
+    activesupport (7.1.3.4)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
@@ -28,7 +28,7 @@ GEM
       tzinfo (~> 2.0)
     base64 (0.2.0)
     bigdecimal (3.1.8)
-    concurrent-ruby (1.2.3)
+    concurrent-ruby (1.3.3)
     connection_pool (2.4.1)
     debug (1.9.2)
       irb (~> 1.10)
@@ -39,10 +39,10 @@ GEM
     i18n (1.14.5)
       concurrent-ruby (~> 1.0)
     io-console (0.7.2)
-    irb (1.13.1)
+    irb (1.13.2)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    minitest (5.23.1)
+    minitest (5.24.0)
     minitest-sprint (1.2.2)
       path_expander (~> 1.1)
     mutex_m (0.2.0)
@@ -52,11 +52,11 @@ GEM
     rake (13.2.1)
     rdoc (6.7.0)
       psych (>= 4.0.0)
-    reline (0.5.7)
+    reline (0.5.9)
       io-console (~> 0.5)
     sqlite3 (1.7.3-arm64-darwin)
     sqlite3 (1.7.3-x86_64-linux)
-    stringio (3.1.0)
+    stringio (3.1.1)
     timeout (0.4.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
@@ -76,4 +76,4 @@ DEPENDENCIES
   sqlite3 (~> 1.4)
 
 BUNDLED WITH
-   2.5.4
+   2.5.14

data/README.md

@@ -1,8 +1,85 @@
 # 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 `ActiveRecord::Base` & other `GlobalID::Identification` objects
+```ruby
+class Post < ApplicationRecord
+  performs :publish
+  # Or `performs def publish`!
+
+  def publish
+    # Some logic to publish a post
+  end
+end
+```
+
+Here's what `performs` generates under the hood:
+
+```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(set = all)
+    ActiveJob.perform_all_later set.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).
+
+### Used in production & praise from people
+
+The https://www.rubyevents.org team uses `ActiveJob::Performs` quite a bit:
+
+- [See `performs` calls in RubyEvents](https://github.com/search?q=repo%3Arubyevents%2Frubyevents+performs+language%3ARuby&type=code&l=Ruby)
+
+
+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.
 
@@ -13,7 +90,7 @@ class Post < ActiveRecord::Base
   extend ActiveJob::Performs # We technically auto-extend ActiveRecord::Base, but other object hierarchies need this.
 
   # `performs` builds a `Post::PublishJob` and routes configs over to it.
-  performs :publish, queue_as: :important, discard_on: SomeError do
+  performs :publish, queue_adapter: :sidekiq, queue_as: :important, discard_on: SomeError do
     retry_on TimeoutError, wait: :polynomially_longer
   end
 
@@ -32,6 +109,7 @@ class Post < ActiveRecord::Base
 
   # Individual method jobs inherit from the `Post::Job` defined above.
   class PublishJob < Job
+    self.queue_adapter = :sidekiq
     queue_as :important
     discard_on SomeError
     retry_on TimeoutError, wait: :polynomially_longer
@@ -46,8 +124,12 @@ 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)
-  def self.publish_later_bulk
-    ActiveJob.perform_all_later all.map { PublishJob.new(_1) }
+  #
+  # Or pass in a subset of posts as an argument:
+  #
+  #   Post.publish_later_bulk Post.unpublished
+  def self.publish_later_bulk(set = all)
+    ActiveJob.perform_all_later set.map { PublishJob.new(_1) }
   end
 
   # We generate `publish_later` to wrap the job execution.
@@ -61,7 +143,10 @@ 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:
+> [!NOTE]
+> We prefer & call `{name}=` setter methods, but fall back to getters. That's how we support `self.queue_adapter=`, but also `queue_as` which is not configured via `queue_as=`.
+
+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
@@ -184,7 +269,7 @@ end
 
 ### Usage with `ActiveRecord::AssociatedObject`
 
-The [`ActiveRecord::AssociatedObject`](https://github.com/kaspth/active_record-associated_object) gem also implements `GlobalID::Identification`, so you can do this too:
+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
@@ -204,6 +289,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:
@@ -230,12 +320,6 @@ class Post < ActiveRecord::Base
 end
 ```
 
-### Praise from people
-
-Here's what [@nshki](https://github.com/nshki) found when they tried `ActiveJob::Performs`:
-
-> 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.
-
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/lib/active_job/performs/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveJob
   module Performs
-    VERSION = "0.3.1"
+    VERSION = "0.3.3"
   end
 end

data/lib/active_job/performs.rb

@@ -5,18 +5,14 @@ require_relative "performs/version"
 module ActiveJob; end
 module ActiveJob::Performs
   module Waiting
-    def Proc(value)
-      value.respond_to?(:call) ? value : proc { value }
-    end unless Kernel.respond_to?(:Proc) # Optimistically assume Ruby gets this and it'll work fine.
+    attr_reader :wait, :wait_until
 
-    def wait(value = nil)
-      @wait = Proc(value) if value
-      @wait
+    def wait=(value)
+      @wait = value.respond_to?(:call) ? value : proc { value }
     end
 
-    def wait_until(value = nil)
-      @wait_until = Proc(value) if value
-      @wait_until
+    def wait_until=(value)
+      @wait_until = value.respond_to?(:call) ? value : proc { value }
     end
 
     def scoped_by_wait(record)
@@ -46,10 +42,10 @@ 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
@@ -69,9 +65,13 @@ module ActiveJob::Performs
       name.safe_constantize || const_set(name, Class.new(yield))
     end
 
-    def apply_performs_to(job_class, **configs, &block)
-      configs.each { job_class.public_send(_1, _2) }
-      job_class.class_exec(&block) if block_given?
+    def apply_performs_to(job, **configs, &block)
+      job.class_exec(&block) if block_given?
+
+      configs.each do |name, value|
+        name = "#{name}=".then.find { job.respond_to? _1 } || name
+        job.public_send name, value
+      end
     end
 
     def performs_later_methods

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_job-performs
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - Kasper Timm Hansen
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -24,7 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
-description:
 email:
 - hey@kaspth.com
 executables: []
@@ -47,7 +45,6 @@ metadata:
   homepage_uri: https://github.com/kaspth/active_job-performs
   source_code_uri: https://github.com/kaspth/active_job-performs
   changelog_uri: https://github.com/kaspth/active_job-performs/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -62,8 +59,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.10
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: ActiveJob::Performs adds the `performs` macro to set up jobs by convention.
 test_files: []