@zizq-labs/zizq 0.1.1 → 0.2.0

package/dist/client.d.ts

@@ -545,6 +545,16 @@ export declare class Client {
      * ```
      */
     deleteAllJobs(options?: DeleteAllJobsOptions): Promise<number>;
+    /**
+     * Count jobs matching the given filters.
+     *
+     * @example
+     * ```ts
+     * // Count all ready jobs in the emails queue
+     * const count = await client.countJobs({ queue: "emails", status: "ready" });
+     * ```
+     */
+    countJobs(where?: JobFilter): Promise<number>;
     /**
      * Update a single job's mutable fields.
      *

package/dist/client.js

@@ -292,31 +292,36 @@ export class Client {
         assertOnlyKeys("deleteAllJobs", options, ["where"]);
         const where = options.where ?? {};
         assertOnlyKeys("deleteAllJobs.where", where, ["id", "status", "queue", "type", "filter"]);
-        // Build the multi-value filters first so we can short-circuit if any
-        // resolves to an empty string. An empty filter matches nothing — we
-        // don't want to pass it as "no filter" and accidentally delete everything.
-        const id = where.id != null ? toCommaList(where.id) : undefined;
-        const status = where.status != null ? toCommaList(where.status) : undefined;
-        const queue = where.queue != null ? toCommaList(where.queue) : undefined;
-        const type = where.type != null ? toCommaList(where.type) : undefined;
-        if (id === "" || status === "" || queue === "" || type === "")
+        // 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.
+        const params = buildJobFilter(where);
+        if (isEmptyFilter(params))
             return 0;
-        const params = new URLSearchParams();
-        if (id != null)
-            params.set("id", id);
-        if (status != null)
-            params.set("status", status);
-        if (queue != null)
-            params.set("queue", queue);
-        if (type != null)
-            params.set("type", type);
-        if (where.filter != null)
-            params.set("filter", where.filter);
         const qs = params.toString();
         const path = `/jobs${qs ? "?" + qs : ""}`;
         const data = await this.handleResponse(await this.request("DELETE", path));
         return data.deleted;
     }
+    /**
+     * Count jobs matching the given filters.
+     *
+     * @example
+     * ```ts
+     * // Count all ready jobs in the emails queue
+     * const count = await client.countJobs({ queue: "emails", status: "ready" });
+     * ```
+     */
+    async countJobs(where = {}) {
+        assertOnlyKeys("countJobs", where, ["id", "status", "queue", "type", "filter"]);
+        const params = buildJobFilter(where);
+        if (isEmptyFilter(params))
+            return 0;
+        const qs = params.toString();
+        const path = `/jobs/count${qs ? "?" + qs : ""}`;
+        const data = await this.handleResponse(await this.request("GET", path));
+        return data.count;
+    }
     /**
      * Update a single job's mutable fields.
      *
@@ -361,23 +366,9 @@ export class Client {
         const where = options.where ?? {};
         assertOnlyKeys("updateAllJobs.where", where, ["id", "status", "queue", "type", "filter"]);
         // Same empty-filter short-circuit as deleteAllJobs.
-        const id = where.id != null ? toCommaList(where.id) : undefined;
-        const status = where.status != null ? toCommaList(where.status) : undefined;
-        const queue = where.queue != null ? toCommaList(where.queue) : undefined;
-        const type = where.type != null ? toCommaList(where.type) : undefined;
-        if (id === "" || status === "" || queue === "" || type === "")
+        const params = buildJobFilter(where);
+        if (isEmptyFilter(params))
             return 0;
-        const params = new URLSearchParams();
-        if (id != null)
-            params.set("id", id);
-        if (status != null)
-            params.set("status", status);
-        if (queue != null)
-            params.set("queue", queue);
-        if (type != null)
-            params.set("type", type);
-        if (where.filter != null)
-            params.set("filter", where.filter);
         const qs = params.toString();
         const path = `/jobs${qs ? "?" + qs : ""}`;
         const api = updateToApi(options.apply);
@@ -409,16 +400,9 @@ export class Client {
             params.set("order", options.order);
         if (options.limit != null)
             params.set("limit", String(options.limit));
-        if (options.status)
-            params.set("status", toCommaList(options.status));
-        if (options.queue)
-            params.set("queue", toCommaList(options.queue));
-        if (options.type)
-            params.set("type", toCommaList(options.type));
-        if (options.id)
-            params.set("id", toCommaList(options.id));
-        if (options.filter != null)
-            params.set("filter", options.filter);
+        buildJobFilter(options, params);
+        if (isEmptyFilter(params))
+            return new JobPage(this, [], {});
         const qs = params.toString();
         const path = `/jobs${qs ? "?" + qs : ""}`;
         return this.listJobsByPath(path);
@@ -757,6 +741,34 @@ export class Client {
 function toCommaList(value) {
     return Array.isArray(value) ? value.join(",") : value;
 }
+/**
+ * Returns `true` when any array filter field resolved to an empty comma list,
+ * meaning the filter matches nothing and the caller can short-circuit.
+ *
+ * Call after {@link buildJobFilter} has populated the params.
+ */
+function isEmptyFilter(params) {
+    return (params.get("id") === "" ||
+        params.get("status") === "" ||
+        params.get("queue") === "" ||
+        params.get("type") === "");
+}
+/**
+ * Populate a {@link URLSearchParams} with the standard job filter fields.
+ */
+function buildJobFilter(where, params = new URLSearchParams()) {
+    if (where.id != null)
+        params.set("id", toCommaList(where.id));
+    if (where.status != null)
+        params.set("status", toCommaList(where.status));
+    if (where.queue != null)
+        params.set("queue", toCommaList(where.queue));
+    if (where.type != null)
+        params.set("type", toCommaList(where.type));
+    if (where.filter != null)
+        params.set("filter", where.filter);
+    return params;
+}
 /**
  * Throw if `obj` contains keys not in the allowed list.
  *

package/dist/query.d.ts

@@ -272,6 +272,16 @@ export declare class JobQuery extends Lazy<Job> {
      * Returns 1 if a job was deleted, 0 if no jobs matched.
      */
     deleteOne(): Promise<number>;
+    /**
+     * Count matching jobs using the server-side count endpoint.
+     *
+     * This overrides the base `Lazy.count()` with a single HTTP request to
+     * `GET /jobs/count` instead of paginating through all results.
+     *
+     * When a `limit` is set, caps the server-side count locally with
+     * `Math.min()` rather than paginating.
+     */
+    count(): Promise<number>;
     /**
      * Async iterator over individual jobs.
      *

package/dist/query.js

@@ -402,6 +402,19 @@ export class JobQuery extends Lazy {
     async deleteOne() {
         return this.limit(1).deleteAll();
     }
+    /**
+     * Count matching jobs using the server-side count endpoint.
+     *
+     * This overrides the base `Lazy.count()` with a single HTTP request to
+     * `GET /jobs/count` instead of paginating through all results.
+     *
+     * When a `limit` is set, caps the server-side count locally with
+     * `Math.min()` rather than paginating.
+     */
+    async count() {
+        const total = await this.client.countJobs(this.toWhere());
+        return this._limit != null ? Math.min(total, this._limit) : total;
+    }
     // --- Iteration ---
     /**
      * Async iterator over individual jobs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zizq-labs/zizq",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Node.js client for the Zizq job queue server",
   "homepage": "https://zizq.io",
   "repository": {
@@ -10,7 +10,13 @@
   "bugs": {
     "url": "https://github.com/zizq-labs/zizq-node/issues"
   },
-  "keywords": ["zizq", "job-queue", "background-jobs", "worker", "queue"],
+  "keywords": [
+    "zizq",
+    "job-queue",
+    "background-jobs",
+    "worker",
+    "queue"
+  ],
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",