@zizq-labs/zizq 0.1.0

package/dist/query.js

@@ -0,0 +1,653 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+/** Maximum page size the server will accept. */
+const MAX_PAGE_SIZE = 2000;
+// ---------------------------------------------------------------------------
+// Lazy<T>
+// ---------------------------------------------------------------------------
+/**
+ * Base class for lazy, async-iterable collections.
+ *
+ * Subclasses only need to implement `[Symbol.asyncIterator]`. All of the
+ * terminal helpers (`toArray`, `count`, `first`, `isEmpty`, `forEach`) and
+ * the lazy transforms (`map`, `filter`) are provided and work against the
+ * iterator.
+ *
+ * `map` and `filter` return a fresh `Lazy<U>` wrapper so that callers can
+ * continue chaining helpers (e.g. `query.map(...).filter(...).toArray()`)
+ * without having to reach for `[Symbol.asyncIterator]()` or `Array.fromAsync`
+ * manually.
+ */
+export class Lazy {
+    /**
+     * Collect all items into an array.
+     *
+     * Delegates to the built-in `Array.fromAsync()` helper.
+     */
+    async toArray() {
+        return Array.fromAsync(this);
+    }
+    /**
+     * Count all items.
+     *
+     * Iterates lazily, holding only one item at a time in memory. The
+     * underlying iterator is responsible for doing this efficiently — for
+     * paginated queries this means `ceil(N / pageSize)` HTTP requests.
+     */
+    async count() {
+        let n = 0;
+        for await (const _ of this)
+            n++;
+        return n;
+    }
+    /** Return the first item, or `undefined` if the collection is empty. */
+    async first() {
+        for await (const item of this)
+            return item;
+        return undefined;
+    }
+    /** Return `true` if there are no items. */
+    async isEmpty() {
+        return (await this.first()) === undefined;
+    }
+    /** Invoke `fn` for each item, awaiting async results sequentially. */
+    async forEach(fn) {
+        for await (const item of this) {
+            await fn(item);
+        }
+    }
+    /** Lazily transform each item. Returns a new `Lazy`. */
+    map(fn) {
+        return new MappedLazy(this, fn);
+    }
+    /** Lazily keep only items for which `fn` returns a truthy value. */
+    filter(fn) {
+        return new FilteredLazy(this, fn);
+    }
+}
+/** @internal */
+class MappedLazy extends Lazy {
+    source;
+    fn;
+    constructor(source, fn) {
+        super();
+        this.source = source;
+        this.fn = fn;
+    }
+    async *[Symbol.asyncIterator]() {
+        for await (const item of this.source) {
+            yield await this.fn(item);
+        }
+    }
+}
+/** @internal */
+class FilteredLazy extends Lazy {
+    source;
+    fn;
+    constructor(source, fn) {
+        super();
+        this.source = source;
+        this.fn = fn;
+    }
+    async *[Symbol.asyncIterator]() {
+        for await (const item of this.source) {
+            if (await this.fn(item))
+                yield item;
+        }
+    }
+}
+/**
+ * Lazy, paginating query builder for jobs.
+ *
+ * Created by `client.jobs()`. Each builder method returns a new instance
+ * (immutable). Iteration is lazy — no HTTP requests are made until the
+ * iterator is consumed or a terminal method is called.
+ *
+ * Implements `Symbol.asyncIterator`, so a `JobQuery` can be used directly
+ * in `for await...of` loops, or handed to `Array.fromAsync()` (with an
+ * optional mapper). To use the Node 22+ async iterator helpers
+ * (`.map()`, `.filter()`, etc.), obtain the iterator explicitly with
+ * `[Symbol.asyncIterator]()` first — those helpers live on
+ * `AsyncIterator.prototype`, not on async iterables.
+ *
+ * @example Iterating, mapping, and collecting
+ * ```ts
+ * // Plain loop
+ * for await (const job of client.jobs().byQueue("emails")) {
+ *   console.log(job.id);
+ * }
+ *
+ * // Array.fromAsync with a mapper
+ * const ids = await Array.fromAsync(
+ *   client.jobs().byQueue("emails"),
+ *   (job) => job.id,
+ * );
+ *
+ * // Iterator helpers via [Symbol.asyncIterator]()
+ * const urgent = await client.jobs()
+ *   .byQueue("emails")
+ *   [Symbol.asyncIterator]()
+ *   .filter((job) => (job.payload as any).urgent)
+ *   .toArray();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Count ready jobs on a queue (paginates server-side; O(1) memory)
+ * const n = await client.jobs()
+ *   .byQueue("emails")
+ *   .byStatus("ready")
+ *   .count();
+ *
+ * // Move all jobs from one queue to another
+ * await client.jobs().byQueue("old").updateAll({ queue: "new" });
+ *
+ * // Delete dead jobs matching a payload subset
+ * await client.jobs()
+ *   .byStatus("dead")
+ *   .withPayloadSubset({ userId: 42 })
+ *   .deleteAll();
+ *
+ * // Iterate in batches
+ * for await (const page of client.jobs().inPagesOf(100).pages()) {
+ *   for (const job of page.jobs) console.log(job.id);
+ * }
+ * ```
+ */
+export class JobQuery extends Lazy {
+    client;
+    _id;
+    _queue;
+    _type;
+    _status;
+    _jqFilter;
+    _order;
+    _limit;
+    _pageSize;
+    /** @internal */
+    constructor(client, options = {}) {
+        super();
+        this.client = client;
+        this._id = options.id;
+        this._queue = options.queue;
+        this._type = options.type;
+        this._status = options.status;
+        this._jqFilter = options.jqFilter;
+        this._order = options.order;
+        this._limit = options.limit;
+        this._pageSize = options.pageSize;
+    }
+    // --- Filter builders ---
+    /** Filter by job ID. Replaces any existing ID filter. */
+    byId(id) {
+        return this.rebuild({ id });
+    }
+    /** Add an ID to the existing ID filter (unions with existing). */
+    addId(id) {
+        return this.rebuild({ id: concat(this._id, id) });
+    }
+    /** Filter by queue name. Replaces any existing queue filter. */
+    byQueue(queue) {
+        return this.rebuild({ queue });
+    }
+    /** Add a queue to the existing queue filter. */
+    addQueue(queue) {
+        return this.rebuild({ queue: concat(this._queue, queue) });
+    }
+    /** Filter by job type. Replaces any existing type filter. */
+    byType(type) {
+        return this.rebuild({ type });
+    }
+    /** Add a type to the existing type filter. */
+    addType(type) {
+        return this.rebuild({ type: concat(this._type, type) });
+    }
+    /** Filter by status. Replaces any existing status filter. */
+    byStatus(status) {
+        return this.rebuild({ status });
+    }
+    /** Add a status to the existing status filter. */
+    addStatus(status) {
+        return this.rebuild({ status: concat(this._status, status) });
+    }
+    /** Replace the jq payload filter expression. */
+    byJqFilter(jqFilter) {
+        return this.rebuild({ jqFilter });
+    }
+    /**
+     * Add a jq payload filter. Combines with any existing filter via `and`.
+     */
+    addJqFilter(jqFilter) {
+        return this.rebuild({
+            jqFilter: concat(this._jqFilter, `(${jqFilter})`).join(" and "),
+        });
+    }
+    /**
+     * Constrain results by an exact payload match.
+     *
+     * Layers onto any existing jq filter via `and`. The emitted jq
+     * expression is `. == <JSON>`, so matching is structural and
+     * key-order independent (jq's object equality sorts keys).
+     *
+     * This is syntactic sugar around `addJqFilter()` so it can be combined with
+     * other jq filter methods.
+     */
+    withPayload(payload) {
+        return this.addJqFilter(`. == ${JSON.stringify(payload)}`);
+    }
+    /**
+     * Constrain results by a payload subset.
+     *
+     * Layers onto any existing jq filter via `and`. The emitted jq
+     * expression depends on the shape of `payload`:
+     *
+     * - **Objects**: `. | contains(<JSON>)` — deep subset check; every key in
+     *   `payload` must exist in the job payload with a contained value.
+     * - **Arrays**: `.[0:N] == <JSON>` — prefix match against the first `N`
+     *   elements of the job payload.
+     * - **Scalars** (number, string, boolean, null): `. == <JSON>` — equality.
+     *
+     * This is syntactic sugar around `addJqFilter()` so it can be combined with
+     * other jq filter methods.
+     */
+    withPayloadSubset(payload) {
+        return this.addJqFilter(payloadSubsetFilter(payload));
+    }
+    // --- Ordering, limiting, paging ---
+    /** Set the sort order. */
+    order(direction) {
+        return this.rebuild({ order: direction });
+    }
+    /** Reverse the sort order. Defaults to "desc" if no order was set. */
+    reverseOrder() {
+        return this.rebuild({ order: this._order === "desc" ? "asc" : "desc" });
+    }
+    /**
+     * Set the maximum total number of jobs to return across all pages.
+     *
+     * Also caps page fetches and limits the number of jobs touched by
+     * `updateAll` / `deleteAll`.
+     */
+    limit(n) {
+        return this.rebuild({ limit: n });
+    }
+    /**
+     * Set the page size for pagination.
+     *
+     * Affects how many jobs are fetched per HTTP request during iteration,
+     * and also causes `updateAll` / `deleteAll` to batch per page using
+     * ID-scoped bulk operations.
+     */
+    inPagesOf(n) {
+        return this.rebuild({ pageSize: n });
+    }
+    // --- Terminal methods ---
+    /**
+     * Return the first matching job, or `undefined` if none.
+     *
+     * Optimised override: pushes `limit=1` to the server instead of
+     * iterating a full default page.
+     */
+    async first() {
+        for await (const job of this.limit(1)) {
+            return job;
+        }
+        return undefined;
+    }
+    /**
+     * Return the last matching job, or `undefined` if none.
+     *
+     * Optimised: reverses the order and fetches a single job.
+     */
+    async last() {
+        return this.reverseOrder().first();
+    }
+    /**
+     * Update all matching jobs.
+     *
+     * Behaviour depends on whether `limit` or `pageSize` is set:
+     *
+     * - **Unbounded**: a single bulk update request is sent with the query
+     *   filters as the scope.
+     * - **Bounded**: pages are iterated and a separate bulk update is issued
+     *   per page, scoped to both the query filters and the IDs on that page.
+     *   This is safe against races with newly enqueued jobs and lets callers
+     *   throttle large update operations via `inPagesOf`.
+     *
+     * Returns the total number of updated jobs.
+     */
+    async updateAll(apply) {
+        const where = this.toWhere();
+        if (this._limit == null && this._pageSize == null) {
+            return this.client.updateAllJobs({ where, apply });
+        }
+        let remaining = this._limit;
+        let updated = 0;
+        for await (const page of this.pages()) {
+            let ids = page.jobs.map((j) => j.id);
+            if (remaining != null) {
+                if (remaining <= 0)
+                    break;
+                if (ids.length > remaining)
+                    ids = ids.slice(0, remaining);
+            }
+            if (ids.length === 0)
+                continue;
+            updated += await this.client.updateAllJobs({
+                where: { ...where, id: ids },
+                apply,
+            });
+            if (remaining != null) {
+                remaining -= ids.length;
+                if (remaining <= 0)
+                    break;
+            }
+        }
+        return updated;
+    }
+    /**
+     * Update the first matching job.
+     *
+     * Returns 1 if a job was updated, 0 if no jobs matched.
+     */
+    async updateOne(apply) {
+        return this.limit(1).updateAll(apply);
+    }
+    /**
+     * Delete all matching jobs.
+     *
+     * Behaviour depends on whether `limit` or `pageSize` is set:
+     *
+     * - **Unbounded**: a single bulk delete request is sent with the query
+     *   filters as the scope. A query with no filters will delete *all* jobs
+     *   on the server — useful in tests, dangerous in production.
+     * - **Bounded**: pages are iterated and a separate bulk delete is issued
+     *   per page, scoped to both the query filters and the IDs on that page.
+     *
+     * Returns the total number of deleted jobs.
+     */
+    async deleteAll() {
+        const where = this.toWhere();
+        if (this._limit == null && this._pageSize == null) {
+            return this.client.deleteAllJobs({ where });
+        }
+        let remaining = this._limit;
+        let deleted = 0;
+        for await (const page of this.pages()) {
+            let ids = page.jobs.map((j) => j.id);
+            if (remaining != null) {
+                if (remaining <= 0)
+                    break;
+                if (ids.length > remaining)
+                    ids = ids.slice(0, remaining);
+            }
+            if (ids.length === 0)
+                continue;
+            deleted += await this.client.deleteAllJobs({
+                where: { ...where, id: ids },
+            });
+            if (remaining != null) {
+                remaining -= ids.length;
+                if (remaining <= 0)
+                    break;
+            }
+        }
+        return deleted;
+    }
+    /**
+     * Delete the first matching job.
+     *
+     * Returns 1 if a job was deleted, 0 if no jobs matched.
+     */
+    async deleteOne() {
+        return this.limit(1).deleteAll();
+    }
+    // --- Iteration ---
+    /**
+     * Async iterator over individual jobs.
+     *
+     * Lazily paginates through results, respecting `limit` if set. Enables
+     * `for await...of` loops and is also consumable by `Array.fromAsync()`.
+     */
+    async *[Symbol.asyncIterator]() {
+        let remaining = this._limit;
+        for await (const page of this.pages()) {
+            for (const job of page.jobs) {
+                if (remaining != null) {
+                    if (remaining <= 0)
+                        return;
+                    remaining--;
+                }
+                yield job;
+            }
+            if (remaining != null && remaining <= 0)
+                return;
+        }
+    }
+    /**
+     * Async iterator over pages of jobs.
+     *
+     * Each yielded value is a `JobPage`. Useful when you want to process jobs
+     * in batches. Terminates once the query's `limit` has been reached (does
+     * not truncate the final page).
+     */
+    async *pages() {
+        const effectivePageSize = clampPageSize(this._pageSize, this._limit);
+        let remaining = this._limit;
+        let page = await this.client.listJobs({
+            id: this._id,
+            queue: this._queue,
+            type: this._type,
+            status: this._status,
+            filter: this._jqFilter,
+            order: this._order,
+            limit: effectivePageSize,
+        });
+        while (page) {
+            yield page;
+            if (remaining != null) {
+                remaining -= page.jobs.length;
+                if (remaining <= 0)
+                    return;
+            }
+            page = await page.nextPage();
+        }
+    }
+    // --- Internal helpers ---
+    toWhere() {
+        return {
+            id: this._id,
+            queue: this._queue,
+            type: this._type,
+            status: this._status,
+            filter: this._jqFilter,
+        };
+    }
+    rebuild(overrides) {
+        return new JobQuery(this.client, {
+            id: this._id,
+            queue: this._queue,
+            type: this._type,
+            status: this._status,
+            jqFilter: this._jqFilter,
+            order: this._order,
+            limit: this._limit,
+            pageSize: this._pageSize,
+            ...overrides,
+        });
+    }
+}
+/**
+ * Lazy async iterator over error records with a chainable builder API.
+ *
+ * Created by `Job.errors()`. Each builder method returns a new instance
+ * (immutable). Iteration is lazy — no HTTP requests are made until the
+ * iterator is consumed.
+ *
+ * @example
+ * ```ts
+ * // Iterate all errors
+ * for await (const error of job.errors()) {
+ *   console.log(`Attempt ${error.attempt}: ${error.message}`);
+ * }
+ *
+ * // With builder options
+ * const recent = await job.errors()
+ *   .order("desc")
+ *   .limit(5)
+ *   .toArray();
+ * ```
+ */
+export class ErrorQuery extends Lazy {
+    client;
+    jobId;
+    _order;
+    _limit;
+    _pageSize;
+    /** @internal */
+    constructor(client, jobId, options) {
+        super();
+        this.client = client;
+        this.jobId = jobId;
+        this._order = options?.order;
+        this._limit = options?.limit;
+        this._pageSize = options?.pageSize;
+    }
+    /** Set the sort order. Returns a new query. */
+    order(direction) {
+        return this.rebuild({ order: direction });
+    }
+    /**
+     * Set the maximum total number of errors to return across all pages.
+     *
+     * Also used to optimise the page size — if the limit is smaller than
+     * the page size, only the needed amount is fetched.
+     */
+    limit(n) {
+        return this.rebuild({ limit: n });
+    }
+    /** Set the page size for pagination. Returns a new query. */
+    inPagesOf(n) {
+        return this.rebuild({ pageSize: n });
+    }
+    /** Reverse the sort order. Returns a new query. */
+    reverseOrder() {
+        return this.rebuild({ order: this._order === "desc" ? "asc" : "desc" });
+    }
+    /**
+     * Return the first error, or `undefined` if none.
+     *
+     * Optimised override: pushes `limit=1` to the server instead of
+     * iterating a full default page.
+     */
+    async first() {
+        for await (const error of this.limit(1)) {
+            return error;
+        }
+        return undefined;
+    }
+    /**
+     * Return the last error, or `undefined` if none.
+     *
+     * Optimised: reverses the order and fetches a single error.
+     */
+    async last() {
+        return this.reverseOrder().first();
+    }
+    /**
+     * Async iterator over individual error records.
+     *
+     * Lazily paginates through results, respecting `limit` if set.
+     * Enables `for await...of` loops and is consumable by `Array.fromAsync()`.
+     */
+    async *[Symbol.asyncIterator]() {
+        let remaining = this._limit;
+        const effectivePageSize = clampPageSize(this._pageSize, this._limit);
+        let page = await this.client.listErrors(this.jobId, {
+            order: this._order,
+            limit: effectivePageSize,
+        });
+        while (true) {
+            for (const error of page) {
+                if (remaining != null) {
+                    if (remaining <= 0)
+                        return;
+                    remaining--;
+                }
+                yield error;
+            }
+            if (!page.hasNext)
+                return;
+            if (remaining != null && remaining <= 0)
+                return;
+            page = (await page.nextPage());
+        }
+    }
+    /**
+     * Async iterator over pages of error records.
+     *
+     * Each yielded value is an `ErrorPage`. Useful when you want to
+     * process errors in batches.
+     */
+    async *pages() {
+        let remaining = this._limit;
+        const effectivePageSize = clampPageSize(this._pageSize, this._limit);
+        let page = await this.client.listErrors(this.jobId, {
+            order: this._order,
+            limit: effectivePageSize,
+        });
+        while (page) {
+            yield page;
+            if (remaining != null) {
+                remaining -= page.errors.length;
+                if (remaining <= 0)
+                    return;
+            }
+            page = await page.nextPage();
+        }
+    }
+    rebuild(overrides) {
+        return new ErrorQuery(this.client, this.jobId, {
+            order: this._order,
+            limit: this._limit,
+            pageSize: this._pageSize,
+            ...overrides,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Module-local helpers
+// ---------------------------------------------------------------------------
+/**
+ * Compute the effective per-request page size.
+ *
+ * Takes the smallest of the caller-provided `pageSize`, the overall
+ * `limit`, and `MAX_PAGE_SIZE`. Returns `undefined` when none are set,
+ * which lets the server apply its own default.
+ */
+function clampPageSize(pageSize, limit) {
+    const candidates = [pageSize, limit, MAX_PAGE_SIZE].filter((v) => v != null);
+    if (candidates.length === 0)
+        return undefined;
+    return Math.min(...candidates);
+}
+/** Combine two scalar-or-array values into a single flattened array. */
+function concat(existing, next) {
+    return [].concat(existing ?? []).concat(next ?? []);
+}
+/**
+ * Build a jq subset filter for a payload value.
+ *
+ * - Object → `. | contains(<JSON>)`
+ * - Array  → `.[0:N] == <JSON>` (prefix match)
+ * - Scalar → `. == <JSON>`
+ */
+function payloadSubsetFilter(payload) {
+    if (payload === null || typeof payload !== "object") {
+        return `. == ${JSON.stringify(payload)}`;
+    }
+    if (Array.isArray(payload)) {
+        return `.[0:${payload.length}] == ${JSON.stringify(payload)}`;
+    }
+    return `. | contains(${JSON.stringify(payload)})`;
+}