@zizq-labs/zizq 0.3.1 → 0.4.0

package/README.md

@@ -7,10 +7,12 @@ API.
 This is the official Zizq client library for Node.js, written in TypeScript.
 
 [![CI](https://github.com/zizq-labs/zizq-node/actions/workflows/ci.yml/badge.svg)](https://github.com/zizq-labs/zizq-node/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@zizq-labs/zizq.svg)](https://www.npmjs.com/package/@zizq-labs/zizq)
 
 ## Features
 
 * Concurrent async-based worker
+* Plain handler functions, or composable Job Functions with attached defaults
 * Enqueue and process jobs from one language to another
 * Arbitrary named queues
 * Granular job priorities
@@ -29,7 +31,7 @@ This is the official Zizq client library for Node.js, written in TypeScript.
 
 Install it with your package manager of choice:
 
-``` shell
+```shell
 npm install @zizq-labs/zizq
 ```
 
@@ -39,29 +41,123 @@ Or:
 yarn add @zizq-labs/zizq
 ```
 
-## Example
+Node **22.19 or newer** is required. Client and server share version
+numbers — keep the client's major/minor at or below the server's.
 
-> [!TIP]
-> There is also a composable function-based convenience wrapper available. Read
-> the documentation on
-> [Handler Functions](https://zizq.io/docs/clients/node/handlers.html) for more
-> info
+## Configuration
 
-Enqueueing a job.
+A `Client` instance is the configuration — there is no global object. The
+defaults talk to a server at `http://localhost:7890`, which is fine for local
+development. For anything else, pass the URL (and TLS, if needed) when
+constructing the client:
 
 ```ts
+import fs from "node:fs";
 import { Client } from "@zizq-labs/zizq";
 
-const client = new Client({ url: "http://localhost:7890" });
+const client = new Client({
+  url: "https://zizq.your.network:7890",
+  tls: {
+    ca: fs.readFileSync("/path/to/server-ca-cert.pem"),
+  },
+});
+```
 
-await client.enqueue({
+For mutual TLS, add `cert` and `key` to the `tls` object (both PEM-encoded
+strings or `Buffer`s).
+
+> [!CAUTION]
+> If your server is exposed directly to the internet, it should require
+> mutual TLS — otherwise anybody can talk to it.
+
+## Usage
+
+> [!TIP]
+> This README is an overview. The
+> [full documentation](https://zizq.io/docs/clients/node/) covers each
+> feature in depth — handler patterns, job querying, unique jobs, and more.
+
+### Enqueuing jobs
+
+The simplest enqueue takes a `type`, `queue`, and `payload`. The Zizq server
+returns the created job, with its `id`, `status`, `readyAt` and other
+metadata:
+
+```ts
+const job = await client.enqueue({
   type: "send_email",
   queue: "emails",
-  payload: { to: "user@example.com" },
+  payload: { userId: 42, template: "welcome" },
+});
+job.id; // "03fu0wm75gxgmfyfplwvazhex"
+```
+
+Per-call options override server defaults — set `priority`, `readyAt` (to
+schedule a job in the future), `retryLimit`, `backoff`, or `retention`
+inline. `client.enqueueBulk(inputs)` submits many jobs atomically in a
+single HTTP request, across queues and types:
+
+```ts
+await client.enqueueBulk([
+  { type: "send_email", queue: "emails", payload: { userId: 1 } },
+  { type: "send_email", queue: "emails", payload: { userId: 2 } },
+]);
+```
+
+### Defining handlers
+
+A handler is an `async` function that accepts a `job` and either resolves
+(the worker acks it as successful) or throws (the worker reports a failure
+and the server retries per the backoff policy). The simplest version is a
+`switch` on `job.type`:
+
+```ts
+async function handler(job) {
+  switch (job.type) {
+    case "send_email":
+      return sendEmail(job.payload);
+    case "generate_report":
+      return generateReport(job.payload);
+    default:
+      throw new Error(`unexpected job type: ${job.type}`);
+  }
+}
+```
+
+For a more composable style, the client ships `buildHandler` — pass in your
+job functions and you get back a handler that dispatches on the function
+name. Each function can also carry `zizqOptions` with its own defaults
+(queue, priority, backoff, retention, uniqueness), so enqueuing later only
+needs the payload:
+
+```ts
+import { buildHandler } from "@zizq-labs/zizq";
+
+async function sendEmail(payload, job) {
+  // ...
+}
+sendEmail.zizqOptions = { queue: "emails", priority: 100 };
+
+async function generateReport(payload) {
+  // ...
+}
+generateReport.zizqOptions = { queue: "reports" };
+
+const handler = buildHandler([sendEmail, generateReport]);
+
+// Job functions can be enqueued directly — the queue and other defaults
+// come from the function's zizqOptions.
+await client.enqueue({
+  type: sendEmail,
+  payload: { userId: 42, template: "welcome" },
 });
 ```
 
-A very basic worker with a custom handler.
+### Running a worker
+
+A `Worker` streams jobs from the server, dispatches them through your
+handler with bounded concurrency, batches acks, and reconnects on transient
+failures. `worker.run()` blocks until the worker stops:
 
 ```ts
 import { Client, Worker } from "@zizq-labs/zizq";
@@ -71,16 +167,8 @@ const client = new Client({ url: "http://localhost:7890" });
 const worker = new Worker({
   client,
   concurrency: 25,
-  queues: ["emails"],
-  handler: async (job) => {
-    switch (job.type) {
-      case "send_email":
-        console.log(`sending email using payload ${JSON.stringify(job.payload)}`);
-        break;
-      default:
-        throw new Error(`unknown job type: ${job.type}`);
-    }
-  },
+  queues: ["emails", "payments"],
+  handler,
 });
 
 process.on("SIGINT",  () => worker.stop());
@@ -89,6 +177,48 @@ process.on("SIGTERM", () => worker.stop());
 await worker.run();
 ```
 
+`worker.stop()` waits for in-flight handlers to settle and flushes pending
+acks before returning. To put a deadline on shutdown, schedule
+`worker.kill()` after a timeout — any handlers still running continue to
+completion (Node can't cancel promises), but their acks are not flushed, so
+the server re-dispatches those jobs to another worker. No jobs are lost.
+
+### Recurring jobs (cron)
+
+Define a cron schedule somewhere in your application startup.
+Registrations are idempotent — every process can safely call the same
+`register()`, and Zizq keeps the server-side schedule in sync by adding,
+replacing, and removing entries as the definition changes. Cron requires
+a Pro license on the server.
+
+```ts
+import { sendDailyDigest } from "./handlers";
+
+await client.cron("maintenance").register({
+  timezone: "Europe/London",
+  entries: [
+    {
+      name: "refresh_warehouse",
+      expression: "*/15 * * * *",
+      type: "refresh_warehouse",
+      queue: "data_warehouse",
+      payload: { incremental: true },
+    },
+    {
+      name: "daily_digest",
+      expression: "0 9 * * *",
+      type: sendDailyDigest, // Job Functions are accepted directly
+      payload: {},
+    },
+  ],
+});
+```
+
+Once defined, schedules can be inspected and managed via
+`client.cron("maintenance")` — `get()` to read the current state,
+`pause()`/`resume()` at the schedule or per-entry level, and `delete()`
+to remove a schedule entirely.
+
 ## Resources
 
 * [Node.js Client Docs](https://zizq.io/docs/clients/node/)
@@ -103,3 +233,7 @@ If you need help using Zizq,
 [create an issue](https://github.com/zizq-labs/zizq-node/issues) on the
 [zizq-node](https://github.com/zizq-labs/zizq-node) repo. Feedback is very
 welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/client.d.ts

@@ -82,6 +82,35 @@ export interface ClientOptions {
     format?: Format;
     /** TLS configuration for HTTPS connections. */
     tls?: TlsOptions;
+    /**
+     * Connect timeout in milliseconds — deadline for the TCP/TLS
+     * handshake. Applies to every pool.
+     *
+     * Default: 10000 (10s).
+     */
+    connectTimeout?: number;
+    /**
+     * Per-read timeout in milliseconds for API traffic (enqueue,
+     * queries, mutations — anything that isn't the long-lived
+     * `take()` stream). Bounds the time between consecutive bytes
+     * received from the server.
+     *
+     * Default: 30000 (30s).
+     */
+    readTimeout?: number;
+    /**
+     * Per-read timeout in milliseconds for the long-lived
+     * `take()` stream consumed by {@link Worker}. The server's
+     * heartbeats (default ~3s) reset the clock on each frame, so this
+     * only fires when the connection has actually gone silent.
+     * Triggers a Worker reconnect via the standard error path.
+     *
+     * Should be comfortably above the server's heartbeat interval to
+     * avoid false-positive disconnects.
+     *
+     * Default: 30000 (30s).
+     */
+    streamIdleTimeout?: number;
     /** @internal For testing — override the HTTP dispatcher. */
     dispatcher?: Dispatcher;
 }
@@ -280,6 +309,27 @@ export declare class Client {
      * ```
      */
     deleteAllJobs(options?: DeleteAllJobsOptions): Promise<number>;
+    /**
+     * Wipe *every* cron group and *every* job on the server.
+     *
+     * Equivalent to calling {@link deleteAllCrons} followed by
+     * {@link deleteAllJobs} (no filter), but in a single request. Useful
+     * primarily as a setup/teardown step in tests where you want a
+     * known-empty server between scenarios.
+     *
+     * **Destructive.** No filters, no escape hatch, no confirmation —
+     * the server-side operation simply returns once everything is gone.
+     *
+     * @example
+     * ```ts
+     * await client.reset();
+     * ```
+     */
+    reset(): Promise<void>;
+    /**
+     * Alias for {@link reset}.
+     */
+    eraseAllData(): Promise<void>;
     /**
      * Count jobs matching the given filters.
      *
@@ -493,6 +543,17 @@ export declare class Client {
      * @throws {NotFoundError} If the cron group is not found.
      */
     deleteCronGroup(name: string): Promise<void>;
+    /**
+     * Delete every cron group on the server in a single call.
+     *
+     * Returns the number of cron groups removed.
+     *
+     * **Destructive.** This deletes *every cron group on the server*. For
+     * granular deletes, use {@link deleteCronGroup} with a specific name.
+     *
+     * Requires a Pro license on the server.
+     */
+    deleteAllCrons(): Promise<number>;
     /**
      * Fetch a single cron entry within a group.
      *

package/dist/client.js

@@ -151,29 +151,54 @@ export class Client {
         this.contentType = CONTENT_TYPES[this.format];
         this.accept = CONTENT_TYPES[this.format];
         this.streamAccept = STREAM_ACCEPT[this.format];
+        const connectTimeout = options.connectTimeout ?? 10_000;
+        const readTimeout = options.readTimeout ?? 30_000;
+        const streamIdleTimeout = options.streamIdleTimeout ?? 30_000;
         if (options.dispatcher) {
             // Testing: use the same dispatcher for both.
             this.http = options.dispatcher;
             this.streamHttp = options.dispatcher;
         }
         else {
-            const connectOpts = options.tls ? {
-                ca: options.tls.ca,
-                cert: options.tls.cert,
-                key: options.tls.key,
-            } : undefined;
+            const connectOpts = {
+                ...(options.tls ? {
+                    ca: options.tls.ca,
+                    cert: options.tls.cert,
+                    key: options.tls.key,
+                } : {}),
+                timeout: connectTimeout,
+            };
             // HTTP/2 for request/response traffic (multiplexed acks, enqueues).
+            // `bodyTimeout` is per-chunk inactivity — reset on each byte —
+            // so it acts as the read timeout; `headersTimeout` caps
+            // "server accepted the request but didn't respond" cases.
             this.http = new Pool(this.url, {
                 allowH2: true,
                 connect: connectOpts,
+                headersTimeout: readTimeout,
+                bodyTimeout: readTimeout,
             });
             // HTTP/1.1 for the long-lived take stream. HTTP/2 adds framing
             // overhead and flow control with no multiplexing benefit on a
             // single long-lived response, resulting in measurably lower
             // throughput compared to HTTP/1.1 chunked transfer.
+            //
+            // `bodyTimeout` here uses `streamIdleTimeout` rather than the
+            // normal `readTimeout`: server heartbeats reset it on each frame,
+            // so this only fires when the connection has actually gone
+            // silent. The Worker's reconnect path handles the resulting
+            // BodyTimeoutError.
+            //
+            // `headersTimeout` stays on `readTimeout`: the response headers
+            // are a one-shot request/response pair like any other API call,
+            // only the body streams. Falling through to undici's 5-minute
+            // default would leave a server stuck pre-headers blocking the
+            // worker far longer than the user-configured timeout would suggest.
             this.streamHttp = new Pool(this.url, {
                 allowH2: false,
                 connect: connectOpts,
+                headersTimeout: readTimeout,
+                bodyTimeout: streamIdleTimeout,
             });
         }
     }
@@ -342,6 +367,34 @@ export class Client {
         const data = await this.handleResponse(await this.request("DELETE", path));
         return data.deleted;
     }
+    /**
+     * Wipe *every* cron group and *every* job on the server.
+     *
+     * Equivalent to calling {@link deleteAllCrons} followed by
+     * {@link deleteAllJobs} (no filter), but in a single request. Useful
+     * primarily as a setup/teardown step in tests where you want a
+     * known-empty server between scenarios.
+     *
+     * **Destructive.** No filters, no escape hatch, no confirmation —
+     * the server-side operation simply returns once everything is gone.
+     *
+     * @example
+     * ```ts
+     * await client.reset();
+     * ```
+     */
+    async reset() {
+        const res = await this.request("POST", "/reset");
+        if (res.statusCode !== 204) {
+            await this.throwOnError(res);
+        }
+    }
+    /**
+     * Alias for {@link reset}.
+     */
+    async eraseAllData() {
+        return this.reset();
+    }
     /**
      * Count jobs matching the given filters.
      *
@@ -645,6 +698,20 @@ export class Client {
             await this.throwOnError(res);
         }
     }
+    /**
+     * Delete every cron group on the server in a single call.
+     *
+     * Returns the number of cron groups removed.
+     *
+     * **Destructive.** This deletes *every cron group on the server*. For
+     * granular deletes, use {@link deleteCronGroup} with a specific name.
+     *
+     * Requires a Pro license on the server.
+     */
+    async deleteAllCrons() {
+        const data = await this.handleResponse(await this.request("DELETE", "/crons"));
+        return data.deleted;
+    }
     /**
      * Fetch a single cron entry within a group.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zizq-labs/zizq",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Node.js client for the Zizq job queue server",
   "homepage": "https://zizq.io",
   "repository": {