@zizq-labs/zizq 0.3.0 → 0.3.2

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 { Client, enqueue } from "@zizq-labs/zizq";
+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"),
+  },
+});
+```
+
+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.
 
-await enqueue(client, {
+### 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

@@ -34,8 +34,8 @@ import { type Dispatcher } from "undici";
 import { Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry } from "./resources.ts";
 import { JobQuery, type JobQueryOptions } from "./query.ts";
 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 type { JobStatus, SortDirection, UniqueScope, BackoffConfig, RetentionConfig, EnqueueOptions, EnqueueInput, FailureOptions, UpdateJobOptions, Format, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions, } from "./types.ts";
+import type { EnqueueOptions, EnqueueInput, 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 {
@@ -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;
 }
@@ -164,10 +193,14 @@ export declare class Client {
     /**
      * Enqueue a single job.
      *
+     * The `type` field accepts either a string job type name or a function
+     * reference with attached `zizqOptions`. When a function is provided,
+     * its `zizqOptions` supplies defaults for `queue`, `priority`, etc.
+     *
      * @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
+     * @example String type
      * ```ts
      * const job = await client.enqueue({
      *   type: "send_email",
@@ -175,22 +208,51 @@ export declare class Client {
      *   payload: { to: "user@example.com" },
      * });
      * ```
+     *
+     * @example Function reference
+     * ```ts
+     * const job = await client.enqueue({
+     *   type: sendEmail,
+     *   payload: { to: "user@example.com" },
+     * });
+     * ```
      */
-    enqueue(options: EnqueueOptions): Promise<Job>;
+    enqueue(input: EnqueueInput): Promise<Job>;
     /**
      * Enqueue multiple jobs in a single request.
      *
+     * Accepts the same input format as {@link enqueue}, including function
+     * references for the `type` field.
+     *
      * @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" } },
+     *   { type: sendEmail, payload: { to: "a@b.com" } },
+     *   { type: "manual_job", queue: "ops", payload: {} },
      * ]);
      * ```
      */
-    enqueueBulk(jobs: EnqueueOptions[]): Promise<Job[]>;
+    enqueueBulk(inputs: EnqueueInput[]): Promise<Job[]>;
+    /**
+     * Enqueue a single job using raw, fully-resolved options.
+     *
+     * Prefer {@link enqueue} for most use cases. This method is useful when
+     * you have already resolved function references or need direct control
+     * over the options object.
+     *
+     * @returns The created job, including its server-assigned `id` and `status`.
+     */
+    enqueueRaw(options: EnqueueOptions): Promise<Job>;
+    /**
+     * Enqueue multiple jobs using raw, fully-resolved options.
+     *
+     * Prefer {@link enqueueBulk} for most use cases.
+     *
+     * @returns An array of created jobs in the same order as the input.
+     */
+    enqueueBulkRaw(jobs: EnqueueOptions[]): Promise<Job[]>;
     /**
      * Acknowledge a job as successfully completed.
      *

package/dist/client.js

@@ -37,6 +37,7 @@ import { encode as msgpackEncode, decode as msgpackDecode } from "@msgpack/msgpa
 import { Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry, } from "./resources.js";
 import { JobQuery } from "./query.js";
 import { CronHandle } from "./cron.js";
+import { resolveInput } from "./enqueue.js";
 // Re-export resource types so consumers can import from client.ts.
 export { Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry, } from "./resources.js";
 /** Base error class for all Zizq errors. */
@@ -150,39 +151,68 @@ 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,
             });
         }
     }
     /**
      * Enqueue a single job.
      *
+     * The `type` field accepts either a string job type name or a function
+     * reference with attached `zizqOptions`. When a function is provided,
+     * its `zizqOptions` supplies defaults for `queue`, `priority`, etc.
+     *
      * @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
+     * @example String type
      * ```ts
      * const job = await client.enqueue({
      *   type: "send_email",
@@ -190,25 +220,58 @@ export class Client {
      *   payload: { to: "user@example.com" },
      * });
      * ```
+     *
+     * @example Function reference
+     * ```ts
+     * const job = await client.enqueue({
+     *   type: sendEmail,
+     *   payload: { to: "user@example.com" },
+     * });
+     * ```
      */
-    async enqueue(options) {
-        const api = enqueueToApi(options);
-        return this.wrapJob(await this.handleResponse(await this.post("/jobs", api)));
+    async enqueue(input) {
+        return this.enqueueRaw(resolveInput(input));
     }
     /**
      * Enqueue multiple jobs in a single request.
      *
+     * Accepts the same input format as {@link enqueue}, including function
+     * references for the `type` field.
+     *
      * @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" } },
+     *   { type: sendEmail, payload: { to: "a@b.com" } },
+     *   { type: "manual_job", queue: "ops", payload: {} },
      * ]);
      * ```
      */
-    async enqueueBulk(jobs) {
+    async enqueueBulk(inputs) {
+        return this.enqueueBulkRaw(inputs.map(resolveInput));
+    }
+    /**
+     * Enqueue a single job using raw, fully-resolved options.
+     *
+     * Prefer {@link enqueue} for most use cases. This method is useful when
+     * you have already resolved function references or need direct control
+     * over the options object.
+     *
+     * @returns The created job, including its server-assigned `id` and `status`.
+     */
+    async enqueueRaw(options) {
+        const api = enqueueToApi(options);
+        return this.wrapJob(await this.handleResponse(await this.post("/jobs", api)));
+    }
+    /**
+     * Enqueue multiple jobs using raw, fully-resolved options.
+     *
+     * Prefer {@link enqueueBulk} for most use cases.
+     *
+     * @returns An array of created jobs in the same order as the input.
+     */
+    async enqueueBulkRaw(jobs) {
         const api = { jobs: jobs.map(enqueueToApi) };
         const data = await this.handleResponse(await this.post("/jobs/bulk", api));
         return data.jobs.map((j) => this.wrapJob(j));

package/dist/cron.d.ts

@@ -8,8 +8,7 @@
  */
 import type { Client } from "./client.ts";
 import type { CronGroup, CronEntry } from "./resources.ts";
-import type { EnqueueOptions } from "./types.ts";
-import { type EnqueueInput } from "./enqueue.ts";
+import type { EnqueueOptions, EnqueueInput } from "./types.ts";
 /**
  * A cron entry definition that accepts function references for the job type.
  *

package/dist/enqueue.d.ts

@@ -1,120 +1,25 @@
-import { Client, type BackoffConfig, type EnqueueOptions, Job, type RetentionConfig, type UniqueScope } from "./client.ts";
-import type { JobFunction } from "./handler.ts";
-/**
- * Input for enqueueing a job.
- *
- * The `type` field accepts either a string job type name or a function
- * reference with optional attached `zizqOptions`. When a function is provided,
- * its `zizqOptions` supplies defaults for `queue`, `priority`, etc. These
- * defaults can be overridden by inputs specified at enqueue-time.
- *
- * When `type` is a string, `queue` is required in the inputs.
- *
- * @example Function reference
- * ```ts
- * await enqueue(client, { type: sendEmail, payload: { to: "a@b.com" } });
- * ```
- *
- * @example String type with explicit config
- * ```ts
- * await enqueue(client, {
- *   type: "send_email",
- *   queue: "emails",
- *   payload: { to: "a@b.com" },
- *   priority: 100,
- * });
- * ```
- */
-export interface EnqueueInput {
-    /** Job type — a function reference or a string type name. */
-    type: JobFunction | string;
-    /** Arbitrary payload delivered to the worker. */
-    payload: unknown;
-    /**
-     * Target queue name.
-     *
-     * Required when `type` is a string and no `zizqOptions.queue` default
-     * is available.
-     */
-    queue?: string;
-    /**
-     * Priority (lower = higher priority).
-     *
-     * Valid range is 0 to 65536. Default: 32768.
-     */
-    priority?: number;
-    /**
-     * 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;
-    /**
-     * Per-job retry limit.
-     *
-     * When not set the server default value applies.
-     */
-    retryLimit?: number;
-    /** Per-job backoff configuration. */
-    backoff?: BackoffConfig;
-    /** Per-job retention configuration. */
-    retention?: RetentionConfig;
-    /**
-     * 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. */
-    uniqueWhile?: UniqueScope;
-}
+import type { EnqueueOptions, EnqueueInput } from "./types.ts";
+import type { Client } from "./client.ts";
+import type { Job } from "./resources.ts";
+export type { EnqueueInput } from "./types.ts";
 /**
  * Enqueue a single job.
  *
+ * @deprecated Use `client.enqueue()` instead.
+ *
  * @param client - The Zizq client to use for the HTTP request.
  * @param input - Job type, payload, and optional configuration.
  * @returns The created job, including its server-assigned `id` and `status`.
- *
- * @example Function reference
- * ```ts
- * async function sendEmail(payload) { ... }
- * sendEmail.zizqOptions = { queue: "emails", priority: 100 };
- *
- * const job = await enqueue(client, {
- *   type: sendEmail,
- *   payload: { to: "user@example.com" },
- * });
- * ```
- *
- * @example String type
- * ```ts
- * const job = await enqueue(client, {
- *   type: "send_email",
- *   queue: "emails",
- *   payload: { to: "user@example.com" },
- * });
- * ```
  */
 export declare function enqueue(client: Client, input: EnqueueInput): Promise<Job>;
 /**
  * Enqueue multiple jobs in a single request.
  *
+ * @deprecated Use `client.enqueueBulk()` instead.
+ *
  * @param client - The Zizq client to use for the HTTP request.
  * @param inputs - Array of job inputs.
  * @returns An array of created jobs in the same order as the input.
- *
- * @example
- * ```ts
- * const jobs = await enqueueBulk(client, [
- *   { type: sendEmail, payload: { to: "a@b.com" } },
- *   { type: sendEmail, payload: { to: "c@d.com" }, priority: 1 },
- *   { type: "manual_job", queue: "ops", payload: {} },
- * ]);
- * ```
  */
 export declare function enqueueBulk(client: Client, inputs: EnqueueInput[]): Promise<Job[]>;
 /**

package/dist/enqueue.js

@@ -3,51 +3,26 @@
 /**
  * Enqueue a single job.
  *
+ * @deprecated Use `client.enqueue()` instead.
+ *
  * @param client - The Zizq client to use for the HTTP request.
  * @param input - Job type, payload, and optional configuration.
  * @returns The created job, including its server-assigned `id` and `status`.
- *
- * @example Function reference
- * ```ts
- * async function sendEmail(payload) { ... }
- * sendEmail.zizqOptions = { queue: "emails", priority: 100 };
- *
- * const job = await enqueue(client, {
- *   type: sendEmail,
- *   payload: { to: "user@example.com" },
- * });
- * ```
- *
- * @example String type
- * ```ts
- * const job = await enqueue(client, {
- *   type: "send_email",
- *   queue: "emails",
- *   payload: { to: "user@example.com" },
- * });
- * ```
  */
 export async function enqueue(client, input) {
-    return client.enqueue(resolveInput(input));
+    return client.enqueue(input);
 }
 /**
  * Enqueue multiple jobs in a single request.
  *
+ * @deprecated Use `client.enqueueBulk()` instead.
+ *
  * @param client - The Zizq client to use for the HTTP request.
  * @param inputs - Array of job inputs.
  * @returns An array of created jobs in the same order as the input.
- *
- * @example
- * ```ts
- * const jobs = await enqueueBulk(client, [
- *   { type: sendEmail, payload: { to: "a@b.com" } },
- *   { type: sendEmail, payload: { to: "c@d.com" }, priority: 1 },
- *   { type: "manual_job", queue: "ops", payload: {} },
- * ]);
- * ```
  */
 export async function enqueueBulk(client, inputs) {
-    return client.enqueueBulk(inputs.map(resolveInput));
+    return client.enqueueBulk(inputs);
 }
 // --- Internal ---
 // Compute the unique key from a job function's ZizqOptions + payload.

package/dist/handler.d.ts

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { BackoffConfig, EnqueueOptions, RetentionConfig, UniqueScope } from "./client.ts";
+import type { BackoffConfig, EnqueueOptions, RetentionConfig, UniqueScope } from "./types.ts";
 import type { Job } from "./resources.ts";
 /**
  * Configuration that can be attached to a job function via `fn.zizqOptions`.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Client, Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry, ZizqError, ConnectionError, ResponseError, ClientError, NotFoundError, ServerError, } from "./client.ts";
 export type { ClientOptions, TlsOptions, } from "./client.ts";
-export type { JobStatus, SortDirection, UniqueScope, Format, BackoffConfig, RetentionConfig, EnqueueOptions, FailureOptions, UpdateJobOptions, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions, } from "./types.ts";
+export type { JobStatus, SortDirection, UniqueScope, Format, BackoffConfig, RetentionConfig, EnqueueOptions, EnqueueInput, FailureOptions, UpdateJobOptions, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions, } from "./types.ts";
 export type { JobData, ErrorRecordData, CronEntryData, CronGroupData, } from "./resources.ts";
 export { Worker } from "./worker.ts";
 export type { WorkerOptions, Logger, RequestRetryOptions } from "./worker.ts";
@@ -11,5 +11,4 @@ export type { ErrorQueryOptions, JobQueryOptions } from "./query.ts";
 export { enqueue, enqueueBulk } from "./enqueue.ts";
 export { CronHandle, CronEntryHandle } from "./cron.ts";
 export type { CronEntryDefinition, RegisterCronOptions } from "./cron.ts";
-export type { EnqueueInput } from "./enqueue.ts";
 export { uniqueKey } from "./unique-key.ts";

package/dist/types.d.ts

@@ -6,6 +6,7 @@
  *
  * @module
  */
+import type { JobFunction } from "./handler.ts";
 /** Lifecycle status of a job. */
 export type JobStatus = "ready" | "in_flight" | "scheduled" | "completed" | "dead";
 /** Sort direction for paginated listings. */
@@ -242,3 +243,75 @@ export interface ReplaceCronGroupOptions {
     /** Named collection of entries present in this group. */
     entries: CronEntryInput[];
 }
+/**
+ * Input for enqueueing a job.
+ *
+ * The `type` field accepts either a string job type name or a function
+ * reference with optional attached `zizqOptions`. When a function is provided,
+ * its `zizqOptions` supplies defaults for `queue`, `priority`, etc. These
+ * defaults can be overridden by inputs specified at enqueue-time.
+ *
+ * When `type` is a string, `queue` is required in the inputs.
+ *
+ * @example Function reference
+ * ```ts
+ * await client.enqueue({ type: sendEmail, payload: { to: "a@b.com" } });
+ * ```
+ *
+ * @example String type with explicit config
+ * ```ts
+ * await client.enqueue({
+ *   type: "send_email",
+ *   queue: "emails",
+ *   payload: { to: "a@b.com" },
+ *   priority: 100,
+ * });
+ * ```
+ */
+export interface EnqueueInput {
+    /** Job type — a function reference or a string type name. */
+    type: JobFunction | string;
+    /** Arbitrary payload delivered to the worker. */
+    payload: unknown;
+    /**
+     * Target queue name.
+     *
+     * Required when `type` is a string and no `zizqOptions.queue` default
+     * is available.
+     */
+    queue?: string;
+    /**
+     * Priority (lower = higher priority).
+     *
+     * Valid range is 0 to 65536. Default: 32768.
+     */
+    priority?: number;
+    /**
+     * 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;
+    /**
+     * Per-job retry limit.
+     *
+     * When not set the server default value applies.
+     */
+    retryLimit?: number;
+    /** Per-job backoff configuration. */
+    backoff?: BackoffConfig;
+    /** Per-job retention configuration. */
+    retention?: RetentionConfig;
+    /**
+     * 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. */
+    uniqueWhile?: UniqueScope;
+}

package/package.json

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