@zizq-labs/zizq 0.1.0

package/dist/resources.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Typed wrappers over API responses.
+ *
+ * These classes wrap raw API data with a Client reference, providing
+ * action methods and pagination helpers.
+ *
+ * @module
+ */
+import type { Client, JobStatus, UniqueScope, BackoffConfig, RetentionConfig, FailureOptions, UpdateJobOptions } from "./client.ts";
+import { ErrorQuery, type ErrorQueryOptions } from "./query.ts";
+/** Raw job data shape (camelCase, as returned by the API translation layer). */
+export interface JobData {
+    /** Unique job identifier. */
+    id: string;
+    /** Job type, e.g. "send_email". */
+    type: string;
+    /** Queue this job belongs to. */
+    queue: string;
+    /** Priority (0 - 65536, lower number = higher priority). */
+    priority: number;
+    /** Lifecycle status. */
+    status: JobStatus;
+    /**
+     * Arbitrary payload provided by the enqueuer.
+     *
+     * Not present on metadata-only requests.
+     */
+    payload?: unknown;
+    /** When the job becomes eligible to run (ms since Unix epoch). */
+    readyAt: number;
+    /** Number of times this job has been previously attempted. */
+    attempts: number;
+    /** Maximum retries before the job is killed. */
+    retryLimit?: number;
+    /** Per-job backoff configuration. */
+    backoff?: BackoffConfig;
+    /** When the job was last dequeued (ms since Unix epoch). */
+    dequeuedAt?: number;
+    /** When the job last failed (ms since Unix epoch). */
+    failedAt?: number;
+    /** When the job was completed (ms since Unix epoch). */
+    completedAt?: number;
+    /** Per-job retention configuration. */
+    retention?: RetentionConfig;
+    /** When the reaper will hard-delete this job (ms since Unix epoch). */
+    purgeAt?: number;
+    /** Unique key used for enqueue-time deduplication. */
+    uniqueKey?: string;
+    /** Uniqueness scope. */
+    uniqueWhile?: UniqueScope;
+    /** True if this job was returned as a duplicate (enqueue responses only). */
+    duplicate?: boolean;
+}
+/**
+ * A job returned by the Zizq server.
+ *
+ * Provides readonly access to all job fields plus action methods that
+ * operate on this job via the Client.
+ *
+ * @example
+ * ```ts
+ * const job = await client.enqueue({ type: "send_email", queue: "emails", payload: {} });
+ * console.log(job.id, job.status);
+ *
+ * // Mark as complete
+ * await job.complete();
+ * ```
+ */
+export declare class Job {
+    /** Unique job identifier. */
+    readonly id: string;
+    /** Job type, e.g. "send_email". */
+    readonly type: string;
+    /** Queue this job belongs to. */
+    readonly queue: string;
+    /** Priority (0 - 65536, lower number = higher priority). */
+    readonly priority: number;
+    /** Lifecycle status. */
+    readonly status: JobStatus;
+    /**
+     * Arbitrary payload provided by the enqueuer.
+     *
+     * Not present on metadata-only requests.
+     */
+    readonly payload?: unknown;
+    /** When the job becomes eligible to run (ms since Unix epoch). */
+    readonly readyAt: number;
+    /** Number of times this job has been previously attempted. */
+    readonly attempts: number;
+    /** Maximum retries before the job is killed. */
+    readonly retryLimit?: number;
+    /** Per-job backoff configuration. */
+    readonly backoff?: BackoffConfig;
+    /** When the job was last dequeued (ms since Unix epoch). */
+    readonly dequeuedAt?: number;
+    /** When the job last failed (ms since Unix epoch). */
+    readonly failedAt?: number;
+    /** When the job was completed (ms since Unix epoch). */
+    readonly completedAt?: number;
+    /** Per-job retention configuration. */
+    readonly retention?: RetentionConfig;
+    /** When the reaper will hard-delete this job (ms since Unix epoch). */
+    readonly purgeAt?: number;
+    /** Unique key used for enqueue-time deduplication. */
+    readonly uniqueKey?: string;
+    /** Uniqueness scope. */
+    readonly uniqueWhile?: UniqueScope;
+    /** True if this job was returned as a duplicate (enqueue responses only). */
+    readonly duplicate?: boolean;
+    /** @internal */
+    private client;
+    /** @internal */
+    constructor(client: Client, data: JobData);
+    /**
+     * Return a lazy async iterator over error records for this job.
+     *
+     * Supports chainable builder methods for configuring order, limit,
+     * and page size.
+     *
+     * @example
+     * ```ts
+     * for await (const error of job.errors()) {
+     *   console.log(`Attempt ${error.attempt}: ${error.message}`);
+     * }
+     *
+     * // Last 5 errors
+     * const recent = await job.errors({ order: "desc", limit: 5 }).toArray();
+     * ```
+     */
+    errors(options?: ErrorQueryOptions): ErrorQuery;
+    /** Mark this job as successfully completed. */
+    complete(): Promise<void>;
+    /**
+     * Report this job as failed.
+     *
+     * @param options - Error details (message, stack trace, etc.).
+     * @returns The updated job with new status and attempt count.
+     */
+    fail(options: FailureOptions): Promise<Job>;
+    /** Delete this job. */
+    delete(): Promise<void>;
+    /**
+     * Update this job's mutable fields.
+     *
+     * @param options - Fields to update. See `UpdateJobOptions` for null/undefined semantics.
+     * @returns The updated job.
+     */
+    update(options: UpdateJobOptions): Promise<Job>;
+    /** Return the raw job data as a plain object. */
+    toJSON(): JobData;
+}
+/**
+ * A page of jobs returned by `Client.listJobs()`.
+ *
+ * Contains the jobs on this page and methods to navigate to adjacent pages.
+ *
+ * @example
+ * ```ts
+ * let page = await client.listJobs({ queue: ["emails"], limit: 10 });
+ *
+ * while (page) {
+ *   for (const job of page) {
+ *     console.log(job.id, job.status);
+ *   }
+ *   page = await page.nextPage();
+ * }
+ * ```
+ */
+export declare class JobPage {
+    /** The jobs on this page. */
+    readonly jobs: Job[];
+    /** @internal */
+    private client;
+    private nextUrl;
+    private prevUrl;
+    /** @internal */
+    constructor(client: Client, jobs: Job[], pages: {
+        next?: string | null;
+        prev?: string | null;
+    });
+    /** Whether there is a next page. */
+    get hasNext(): boolean;
+    /** Whether there is a previous page. */
+    get hasPrev(): boolean;
+    /** Iterate over the jobs on this page. */
+    [Symbol.iterator](): IterableIterator<Job>;
+    /**
+     * Delete all jobs on this page.
+     *
+     * @returns The number of deleted jobs.
+     */
+    deleteAll(): Promise<number>;
+    /**
+     * Update all jobs on this page.
+     *
+     * @param apply - Fields to update. See `UpdateJobOptions` for null/undefined semantics.
+     * @returns The number of updated jobs.
+     */
+    updateAll(apply: UpdateJobOptions): Promise<number>;
+    /**
+     * Fetch the next page, or `null` if this is the last page.
+     */
+    nextPage(): Promise<JobPage | null>;
+    /**
+     * Fetch the previous page, or `null` if this is the first page.
+     */
+    prevPage(): Promise<JobPage | null>;
+}
+/** Raw error record data (camelCase). */
+export interface ErrorRecordData {
+    /** Which attempt this error corresponds to (1-based). */
+    attempt: number;
+    /** Error message from the worker. */
+    message: string;
+    /** Error class, e.g. "TimeoutError". */
+    errorType?: string;
+    /** Stack trace / backtrace. */
+    backtrace?: string;
+    /** When the job was dequeued for this attempt (ms since Unix epoch). */
+    dequeuedAt: number;
+    /** When the job failed (ms since Unix epoch). */
+    failedAt: number;
+}
+/**
+ * An error record for a failed job attempt.
+ */
+export declare class ErrorRecord {
+    /** Which attempt this error corresponds to (1-based). */
+    readonly attempt: number;
+    /** Error message from the worker. */
+    readonly message: string;
+    /** Error class, e.g. "TimeoutError". */
+    readonly errorType?: string;
+    /** Stack trace / backtrace. */
+    readonly backtrace?: string;
+    /** When the job was dequeued for this attempt (ms since Unix epoch). */
+    readonly dequeuedAt: number;
+    /** When the job failed (ms since Unix epoch). */
+    readonly failedAt: number;
+    /** @internal */
+    constructor(data: ErrorRecordData);
+}
+/**
+ * A page of error records returned by `Client.listErrors()`.
+ *
+ * @example
+ * ```ts
+ * let page = await client.listErrors("job-id");
+ *
+ * for (const error of page) {
+ *   console.log(`Attempt ${error.attempt}: ${error.message}`);
+ * }
+ * ```
+ */
+export declare class ErrorPage {
+    /** The error records on this page. */
+    readonly errors: ErrorRecord[];
+    /** @internal */
+    private client;
+    private nextUrl;
+    private prevUrl;
+    /** @internal */
+    constructor(client: Client, errors: ErrorRecord[], pages: {
+        next?: string | null;
+        prev?: string | null;
+    });
+    /** Whether there is a next page. */
+    get hasNext(): boolean;
+    /** Whether there is a previous page. */
+    get hasPrev(): boolean;
+    /** Iterate over the error records on this page. */
+    [Symbol.iterator](): IterableIterator<ErrorRecord>;
+    /**
+     * Fetch the next page, or `null` if this is the last page.
+     */
+    nextPage(): Promise<ErrorPage | null>;
+    /**
+     * Fetch the previous page, or `null` if this is the first page.
+     */
+    prevPage(): Promise<ErrorPage | null>;
+}

package/dist/resources.js

@@ -0,0 +1,319 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+import { ErrorQuery } from "./query.js";
+// --- Job ---
+/**
+ * A job returned by the Zizq server.
+ *
+ * Provides readonly access to all job fields plus action methods that
+ * operate on this job via the Client.
+ *
+ * @example
+ * ```ts
+ * const job = await client.enqueue({ type: "send_email", queue: "emails", payload: {} });
+ * console.log(job.id, job.status);
+ *
+ * // Mark as complete
+ * await job.complete();
+ * ```
+ */
+export class Job {
+    /** Unique job identifier. */
+    id;
+    /** Job type, e.g. "send_email". */
+    type;
+    /** Queue this job belongs to. */
+    queue;
+    /** Priority (0 - 65536, lower number = higher priority). */
+    priority;
+    /** Lifecycle status. */
+    status;
+    /**
+     * Arbitrary payload provided by the enqueuer.
+     *
+     * Not present on metadata-only requests.
+     */
+    payload;
+    /** When the job becomes eligible to run (ms since Unix epoch). */
+    readyAt;
+    /** Number of times this job has been previously attempted. */
+    attempts;
+    /** Maximum retries before the job is killed. */
+    retryLimit;
+    /** Per-job backoff configuration. */
+    backoff;
+    /** When the job was last dequeued (ms since Unix epoch). */
+    dequeuedAt;
+    /** When the job last failed (ms since Unix epoch). */
+    failedAt;
+    /** When the job was completed (ms since Unix epoch). */
+    completedAt;
+    /** Per-job retention configuration. */
+    retention;
+    /** When the reaper will hard-delete this job (ms since Unix epoch). */
+    purgeAt;
+    /** Unique key used for enqueue-time deduplication. */
+    uniqueKey;
+    /** Uniqueness scope. */
+    uniqueWhile;
+    /** True if this job was returned as a duplicate (enqueue responses only). */
+    duplicate;
+    /** @internal */
+    client;
+    /** @internal */
+    constructor(client, data) {
+        this.client = client;
+        this.id = data.id;
+        this.type = data.type;
+        this.queue = data.queue;
+        this.priority = data.priority;
+        this.status = data.status;
+        this.payload = data.payload;
+        this.readyAt = data.readyAt;
+        this.attempts = data.attempts;
+        this.retryLimit = data.retryLimit;
+        this.backoff = data.backoff;
+        this.dequeuedAt = data.dequeuedAt;
+        this.failedAt = data.failedAt;
+        this.completedAt = data.completedAt;
+        this.retention = data.retention;
+        this.purgeAt = data.purgeAt;
+        this.uniqueKey = data.uniqueKey;
+        this.uniqueWhile = data.uniqueWhile;
+        this.duplicate = data.duplicate;
+    }
+    /**
+     * Return a lazy async iterator over error records for this job.
+     *
+     * Supports chainable builder methods for configuring order, limit,
+     * and page size.
+     *
+     * @example
+     * ```ts
+     * for await (const error of job.errors()) {
+     *   console.log(`Attempt ${error.attempt}: ${error.message}`);
+     * }
+     *
+     * // Last 5 errors
+     * const recent = await job.errors({ order: "desc", limit: 5 }).toArray();
+     * ```
+     */
+    errors(options) {
+        return new ErrorQuery(this.client, this.id, options);
+    }
+    /** Mark this job as successfully completed. */
+    async complete() {
+        return this.client.reportSuccess(this.id);
+    }
+    /**
+     * Report this job as failed.
+     *
+     * @param options - Error details (message, stack trace, etc.).
+     * @returns The updated job with new status and attempt count.
+     */
+    async fail(options) {
+        return this.client.reportFailure(this.id, options);
+    }
+    /** Delete this job. */
+    async delete() {
+        return this.client.deleteJob(this.id);
+    }
+    /**
+     * Update this job's mutable fields.
+     *
+     * @param options - Fields to update. See `UpdateJobOptions` for null/undefined semantics.
+     * @returns The updated job.
+     */
+    async update(options) {
+        return this.client.updateJob(this.id, options);
+    }
+    /** Return the raw job data as a plain object. */
+    toJSON() {
+        return {
+            id: this.id,
+            type: this.type,
+            queue: this.queue,
+            priority: this.priority,
+            status: this.status,
+            payload: this.payload,
+            readyAt: this.readyAt,
+            attempts: this.attempts,
+            retryLimit: this.retryLimit,
+            backoff: this.backoff,
+            dequeuedAt: this.dequeuedAt,
+            failedAt: this.failedAt,
+            completedAt: this.completedAt,
+            retention: this.retention,
+            purgeAt: this.purgeAt,
+            uniqueKey: this.uniqueKey,
+            uniqueWhile: this.uniqueWhile,
+            duplicate: this.duplicate,
+        };
+    }
+}
+// --- JobPage ---
+/**
+ * A page of jobs returned by `Client.listJobs()`.
+ *
+ * Contains the jobs on this page and methods to navigate to adjacent pages.
+ *
+ * @example
+ * ```ts
+ * let page = await client.listJobs({ queue: ["emails"], limit: 10 });
+ *
+ * while (page) {
+ *   for (const job of page) {
+ *     console.log(job.id, job.status);
+ *   }
+ *   page = await page.nextPage();
+ * }
+ * ```
+ */
+export class JobPage {
+    /** The jobs on this page. */
+    jobs;
+    /** @internal */
+    client;
+    nextUrl;
+    prevUrl;
+    /** @internal */
+    constructor(client, jobs, pages) {
+        this.client = client;
+        this.jobs = jobs;
+        this.nextUrl = pages.next ?? null;
+        this.prevUrl = pages.prev ?? null;
+    }
+    /** Whether there is a next page. */
+    get hasNext() {
+        return this.nextUrl !== null;
+    }
+    /** Whether there is a previous page. */
+    get hasPrev() {
+        return this.prevUrl !== null;
+    }
+    /** Iterate over the jobs on this page. */
+    [Symbol.iterator]() {
+        return this.jobs[Symbol.iterator]();
+    }
+    /**
+     * Delete all jobs on this page.
+     *
+     * @returns The number of deleted jobs.
+     */
+    async deleteAll() {
+        const ids = this.jobs.map((j) => j.id);
+        if (ids.length === 0)
+            return 0;
+        return this.client.deleteAllJobs({ where: { id: ids } });
+    }
+    /**
+     * Update all jobs on this page.
+     *
+     * @param apply - Fields to update. See `UpdateJobOptions` for null/undefined semantics.
+     * @returns The number of updated jobs.
+     */
+    async updateAll(apply) {
+        const ids = this.jobs.map((j) => j.id);
+        if (ids.length === 0)
+            return 0;
+        return this.client.updateAllJobs({ where: { id: ids }, apply });
+    }
+    /**
+     * Fetch the next page, or `null` if this is the last page.
+     */
+    async nextPage() {
+        if (!this.nextUrl)
+            return null;
+        return this.client.listJobsByPath(this.nextUrl);
+    }
+    /**
+     * Fetch the previous page, or `null` if this is the first page.
+     */
+    async prevPage() {
+        if (!this.prevUrl)
+            return null;
+        return this.client.listJobsByPath(this.prevUrl);
+    }
+}
+/**
+ * An error record for a failed job attempt.
+ */
+export class ErrorRecord {
+    /** Which attempt this error corresponds to (1-based). */
+    attempt;
+    /** Error message from the worker. */
+    message;
+    /** Error class, e.g. "TimeoutError". */
+    errorType;
+    /** Stack trace / backtrace. */
+    backtrace;
+    /** When the job was dequeued for this attempt (ms since Unix epoch). */
+    dequeuedAt;
+    /** When the job failed (ms since Unix epoch). */
+    failedAt;
+    /** @internal */
+    constructor(data) {
+        this.attempt = data.attempt;
+        this.message = data.message;
+        this.errorType = data.errorType;
+        this.backtrace = data.backtrace;
+        this.dequeuedAt = data.dequeuedAt;
+        this.failedAt = data.failedAt;
+    }
+}
+// --- ErrorPage ---
+/**
+ * A page of error records returned by `Client.listErrors()`.
+ *
+ * @example
+ * ```ts
+ * let page = await client.listErrors("job-id");
+ *
+ * for (const error of page) {
+ *   console.log(`Attempt ${error.attempt}: ${error.message}`);
+ * }
+ * ```
+ */
+export class ErrorPage {
+    /** The error records on this page. */
+    errors;
+    /** @internal */
+    client;
+    nextUrl;
+    prevUrl;
+    /** @internal */
+    constructor(client, errors, pages) {
+        this.client = client;
+        this.errors = errors;
+        this.nextUrl = pages.next ?? null;
+        this.prevUrl = pages.prev ?? null;
+    }
+    /** Whether there is a next page. */
+    get hasNext() {
+        return this.nextUrl !== null;
+    }
+    /** Whether there is a previous page. */
+    get hasPrev() {
+        return this.prevUrl !== null;
+    }
+    /** Iterate over the error records on this page. */
+    [Symbol.iterator]() {
+        return this.errors[Symbol.iterator]();
+    }
+    /**
+     * Fetch the next page, or `null` if this is the last page.
+     */
+    async nextPage() {
+        if (!this.nextUrl)
+            return null;
+        return this.client.listErrorsByPath(this.nextUrl);
+    }
+    /**
+     * Fetch the previous page, or `null` if this is the first page.
+     */
+    async prevPage() {
+        if (!this.prevUrl)
+            return null;
+        return this.client.listErrorsByPath(this.prevUrl);
+    }
+}

package/dist/unique-key.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Helpers for building unique keys from job payloads.
+ *
+ * The returned functions are suitable for assigning to `zizqOptions.uniqueKey`
+ * on a job function.
+ *
+ * @module
+ */
+import { type Hash } from "node:crypto";
+import type { JobFunction } from "./handler.ts";
+/**
+ * Build a function that computes a unique key from a subset of the payload.
+ *
+ * At enqueue time, the named fields are picked from the payload,
+ * round-tripped through `JSON` to normalise any exotic values, hashed
+ * with SHA-256, and prefixed with the job type.
+ *
+ * When no fields are passed, the entire payload is hashed.
+ *
+ * The returned function is assigned to `zizqOptions.uniqueKey` on a job
+ * function. The resolver is called with `(fn, payload)` at enqueue time.
+ *
+ * For cross-type deduplication (e.g. a push notification and an email
+ * that represent the same logical event), write your own plain function
+ * with whatever key format you want; it will pass through unchanged.
+ *
+ * @example Unique by specific payload fields
+ * ```ts
+ * import { uniqueKey } from "@zizq-labs/zizq";
+ *
+ * async function sendEmail(payload) { ... }
+ * sendEmail.zizqOptions = {
+ *   queue: "emails",
+ *   uniqueKey: uniqueKey("userId", "action"),
+ *   uniqueWhile: "queued",
+ * };
+ * ```
+ *
+ * @example Unique by the entire payload
+ * ```ts
+ * sendEmail.zizqOptions = {
+ *   uniqueKey: uniqueKey(),
+ * };
+ * ```
+ */
+export declare function uniqueKey(...fields: string[]): (fn: JobFunction, payload: unknown) => string;
+/**
+ * Stream a JSON-compatible value into a crypto hash as canonical JSON:
+ * object keys sorted, arrays in order, primitives emitted via `JSON.stringify`.
+ *
+ * The resulting byte stream is unambiguous because strings are quoted,
+ * `null`/`true`/`false` are fixed tokens, and commas separate items within
+ * containers (so `[1,2]` and `[12]` hash differently).
+ *
+ * The input must already be normalised JSON data, as from
+ * `JSON.parse(JSON.stringify(x))`.
+ */
+export declare function hashInto(hash: Hash, value: unknown): void;