Enqueuing Jobs

The Zizq Node client exposes two top-level enqueue functions:

enqueue(client, input) — enqueue a single job.
enqueueBulk(client, inputs) — enqueue many jobs in a single HTTP request.

Note

Both Job Functions and raw job inputs use the same enqueue functions. The only difference is that Job Functions can be passed directly as the type, and any zizqOptions are automatically used as default options when enqueueing that job type.

import { enqueue, enqueueBulk } from "@zizq-labs/zizq";

await enqueue(client, {
  type: "send_email",
  queue: "emails",
  payload: { userId: 42, template: "welcome" },
});

await enqueueBulk(client, [
  { type: "send_email", queue: "emails", payload: { userId: 1 } },
  { type: "send_email", queue: "emails", payload: { userId: 2 } },
]);

await enqueue(client, {
  type: sendEmail,
  payload: { userId: 42, template: "welcome" },
});

Both accept either a string job type or a function reference with attached zizqOptions, which lets the function itself carry its default queue, priority, backoff, etc.

Single enqueue

When enqueueing a single job, the enqueue() function returns the Job from the Zizq server, which provides all its metadata, such as id, status, readyAt etc. Note that payload is not part of the response.

const result = await enqueue(client, {
  type: "send_email",
  queue: "emails",
  payload: { userId: 42, template: "welcome" },
});
result.id // "03fu0wm75gxgmfyfplwvazhex"

Bulk enqueue

Bulk enqueue works exactly the same as a single job enqueue, except that an array of inputs are provided, and an array of Job instances is returned in the order matching the inputs.

const results = await enqueueBulk(client, [
  { type: "send_email", queue: "emails", payload: { userId: 1 } },
  { type: "send_email", queue: "emails", payload: { userId: 2 } },
]);
results.length // 2

Enqueue options

The following options are available on the inputs to enqueue() and enqueueBulk(). All of type, queue and payload are required inputs, though Job Functions may specify their queue in zizqOptions meaning it is implicitly provided to enqueue() and enqueueBulk().

Option	Description
`type` string \| JobFunction	The type that identifies this job. Either a string, or a named JavaScript function, with optional attached `zizqOptions`.
`queue` string	The name of the queue onto which this job is enqueued.
`payload` object	Any valid JSON-serializable type understood by the handler that will run this job.
`priority` number?	Optional priority value between `0` and `65536`. When not specified, the default priority from the server applies.
`readyAt` number?	Optional milliseconds since the Unix epoch at which this job becomes ready for processing. When set at a future time, the job is enqueued with the `scheduled` status. Otherwise the job is `ready` immediately.
`retryLimit` number?	Optional retry limit override, which defines the number of retries that can occur before the Zizq server marks the job `dead` and stops retrying. When not specified, the server's default retry limit applies.
`backoff` BackoffConfig?	Optional backoff policy specific to this job. When not specified the server's default backoff policy applies. When specified, all fields must be present as they form a single backoff curve formula.
`backoff.baseMs` number	Number of milliseconds used at the mimimum delay in all exponential backoff calculations.
`backoff.exponent` number	The power curve steepness of the exponential backoff formula. The number of job attempts is raised to this power and added onto the `baseMs`. Floating point values are acceptable.
`backoff.jitterMs` number	A random jitter delay used to avoid cascades of failures all retrying at the same time. A random number between `0` and `jitterMs` is picked, then multiplied by the number of job attempts. The result is then added onto the total delay which creates a natural spread.
`retention` RetentionConfig?	Optional retention policy specific to this job. When not specified the server's default retention policy applies.
`retention.deadMs` number?	Number of milliseconds for which this job should be retained after entering the `dead` status. When not specified the server's default applies.
`retention.completedMs` number?	Number of milliseconds for which this job should be retained after entering the `completed` status. When not specified the server's default applies.
`uniqueKey` string?	Optional unique key used to handle enqueue-time de-duplication of jobs. Requires a Pro license on the server.
`uniqueWhile` ("queued" \| "active" \| "exists")?	Optional unique scope for which uniqueness is enforced on this job after it is enqueued. One of: `queued` — duplicates will be prevented while this job is in the `scheduled` or `ready` states. `active` — duplicates will be prevented while this job is in the `scheduled`, `ready` or `in_flight` states. `exists` — duplicates will be prevented for as long as this job is present on the server.

Keyboard shortcuts

Zizq Node Client

Enqueuing Jobs

Single enqueue

Bulk enqueue

Enqueue options