@zizq-labs/zizq 0.4.2 → 0.5.0

package/dist/client.d.ts

@@ -34,7 +34,7 @@ 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, EnqueueInput, 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, RangeBounds, RangeFilter, 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`. */

package/dist/client.js

@@ -367,7 +367,7 @@ export class Client {
     async deleteAllJobs(options = {}) {
         assertOnlyKeys("deleteAllJobs", options, ["where"]);
         const where = options.where ?? {};
-        assertOnlyKeys("deleteAllJobs.where", where, ["id", "status", "queue", "type", "filter"]);
+        assertOnlyKeys("deleteAllJobs.where", where, ["id", "status", "queue", "type", "filter", "priority", "readyAt", "attempts"]);
         // Build the filter params, then short-circuit if any array filter resolved
         // to empty — an empty filter matches nothing, and we don't want to
         // accidentally delete everything.
@@ -417,7 +417,7 @@ export class Client {
      * ```
      */
     async countJobs(where = {}) {
-        assertOnlyKeys("countJobs", where, ["id", "status", "queue", "type", "filter"]);
+        assertOnlyKeys("countJobs", where, ["id", "status", "queue", "type", "filter", "priority", "readyAt", "attempts"]);
         const params = buildJobFilter(where);
         if (isEmptyFilter(params))
             return 0;
@@ -468,7 +468,7 @@ export class Client {
     async updateAllJobs(options) {
         assertOnlyKeys("updateAllJobs", options, ["where", "apply"]);
         const where = options.where ?? {};
-        assertOnlyKeys("updateAllJobs.where", where, ["id", "status", "queue", "type", "filter"]);
+        assertOnlyKeys("updateAllJobs.where", where, ["id", "status", "queue", "type", "filter", "priority", "readyAt", "attempts"]);
         // Same empty-filter short-circuit as deleteAllJobs.
         const params = buildJobFilter(where);
         if (isEmptyFilter(params))
@@ -1059,6 +1059,42 @@ function isEmptyFilter(params) {
         params.get("queue") === "" ||
         params.get("type") === "");
 }
+/**
+ * Encode a {@link RangeFilter} value into the server's query syntax.
+ *
+ * The four accepted shapes:
+ *
+ * - `number` (e.g. `50`) -> `"50"`
+ * - `{ min, max }` -> `"min..max"`
+ * - `{ min }` -> `"min.."`
+ * - `{ max }` -> `"..max"`
+ *
+ * Returns `undefined` for `null`/`undefined` so the caller can skip
+ * setting the param. Throws `TypeError` for any other shape (e.g. arrays,
+ * strings, objects with unknown keys).
+ */
+function encodeRange(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError(`range filter value must be a finite number, got ${value}`);
+        }
+        return String(value);
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`range filter must be a number or { min?, max? } object, got ${typeof value}`);
+    }
+    const { min, max } = value;
+    for (const [key, bound] of [["min", min], ["max", max]]) {
+        if (bound != null && (typeof bound !== "number" || !Number.isFinite(bound))) {
+            throw new TypeError(`range filter "${key}" must be a finite number, got ${typeof bound}`);
+        }
+    }
+    const lo = min != null ? String(min) : "";
+    const hi = max != null ? String(max) : "";
+    return `${lo}..${hi}`;
+}
 /**
  * Populate a {@link URLSearchParams} with the standard job filter fields.
  */
@@ -1073,6 +1109,15 @@ function buildJobFilter(where, params = new URLSearchParams()) {
         params.set("type", toCommaList(where.type));
     if (where.filter != null)
         params.set("filter", where.filter);
+    const priority = encodeRange(where.priority);
+    if (priority != null)
+        params.set("priority", priority);
+    const readyAt = encodeRange(where.readyAt);
+    if (readyAt != null)
+        params.set("ready_at", readyAt);
+    const attempts = encodeRange(where.attempts);
+    if (attempts != null)
+        params.set("attempts", attempts);
     return params;
 }
 /**

package/dist/query.d.ts

@@ -19,7 +19,7 @@
  *
  * @module
  */
-import type { Client, JobStatus, SortDirection, UpdateJobOptions } from "./client.ts";
+import type { Client, JobStatus, RangeFilter, SortDirection, UpdateJobOptions } from "./client.ts";
 import type { Job, JobPage, ErrorRecord, ErrorPage } from "./resources.ts";
 /**
  * Base class for lazy, async-iterable collections.
@@ -73,6 +73,12 @@ export interface JobQueryOptions {
     status?: JobStatus | JobStatus[];
     /** jq expression applied to the payload. */
     jqFilter?: string;
+    /** Priority filter — exact value or `{min, max}` inclusive range. */
+    priority?: RangeFilter;
+    /** `readyAt` filter (ms since epoch) — exact value or `{min, max}` range. */
+    readyAt?: RangeFilter;
+    /** Failure count filter — exact value or `{min, max}` inclusive range. */
+    attempts?: RangeFilter;
     /** Sort order. Default: "asc" (oldest first). */
     order?: SortDirection;
     /** Maximum total number of jobs to return across all pages. */
@@ -145,6 +151,9 @@ export declare class JobQuery extends Lazy<Job> {
     private _type?;
     private _status?;
     private _jqFilter?;
+    private _priority?;
+    private _readyAt?;
+    private _attempts?;
     private _order?;
     private _limit?;
     private _pageSize?;
@@ -172,6 +181,47 @@ export declare class JobQuery extends Lazy<Job> {
      * Add a jq payload filter. Combines with any existing filter via `and`.
      */
     addJqFilter(jqFilter: string): JobQuery;
+    /**
+     * Filter by priority. Replaces any existing priority filter.
+     *
+     * Accepts an exact value (`50`) or a `{min, max}` range with inclusive
+     * bounds. Omit either side for an unbounded end. Lower numbers are
+     * higher priority.
+     *
+     * @example
+     * client.jobs().byPriority(0);                  // exact match
+     * client.jobs().byPriority({ min: 0, max: 100 }); // bounded range
+     * client.jobs().byPriority({ min: 100 });        // 100 or higher
+     * client.jobs().byPriority({ max: 100 });        // 100 or lower
+     */
+    byPriority(priority: RangeFilter | undefined): JobQuery;
+    /**
+     * Filter by `readyAt` (ms since epoch). Replaces any existing filter.
+     *
+     * Accepts an exact value or a `{min, max}` range with inclusive bounds.
+     * Use `Date.prototype.getTime()` to derive ms from a `Date` instance.
+     *
+     * @example
+     * // Eligible to run by now.
+     * client.jobs().byReadyAt({ max: Date.now() });
+     *
+     * // Within the next hour.
+     * client.jobs().byReadyAt({ min: Date.now(), max: Date.now() + 3_600_000 });
+     */
+    byReadyAt(readyAt: RangeFilter | undefined): JobQuery;
+    /**
+     * Filter by failure count. Replaces any existing attempts filter.
+     *
+     * Accepts an exact value or a `{min, max}` range with inclusive bounds.
+     * `0` selects jobs that have never failed; `{ min: 1 }` selects anything
+     * that has failed at least once.
+     *
+     * @example
+     * client.jobs().byAttempts(0);                 // never failed
+     * client.jobs().byAttempts({ min: 1 });        // has failed
+     * client.jobs().byAttempts({ min: 1, max: 3 }); // 1, 2, or 3 failures
+     */
+    byAttempts(attempts: RangeFilter | undefined): JobQuery;
     /**
      * Constrain results by an exact payload match.
      *

package/dist/query.js

@@ -161,6 +161,9 @@ export class JobQuery extends Lazy {
     _type;
     _status;
     _jqFilter;
+    _priority;
+    _readyAt;
+    _attempts;
     _order;
     _limit;
     _pageSize;
@@ -173,6 +176,9 @@ export class JobQuery extends Lazy {
         this._type = options.type;
         this._status = options.status;
         this._jqFilter = options.jqFilter;
+        this._priority = options.priority;
+        this._readyAt = options.readyAt;
+        this._attempts = options.attempts;
         this._order = options.order;
         this._limit = options.limit;
         this._pageSize = options.pageSize;
@@ -222,6 +228,53 @@ export class JobQuery extends Lazy {
             jqFilter: concat(this._jqFilter, `(${jqFilter})`).join(" and "),
         });
     }
+    /**
+     * Filter by priority. Replaces any existing priority filter.
+     *
+     * Accepts an exact value (`50`) or a `{min, max}` range with inclusive
+     * bounds. Omit either side for an unbounded end. Lower numbers are
+     * higher priority.
+     *
+     * @example
+     * client.jobs().byPriority(0);                  // exact match
+     * client.jobs().byPriority({ min: 0, max: 100 }); // bounded range
+     * client.jobs().byPriority({ min: 100 });        // 100 or higher
+     * client.jobs().byPriority({ max: 100 });        // 100 or lower
+     */
+    byPriority(priority) {
+        return this.rebuild({ priority });
+    }
+    /**
+     * Filter by `readyAt` (ms since epoch). Replaces any existing filter.
+     *
+     * Accepts an exact value or a `{min, max}` range with inclusive bounds.
+     * Use `Date.prototype.getTime()` to derive ms from a `Date` instance.
+     *
+     * @example
+     * // Eligible to run by now.
+     * client.jobs().byReadyAt({ max: Date.now() });
+     *
+     * // Within the next hour.
+     * client.jobs().byReadyAt({ min: Date.now(), max: Date.now() + 3_600_000 });
+     */
+    byReadyAt(readyAt) {
+        return this.rebuild({ readyAt });
+    }
+    /**
+     * Filter by failure count. Replaces any existing attempts filter.
+     *
+     * Accepts an exact value or a `{min, max}` range with inclusive bounds.
+     * `0` selects jobs that have never failed; `{ min: 1 }` selects anything
+     * that has failed at least once.
+     *
+     * @example
+     * client.jobs().byAttempts(0);                 // never failed
+     * client.jobs().byAttempts({ min: 1 });        // has failed
+     * client.jobs().byAttempts({ min: 1, max: 3 }); // 1, 2, or 3 failures
+     */
+    byAttempts(attempts) {
+        return this.rebuild({ attempts });
+    }
     /**
      * Constrain results by an exact payload match.
      *
@@ -453,6 +506,9 @@ export class JobQuery extends Lazy {
             type: this._type,
             status: this._status,
             filter: this._jqFilter,
+            priority: this._priority,
+            readyAt: this._readyAt,
+            attempts: this._attempts,
             order: this._order,
             limit: effectivePageSize,
         });
@@ -474,6 +530,9 @@ export class JobQuery extends Lazy {
             type: this._type,
             status: this._status,
             filter: this._jqFilter,
+            priority: this._priority,
+            readyAt: this._readyAt,
+            attempts: this._attempts,
         };
     }
     rebuild(overrides) {
@@ -483,6 +542,9 @@ export class JobQuery extends Lazy {
             type: this._type,
             status: this._status,
             jqFilter: this._jqFilter,
+            priority: this._priority,
+            readyAt: this._readyAt,
+            attempts: this._attempts,
             order: this._order,
             limit: this._limit,
             pageSize: this._pageSize,

package/dist/types.d.ts

@@ -161,6 +161,32 @@ export interface TakeOptions {
     /** AbortSignal to cancel the streaming connection. */
     signal?: AbortSignal;
 }
+/**
+ * A range with inclusive bounds. Omit either side for an unbounded end.
+ *
+ * Used by the `priority`, `readyAt`, and `attempts` filter fields. An
+ * empty object (`{}`) is treated as a fully unbounded range.
+ */
+export interface RangeBounds {
+    /** Lower bound, inclusive. Omit for no lower bound. */
+    min?: number;
+    /** Upper bound, inclusive. Omit for no upper bound. */
+    max?: number;
+}
+/**
+ * A range filter that matches either a single value or a span of values.
+ *
+ * Pass a bare `number` for an exact match. Pass an object with `min` and/or
+ * `max` for a range — both bounds are **inclusive**. Omit either side for
+ * an unbounded end.
+ *
+ * @example
+ * priority: 50                   // exactly 50
+ * priority: { min: 0, max: 100 } // 0..100 inclusive
+ * priority: { min: 50 }          // 50 or higher
+ * priority: { max: 100 }         // 100 or lower
+ */
+export type RangeFilter = number | RangeBounds;
 /** Options for listing jobs with cursor-based pagination. */
 export interface ListJobsOptions {
     /** Cursor: start after this job ID (exclusive). */
@@ -177,6 +203,21 @@ export interface ListJobsOptions {
     type?: string | string[];
     /** Filter by job ID. Accepts a single value or an array. */
     id?: string | string[];
+    /**
+     * Filter by priority. Accepts an exact value or a `{min, max}` range
+     * with inclusive bounds. Lower numbers are higher priority.
+     */
+    priority?: RangeFilter;
+    /**
+     * Filter by `readyAt` (milliseconds since the Unix epoch). Accepts an
+     * exact value or a `{min, max}` range with inclusive bounds.
+     */
+    readyAt?: RangeFilter;
+    /**
+     * Filter by failure count. Accepts an exact value or a `{min, max}`
+     * range with inclusive bounds. `0` selects jobs that have never failed.
+     */
+    attempts?: RangeFilter;
     /** jq expression to filter jobs by payload. */
     filter?: string;
 }
@@ -211,6 +252,21 @@ export interface JobFilter {
     queue?: string | string[];
     /** Filter by job type. Accepts a single value or an array. */
     type?: string | string[];
+    /**
+     * Filter by priority. Accepts an exact value or a `{min, max}` range
+     * with inclusive bounds. Lower numbers are higher priority.
+     */
+    priority?: RangeFilter;
+    /**
+     * Filter by `readyAt` (milliseconds since the Unix epoch). Accepts an
+     * exact value or a `{min, max}` range with inclusive bounds.
+     */
+    readyAt?: RangeFilter;
+    /**
+     * Filter by failure count. Accepts an exact value or a `{min, max}`
+     * range with inclusive bounds. `0` selects jobs that have never failed.
+     */
+    attempts?: RangeFilter;
     /** jq expression to filter jobs by payload. */
     filter?: string;
 }

package/package.json

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