@zizq-labs/zizq 0.1.1 → 0.3.0

package/README.md

@@ -17,9 +17,28 @@ This is the official Zizq client library for Node.js, written in TypeScript.
 * Scheduled jobs
 * Configurable backoff policies
 * Configurable job retention policies
+* Recurring jobs (cron)
 * Job introspection and management APIs, with support for `jq` query filters
 * Unique jobs
 
+## Installation
+
+> [!NOTE]
+> If you have not yet installed the Zizq server, follow the
+> [Getting Started](https://zizq.io/docs/getting-started) guide first.
+
+Install it with your package manager of choice:
+
+``` shell
+npm install @zizq-labs/zizq
+```
+
+Or:
+
+```shell
+yarn add @zizq-labs/zizq
+```
+
 ## Example
 
 > [!TIP]

package/dist/client.d.ts

@@ -31,309 +31,12 @@
  * @module
  */
 import { type Dispatcher } from "undici";
-import { Job, JobPage, ErrorRecord, ErrorPage } from "./resources.ts";
+import { Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry } from "./resources.ts";
 import { JobQuery, type JobQueryOptions } from "./query.ts";
-/** Lifecycle status of a job. */
-export type JobStatus = "ready" | "in_flight" | "scheduled" | "completed" | "dead";
-/** Sort direction for paginated listings. */
-export type SortDirection = "asc" | "desc";
-/** Uniqueness scope for deduplication. */
-export type UniqueScope = "queued" | "active" | "exists";
-export { Job, JobPage, ErrorRecord, ErrorPage, type JobData, type ErrorRecordData } from "./resources.ts";
-/**
- * Backoff configuration for retry delays.
- *
- * This is used in the following formula:
- *
- * ```
- * t = baseMs + (attempts ** exponent) + (attempts * random() * jitterMs)
- * ```
- *
- * The random jitter is designed to ensure clusters of failed jobs do not all
- * retry at the same time but are instead randomly spread out.
- */
-export interface BackoffConfig {
-    /** Base delay in milliseconds, applied to all retries. */
-    baseMs: number;
-    /** Backoff curve steepness (attempts ** exponent). */
-    exponent: number;
-    /** Maximum random jitter in milliseconds per attempt multiplier. */
-    jitterMs: number;
-}
-/**
- * Retention configuration controlling how long jobs in terminal statuses are kept.
- *
- * The terminal statuses are "completed" and "dead".
- */
-export interface RetentionConfig {
-    /** How long completed jobs remain visible (ms). `null` clears to server default. */
-    completedMs?: number | null;
-    /** How long dead jobs remain visible (ms). `null` clears to server default. */
-    deadMs?: number | null;
-}
-/**
- * Options for enqueueing a single job.
- *
- * @example
- * ```ts
- * await client.enqueue({
- *   type: "generate_report",
- *   queue: "reports",
- *   payload: { reportId: 42 },
- *   priority: 100,            // optional, lower = higher priority
- *   readyAt: Date.now() + 60000, // optional, delay by 1 minute
- * });
- * ```
- */
-export interface EnqueueOptions {
-    /** Job type identifier. */
-    type: string;
-    /**
-     * Target queue name.
-     *
-     * Must be valid UTF-8 and must not contain any of the following reserved
-     * characters: ",", "?", "*", "[", "]", "{", "}", "!".
-     */
-    queue: string;
-    /**
-     * Arbitrary payload delivered to the worker.
-     */
-    payload: unknown;
-    /**
-     * Optional priority (lower = higher priority).
-     *
-     * Valid range is 0 to 65536. Default: 32768.
-     */
-    priority?: number;
-    /**
-     * Optional timestamp (ms since epoch) when the job becomes eligible.
-     *
-     * When set to a future timestamp the job is created in the "scheduled"
-     * status. Otherwise the job is created in the "ready" status.
-     */
-    readyAt?: number;
-    /**
-     * Optional per-job retry limit.
-     *
-     * When not set the server default value applies.
-     */
-    retryLimit?: number;
-    /** Optional per-job backoff configuration. */
-    backoff?: BackoffConfig;
-    /** Optional per-job retention configuration. */
-    retention?: RetentionConfig;
-    /**
-     * Optional unique key for enqueue-time deduplication.
-     *
-     * Requires a pro license on the server.
-     *
-     * The key is global across all queues and job types. Prefix with the job
-     * type to make it unique per job type.
-     */
-    uniqueKey?: string;
-    /**
-     * Uniqueness scope. Only valid when `uniqueKey` is set.
-     *
-     * When set to "queued" other jobs with the same key will not be enqueued as
-     * long as this job is in the "scheduled" or "ready" statuses.
-     *
-     * When set to "active" other jobs with the same key will not be enqueued
-     * while this job is in the "scheduled", "ready" or "in_flight" statuses.
-     *
-     * When set to "exists" other jobs with the same key will not be enqueued
-     * for as long as this job remains on the server (i.e. until it is eventually
-     * reaped, based on the retention policy).
-     */
-    uniqueWhile?: UniqueScope;
-}
-/** Options for reporting a job failure. */
-export interface FailureOptions {
-    /** Error message describing what went wrong. */
-    message: string;
-    /** Optional error class name, e.g. "TimeoutError". */
-    errorType?: string;
-    /** Optional stack trace from the worker. */
-    backtrace?: string;
-    /** Optional forced retry time (ms since epoch), bypassing backoff. */
-    retryAt?: number;
-    /**
-     * Kill the job immediately regardless of retry limit.
-     *
-     * Note: passing false does nothing.
-     */
-    kill?: boolean;
-}
-/**
- * Options for the streaming take endpoint.
- *
- * Returns an async generator which never terminates as long as the connection
- * to the server remains open. Clients should use `break` to explicitly
- * disconnect from the endpoint and stop receiving jobs.
- *
- * When no jobs are available, the generator waits until new jobs are enqueued.
- *
- * @example
- * ```ts
- * // Take up to 10 jobs at a time from specific queues
- * for await (const job of client.take({ prefetch: 10, queues: ["emails", "webhooks"] })) {
- *   // process job...
- * }
- * ```
- */
-export interface TakeOptions {
-    /**
-     * Maximum number of "in_flight", unacknowledged jobs the server will send.
-     *
-     * The default is 1, meaning the client must acknowledge or fail the job
-     * before the server sends the next, and so on.
-     */
-    prefetch?: number;
-    /** Only take jobs from these queues. Empty means all queues. */
-    queues?: string[];
-    /** AbortSignal to cancel the streaming connection. */
-    signal?: AbortSignal;
-}
-/**
- * Options for listing jobs with cursor-based pagination.
- *
- * @example
- * ```ts
- * const page = await client.listJobs({
- *   queue: "emails",
- *   status: ["ready", "in_flight"],
- *   limit: 20,
- * });
- * ```
- */
-export interface ListJobsOptions {
-    /** Cursor: start after this job ID (exclusive). */
-    from?: string;
-    /** Sort order. Default: "asc" (oldest first). */
-    order?: SortDirection;
-    /** Maximum number of jobs per page (1–2000, default 50). */
-    limit?: number;
-    /** Filter by status. Accepts a single value or an array. */
-    status?: JobStatus | JobStatus[];
-    /** Filter by queue name. Accepts a single value or an array. */
-    queue?: string | string[];
-    /** Filter by job type. Accepts a single value or an array. */
-    type?: string | string[];
-    /** Filter by job ID. Accepts a single value or an array. */
-    id?: string | string[];
-    /** jq expression to filter jobs by payload. */
-    filter?: string;
-}
-/**
- * Options for listing error records for a job.
- *
- * @example
- * ```ts
- * const page = await client.listErrors("job-id", { order: "desc", limit: 10 });
- * ```
- */
-export interface ListErrorsOptions {
-    /** Cursor: start after this attempt number (exclusive). */
-    from?: number;
-    /** Sort order. Default: "asc" (oldest first). */
-    order?: SortDirection;
-    /** Maximum number of error records per page (1–2000, default 50). */
-    limit?: number;
-}
-/**
- * Mutable fields for updating a job.
- *
- * Field semantics:
- * - **omitted or `undefined`** — leave unchanged
- * - **`null`** — clear the field (only valid for nullable fields)
- * - **a value** — update to that value
- *
- * Nullable fields: `readyAt`, `retryLimit`, `backoff`, `retention`.
- * Non-nullable fields: `queue`, `priority`.
- *
- * @example
- * ```ts
- * // Change priority and clear retry limit (use server default)
- * await client.updateJob("job-id", {
- *   priority: 100,
- *   retryLimit: null,
- * });
- * ```
- */
-export interface UpdateJobOptions {
-    /** Move the job to a different queue. */
-    queue?: string;
-    /** Change the job's priority. */
-    priority?: number;
-    /** Change when the job becomes ready (ms since epoch). `null` clears to immediately ready. */
-    readyAt?: number | null;
-    /** Override the retry limit. `null` clears to server default. */
-    retryLimit?: number | null;
-    /** Override the backoff config. `null` clears to server default. */
-    backoff?: BackoffConfig | null;
-    /** Override the retention config. `null` clears to server default. */
-    retention?: RetentionConfig | null;
-}
-/**
- * Options for bulk-updating jobs.
- *
- * Has two parts:
- * - `where` — filter selecting which jobs to update (same as `deleteAllJobs`)
- * - `apply` — fields to update on the matching jobs (same as `updateJob`)
- *
- * An empty array filter (e.g. `where.id: []`) short-circuits to 0 jobs updated.
- *
- * @example
- * ```ts
- * // Lower the priority of all dead jobs in the emails queue
- * const count = await client.updateAllJobs({
- *   where: { queue: "emails", status: "dead" },
- *   apply: { priority: 1000 },
- * });
- * ```
- */
-export interface UpdateAllJobsOptions {
-    /** Filter selecting which jobs to update. */
-    where?: JobFilter;
-    /** Fields to update on the matching jobs. */
-    apply: UpdateJobOptions;
-}
-/**
- * Filter for selecting jobs in bulk operations.
- *
- * Used by `deleteAllJobs` and `updateAllJobs` to scope which jobs are
- * affected. An empty filter selects all jobs.
- *
- * Multi-value fields accept either a single value or an array.
- */
-export interface JobFilter {
-    /** Filter by job ID. Accepts a single value or an array. */
-    id?: string | string[];
-    /** Filter by status. Accepts a single value or an array. */
-    status?: JobStatus | JobStatus[];
-    /** Filter by queue name. Accepts a single value or an array. */
-    queue?: string | string[];
-    /** Filter by job type. Accepts a single value or an array. */
-    type?: string | string[];
-    /** jq expression to filter jobs by payload. */
-    filter?: string;
-}
-/**
- * Options for bulk-deleting jobs.
- *
- * An empty `where` filter deletes all jobs.
- *
- * @example
- * ```ts
- * // Delete all dead jobs in the emails queue
- * const count = await client.deleteAllJobs({
- *   where: { queue: "emails", status: "dead" },
- * });
- * ```
- */
-export interface DeleteAllJobsOptions {
-    /** Filter selecting which jobs to delete. */
-    where?: JobFilter;
-}
+import { CronHandle } from "./cron.ts";
+export type { JobStatus, SortDirection, UniqueScope, BackoffConfig, RetentionConfig, EnqueueOptions, FailureOptions, UpdateJobOptions, Format, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions, } from "./types.ts";
+import type { EnqueueOptions, FailureOptions, UpdateJobOptions, Format, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions } from "./types.ts";
+export { Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry, type JobData, type ErrorRecordData, type CronGroupData, type CronEntryData, } from "./resources.ts";
 /** Response shape for `GET /health`. */
 interface HealthResponse {
     status: string;
@@ -367,7 +70,6 @@ export interface TlsOptions {
     key?: string | Buffer;
 }
 /** Serialization format for client-server communication. */
-export type Format = "json" | "msgpack";
 /** Options for constructing a {@link Client}. */
 export interface ClientOptions {
     /** Base URL of the Zizq server, e.g. "http://localhost:7890". */
@@ -522,7 +224,7 @@ export declare class Client {
      *
      * @param id - The job ID to fetch.
      * @returns The full job data including payload.
-     * @throws {ZizqError} If the job is not found (404).
+     * @throws {NotFoundError} If the job is not found (404).
      */
     getJob(id: string): Promise<Job>;
     /**
@@ -545,6 +247,16 @@ export declare class Client {
      * ```
      */
     deleteAllJobs(options?: DeleteAllJobsOptions): Promise<number>;
+    /**
+     * Count jobs matching the given filters.
+     *
+     * @example
+     * ```ts
+     * // Count all ready jobs in the emails queue
+     * const count = await client.countJobs({ queue: "emails", status: "ready" });
+     * ```
+     */
+    countJobs(where?: JobFilter): Promise<number>;
     /**
      * Update a single job's mutable fields.
      *
@@ -683,6 +395,154 @@ export declare class Client {
      * @throws {NotFoundError} If the job or attempt is not found.
      */
     getError(id: string, attempt: number): Promise<ErrorRecord>;
+    /**
+     * List all cron group names.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @example
+     * ```ts
+     * const groups = await client.listCronGroups();
+     * // ["default", "billing"]
+     * ```
+     */
+    listCronGroups(): Promise<string[]>;
+    /**
+     * Fetch a cron group and all its entries.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @param name - The name of the cron group
+     * @returns The cron group record
+     * @throws {NotFoundError} If the cron group is not found.
+     */
+    getCronGroup(name: string): Promise<CronGroup>;
+    /**
+     * Create or replace an entire cron group.
+     *
+     * Entries absent from the request are removed. Entries with unchanged
+     * expressions preserve their scheduling state.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @example
+     * ```ts
+     * const group = await client.replaceCronGroup("default", {
+     *   entries: [
+     *     { name: "send-reminders", expression: "0 9 * * *",
+     *       job: { type: "send_reminders", queue: "emails", payload: {} } },
+     *   ],
+     * });
+     * ```
+     */
+    replaceCronGroup(name: string, options: ReplaceCronGroupOptions): Promise<CronGroup>;
+    /**
+     * Update group-level fields.
+     *
+     * Currently only used for pause/resume.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @param name - The name of the cron group
+     * @param options - The new state of the cron group
+     * @returns The cron group record
+     * @throws {NotFoundError} If the cron group is not found.
+     */
+    updateCronGroup(name: string, options: {
+        paused: boolean;
+    }): Promise<CronGroup>;
+    /**
+     * Delete a cron group and all its entries.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @param name - The name of the cron group
+     * @throws {NotFoundError} If the cron group is not found.
+     */
+    deleteCronGroup(name: string): Promise<void>;
+    /**
+     * Fetch a single cron entry within a group.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @param group - The name of the cron group
+     * @param entry - The name of the entry within the group
+     * @returns The cron entry record
+     * @throws {NotFoundError} If the cron entry is not found.
+     */
+    getCronEntry(group: string, entry: string): Promise<CronEntry>;
+    /**
+     * Add a single entry to a cron group.
+     *
+     * Creates the group if needed. Throws a 409 conflict error if an entry
+     * with the same name already exists.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @example
+     * ```ts
+     * const entry = await client.addCronEntry("default", {
+     *   name: "weekly-report",
+     *   expression: "0 9 * * MON",
+     *   job: { type: "generate_report", queue: "reports", payload: { format: "pdf" } },
+     * });
+     * ```
+     *
+     * @throws {ClientError} If the cron entry already exists (409)
+     */
+    addCronEntry(group: string, entry: CronEntryInput): Promise<CronEntry>;
+    /**
+     * Create or replace a single cron entry within a group.
+     *
+     * Creates the group if needed.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @param group - The name of the cron group
+     * @param entry - The entry definition to create or replace
+     * @returns The cron entry record
+     */
+    replaceCronEntry(group: string, entryName: string, entry: Omit<CronEntryInput, "name">): Promise<CronEntry>;
+    /**
+     * Update cron entry-level fields.
+     *
+     * Currently only used for pause/resume.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @param group - The name of the cron group
+     * @param entry - The name of the entry within the group
+     * @param options - The new state of the cron group
+     * @returns The cron entry record
+     * @throws {NotFoundError} If the cron entry is not found.
+     */
+    updateCronEntry(group: string, entry: string, options: {
+        paused: boolean;
+    }): Promise<CronEntry>;
+    /**
+     * Delete a single cron entry within a group.
+     *
+     * Requires a Pro license on the server.
+     *
+     * @param group - The name of the cron group
+     * @param entry - The name of the entry within the group
+     * @throws {NotFoundError} If the cron entry is not found.
+     */
+    deleteCronEntry(group: string, entry: string): Promise<void>;
+    /**
+     * Get a handle for a cron group (schedule).
+     *
+     * No API call is made until you invoke a method on the handle.
+     *
+     * @example
+     * ```ts
+     * const cron = client.cron("default");
+     * await cron.register({ entries: [...] });
+     * await cron.pause();
+     * await cron.entry("sync").pause();
+     * ```
+     */
+    cron(name: string): CronHandle;
     /**
      * Connect to the streaming take endpoint and return an async generator
      * of jobs.
@@ -736,6 +596,7 @@ export declare class Client {
     private request;
     private post;
     private patch;
+    private put;
     private requestWithBody;
     /** Encode a value in the configured format. */
     private encode;