@zizq-labs/zizq 0.1.0

package/dist/query.d.ts

@@ -0,0 +1,372 @@
+/**
+ * Composable, lazy query builders.
+ *
+ * Exposes two chainable, immutable builders:
+ *
+ * - {@link JobQuery} — for filtering, iterating, updating, and deleting
+ *   jobs. Created via `client.jobs()`.
+ * - {@link ErrorQuery} — for iterating error records attached to a job.
+ *   Created via `job.errors()`.
+ *
+ * Both share the same iteration shape (`Symbol.asyncIterator`, `pages()`,
+ * `first()`, `last()`, `toArray()`) and honour `limit` and `inPagesOf`.
+ *
+ * Every builder method returns a new instance, so queries are safe to
+ * share and compose.
+ *
+ * Iteration is lazy: no HTTP requests are made until the async iterator is
+ * consumed or a terminal method is called.
+ *
+ * @module
+ */
+import type { Client, JobStatus, SortDirection, UpdateJobOptions } from "./client.ts";
+import type { Job, JobPage, ErrorRecord, ErrorPage } from "./resources.ts";
+/**
+ * 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 declare abstract class Lazy<T> implements AsyncIterable<T> {
+    abstract [Symbol.asyncIterator](): AsyncGenerator<T>;
+    /**
+     * Collect all items into an array.
+     *
+     * Delegates to the built-in `Array.fromAsync()` helper.
+     */
+    toArray(): Promise<T[]>;
+    /**
+     * 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.
+     */
+    count(): Promise<number>;
+    /** Return the first item, or `undefined` if the collection is empty. */
+    first(): Promise<T | undefined>;
+    /** Return `true` if there are no items. */
+    isEmpty(): Promise<boolean>;
+    /** Invoke `fn` for each item, awaiting async results sequentially. */
+    forEach(fn: (item: T) => void | Promise<void>): Promise<void>;
+    /** Lazily transform each item. Returns a new `Lazy`. */
+    map<U>(fn: (item: T) => U | Promise<U>): Lazy<U>;
+    /** Lazily keep only items for which `fn` returns a truthy value. */
+    filter(fn: (item: T) => boolean | Promise<boolean>): Lazy<T>;
+}
+/** Options for configuring a {@link JobQuery}. */
+export interface JobQueryOptions {
+    /** Filter by job ID. */
+    id?: string | string[];
+    /** Filter by queue name. */
+    queue?: string | string[];
+    /** Filter by job type. */
+    type?: string | string[];
+    /** Filter by status. */
+    status?: JobStatus | JobStatus[];
+    /** jq expression applied to the payload. */
+    jqFilter?: string;
+    /** Sort order. Default: "asc" (oldest first). */
+    order?: SortDirection;
+    /** Maximum total number of jobs to return across all pages. */
+    limit?: number;
+    /** Number of jobs to fetch per page. */
+    pageSize?: number;
+}
+/**
+ * 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 declare class JobQuery extends Lazy<Job> {
+    private client;
+    private _id?;
+    private _queue?;
+    private _type?;
+    private _status?;
+    private _jqFilter?;
+    private _order?;
+    private _limit?;
+    private _pageSize?;
+    /** @internal */
+    constructor(client: Client, options?: JobQueryOptions);
+    /** Filter by job ID. Replaces any existing ID filter. */
+    byId(id: string | string[] | undefined): JobQuery;
+    /** Add an ID to the existing ID filter (unions with existing). */
+    addId(id: string | string[]): JobQuery;
+    /** Filter by queue name. Replaces any existing queue filter. */
+    byQueue(queue: string | string[] | undefined): JobQuery;
+    /** Add a queue to the existing queue filter. */
+    addQueue(queue: string | string[]): JobQuery;
+    /** Filter by job type. Replaces any existing type filter. */
+    byType(type: string | string[] | undefined): JobQuery;
+    /** Add a type to the existing type filter. */
+    addType(type: string | string[]): JobQuery;
+    /** Filter by status. Replaces any existing status filter. */
+    byStatus(status: JobStatus | JobStatus[] | undefined): JobQuery;
+    /** Add a status to the existing status filter. */
+    addStatus(status: JobStatus | JobStatus[]): JobQuery;
+    /** Replace the jq payload filter expression. */
+    byJqFilter(jqFilter: string | undefined): JobQuery;
+    /**
+     * Add a jq payload filter. Combines with any existing filter via `and`.
+     */
+    addJqFilter(jqFilter: string): JobQuery;
+    /**
+     * 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: unknown): JobQuery;
+    /**
+     * 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: unknown): JobQuery;
+    /** Set the sort order. */
+    order(direction: SortDirection): JobQuery;
+    /** Reverse the sort order. Defaults to "desc" if no order was set. */
+    reverseOrder(): JobQuery;
+    /**
+     * 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: number): JobQuery;
+    /**
+     * 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: number): JobQuery;
+    /**
+     * Return the first matching job, or `undefined` if none.
+     *
+     * Optimised override: pushes `limit=1` to the server instead of
+     * iterating a full default page.
+     */
+    first(): Promise<Job | undefined>;
+    /**
+     * Return the last matching job, or `undefined` if none.
+     *
+     * Optimised: reverses the order and fetches a single job.
+     */
+    last(): Promise<Job | undefined>;
+    /**
+     * 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.
+     */
+    updateAll(apply: UpdateJobOptions): Promise<number>;
+    /**
+     * Update the first matching job.
+     *
+     * Returns 1 if a job was updated, 0 if no jobs matched.
+     */
+    updateOne(apply: UpdateJobOptions): Promise<number>;
+    /**
+     * 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.
+     */
+    deleteAll(): Promise<number>;
+    /**
+     * Delete the first matching job.
+     *
+     * Returns 1 if a job was deleted, 0 if no jobs matched.
+     */
+    deleteOne(): Promise<number>;
+    /**
+     * 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()`.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<Job>;
+    /**
+     * 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).
+     */
+    pages(): AsyncGenerator<JobPage>;
+    private toWhere;
+    private rebuild;
+}
+/** Options for configuring an {@link ErrorQuery}. */
+export interface ErrorQueryOptions {
+    /** Sort order. Default: "asc" (oldest first). */
+    order?: SortDirection;
+    /** Maximum total number of errors to return across all pages. */
+    limit?: number;
+    /** Number of errors to fetch per page. */
+    pageSize?: number;
+}
+/**
+ * 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 declare class ErrorQuery extends Lazy<ErrorRecord> {
+    private client;
+    private jobId;
+    private _order?;
+    private _limit?;
+    private _pageSize?;
+    /** @internal */
+    constructor(client: Client, jobId: string, options?: ErrorQueryOptions);
+    /** Set the sort order. Returns a new query. */
+    order(direction: SortDirection): ErrorQuery;
+    /**
+     * 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: number): ErrorQuery;
+    /** Set the page size for pagination. Returns a new query. */
+    inPagesOf(n: number): ErrorQuery;
+    /** Reverse the sort order. Returns a new query. */
+    reverseOrder(): ErrorQuery;
+    /**
+     * Return the first error, or `undefined` if none.
+     *
+     * Optimised override: pushes `limit=1` to the server instead of
+     * iterating a full default page.
+     */
+    first(): Promise<ErrorRecord | undefined>;
+    /**
+     * Return the last error, or `undefined` if none.
+     *
+     * Optimised: reverses the order and fetches a single error.
+     */
+    last(): Promise<ErrorRecord | undefined>;
+    /**
+     * 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()`.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<ErrorRecord>;
+    /**
+     * Async iterator over pages of error records.
+     *
+     * Each yielded value is an `ErrorPage`. Useful when you want to
+     * process errors in batches.
+     */
+    pages(): AsyncGenerator<ErrorPage>;
+    private rebuild;
+}