@zizq-labs/zizq 0.5.0 → 0.6.0

package/README.md

@@ -12,7 +12,7 @@ This is the official Zizq client library for Node.js, written in TypeScript.
 ## Features
 
 * Concurrent async-based worker
-* Plain handler functions, or composable Job Functions with attached defaults
+* Simple handler functions, or composable `Router`
 * Enqueue and process jobs from one language to another
 * Arbitrary named queues
 * Granular job priorities
@@ -21,7 +21,8 @@ This is the official Zizq client library for Node.js, written in TypeScript.
 * Configurable job retention policies
 * Recurring jobs (cron)
 * Job introspection and management APIs, with support for `jq` query filters
-* Unique jobs
+* Unique jobs (de-duplicated)
+* Batched jobs (folded/merged)
 
 ## Installation
 
@@ -106,7 +107,7 @@ await client.enqueueBulk([
 
 ### Defining handlers
 
-A handler is an `async` function that accepts a `job` and either resolves
+A handler is any `async` function that accepts a `job` and either resolves
 (the worker acks it as successful) or throws (the worker reports a failure
 and the server retries per the backoff policy). The simplest version is a
 `switch` on `job.type`:
@@ -124,38 +125,9 @@ async function handler(job) {
 }
 ```
 
-For a more composable style, the client ships `buildHandler` — pass in your
-job functions and you get back a handler that dispatches on the function
-name. Each function can also carry `zizqOptions` with its own defaults
-(queue, priority, backoff, retention, uniqueness), so enqueuing later only
-needs the payload:
-
-```ts
-import { buildHandler } from "@zizq-labs/zizq";
-
-async function sendEmail(payload, job) {
-  // ...
-}
-sendEmail.zizqOptions = { queue: "emails", priority: 100 };
-
-async function generateReport(payload) {
-  // ...
-}
-generateReport.zizqOptions = { queue: "reports" };
-
-const handler = buildHandler([sendEmail, generateReport]);
-
-// Job functions can be enqueued directly — the queue and other defaults
-// come from the function's zizqOptions.
-await client.enqueue({
-  type: sendEmail,
-  payload: { userId: 42, template: "welcome" },
-});
-```
-
-For cross-language workflows or when you want explicit `type -> handler`
-registration with optional fallback, use `Router`. Routes match by job
-type (a string the producer agrees on with the consumer), and an
+For a more composable style, the client ships a `Router` that implements
+handler registration for named job types with optional fallback. Routes match
+by job type (a string the producer agrees on with the consumer), and an
 optional `fallback` catches anything unmatched:
 
 ```ts
@@ -220,8 +192,6 @@ replacing, and removing entries as the definition changes. Cron requires
 a Pro license on the server.
 
 ```ts
-import { sendDailyDigest } from "./handlers";
-
 await client.cron("maintenance").register({
   timezone: "Europe/London",
   entries: [
@@ -235,7 +205,7 @@ await client.cron("maintenance").register({
     {
       name: "daily_digest",
       expression: "0 9 * * *",
-      type: sendDailyDigest, // Job Functions are accepted directly
+      type: "send_daily_digest",
       payload: {},
     },
   ],

package/dist/batch-config.d.ts

@@ -0,0 +1,64 @@
+import type { EnqueueInput } from "./types.ts";
+/** Options for the third argument of {@link batchConfig}. */
+export interface BatchConfigOptions {
+    /**
+     * Append `| unique` to the fold expression to deduplicate entries
+     * within the batch. `unique` in jq also sorts, so it subsumes
+     * `sorted:` when both are set.
+     */
+    dedup?: boolean;
+    /**
+     * Append `| sort` to the fold expression to sort entries within
+     * the batch. Ignored when `dedup:` is also set.
+     */
+    sorted?: boolean;
+}
+/**
+ * Build a batched-job configuration for a specific target path.
+ *
+ * Returns the `{key, when, fold}` shape expected by
+ * `client.enqueue({batch: ...})`, with `key` as a function that
+ * derives a stable batch key from the enqueue input at call time
+ * (hashing everything *except* the batch target path).
+ *
+ * @param limit  Maximum combined length of the batched value at
+ *   `path` before the current batch is sealed and a new one starts.
+ * @param path  jq path to the batch target within the payload.
+ *   Defaults to `.` (the whole payload is the batch target, assumed
+ *   to be an array).
+ * @param options  `dedup: true` deduplicates via `| unique`;
+ *   `sorted: true` sorts via `| sort`. `dedup:` subsumes `sorted:`.
+ *
+ * @example Whole-payload batch (payload is an array)
+ * ```ts
+ * await client.enqueue({
+ *   type: "audit.events",
+ *   queue: "audit",
+ *   payload: [{ actor: "u1", action: "login" }],
+ *   batch: batchConfig(1000),
+ * });
+ * ```
+ *
+ * @example Batch a specific field
+ * ```ts
+ * await client.enqueue({
+ *   type: "push",
+ *   queue: "push",
+ *   payload: { deviceIds: [id], platform: "apple" },
+ *   batch: batchConfig(100, ".deviceIds"),
+ * });
+ * ```
+ *
+ * @example Custom key (spread + override)
+ * ```ts
+ * batch: {
+ *   ...batchConfig(100, ".deviceIds"),
+ *   key: (input) => `push:tenant-${input.payload.tenantId}`,
+ * }
+ * ```
+ */
+export declare function batchConfig(limit: number, path?: string, options?: BatchConfigOptions): {
+    key: (input: EnqueueInput) => string;
+    when: string;
+    fold: string;
+};

package/dist/batch-config.js

@@ -0,0 +1,76 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * Helper for building batched-job configuration objects. See
+ * {@link batchConfig}.
+ *
+ * @module
+ */
+import { payloadHasher } from "./payload-hasher.js";
+/**
+ * Build a batched-job configuration for a specific target path.
+ *
+ * Returns the `{key, when, fold}` shape expected by
+ * `client.enqueue({batch: ...})`, with `key` as a function that
+ * derives a stable batch key from the enqueue input at call time
+ * (hashing everything *except* the batch target path).
+ *
+ * @param limit  Maximum combined length of the batched value at
+ *   `path` before the current batch is sealed and a new one starts.
+ * @param path  jq path to the batch target within the payload.
+ *   Defaults to `.` (the whole payload is the batch target, assumed
+ *   to be an array).
+ * @param options  `dedup: true` deduplicates via `| unique`;
+ *   `sorted: true` sorts via `| sort`. `dedup:` subsumes `sorted:`.
+ *
+ * @example Whole-payload batch (payload is an array)
+ * ```ts
+ * await client.enqueue({
+ *   type: "audit.events",
+ *   queue: "audit",
+ *   payload: [{ actor: "u1", action: "login" }],
+ *   batch: batchConfig(1000),
+ * });
+ * ```
+ *
+ * @example Batch a specific field
+ * ```ts
+ * await client.enqueue({
+ *   type: "push",
+ *   queue: "push",
+ *   payload: { deviceIds: [id], platform: "apple" },
+ *   batch: batchConfig(100, ".deviceIds"),
+ * });
+ * ```
+ *
+ * @example Custom key (spread + override)
+ * ```ts
+ * batch: {
+ *   ...batchConfig(100, ".deviceIds"),
+ *   key: (input) => `push:tenant-${input.payload.tenantId}`,
+ * }
+ * ```
+ */
+export function batchConfig(limit, path = ".", options = {}) {
+    // `payloadHasher` validates `path` via its jq-path parser and
+    // throws on invalid syntax at construction time — surfacing typos
+    // before any enqueue happens.
+    const key = payloadHasher({ except: [path] });
+    // Pipe-form access (`$var | <path>`) is the uniform shape that
+    // works for every path we accept, including the root `.` case
+    // where `$existing<path>` would otherwise be a syntax error.
+    const when = `(($existing | ${path}) + ($new | ${path})) | length <= ${limit}`;
+    let fold;
+    if (options.dedup) {
+        fold =
+            `$existing | ${path} = ((${path}) + ($new | ${path}) | unique)`;
+    }
+    else if (options.sorted) {
+        fold =
+            `$existing | ${path} = ((${path}) + ($new | ${path}) | sort)`;
+    }
+    else {
+        fold = `$existing | ${path} += ($new | ${path})`;
+    }
+    return { key, when, fold };
+}

package/dist/client.js

@@ -1154,6 +1154,7 @@ function enqueueToApi(opts) {
         retention: opts.retention && retentionToApi(opts.retention),
         unique_key: opts.uniqueKey,
         unique_while: opts.uniqueWhile,
+        batch: opts.batch,
     });
 }
 /**
@@ -1216,6 +1217,8 @@ function jobFromApi(raw) {
         uniqueKey: r.unique_key,
         uniqueWhile: r.unique_while,
         duplicate: r.duplicate,
+        folded: r.folded,
+        batch: r.batch,
     });
 }
 /** Convert an API-format backoff to camelCase. */
@@ -1308,6 +1311,7 @@ function cronJobToApi(job) {
         retention: job.retention && retentionToApi(job.retention),
         unique_key: job.uniqueKey,
         unique_while: job.uniqueWhile,
+        batch: job.batch,
     });
 }
 /** Convert a CronEntryInput to the server's API format. */

package/dist/enqueue.js

@@ -37,6 +37,16 @@ function computeUniqueKey(jobFn, payload) {
         return uniqueKey(jobFn, payload);
     return uniqueKey;
 }
+// Resolve a value that may be either a literal or a function derived
+// from the enqueue input. Used for both `uniqueKey` and `batch.key`
+// on `EnqueueInput` so `payloadHasher(...)` and other userland
+// factories can produce a function that receives the input at call
+// time.
+function resolveKey(value, input) {
+    if (value === undefined)
+        return undefined;
+    return typeof value === "function" ? value(input) : value;
+}
 /**
  * Resolve an EnqueueInput into a low-level EnqueueOptions.
  *
@@ -54,6 +64,7 @@ export function resolveInput(input) {
         if (!jobType) {
             throw new Error("Job function must have a name or zizqOptions.type");
         }
+        warnJobFunctionDeprecated(input.type, jobType);
     }
     else {
         jobType = input.type;
@@ -62,11 +73,18 @@ export function resolveInput(input) {
     if (!queue) {
         throw new Error(`No queue specified for job type "${jobType}"`);
     }
-    const uniqueKey = input.uniqueKey ??
+    const uniqueKey = resolveKey(input.uniqueKey, input) ??
         (typeof input.type === "function"
             ? computeUniqueKey(input.type, input.payload)
             : undefined);
     const uniqueWhile = input.uniqueWhile ?? defaults?.uniqueWhile;
+    const batch = input.batch
+        ? {
+            key: resolveKey(input.batch.key, input),
+            when: input.batch.when,
+            fold: input.batch.fold,
+        }
+        : undefined;
     const opts = {
         type: jobType,
         queue,
@@ -78,6 +96,7 @@ export function resolveInput(input) {
         retention: input.retention,
         uniqueKey,
         uniqueWhile: uniqueKey ? uniqueWhile : undefined,
+        batch,
     };
     // Apply the transform hook (if any). Transforms can change the options based
     // on the payload or other factors, and can mutate `opts` in place, or return
@@ -88,3 +107,18 @@ export function resolveInput(input) {
     }
     return opts;
 }
+// --- Deprecation warnings ---
+// One warning per unique job function, ever. WeakSet so job functions
+// can still be GC'd even after we've warned about them.
+const warnedFunctions = new WeakSet();
+function warnJobFunctionDeprecated(fn, jobType) {
+    if (warnedFunctions.has(fn))
+        return;
+    warnedFunctions.add(fn);
+    process.emitWarning("Job functions are deprecated and will removed in v1.0. " +
+        `Migrate ${jobType} to ` +
+        `client.enqueue({type: '${jobType}', queue: '...', payload: ...}).`, {
+        type: "DeprecationWarning",
+        code: "ZIZQ_JOB_FUNCTIONS_DEPRECATED",
+    });
+}

package/dist/handler.js

@@ -25,6 +25,7 @@ import { Router } from "./router.js";
  *   functions resolve to the same type.
  */
 export function buildHandler(jobs) {
+    warnBuildHandlerDeprecated();
     const seen = new Set();
     const router = new Router();
     for (const fn of jobs) {
@@ -40,3 +41,16 @@ export function buildHandler(jobs) {
     }
     return router.build();
 }
+// --- Deprecation warnings ---
+let warnedBuildHandler = false;
+function warnBuildHandlerDeprecated() {
+    if (warnedBuildHandler)
+        return;
+    warnedBuildHandler = true;
+    process.emitWarning("buildHandler and job functions are deprecated and will be removed in " +
+        "v1.0. Use Router directly (client.enqueue({type: '...', ...}) + a " +
+        "Router-based worker) instead.", {
+        type: "DeprecationWarning",
+        code: "ZIZQ_JOB_FUNCTIONS_DEPRECATED",
+    });
+}

package/dist/index.d.ts

@@ -14,3 +14,7 @@ export { enqueue, enqueueBulk } from "./enqueue.ts";
 export { CronHandle, CronEntryHandle } from "./cron.ts";
 export type { CronEntryDefinition, RegisterCronOptions } from "./cron.ts";
 export { uniqueKey } from "./unique-key.ts";
+export { payloadHasher } from "./payload-hasher.ts";
+export type { PayloadHasherOptions } from "./payload-hasher.ts";
+export { batchConfig } from "./batch-config.ts";
+export type { BatchConfigOptions } from "./batch-config.ts";

package/dist/index.js

@@ -8,3 +8,5 @@ export { Lazy, ErrorQuery, JobQuery } from "./query.js";
 export { enqueue, enqueueBulk } from "./enqueue.js";
 export { CronHandle, CronEntryHandle } from "./cron.js";
 export { uniqueKey } from "./unique-key.js";
+export { payloadHasher } from "./payload-hasher.js";
+export { batchConfig } from "./batch-config.js";

package/dist/payload-hasher.d.ts

@@ -0,0 +1,50 @@
+import type { EnqueueInput } from "./types.ts";
+/** Options for {@link payloadHasher}. */
+export interface PayloadHasherOptions {
+    /**
+     * jq paths whose values participate in the hash. When multiple paths
+     * are supplied their sub-values are hashed together, keyed by path
+     * so ordering doesn't matter. Defaults to `['.']` (whole payload).
+     *
+     * Accepts a single path or an array. Cannot be combined with `except`.
+     */
+    only?: string | string[];
+    /**
+     * jq paths whose values are excluded from the hash. The payload is
+     * deep-cloned and each path is deleted before hashing. Missing paths
+     * are silently ignored.
+     *
+     * Accepts a single path or an array. Cannot be combined with `only`.
+     */
+    except?: string | string[];
+    /**
+     * When `true` (default), the returned key is prefixed with the job
+     * type and a `:`. When `false`, only the raw hex digest is returned.
+     */
+    prefix?: boolean;
+}
+/**
+ * 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 declare function payloadHasher(options?: PayloadHasherOptions): (input: EnqueueInput) => string;

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/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 {};

package/dist/types.d.ts

@@ -13,6 +13,29 @@ export type JobStatus = "ready" | "in_flight" | "scheduled" | "completed" | "dea
 export type SortDirection = "asc" | "desc";
 /** Uniqueness scope for deduplication. */
 export type UniqueScope = "queued" | "active" | "exists";
+/**
+ * Batching configuration for folded jobs.
+ *
+ * When present on an enqueue, subsequent enqueues that share `key` may
+ * be folded into the same pending job's payload. `when` (jq predicate)
+ * decides whether to fold; `fold` (jq reducer) produces the merged
+ * payload. Both run with `$existing` bound to the current pending
+ * payload and `$new` bound to the incoming one.
+ *
+ * Requires a pro license on the server.
+ */
+export interface BatchConfig {
+    /** Identifies the batch. Only one pending batch per key at a time. */
+    key: string;
+    /**
+     * jq predicate deciding whether to fold. Truthy → merge into the
+     * existing batch. Falsy → seal the existing batch and start a fresh
+     * one from this enqueue.
+     */
+    when: string;
+    /** jq expression producing the merged payload when `when` returns true. */
+    fold: string;
+}
 /** Serialisation format for client-server communication. */
 export type Format = "json" | "msgpack";
 /**
@@ -99,6 +122,12 @@ export interface EnqueueOptions {
      * Uniqueness scope. Only valid when `uniqueKey` is set.
      */
     uniqueWhile?: UniqueScope;
+    /**
+     * Batching configuration for folded jobs.
+     *
+     * Requires a pro license on the server.
+     */
+    batch?: BatchConfig;
 }
 /** Options for reporting a job failure. */
 export interface FailureOptions {
@@ -366,8 +395,28 @@ export interface EnqueueInput {
      *
      * The key is global across all queues and job types. Prefix with the job
      * type to make it unique per job type.
+     *
+     * Accepts either a literal string or a function that derives the key
+     * from this enqueue input at call time. The function form is what
+     * `payloadHasher(...)` returns.
      */
-    uniqueKey?: string;
+    uniqueKey?: string | ((input: EnqueueInput) => string);
     /** Uniqueness scope. Only valid when `uniqueKey` is set. */
     uniqueWhile?: UniqueScope;
+    /**
+     * Batching configuration for folded jobs.
+     *
+     * `key` can be either a literal string or a function that derives the
+     * key from this enqueue input at call time. `batchConfig(...)`
+     * returns a value shaped like this with `key` as a function; users
+     * can also spread its result and override `key` with a custom
+     * derivation.
+     *
+     * Requires a pro license on the server.
+     */
+    batch?: {
+        key: string | ((input: EnqueueInput) => string);
+        when: string;
+        fold: string;
+    };
 }

package/dist/unique-key.d.ts

@@ -6,7 +6,6 @@
  *
  * @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.
@@ -24,6 +23,11 @@ import type { JobFunction } from "./handler.ts";
  * that represent the same logical event), write your own plain function
  * with whatever key format you want; it will pass through unchanged.
  *
+ * For the newer `(input) => string` shape used by `client.enqueue({...})`
+ * directly, use {@link payloadHasher} instead — this function is a
+ * `(fn, payload)`-signature adapter around it that fits the
+ * `zizqOptions.uniqueKey` slot on job functions.
+ *
  * @example Unique by specific payload fields
  * ```ts
  * import { uniqueKey } from "@zizq-labs/zizq";
@@ -44,15 +48,3 @@ import type { JobFunction } from "./handler.ts";
  * ```
  */
 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;

package/dist/unique-key.js

@@ -1,14 +1,6 @@
 // Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
 // Licensed under the MIT License. See LICENSE file for details.
-/**
- * Helpers for building unique keys from job payloads.
- *
- * The returned functions are suitable for assigning to `zizqOptions.uniqueKey`
- * on a job function.
- *
- * @module
- */
-import { createHash } from "node:crypto";
+import { payloadHasher } from "./payload-hasher.js";
 /**
  * Build a function that computes a unique key from a subset of the payload.
  *
@@ -25,6 +17,11 @@ import { createHash } from "node:crypto";
  * that represent the same logical event), write your own plain function
  * with whatever key format you want; it will pass through unchanged.
  *
+ * For the newer `(input) => string` shape used by `client.enqueue({...})`
+ * directly, use {@link payloadHasher} instead — this function is a
+ * `(fn, payload)`-signature adapter around it that fits the
+ * `zizqOptions.uniqueKey` slot on job functions.
+ *
  * @example Unique by specific payload fields
  * ```ts
  * import { uniqueKey } from "@zizq-labs/zizq";
@@ -45,78 +42,24 @@ import { createHash } from "node:crypto";
  * ```
  */
 export function uniqueKey(...fields) {
+    const only = fields.length === 0 ? undefined : fields.map((f) => `.${f}`);
+    const hasher = payloadHasher({ only });
     return (fn, payload) => {
         const jobType = fn.zizqOptions?.type ?? fn.name;
         if (!jobType) {
             throw new Error("uniqueKey: job function must have a name or zizqOptions.type");
         }
-        let input;
-        if (fields.length === 0) {
-            input = payload;
-        }
-        else {
-            if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
-                throw new Error(`uniqueKey: cannot pick fields from a non-object payload (got ${payload === null ? "null" : Array.isArray(payload) ? "array" : typeof payload}). Use uniqueKey() with no fields to hash the whole payload, or write a custom resolver.`);
+        if (fields.length > 0) {
+            if (payload === null ||
+                typeof payload !== "object" ||
+                Array.isArray(payload)) {
+                throw new Error(`uniqueKey: cannot pick fields from a non-object payload (got ${payload === null
+                    ? "null"
+                    : Array.isArray(payload)
+                        ? "array"
+                        : typeof payload}). Use uniqueKey() with no fields to hash the whole payload, or write a custom resolver.`);
             }
-            input = pick(payload, fields);
         }
-        // Round-trip through JSON to normalise any exotic values (Dates,
-        // NaN, undefined, BigInt, functions, etc.) and detect circular
-        // references. The result is plain JSON-compatible data.
-        const normalised = JSON.parse(JSON.stringify(input));
-        const hash = createHash("sha256");
-        hashInto(hash, normalised);
-        return `${jobType}:${hash.digest("hex")}`;
+        return hasher({ type: fn, queue: "", payload });
     };
 }
-// --- Internal helpers ---
-/** Extract the given top-level fields from an object, preserving order. */
-function pick(obj, fields) {
-    const result = {};
-    for (const field of fields) {
-        if (field in obj)
-            result[field] = obj[field];
-    }
-    return result;
-}
-/**
- * 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 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("}");
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zizq-labs/zizq",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Node.js client for the Zizq job queue server",
   "homepage": "https://zizq.io",
   "repository": {
@@ -34,7 +34,7 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "test": "node --test --experimental-strip-types 'src/**/*.test.ts'"
+    "test": "node --test --experimental-strip-types --import ./src/test-setup.ts 'src/**/*.test.ts'"
   },
   "engines": {
     "node": ">=22.19"