zizq 0.1.0

data/lib/zizq/resources/error_enumerator.rb

@@ -0,0 +1,241 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  module Resources
+    # Provides a lazy Enumerator across all errors on a job following the
+    # cursor-based pagination.
+    class ErrorEnumerator
+      # Maximum page size the server can handle.
+      MAX_PAGE_SIZE = 2000 #: Integer
+
+      # @rbs skip
+      include Enumerable
+
+      # @rbs!
+      #   include ::Enumerable[Zizq::Resources::ErrorRecord]
+
+      # Initialize the enumerator.
+      #
+      # @rbs id: String
+      # @rbs order: Zizq::sort_direction?
+      # @rbs limit: Integer?
+      # @rbs page_size: Integer?
+      # @rbs return: void
+      def initialize(id,
+                     order: nil,
+                     limit: nil,
+                     page_size: nil)
+        @id = id
+        @order = order
+        @limit = limit
+        @page_size = page_size
+      end
+
+      # Set the page size for paginated iteration.
+      #
+      # When set, `each_page` fetches pages of this size, and `each` fetches
+      # errors in pages of this size.
+      #
+      # @rbs page_size: Integer?
+      # @rbs return: ErrorEnumerator
+      def in_pages_of(page_size)
+        rebuild(page_size:)
+      end
+
+      # Set the sort order for iteration.
+      #
+      # @rbs order: Zizq::sort_direction?
+      # @rbs return: ErrorEnumerator
+      def order(order)
+        rebuild(order:)
+      end
+
+      # Limit the total number of errors returned.
+      #
+      # This is a total limit, imposed across potentially multiple page fetches.
+      #
+      # @rbs limit: Integer?
+      # @rbs return: ErrorEnumerator
+      def limit(limit)
+        rebuild(limit:)
+      end
+
+      # Reverse the sort order.
+      #
+      # Returns a new query with the opposite order. If no order was set,
+      # defaults to descending (the server default is ascending).
+      #
+      # @rbs return: ErrorEnumerator
+      def reverse_order
+        rebuild(order: @order == :desc ? :asc : :desc)
+      end
+
+      # Returns true if there are no errors.
+      #
+      # Optimised: fetches a single error to check.
+      #
+      # @rbs return: bool
+      def empty?
+        first.nil?
+      end
+
+      # Returns true if there are any errors.
+      #
+      # Without a block, optimised to fetch a single error. With a block,
+      # falls back to Enumerable (tests each error against the block).
+      #
+      # @rbs &block: ?(Resources::ErrorRecord) -> bool
+      # @rbs return: bool
+      def any?
+        return super if block_given?
+
+        !first.nil?
+      end
+
+      # Returns true if there are no errors.
+      #
+      # Without a block, optimised to fetch a single error. With a block,
+      # falls back to Enumerable (tests each error against the block).
+      #
+      # @rbs &block: ?(Resources::ErrorRecord) -> bool
+      # @rbs return: bool
+      def none?
+        return super if block_given?
+
+        first.nil?
+      end
+
+      # Returns true if there is exactly one error.
+      #
+      # Without a block, optimised to fetch at most two errors. With a block,
+      # falls back to Enumerable.
+      #
+      # @rbs &block: ?(Resources::ErrorRecord) -> bool
+      # @rbs return: bool
+      def one?
+        return super if block_given?
+
+        limit(2).to_a.size == 1
+      end
+
+      # Iterate over errors in reverse order.
+      #
+      # Optimised: pushes the reverse ordering to the server instead of
+      # fetching all errors into memory and reversing.
+      #
+      # @rbs &block: ?(Resources::ErrorRecord) -> void
+      # @rbs return: ::Enumerator[Zizq::Resources::ErrorRecord, void]
+      def reverse_each(&block)
+        reverse_order.each(&block)
+      end
+
+      # Return the first error, or nil if no errors.
+      #
+      # Optimised: fetches a single error from the server (`?limit=1`).
+      #
+      # @rbs return: Resources::ErrorRecord?
+      def first
+        limit(1).each.first
+      end
+
+      # Return the last error, or nil if no errors.
+      #
+      # Optimised: reverses the order and fetches a single error.
+      #
+      # @rbs return: Resources::ErrorRecord?
+      def last
+        reverse_order.first
+      end
+
+      # Return the first `n` errors.
+      #
+      # Optimised: sets the limit to `n` so the server only returns what's
+      # needed.
+      #
+      # @rbs n: Integer
+      # @rbs return: Array[Resources::ErrorRecord]
+      def take(n)
+        limit(n).to_a
+      end
+
+      # Iterate over errors, lazily paginating through results.
+      #
+      # Respects `limit` if set. Without a block, returns an `Enumerator`.
+      #
+      # @rbs &block: ?(Resources::ErrorRecord) -> void
+      # @rbs return: ::Enumerator[Zizq::Resources::ErrorRecord, void]
+      def each(&block)
+        enumerator = enum_for(:each)
+
+        if block_given?
+          remaining = @limit
+
+          each_page do |page|
+            page.errors.each do |error|
+              if remaining
+                break if remaining <= 0
+              end
+
+              yield error
+
+              remaining -= 1 if remaining
+            end
+          end
+        end
+
+        enumerator
+      end
+
+      # Iterate over pages of errors.
+      #
+      # Each page is a `Resources::ErrorPage`. Without a block, returns an
+      # `Enumerator`.
+      #
+      # If `limit` is set, terminates after the last page is reached that
+      # exceeds the limit, but does not truncate the page.
+      #
+      # @rbs &block: ?(Resources::ErrorPage) -> void
+      # @rbs return: ::Enumerator[Zizq::Resources::ErrorPage, void]
+      def each_page(&block)
+        enumerator = enum_for(:each_page)
+
+        if block_given?
+          page = Zizq.client.list_errors(
+            @id,
+            limit: [@page_size, @limit, (@page_size || @limit) && MAX_PAGE_SIZE].compact.min,
+            order: @order,
+          )
+
+          remaining = @limit
+
+          while page
+            yield page
+
+            if remaining
+              remaining -= page.errors.size
+              break if remaining <= 0
+            end
+
+            page = page.next_page
+          end
+        end
+
+        enumerator
+      end
+
+      private
+
+      # Build a new ErrorEnumerator with the given overrides, preserving all
+      # other fields.
+      #
+      # @rbs return: ErrorEnumerator
+      def rebuild(id = @id, order: @order, limit: @limit, page_size: @page_size)
+        self.class.new(id, limit:, order:, page_size:)
+      end
+    end
+  end
+end

data/lib/zizq/resources/error_page.rb

@@ -0,0 +1,19 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  module Resources
+    # Paginated list of error records.
+    # @rbs inherits Page[ErrorRecord]
+    class ErrorPage < Page
+      def items #: () -> Array[ErrorRecord]
+        @items ||= (@data["errors"] || []).map { |e| ErrorRecord.new(client, e) }
+      end
+
+      alias errors items
+    end
+  end
+end

data/lib/zizq/resources/error_record.rb

@@ -0,0 +1,19 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  module Resources
+    # Typed wrapper around a single error record from the job error history.
+    class ErrorRecord < Resource
+      def attempt     = @data["attempt"]     #: () -> Integer
+      def message     = @data["message"]     #: () -> String
+      def error_type  = @data["error_type"]  #: () -> String?
+      def backtrace   = @data["backtrace"]   #: () -> String?
+      def dequeued_at = ms_to_seconds(@data["dequeued_at"]) #: () -> Float
+      def failed_at   = ms_to_seconds(@data["failed_at"])   #: () -> Float
+    end
+  end
+end

data/lib/zizq/resources/job.rb

@@ -0,0 +1,124 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  module Resources
+    # Typed wrapper around a job response hash.
+    #
+    # Exposes named accessor methods with Ruby-idiomatic types (fractional
+    # seconds instead of milliseconds) and link methods that follow related
+    # resources through the Client.
+    class Job < Resource
+      def id          = @data["id"]          #: () -> String
+      def type        = @data["type"]        #: () -> String
+      def queue       = @data["queue"]       #: () -> String
+      def priority    = @data["priority"]    #: () -> Integer
+      def status      = @data["status"]      #: () -> String
+      def ready_at    = ms_to_seconds(@data["ready_at"])    #: () -> Float?
+      def attempts    = @data["attempts"]    #: () -> Integer
+      def payload     = @data["payload"]     #: () -> Hash[String, untyped]?
+      def dequeued_at = ms_to_seconds(@data["dequeued_at"]) #: () -> Float?
+      def failed_at     = ms_to_seconds(@data["failed_at"])     #: () -> Float?
+      def completed_at  = ms_to_seconds(@data["completed_at"])  #: () -> Float?
+      def retry_limit   = @data["retry_limit"] #: () -> Integer?
+      def unique_key    = @data["unique_key"]  #: () -> String?
+      def unique_while  = @data["unique_while"]&.to_sym #: () -> Zizq::unique_scope?
+      def duplicate?    = @data["duplicate"] == true #: () -> bool
+
+      # Backoff configuration converted from the wire format (ms) to the
+      # Ruby-idiomatic format (seconds), matching the Zizq::backoff type.
+      def backoff #: () -> Zizq::backoff?
+        raw = @data["backoff"]
+        return nil unless raw
+
+        {
+          exponent: raw["exponent"].to_f,
+          base: raw["base_ms"] / 1000.0,
+          jitter: raw["jitter_ms"] / 1000.0
+        }
+      end
+
+      # Retention configuration converted from the wire format (ms) to the
+      # Ruby-idiomatic format (seconds), matching the Zizq::retention type.
+      def retention #: () -> Zizq::retention?
+        raw = @data["retention"]
+        return nil unless raw
+
+        result = {} #: Hash[Symbol, Float]
+        result[:completed] = raw["completed_ms"] / 1000.0 if raw["completed_ms"]
+        result[:dead] = raw["dead_ms"] / 1000.0 if raw["dead_ms"]
+        result
+      end
+
+      # Fetch the error history for this job.
+      #
+      # @rbs order: Zizq::sort_direction?
+      # @rbs limit: Integer?
+      # @rbs page_size: Integer?
+      # @rbs return: ErrorEnumerator
+      def errors(order: nil, limit: nil, page_size: nil)
+        ErrorEnumerator.new(id, order:, limit:, page_size:)
+      end
+
+      # Mark this job as successfully completed.
+      def complete! #: () -> nil
+        @client.report_success(id)
+      end
+
+      # Report this job as failed.
+      #
+      # @rbs message: String
+      # @rbs error_type: String?
+      # @rbs backtrace: String?
+      # @rbs retry_at: Float?
+      # @rbs kill: bool
+      # @rbs return: Job
+      def fail!(message:, error_type: nil, backtrace: nil, retry_at: nil, kill: false)
+        @client.report_failure(id, message:, error_type:, backtrace:, retry_at:, kill:)
+      end
+
+      # Delete this job.
+      #
+      # @rbs return: void
+      def delete
+        @client.delete_job(id)
+      end
+
+      # Update this job's mutable fields.
+      #
+      # Returns the updated job.
+      #
+      # @rbs queue: (String | singleton(Zizq::UNCHANGED))?
+      # @rbs priority: (Integer | singleton(Zizq::UNCHANGED))?
+      # @rbs ready_at: (Zizq::to_f | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+      # @rbs retry_limit: (Integer | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+      # @rbs backoff: (Zizq::backoff | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+      # @rbs retention: (Zizq::retention | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+      # @rbs return: Job
+      def update(queue: Zizq::UNCHANGED,
+                 priority: Zizq::UNCHANGED,
+                 ready_at: Zizq::UNCHANGED,
+                 retry_limit: Zizq::UNCHANGED,
+                 backoff: Zizq::UNCHANGED,
+                 retention: Zizq::UNCHANGED)
+        job = @client.update_job(
+          id,
+          queue:,
+          priority:,
+          ready_at:,
+          retry_limit:,
+          backoff:,
+          retention:
+        )
+
+        # Make sure this job's fields are updated.
+        @data.merge!(job.to_h)
+
+        job
+      end
+    end
+  end
+end

data/lib/zizq/resources/job_page.rb

@@ -0,0 +1,57 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  module Resources
+    # Paginated list of jobs.
+    # @rbs inherits Page[Job]
+    class JobPage < Page
+      def items #: () -> Array[Job]
+        @items ||= (@data["jobs"] || []).map { |j| Job.new(client, j) }
+      end
+
+      alias jobs items
+
+      # Delete all jobs on this page.
+      #
+      # Returns the number of deleted jobs.
+      #
+      # @rbs return: Integer
+      def delete_all
+        ids = jobs.map(&:id)
+        return 0 if ids.empty?
+
+        client.delete_all_jobs(where: { id: ids })
+      end
+
+      # Update all jobs on this page with the given field values.
+      #
+      # Returns the number of updated jobs.
+      #
+      # @rbs queue: (String | singleton(Zizq::UNCHANGED))?
+      # @rbs priority: (Integer | singleton(Zizq::UNCHANGED))?
+      # @rbs ready_at: (Zizq::to_f | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+      # @rbs retry_limit: (Integer | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+      # @rbs backoff: (Zizq::backoff | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+      # @rbs retention: (Zizq::retention | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+      # @rbs return: Integer
+      def update_all(queue: Zizq::UNCHANGED,
+                     priority: Zizq::UNCHANGED,
+                     ready_at: Zizq::UNCHANGED,
+                     retry_limit: Zizq::UNCHANGED,
+                     backoff: Zizq::UNCHANGED,
+                     retention: Zizq::UNCHANGED)
+        ids = jobs.map(&:id)
+        return 0 if ids.empty?
+
+        client.update_all_jobs(
+          where: { id: ids },
+          apply: { queue:, priority:, ready_at:, retry_limit:, backoff:, retention: },
+        )
+      end
+    end
+  end
+end

data/lib/zizq/resources/page.rb

@@ -0,0 +1,77 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  module Resources
+    # Base class for paginated list responses.
+    #
+    # Stores the raw response data and provides navigation helpers that
+    # follow pagination links through the Client.
+    #
+    # @rbs generic T < Resource
+    class Page < Resource
+      # @rbs skip
+      include Enumerable
+
+      # @rbs!
+      #   include ::Enumerable[T]
+
+      # Wrapped resource objects for this page.
+      def items #: () -> Array[T]
+        raise NotImplementedError, "#{self.class.name}#items must be implemented"
+      end
+
+      # Returns the underlying raw response hash.
+      #
+      # Re-declared here because Enumerable#to_h would otherwise shadow
+      # the Resource#to_h definition.
+      def to_h #: () -> Hash[String, untyped]
+        @data
+      end
+
+      # Yields each item on this page. Required by Enumerable.
+      #
+      # @rbs &block: (T) -> void
+      # @rbs return: Enumerator[T, void] | void
+      def each(&block)
+        items.each(&block)
+      end
+
+      # Returns true if there is a next page that can be fetched.
+      def has_next? #: () -> bool
+        !!@data.dig("pages", "next")
+      end
+
+      # Returns true if there is a previous page that can be fetched.
+      def has_prev? #: () -> bool
+        !!@data.dig("pages", "prev")
+      end
+
+      # Fetch the next page, or nil if there isn't one.
+      def next_page #: () -> Page?
+        path = @data.dig("pages", "next")
+        return nil unless path
+
+        wrap_page(client.get_path(path))
+      end
+
+      # Fetch the previous page, or nil if there isn't one.
+      def prev_page #: () -> Page?
+        path = @data.dig("pages", "prev")
+        return nil unless path
+
+        wrap_page(client.get_path(path))
+      end
+
+      private
+
+      # Subclasses override to wrap the raw page data in the correct Page type.
+      def wrap_page(data) #: (Hash[String, untyped]) -> Page
+        self.class.new(client, data)
+      end
+    end
+  end
+end

data/lib/zizq/resources/resource.rb

@@ -0,0 +1,45 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  module Resources
+    # Base class for all typed response wrappers. Holds a reference to the
+    # Client (for following links) and the raw response hash.
+    class Resource
+      # Returns the client instance that returned this resource.
+      attr_reader :client #: Client
+
+      # @rbs client: Zizq::Client
+      # @rbs data: Hash[String, untyped]
+      # @rbs return: void
+      def initialize(client, data)
+        @client = client
+        @data = data
+      end
+
+      # Returns the underlying raw response hash.
+      def to_h #: () -> Hash[String, untyped]
+        @data
+      end
+
+      # Omit the client from inspect output to reduce noise.
+      def inspect #: () -> String
+        ivars = instance_variables
+          .reject { |v| v == :@client }
+          .map { |v| " #{v}=#{instance_variable_get(v).inspect}" }
+          .join
+        "#<#{self.class}#{ivars}>"
+      end
+
+      protected
+
+      # Convert a millisecond timestamp to fractional seconds, nil-safe.
+      def ms_to_seconds(value) #: (Integer?) -> Float?
+        value&./(1000.0)
+      end
+    end
+  end
+end

data/lib/zizq/resources.rb

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# frozen_string_literal: true
+
+module Zizq
+  module Resources
+    autoload :Resource,        "zizq/resources/resource"
+    autoload :Job,             "zizq/resources/job"
+    autoload :ErrorRecord,     "zizq/resources/error_record"
+    autoload :Page,            "zizq/resources/page"
+    autoload :JobPage,         "zizq/resources/job_page"
+    autoload :ErrorPage,       "zizq/resources/error_page"
+    autoload :ErrorEnumerator, "zizq/resources/error_enumerator"
+  end
+end

data/lib/zizq/version.rb

@@ -0,0 +1,9 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  VERSION = "0.1.0" #: String
+end