activejob-later 2026.10.29.162056

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 72ac0154c0607d1f6dd6f7cf36e0398062381ab252deab36ee96cfe06c9a3d6d
+  data.tar.gz: 42bf415d23c136a6490237a84e6cbb4987b8531fa8ee251715ce724787626467
+SHA512:
+  metadata.gz: 37c9ebf8a59917d4e780c1b6d2b30f33aa42a69d9557c4cf268876ce53bdd83ff67c35897e7c807407588281d17edd53762c98596bb105320c0fb25e561fe724
+  data.tar.gz: a8433f560729ebe2514ffc0c0a1325c1fb5b261c85f2ea60e6254407edd91fbdb6df7002fbd3f7c3cdbb4843e1f17420df4da707451b59bee80a6760efb18d93

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluence
+
+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,88 @@
+# activejob-later
+
+Run any method of any class, module or instance in the background through
+Active Job — no dedicated job class needed.
+
+```ruby
+Report.perform_later.compute("2026-06")
+Report.perform_later(queue: :low, wait: 10.minutes).compute("2026-06")
+invoice.perform_later.generate_pdf          # instances via GlobalID
+Maintenance.perform_later.purge             # modules too
+```
+
+The direct call (`Report.compute(...)`) stays synchronous and untouched.
+Options are passed straight to `ActiveJob::Base.set` (`queue:`, `wait:`,
+`wait_until:`, `priority:`).
+
+## Per-class and per-method job configuration
+
+`perform_later` calls go through a generic job by default. Declare a dedicated
+job to use the full Active Job class DSL — `retry_on`, `discard_on`,
+`rescue_from`, `queue_as`, callbacks, and adapter extensions such as
+`limits_concurrency` (Solid Queue):
+
+```ruby
+class Report
+  perform_later_job do                      # applies to the whole class
+    queue_as :reports
+    retry_on Timeout::Error, attempts: 5
+  end
+
+  perform_later_job :compute do             # applies to one method only
+    limits_concurrency to: 1, key: ->(target, *) { target }
+    discard_on ActiveRecord::RecordNotFound
+  end
+
+  def self.compute(month)
+    # ...
+  end
+end
+```
+
+Job resolution order: method job (`Report::ComputePerformLaterJob`) → class
+job (`Report::PerformLaterJob`) → generic (`ActiveJob::PerformLater::Job`).
+Method jobs inherit the class job, so rules cumulate.
+Declare the class-level `perform_later_job` before the per-method ones — a method job only inherits a class job that already exists at that point.
+
+When a class method and an instance method share a name, scope the job:
+
+```ruby
+perform_later_job :sync, on: :class do ... end      # Report.perform_later.sync
+perform_later_job :sync, on: :instance do ... end   # report.perform_later.sync
+```
+
+## Building a job without enqueuing it
+
+`job_later` takes the same options and returns the job `perform_later` would
+enqueue, without enqueuing it — for APIs that take a job instance, such as
+Solid Queue batch callbacks:
+
+```ruby
+SolidQueue::Batch.enqueue(on_finish: import.job_later.finalize!) do
+  import.lines.each { |line| line.perform_later.process! }
+end
+```
+
+Job resolution and the errors below are the same as for `perform_later`.
+
+## Configuration
+
+```ruby
+ActiveJob::PerformLater.base_job = "ApplicationJob"  # default: "ActiveJob::Base"
+```
+
+Parent class of the jobs generated by `perform_later_job`.
+
+## Error behavior
+
+- Unknown or private method → `NoMethodError` at enqueue time, not in the worker.
+- Non-serializable instance (no GlobalID, no custom serializer) →
+  `ActiveJob::SerializationError` at enqueue time.
+- Target class removed before the job runs → `NameError` at perform.
+- The proxy forwards every method call, so reflective calls like `.class` on the proxy itself enqueue real jobs; `inspect` is the exception (safe to display in a console).
+- String instances are rejected as targets (`ArgumentError`) — a String would be ambiguous with a class reference in the job payload.
+- Passing a block to a proxied call raises `ArgumentError` — blocks cannot be serialized.
+
+## Requirements
+
+Ruby >= 3.3, activejob >= 7.1.

data/lib/active_job/perform_later/job.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module PerformLater
+    # Shared perform implementation included in every job the gem
+    # resolves or generates.
+    #
+    # @api private
+    module JobBehavior
+      # Replays the captured call: resolves a class or module reference
+      # back to its constant, then public_sends the method.
+      #
+      # @api private
+      # @param target [Object, String] receiver, or class/module name
+      # @param method_name [String] method to invoke
+      # @param args [Array] positional arguments
+      # @param kwargs [Hash] keyword arguments
+      # @return [Object] whatever the replayed method returns
+      def perform(target, method_name, args, kwargs)
+        target = ::Object.const_get(target) if target.is_a?(String)
+        target.public_send(method_name, *args, **kwargs)
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_job) do
+  # Generic fallback job used when no dedicated job constant matches the
+  # enqueued method. Defined in the load hook so {PerformLater.base_job}
+  # is only touched once Active Job is actually loaded.
+  class ActiveJob::PerformLater::Job < ActiveJob::Base
+    include ActiveJob::PerformLater::JobBehavior
+  end
+end

data/lib/active_job/perform_later/macro.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module PerformLater
+    # `perform_later_job` class macro, mixed into Module.
+    module Macro
+      # Accepted values for the `on:` scope option.
+      #
+      # @api private
+      # @return [Array<Symbol, nil>] valid scopes
+      VALID_SCOPES = [nil, :class, :instance].freeze
+
+      # Defines a dedicated job class for `method_name` — or the
+      # class-wide `PerformLaterJob` fallback when no name is given —
+      # named after {PerformLater.job_const_name} and inheriting from the
+      # nearest `PerformLaterJob` or {PerformLater.base_job}.
+      #
+      # @api public
+      # @param method_name [Symbol, nil] method the job is dedicated to;
+      #   nil declares the class-wide fallback job
+      # @param on [Symbol, nil] restrict the job to `:class` or
+      #   `:instance` calls of `method_name`
+      # @yield optional block class_eval'ed inside the generated job
+      #   (`queue_as`, `retry_on`, ...)
+      # @return [Class] the generated job class
+      # @raise [ArgumentError] on an invalid scope, a scope without a
+      #   method name, or an already-defined job constant
+      # @example Dedicated job with options
+      #   class Report
+      #     perform_later_job :generate, on: :instance do
+      #       queue_as :reports
+      #     end
+      #   end
+      def perform_later_job(method_name = nil, on: nil, &block)
+        unless VALID_SCOPES.include?(on)
+          raise ArgumentError, "on: must be :class or :instance, got #{on.inspect}"
+        end
+        raise ArgumentError, "on: requires a method name" if on && method_name.nil?
+
+        const_name = PerformLater.job_const_name(method_name, on: on)
+        if const_defined?(const_name, false)
+          raise ArgumentError, "#{self}::#{const_name} is already defined"
+        end
+
+        parent =
+          if method_name
+            PerformLater.lookup_const(self, "PerformLaterJob") || PerformLater.resolved_base_job
+          else
+            PerformLater.resolved_base_job
+          end
+
+        job = const_set(const_name, Class.new(parent))
+        job.include(JobBehavior)
+        job.class_eval(&block) if block
+        job
+      end
+    end
+  end
+end

data/lib/active_job/perform_later/mixin.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module PerformLater
+    # `perform_later` entry point, mixed into Object.
+    module Mixin
+      # Returns a proxy that enqueues the next method call as an Active
+      # Job instead of invoking it.
+      #
+      # @api public
+      # @param options [Hash] Active Job set options (`:queue`, `:wait`,
+      #   `:wait_until`, `:priority`, ...)
+      # @return [Proxy] proxy enqueueing method calls on this receiver
+      # @example
+      #   Newsletter.perform_later(queue: :low).deliver_all
+      def perform_later(**options)
+        Proxy.new(self, options)
+      end
+
+      # Returns a proxy that builds the next method call as an Active Job
+      # without enqueuing it, resolved and checked like {#perform_later}.
+      #
+      # @api public
+      # @param options [Hash] Active Job set options (`:queue`, `:wait`,
+      #   `:wait_until`, `:priority`, ...)
+      # @return [Proxy] proxy building jobs for method calls on this receiver
+      # @example Hand a call to a Solid Queue batch callback
+      #   SolidQueue::Batch.enqueue(on_finish: import.job_later.finalize!) { ... }
+      def job_later(**options) = Proxy.new(self, options, enqueue: false)
+    end
+  end
+end

data/lib/active_job/perform_later/proxy.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module PerformLater
+    # Intermediate object returned by {Mixin#perform_later} and
+    # {Mixin#job_later}: captures the next method call and enqueues — or
+    # only builds — it instead of invoking it.
+    #
+    # @api private
+    class Proxy < BasicObject
+      # @api private
+      # @param target [Object] receiver the call will be replayed on
+      # @param options [Hash] Active Job set options
+      # @param enqueue [Boolean] false to build the job without enqueuing it
+      # @return [Proxy] a new proxy around target
+      def initialize(target, options, enqueue: true)
+        @target = target
+        @options = options
+        @enqueue = enqueue
+      end
+
+      # Enqueues — or only builds, for {Mixin#job_later} — `method_name`
+      # on the captured target through the job class resolved by
+      # {PerformLater.job_for}.
+      #
+      # @api private
+      # @return [ActiveJob::Base] the enqueued, or built, job instance
+      # @raise [NoMethodError] when the target does not respond to the
+      #   method
+      # @raise [ArgumentError] when a block is passed — blocks are not
+      #   serializable
+      def method_missing(method_name, *args, **kwargs, &block)
+        unless @target.respond_to?(method_name)
+          ::Kernel.raise ::NoMethodError,
+                         "undefined method '#{method_name}' for #{@target.inspect} (via perform_later)"
+        end
+
+        if block
+          ::Kernel.raise ::ArgumentError,
+                         "cannot enqueue '#{method_name}' with a block — blocks are not serializable"
+        end
+
+        job = PerformLater.job_for(@target, method_name)
+        arguments = [PerformLater.target_ref(@target), method_name.to_s, args, kwargs]
+        return job.new(*arguments).set(@options) unless @enqueue
+
+        job.set(**@options).perform_later(*arguments)
+      end
+
+      # Human-readable description of the proxy.
+      #
+      # @api private
+      # @return [String] the captured target and options
+      def inspect
+        "#<ActiveJob::PerformLater::Proxy target=#{@target.inspect} options=#{@options.inspect}>"
+      end
+    end
+  end
+end

data/lib/active_job/perform_later/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module PerformLater
+    # Semantic version of the gem, bumped by the release workflow.
+    #
+    # @api public
+    # @return [String] the current version
+    VERSION = '2026.10.29.162056'
+  end
+end

data/lib/active_job/perform_later.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "active_job/perform_later/version"
+require "active_job/perform_later/job"
+require "active_job/perform_later/proxy"
+require "active_job/perform_later/mixin"
+require "active_job/perform_later/macro"
+
+module ActiveJob
+  # Runs any method of any class or instance in the background, either
+  # through ad-hoc {Mixin#perform_later} proxies or through dedicated
+  # jobs declared with the {Macro#perform_later_job} macro.
+  #
+  # @example Enqueue a method call on a model
+  #   user.perform_later(wait: 5.minutes).send_welcome_email
+  module PerformLater
+    class << self
+      # Sets the job class every generated job inherits from.
+      #
+      # Accepts a Class, or a String resolved lazily so the constant can
+      # be defined after configuration runs (e.g. an autoloaded
+      # `ApplicationJob`).
+      #
+      # @api public
+      # @return [Class, String] the new base job
+      attr_writer :base_job
+
+      # The job class (or class name) generated jobs inherit from.
+      #
+      # @api public
+      # @return [Class, String] defaults to `"ActiveJob::Base"`
+      def base_job
+        @base_job ||= "ActiveJob::Base"
+      end
+
+      # Resolves {base_job} to a Class, constantizing it when configured
+      # as a String.
+      #
+      # @api private
+      # @return [Class] the job class generated jobs inherit from
+      def resolved_base_job
+        base_job.is_a?(String) ? Object.const_get(base_job) : base_job
+      end
+
+      # Converts a proxy target into an Active Job serializable reference.
+      #
+      # Classes and modules are passed by name; any other object is
+      # passed as-is and relies on GlobalID (or primitive) serialization.
+      #
+      # @api private
+      # @param target [Object] receiver captured by the proxy
+      # @return [Object] the reference given to `perform_later`
+      # @raise [ArgumentError] when target is a String or an anonymous
+      #   class or module
+      def target_ref(target)
+        if target.is_a?(String)
+          raise ArgumentError, "String targets are not supported by perform_later"
+        end
+        return target unless target.is_a?(Module)
+
+        target.name || raise(ArgumentError, "cannot perform_later on an anonymous class or module")
+      end
+
+      # Picks the job class used to enqueue `method_name` on `target`.
+      #
+      # Looks up, in order: the scope-prefixed constant
+      # (`Class…`/`Instance…`), the method-named constant, the class-wide
+      # `PerformLaterJob`, then falls back to the generic {Job}.
+      #
+      # @api private
+      # @param target [Object] receiver captured by the proxy
+      # @param method_name [Symbol] method being enqueued
+      # @return [Class] the Active Job class to enqueue with
+      def job_for(target, method_name)
+        klass = target.is_a?(Module) ? target : target.class
+        scope = target.is_a?(Module) ? :class : :instance
+
+        [job_const_name(method_name, on: scope),
+         job_const_name(method_name),
+         "PerformLaterJob"].each do |const_name|
+          job = lookup_const(klass, const_name)
+          return job if job
+        end
+
+        Job
+      end
+
+      # Builds the conventional job constant name for a method.
+      #
+      # @api private
+      # @param method_name [Symbol, String, nil] method the job wraps
+      # @param on [Symbol, nil] optional `:class` / `:instance` scope prefix
+      # @return [String] e.g. `"SyncPerformLaterJob"`,
+      #   `"ClassSyncPerformLaterJob"`
+      def job_const_name(method_name, on: nil)
+        return "PerformLaterJob" if method_name.nil?
+
+        prefix = on ? ActiveSupport::Inflector.camelize(on.to_s) : ""
+        base = ActiveSupport::Inflector.camelize(method_name.to_s.sub(/[?!=]\z/, ""))
+        "#{prefix}#{base}PerformLaterJob"
+      end
+
+      # Finds `const_name` defined directly on `mod` or one of its
+      # ancestors, skipping Object so a top-level constant does not leak
+      # into every class.
+      #
+      # @api private
+      # @param mod [Module] starting point of the ancestry lookup
+      # @param const_name [String] constant name to look up
+      # @return [Class, nil] the matching job class, or nil when undefined
+      def lookup_const(mod, const_name)
+        mod.ancestors.each do |ancestor|
+          next if ancestor == Object
+          return ancestor.const_get(const_name, false) if ancestor.const_defined?(const_name, false)
+        end
+        nil
+      end
+    end
+  end
+end
+
+Object.include ActiveJob::PerformLater::Mixin
+Module.include ActiveJob::PerformLater::Macro

data/lib/activejob-later.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "active_job/perform_later"

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: activejob-later
+version: !ruby/object:Gem::Version
+  version: 2026.10.29.162056
+platform: ruby
+authors:
+- Jonathan PHILIPPE
+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: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/active_job/perform_later.rb
+- lib/active_job/perform_later/job.rb
+- lib/active_job/perform_later/macro.rb
+- lib/active_job/perform_later/mixin.rb
+- lib/active_job/perform_later/proxy.rb
+- lib/active_job/perform_later/version.rb
+- lib/activejob-later.rb
+homepage: https://github.com/fluence-eu/activejob-later
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fluence-eu/activejob-later
+  source_code_uri: https://github.com/fluence-eu/activejob-later
+  changelog_uri: https://github.com/fluence-eu/activejob-later/blob/main/CHANGELOG.md
+  github_repo: https://github.com/fluence-eu/activejob-later
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Run any method of any class in the background via Active Job
+test_files: []