@zizq-labs/zizq 0.4.2 → 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.d.ts

@@ -34,7 +34,7 @@ import { type Dispatcher } from "undici";
 import { Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry } from "./resources.ts";
 import { JobQuery, type JobQueryOptions } from "./query.ts";
 import { CronHandle } from "./cron.ts";
-export type { JobStatus, SortDirection, UniqueScope, BackoffConfig, RetentionConfig, EnqueueOptions, EnqueueInput, FailureOptions, UpdateJobOptions, Format, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions, } from "./types.ts";
+export type { JobStatus, SortDirection, UniqueScope, BackoffConfig, RetentionConfig, EnqueueOptions, EnqueueInput, FailureOptions, UpdateJobOptions, Format, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, RangeBounds, RangeFilter, ReplaceCronGroupOptions, } from "./types.ts";
 import type { EnqueueOptions, EnqueueInput, FailureOptions, UpdateJobOptions, Format, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions } from "./types.ts";
 export { Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry, type JobData, type ErrorRecordData, type CronGroupData, type CronEntryData, } from "./resources.ts";
 /** Response shape for `GET /health`. */

package/dist/client.js

@@ -367,7 +367,7 @@ export class Client {
     async deleteAllJobs(options = {}) {
         assertOnlyKeys("deleteAllJobs", options, ["where"]);
         const where = options.where ?? {};
-        assertOnlyKeys("deleteAllJobs.where", where, ["id", "status", "queue", "type", "filter"]);
+        assertOnlyKeys("deleteAllJobs.where", where, ["id", "status", "queue", "type", "filter", "priority", "readyAt", "attempts"]);
         // Build the filter params, then short-circuit if any array filter resolved
         // to empty — an empty filter matches nothing, and we don't want to
         // accidentally delete everything.
@@ -417,7 +417,7 @@ export class Client {
      * ```
      */
     async countJobs(where = {}) {
-        assertOnlyKeys("countJobs", where, ["id", "status", "queue", "type", "filter"]);
+        assertOnlyKeys("countJobs", where, ["id", "status", "queue", "type", "filter", "priority", "readyAt", "attempts"]);
         const params = buildJobFilter(where);
         if (isEmptyFilter(params))
             return 0;
@@ -468,7 +468,7 @@ export class Client {
     async updateAllJobs(options) {
         assertOnlyKeys("updateAllJobs", options, ["where", "apply"]);
         const where = options.where ?? {};
-        assertOnlyKeys("updateAllJobs.where", where, ["id", "status", "queue", "type", "filter"]);
+        assertOnlyKeys("updateAllJobs.where", where, ["id", "status", "queue", "type", "filter", "priority", "readyAt", "attempts"]);
         // Same empty-filter short-circuit as deleteAllJobs.
         const params = buildJobFilter(where);
         if (isEmptyFilter(params))
@@ -1059,6 +1059,42 @@ function isEmptyFilter(params) {
         params.get("queue") === "" ||
         params.get("type") === "");
 }
+/**
+ * Encode a {@link RangeFilter} value into the server's query syntax.
+ *
+ * The four accepted shapes:
+ *
+ * - `number` (e.g. `50`) -> `"50"`
+ * - `{ min, max }` -> `"min..max"`
+ * - `{ min }` -> `"min.."`
+ * - `{ max }` -> `"..max"`
+ *
+ * Returns `undefined` for `null`/`undefined` so the caller can skip
+ * setting the param. Throws `TypeError` for any other shape (e.g. arrays,
+ * strings, objects with unknown keys).
+ */
+function encodeRange(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError(`range filter value must be a finite number, got ${value}`);
+        }
+        return String(value);
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`range filter must be a number or { min?, max? } object, got ${typeof value}`);
+    }
+    const { min, max } = value;
+    for (const [key, bound] of [["min", min], ["max", max]]) {
+        if (bound != null && (typeof bound !== "number" || !Number.isFinite(bound))) {
+            throw new TypeError(`range filter "${key}" must be a finite number, got ${typeof bound}`);
+        }
+    }
+    const lo = min != null ? String(min) : "";
+    const hi = max != null ? String(max) : "";
+    return `${lo}..${hi}`;
+}
 /**
  * Populate a {@link URLSearchParams} with the standard job filter fields.
  */
@@ -1073,6 +1109,15 @@ function buildJobFilter(where, params = new URLSearchParams()) {
         params.set("type", toCommaList(where.type));
     if (where.filter != null)
         params.set("filter", where.filter);
+    const priority = encodeRange(where.priority);
+    if (priority != null)
+        params.set("priority", priority);
+    const readyAt = encodeRange(where.readyAt);
+    if (readyAt != null)
+        params.set("ready_at", readyAt);
+    const attempts = encodeRange(where.attempts);
+    if (attempts != null)
+        params.set("attempts", attempts);
     return params;
 }
 /**
@@ -1109,6 +1154,7 @@ function enqueueToApi(opts) {
         retention: opts.retention && retentionToApi(opts.retention),
         unique_key: opts.uniqueKey,
         unique_while: opts.uniqueWhile,
+        batch: opts.batch,
     });
 }
 /**
@@ -1171,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. */
@@ -1263,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;