job-iteration 1.17.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 657313f73892dc576ba595499f00d97a211936bdbec570db64e72c7431aa0a11
-  data.tar.gz: f12f068e6a83efc6fd702e4c5068c8b428587ec2b94eb9087c00e7141f689dee
+  metadata.gz: 4eeecd22600aa17ab6d0cee8d7ce0b5df6cd7bc984facb2a2b16025d7432881f
+  data.tar.gz: b08981a5c35feba0d9077dffd45147ea16838c87c2fc2c3de2c4798b90c3ce26
 SHA512:
-  metadata.gz: dd60d3982a00af5e2193739c0e9e62adee8e08414628fa19a9f1d6d85f4ad1c5d9cbbd3b5a931b695fccdd50d60a5592a420a04c6eaa446f3b5cbf2e53beadb9
-  data.tar.gz: 0e4c271a6a72a11bafcb5bb3fd362f88c2a90ee8b1ddb622c7053c0b0a8eed6b78b2420db0a28d448d7ce12026ad6313d409441567b30acc8e46a46a3243cfdc
+  metadata.gz: 57e13085c92355e548c35a96aa8506ab084444dbc8c83857dc1b7e234dc91783cb517613be43d90a9a03ee93f668cecc890a6bb4cfac1dcc835431004f565062
+  data.tar.gz: 338fef9982f317132a3f46681c015d9790d98a688e773ad34519a1821acf35e44ea6c4fda2f8b2b7b0e863a533d97aecde2426f478d8329a1129a59e2ad9b8eb

data/CHANGELOG.md

@@ -16,6 +16,12 @@ nil
 
 nil
 
+## v1.18.0 (Nov 6, 2026)
+
+### Features
+
+- [760](https://github.com/Shopify/job-iteration/pull/760) - Add the `serialize_cursor` and `deserialize_cursor` hooks, which a job overrides to decide how its cursor is stored in the job payload and rebuilt when it resumes; for example through `ActiveJob::Arguments`, so a `Time` or a custom id class survives the trip through JSON. The defaults keep the cursor as it is.
+
 ## v1.17.0 (Oct 27, 2026)
 
 ### Features

data/lib/job-iteration/iteration.rb

@@ -94,7 +94,7 @@ module JobIteration
 
     def serialize # @private
       super.merge(
-        "cursor_position" => cursor_position,
+        "cursor_position" => serialize_cursor(cursor_position),
         "times_interrupted" => times_interrupted,
         "total_time" => total_time,
       )
@@ -102,11 +102,42 @@ module JobIteration
 
     def deserialize(job_data) # @private
       super
-      self.cursor_position = job_data["cursor_position"]
+      self.cursor_position = deserialize_cursor(job_data["cursor_position"])
       self.times_interrupted = Integer(job_data["times_interrupted"] || 0)
       self.total_time = Float(job_data["total_time"] || 0.0)
     end
 
+    # Converts the cursor into the form stored in the job payload when the job is interrupted. The queue
+    # backend serializes that payload, typically as JSON, so by default a cursor has to be made of values
+    # JSON round-trips as the same objects: Strings, Integers, Floats, Arrays, Hashes, true, false, or nil.
+    #
+    # Override this method together with #deserialize_cursor to persist cursors of other types. Active Job's
+    # argument serialization is a natural choice: it already handles Time, Date, BigDecimal, Symbol and any
+    # class with an ActiveJob::Serializers::ObjectSerializer, and leaves JSON-native values untouched.
+    #
+    #   def serialize_cursor(cursor)
+    #     ActiveJob::Arguments.serialize([cursor]).first
+    #   end
+    #
+    #   def deserialize_cursor(cursor)
+    #     ActiveJob::Arguments.deserialize([cursor]).first
+    #   end
+    #
+    # @param cursor [Object] the cursor the enumerator yielded last
+    # @return [Object] what to store in the job payload
+    def serialize_cursor(cursor)
+      cursor
+    end
+
+    # Rebuilds the cursor from the form #serialize_cursor stored in the job payload, before it is passed to
+    # #build_enumerator as +cursor:+. The default returns it unchanged.
+    #
+    # @param cursor [Object] the stored cursor, as the queue backend deserialized it
+    # @return [Object] the cursor to resume from
+    def deserialize_cursor(cursor)
+      cursor
+    end
+
     def perform(...) # @private
       interruptible_perform(...)
 
@@ -184,7 +215,7 @@ module JobIteration
 
       enumerator.each do |object_from_enumerator, cursor_from_enumerator|
         # Deferred until 2.0.0
-        # assert_valid_cursor!(cursor_from_enumerator)
+        # assert_valid_cursor!(serialize_cursor(cursor_from_enumerator))
 
         tags = instrumentation_tags.merge(cursor_position: cursor_from_enumerator)
         ActiveSupport::Notifications.instrument("each_iteration.iteration", tags) do
@@ -312,12 +343,14 @@ module JobIteration
 
     # The adapter must be able to serialize and deserialize the cursor back into an equivalent object.
     # https://github.com/mperham/sidekiq/wiki/Best-Practices#1-make-your-job-parameters-small-and-simple
+    # Validated on the result of #serialize_cursor, which is what reaches the adapter.
     def assert_valid_cursor!(cursor)
       return if serializable?(cursor)
 
       raise CursorError.new(
         "Cursor must be composed of objects capable of built-in (de)serialization: " \
-          "Strings, Integers, Floats, Arrays, Hashes, true, false, or nil.",
+          "Strings, Integers, Floats, Arrays, Hashes, true, false, or nil. " \
+          "Override #serialize_cursor and #deserialize_cursor to persist other types.",
         cursor: cursor,
       )
     end

data/lib/job-iteration/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JobIteration
-  VERSION = "1.17.0"
+  VERSION = "1.18.0"
 end

data/lib/tapioca/dsl/compilers/job_iteration.rb

@@ -23,7 +23,7 @@ module Tapioca
 
         sig { override.void }
         def decorate
-          return unless constant.instance_methods(false).include?(:build_enumerator)
+          return unless constant.method_defined?(:build_enumerator, false)
 
           root.create_path(constant) do |job|
             method = constant.instance_method(:build_enumerator)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: job-iteration
 version: !ruby/object:Gem::Version
-  version: 1.17.0
+  version: 1.18.0
 platform: ruby
 authors:
 - Shopify