marj 3.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7afb73261695ca8eb0005d59b292ec659a9c10124a2b3984242e3f8e209fc897
-  data.tar.gz: 5f5fea852ab9a8e7eb9ca6fa59ed6cb4e0537651bf3edf6713ec0cad4a1c1ed0
+  metadata.gz: 8ea99cb466811e6f77fb6476e7e8ca02b7345c8d297ebdb1954b9109f772bfd9
+  data.tar.gz: 35a1ed99e2afe6934a5a7ea9b40375a93d5c79b9c46d304aac49457913794fba
 SHA512:
-  metadata.gz: 348506cb34c7956e4c17554223c81d47353905ebdfb684c965d4deeb2b3a47727b5cb971211e2f2c48e039c8c5c1d9a1b02a6e9647be247ca0d86472a357f1b0
-  data.tar.gz: 94069a23d1882ff62c5b630e5e50357c63f230f8fc4a86828d3e4d785402f6c325fb82fb2d398c5ec937a572018b8c4027f5569fb818dcbc1dd2258e1cc9ac54
+  metadata.gz: 0a1568a19c7faeedc80d0a17cf71c536a5dcb9b497645c87772213b5a20ca22b8ae250099826a75654d36260b5d34d77c896b81b28cc87e3ec1e4e181b5440bb
+  data.tar.gz: 701727d777c8f9c990bdca6d66f9cf3d76d41eddddd77f1dbcbb1c75cff5b75b7acce065cb5c83b01c23dff3a6878218b4b6f3c4528d0e307ae8bc8e192d91e9

data/README.md

@@ -4,7 +4,7 @@ A minimal database-backed ActiveJob queueing backend.
 
 ## Quick Links
 
-API docs: https://www.rubydoc.info/github/nicholasdower/marj <br>
+API docs: https://gemdocs.org/gems/marj/latest <br>
 RubyGems: https://rubygems.org/gems/marj <br>
 Changelog: https://github.com/nicholasdower/marj/releases <br>
 Issues: https://github.com/nicholasdower/marj/issues <br>
@@ -17,7 +17,7 @@ Development: https://github.com/nicholasdower/marj/blob/master/CONTRIBUTING.md
 - Failed jobs which should be retried are updated in the database.
 - Failed jobs which should not be retried are deleted from the database.
 - An interface is provided to retrieve, execute, discard and re-enqueue jobs.
-- An `ActiveRecord` model class is provided to query the database directly.
+- An `ActiveRecord` class is provided to query the database directly.
 
 ## Features Not Provided
 
@@ -39,7 +39,7 @@ bundle add activejob activerecord marj
 gem install activejob activerecord marj
 ```
 
-### 3. Create the jobs table
+### 3. Create the database table
 
 ```ruby
 class CreateJobs < ActiveRecord::Migration[7.1]
@@ -68,6 +68,9 @@ class CreateJobs < ActiveRecord::Migration[7.1]
 end
 ```
 
+Note that by default, Marj uses a table named `jobs`. To override the default
+table name, set `Marj.table_name` before loading `ActiveRecord`.
+
 ### 4. Configure the queue adapter
 
 ```ruby
@@ -78,34 +81,64 @@ ActiveJob::Base.queue_adapter = :marj                # Globally, without Rails
 SomeJob.queue_adapter = :marj                        # Single job
 ```
 
+## Example Usage
+
+```ruby
+# Enqueue and manually run a job:
+job = SomeJob.perform_later('foo')
+job.perform_now
+
+# Retrieve and execute a job
+Marj.due.next.perform_now
+
+# Run all due jobs (single DB query)
+Marj.due.perform_all
+
+# Run all due jobs (multiple DB queries)
+Marj.due.perform_all(batch_size: 1)
+
+# Run all due jobs in a specific queue:
+Marj.queue('foo').due.perform_all
+
+# Run jobs as they become due:
+loop do
+  Marj.due.perform_all rescue logger.error($!)
+ensure
+  sleep 5.seconds
+end
+```
+
 ## Jobs Interface
 
-`Marj::Jobs` provides a query interface (`Marj::JobsInterface`) which can be
-used to retrieve, execute and discard enqueued jobs. It returns, yields and
-accepts `ActiveJob` objects rather than `ActiveRecord` objects. Jobs are
-orderd by due date. To query the database directly, use `Marj::Record`.
+The `Marj` module provides methods for interacting with enqueued jobs. These
+methods accept, return and yield +ActiveJob+ objects rather than +ActiveRecord+
+objects. Returned jobs are orderd by due date. To query the database directly,
+use `Marj::Record`.
+
+Example usage:
 
 ```ruby
-Marj::Jobs.all         # Returns all enqueued jobs.
-Marj::Jobs.queue       # Returns jobs in the specified queue(s).
-Marj::Jobs.due         # Returns jobs which are due to be executed.
-Marj::Jobs.next        # Returns the next job(s) to be executed.
-Marj::Jobs.count       # Returns the number of enqueued jobs.
-Marj::Jobs.where       # Returns jobs matching the specified criteria.
-Marj::Jobs.perform_all # Executes all jobs.
-Marj::Jobs.discard_all # Discards all jobs.
-Marj::Jobs.discard     # Discards the specified job.
+Marj.all         # Returns all enqueued jobs.
+Marj.queue       # Returns jobs in the specified queue(s).
+Marj.due         # Returns jobs which are due to be executed.
+Marj.next        # Returns the next job(s) to be executed.
+Marj.count       # Returns the number of enqueued jobs.
+Marj.where       # Returns jobs matching the specified criteria.
+Marj.perform_all # Executes all jobs.
+Marj.discard_all # Discards all jobs.
+Marj.discard     # Discards the specified job.
 ```
 
-`all`, `queue`, `due` and `where` return a `Marj::Relation` which provides
-the same `Marj::JobsInterface`. This can be used to chain query methods like:
+Query methods can also be chained:
 
 ```ruby
-Marj::Jobs.due.where(job_class: SomeJob).next
+Marj.due.where(job_class: SomeJob).next # Returns the next SomeJob that is due
 ```
 
-Note that the `Marj::JobsInterface` can be added to any class or module. For
-example, to add it to all jobs classes:
+## Custom Jobs Interface
+
+The `Marj::JobsInterface` can be added to any class or module. For example, to
+add it to all jobs classes:
 
 ```ruby
 class ApplicationJob < ActiveJob::Base
@@ -125,40 +158,12 @@ ApplicationJob.due # Returns all jobs which are due to be executed.
 SomeJob.due        # Returns SomeJobs which are due to be executed.
 ```
 
-## Example Usage
-
-```ruby
-# Enqueue and manually run a job:
-job = SomeJob.perform_later('foo')
-job.perform_now
-
-# Retrieve and execute a job
-Marj::Jobs.due.next.perform_now
-
-# Run all due jobs (single DB query)
-Marj::Jobs.due.perform_all
-
-# Run all due jobs (multiple DB queries)
-Marj::Jobs.due.perform_all(batch_size: 1)
-
-# Run all due jobs in a specific queue:
-Marj::Jobs.queue('foo').due.perform_all
-
-# Run all jobs indefinitely, as they become due:
-loop do
-  Marj::Jobs.due.perform_all rescue logger.error($!)
-ensure
-  sleep 5.seconds
-end
-```
-
-## Customization
+## Multiple Tables
 
-It is possible to create a custom record class and jobs interface. This enables,
-for instance, writing jobs to multiple databases/tables within a single
-application.
+It is possible to create a custom record class in order to, for instance,
+write jobs to multiple databases/tables within a single application.
 
-```
+```ruby
 class CreateMyJobs < ActiveRecord::Migration[7.1]
   def self.up
     create_table :my_jobs, id: :string, primary_key: :job_id do |table|
@@ -184,28 +189,21 @@ class CreateMyJobs < ActiveRecord::Migration[7.1]
   end
 end
 
-class MyRecord < ActiveRecord::Base
-  include Marj::RecordInterface
-
+class MyRecord < Marj::Record
   self.table_name = 'my_jobs'
 end
 
 CreateMyJobs.migrate(:up)
 
-class ApplicationJob < ActiveJob::Base
+class MyJob < ActiveJob::Base
   self.queue_adapter = MarjAdapter.new('MyRecord')
 
   extend Marj::JobsInterface
 
   def self.all
-    Marj::Relation.new(
-      self == ApplicationJob ?
-        MyRecord.ordered : MyRecord.where(job_class: self)
-    )
+    Marj::Relation.new(MyRecord.all)
   end
-end
 
-class MyJob < ApplicationJob
   def perform(msg)
     puts msg
   end
@@ -221,7 +219,7 @@ By default, jobs enqeued during tests will be written to the database. Enqueued
 jobs can be executed via:
 
 ```ruby
-Marj::Jobs.due.perform_all
+Marj.due.perform_all
 ```
 
 Alternatively, to use [ActiveJob::QueueAdapters::TestAdapter](https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters/TestAdapter.html):
@@ -318,40 +316,48 @@ SomeJob.queue_adapter = FooAdapter.new             # Uses FooAdapter directly
 
 ### Configuration
 
-- `config.active_job.default_queue_name`
-- `config.active_job.queue_name_prefix`
-- `config.active_job.queue_name_delimiter`
-- `config.active_job.retry_jitter`
-- `SomeJob.queue_name`
-- `SomeJob.queue_as`
-- `SomeJob.queue_name_prefix`
-- `SomeJob.queue_name_delimiter`
-- `SomeJob.retry_jitter`
+```ruby
+config.active_job.default_queue_name
+config.active_job.queue_name_prefix
+config.active_job.queue_name_delimiter
+config.active_job.retry_jitter
+SomeJob.queue_name
+SomeJob.queue_as
+SomeJob.queue_name_prefix
+SomeJob.queue_name_delimiter
+SomeJob.retry_jitter
+```
 
 ### Options
 
-- `:wait` - Enqueues the job with the specified delay
-- `:wait_until` - Enqueues the job at the time specified
-- `:queue` - Enqueues the job on the specified queue
-- `:priority` - Enqueues the job with the specified priority
+```ruby
+:wait       # Enqueues the job with the specified delay
+:wait_until # Enqueues the job at the time specified
+:queue      # Enqueues the job on the specified queue
+:priority   # Enqueues the job with the specified priority
+```
 
 ### Callbacks
 
-- `SomeJob.before_enqueue`
-- `SomeJob.after_enqueue`
-- `SomeJob.around_enqueue`
-- `SomeJob.before_perform`
-- `SomeJob.after_perform`
-- `SomeJob.around_perform`
-- `ActiveJob::Callbacks.singleton_class.set_callback(:execute, :before, &block)`
-- `ActiveJob::Callbacks.singleton_class.set_callback(:execute, :after, &block)`
-- `ActiveJob::Callbacks.singleton_class.set_callback(:execute, :around, &block)`
+```ruby
+SomeJob.before_enqueue
+SomeJob.after_enqueue
+SomeJob.around_enqueue
+SomeJob.before_perform
+SomeJob.after_perform
+SomeJob.around_perform
+ActiveJob::Callbacks.singleton_class.set_callback(:execute, :before, &block)
+ActiveJob::Callbacks.singleton_class.set_callback(:execute, :after, &block)
+ActiveJob::Callbacks.singleton_class.set_callback(:execute, :around, &block)
+```
 
 ### Handling Exceptions
 
-- `SomeJob.retry_on`
-- `SomeJob.discard_on`
-- `SomeJob.after_discard`
+```ruby
+SomeJob.retry_on
+SomeJob.discard_on
+SomeJob.after_discard
+```
 
 ### Creating Jobs
 

data/lib/marj/jobs_interface.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Marj
-  # The interface provided by {Marj::Jobs} and {Marj::Relation}. Include to create a custom jobs interface.
+  # The interface provided by {Marj} and {Marj::Relation}.
   #
-  # To create a jobs interface for all job classes:
+  # To create a custom jobs interface, for example for all job classes in your application:
   #   class ApplicationJob < ActiveJob::Base
   #     extend Marj::JobsInterface
   #
@@ -12,10 +12,19 @@ module Marj
   #     end
   #   end
   #
-  #   ApplicationJob.next
-  #   SomeJob.next
+  #   class SomeJob < ApplicationJob
+  #     def perform(msg)
+  #       puts msg
+  #     end
+  #   end
+  #
+  # This will allow you to query jobs via the +ApplicationJob+ class:
+  #   ApplicationJob.next # Returns the next job of any type
   #
-  # To create a jobs interface for a single job class:
+  # Or to query jobs via a specific job class:
+  #   SomeJob.next # Returns the next SomeJob
+  #
+  # Alternatively, to create a jobs interface for a single job class:
   #   class SomeJob < ActiveJob::Base
   #     extend Marj::JobsInterface
   #
@@ -23,16 +32,26 @@ module Marj
   #       Marj::Relation.new(Marj::Record.where(job_class: self).ordered)
   #     end
   #   end
-  #
-  #   SomeJob.next
   module JobsInterface
+    def self.included(clazz)
+      return if clazz == Marj::Relation
+
+      clazz.delegate :queue, :next, :count, :where, :due, :perform_all, :discard_all, to: :all
+    end
+    private_class_method :included
+
+    def self.extended(clazz)
+      clazz.singleton_class.delegate :queue, :next, :count, :where, :due, :perform_all, :discard_all, to: :all
+    end
+    private_class_method :extended
+
     # Returns a {Marj::Relation} for jobs in the specified queue(s).
     #
     # @param queue [String, Symbol] the queue to query
-    # @param queues [Array<String, Array<Symbol>] more queues to query
+    # @param queues [Array<String>, Array<Symbol>] more queues to query
     # @return [Marj::Relation]
     def queue(queue, *queues)
-      all.queue(queue, *queues)
+      Marj::Relation.new(all.where(queue_name: queues.dup.unshift(queue)))
     end
 
     # Returns the next job or the next N jobs if +limit+ is specified. If no jobs exist, returns +nil+.
@@ -40,7 +59,7 @@ module Marj
     # @param limit [Integer, NilClass]
     # @return [ActiveJob::Base, NilClass]
     def next(limit = nil)
-      all.next(limit)
+      all.first(limit)&.then { _1.is_a?(Array) ? _1.map(&:as_job) : _1.as_job }
     end
 
     # Returns a count of jobs, optionally either matching the specified column name criteria or where the specified
@@ -50,7 +69,7 @@ module Marj
     # @param block [Proc, NilClass]
     # @return [Integer]
     def count(column_name = nil, &block)
-      all.count(column_name, &block)
+      block_given? ? all.count(column_name) { |r| block.call(r.as_job) } : all.count(column_name)
     end
 
     # Returns a {Marj::Relation} for jobs matching the specified criteria.
@@ -58,14 +77,14 @@ module Marj
     # @param args [Array]
     # @return [Marj::Relation]
     def where(*args)
-      all.where(*args)
+      Marj::Relation.new(all.where(*args))
     end
 
     # Returns a {Marj::Relation} for enqueued jobs with a +scheduled_at+ that is either +null+ or in the past.
     #
     # @return [Marj::Relation]
     def due
-      all.due
+      Marj::Relation.new(all.due)
     end
 
     # Calls +perform_now+ on each job.
@@ -73,14 +92,22 @@ module Marj
     # @param batch_size [Integer, NilClass] the number of jobs to fetch at a time, or +nil+ to fetch all jobs at once
     # @return [Array] the results returned by each job
     def perform_all(batch_size: nil)
-      all.perform_all(batch_size: batch_size)
+      if batch_size
+        [].tap do |results|
+          while (jobs = all.limit(batch_size).map(&:as_job)).any?
+            results.concat(jobs.map { |job| ActiveJob::Callbacks.run_callbacks(:execute) { job.perform_now } })
+          end
+        end
+      else
+        all.map(&:as_job).map { |job| ActiveJob::Callbacks.run_callbacks(:execute) { job.perform_now } }
+      end
     end
 
     # Discards all jobs.
     #
     # @return [Numeric] the number of discarded jobs
     def discard_all
-      all.discard_all
+      all.delete_all
     end
   end
 end

data/lib/marj/record.rb

@@ -2,16 +2,81 @@
 
 require 'active_job'
 require 'active_record'
-require_relative 'record_interface'
 
 module Marj
-  # The Marj ActiveRecord model class.
-  #
-  # See https://github.com/nicholasdower/marj
+  # The default +ActiveRecord+ class.
   class Record < ActiveRecord::Base
-    include Marj::RecordInterface
-    extend Marj::RecordInterface::ClassMethods # Added explicitly to generate docs
+    self.table_name = Marj.table_name
 
-    self.table_name = 'jobs'
+    # Order by +enqueued_at+ rather than +job_id+ (the default).
+    self.implicit_order_column = 'enqueued_at'
+
+    # Using a custom serializer for exception_executions so that we can interact with it as a hash rather than a
+    # string.
+    serialize(:exception_executions, coder: JSON)
+
+    # Using a custom serializer for arguments so that we can interact with as an array rather than a string.
+    # This enables code like:
+    #   Marj::Record.next.arguments.first
+    #   Marj::Record.next.update!(arguments: ['foo', 1, Time.now])
+    serialize(:arguments, coder: Class.new do
+      def self.dump(arguments)
+        return ActiveJob::Arguments.serialize(arguments).to_json if arguments.is_a?(Array)
+        return arguments if arguments.is_a?(String) || arguments.nil?
+
+        raise "invalid arguments: #{arguments}"
+      end
+
+      def self.load(arguments)
+        arguments ? ActiveJob::Arguments.deserialize(JSON.parse(arguments)) : nil
+      end
+    end)
+
+    # Using a custom serializer for job_class so that we can interact with it as a class rather than a string.
+    serialize(:job_class, coder: Class.new do
+      def self.dump(clazz)
+        return clazz.name if clazz.is_a?(Class)
+        return clazz if clazz.is_a?(String) || clazz.nil?
+
+        raise "invalid class: #{clazz}"
+      end
+
+      def self.load(str)
+        str&.constantize
+      end
+    end)
+
+    # Returns a job object for this record which will update the database when successfully executed, enqueued or
+    # discarded.
+    #
+    # @return [ActiveJob::Base]
+    def as_job
+      Marj.send(:to_job, self)
+    end
+
+    class << self
+      # Returns an +ActiveRecord::Relation+ scope for enqueued jobs with a +scheduled_at+ that is either +null+ or in
+      # the past.
+      #
+      # @return [ActiveRecord::Relation]
+      def due
+        where('scheduled_at IS NULL OR scheduled_at <= ?', Time.now.utc)
+      end
+
+      # Returns an +ActiveRecord::Relation+ scope for jobs ordered by +priority+ (+null+ last), then +scheduled_at+
+      # (+null+ last), then +enqueued_at+.
+      #
+      # @return [ActiveRecord::Relation]
+      def ordered
+        order(
+          Arel.sql(<<~SQL.squish, Time.now.utc)
+            CASE WHEN scheduled_at IS NULL OR scheduled_at <= ? THEN 0 ELSE 1 END,
+            CASE WHEN priority IS NULL THEN 1 ELSE 0 END, priority,
+            CASE WHEN scheduled_at IS NULL THEN 1 ELSE 0 END, scheduled_at,
+            enqueued_at
+          SQL
+        )
+      end
+    end
   end
 end

data/lib/marj/relation.rb

@@ -8,52 +8,12 @@ module Marj
     include Enumerable
     include Marj::JobsInterface
 
-    # Returns a Marj::Relation which wraps the specified +ActiveRecord+ relation.
-    def initialize(ar_relation)
-      @ar_relation = ar_relation
-    end
-
-    # (see Marj::JobsInterface#queue)
-    def queue(queue, *queues)
-      Marj::Relation.new(@ar_relation.where(queue_name: queues.dup.unshift(queue)))
-    end
-
-    # (see Marj::JobsInterface#next)
-    def next(limit = nil)
-      @ar_relation.first(limit)&.then { _1.is_a?(Array) ? _1.map(&:as_job) : _1.as_job }
-    end
-
-    # (see Marj::JobsInterface#count)
-    def count(column_name = nil, &block)
-      block_given? ? @ar_relation.count(column_name) { |r| block.call(r.as_job) } : @ar_relation.count(column_name)
-    end
+    attr_reader :all
+    private :all
 
-    # (see Marj::JobsInterface#where)
-    def where(*args)
-      Marj::Relation.new(@ar_relation.where(*args))
-    end
-
-    # (see Marj::JobsInterface#due)
-    def due
-      Marj::Relation.new(@ar_relation.due)
-    end
-
-    # (see Marj::JobsInterface#perform_all)
-    def perform_all(batch_size: nil)
-      if batch_size
-        [].tap do |results|
-          while (jobs = @ar_relation.limit(batch_size).map(&:as_job)).any?
-            results.concat(jobs.map { |job| ActiveJob::Callbacks.run_callbacks(:execute) { job.perform_now } })
-          end
-        end
-      else
-        @ar_relation.map(&:as_job).map { |job| ActiveJob::Callbacks.run_callbacks(:execute) { job.perform_now } }
-      end
-    end
-
-    # (see Marj::JobsInterface#discard_all)
-    def discard_all
-      @ar_relation.delete_all
+    # Returns a {Marj::Relation} which wraps the specified +ActiveRecord+ relation.
+    def initialize(ar_relation)
+      @all = ar_relation
     end
 
     # Yields each job in this relation.
@@ -61,14 +21,14 @@ module Marj
     # @param block [Proc]
     # @return [Array] the jobs in this relation
     def each(&block)
-      @ar_relation.map(&:as_job).each(&block)
+      all.map(&:as_job).each(&block)
     end
 
     # Provides +pretty_inspect+ output containing arrays of jobs rather than arrays of records, similar to the output
     # produced when calling +pretty_inspect+ on +ActiveRecord::Relation+.
     #
     # Instead of the default +pretty_inspect+ output:
-    #   > Marj::Jobs.all
+    #   > Marj.all
     #    =>
     #   #<Marj::Relation:0x000000012728bd88
     #    @ar_relation=
@@ -86,7 +46,7 @@ module Marj
     #       timezone: "UTC">]>
     #
     # Produces:
-    #   > Marj::Jobs.all
+    #   > Marj.all
     #    =>
     #   [#<TestJob:0x000000010b63cef8
     #     @_scheduled_at_time=nil,

data/lib/marj.rb

@@ -1,21 +1,74 @@
 # frozen_string_literal: true
 
 require_relative 'marj_adapter'
-require_relative 'marj/jobs'
 require_relative 'marj/jobs_interface'
-require_relative 'marj/record_interface'
 require_relative 'marj/relation'
 
 # A minimal database-backed ActiveJob queueing backend.
 #
+# The {Marj} module provides methods for interacting with enqueued jobs. These methods accept, return and yield
+# +ActiveJob+ objects rather than +ActiveRecord+ objects. Returned jobs are ordered by due date. To query the database
+# directly, use {Record}.
+#
+# Example usage:
+#   Marj.all         # Returns all enqueued jobs.
+#   Marj.queue       # Returns jobs in the specified queue(s).
+#   Marj.due         # Returns jobs which are due to be executed.
+#   Marj.next        # Returns the next job(s) to be executed.
+#   Marj.count       # Returns the number of enqueued jobs.
+#   Marj.where       # Returns jobs matching the specified criteria.
+#   Marj.perform_all # Executes all jobs.
+#   Marj.discard_all # Discards all jobs.
+#   Marj.discard     # Discards the specified job.
+#
+# Query methods can also be chained:
+#   Marj.due.where(job_class: SomeJob).next # Returns the next SomeJob that is due
+#
+# Note that by default, Marj uses {Marj::Record} to interact with the +jobs+ table. To use a different record class, set
+# {record_class}. To simply override the table name, set {table_name} before loading +ActiveRecord+.
+#
 # See https://github.com/nicholasdower/marj
 module Marj
   # The Marj version.
-  VERSION = '3.0.0'
+  VERSION = '4.1.0'
 
   Kernel.autoload(:Record, File.expand_path(File.join('marj', 'record.rb'), __dir__))
 
+  @table_name = :jobs
+  @record_class = 'Marj::Record'
+
   class << self
+    include Marj::JobsInterface
+
+    # @!attribute record_class
+    #   The name of the +ActiveRecord+ class. Defaults to +Marj::Record+.
+    #   @return [Class, String]
+
+    attr_writer :record_class
+
+    def record_class
+      @record_class = @record_class.is_a?(String) ? @record_class.constantize : @record_class
+    end
+
+    # @!attribute table_name
+    #   The name of the database table. Defaults to +:jobs+.
+    #   @return [Symbol, String]
+    attr_accessor :table_name
+
+    # Returns a {Marj::Relation} for all jobs in the order they should be executed.
+    #
+    # @return [Marj::Relation]
+    def all
+      Marj::Relation.new(Marj.record_class.ordered)
+    end
+
+    # Discards the specified job.
+    #
+    # @return [Integer] the number of discarded jobs
+    def discard(job)
+      all.where(job_id: job.job_id).discard_all
+    end
+
     private
 
     # Creates a job instance for the given record which will update the database when successfully executed, enqueued or
@@ -34,9 +87,16 @@ module Marj
       # ActiveJob::Base#deserialize expects dates to be strings rather than Time objects.
       job_data = job_data.to_h { |k, v| [k, %w[enqueued_at scheduled_at].include?(k) ? v&.iso8601 : v] }
 
-      job.tap { job.deserialize(job_data) }
+      job.deserialize(job_data)
+
+      # ActiveJob deserializes arguments on demand when a job is performed. Until then they are empty. That's strange.
+      # Instead, deserialize them now. Also, clear `serialized_arguments` to prevent ActiveJob from overwriting changes
+      # to arguments when serializing later.
+      job.arguments = record.arguments
+      job.serialized_arguments = nil
+
+      job
     end
-    private :to_job
 
     # Registers callbacks for the given job which destroy the given database record when the job succeeds or is
     # discarded.
@@ -57,12 +117,11 @@ module Marj
 
       job
     end
-    private :register_callbacks
 
     # Enqueue a job for execution at the specified time.
     #
     # @param job [ActiveJob::Base] the job to enqueue
-    # @param record_class [Class] the +ActiveRecord+ model class
+    # @param record_class [Class] the +ActiveRecord+ class
     # @param time [Time, NilClass] optional time at which to execute the job
     # @return [ActiveJob::Base] the enqueued job
     def enqueue(job, record_class, time = nil)
@@ -101,6 +160,5 @@ module Marj
       end
       job
     end
-    private :enqueue
   end
 end

data/lib/marj_adapter.rb

@@ -4,9 +4,9 @@
 #
 # See https://github.com/nicholasdower/marj
 class MarjAdapter
-  # Creates a new adapter which will enqueue jobs using the given +ActiveRecord+ model class.
+  # Creates a new adapter which will enqueue jobs using the given +ActiveRecord+ class.
   #
-  # @param record_class [Class, String] the +ActiveRecord+ model class (or its name) to use to store jobs
+  # @param record_class [Class, String] the +ActiveRecord+ class (or its name) to use to store jobs
   def initialize(record_class = 'Marj::Record')
     @record_class = record_class
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: marj
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Nick Dower
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-27 00:00:00.000000000 Z
+date: 2024-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -48,10 +48,8 @@ files:
 - LICENSE.txt
 - README.md
 - lib/marj.rb
-- lib/marj/jobs.rb
 - lib/marj/jobs_interface.rb
 - lib/marj/record.rb
-- lib/marj/record_interface.rb
 - lib/marj/relation.rb
 - lib/marj_adapter.rb
 homepage: https://github.com/nicholasdower/marj
@@ -59,8 +57,8 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/nicholasdower/marj/issues
-  changelog_uri: https://github.com/nicholasdower/marj/releases/tag/v3.0.0
-  documentation_uri: https://www.rubydoc.info/github/nicholasdower/marj/v3.0.0
+  changelog_uri: https://github.com/nicholasdower/marj/releases/tag/v4.1.0
+  documentation_uri: https://www.rubydoc.info/github/nicholasdower/marj/v4.1.0
   homepage_uri: https://github.com/nicholasdower/marj
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/nicholasdower/marj

data/lib/marj/jobs.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'jobs_interface'
-require_relative 'relation'
-
-module Marj
-  # Provides methods for querying, performing and discarding jobs. Returns, yields and accepts
-  # +ActiveJob+ objects rather than +ActiveRecord+ objects. To query the database directly, use
-  # {Marj::Record}.
-  #
-  # To create a custom jobs interface, see {Marj::JobsInterface}.
-  module Jobs
-    singleton_class.include Marj::JobsInterface
-
-    # Returns a {Marj::Relation} for all jobs in the order they should be executed.
-    #
-    # @return [Marj::Relation]
-    def self.all
-      Marj::Relation.new(Marj::Record.ordered)
-    end
-
-    # Discards the specified job.
-    #
-    # @return [Integer] the number of discarded jobs
-    def self.discard(job)
-      all.where(job_id: job.job_id).discard_all
-    end
-  end
-end

data/lib/marj/record_interface.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-require 'active_job/arguments'
-
-module Marj
-  # Provides base functionality for {Marj::Record}. Can be used to create a custom +ActiveRecord+ model class.
-  #
-  # Example Usage:
-  #   class MyRecord < ActiveRecord::Base
-  #     include Marj::RecordInterface
-  #
-  #     self.table_name = 'my_jobs'
-  #   end
-  module RecordInterface
-    # Adds {ClassMethods}, custom serializers and an implicit order column to the including class.
-    #
-    # @param clazz [Class] the including class
-    def self.included(clazz)
-      clazz.extend(ClassMethods)
-
-      # Order by +enqueued_at+ rather than +job_id+ (the default).
-      clazz.implicit_order_column = 'enqueued_at'
-
-      # Using a custom serializer for exception_executions so that we can interact with it as a hash rather than a
-      # string.
-      clazz.serialize(:exception_executions, coder: JSON)
-
-      # Using a custom serializer for arguments so that we can interact with as an array rather than a string.
-      # This enables code like:
-      #   Marj::Record.next.arguments.first
-      #   Marj::Record.next.update!(arguments: ['foo', 1, Time.now])
-      clazz.serialize(:arguments, coder: Class.new do
-        def self.dump(arguments)
-          return ActiveJob::Arguments.serialize(arguments).to_json if arguments.is_a?(Array)
-          return arguments if arguments.is_a?(String) || arguments.nil?
-
-          raise "invalid arguments: #{arguments}"
-        end
-
-        def self.load(arguments)
-          arguments ? ActiveJob::Arguments.deserialize(JSON.parse(arguments)) : nil
-        end
-      end)
-
-      # Using a custom serializer for job_class so that we can interact with it as a class rather than a string.
-      clazz.serialize(:job_class, coder: Class.new do
-        def self.dump(clazz)
-          return clazz.name if clazz.is_a?(Class)
-          return clazz if clazz.is_a?(String) || clazz.nil?
-
-          raise "invalid class: #{clazz}"
-        end
-
-        def self.load(str)
-          str&.constantize
-        end
-      end)
-    end
-
-    # Class methods for {Marj::RecordInterface}.
-    module ClassMethods
-      # Returns an +ActiveRecord::Relation+ scope for enqueued jobs with a +scheduled_at+ that is either +null+ or in
-      # the past.
-      #
-      # @return [ActiveRecord::Relation]
-      def due
-        where('scheduled_at IS NULL OR scheduled_at <= ?', Time.now.utc)
-      end
-
-      # Returns an +ActiveRecord::Relation+ scope for jobs ordered by +priority+ (+null+ last), then +scheduled_at+
-      # (+null+ last), then +enqueued_at+.
-      #
-      # @return [ActiveRecord::Relation]
-      def ordered
-        order(
-          Arel.sql(<<~SQL.squish, Time.now.utc)
-            CASE WHEN scheduled_at IS NULL OR scheduled_at <= ? THEN 0 ELSE 1 END,
-            CASE WHEN priority IS NULL THEN 1 ELSE 0 END, priority,
-            CASE WHEN scheduled_at IS NULL THEN 1 ELSE 0 END, scheduled_at,
-            enqueued_at
-          SQL
-        )
-      end
-    end
-
-    # Returns a job object for this record which will update the database when successfully executed, enqueued or
-    # discarded.
-    #
-    # @return [ActiveJob::Base]
-    def as_job
-      Marj.send(:to_job, self)
-    end
-  end
-end