@zizq-labs/zizq 0.4.2 → 0.6.0

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 {
@@ -161,6 +190,32 @@ export interface TakeOptions {
     /** AbortSignal to cancel the streaming connection. */
     signal?: AbortSignal;
 }
+/**
+ * A range with inclusive bounds. Omit either side for an unbounded end.
+ *
+ * Used by the `priority`, `readyAt`, and `attempts` filter fields. An
+ * empty object (`{}`) is treated as a fully unbounded range.
+ */
+export interface RangeBounds {
+    /** Lower bound, inclusive. Omit for no lower bound. */
+    min?: number;
+    /** Upper bound, inclusive. Omit for no upper bound. */
+    max?: number;
+}
+/**
+ * A range filter that matches either a single value or a span of values.
+ *
+ * Pass a bare `number` for an exact match. Pass an object with `min` and/or
+ * `max` for a range — both bounds are **inclusive**. Omit either side for
+ * an unbounded end.
+ *
+ * @example
+ * priority: 50                   // exactly 50
+ * priority: { min: 0, max: 100 } // 0..100 inclusive
+ * priority: { min: 50 }          // 50 or higher
+ * priority: { max: 100 }         // 100 or lower
+ */
+export type RangeFilter = number | RangeBounds;
 /** Options for listing jobs with cursor-based pagination. */
 export interface ListJobsOptions {
     /** Cursor: start after this job ID (exclusive). */
@@ -177,6 +232,21 @@ export interface ListJobsOptions {
     type?: string | string[];
     /** Filter by job ID. Accepts a single value or an array. */
     id?: string | string[];
+    /**
+     * Filter by priority. Accepts an exact value or a `{min, max}` range
+     * with inclusive bounds. Lower numbers are higher priority.
+     */
+    priority?: RangeFilter;
+    /**
+     * Filter by `readyAt` (milliseconds since the Unix epoch). Accepts an
+     * exact value or a `{min, max}` range with inclusive bounds.
+     */
+    readyAt?: RangeFilter;
+    /**
+     * Filter by failure count. Accepts an exact value or a `{min, max}`
+     * range with inclusive bounds. `0` selects jobs that have never failed.
+     */
+    attempts?: RangeFilter;
     /** jq expression to filter jobs by payload. */
     filter?: string;
 }
@@ -211,6 +281,21 @@ export interface JobFilter {
     queue?: string | string[];
     /** Filter by job type. Accepts a single value or an array. */
     type?: string | string[];
+    /**
+     * Filter by priority. Accepts an exact value or a `{min, max}` range
+     * with inclusive bounds. Lower numbers are higher priority.
+     */
+    priority?: RangeFilter;
+    /**
+     * Filter by `readyAt` (milliseconds since the Unix epoch). Accepts an
+     * exact value or a `{min, max}` range with inclusive bounds.
+     */
+    readyAt?: RangeFilter;
+    /**
+     * Filter by failure count. Accepts an exact value or a `{min, max}`
+     * range with inclusive bounds. `0` selects jobs that have never failed.
+     */
+    attempts?: RangeFilter;
     /** jq expression to filter jobs by payload. */
     filter?: string;
 }
@@ -310,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.4.2",
+  "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"