que-scheduler 7.0.1 → 7.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b09366936c031d9621c4596d06e3ad7bf590a6d52a2db9cf1b0f9fe31b8d3bba
-  data.tar.gz: d8caa2bfb5becaee14cbc827a63aa0d138597f702e62d7e59e65acff604baa77
+  metadata.gz: bdd3f8eb6dccc6c82cb4ce97f0a64f7acf30394cdc4d7f7f299d86680209777a
+  data.tar.gz: ac8c0c66d2fb3def5887a6f7cc27b6577c28692b55549fd067e09ad6767fe68e
 SHA512:
-  metadata.gz: a371c6a801e5bcd9fb153faa8190cce580192fb6bc304c4cecdb3e8fb89d782f0ced9b07e05a7a546a631c9a73dec40648fe4c8bc800930e175ac810d4e81d4e
-  data.tar.gz: 02ff472a2d83564fd197a6e03fea030e8304e1a2ea2f49c900e83afdc9a70d2d07dc2ce88941fd153f53fc4d9ec445c05ba1271aba330b8f8663a76ede2a7264
+  metadata.gz: 384c9a75444bac91293d13f4bcfa9c79418df2b43d537a8707b1996705c27d44d44422a7af90135ec34311d872096fa06a1ac32eefbf5bf770223673019c2606
+  data.tar.gz: 1f6e7fa846f34937010560a8905c84b56f2e67f87acafd9d0b72d83503f9ec32b36b7ad9c1d77f7396cd7e8ccfe0564a494d2992bb82430fc4ff3cfab76a6f46

data/README.md

@@ -123,11 +123,13 @@ A job can have a `schedule_type` assigned to it. Valid values are:
   times go by during an extended period of downtime (eg a long maintenance window) then only one job
   will be enqueued when the system starts back up. Multiple missed events are coalesced. This mimics
   the way resque-scheduler would perform if it were taken down for some time.
+  The job's `run_at` is the latest missed cron time.
 1. `every_event` - Every cron match will result in a job being scheduled. If multiple cron times go 
   by during an extended period of downtime, then a job will be scheduled for every one missed on 
   startup. This `schedule_type` should be used for regular batch jobs that need to know which time
   they are running a batch for. The job will always be scheduled with an ISO8601 string of the cron 
   that matched as the first argument. 
+  Its `run_at` is that same cron time, so overdue jobs retain their scheduled order within a priority.
   
   An example would be an eventing DailyReportJob which summarises a day's sales. If no jobs run for
   a few days due to a technical failure, then on recovery a report would still be needed for each 
@@ -338,3 +340,4 @@ This gem was inspired by the makers of the excellent [Que](https://github.com/ch
 * @milgner
 * @oiahoon
 * @papodaca
+* @bensynapse

data/lib/que/scheduler/audit.rb

@@ -1,6 +1,9 @@
+# typed: true
 # frozen_string_literal: true
 
+require "sorbet-runtime"
 require_relative "to_enqueue"
+require_relative "types"
 
 module Que
   module Scheduler
@@ -23,6 +26,15 @@ module Que
       }.freeze
 
       class << self
+        extend T::Sig
+
+        sig do
+          params(
+            scheduler_job_id: Integer,
+            executed_at: Types::TIME,
+            enqueued_jobs: T::Array[Que::Scheduler::EnqueuedJobType]
+          ).void
+        end
         def append(scheduler_job_id, executed_at, enqueued_jobs)
           ::Que::Scheduler::DbSupport.execute(INSERT_AUDIT, [scheduler_job_id, executed_at])
           enqueued_jobs.each do |j|

data/lib/que/scheduler/configuration.rb

@@ -1,23 +1,47 @@
+# typed: true
+
+require "pathname"
 require "que"
+require "sorbet-runtime"
 require_relative "db_support"
+require_relative "types"
 
 module Que
   module Scheduler
     # :reek:Attribute
     class Configuration
-      attr_accessor :schedule_location, :schedule, :transaction_adapter, :que_scheduler_queue,
-                    :time_zone
+      extend T::Sig
+
+      sig { returns(T.any(String, Pathname)) }
+      attr_accessor :schedule_location
+
+      sig { returns(T.nilable(Types::SCHEDULE_CONFIG)) }
+      attr_accessor :schedule
+
+      sig { returns(T.any(Method, Proc)) }
+      attr_accessor :transaction_adapter
+
+      sig { returns(String) }
+      attr_accessor :que_scheduler_queue
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :time_zone
     end
 
     class << self
-      # :reek:Attribute
-      attr_accessor :configuration # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+      extend T::Sig
+
+      sig { returns(Configuration) }
+      def configuration
+        @configuration ||= Configuration.new
+      end
 
-      def configure
-        self.configuration ||= Configuration.new
+      sig { params(blk: T.proc.params(config: Configuration).void).void }
+      def configure(&blk)
         yield(configuration)
       end
 
+      sig { void }
       def apply_defaults
         configure do |config|
           config.schedule_location =

data/lib/que/scheduler/db.rb

@@ -1,5 +1,7 @@
+# typed: true
 # frozen_string_literal: true
 
+require "sorbet-runtime"
 require_relative "configuration"
 
 module Que
@@ -10,19 +12,31 @@ module Que
       NOW_SQL = "SELECT now()"
 
       class << self
+        extend T::Sig
+
+        sig { returns(Integer) }
         def count_schedulers
-          Que::Scheduler::DbSupport.execute(SCHEDULER_COUNT_SQL).first.values.first.to_i
+          T.cast(first_value(SCHEDULER_COUNT_SQL), Integer)
         end
 
+        sig { returns(Time) }
         def now
-          Que::Scheduler::DbSupport.execute(NOW_SQL).first.values.first
+          T.cast(first_value(NOW_SQL), Time)
+        end
+
+        sig { params(sql: String).returns(T.anything) }
+        private def first_value(sql)
+          Que::Scheduler::DbSupport.execute(sql).fetch(0).values.fetch(0)
         end
 
-        # rubocop:disable Style/ExplicitBlockArgument
-        def transaction
-          Que::Scheduler.configuration.transaction_adapter.call { yield }
+        sig do
+          type_parameters(:U)
+            .params(blk: T.proc.returns(T.type_parameter(:U)))
+            .returns(T.type_parameter(:U))
+        end
+        def transaction(&blk)
+          Que::Scheduler.configuration.transaction_adapter.call(&blk)
         end
-        # rubocop:enable Style/ExplicitBlockArgument
       end
     end
   end

data/lib/que/scheduler/db_support.rb

@@ -1,39 +1,64 @@
+# typed: true
+
 require "que"
+require "sorbet-runtime"
 
 module Que
   module Scheduler
     module DbSupport
       class << self
+        extend T::Sig
+
+        sig { params(enqueued_job: Que::Job).returns(T::Hash[Symbol, T.anything]) }
         def job_attributes(enqueued_job)
           enqueued_job.que_attrs.to_h.transform_keys(&:to_sym).tap do |hash|
             hash[:job_id] = hash.delete(:id)
           end
         end
 
+        sig { params(enqueued_job: Que::Job).returns(Integer) }
+        def job_id(enqueued_job) = T.cast(job_attributes(enqueued_job).fetch(:job_id), Integer)
+
         # Between Que versions the result of Que execute changed keys from strings to symbols.
         # Here we wrap the concept and make sure either way produces symbols
+        sig do
+          params(str: String, args: T::Array[T.anything])
+            .returns(T::Array[T::Hash[Symbol, T.anything]])
+        end
         def execute(str, args = [])
           normalise_array_of_hashes(Que.execute(str, args))
         end
 
+        sig do
+          params(
+            clazz: T.class_of(Que::Job),
+            job_options: T::Hash[Symbol, T.anything],
+            job_args: T.anything
+          ).returns(T.nilable(T.any(Que::Job, FalseClass)))
+        end
         def enqueue_a_job(clazz, job_options = {}, job_args = [])
-          if job_args.is_a?(Hash)
+          case job_args
+          when Hash
             clazz.enqueue(job_args, job_options: job_options)
           else
-            clazz.enqueue(*job_args, job_options: job_options)
+            # Sorbet cannot type a splat of a value of unknown size
+            T.unsafe(clazz).enqueue(*job_args, job_options: job_options)
           end
         end
 
+        sig { returns(String) }
         def que_version
           @que_version ||= que_version_object.to_s
         end
 
+        sig { returns(Gem::Version) }
         private def que_version_object
-          @que_version_object ||= Gem.loaded_specs["que"].version
+          @que_version_object ||= T.must(Gem.loaded_specs["que"]).version
         end
 
+        sig { params(array: T::Array[T.anything]).returns(T::Array[T::Hash[Symbol, T.anything]]) }
         private def normalise_array_of_hashes(array)
-          array.map { |row| row.to_h.transform_keys(&:to_sym) }
+          array.map { |row| T.cast(row, T::Hash[T.any(String, Symbol), T.anything]).to_h.transform_keys(&:to_sym) }
         end
       end
     end

data/lib/que/scheduler/defined_job.rb

@@ -1,11 +1,16 @@
+# typed: true
+
 require "hashie"
+require "sorbet-runtime"
 require "fugit"
+require_relative "types"
 
 # This is the definition of one scheduleable job in the que-scheduler config yml file.
 module Que
   module Scheduler
-    class DefinedJob < Hashie::Dash
+    class DefinedJob < Hashie::Dash # rubocop:disable Metrics/ClassLength -- shrinks with T::Struct
       include Hashie::Extensions::Dash::PropertyTranslation
+      extend T::Sig
 
       DEFINED_JOB_TYPES = [
         DEFINED_JOB_TYPE_DEFAULT = :default,
@@ -21,6 +26,9 @@ module Que
       property :schedule_type, default: DEFINED_JOB_TYPE_DEFAULT
 
       class << self
+        extend T::Sig
+
+        sig { params(options: T::Hash[Symbol, T.anything]).returns(DefinedJob) }
         def create(options)
           defined_job = new(options.compact)
           defined_job.freeze.tap { |dj| dj.validate(options) }
@@ -29,6 +37,7 @@ module Que
 
       # Given a "last time", return the next Time the event will occur, or nil if it
       # is after "to".
+      sig { params(from: Types::TIME, to: Types::TIME).returns(T.nilable(ActiveSupport::TimeWithZone)) }
       def next_run_time(from, to)
         next_time = cron.next_time(from)
         next_run = next_time.to_local_time.in_time_zone(next_time.zone)
@@ -37,9 +46,10 @@ module Que
 
       # Given the last scheduler run time, and this run time, return all
       # the instances that should be enqueued for the job class.
+      sig { params(last_run_time: Types::TIME, as_time: Types::TIME).returns(T::Array[ToEnqueue]) }
       def calculate_missed_runs(last_run_time, as_time)
-        missed_times = []
-        last_time = last_run_time
+        missed_times = T.let([], T::Array[ActiveSupport::TimeWithZone])
+        last_time = T.let(last_run_time, Types::TIME)
         while (next_run = next_run_time(last_time, as_time))
           missed_times << next_run
           last_time = next_run
@@ -48,6 +58,7 @@ module Que
         generate_to_enqueue_list(missed_times)
       end
 
+      sig { params(options: T::Hash[Symbol, T.anything]).void }
       def validate(options)
         validate_fields_presence(options)
         validate_fields_types(options)
@@ -55,6 +66,7 @@ module Que
       end
 
       # rubocop:disable Style/GuardClause -- This reads better as a conditional
+      sig { params(options: T::Hash[Symbol, T.anything]).void }
       private def validate_fields_types(options)
         unless queue.nil? || queue.is_a?(String)
           err_field(:queue, options, "queue must be a string")
@@ -68,6 +80,7 @@ module Que
       end
       # rubocop:enable Style/GuardClause
 
+      sig { params(options: T::Hash[Symbol, T.anything]).void }
       private def validate_fields_presence(options)
         err_field(:name, options, "name must be present") if name.nil?
         err_field(:job_class, options, "job_class must be present") if job_class.nil?
@@ -75,6 +88,7 @@ module Que
         err_field(:cron, options, "cron must be present") if cron.nil?
       end
 
+      sig { params(options: T::Hash[Symbol, T.anything]).void }
       private def validate_job_class_related(options)
         # Only support known job engines
         unless Que::Scheduler::ToEnqueue.valid_job_class?(job_class)
@@ -86,7 +100,7 @@ module Que
         if queue &&
            Que::Scheduler::ToEnqueue.active_job_defined? &&
            job_class < ::ActiveJob::Base &&
-           Que::Scheduler::ToEnqueue.active_job_version < Gem::Version.create("6.0.3")
+           T.must(Que::Scheduler::ToEnqueue.active_job_version) < Gem::Version.create("6.0.3")
           puts <<~ERR
             WARNING from que-scheduler....
             Between versions 4.2.3 and 6.0.2 (inclusive) Rails did not support setting queue names
@@ -102,6 +116,7 @@ module Que
         end
       end
 
+      sig { params(field: Symbol, options: T::Hash[Symbol, T.anything], reason: String).returns(T.noreturn) }
       private def err_field(field, options, reason = "")
         schedule = Que::Scheduler.configuration.schedule_location
         value = options[field]
@@ -109,6 +124,7 @@ module Que
               "#{reason}"
       end
 
+      sig { params(missed_times: T::Array[ActiveSupport::TimeWithZone]).returns(T::Array[ToEnqueue]) }
       private def generate_to_enqueue_list(missed_times)
         return [] if missed_times.empty?
 
@@ -116,10 +132,11 @@ module Que
 
         if schedule_type == DefinedJob::DEFINED_JOB_TYPE_EVERY_EVENT
           missed_times.map do |time_missed|
-            ToEnqueue.create(options.merge(args: [time_missed.iso8601] + args_array))
+            ToEnqueue.create(options.merge(run_at: time_missed,
+                                           args: [time_missed.iso8601] + args_array))
           end
         else
-          [ToEnqueue.create(options.merge(args: args_array))]
+          [ToEnqueue.create(options.merge(run_at: missed_times.last, args: args_array))]
         end
       end
     end

data/lib/que/scheduler/enqueueing_calculator.rb

@@ -1,4 +1,7 @@
+# typed: true
+
 require "fugit"
+require "sorbet-runtime"
 
 module Que
   module Scheduler
@@ -9,6 +12,14 @@ module Que
       end
 
       class << self
+        extend T::Sig
+
+        sig do
+          params(
+            scheduler_config: T::Array[DefinedJob],
+            scheduler_job_args: SchedulerJobArgs
+          ).returns(Result)
+        end
         def parse(scheduler_config, scheduler_job_args)
           job_dictionary = []
 

data/lib/que/scheduler/jobs/que_scheduler_audit_clear_down_job.rb

@@ -1,4 +1,7 @@
+# typed: true
+
 require "que"
+require "sorbet-runtime"
 
 # This job can optionally be scheduled to clear down the que-scheduler audit log if it
 # isn't required in the long term.
@@ -6,7 +9,12 @@ module Que
   module Scheduler
     module Jobs
       class QueSchedulerAuditClearDownJob < Que::Job
+        extend T::Sig
+
         class << self
+          extend T::Sig
+
+          sig { params(table_name: String).returns(String) }
           def build_sql(table_name)
             <<~SQL
               WITH deleted AS (
@@ -28,6 +36,7 @@ module Que
         self.priority = 100
         self.queue = -> { Que::Scheduler.configuration.que_scheduler_queue }
 
+        sig { params(options: T::Hash[T.any(String, Symbol), T.anything]).void }
         def run(options)
           retain_row_count = options.symbolize_keys.fetch(:retain_row_count)
           Que::Scheduler::Db.transaction do
@@ -36,7 +45,7 @@ module Que
             Que::Scheduler::DbSupport.execute(DELETE_AUDIT_ENQUEUED_SQL, [retain_row_count])
             # This will delete all but `retain_row_count` oldest rows
             count = Que::Scheduler::DbSupport.execute(DELETE_AUDIT_SQL, [retain_row_count])
-            log = "#{self.class} cleared down #{count.first.fetch(:count)} rows"
+            log = "#{self.class} cleared down #{count.fetch(0).fetch(:count)} rows"
             ::Que.log(event: :"que-scheduler", message: log)
           end
         end

data/lib/que/scheduler/migrations.rb

@@ -1,5 +1,8 @@
+# typed: true
 # frozen_string_literal: true
 
+require "sorbet-runtime"
+
 module Que
   module Scheduler
     module Migrations
@@ -12,6 +15,9 @@ module Que
       MAX_VERSION = Dir.glob("#{__dir__}/migrations/*").map { |d| File.basename(d) }.map(&:to_i).max
 
       class << self
+        extend T::Sig
+
+        sig { params(version: Integer).void }
         def migrate!(version:)
           # Like que, Do not migrate test DBs.
           return if defined?(Que::Testing)
@@ -27,9 +33,11 @@ module Que
         end
 
         # rubocop:disable MagicNumbers/NoReturn
+        sig { returns(Integer) }
         def db_version
           if audit_table_exists?
-            return Que::Scheduler::DbSupport.execute(TABLE_COMMENT).first[:description].to_i
+            comment = Que::Scheduler::DbSupport.execute(TABLE_COMMENT).fetch(0).fetch(:description)
+            return T.cast(comment, T.nilable(String)).to_i
           end
 
           # At this point we used to be able to tell if it was 0 or 1 by the presence of the
@@ -38,6 +46,7 @@ module Que
         end
         # rubocop:enable MagicNumbers/NoReturn
 
+        sig { returns(T::Boolean) }
         def audit_table_exists?
           result = Que::Scheduler::DbSupport.execute(<<-SQL)
             SELECT * FROM information_schema.tables WHERE table_name = '#{AUDIT_TABLE_NAME}';
@@ -47,6 +56,7 @@ module Que
 
         # This method must be used during initial installation of que-scheduler and if the
         # project migrations are squashed.
+        sig { void }
         def reenqueue_scheduler_if_missing
           raise <<~MSG unless Que::Migrations.db_version >= 6
             Cannot (re)enqueue the que-scheduler worker unless the Que migrations have been run to at least version 6.
@@ -64,15 +74,18 @@ module Que
           Que::Scheduler::DbSupport.enqueue_a_job(Que::Scheduler::SchedulerJob)
         end
 
+        sig { params(current: Integer, version: Integer).void }
         private def migrate_up(current, version)
           execute_step(current += 1, :up) until current == version
         end
 
+        sig { params(current: Integer, version: Integer).void }
         private def migrate_down(current, version)
           current += 1
           execute_step(current -= 1, :down) until current == version + 1
         end
 
+        sig { params(number: Integer, direction: Symbol).void }
         private def execute_step(number, direction)
           sql = File.read("#{__dir__}/migrations/#{number}/#{direction}.sql")
           Que::Scheduler::DbSupport.execute(sql)

data/lib/que/scheduler/schedule.rb

@@ -1,21 +1,29 @@
+# typed: true
+
+require "sorbet-runtime"
 require_relative "configuration"
 require_relative "defined_job"
+require_relative "types"
 
 module Que
   module Scheduler
     class Schedule
       class << self
+        extend T::Sig
+
         # The main method for determining the schedule. It has to evaluate the schedule as late as
         # possible (ie just as it is about to be used) as we cannot guarantee we are in a Rails
         # app with initializers. In a future release this may change to "fast fail" in Rails by
         # checking the config up front.
+        sig { returns(T::Hash[String, DefinedJob]) }
         def schedule
           @schedule ||=
             begin
               configuration = Que::Scheduler.configuration
-              if !configuration.schedule.nil?
+              explicit_schedule = configuration.schedule
+              if !explicit_schedule.nil?
                 # If an explicit schedule as a hash has been defined, use that.
-                from_hash(configuration.schedule)
+                from_hash(explicit_schedule)
               elsif File.exist?(configuration.schedule_location)
                 # If the schedule is defined as a file location, then load it and return it.
                 from_file(configuration.schedule_location)
@@ -26,21 +34,30 @@ module Que
             end
         end
 
+        sig { params(location: T.any(String, Pathname)).returns(T::Hash[String, DefinedJob]) }
         def from_file(location)
           from_yaml(File.read(location))
         end
 
+        sig { params(config: String).returns(T::Hash[String, DefinedJob]) }
         def from_yaml(config)
           config_hash = YAML.safe_load(config)
           from_hash(config_hash)
         end
 
+        sig { params(config_hash: Types::SCHEDULE_CONFIG).returns(T::Hash[String, DefinedJob]) }
         def from_hash(config_hash)
           config_hash
             .map { |name, defined_job_hash| hash_item_to_defined_job(name.to_s, defined_job_hash) }
             .index_by(&:name)
         end
 
+        sig do
+          params(
+            name: String,
+            defined_job_hash_in: T::Hash[T.any(String, Symbol), T.anything]
+          ).returns(DefinedJob)
+        end
         def hash_item_to_defined_job(name, defined_job_hash_in)
           defined_job_hash = defined_job_hash_in.stringify_keys
           # Que stores arguments as a json array. If the args we have to provide are already an
@@ -77,6 +94,9 @@ module Que
     end
 
     class << self
+      extend T::Sig
+
+      sig { returns(T::Hash[String, DefinedJob]) }
       def schedule
         Schedule.schedule
       end

data/lib/que/scheduler/scheduler_job.rb

@@ -1,4 +1,7 @@
+# typed: true
+
 require "que"
+require "sorbet-runtime"
 require "active_support"
 require "active_support/core_ext/time"
 
@@ -8,12 +11,15 @@ require_relative "scheduler_job_args"
 require_relative "state_checks"
 require_relative "to_enqueue"
 require_relative "db_support"
+require_relative "types"
 
 # The main job that runs every minute, determining what needs to be enqueued, enqueues the required
 # jobs, then re-enqueues itself.
 module Que
   module Scheduler
     class SchedulerJob < Que::Job
+      extend T::Sig
+
       SCHEDULER_FREQUENCY = 60
       RETRY_PROC = proc { |count|
         # Maximum one hour, otherwise use the default backoff
@@ -24,6 +30,7 @@ module Que
       self.maximum_retry_count = 1 << 128 # Heat death of universe
       self.retry_interval = RETRY_PROC
 
+      sig { params(options: T.nilable(T::Hash[T.any(String, Symbol), T.anything])).void }
       def run(options = nil)
         Que::Scheduler::Db.transaction do
           Que::Scheduler::StateChecks.check
@@ -42,6 +49,12 @@ module Que
         end
       end
 
+      sig do
+        params(
+          calculator_result: EnqueueingCalculator::Result,
+          logs: T::Array[String]
+        ).returns(T::Array[EnqueuedJobType])
+      end
       def enqueue_required_jobs(calculator_result, logs)
         calculator_result.missed_jobs.filter_map do |to_enqueue|
           to_enqueue.enqueue.tap do |enqueued_job|
@@ -50,6 +63,13 @@ module Que
         end
       end
 
+      sig do
+        params(
+          to_enqueue: ToEnqueue,
+          enqueued_job: T.nilable(EnqueuedJobType),
+          logs: T::Array[String]
+        ).void
+      end
       private def check_enqueued_job(to_enqueue, enqueued_job, logs)
         logs << if enqueued_job.present?
                   "que-scheduler enqueueing #{enqueued_job.job_class} " \
@@ -61,10 +81,18 @@ module Que
                 end
       end
 
+      sig do
+        params(
+          scheduler_job_args: SchedulerJobArgs,
+          last_full_execution: Types::TIME,
+          job_dictionary: T::Array[String],
+          enqueued_jobs: T::Array[EnqueuedJobType]
+        ).void
+      end
       private def enqueue_self_again(scheduler_job_args, last_full_execution, job_dictionary,
                                      enqueued_jobs)
         # Log last run...
-        job_id = DbSupport.job_attributes(self).fetch(:job_id)
+        job_id = DbSupport.job_id(self)
         Audit.append(job_id, scheduler_job_args.as_time, enqueued_jobs)
 
         # And rerun...

data/lib/que/scheduler/scheduler_job_args.rb

@@ -1,4 +1,7 @@
+# typed: true
+
 require "hashie"
+require "sorbet-runtime"
 require "active_support"
 require "active_support/time_with_zone"
 
@@ -10,6 +13,9 @@ module Que
       property :job_dictionary, required: true
       property :as_time, required: true
 
+      extend T::Sig
+
+      sig { params(options: T.nilable(T::Hash[T.any(String, Symbol), T.anything])).returns(SchedulerJobArgs) }
       def self.build(options)
         now = Que::Scheduler::Db.now
         parsed =

data/lib/que/scheduler/state_checks.rb

@@ -1,3 +1,6 @@
+# typed: true
+
+require "sorbet-runtime"
 require_relative "audit"
 require_relative "db"
 require_relative "migrations"
@@ -6,11 +9,15 @@ module Que
   module Scheduler
     module StateChecks
       class << self
+        extend T::Sig
+
+        sig { void }
         def check
           assert_db_migrated
         end
 
         # rubocop:disable Metrics/MethodLength
+        sig { void }
         private def assert_db_migrated
           db_version = Que::Scheduler::Migrations.db_version
           return if db_version == Que::Scheduler::Migrations::MAX_VERSION

data/lib/que/scheduler/time_zone.rb

@@ -1,3 +1,7 @@
+# typed: true
+
+require "sorbet-runtime"
+
 module Que
   module Scheduler
     module TimeZone
@@ -35,6 +39,9 @@ module Que
       ERR
 
       class << self
+        extend T::Sig
+
+        sig { returns(ActiveSupport::TimeZone) }
         def time_zone
           @time_zone ||=
             begin

data/lib/que/scheduler/to_enqueue.rb

@@ -1,44 +1,63 @@
+# typed: true
+
 require "que"
+require "sorbet-runtime"
 
 # This module uses polymorphic dispatch to centralise the differences between supporting Que::Job
 # and other job systems.
 module Que
   module Scheduler
     class ToEnqueue < Hashie::Dash
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+
       property :args, required: true, default: []
       property :queue
       property :priority
       property :run_at, required: true
       property :job_class, required: true
 
+      sig { abstract.returns(T.nilable(EnqueuedJobType)) }
+      def enqueue; end
+
       class << self
+        extend T::Sig
+
+        sig { params(options: T::Hash[Symbol, T.anything]).returns(ToEnqueue) }
         def create(options)
-          type_from_job_class(options.fetch(:job_class)).new(
-            options.merge(run_at: Que::Scheduler::Db.now)
+          T.must(type_from_job_class(T.cast(options.fetch(:job_class), Class))).new(
+            options.merge(run_at: options.fetch(:run_at) { Que::Scheduler::Db.now })
           )
         end
 
+        sig { params(job_class: Class).returns(T::Boolean) }
         def valid_job_class?(job_class)
           type_from_job_class(job_class).present?
         end
 
+        sig { returns(T::Boolean) }
         def active_job_defined?
           Object.const_defined?(:ActiveJob)
         end
 
+        sig { returns(T.nilable(Gem::Version)) }
         def active_job_version
           Gem.loaded_specs["activejob"]&.version
         end
 
+        sig { returns(T::Boolean) }
         def active_job_version_supports_queues?
           # Supporting queue name in ActiveJob was removed in Rails 4.2.3
           # https://github.com/rails/rails/pull/19498
           # and readded in Rails 6.0.3
           # https://github.com/rails/rails/pull/38635
-          ToEnqueue.active_job_version && ToEnqueue.active_job_version >=
-            Gem::Version.create("6.0.3")
+          version = ToEnqueue.active_job_version
+          !version.nil? && version >= Gem::Version.create("6.0.3")
         end
 
+        sig { params(job_class: Class).returns(T.nilable(T.class_of(ToEnqueue))) }
         private def type_from_job_class(job_class)
           types.each do |type, implementation|
             return implementation if job_class < type
@@ -46,6 +65,7 @@ module Que
           nil
         end
 
+        sig { returns(T::Hash[Class, T.class_of(ToEnqueue)]) }
         private def types
           @types ||=
             begin
@@ -61,10 +81,11 @@ module Que
 
     # For jobs of type Que::Job
     class QueJobType < ToEnqueue
+      sig { override.returns(T.nilable(EnqueuedJobType)) }
       def enqueue
         job_settings = to_h.slice(:queue, :priority, :run_at).compact
         job = Que::Scheduler::DbSupport.enqueue_a_job(
-          job_class,
+          T.cast(job_class, T.class_of(Que::Job)),
           job_settings,
           args
         )
@@ -82,6 +103,7 @@ module Que
 
     # For jobs of type ActiveJob
     class ActiveJobType < ToEnqueue
+      sig { override.returns(T.nilable(EnqueuedJobType)) }
       def enqueue
         job = enqueue_active_job
 
@@ -91,6 +113,7 @@ module Que
         EnqueuedJobType.new(enqueued_values)
       end
 
+      sig { params(job: ::ActiveJob::Base).returns(T::Hash[Symbol, T.anything]) }
       def calculate_enqueued_values(job)
         # Now read the just inserted job back out of the DB to get the actual values that will
         # be used when the job is worked.
@@ -117,6 +140,7 @@ module Que
         }
       end
 
+      sig { returns(T.nilable(T.any(::ActiveJob::Base, FalseClass))) }
       def enqueue_active_job
         job_settings = {
           priority: priority,
@@ -124,22 +148,29 @@ module Que
           queue: queue || Que::DEFAULT_QUEUE,
         }.compact
 
-        job_class_set = job_class.set(**job_settings)
-        if args.is_a?(Hash)
-          job_class_set.perform_later(**args)
+        job_class_set = T.cast(job_class, T.class_of(::ActiveJob::Base)).set(**job_settings)
+        job_args = args
+        case job_args
+        when Hash
+          job_class_set.perform_later(**job_args)
         else
-          job_class_set.perform_later(*args)
+          # Sorbet cannot type a splat of a value of unknown size
+          T.unsafe(job_class_set).perform_later(*job_args)
         end
       end
 
       class << self
+        extend T::Sig
+
         # ActiveJob scheduled_at is returned as a float, or a string post Rails 7.1,
         # and we want a Time for consistency
+        sig { params(scheduled_at: T.anything).returns(T.nilable(ActiveSupport::TimeWithZone)) }
         def extract_scheduled_at(scheduled_at)
           # rubocop:disable Style/EmptyElse
-          if scheduled_at.is_a?(Float)
+          case scheduled_at
+          when Float
             Que::Scheduler::TimeZone.time_zone.at(scheduled_at)
-          elsif scheduled_at.is_a?(String)
+          when String
             Que::Scheduler::TimeZone.time_zone.parse(scheduled_at)
           else
             nil

data/lib/que/scheduler/types.rb

@@ -0,0 +1,18 @@
+# typed: true
+
+require "sorbet-runtime"
+require "active_support"
+require "active_support/time_with_zone"
+
+module Que
+  module Scheduler
+    module Types
+      # Times come from both Postgres (Time) and the configured zone (TimeWithZone)
+      TIME = T.type_alias { T.any(Time, ActiveSupport::TimeWithZone) }
+      # A schedule as given in config: job name to its options
+      SCHEDULE_CONFIG = T.type_alias do
+        T::Hash[T.any(String, Symbol), T::Hash[T.any(String, Symbol), T.anything]]
+      end
+    end
+  end
+end

data/lib/que/scheduler/version.rb

@@ -1,5 +1,7 @@
+# typed: true
+
 module Que
   module Scheduler
-    VERSION = "7.0.1".freeze
+    VERSION = "7.2.0".freeze
   end
 end

data/lib/que/scheduler.rb

@@ -1,3 +1,5 @@
+# typed: true
+
 require "que/scheduler/version"
 require "que/scheduler/db_support"
 require "que/scheduler/configuration"

data/lib/que-scheduler.rb

@@ -1 +1,3 @@
+# typed: true
+
 require "que/scheduler"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: que-scheduler
 version: !ruby/object:Gem::Version
-  version: 7.0.1
+  version: 7.2.0
 platform: ruby
 authors:
 - Harry Lascelles
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-21 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -84,6 +84,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -452,6 +466,7 @@ files:
 - lib/que/scheduler/state_checks.rb
 - lib/que/scheduler/time_zone.rb
 - lib/que/scheduler/to_enqueue.rb
+- lib/que/scheduler/types.rb
 - lib/que/scheduler/version.rb
 homepage: https://github.com/hlascelles/que-scheduler
 licenses: