zizq 0.2.1 → 0.3.0

data/sig/generated/zizq/enqueue_with.rbs

@@ -58,12 +58,12 @@ module Zizq
     # Enqueue a job class via the underlying target, applying the scoped
     # overrides before invoking any caller-supplied block.
     #
-    # @rbs job_class: Class & Zizq::job_class
+    # @rbs job_class: Class & Zizq::JobConfig
     # @rbs args: Array[untyped]
     # @rbs kwargs: Hash[Symbol, untyped]
     # @rbs &block: ?(EnqueueRequest) -> void
     # @rbs return: untyped
-    def enqueue: (Class & Zizq::job_class job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> untyped
+    def enqueue: (Class & Zizq::JobConfig job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> untyped
 
     # Enqueue a raw request via the underlying target, with overrides
     # merged into the kwargs (explicit kwargs take precedence).

data/sig/generated/zizq/query.rbs

@@ -118,11 +118,11 @@ module Zizq
     # Sets the type filter to the class name and adds a jq payload filter
     # for an exact match of the serialized arguments.
     #
-    # @rbs job_class: Zizq::job_class
+    # @rbs job_class: Class && Zizq::JobConfig
     # @rbs *args: untyped
     # @rbs **kwargs: untyped
     # @rbs return: Query
-    def by_job_class_and_args: (Zizq::job_class job_class, *untyped args, **untyped kwargs) -> Query
+    def by_job_class_and_args: (untyped job_class, *untyped args, **untyped kwargs) -> Query
 
     # Filter by job class and a subset of arguments.
     #
@@ -132,11 +132,11 @@ module Zizq
     # The job class must include `Zizq::Job` or for Active Job classes must
     # extend `Zizq::ActiveJobConfig`.
     #
-    # @rbs job_class: Zizq::job_class
+    # @rbs job_class: Class & Zizq::JobConfig
     # @rbs *args: untyped
     # @rbs **kwargs: untyped
     # @rbs return: Query
-    def by_job_class_and_args_subset: (Zizq::job_class job_class, *untyped args, **untyped kwargs) -> Query
+    def by_job_class_and_args_subset: (Class & Zizq::JobConfig job_class, *untyped args, **untyped kwargs) -> Query
 
     # Replace the jq payload filter expression.
     #

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

@@ -0,0 +1,29 @@
+# Generated from lib/zizq/resources/cron_entry.rb with RBS::Inline
+
+module Zizq
+  module Resources
+    # Typed wrapper around a cron entry response hash.
+    class CronEntry < Resource
+      def name: () -> untyped
+
+      def expression: () -> untyped
+
+      def timezone: () -> untyped
+
+      def paused: () -> untyped
+
+      def paused?: () -> untyped
+
+      def paused_at: () -> untyped
+
+      def resumed_at: () -> untyped
+
+      def next_enqueue_at: () -> untyped
+
+      def last_enqueue_at: () -> untyped
+
+      # Returns the job template for this entry.
+      def job: () -> untyped
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# Generated from lib/zizq/resources/cron_group.rb with RBS::Inline
+
+module Zizq
+  module Resources
+    # Typed wrapper around a cron group response hash.
+    class CronGroup < Resource
+      def name: () -> untyped
+
+      def paused: () -> untyped
+
+      def paused?: () -> untyped
+
+      def paused_at: () -> untyped
+
+      def resumed_at: () -> untyped
+
+      # Returns the entries in this group as typed resources.
+      def entries: () -> untyped
+    end
+  end
+end

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

@@ -4,48 +4,26 @@ 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
+    # Inherits template fields (type, queue, priority, payload, backoff,
+    # retention, unique_key, unique_while) from JobTemplate and adds
+    # lifecycle fields and action methods.
+    class Job < JobTemplate
       def id: () -> untyped
 
-      def type: () -> untyped
-
-      def queue: () -> untyped
-
-      def priority: () -> untyped
-
       def status: () -> untyped
 
       def ready_at: () -> untyped
 
       def attempts: () -> untyped
 
-      def payload: () -> untyped
-
       def dequeued_at: () -> untyped
 
       def failed_at: () -> untyped
 
       def completed_at: () -> untyped
 
-      def retry_limit: () -> untyped
-
-      def unique_key: () -> untyped
-
-      def unique_while: () -> untyped
-
       def duplicate?: () -> untyped
 
-      # Backoff configuration converted from the wire format (ms) to the
-      # Ruby-idiomatic format (seconds), matching the Zizq::backoff type.
-      def backoff: () -> untyped
-
-      # Retention configuration converted from the wire format (ms) to the
-      # Ruby-idiomatic format (seconds), matching the Zizq::retention type.
-      def retention: () -> untyped
-
       # Fetch the error history for this job.
       #
       # @rbs order: Zizq::sort_direction?

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

@@ -0,0 +1,31 @@
+# Generated from lib/zizq/resources/job_template.rb with RBS::Inline
+
+module Zizq
+  module Resources
+    # Typed wrapper around a job template — the fields shared between
+    # live jobs and cron entry job definitions.
+    class JobTemplate < Resource
+      def type: () -> untyped
+
+      def queue: () -> untyped
+
+      def priority: () -> untyped
+
+      def payload: () -> untyped
+
+      def retry_limit: () -> untyped
+
+      def unique_key: () -> untyped
+
+      def unique_while: () -> untyped
+
+      # Backoff configuration converted from the wire format (ms) to the
+      # Ruby-idiomatic format (seconds), matching the Zizq::backoff type.
+      def backoff: () -> untyped
+
+      # Retention configuration converted from the wire format (ms) to the
+      # Ruby-idiomatic format (seconds), matching the Zizq::retention type.
+      def retention: () -> untyped
+    end
+  end
+end

data/sig/generated/zizq.rbs

@@ -58,6 +58,80 @@ module Zizq
   # @rbs return: Zizq::Query
   def self.query: () -> Zizq::Query
 
+  # Return a list of all available Crontab schedules.
+  def self.crontabs: () -> untyped
+
+  # Define (or redefine) a Crontab schedule.
+  #
+  # This requires a Pro license on the Zizq server.
+  #
+  # Crontabs are used to define collections of recurring jobs that run on a
+  # specified schedule, such as at 2am on every Monday. Each entry on the
+  # Crontab is a single job enqueue, which the Zizq server automatically
+  # triggers at the correct point in time. Zizq uses standard Cron expression
+  # syntax (with support for seconds via 6-fields) to define entries.
+  #
+  # This is designed to be idempotent. You can define a schedule somewhere in
+  # your application startup process (after `Zizq.configure`) and it doesn't
+  # matter if multiple process all define the same schedule. Zizq is smart
+  # enough to handle this correctly.
+  #
+  # Entire schedules, and individual entries on a schedule, can be paused and
+  # resumed.
+  #
+  # By default schedules operate in the system time zone of the Zizq server
+  # but an explicit IANA timezone name can be specified when defining the
+  # Crontab.
+  #
+  # This method sends exactly *one* request to the Zizq server upon
+  # completion of the block. Any existing entries are retained. Any new
+  # entries are added, any absent entries are removed, and any modified
+  # entries are replaced. In short, whatever the block defines is what the
+  # entire resulting Crontab schedule will look like.
+  #
+  #   Zizq.define_crontab("example", timezone: "Europe/Rome") do |cron|
+  #     cron.define_entry(
+  #       "refresh_data_warehose",
+  #       "*/15 * * * *"
+  #     ).enqueue(RefreshDataWarehoseJob, incremental: true)
+  #
+  #     cron.define_entry(
+  #       "expire_acess_tokens",
+  #       "*/10 * * * * *"
+  #     ).enqueue_raw(
+  #       queue: "identity-server",
+  #       type: "expire_access_tokens",
+  #       priority: 100,
+  #       payload: {},
+  #     )
+  #   end
+  #
+  # When jobs are pushed to the queue at their execution time, Zizq handles
+  # this atomically, so there is no risk of a duplicate enqueue for the same
+  # schedule tick. However, if you have long-running jobs that should not be
+  # permitted to overlap, such as in the case your schedule runs every 10
+  # seconds but jobs can take 30 seconds to execute, you should consider
+  # using unique jobs.
+  #
+  # @rbs name: String
+  # @rbs timezone: String?
+  # @rbs paused: bool?
+  # @rbs &block: (Zizq::CrontabBuilder) -> void
+  # @rbs return: Zizq::Crontab
+  def self.define_crontab: (String name, ?timezone: String?, ?paused: bool?) { (Zizq::CrontabBuilder) -> void } -> Zizq::Crontab
+
+  # Obtain a handle for the given Crontab schedule.
+  #
+  # This is a lazy operation. The schedule data is only fetched from the Zizq
+  # server upon first accessing data within the schedule.
+  #
+  #   Zizq.crontab("default").paused?
+  #   Zizq.crontab("default").resume!
+  #
+  # @rbs name: String
+  # @rbs return: Zizq::Crontab
+  def self.crontab: (String name) -> Zizq::Crontab
+
   # Enqueue a job by class with positional and keyword arguments.
   #
   # By default all arguments are serialized as JSON, which means hashes with
@@ -93,12 +167,12 @@ module Zizq
   #     end
   #   end
   #
-  # @rbs job_class: Class & Zizq::job_class
+  # @rbs job_class: Class & Zizq::JobConfig
   # @rbs args: Array[untyped]
   # @rbs kwargs: Hash[Symbol, untyped]
   # @rbs &block: ?(EnqueueRequest) -> void
   # @rbs return: Resources::Job
-  def self.enqueue: (Class & Zizq::job_class job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> Resources::Job
+  def self.enqueue: (Class & Zizq::JobConfig job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> Resources::Job
 
   # Enqueue a job by providing raw inputs to the Zizq server.
   #
@@ -171,10 +245,10 @@ module Zizq
   # @api private
   # Build an EnqueueRequest for a single job class enqueue.
   #
-  # @rbs job_class: Class & Zizq::job_class
+  # @rbs job_class: Class & Zizq::JobConfig
   # @rbs args: Array[untyped]
   # @rbs kwargs: Hash[Symbol, untyped]
   # @rbs &block: ?(EnqueueRequest) -> void
   # @rbs return: EnqueueRequest
-  def self.build_enqueue_request: (Class & Zizq::job_class job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> EnqueueRequest
+  def self.build_enqueue_request: (Class & Zizq::JobConfig job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> EnqueueRequest
 end

data/sig/zizq.rbs

@@ -45,6 +45,28 @@ module Zizq
     ?retention: (retention | singleton(RESET) | singleton(UNCHANGED))?
   }
 
+  # Job template for cron entry definitions.
+  type cron_job_params = {
+    type: String,
+    queue: String,
+    payload: untyped,
+    ?priority: Integer?,
+    ?retry_limit: Integer?,
+    ?backoff: backoff?,
+    ?retention: retention?,
+    ?unique_key: String?,
+    ?unique_while: unique_scope?
+  }
+
+  # Parameters for a single cron entry.
+  type cron_entry_params = {
+    name: String,
+    expression: String,
+    job: cron_job_params,
+    ?timezone: String?,
+    ?paused: bool?
+  }
+
   # TLS options for connecting over HTTPS. Values are PEM strings or file paths.
   type tls_options = { ?ca: String, ?client_cert: String, ?client_key: String }
 
@@ -58,26 +80,11 @@ module Zizq
 
   # Structural type for a class that includes Zizq::Job.
   #
-  # When a class includes Zizq::Job, the `included` callback extends
-  # ClassMethods onto the class. Steep can't infer this from the runtime
-  # `extend` call, so we describe the resulting shape as an interface.
+  # This serves only to ensure the class can be instantiated without args.
   #
   # The `_` prefix is mandatory RBS syntax for interfaces. The `job_class`
   # type alias below provides a cleaner name for use in source annotations.
   interface _JobClass
-    def zizq_queue: (?String?) -> String
-    def zizq_retry_limit: (?Integer?) -> Integer?
-    def zizq_backoff: (?exponent: Numeric?, ?base: Numeric?, ?jitter: Numeric?) -> backoff?
-    def zizq_retention: (?completed: Numeric?, ?dead: Numeric?) -> retention?
-    def zizq_unique: (?bool?, ?scope: unique_scope?) -> bool
-    def zizq_unique_scope: (?unique_scope?) -> unique_scope?
-    def zizq_unique_key: (*untyped, **untyped) -> String
-    def zizq_serialize: (*untyped, **untyped) -> Hash[String, untyped]
-    def zizq_deserialize: (Hash[String, untyped]) -> [Array[untyped], Hash[Symbol, untyped]]
-    def zizq_payload_filter: (*untyped, **untyped) -> String
-    def zizq_payload_subset_filter: (*untyped, **untyped) -> String
-    def zizq_enqueue_request: (*untyped, **untyped) -> EnqueueRequest
-    def name: () -> String?
     def new: () -> Job
   end
 
@@ -91,7 +98,7 @@ module Zizq
   # inside an existing bulk block compose naturally.
   interface _EnqueueTarget
     def enqueue: (
-      Class & job_class,
+      Class & JobConfig,
       *untyped,
       **untyped
     ) ?{ (EnqueueRequest) -> void } -> untyped

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zizq
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Chris Corbyn <chris@zizq.io>
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-02 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -38,12 +38,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
-description: |-
-  This is the Ruby client for the Zizq job queue server.
+description: |+
+  This is the official Ruby client for the Zizq job queue server.
 
-  [Zizq](https://zizq.io/) is a simple, single binary, zero dependency, language agnostic job queue.
+  Zizq is a simple, single binary, zero dependency, language agnostic job queue.
 
-  This client supports multi-threaded and/or multi-fiber concurrency and is very fast. The Zizq server provides everything needed. There are no separate external storage dependencies to configure.
 email:
 executables:
 - zizq-worker
@@ -62,6 +61,10 @@ files:
 - lib/zizq/bulk_enqueue.rb
 - lib/zizq/client.rb
 - lib/zizq/configuration.rb
+- lib/zizq/crontab.rb
+- lib/zizq/crontab_builder.rb
+- lib/zizq/crontab_entry.rb
+- lib/zizq/crontab_entry_builder.rb
 - lib/zizq/enqueue_request.rb
 - lib/zizq/enqueue_with.rb
 - lib/zizq/error.rb
@@ -71,11 +74,14 @@ files:
 - lib/zizq/middleware.rb
 - lib/zizq/query.rb
 - lib/zizq/resources.rb
+- lib/zizq/resources/cron_entry.rb
+- lib/zizq/resources/cron_group.rb
 - lib/zizq/resources/error_enumerator.rb
 - lib/zizq/resources/error_page.rb
 - lib/zizq/resources/error_record.rb
 - lib/zizq/resources/job.rb
 - lib/zizq/resources/job_page.rb
+- lib/zizq/resources/job_template.rb
 - lib/zizq/resources/page.rb
 - lib/zizq/resources/resource.rb
 - lib/zizq/version.rb
@@ -87,6 +93,10 @@ files:
 - sig/generated/zizq/bulk_enqueue.rbs
 - sig/generated/zizq/client.rbs
 - sig/generated/zizq/configuration.rbs
+- sig/generated/zizq/crontab.rbs
+- sig/generated/zizq/crontab_builder.rbs
+- sig/generated/zizq/crontab_entry.rbs
+- sig/generated/zizq/crontab_entry_builder.rbs
 - sig/generated/zizq/enqueue_request.rbs
 - sig/generated/zizq/enqueue_with.rbs
 - sig/generated/zizq/error.rbs
@@ -95,11 +105,14 @@ files:
 - sig/generated/zizq/lifecycle.rbs
 - sig/generated/zizq/middleware.rbs
 - sig/generated/zizq/query.rbs
+- sig/generated/zizq/resources/cron_entry.rbs
+- sig/generated/zizq/resources/cron_group.rbs
 - sig/generated/zizq/resources/error_enumerator.rbs
 - sig/generated/zizq/resources/error_page.rbs
 - sig/generated/zizq/resources/error_record.rbs
 - sig/generated/zizq/resources/job.rbs
 - sig/generated/zizq/resources/job_page.rbs
+- sig/generated/zizq/resources/job_template.rbs
 - sig/generated/zizq/resources/page.rbs
 - sig/generated/zizq/resources/resource.rbs
 - sig/generated/zizq/version.rbs
@@ -132,3 +145,4 @@ signing_key:
 specification_version: 4
 summary: The official Ruby client for the Zizq job queue
 test_files: []
+...