@zizq-labs/zizq 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,747 @@
+/**
+ * Low-level HTTP client for the Zizq job queue server.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { Client } from "@zizq-labs/zizq";
+ *
+ * const client = new Client({ url: "http://localhost:7890" });
+ *
+ * // Enqueue a job
+ * const job = await client.enqueue({
+ *   type: "send_email",
+ *   queue: "emails",
+ *   payload: { to: "user@example.com", subject: "Hello" },
+ * });
+ * console.log(job.id); // "03fvqh..."
+ *
+ * // Take and process jobs (streaming)
+ * for await (const job of client.take({ prefetch: 5, queues: ["emails"] })) {
+ *   try {
+ *     await processJob(job);
+ *     await client.reportSuccess(job.id);
+ *   } catch (err) {
+ *     await client.reportFailure(job.id, { message: err.message });
+ *   }
+ * }
+ *
+ * await client.close();
+ * ```
+ *
+ * @module
+ */
+import { type Dispatcher } from "undici";
+import { Job, JobPage, ErrorRecord, ErrorPage } 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;
+}
+/** Response shape for `GET /health`. */
+interface HealthResponse {
+    status: string;
+}
+/**
+ * TLS configuration for connecting to the Zizq server over HTTPS.
+ *
+ * Values are PEM-encoded strings or Buffers. If loading from files,
+ * use `fs.readFileSync()`.
+ *
+ * @example
+ * ```ts
+ * import fs from "node:fs";
+ *
+ * const client = new Client({
+ *   url: "https://localhost:7890",
+ *   tls: {
+ *     ca: fs.readFileSync("/path/to/ca.pem"),
+ *     cert: fs.readFileSync("/path/to/client.pem"),
+ *     key: fs.readFileSync("/path/to/client-key.pem"),
+ *   },
+ * });
+ * ```
+ */
+export interface TlsOptions {
+    /** PEM-encoded CA certificate(s) for verifying the server. */
+    ca?: string | Buffer;
+    /** PEM-encoded client certificate for mTLS. Must be paired with `key`. */
+    cert?: string | Buffer;
+    /** PEM-encoded client private key for mTLS. Must be paired with `cert`. */
+    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". */
+    url: string;
+    /**
+     * Serialization format for request and response bodies.
+     *
+     * Default: "json".
+     */
+    format?: Format;
+    /** TLS configuration for HTTPS connections. */
+    tls?: TlsOptions;
+    /** @internal For testing — override the HTTP dispatcher. */
+    dispatcher?: Dispatcher;
+}
+/** Base error class for all Zizq errors. */
+export declare class ZizqError extends Error {
+    constructor(message: string);
+}
+/**
+ * Network-level failure (connection refused, DNS, timeout, etc.).
+ *
+ * These are always transient and safe to retry.
+ */
+export declare class ConnectionError extends ZizqError {
+    constructor(message: string);
+}
+/**
+ * HTTP error — the server returned a non-success status code.
+ *
+ * Carries the HTTP status code and (when available) the parsed response
+ * body, which typically contains an `error` field with a human-readable
+ * message from the server.
+ */
+export declare class ResponseError extends ZizqError {
+    /** HTTP status code from the server. */
+    status: number;
+    /** Parsed response body, if available. */
+    body?: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 4xx client error — the request was invalid. Not retryable. */
+export declare class ClientError extends ResponseError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 404 specifically — job not found, etc. */
+export declare class NotFoundError extends ClientError {
+    constructor(message: string, body?: unknown);
+}
+/** 5xx server error — something went wrong on the server. Retryable. */
+export declare class ServerError extends ResponseError {
+    constructor(message: string, status: number, body?: unknown);
+}
+/**
+ * Low-level HTTP client for the Zizq job queue server.
+ *
+ * Maintains a persistent connection (HTTP/2 when available) for efficient
+ * request multiplexing. All methods map directly to server API endpoints.
+ *
+ * Call {@link close} when done to wait for in-flight requests to complete and
+ * release the underlying connection.
+ *
+ * @example
+ * ```ts
+ * const client = new Client({ url: "http://localhost:7890" });
+ *
+ * const job = await client.enqueue({
+ *   type: "send_email",
+ *   queue: "emails",
+ *   payload: { to: "user@example.com" },
+ * });
+ *
+ * await client.close();
+ * ```
+ */
+export declare class Client {
+    /** Pool for request/response traffic (enqueue, ack, failure, get). */
+    private http;
+    /** Separate pool for long-lived streaming connections (take). */
+    private streamHttp;
+    /** The base URL of the Zizq server. */
+    readonly url: string;
+    /** Serialization format. */
+    private format;
+    /** Content-type for requests. */
+    private contentType;
+    /** Accept header for request/response endpoints. */
+    private accept;
+    /** Accept header for the streaming take endpoint. */
+    private streamAccept;
+    constructor(options: ClientOptions);
+    /**
+     * Enqueue a single job.
+     *
+     * @returns The created job, including its server-assigned `id` and `status`.
+     * @throws {ZizqError} If the server rejects the request (e.g. invalid queue name).
+     *
+     * @example
+     * ```ts
+     * const job = await client.enqueue({
+     *   type: "send_email",
+     *   queue: "emails",
+     *   payload: { to: "user@example.com" },
+     * });
+     * ```
+     */
+    enqueue(options: EnqueueOptions): Promise<Job>;
+    /**
+     * Enqueue multiple jobs in a single request.
+     *
+     * @returns An array of created jobs in the same order as the input.
+     *
+     * @example
+     * ```ts
+     * const jobs = await client.enqueueBulk([
+     *   { type: "send_email", queue: "emails", payload: { to: "a@b.com" } },
+     *   { type: "send_email", queue: "emails", payload: { to: "c@d.com" } },
+     * ]);
+     * ```
+     */
+    enqueueBulk(jobs: EnqueueOptions[]): Promise<Job[]>;
+    /**
+     * Acknowledge a job as successfully completed.
+     *
+     * @param id - The job ID to acknowledge.
+     * @throws {ZizqError} If the job is not found or not in-flight.
+     */
+    reportSuccess(id: string): Promise<void>;
+    /**
+     * Acknowledge multiple jobs as successfully completed in a single request.
+     *
+     * Jobs that have already been acknowledged or that don't exist are
+     * silently ignored (the server returns 422 but the client treats it
+     * as success).
+     *
+     * @param ids - Array of job IDs to acknowledge.
+     */
+    reportSuccessBulk(ids: string[]): Promise<void>;
+    /**
+     * Report a job as failed.
+     *
+     * The server will either reschedule the job with backoff or move it to
+     * the dead list if the retry limit has been exceeded.
+     *
+     * @param id - The job ID to report failure for.
+     * @param options - Error details (message, stack trace, etc.).
+     * @returns The updated job with its new status and attempt count.
+     */
+    reportFailure(id: string, options: FailureOptions): Promise<Job>;
+    /**
+     * Fetch a single job by ID.
+     *
+     * @param id - The job ID to fetch.
+     * @returns The full job data including payload.
+     * @throws {ZizqError} If the job is not found (404).
+     */
+    getJob(id: string): Promise<Job>;
+    /**
+     * Delete a single job by ID.
+     *
+     * @param id - The job ID to delete.
+     * @throws {NotFoundError} If the job is not found.
+     */
+    deleteJob(id: string): Promise<void>;
+    /**
+     * Delete jobs matching the given filters.
+     *
+     * An empty options object deletes all jobs.
+     *
+     * @returns The number of deleted jobs.
+     *
+     * @example
+     * ```ts
+     * const count = await client.deleteAllJobs({ queue: "emails", status: "dead" });
+     * ```
+     */
+    deleteAllJobs(options?: DeleteAllJobsOptions): Promise<number>;
+    /**
+     * Update a single job's mutable fields.
+     *
+     * Field semantics:
+     * - **omitted or `undefined`** — leave unchanged
+     * - **`null`** — clear the field (only valid for nullable fields)
+     * - **a value** — update to that value
+     *
+     * @param id - The job ID to update.
+     * @param options - Fields to update.
+     * @returns The updated job.
+     * @throws {NotFoundError} If the job is not found.
+     *
+     * @example
+     * ```ts
+     * // Change priority and clear the retry limit
+     * await client.updateJob("job-id", {
+     *   priority: 100,
+     *   retryLimit: null,
+     * });
+     * ```
+     */
+    updateJob(id: string, options: UpdateJobOptions): Promise<Job>;
+    /**
+     * Bulk update jobs matching a filter.
+     *
+     * @returns The number of updated jobs.
+     *
+     * @example
+     * ```ts
+     * const count = await client.updateAllJobs({
+     *   where: { queue: "emails", status: "ready" },
+     *   apply: { priority: 1000 },
+     * });
+     * ```
+     */
+    updateAllJobs(options: UpdateAllJobsOptions): Promise<number>;
+    /**
+     * List jobs with cursor-based pagination.
+     *
+     * Returns a single page of jobs. Use `page.nextPage()` and
+     * `page.prevPage()` to navigate between pages.
+     *
+     * @example
+     * ```ts
+     * const page = await client.listJobs({ queue: ["emails"], limit: 10 });
+     * for (const job of page.jobs) {
+     *   console.log(job.id, job.status);
+     * }
+     * if (page.hasNext) {
+     *   const next = await page.nextPage();
+     * }
+     * ```
+     */
+    listJobs(options?: ListJobsOptions): Promise<JobPage>;
+    /**
+     * Fetch a page of jobs by a raw path (used internally for pagination links).
+     *
+     * @internal
+     */
+    listJobsByPath(path: string): Promise<JobPage>;
+    /**
+     * Health check.
+     *
+     * @returns The parsed response body, e.g. `{ status: "ok" }`.
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * Server version.
+     *
+     * @returns The server's version string.
+     */
+    serverVersion(): Promise<string>;
+    /**
+     * Start a composable, lazy query over jobs.
+     *
+     * Returns a {@link JobQuery} that can be chained with filter and
+     * ordering methods, then iterated or used with terminal methods like
+     * `first()`, `toArray()`, `updateAll()`, and `deleteAll()`.
+     *
+     * No HTTP request is made until the query is consumed.
+     *
+     * Accepts an optional {@link JobQueryOptions} to seed the query's initial
+     * filter, order, limit, and page size — handy as a shorthand for
+     * `client.jobs().byQueue(...).limit(...)` etc.
+     *
+     * @example
+     * ```ts
+     * const dead = await client.jobs()
+     *   .byQueue("emails")
+     *   .byStatus("dead")
+     *   .toArray();
+     *
+     * // Shorthand with seeded options
+     * const ready = await client.jobs({ queue: "emails", status: "ready" }).toArray();
+     *
+     * for await (const job of client.jobs().byStatus("ready")) {
+     *   console.log(job.id);
+     * }
+     * ```
+     */
+    jobs(options?: JobQueryOptions): JobQuery;
+    /**
+     * List all distinct queue names on the server.
+     *
+     * @returns An array of queue name strings, sorted alphabetically.
+     */
+    queues(): Promise<string[]>;
+    /**
+     * List error records for a job with cursor-based pagination.
+     *
+     * @param id - The job ID to list errors for.
+     * @param options - Pagination and ordering options.
+     *
+     * @example
+     * ```ts
+     * const page = await client.listErrors("job-id", { order: "desc" });
+     * for (const error of page) {
+     *   console.log(`Attempt ${error.attempt}: ${error.message}`);
+     * }
+     * ```
+     */
+    listErrors(id: string, options?: ListErrorsOptions): Promise<ErrorPage>;
+    /**
+     * Fetch a page of errors by a raw path (used internally for pagination links).
+     *
+     * @internal
+     */
+    listErrorsByPath(path: string): Promise<ErrorPage>;
+    /**
+     * Fetch a single error record for a job by attempt number.
+     *
+     * @param id - The job ID.
+     * @param attempt - The attempt number (1-based).
+     * @returns The error record for that attempt.
+     * @throws {NotFoundError} If the job or attempt is not found.
+     */
+    getError(id: string, attempt: number): Promise<ErrorRecord>;
+    /**
+     * Connect to the streaming take endpoint and return an async generator
+     * of jobs.
+     *
+     * The returned promise resolves once the HTTP connection is established.
+     * The async generator then yields jobs as they arrive. Heartbeats in
+     * the stream are silently skipped.
+     *
+     * The generator completes when the server closes the connection. The
+     * caller may also break out of the loop explicitly to end the stream,
+     * or provide an AbortSignal to explicitly signal cancellation.
+     *
+     * @example
+     * ```ts
+     * for await (const job of await client.take({ prefetch: 5, queues: ["emails"] })) {
+     *   await processJob(job.payload);
+     *   await client.reportSuccess(job.id);
+     * }
+     * ```
+     */
+    take(options?: TakeOptions): Promise<AsyncGenerator<Job>>;
+    /** Parse an NDJSON stream, yielding jobs. Empty lines are heartbeats. */
+    private iterateNdjson;
+    /**
+     * Parse a length-prefixed MessagePack stream, yielding jobs.
+     *
+     * Frame format: [4-byte big-endian length][MessagePack payload].
+     * A zero-length frame is a heartbeat and is silently skipped.
+     */
+    private iterateMsgpackStream;
+    /** Wrap raw API data as a Job instance. */
+    private wrapJob;
+    /** Wrap raw API data as an ErrorRecord instance. */
+    private wrapError;
+    /**
+     * Gracefully close the underlying HTTP connection.
+     *
+     * Waits for in-flight requests to complete. If a streaming `take()`
+     * connection is open, this will block until it ends — use
+     * {@link destroy} for hard immediate shutdown.
+     */
+    close(): Promise<void>;
+    /**
+     * Forcefully destroy the underlying HTTP connection.
+     *
+     * Immediately terminates all in-flight requests including any open
+     * `take()` stream. Use this when `close()` would block (e.g. after
+     * an unclean interruption in the REPL).
+     */
+    destroy(): Promise<void>;
+    private request;
+    private post;
+    private patch;
+    private requestWithBody;
+    /** Encode a value in the configured format. */
+    private encode;
+    private handleResponse;
+    private throwOnError;
+    /** Read and decode a response body, using the content-type header to
+     *  pick the correct decoder rather than assuming the requested format. */
+    private readBody;
+}