zizq 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77ab05fe491ab193d0c5c3b1106aac3e5effe7b1dcb7e0117b70e0e05652426b
-  data.tar.gz: 05f26bd94ca2127e7e859212348e063bc9354d866945ae500514dcfbcfe57828
+  metadata.gz: de36f4f8204a5d5b0c64e77b78249ed34ea6c667ceb6b03dbdca2a291cb0f330
+  data.tar.gz: 7cbb62aac1788627bb1047b474e5ca915c5dca059bc6f00be7a2f5adca798a7a
 SHA512:
-  metadata.gz: f12216566271dbd68395eeada829ffd68bfd853e86c1a8e598dbac6c3c7f5d8af5008ee084a9a7ebaef99d74144c6d05995fe32e01f0349b47dac6beb082c702
-  data.tar.gz: 505804d9abd2c1cff8a749bd9cb6ad3d224d09545648a314b54a3094a96f2d18cb18257661833479bf1b59959d6d300730e2cbcbb70572afee5195bb538d8460
+  metadata.gz: 95b80cec6e0bb1704bd1244b37c4434b5d5467139e35c61bae39f342825a3e136a413aa55c0a0b7de379024bcdee3486e08cb211062a9d406011093a68de2899
+  data.tar.gz: '09952b2563e139e9987473b53524ea993f1c803ea0320082c166132053919f3401cad65c8dc063923837c3b1fe8a505e3e27dcd9ce6a20724313c1d6f82c00e3'

data/lib/zizq/active_job_config.rb

@@ -9,8 +9,9 @@ require_relative "job_config"
 module Zizq
   # Zizq configuration DSL for ActiveJob classes.
   #
-  # Extend this module in an ActiveJob subclass to gain access to Zizq
-  # features like unique jobs, backoff, and retention:
+  # Extend this module in an ActiveJob subclass to allow enqueueing jobs via
+  # `Zizq.enqueue` and to gain access to Zizq features like unique jobs,
+  # backoff, and retention:
   #
   #   class SendEmailJob < ApplicationJob
   #     extend Zizq::ActiveJobConfig
@@ -36,17 +37,28 @@ module Zizq
     # @rbs!
     #   # ActiveJob::Base.new — invisible to steep without this.
     #   def new: (*untyped, **untyped) -> untyped
+    #
+    #   # ActiveJob::Base.queue_name — invisible to steep without this.
+    #   def queue_name: () -> String?
+
+    # Use ActiveJob's `queue_name` as the default queue, falling back to
+    # any explicit `zizq_queue` setting, then "default".
+    def zizq_queue(name = nil) #: (?String?) -> String
+      if name
+        super
+      else
+        @zizq_queue || queue_name || "default"
+      end
+    end
 
-    # Serialize arguments using ActiveJob's serialization format.
+    # Serialize using ActiveJob's own format.
     #
     # Creates a temporary ActiveJob instance to produce the canonical
-    # serialized form, including `_aj_ruby2_keywords` markers for kwargs.
-    # This ensures unique key generation uses the same format as the
-    # enqueued payload.
-    #
-    # This is needed so that unique job keys can be correctly generated.
-    def zizq_serialize(*args, **kwargs) #: (*untyped, **untyped) -> Array[untyped]
-      new(*args, **kwargs).serialize["arguments"]
+    # serialized form. Returns the full serialized hash (including
+    # `job_class`, `arguments`, `queue_name`, etc.) so that the payload
+    # stored in Zizq matches what `ActiveJob::Base.execute` expects.
+    def zizq_serialize(*args, **kwargs) #: (*untyped, **untyped) -> Hash[String, untyped]
+      new(*args, **kwargs).serialize
     end
 
     # Deserialization is handled by ActiveJob::Base.execute on the worker
@@ -56,6 +68,15 @@ module Zizq
         "ActiveJob handles deserialization via ActiveJob::Base.execute"
     end
 
+    # Override unique key generation to hash only the arguments portion
+    # of the serialized payload. The full payload contains volatile fields
+    # (job_id, enqueued_at, etc.) that change per instance.
+    def zizq_unique_key(*args, **kwargs) #: (*untyped, **untyped) -> String
+      arguments = new(*args, **kwargs).serialize["arguments"]
+      payload = normalize_payload(arguments)
+      "#{name}:#{Digest::SHA256.hexdigest(JSON.generate(payload))}"
+    end
+
     # Generate a jq expression that exactly matches payloads with the given
     # arguments.
     #
@@ -65,8 +86,8 @@ module Zizq
     #
     #   .arguments == ["a","b",{"example":true,"_aj_ruby2_keywords":["example"]}]
     def zizq_payload_filter(*args, **kwargs) #: (*untyped, **untyped) -> String
-      payload = zizq_serialize(*args, **kwargs)
-      ".arguments == #{JSON.generate(payload)}"
+      arguments = zizq_serialize(*args, **kwargs)["arguments"]
+      ".arguments == #{JSON.generate(arguments)}"
     end
 
     # Generate a jq expression that matches jobs whose positional args
@@ -85,27 +106,27 @@ module Zizq
     #   (.arguments[-1] | has("_aj_ruby2_keywords")) and
     #   (.arguments[-1] | contains({"example":true}))
     def zizq_payload_subset_filter(*args, **kwargs) #: (*untyped, **untyped) -> String
-      payload = zizq_serialize(*args, **kwargs)
+      arguments = zizq_serialize(*args, **kwargs)["arguments"]
 
       # ActiveJob flattens arguments into a single array, but marks kwargs with
       # "_aj_ruby2_keywords" => ["key1", "key2", ...] in the last element of
       # the array where kwargs are present. We need to detect this to generate
       # a suitable expression.
       serialized_args, serialized_kwargs =
-        if payload.size > 0
+        if arguments.size > 0
           # See what the last argument looks like. It might be kwargs.
-          maybe_kwargs = payload.pop
+          maybe_kwargs = arguments.pop
 
           # If it's got "_aj_ruby2_keywords" then it is kwargs.
           if maybe_kwargs.is_a?(Hash) && maybe_kwargs["_aj_ruby2_keywords"]
             # We only want the actual kwargs, not the marker.
-            [payload, maybe_kwargs.except("_aj_ruby2_keywords")]
+            [arguments, maybe_kwargs.except("_aj_ruby2_keywords")]
           else
             # It wasn't kwargs, so put it back.
-            [payload.push(maybe_kwargs), nil]
+            [arguments.push(maybe_kwargs), nil]
           end
         else
-          [payload, nil]
+          [arguments, nil]
         end
 
       parts = [] #: Array[String]

data/lib/zizq/client.rb

@@ -249,6 +249,37 @@ module Zizq
       Resources::JobPage.new(self, data)
     end
 
+    # Count jobs matching the given filters.
+    #
+    # Accepts the same filter arguments as `list_jobs` (minus pagination).
+    # Returns the count as an integer.
+    #
+    # @rbs id: (String | Array[String])?
+    # @rbs status: (String | Array[String])?
+    # @rbs queue: (String | Array[String])?
+    # @rbs type: (String | Array[String])?
+    # @rbs filter: String?
+    # @rbs return: Integer
+    def count_jobs(id: nil,
+                   status: nil,
+                   queue: nil,
+                   type: nil,
+                   filter: nil)
+      options = { id:, status:, queue:, type:, filter: }.compact #: Hash[Symbol, untyped]
+
+      multi_keys = %i[id status queue type]
+      params = build_where_params(options, multi_keys:)
+
+      # An empty filter ([] or "") matches nothing — short-circuit.
+      multi_keys.each do |key|
+        return 0 if params[key] == ""
+      end
+
+      response = get("/jobs/count", params:)
+      data = handle_response!(response, expected: 200)
+      data.fetch("count")
+    end
+
     # Delete a single job by ID.
     #
     # @rbs id: String

data/lib/zizq/query.rb

@@ -283,6 +283,32 @@ module Zizq
       limit(2).to_a.size == 1
     end
 
+    # Count matching jobs via the server-side count endpoint.
+    #
+    # Without a block or argument, uses `GET /jobs/count` for an efficient
+    # server-side count. When a limit is set, caps the result locally with
+    # `[total, limit].min`.
+    #
+    # With a block or argument, falls back to Enumerable (iterates and counts
+    # matching jobs).
+    #
+    # @rbs *args: untyped
+    # @rbs &block: ?(Resources::Job) -> bool
+    # @rbs return: Integer
+    def count(*args, &block)
+      return super if block || !args.empty?
+
+      total = Zizq.client.count_jobs(
+        id: @id,
+        queue: @queue,
+        type: @type,
+        status: @status,
+        filter: @jq_filter,
+      )
+
+      @limit ? [total, @limit].min : total
+    end
+
     # Iterate over matching jobs in reverse order.
     #
     # Optimised: pushes the reverse ordering to the server instead of

data/lib/zizq/version.rb

@@ -5,5 +5,5 @@
 # frozen_string_literal: true
 
 module Zizq
-  VERSION = "0.1.0" #: String
+  VERSION = "0.2.1" #: String
 end

data/lib/zizq.rb

@@ -253,8 +253,8 @@ module Zizq
     # @rbs &block: ?(EnqueueRequest) -> void
     # @rbs return: EnqueueRequest
     def build_enqueue_request(job_class, *args, **kwargs, &block)
-      unless job_class.is_a?(Class) && job_class < Zizq::Job
-        raise ArgumentError, "#{job_class.inspect} must include Zizq::Job"
+      unless job_class.is_a?(Class) && job_class.is_a?(Zizq::JobConfig)
+        raise ArgumentError, "#{job_class.inspect} must include Zizq::Job or extend Zizq::ActiveJobConfig"
       end
 
       zizq_job_class = job_class #: Zizq::job_class

data/sig/generated/zizq/active_job_config.rbs

@@ -3,8 +3,9 @@
 module Zizq
   # Zizq configuration DSL for ActiveJob classes.
   #
-  # Extend this module in an ActiveJob subclass to gain access to Zizq
-  # features like unique jobs, backoff, and retention:
+  # Extend this module in an ActiveJob subclass to allow enqueueing jobs via
+  # `Zizq.enqueue` and to gain access to Zizq features like unique jobs,
+  # backoff, and retention:
   #
   #   class SendEmailJob < ApplicationJob
   #     extend Zizq::ActiveJobConfig
@@ -30,20 +31,30 @@ module Zizq
     # ActiveJob::Base.new — invisible to steep without this.
     def new: (*untyped, **untyped) -> untyped
 
-    # Serialize arguments using ActiveJob's serialization format.
+    # ActiveJob::Base.queue_name — invisible to steep without this.
+    def queue_name: () -> String?
+
+    # Use ActiveJob's `queue_name` as the default queue, falling back to
+    # any explicit `zizq_queue` setting, then "default".
+    def zizq_queue: (?untyped name) -> untyped
+
+    # Serialize using ActiveJob's own format.
     #
     # Creates a temporary ActiveJob instance to produce the canonical
-    # serialized form, including `_aj_ruby2_keywords` markers for kwargs.
-    # This ensures unique key generation uses the same format as the
-    # enqueued payload.
-    #
-    # This is needed so that unique job keys can be correctly generated.
+    # serialized form. Returns the full serialized hash (including
+    # `job_class`, `arguments`, `queue_name`, etc.) so that the payload
+    # stored in Zizq matches what `ActiveJob::Base.execute` expects.
     def zizq_serialize: (*untyped args, **untyped kwargs) -> untyped
 
     # Deserialization is handled by ActiveJob::Base.execute on the worker
     # side. This method is not used in the ActiveJob dispatch path.
     def zizq_deserialize: (untyped _payload) -> untyped
 
+    # Override unique key generation to hash only the arguments portion
+    # of the serialized payload. The full payload contains volatile fields
+    # (job_id, enqueued_at, etc.) that change per instance.
+    def zizq_unique_key: (*untyped args, **untyped kwargs) -> untyped
+
     # Generate a jq expression that exactly matches payloads with the given
     # arguments.
     #

data/sig/generated/zizq/client.rbs

@@ -108,6 +108,19 @@ module Zizq
     # @rbs return: Resources::JobPage
     def list_jobs: (?id: (String | Array[String])?, ?status: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?filter: String?, ?from: String?, ?order: Zizq::sort_direction?, ?limit: Integer?) -> Resources::JobPage
 
+    # Count jobs matching the given filters.
+    #
+    # Accepts the same filter arguments as `list_jobs` (minus pagination).
+    # Returns the count as an integer.
+    #
+    # @rbs id: (String | Array[String])?
+    # @rbs status: (String | Array[String])?
+    # @rbs queue: (String | Array[String])?
+    # @rbs type: (String | Array[String])?
+    # @rbs filter: String?
+    # @rbs return: Integer
+    def count_jobs: (?id: (String | Array[String])?, ?status: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?filter: String?) -> Integer
+
     # Delete a single job by ID.
     #
     # @rbs id: String

data/sig/generated/zizq/query.rbs

@@ -208,6 +208,20 @@ module Zizq
     # @rbs return: bool
     def one?: () ?{ (Resources::Job) -> bool } -> bool
 
+    # Count matching jobs via the server-side count endpoint.
+    #
+    # Without a block or argument, uses `GET /jobs/count` for an efficient
+    # server-side count. When a limit is set, caps the result locally with
+    # `[total, limit].min`.
+    #
+    # With a block or argument, falls back to Enumerable (iterates and counts
+    # matching jobs).
+    #
+    # @rbs *args: untyped
+    # @rbs &block: ?(Resources::Job) -> bool
+    # @rbs return: Integer
+    def count: (*untyped args) ?{ (Resources::Job) -> bool } -> Integer
+
     # Iterate over matching jobs in reverse order.
     #
     # Optimised: pushes the reverse ordering to the server instead of

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zizq
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Chris Corbyn <chris@zizq.io>
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-25 00:00:00.000000000 Z
+date: 2026-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http