performs 0.3.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58f4522465e497385cd7d88c3b8bf68eb83505addcbfc23024b4af4c7d21e855
+  data.tar.gz: d446c5a77683f7c6e5c757fcdfabecd80a0556f46fd5fc247107a38077f1e6fd
+SHA512:
+  metadata.gz: a1af1460078f19f76d980701f9ab0f3cf09c567e291e54399f8ed7b6580373e2de8d29db08b42d4aeaabf0ee5ca135d0670538f95b508b6affa50c4e3803d6b6
+  data.tar.gz: f29b84a433c8b9ce582353af9b79f7b624f7686b93c210b30065ad10fd92f7412df1c355482f44ee8fc07b1a145db8075b5ce0069b08d9570954067db9ef93d8

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+## [Unreleased]
+
+## [0.3.4] - 2025-11-28
+
+- Breaking change. `performs` return only the later method, not an array.
+
+## [0.2.0] - 2023-01-12
+
+- Supports `private performs :some_method`
+
+  Which then generates a private `some_method_later` method.
+
+  This was already technically supported but a test was added to declare it expected.
+
+- Support method suffixes ! and ?
+
+  You can call `performs :some_method!` and have `some_method_later!` generated. Same for `?`.
+
+- Support `performs` on private methods
+
+  Method jobs will now call methods with `send`, in case you only want to expose the generated later method to the outside world.
+
+  ```ruby
+  class Post < ActiveRecord::Base
+    performs :something_low_level
+
+    private
+
+    # We don't want other objects to call this, they should always use the generated later method.
+    def something_low_level
+      # …
+    end
+  end
+  ```
+
+  Here, the generated `Post#something_low_level_later` is public and available but can still call into the immediate version of `something_low_level`.
+
+## [0.1.1] - 2022-09-27
+
+- Fixed: extend ActiveRecord::Base with ActiveJob::Performs as the README says.
+
+## [0.1.0] - 2022-09-27
+
+- Initial release

data/Gemfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in active_job-performs.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"
+gem "minitest-sprint"
+
+gem "debug"
+
+# Fetch latest Active Job to test `ActiveJob.perform_all_later`
+gem "activejob",    ">= 7.1"
+gem "activerecord", ">= 7.1"
+
+gem "sqlite3", "~> 1.4"

data/Gemfile.lock

@@ -0,0 +1,79 @@
+PATH
+  remote: .
+  specs:
+    active_job-performs (0.3.3)
+      activejob (>= 6.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activejob (7.1.3.4)
+      activesupport (= 7.1.3.4)
+      globalid (>= 0.3.6)
+    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.4)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      mutex_m
+      tzinfo (~> 2.0)
+    base64 (0.2.0)
+    bigdecimal (3.1.8)
+    concurrent-ruby (1.3.3)
+    connection_pool (2.4.1)
+    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.5)
+      concurrent-ruby (~> 1.0)
+    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.2.0)
+    path_expander (1.1.1)
+    psych (5.1.2)
+      stringio
+    rake (13.2.1)
+    rdoc (6.7.0)
+      psych (>= 4.0.0)
+    reline (0.5.9)
+      io-console (~> 0.5)
+    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
+  x86_64-linux
+
+DEPENDENCIES
+  active_job-performs!
+  activejob (>= 7.1)
+  activerecord (>= 7.1)
+  debug
+  minitest (~> 5.0)
+  minitest-sprint
+  rake (~> 13.0)
+  sqlite3 (~> 1.4)
+
+BUNDLED WITH
+   2.5.14

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Kasper Timm Hansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,345 @@
+# ActiveJob::Performs
+
+`ActiveJob::Performs` adds a `performs` class method to make the model + job loop vastly more conventional. You use it like this:
+
+```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.
+
+`ActiveRecord::Base` implements this, so here's how that looks:
+
+```ruby
+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_adapter: :sidekiq, queue_as: :important, discard_on: SomeError do
+    retry_on TimeoutError, wait: :polynomially_longer
+  end
+
+  def publish
+    …
+  end
+end
+```
+
+Here's what `performs` generates under the hood:
+
+```ruby
+class Post < ActiveRecord::Base
+  # We setup a general Job class that's shared between method jobs.
+  class Job < ApplicationJob; end
+
+  # 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
+
+    # We generate `perform` passing in the `post` and calling `publish` on it.
+    def perform(post, *arguments, **options)
+      post.publish(*arguments, **options)
+    end
+  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)
+  #
+  # 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.
+  def publish_later(*arguments, **options)
+    PublishJob.perform_later(self, *arguments, **options)
+  end
+
+  def publish
+    …
+  end
+end
+```
+
+> [!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
+  performs queue_as: :important
+  performs :publish
+  performs :retract
+
+  def publish
+    …
+  end
+
+  def retract(reason:)
+    …
+  end
+end
+```
+
+Which would then become:
+
+```ruby
+class Post < ActiveRecord::Base
+  class Job < ApplicationJob
+    queue_as :important
+  end
+
+  class PublishJob < Job
+    …
+  end
+
+  class RetractJob < Job
+    …
+  end
+
+  …
+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.
+
+```ruby
+class Post < ActiveRecord::Base
+  performs :publish! # Generates `publish_later!` which calls `publish!`.
+  performs :retract? # Generates `retract_later?` which calls `retract?`.
+
+  def publish!
+    …
+  end
+
+  def retract?
+    …
+  end
+end
+```
+
+#### Private methods
+
+`ActiveJob::Performs` also works with private methods in case you only want to expose the generated `_later` method.
+
+```ruby
+class Post < ActiveRecord::Base
+  performs :publish # Generates the public `publish_later` instance method.
+
+  # Private implementation, only call `publish_later` please!
+  private def publish
+    …
+  end
+end
+```
+
+Additionally, in case the job is meant to be internal to the object, `performs :some_method` returns `:some_method_later` which you can pass to `private`.
+
+E.g. `private performs :some_method` will generate a private `some_method_later` method.
+
+#### Overriding the generated instance `_later` method
+
+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
+  extend ActiveJob::Performs # We technically auto-extend ActiveRecord::AssociatedObject, but other object hierarchies need this.
+
+  performs queue_as: :important
+  performs :publish
+  performs :retract
+
+  def publish
+    …
+  end
+
+  def retract(reason:)
+    …
+  end
+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:
+
+```ruby
+class Post < ActiveRecord::Base
+  mattr_reader :config, default: Rails.application.config_for(:posts)
+
+  performs :social_media_boost, wait: config.social_media_boost_after
+  performs :social_media_boost, wait: 5.minutes # Alternatively, this works too.
+
+  # Additionally, a block can be passed to have access to the `post`:
+  performs :social_media_boost, wait: -> post { post.social_media_boost_grace_period }
+end
+```
+
+Now, `social_media_boost_later` can be called immediately, but automatically run after the grace period.
+
+`wait_until` is also supported:
+
+```ruby
+class Post < ActiveRecord::Base
+  performs :publish, wait_until: -> post { Date.tomorrow.noon if post.graceful? }
+end
+```
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add active_job-performs
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install active_job-performs
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kaspth/active_job-performs.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"

data/lib/active_job/performs/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Performs
+    VERSION = "0.3.4"
+  end
+end

data/lib/active_job/performs.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "performs/version"
+
+module ActiveJob; end
+module ActiveJob::Performs
+  module Waiting
+    attr_reader :wait, :wait_until
+
+    def wait=(value)
+      @wait = value.respond_to?(:call) ? value : proc { value }
+    end
+
+    def wait_until=(value)
+      @wait_until = value.respond_to?(:call) ? value : proc { value }
+    end
+
+    def scoped_by_wait(record)
+      if waits = { wait: wait&.call(record), wait_until: wait_until&.call(record) }.compact and waits.any?
+        set(waits)
+      else
+        self
+      end
+    end
+  end
+
+  def performs(method = nil, **configs, &block)
+    @job ||= safe_define("Job") { ApplicationJob }.tap { _1.extend Waiting }
+
+    if method.nil?
+      apply_performs_to(@job, **configs, &block)
+    else
+      method = method.to_s.dup
+      suffix = $1 if method.gsub!(/([!?])$/, "")
+
+      job = safe_define("#{method}_job".classify) { @job }
+      apply_performs_to(job, **configs, &block)
+
+      job.class_eval <<~RUBY, __FILE__, __LINE__ + 1 unless job.instance_method(:perform).owner == job
+        def perform(object, *arguments, **options)
+          object.send(:#{method}#{suffix}, *arguments, **options)
+        end
+      RUBY
+
+      if ActiveJob.respond_to?(:perform_all_later)
+        class_eval <<~RUBY, __FILE__, __LINE__ + 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
+
+      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
+      RUBY
+
+      :"#{method}_later#{suffix}"
+    end
+  end
+
+  private
+    def safe_define(name)
+      name.safe_constantize || const_set(name, Class.new(yield))
+    end
+
+    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
+      @performs_later_methods ||= Module.new.tap { include _1 }
+    end
+end
+
+ActiveSupport.on_load(:active_record) { extend ActiveJob::Performs }

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: performs
+version: !ruby/object:Gem::Version
+  version: 0.3.4
+platform: ruby
+authors:
+- Kasper Timm Hansen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+email:
+- hey@kaspth.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/active_job/performs.rb
+- lib/active_job/performs/version.rb
+homepage: https://github.com/claudiob/active_job-performs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/claudiob/active_job-performs
+  source_code_uri: https://github.com/claudiob/active_job-performs
+  changelog_uri: https://github.com/claudiob/active_job-performs/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: ActiveJob::Performs adds the `performs` macro to set up jobs by convention.
+test_files: []