@zizq-labs/zizq 0.4.0 → 0.4.1

package/README.md

@@ -153,6 +153,34 @@ await client.enqueue({
 });
 ```
 
+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
+optional `fallback` catches anything unmatched:
+
+```ts
+import { Router } from "@zizq-labs/zizq";
+
+const router = new Router()
+  .route("send_email", async (payload, job) => {
+    await mailer.send(payload.to, payload.subject);
+  })
+  .route("generate_report", async (payload) => {
+    await reports.generate(payload.id);
+  })
+  .fallback(async (job) => {
+    console.warn(`Unhandled job type: ${job.type}`);
+  });
+
+const worker = new Worker({ client, handler: router.build() });
+```
+
+Routes overwrite on re-registration, which makes it natural to compose
+routers — e.g. start from one that supplies defaults and selectively
+override individual routes. If no route matches and no fallback is
+registered, the router throws `UnknownJobTypeError`, which the worker
+treats like any other handler failure (retries, eventually dead-lettered).
+
 ### Running a worker
 
 A `Worker` streams jobs from the server, dispatches them through your

package/dist/handler.js

@@ -1,5 +1,6 @@
 // Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
 // Licensed under the MIT License. See LICENSE file for details.
+import { Router } from "./router.js";
 /**
  * Build a `JobHandler` that dispatches incoming jobs to the matching
  * function from an array, looking up by `zizqOptions.type` (or `.name`).
@@ -24,22 +25,18 @@
  *   functions resolve to the same type.
  */
 export function buildHandler(jobs) {
-    const handlers = new Map();
+    const seen = new Set();
+    const router = new Router();
     for (const fn of jobs) {
         const typeName = fn.zizqOptions?.type ?? fn.name;
         if (!typeName) {
             throw new Error("Job function must have a name or zizqOptions.type");
         }
-        if (handlers.has(typeName)) {
+        if (seen.has(typeName)) {
             throw new Error(`Duplicate job type registered: "${typeName}"`);
         }
-        handlers.set(typeName, fn);
+        seen.add(typeName);
+        router.route(typeName, fn);
     }
-    return async (job) => {
-        const fn = handlers.get(job.type);
-        if (!fn) {
-            throw new Error(`No handler registered for job type: ${job.type}`);
-        }
-        await fn(job.payload, job);
-    };
+    return router.build();
 }

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { Worker } from "./worker.ts";
 export type { WorkerOptions, Logger, RequestRetryOptions } from "./worker.ts";
 export { buildHandler } from "./handler.ts";
 export type { JobFunction, JobHandler, ZizqOptions, EnqueueTransform, } from "./handler.ts";
+export { Router, UnknownJobTypeError } from "./router.ts";
+export type { RouteHandler } from "./router.ts";
 export { Lazy, ErrorQuery, JobQuery } from "./query.ts";
 export type { ErrorQueryOptions, JobQueryOptions } from "./query.ts";
 export { enqueue, enqueueBulk } from "./enqueue.ts";

package/dist/index.js

@@ -3,6 +3,7 @@
 export { Client, Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry, ZizqError, ConnectionError, ResponseError, ClientError, NotFoundError, ServerError, } from "./client.js";
 export { Worker } from "./worker.js";
 export { buildHandler } from "./handler.js";
+export { Router, UnknownJobTypeError } from "./router.js";
 export { Lazy, ErrorQuery, JobQuery } from "./query.js";
 export { enqueue, enqueueBulk } from "./enqueue.js";
 export { CronHandle, CronEntryHandle } from "./cron.js";

package/dist/router.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Type-based job dispatch.
+ *
+ * @module
+ */
+import type { Job } from "./resources.ts";
+import type { JobHandler } from "./handler.ts";
+/**
+ * Handler for a specific job type.
+ *
+ * Receives the unwrapped `payload` (the JSON body of the job) along with the
+ * full `Job` for access to metadata like `id`, `type`, or `attempts`. Most
+ * handlers will only need the payload — JS lets you omit the second arg.
+ */
+export type RouteHandler = (
+/**
+ * The payload of the job to be performed, equivalent to `job.payload`.
+ */
+payload: unknown, 
+/**
+ * The full `Job` resource received from the server.
+ */
+job: Job) => Promise<void> | void;
+/**
+ * Thrown when a job arrives with no registered route and no fallback.
+ *
+ * Caught by the worker's normal failure path: the job is nacked for retry,
+ * and eventually dead-lettered once the retry limit is hit.
+ */
+export declare class UnknownJobTypeError extends Error {
+    /**
+     * The name of the unhandled job type.
+     */
+    readonly type: string;
+    constructor(type: string);
+}
+/**
+ * Dispatch jobs by `type` string to registered handler functions.
+ *
+ * Designed for cross-language workflows: payloads are plain JSON values
+ * (objects / arrays / strings / numbers), `type` is a string the producer
+ * agrees on with the consumer, and routes are registered explicitly.
+ *
+ * @example
+ * ```ts
+ * import { Worker, Router } from "@zizq-labs/zizq";
+ *
+ * const router = new Router()
+ *   .route("send_email", async (payload, job) => {
+ *     await mailer.send(payload.to);
+ *   })
+ *   .route("generate_report", async (payload) => {
+ *     await reports.generate(payload.id);
+ *   })
+ *   .fallback(async (job) => {
+ *     console.warn(`Unhandled job type: ${job.type}`);
+ *   });
+ *
+ * const worker = new Worker({ client, handler: router.build() });
+ * ```
+ *
+ * If no route matches and no fallback is registered, the dispatcher throws
+ * `UnknownJobTypeError`, which the worker treats as a normal job failure
+ * (retried per the backoff policy, eventually dead-lettered).
+ */
+export declare class Router {
+    private readonly routes;
+    private fallbackHandler;
+    /**
+     * Register `handler` for jobs whose `type` matches.
+     *
+     * Returns `this` for chaining.
+     *
+     * Re-registering a type replaces the previous handler. This supports
+     * builder-style composition — e.g. starting from a router that supplies
+     * defaults and selectively overriding individual routes.
+     */
+    route(type: string, handler: RouteHandler): this;
+    /**
+     * Register a fallback handler invoked when no route matches.
+     *
+     * Receives the full `Job` (not split into a payload/job pair). Since a
+     * fallback has the same signature as a `JobHandler`, you can delegate
+     * straight to another router's compiled handler:
+     *
+     * ```ts
+     * router.fallback(otherRouter.build());
+     * ```
+     *
+     * Returns `this` for chaining. Calling `fallback` again replaces the
+     * previous handler.
+     */
+    fallback(handler: JobHandler): this;
+    /**
+     * Compile this router into a `JobHandler` suitable for the worker.
+     *
+     * The returned function dispatches each incoming job: routes match by
+     * `job.type`, then the fallback (if any), otherwise throws
+     * `UnknownJobTypeError`.
+     */
+    build(): JobHandler;
+}

package/dist/router.js

@@ -0,0 +1,106 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * Thrown when a job arrives with no registered route and no fallback.
+ *
+ * Caught by the worker's normal failure path: the job is nacked for retry,
+ * and eventually dead-lettered once the retry limit is hit.
+ */
+export class UnknownJobTypeError extends Error {
+    /**
+     * The name of the unhandled job type.
+     */
+    type;
+    constructor(type) {
+        super(`No handler registered for job type "${type}"`);
+        this.name = "UnknownJobTypeError";
+        this.type = type;
+    }
+}
+/**
+ * Dispatch jobs by `type` string to registered handler functions.
+ *
+ * Designed for cross-language workflows: payloads are plain JSON values
+ * (objects / arrays / strings / numbers), `type` is a string the producer
+ * agrees on with the consumer, and routes are registered explicitly.
+ *
+ * @example
+ * ```ts
+ * import { Worker, Router } from "@zizq-labs/zizq";
+ *
+ * const router = new Router()
+ *   .route("send_email", async (payload, job) => {
+ *     await mailer.send(payload.to);
+ *   })
+ *   .route("generate_report", async (payload) => {
+ *     await reports.generate(payload.id);
+ *   })
+ *   .fallback(async (job) => {
+ *     console.warn(`Unhandled job type: ${job.type}`);
+ *   });
+ *
+ * const worker = new Worker({ client, handler: router.build() });
+ * ```
+ *
+ * If no route matches and no fallback is registered, the dispatcher throws
+ * `UnknownJobTypeError`, which the worker treats as a normal job failure
+ * (retried per the backoff policy, eventually dead-lettered).
+ */
+export class Router {
+    routes = new Map();
+    fallbackHandler = null;
+    /**
+     * Register `handler` for jobs whose `type` matches.
+     *
+     * Returns `this` for chaining.
+     *
+     * Re-registering a type replaces the previous handler. This supports
+     * builder-style composition — e.g. starting from a router that supplies
+     * defaults and selectively overriding individual routes.
+     */
+    route(type, handler) {
+        this.routes.set(type, handler);
+        return this;
+    }
+    /**
+     * Register a fallback handler invoked when no route matches.
+     *
+     * Receives the full `Job` (not split into a payload/job pair). Since a
+     * fallback has the same signature as a `JobHandler`, you can delegate
+     * straight to another router's compiled handler:
+     *
+     * ```ts
+     * router.fallback(otherRouter.build());
+     * ```
+     *
+     * Returns `this` for chaining. Calling `fallback` again replaces the
+     * previous handler.
+     */
+    fallback(handler) {
+        this.fallbackHandler = handler;
+        return this;
+    }
+    /**
+     * Compile this router into a `JobHandler` suitable for the worker.
+     *
+     * The returned function dispatches each incoming job: routes match by
+     * `job.type`, then the fallback (if any), otherwise throws
+     * `UnknownJobTypeError`.
+     */
+    build() {
+        const routes = this.routes;
+        const fallback = this.fallbackHandler;
+        return async (job) => {
+            const handler = routes.get(job.type);
+            if (handler) {
+                await handler(job.payload, job);
+                return;
+            }
+            if (fallback) {
+                await fallback(job);
+                return;
+            }
+            throw new UnknownJobTypeError(job.type);
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zizq-labs/zizq",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Node.js client for the Zizq job queue server",
   "homepage": "https://zizq.io",
   "repository": {