@zizq-labs/zizq 0.4.2 → 0.6.0

package/dist/payload-hasher.js

@@ -0,0 +1,348 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * Builds a function that derives a stable key from an enqueue input's
+ * payload. Used for both batched-job keys (via `batchConfig`) and as
+ * a first-class option for `uniqueKey`.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+/**
+ * Build a function that hashes some or all of an enqueue's payload
+ * into a stable key string.
+ *
+ * The returned function takes the whole `EnqueueInput` so it can read
+ * both the payload (for hashing) and the type (for the optional
+ * prefix). Suitable for assignment to `uniqueKey` or `batch.key` on
+ * `client.enqueue({...})` inputs.
+ *
+ * @example Full-payload hash with type prefix
+ * ```ts
+ * uniqueKey: payloadHasher()
+ * // => "sendEmail:<sha256>"
+ * ```
+ *
+ * @example Batch by tenant only
+ * ```ts
+ * batch: {
+ *   key: payloadHasher({ except: '.notifications' }),
+ *   when: "...",
+ *   fold: "...",
+ * }
+ * ```
+ */
+export function payloadHasher(options = {}) {
+    const prefix = options.prefix ?? true;
+    const only = options.only !== undefined ? asArray(options.only) : undefined;
+    const except = options.except !== undefined ? asArray(options.except) : undefined;
+    if (only && except) {
+        throw new Error("payloadHasher: `only` and `except` cannot be combined");
+    }
+    // Parse paths once at construction so the returned function has no
+    // parse overhead per call.
+    const onlyPaths = only?.map(parsePath);
+    const exceptPaths = except?.map(parsePath);
+    return (input) => {
+        const value = deriveHashable(input.payload, onlyPaths, exceptPaths);
+        const hash = createHash("sha256");
+        hashInto(hash, value);
+        const digest = hash.digest("hex");
+        if (!prefix)
+            return digest;
+        return `${typeName(input)}:${digest}`;
+    };
+}
+// --- Internal helpers ---
+function asArray(v) {
+    return Array.isArray(v) ? v : [v];
+}
+/**
+ * Return the value that should participate in the hash, given the
+ * caller's `only`/`except` config.
+ */
+function deriveHashable(payload, onlyPaths, exceptPaths) {
+    // Normalise via JSON round-trip so exotic values (Dates, undefined,
+    // functions, etc.) become the plain JSON representation the server
+    // would see. Also detects circular references early.
+    const normalised = JSON.parse(JSON.stringify(payload));
+    if (onlyPaths) {
+        return pickPaths(normalised, onlyPaths);
+    }
+    if (exceptPaths) {
+        let out = normalised;
+        for (const steps of exceptPaths) {
+            out = deletePath(out, steps);
+        }
+        return out;
+    }
+    return normalised;
+}
+/** Sentinel returned by `walk` to distinguish "missing" from "value is null". */
+const MISSING = Symbol("missing");
+/**
+ * Reconstruct a subset of the payload containing only the requested
+ * paths, preserving the original nesting structure. Missing paths are
+ * silently skipped so hashes remain stable across payloads that omit
+ * optional fields.
+ *
+ * `only: ['.a', '.b']` on `{a: 1, b: 2, c: 3}` returns `{a: 1, b: 2}`.
+ * `only: ['.user.id']` on `{user: {id: 42, name: 'x'}}` returns
+ * `{user: {id: 42}}`.
+ */
+function pickPaths(source, paths) {
+    let target = undefined;
+    for (const steps of paths) {
+        if (steps.length === 0)
+            return source; // '.' short-circuits to full payload.
+        const value = walk(source, steps);
+        if (value === MISSING)
+            continue;
+        target = setPath(target, steps, value);
+    }
+    // Never-matched: fall back to an empty object so the hash is total
+    // and matches what an empty pick would produce.
+    return target ?? {};
+}
+/**
+ * Write `value` into `target` at `steps`, creating intermediate
+ * objects/arrays as needed. Returns the (possibly newly-created)
+ * root. The choice between object/array at each level is driven by
+ * whether the *next* step is a key or an index.
+ */
+function setPath(target, steps, value) {
+    const first = steps[0];
+    if (target === undefined) {
+        target = first.kind === "key" ? {} : [];
+    }
+    let cur = target;
+    for (let i = 0; i < steps.length - 1; i++) {
+        const step = steps[i];
+        const next = steps[i + 1];
+        const childInit = next.kind === "key" ? {} : [];
+        if (step.kind === "key") {
+            if (cur[step.name] === undefined)
+                cur[step.name] = childInit;
+            cur = cur[step.name];
+        }
+        else {
+            if (cur[step.index] === undefined)
+                cur[step.index] = childInit;
+            cur = cur[step.index];
+        }
+    }
+    const last = steps[steps.length - 1];
+    if (last.kind === "key")
+        cur[last.name] = value;
+    else
+        cur[last.index] = value;
+    return target;
+}
+/**
+ * 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))`.
+ */
+function hashInto(hash, value) {
+    // Bare number, string, boolean or null. Use JSON repr.
+    if (value === null || typeof value !== "object") {
+        hash.update(JSON.stringify(value));
+        return;
+    }
+    // Arrays hash in the original order, with "[" and "]" markers.
+    // We don't worry about the trailing comma; we just need a stable digest.
+    if (Array.isArray(value)) {
+        hash.update("[");
+        for (const item of value) {
+            hashInto(hash, item);
+            hash.update(",");
+        }
+        hash.update("]");
+        return;
+    }
+    // Objects hash in key-sorted order, with "{" and "}" markers.
+    // We don't worry about the trailing comma; we just need a stable digest.
+    hash.update("{");
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    for (const key of keys) {
+        hash.update(JSON.stringify(key));
+        hash.update(":");
+        hashInto(hash, obj[key]);
+        hash.update(",");
+    }
+    hash.update("}");
+}
+function typeName(input) {
+    if (typeof input.type === "function") {
+        const fn = input.type;
+        const name = fn.zizqOptions?.type ?? fn.name;
+        if (!name) {
+            throw new Error("payloadHasher: job function must have a name or zizqOptions.type");
+        }
+        return name;
+    }
+    return input.type;
+}
+/**
+ * Parse a jq-compatible dotted path into an ordered list of steps.
+ *
+ * Accepted forms:
+ * - `.`               — root (no steps)
+ * - `.foo`            — object key
+ * - `.foo.bar`        — nested keys
+ * - `.foo[0]`         — nth array element
+ * - `.[0]`            — root array index
+ * - `.["dotted.key"]` — quoted key (escape hatch for keys with dots)
+ */
+function parsePath(path) {
+    if (path === ".")
+        return [];
+    if (path === "" || path[0] !== ".") {
+        throw new Error(`payloadHasher: path must start with '.', got "${path}"`);
+    }
+    const steps = [];
+    let i = 1;
+    const n = path.length;
+    while (i < n) {
+        if (path[i] === "[") {
+            // `[N]` or `["quoted key"]`
+            i += 1;
+            if (path[i] === '"') {
+                // Quoted key. Consume until the matching unescaped ".
+                i += 1;
+                let name = "";
+                while (i < n && path[i] !== '"') {
+                    if (path[i] === "\\" && i + 1 < n) {
+                        name += path[i + 1];
+                        i += 2;
+                    }
+                    else {
+                        name += path[i];
+                        i += 1;
+                    }
+                }
+                if (path[i] !== '"') {
+                    throw new Error(`payloadHasher: unterminated quoted key in "${path}"`);
+                }
+                i += 1; // consume "
+                if (path[i] !== "]") {
+                    throw new Error(`payloadHasher: expected ']' in "${path}"`);
+                }
+                i += 1;
+                steps.push({ kind: "key", name });
+            }
+            else {
+                // Numeric index.
+                let digits = "";
+                while (i < n && path[i] >= "0" && path[i] <= "9") {
+                    digits += path[i];
+                    i += 1;
+                }
+                if (digits.length === 0 || path[i] !== "]") {
+                    throw new Error(`payloadHasher: invalid array index in "${path}"`);
+                }
+                i += 1;
+                steps.push({ kind: "index", index: parseInt(digits, 10) });
+            }
+        }
+        else if (path[i] === ".") {
+            i += 1;
+            // Follow-on dot before a name or bracket.
+            continue;
+        }
+        else if (isNameChar(path[i], true)) {
+            let name = "";
+            while (i < n && isNameChar(path[i], false)) {
+                name += path[i];
+                i += 1;
+            }
+            steps.push({ kind: "key", name });
+        }
+        else {
+            throw new Error(`payloadHasher: unexpected character '${path[i]}' in "${path}"`);
+        }
+    }
+    return steps;
+}
+function isNameChar(c, first) {
+    if ((c >= "A" && c <= "Z") || (c >= "a" && c <= "z") || c === "_")
+        return true;
+    if (!first && c >= "0" && c <= "9")
+        return true;
+    return false;
+}
+/**
+ * Follow `steps` and return the sub-value. Returns the `MISSING`
+ * sentinel when any hop is absent (as opposed to a legitimate `null`
+ * at the terminal step). Callers use the sentinel to distinguish
+ * "silently skip this path" from "hash a null here".
+ */
+function walk(value, steps) {
+    let cur = value;
+    for (const step of steps) {
+        if (cur == null)
+            return MISSING;
+        if (step.kind === "key") {
+            if (typeof cur !== "object" || Array.isArray(cur))
+                return MISSING;
+            const obj = cur;
+            if (!(step.name in obj))
+                return MISSING;
+            cur = obj[step.name];
+        }
+        else {
+            if (!Array.isArray(cur) || step.index >= cur.length)
+                return MISSING;
+            cur = cur[step.index];
+        }
+    }
+    return cur;
+}
+/** Return a copy of `value` with the value at `steps` removed. */
+function deletePath(value, steps) {
+    if (steps.length === 0) {
+        // `except: ['.']` — the entire payload is excluded. Nothing left
+        // to hash; return null so we still produce a stable digest
+        // (every call collapses to the same value).
+        return null;
+    }
+    // Walk to the parent of the final step, cloning as we go.
+    const cloned = structuredClone(value);
+    let cur = cloned;
+    for (let i = 0; i < steps.length - 1; i++) {
+        const step = steps[i];
+        if (cur == null)
+            return cloned; // silent no-op
+        if (step.kind === "key") {
+            if (typeof cur !== "object" || Array.isArray(cur))
+                return cloned;
+            cur = cur[step.name];
+        }
+        else {
+            if (!Array.isArray(cur))
+                return cloned;
+            cur = cur[step.index];
+        }
+    }
+    if (cur == null || typeof cur !== "object")
+        return cloned;
+    const last = steps[steps.length - 1];
+    if (last.kind === "key") {
+        if (Array.isArray(cur))
+            return cloned;
+        delete cur[last.name];
+    }
+    else {
+        if (Array.isArray(cur)) {
+            cur.splice(last.index, 1);
+        }
+    }
+    return cloned;
+}

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/resources.d.ts

@@ -7,7 +7,7 @@
  * @module
  */
 import type { Client } from "./client.ts";
-import type { JobStatus, UniqueScope, BackoffConfig, RetentionConfig, EnqueueOptions, FailureOptions, UpdateJobOptions } from "./types.ts";
+import type { JobStatus, UniqueScope, BackoffConfig, BatchConfig, RetentionConfig, EnqueueOptions, FailureOptions, UpdateJobOptions } from "./types.ts";
 import { ErrorQuery, type ErrorQueryOptions } from "./query.ts";
 /** Raw job data shape (camelCase, as returned by the API translation layer). */
 export interface JobData {
@@ -51,6 +51,16 @@ export interface JobData {
     uniqueWhile?: UniqueScope;
     /** True if this job was returned as a duplicate (enqueue responses only). */
     duplicate?: boolean;
+    /**
+     * True if this enqueue was folded into an existing pending batched
+     * job (enqueue responses only).
+     */
+    folded?: boolean;
+    /**
+     * Batching configuration stored on this job. Present only for
+     * batched jobs.
+     */
+    batch?: BatchConfig;
 }
 /**
  * A job returned by the Zizq server.
@@ -108,6 +118,18 @@ export declare class Job {
     readonly uniqueWhile?: UniqueScope;
     /** True if this job was returned as a duplicate (enqueue responses only). */
     readonly duplicate?: boolean;
+    /**
+     * True if this enqueue was folded into an existing pending batched
+     * job (enqueue responses only).
+     */
+    readonly folded?: boolean;
+    /**
+     * Batching configuration stored on this job. Present only for
+     * batched jobs. The first enqueue's `when`/`fold` are the ones
+     * that apply for the life of the batch, so this is the source of
+     * truth for what's being evaluated on subsequent folds.
+     */
+    readonly batch?: BatchConfig;
     /** @internal */
     private client;
     /** @internal */

package/dist/resources.js

@@ -57,6 +57,18 @@ export class Job {
     uniqueWhile;
     /** True if this job was returned as a duplicate (enqueue responses only). */
     duplicate;
+    /**
+     * True if this enqueue was folded into an existing pending batched
+     * job (enqueue responses only).
+     */
+    folded;
+    /**
+     * Batching configuration stored on this job. Present only for
+     * batched jobs. The first enqueue's `when`/`fold` are the ones
+     * that apply for the life of the batch, so this is the source of
+     * truth for what's being evaluated on subsequent folds.
+     */
+    batch;
     /** @internal */
     client;
     /** @internal */
@@ -80,6 +92,8 @@ export class Job {
         this.uniqueKey = data.uniqueKey;
         this.uniqueWhile = data.uniqueWhile;
         this.duplicate = data.duplicate;
+        this.folded = data.folded;
+        this.batch = data.batch;
     }
     /**
      * Return a lazy async iterator over error records for this job.
@@ -147,6 +161,8 @@ export class Job {
             uniqueKey: this.uniqueKey,
             uniqueWhile: this.uniqueWhile,
             duplicate: this.duplicate,
+            folded: this.folded,
+            batch: this.batch,
         };
     }
 }

package/dist/test-setup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test-setup.js

@@ -0,0 +1,30 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * Loaded before every test via `node --import`.
+ *
+ * Suppresses the `ZIZQ_JOB_FUNCTIONS_DEPRECATED` warning during test
+ * runs — the tests that exercise the deprecated code paths still need
+ * to run, and we don't want their output cluttered with the same
+ * migration hint they're validating. Any other warning (Node's own
+ * experimental notices, real deprecations from dependencies) flows
+ * through unchanged.
+ *
+ * @module
+ */
+const SUPPRESSED_CODES = new Set(["ZIZQ_JOB_FUNCTIONS_DEPRECATED"]);
+const originalListeners = process.listeners("warning");
+process.removeAllListeners("warning");
+process.on("warning", (warning) => {
+    if (warning instanceof Error &&
+        "code" in warning &&
+        typeof warning.code === "string" &&
+        SUPPRESSED_CODES.has(warning.code)) {
+        return;
+    }
+    // Re-dispatch to whatever the default handler would have done.
+    for (const listener of originalListeners) {
+        listener(warning);
+    }
+});
+export {};