@zizq-labs/zizq 0.1.0

package/dist/unique-key.js

@@ -0,0 +1,122 @@
+// 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";
+/**
+ * Build a function that computes a unique key from a subset of the payload.
+ *
+ * At enqueue time, the named fields are picked from the payload,
+ * round-tripped through `JSON` to normalise any exotic values, hashed
+ * with SHA-256, and prefixed with the job type.
+ *
+ * When no fields are passed, the entire payload is hashed.
+ *
+ * The returned function is assigned to `zizqOptions.uniqueKey` on a job
+ * function. The resolver is called with `(fn, payload)` at enqueue time.
+ *
+ * For cross-type deduplication (e.g. a push notification and an email
+ * that represent the same logical event), write your own plain function
+ * with whatever key format you want; it will pass through unchanged.
+ *
+ * @example Unique by specific payload fields
+ * ```ts
+ * import { uniqueKey } from "@zizq-labs/zizq";
+ *
+ * async function sendEmail(payload) { ... }
+ * sendEmail.zizqOptions = {
+ *   queue: "emails",
+ *   uniqueKey: uniqueKey("userId", "action"),
+ *   uniqueWhile: "queued",
+ * };
+ * ```
+ *
+ * @example Unique by the entire payload
+ * ```ts
+ * sendEmail.zizqOptions = {
+ *   uniqueKey: uniqueKey(),
+ * };
+ * ```
+ */
+export function uniqueKey(...fields) {
+    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.`);
+            }
+            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")}`;
+    };
+}
+// --- 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/dist/worker.d.ts

@@ -0,0 +1,307 @@
+/**
+ * In-process worker that takes jobs from the Zizq server and dispatches
+ * them to a single handler function.
+ *
+ * The handler can either route jobs manually (e.g. via a `switch` on
+ * `job.type`) or use `buildHandler([...])` to build a dispatcher
+ * from an array of named `JobFunction`s.
+ *
+ * @example Function-based dispatch
+ * ```ts
+ * import { Client, Worker, buildHandler } from "@zizq-labs/zizq";
+ *
+ * async function sendEmail(payload) { ... }
+ * sendEmail.zizqOptions = { queue: "emails" };
+ *
+ * async function generateReport(payload) { ... }
+ * generateReport.zizqOptions = { queue: "reports" };
+ *
+ * const client = new Client({ url: "http://localhost:7890" });
+ * const worker = new Worker({
+ *   client,
+ *   concurrency: 10,
+ *   handler: buildHandler([sendEmail, generateReport]),
+ * });
+ *
+ * // Blocks until stopped.
+ * await worker.run();
+ * ```
+ *
+ * @example Manual dispatch (low-level / cross-language)
+ * ```ts
+ * const worker = new Worker({
+ *   client,
+ *   queues: ["payments"],
+ *   concurrency: 5,
+ *   handler: async (job) => {
+ *     switch (job.type) {
+ *       case "charge_card": return chargeCard(job.payload);
+ *       case "send_receipt": return sendReceipt(job.payload);
+ *       default: throw new Error(`Unknown job type: ${job.type}`);
+ *     }
+ *   },
+ * });
+ *
+ * await worker.run();
+ * ```
+ *
+ * @example Graceful shutdown
+ * ```ts
+ * process.on("SIGTERM", () => worker.stop());
+ * ```
+ *
+ * @module
+ */
+import { Client } from "./client.ts";
+import type { JobHandler } from "./handler.ts";
+/**
+ * Options for constructing a {@link Worker}.
+ */
+export interface WorkerOptions {
+    /** Zizq client instance to use for all server communication. */
+    client: Client;
+    /**
+     * Handler function called for every job received.
+     *
+     * For function-based dispatch (looking up handlers by job type), use
+     * `buildHandler([...])` to build a dispatcher from an array
+     * of `JobFunction`s.
+     *
+     * @example Manual dispatch
+     * ```ts
+     * new Worker({
+     *   client,
+     *   handler: async (job) => {
+     *     switch (job.type) {
+     *       case "charge_card": return chargeCard(job.payload);
+     *     }
+     *   },
+     * });
+     * ```
+     *
+     * @example Function-based dispatch
+     * ```ts
+     * import { buildHandler } from "@zizq-labs/zizq";
+     *
+     * new Worker({
+     *   client,
+     *   handler: buildHandler([sendEmail, generateReport]),
+     * });
+     * ```
+     */
+    handler: JobHandler;
+    /**
+     * Maximum number of jobs to process concurrently.
+     *
+     * Default: 1 (sequential processing).
+     */
+    concurrency?: number;
+    /**
+     * Maximum number of unacknowledged jobs the server will send ahead.
+     *
+     * A higher prefetch than concurrency keeps jobs buffered in the stream
+     * so there's always work ready when a processing slot opens, avoiding
+     * a round-trip delay between finishing a job and starting the next.
+     *
+     * Default: same as `concurrency`.
+     */
+    prefetch?: number;
+    /**
+     * Queues to take jobs from.
+     *
+     * When omitted, the worker takes from all queues.
+     */
+    queues?: string[];
+    /**
+     * Logger for worker diagnostics (retry warnings, unrecoverable errors).
+     *
+     * Must implement at least an `error` method. Any logger that satisfies
+     * this (console, pino, winston, etc.) works out of the box.
+     *
+     * Default: `console`.
+     */
+    logger?: Logger;
+    /**
+     * Retry configuration for transient HTTP failures (connection drops,
+     * server errors). Applies to both the take stream (reconnection) and
+     * ack/nack requests.
+     *
+     * This is unrelated to Zizq's job-level retry/backoff — it controls
+     * how the worker retries its own communication with the server.
+     *
+     * Client errors (4xx) are never retried.
+     */
+    requestRetry?: RequestRetryOptions;
+}
+/**
+ * Configuration for ack/nack retry backoff.
+ *
+ * The delay between retries follows: `min(initialDelay * multiplier^(attempt-1), maxDelay)`.
+ */
+export interface RequestRetryOptions {
+    /**
+     * Initial delay in milliseconds before the first retry.
+     *
+     * Default: 500.
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds between retries.
+     *
+     * Default: 30000 (30 seconds).
+     */
+    maxDelay?: number;
+    /**
+     * Multiplier applied to the delay after each failed attempt.
+     *
+     * Default: 2.
+     */
+    multiplier?: number;
+}
+/** Minimal logger interface used by the worker. */
+export interface Logger {
+    info(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * In-process worker that takes jobs from the Zizq server and dispatches them
+ * to registered handlers.
+ *
+ * Manages concurrency via a prefetch-based flow control model: the server
+ * sends up to `prefetch` unacknowledged jobs, and the worker processes
+ * up to `concurrency` of them concurrently using `Promise.race` to stay
+ * within the limit.
+ *
+ * Jobs that complete successfully are acknowledged automatically. Jobs that
+ * throw are reported as failures (with error message, type, and stack trace),
+ * and the server handles retry scheduling based on the backoff policy.
+ */
+export declare class Worker {
+    private client;
+    private concurrency;
+    private prefetch;
+    private queues;
+    private logger;
+    private retryInitialDelay;
+    private retryMaxDelay;
+    private retryMultiplier;
+    private handler;
+    private abortController;
+    private streamController;
+    private inFlight;
+    private shutdownPromise;
+    private killing;
+    private killDeferred;
+    private pendingAcks;
+    private ackFlushInFlight;
+    private ackFlushPromise;
+    constructor(options: WorkerOptions);
+    /**
+     * Start processing jobs. Blocks until {@link stop} is called.
+     *
+     * Opens a streaming connection to the server's take endpoint and
+     * dispatches incoming jobs to the registered handlers concurrently.
+     *
+     * Automatically reconnects with exponential backoff if the connection
+     * drops or the server is unreachable. The backoff is reset after a
+     * successful connection. Uses the `requestRetry` configuration.
+     *
+     * On shutdown, waits for all in-flight jobs to complete and flushes
+     * pending acks before returning.
+     *
+     * @example
+     * ```ts
+     * const worker = new Worker({ client, jobs: [sendEmail] });
+     *
+     * // In another context (e.g. signal handler):
+     * process.on("SIGTERM", () => worker.stop());
+     *
+     * // Blocks here until stopped.
+     * await worker.run();
+     * ```
+     */
+    run(): Promise<void>;
+    /**
+     * Reset all mutable runtime state so {@link run} can be called
+     * multiple times on the same Worker instance. Called from the top of
+     * {@link run}. Config (client, handler, concurrency, etc.) is
+     * preserved; only per-run state is wiped.
+     */
+    private resetRuntimeState;
+    /**
+     * Async sequence triggered by the shutdown listener when `stop()` or
+     * `kill()` is called. On a graceful stop, drains in-flight jobs and
+     * flushes pending acks before aborting the take stream. On kill, the
+     * drain loop bails out early via the `killing` flag, any pending
+     * acks are dropped, and the stream is (already) aborted by `kill()`
+     * itself.
+     *
+     * The drain loop races `Promise.allSettled(inFlight)` against
+     * `killDeferred.promise` so that a `kill()` call mid-drain wakes the
+     * loop immediately, rather than having to wait for an in-flight
+     * handler to finish before noticing.
+     */
+    private startShutdown;
+    /**
+     * Request a graceful shutdown.
+     *
+     * Stops dispatching new jobs, waits for all in-flight job handlers to
+     * finish, flushes any pending acks, and then aborts the take stream.
+     * {@link run} returns once all of that has drained. `stop` is patient
+     * — there is no internal deadline. If you need to bound how long
+     * shutdown can take, use {@link kill} as an escalation.
+     *
+     * Callable any number of times; subsequent calls are no-ops.
+     */
+    stop(): void;
+    /**
+     * Force an immediate shutdown.
+     *
+     * Aborts the take stream right away and skips the drain + flush
+     * steps. Any in-flight job handlers that are already running will
+     * continue to completion. JavaScript can't cancel promises, but
+     * their acks will not be flushed, so the server will re-queue the
+     * corresponding jobs once the worker disconnects.
+     *
+     * Safe to call after `stop()` has already been called; this is the
+     * deadline-escalation path. A `stop()` drain that's been running too
+     * long will wake up immediately once `kill()` is called, and
+     * {@link run} returns shortly after.
+     */
+    kill(): void;
+    /**
+     * Process a single job: dispatch to the handler, then ack or fail.
+     *
+     * Success acks are batched — the job ID is buffered and a flush is
+     * scheduled via `setImmediate`. This means the worker moves on to
+     * the next job immediately without waiting for the ack round-trip.
+     *
+     * Failures are reported individually (they carry per-job error details)
+     * and are retried on transient errors.
+     */
+    private processJob;
+    /**
+     * Buffer a success ack and schedule a flush.
+     *
+     * If a flush is already in flight, the ack simply accumulates in the
+     * buffer; it will be picked up when the current flush completes and
+     * schedules the next one.
+     */
+    private scheduleAck;
+    /**
+     * Send all buffered acks in a single bulk request.
+     *
+     * After the request completes (or fails with retry), if more acks have
+     * accumulated during the flush, schedule another flush immediately.
+     */
+    private flushAcks;
+    /**
+     * Retry an async operation with exponential backoff for transient errors.
+     *
+     * Client errors (4xx) are not retried — they indicate a permanent problem
+     * with the request. Connection errors and server errors (5xx) are retried
+     * indefinitely with exponential backoff. Retry timing is configured via
+     * `requestRetry` in `WorkerOptions`.
+     */
+    private withRetry;
+}