zizq 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16999267b593c3fbe71930e3e9d57754e8fd2fea5b336dbeef281e26aea80cb4
-  data.tar.gz: da78dd13533f26d22ad896435d62e0e6348ff4978047f96ee1dede9e98c06cc0
+  metadata.gz: 424b67e8dbba3c82506c24ed18cbaa9fc87af3febe9e079ef458f705e9299fdd
+  data.tar.gz: 53bc5f8b3aefbdddc69e2471e6efbd2ba7c84016cb8eb63ff16bc463107991fe
 SHA512:
-  metadata.gz: 24fa716817d30de27b041c693ea3275f24ad8eec6979d7b58b271e6d4868329a87a3a7a2402068699d21c7fcb96c19061609a77df2cc93034bbd4d355fb2277f
-  data.tar.gz: 23d3005105f3ce7140d2d644da28b2af508457c71e30e8df9754db44afa1ca3887b69c4f17fc950c65e46ea87bb2ce9bb8dda534a79321fd32a0138d5da9a6f9
+  metadata.gz: 10f7ab3fe215f04eff3c1753826734c609454c93f9c30c586dd0f38f49ac563d23dcb47317c12e7c00cde3dff558cb124ce0ae25a3c801b9b71a85ce806d96e9
+  data.tar.gz: 422601a65e9862a73360e036a0e5f44ac36bdcaa04a3fe585567e4fefaf9b73e4fa4736ac3fe9d0cc552173bcd9c47fef98cbc1a6935ef3a64870a839a5a13b9

data/README.md

@@ -33,13 +33,13 @@ API.
 Add it to your application's `Gemfile`:
 
 ```ruby
-gem 'zizq', '~> 0.4.0'
+gem 'zizq', '~> 0.5.0'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.4.0
+$ gem install zizq -v 0.5.0
 ```
 
 Ruby **3.2.8 or newer** is required. Client and server share version

data/lib/zizq/client.rb

@@ -238,11 +238,17 @@ module Zizq
     # The `filter` parameter accepts a jq expression for filtering jobs by
     # payload content (e.g. `.user_id == 42`).
     #
+    # Range filters (`priority`, `attempts`, `ready_at`) accept exact values or
+    # inclusive ranges.
+    #
     # @rbs id: (String | Array[String])?
     # @rbs status: (String | Array[String])?
     # @rbs queue: (String | Array[String])?
     # @rbs type: (String | Array[String])?
     # @rbs filter: String?
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs attempts: (Integer | Range[Integer?])?
     # @rbs from: String?
     # @rbs order: Zizq::sort_direction?
     # @rbs limit: Integer?
@@ -252,10 +258,25 @@ module Zizq
                   queue: nil,
                   type: nil,
                   filter: nil,
+                  priority: nil,
+                  ready_at: nil,
+                  attempts: nil,
                   from: nil,
                   order: nil,
                   limit: nil)
-      options = { id:, status:, queue:, type:, filter:, from:, order:, limit: }.compact #: Hash[Symbol, untyped]
+      options = {
+        id:,
+        status:,
+        queue:,
+        type:,
+        filter:,
+        priority: encode_range(priority),
+        ready_at: encode_range(ready_at) { |v| (v.to_f * 1000).to_i },
+        attempts: encode_range(attempts),
+        from:,
+        order:,
+        limit:,
+      }.compact #: Hash[Symbol, untyped]
 
       multi_keys = %i[id status queue type]
       params = build_where_params(options, multi_keys:)
@@ -280,13 +301,28 @@ module Zizq
     # @rbs queue: (String | Array[String])?
     # @rbs type: (String | Array[String])?
     # @rbs filter: String?
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs attempts: (Integer | Range[Integer?])?
     # @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]
+                   filter: nil,
+                   priority: nil,
+                   ready_at: nil,
+                   attempts: nil)
+      options = {
+        id:,
+        status:,
+        queue:,
+        type:,
+        filter:,
+        priority: encode_range(priority),
+        ready_at: encode_range(ready_at) { |v| (v.to_f * 1000).to_i },
+        attempts: encode_range(attempts),
+      }.compact #: Hash[Symbol, untyped]
 
       multi_keys = %i[id status queue type]
       params = build_where_params(options, multi_keys:)
@@ -380,8 +416,12 @@ module Zizq
                    backoff: UNCHANGED,
                    retention: UNCHANGED)
       body = build_set_body(
-        queue:, priority:, ready_at:,
-        retry_limit:, backoff:, retention:
+        queue:,
+        priority:,
+        ready_at:,
+        retry_limit:,
+        backoff:,
+        retention:
       )
       response = patch("/jobs/#{enc(id)}", body)
       data = handle_response!(response, expected: 200)
@@ -926,9 +966,62 @@ module Zizq
     # @rbs queue: (String | Array[String])?
     # @rbs type: (String | Array[String])?
     # @rbs filter: String?
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs attempts: (Integer | Range[Integer?])?
     # @rbs return: Hash[Symbol, untyped]
-    def validate_where(id: nil, status: nil, queue: nil, type: nil, filter: nil)
-      { id:, status:, queue:, type:, filter: }.compact
+    def validate_where(id: nil,
+                       status: nil,
+                       queue: nil,
+                       type: nil,
+                       filter: nil,
+                       priority: nil,
+                       ready_at: nil,
+                       attempts: nil)
+      {
+        id:,
+        status:,
+        queue:,
+        type:,
+        filter:,
+        priority: encode_range(priority),
+        ready_at: encode_range(ready_at) { |v| (v.to_f * 1000).to_i },
+        attempts: encode_range(attempts),
+      }.compact
+    end
+
+    # Encode an Integer or Range filter into the server's query format.
+    #
+    # Accepted shapes:
+    #
+    # - `nil` -> `nil` (no filter sent)
+    # - `Integer` -> `"N"` (single value)
+    # - `(a..b)` -> `"A..B"` (inclusive both ends)
+    # - `(a..)` -> `"A.."` (lower bound only)
+    # - `(..b)` -> `"..B"` (upper bound only)
+    #
+    # Exclusive ranges (`a...b`, `a...`, `...b`) raise `ArgumentError` — the
+    # server only supports inclusive bounds. A bound transformation block can
+    # convert values before formatting (e.g. seconds -> ms for `ready_at`).
+    #
+    # @rbs value: untyped
+    # @rbs &block: ?(untyped) -> Integer
+    # @rbs return: String?
+    def encode_range(value, &block)
+      block ||= ->(v) { v.to_i }
+
+      case value
+      when nil
+        nil
+      when Range
+        if value.exclude_end?
+          raise ArgumentError,
+            "exclusive ranges are not supported by the server; use an inclusive range (a..b) instead"
+        end
+        "#{value.begin&.then(&block)}..#{value.end&.then(&block)}"
+      else
+        block.call(value).to_s
+      end
     end
 
     # Validate set parameters via keyword args (rejects unknown keys) and

data/lib/zizq/query.rb

@@ -55,6 +55,9 @@ module Zizq
     # @rbs type: (String | Array[String])?
     # @rbs status: (String | Array[String])?
     # @rbs jq_filter: String?
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs attempts: (Integer | Range[Integer?])?
     # @rbs order: Zizq::sort_direction?
     # @rbs limit: Integer?
     # @rbs page_size: Integer?
@@ -64,6 +67,9 @@ module Zizq
                    type: nil,
                    status: nil,
                    jq_filter: nil,
+                   priority: nil,
+                   ready_at: nil,
+                   attempts: nil,
                    order: nil,
                    limit: nil,
                    page_size: nil)
@@ -72,6 +78,9 @@ module Zizq
       @type = type
       @status = status
       @jq_filter = jq_filter
+      @priority = priority
+      @ready_at = ready_at
+      @attempts = attempts
       @order = order
       @limit = limit
       @page_size = page_size
@@ -153,6 +162,62 @@ module Zizq
       rebuild(status: Array(@status) + Array(status))
     end
 
+    # Filter by priority range (replaces any existing priority filter).
+    #
+    # Accepts an Integer (exact match) or an inclusive Range. Lower numbers
+    # are higher priority. Exclusive ranges (e.g. `0...100`) raise
+    # `ArgumentError` — the server only supports inclusive bounds.
+    #
+    # Examples:
+    #
+    #   .by_priority(50)        # exactly priority 50
+    #   .by_priority(0..100)    # between 0 and 100 inclusive
+    #   .by_priority(100..)     # 100 or greater
+    #   .by_priority(..100)     # 100 or less
+    #
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs return: Query
+    def by_priority(priority)
+      rebuild(priority:)
+    end
+
+    # Filter by `ready_at` range (replaces any existing `ready_at` filter).
+    #
+    # Accepts a value (`Time`, `Numeric`, anything that responds to `to_f`)
+    # for an exact match, or an inclusive Range. Values are interpreted as
+    # fractional seconds on the Ruby side and converted to milliseconds for
+    # the server. Exclusive ranges raise `ArgumentError`.
+    #
+    # Examples:
+    #
+    #   .by_ready_at(Time.now..)         # ready to run now or later
+    #   .by_ready_at(..Time.now)         # was ready to run by now
+    #   .by_ready_at(t1..t2)             # ready between t1 and t2
+    #
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs return: Query
+    def by_ready_at(ready_at)
+      rebuild(ready_at:)
+    end
+
+    # Filter by `attempts` range (replaces any existing `attempts` filter).
+    #
+    # Accepts an Integer (exact match) or an inclusive Range. `attempts` is
+    # the number of times the job has failed. Exclusive ranges raise
+    # `ArgumentError`.
+    #
+    # Examples:
+    #
+    #   .by_attempts(0)         # never failed
+    #   .by_attempts(1..)       # has failed at least once
+    #   .by_attempts(1..3)      # has failed 1, 2, or 3 times
+    #
+    # @rbs attempts: (Integer | Range[Integer?])?
+    # @rbs return: Query
+    def by_attempts(attempts)
+      rebuild(attempts:)
+    end
+
     # Filter by job class and exact arguments.
     #
     # The job class must include `Zizq::Job` or for Active Job classes must
@@ -304,6 +369,9 @@ module Zizq
         type: @type,
         status: @status,
         filter: @jq_filter,
+        priority: @priority,
+        ready_at: @ready_at,
+        attempts: @attempts,
       )
 
       @limit ? [total, @limit].min : total
@@ -421,6 +489,9 @@ module Zizq
           type: @type,
           status: @status,
           filter: @jq_filter,
+          priority: @priority,
+          ready_at: @ready_at,
+          attempts: @attempts,
           limit: [@page_size, @limit, (@page_size || @limit) && MAX_PAGE_SIZE].compact.min,
           order: @order,
         )
@@ -470,6 +541,9 @@ module Zizq
         type: @type,
         status: @status,
         filter: @jq_filter,
+        priority: @priority,
+        ready_at: @ready_at,
+        attempts: @attempts,
       }
 
       apply = {
@@ -527,6 +601,9 @@ module Zizq
         type: @type,
         status: @status,
         filter: @jq_filter,
+        priority: @priority,
+        ready_at: @ready_at,
+        attempts: @attempts,
       }
 
       if @limit || @page_size
@@ -564,6 +641,9 @@ module Zizq
                 type: @type,
                 status: @status,
                 jq_filter: @jq_filter,
+                priority: @priority,
+                ready_at: @ready_at,
+                attempts: @attempts,
                 order: @order,
                 limit: @limit,
                 page_size: @page_size)
@@ -573,6 +653,9 @@ module Zizq
         type:,
         status:,
         jq_filter:,
+        priority:,
+        ready_at:,
+        attempts:,
         limit:,
         order:,
         page_size:,

data/lib/zizq/version.rb

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

data/sig/generated/zizq/client.rbs

@@ -105,16 +105,22 @@ module Zizq
     # The `filter` parameter accepts a jq expression for filtering jobs by
     # payload content (e.g. `.user_id == 42`).
     #
+    # Range filters (`priority`, `attempts`, `ready_at`) accept exact values or
+    # inclusive ranges.
+    #
     # @rbs id: (String | Array[String])?
     # @rbs status: (String | Array[String])?
     # @rbs queue: (String | Array[String])?
     # @rbs type: (String | Array[String])?
     # @rbs filter: String?
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs attempts: (Integer | Range[Integer?])?
     # @rbs from: String?
     # @rbs order: Zizq::sort_direction?
     # @rbs limit: Integer?
     # @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
+    def list_jobs: (?id: (String | Array[String])?, ?status: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?filter: String?, ?priority: (Integer | Range[Integer?])?, ?ready_at: (Zizq::to_f | Range[Zizq::to_f?])?, ?attempts: (Integer | Range[Integer?])?, ?from: String?, ?order: Zizq::sort_direction?, ?limit: Integer?) -> Resources::JobPage
 
     # Count jobs matching the given filters.
     #
@@ -126,8 +132,11 @@ module Zizq
     # @rbs queue: (String | Array[String])?
     # @rbs type: (String | Array[String])?
     # @rbs filter: String?
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs attempts: (Integer | Range[Integer?])?
     # @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
+    def count_jobs: (?id: (String | Array[String])?, ?status: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?filter: String?, ?priority: (Integer | Range[Integer?])?, ?ready_at: (Zizq::to_f | Range[Zizq::to_f?])?, ?attempts: (Integer | Range[Integer?])?) -> Integer
 
     # Delete a single job by ID.
     #
@@ -492,8 +501,30 @@ module Zizq
     # @rbs queue: (String | Array[String])?
     # @rbs type: (String | Array[String])?
     # @rbs filter: String?
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs attempts: (Integer | Range[Integer?])?
     # @rbs return: Hash[Symbol, untyped]
-    def validate_where: (?id: (String | Array[String])?, ?status: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?filter: String?) -> Hash[Symbol, untyped]
+    def validate_where: (?id: (String | Array[String])?, ?status: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?filter: String?, ?priority: (Integer | Range[Integer?])?, ?ready_at: (Zizq::to_f | Range[Zizq::to_f?])?, ?attempts: (Integer | Range[Integer?])?) -> Hash[Symbol, untyped]
+
+    # Encode an Integer or Range filter into the server's query format.
+    #
+    # Accepted shapes:
+    #
+    # - `nil` -> `nil` (no filter sent)
+    # - `Integer` -> `"N"` (single value)
+    # - `(a..b)` -> `"A..B"` (inclusive both ends)
+    # - `(a..)` -> `"A.."` (lower bound only)
+    # - `(..b)` -> `"..B"` (upper bound only)
+    #
+    # Exclusive ranges (`a...b`, `a...`, `...b`) raise `ArgumentError` — the
+    # server only supports inclusive bounds. A bound transformation block can
+    # convert values before formatting (e.g. seconds -> ms for `ready_at`).
+    #
+    # @rbs value: untyped
+    # @rbs &block: ?(untyped) -> Integer
+    # @rbs return: String?
+    def encode_range: (untyped value) ?{ (untyped) -> Integer } -> String?
 
     # Validate set parameters via keyword args (rejects unknown keys) and
     # build the JSON body. Used by `update_all_jobs`.

data/sig/generated/zizq/query.rbs

@@ -46,11 +46,14 @@ module Zizq
     # @rbs type: (String | Array[String])?
     # @rbs status: (String | Array[String])?
     # @rbs jq_filter: String?
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs attempts: (Integer | Range[Integer?])?
     # @rbs order: Zizq::sort_direction?
     # @rbs limit: Integer?
     # @rbs page_size: Integer?
     # @rbs return: void
-    def initialize: (?id: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?status: (String | Array[String])?, ?jq_filter: String?, ?order: Zizq::sort_direction?, ?limit: Integer?, ?page_size: Integer?) -> void
+    def initialize: (?id: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?status: (String | Array[String])?, ?jq_filter: String?, ?priority: (Integer | Range[Integer?])?, ?ready_at: (Zizq::to_f | Range[Zizq::to_f?])?, ?attempts: (Integer | Range[Integer?])?, ?order: Zizq::sort_direction?, ?limit: Integer?, ?page_size: Integer?) -> void
 
     # Set the page size for paginated iteration.
     #
@@ -110,6 +113,56 @@ module Zizq
     # @rbs return: Query
     def add_status: (String | Array[String] status) -> Query
 
+    # Filter by priority range (replaces any existing priority filter).
+    #
+    # Accepts an Integer (exact match) or an inclusive Range. Lower numbers
+    # are higher priority. Exclusive ranges (e.g. `0...100`) raise
+    # `ArgumentError` — the server only supports inclusive bounds.
+    #
+    # Examples:
+    #
+    #   .by_priority(50)        # exactly priority 50
+    #   .by_priority(0..100)    # between 0 and 100 inclusive
+    #   .by_priority(100..)     # 100 or greater
+    #   .by_priority(..100)     # 100 or less
+    #
+    # @rbs priority: (Integer | Range[Integer?])?
+    # @rbs return: Query
+    def by_priority: ((Integer | Range[Integer?])? priority) -> Query
+
+    # Filter by `ready_at` range (replaces any existing `ready_at` filter).
+    #
+    # Accepts a value (`Time`, `Numeric`, anything that responds to `to_f`)
+    # for an exact match, or an inclusive Range. Values are interpreted as
+    # fractional seconds on the Ruby side and converted to milliseconds for
+    # the server. Exclusive ranges raise `ArgumentError`.
+    #
+    # Examples:
+    #
+    #   .by_ready_at(Time.now..)         # ready to run now or later
+    #   .by_ready_at(..Time.now)         # was ready to run by now
+    #   .by_ready_at(t1..t2)             # ready between t1 and t2
+    #
+    # @rbs ready_at: (Zizq::to_f | Range[Zizq::to_f?])?
+    # @rbs return: Query
+    def by_ready_at: ((Zizq::to_f | Range[Zizq::to_f?])? ready_at) -> Query
+
+    # Filter by `attempts` range (replaces any existing `attempts` filter).
+    #
+    # Accepts an Integer (exact match) or an inclusive Range. `attempts` is
+    # the number of times the job has failed. Exclusive ranges raise
+    # `ArgumentError`.
+    #
+    # Examples:
+    #
+    #   .by_attempts(0)         # never failed
+    #   .by_attempts(1..)       # has failed at least once
+    #   .by_attempts(1..3)      # has failed 1, 2, or 3 times
+    #
+    # @rbs attempts: (Integer | Range[Integer?])?
+    # @rbs return: Query
+    def by_attempts: ((Integer | Range[Integer?])? attempts) -> Query
+
     # Filter by job class and exact arguments.
     #
     # The job class must include `Zizq::Job` or for Active Job classes must
@@ -332,7 +385,7 @@ module Zizq
     # Build a new Query with the given overrides, preserving all other fields.
     #
     # @rbs return: Query
-    def rebuild: (?id: untyped, ?queue: untyped, ?type: untyped, ?status: untyped, ?jq_filter: untyped, ?order: untyped, ?limit: untyped, ?page_size: untyped) -> Query
+    def rebuild: (?id: untyped, ?queue: untyped, ?type: untyped, ?status: untyped, ?jq_filter: untyped, ?priority: untyped, ?ready_at: untyped, ?attempts: untyped, ?order: untyped, ?limit: untyped, ?page_size: untyped) -> Query
 
     # @rbs job_class: untyped
     # @rbs return: void

data/sig/generated/zizq/resources/page.rbs

@@ -24,7 +24,7 @@ module Zizq
       #
       # @rbs &block: (T) -> void
       # @rbs return: Enumerator[T, void] | void
-      def each: () { (T) -> void } -> (Enumerator[T, void] | void)
+      def each: () { (T) -> void } -> untyped
 
       # Returns true if there is a next page that can be fetched.
       def has_next?: () -> untyped

data/sig/zizq.rbs

@@ -32,7 +32,10 @@ module Zizq
     ?status: (String | Array[String])?,
     ?queue: (String | Array[String])?,
     ?type: (String | Array[String])?,
-    ?filter: String?
+    ?filter: String?,
+    ?priority: (Integer | Range[Integer?])?,
+    ?ready_at: (to_f | Range[to_f?])?,
+    ?attempts: (Integer | Range[Integer?])?
   }
 
   # Update parameters for single and bulk update operations.

metadata

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