@zizq-labs/zizq 0.1.0

package/dist/enqueue.d.ts

@@ -0,0 +1,119 @@
+import { Client, type BackoffConfig, Job, type RetentionConfig, type UniqueScope } from "./client.ts";
+import type { JobFunction } from "./handler.ts";
+/**
+ * Input for enqueueing a job.
+ *
+ * The `type` field accepts either a string job type name or a function
+ * reference with optional attached `zizqOptions`. When a function is provided,
+ * its `zizqOptions` supplies defaults for `queue`, `priority`, etc. These
+ * defaults can be overridden by inputs specified at enqueue-time.
+ *
+ * When `type` is a string, `queue` is required in the inputs.
+ *
+ * @example Function reference
+ * ```ts
+ * await enqueue(client, { type: sendEmail, payload: { to: "a@b.com" } });
+ * ```
+ *
+ * @example String type with explicit config
+ * ```ts
+ * await enqueue(client, {
+ *   type: "send_email",
+ *   queue: "emails",
+ *   payload: { to: "a@b.com" },
+ *   priority: 100,
+ * });
+ * ```
+ */
+export interface EnqueueInput {
+    /** Job type — a function reference or a string type name. */
+    type: JobFunction | string;
+    /** Arbitrary payload delivered to the worker. */
+    payload: unknown;
+    /**
+     * Target queue name.
+     *
+     * Required when `type` is a string and no `zizqOptions.queue` default
+     * is available.
+     */
+    queue?: string;
+    /**
+     * Priority (lower = higher priority).
+     *
+     * Valid range is 0 to 65536. Default: 32768.
+     */
+    priority?: number;
+    /**
+     * Timestamp (ms since epoch) when the job becomes eligible.
+     *
+     * When set to a future timestamp the job is created in the "scheduled"
+     * status. Otherwise the job is created in the "ready" status.
+     */
+    readyAt?: number;
+    /**
+     * Per-job retry limit.
+     *
+     * When not set the server default value applies.
+     */
+    retryLimit?: number;
+    /** Per-job backoff configuration. */
+    backoff?: BackoffConfig;
+    /** Per-job retention configuration. */
+    retention?: RetentionConfig;
+    /**
+     * Unique key for enqueue-time deduplication.
+     *
+     * Requires a pro license on the server.
+     *
+     * The key is global across all queues and job types. Prefix with the job
+     * type to make it unique per job type.
+     */
+    uniqueKey?: string;
+    /** Uniqueness scope. Only valid when `uniqueKey` is set. */
+    uniqueWhile?: UniqueScope;
+}
+/**
+ * Enqueue a single job.
+ *
+ * @param client - The Zizq client to use for the HTTP request.
+ * @param input - Job type, payload, and optional configuration.
+ * @returns The created job, including its server-assigned `id` and `status`.
+ *
+ * @example Function reference
+ * ```ts
+ * async function sendEmail(payload) { ... }
+ * sendEmail.zizqOptions = { queue: "emails", priority: 100 };
+ *
+ * const job = await enqueue(client, {
+ *   type: sendEmail,
+ *   payload: { to: "user@example.com" },
+ * });
+ * ```
+ *
+ * @example String type
+ * ```ts
+ * const job = await enqueue(client, {
+ *   type: "send_email",
+ *   queue: "emails",
+ *   payload: { to: "user@example.com" },
+ * });
+ * ```
+ */
+export declare function enqueue(client: Client, input: EnqueueInput): Promise<Job>;
+/**
+ * Enqueue multiple jobs in a single request.
+ *
+ * @param client - The Zizq client to use for the HTTP request.
+ * @param inputs - Array of job inputs.
+ * @returns An array of created jobs in the same order as the input.
+ *
+ * @example
+ * ```ts
+ * const jobs = await enqueueBulk(client, [
+ *   { type: sendEmail, payload: { to: "a@b.com" } },
+ *   { type: sendEmail, payload: { to: "c@d.com" }, priority: 1 },
+ *   { type: "manual_job", queue: "ops", payload: {} },
+ * ]);
+ * ```
+ */
+export declare function enqueueBulk(client: Client, inputs: EnqueueInput[]): Promise<Job[]>;

package/dist/enqueue.js

@@ -0,0 +1,110 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * Enqueue a single job.
+ *
+ * @param client - The Zizq client to use for the HTTP request.
+ * @param input - Job type, payload, and optional configuration.
+ * @returns The created job, including its server-assigned `id` and `status`.
+ *
+ * @example Function reference
+ * ```ts
+ * async function sendEmail(payload) { ... }
+ * sendEmail.zizqOptions = { queue: "emails", priority: 100 };
+ *
+ * const job = await enqueue(client, {
+ *   type: sendEmail,
+ *   payload: { to: "user@example.com" },
+ * });
+ * ```
+ *
+ * @example String type
+ * ```ts
+ * const job = await enqueue(client, {
+ *   type: "send_email",
+ *   queue: "emails",
+ *   payload: { to: "user@example.com" },
+ * });
+ * ```
+ */
+export async function enqueue(client, input) {
+    return client.enqueue(resolveInput(input));
+}
+/**
+ * Enqueue multiple jobs in a single request.
+ *
+ * @param client - The Zizq client to use for the HTTP request.
+ * @param inputs - Array of job inputs.
+ * @returns An array of created jobs in the same order as the input.
+ *
+ * @example
+ * ```ts
+ * const jobs = await enqueueBulk(client, [
+ *   { type: sendEmail, payload: { to: "a@b.com" } },
+ *   { type: sendEmail, payload: { to: "c@d.com" }, priority: 1 },
+ *   { type: "manual_job", queue: "ops", payload: {} },
+ * ]);
+ * ```
+ */
+export async function enqueueBulk(client, inputs) {
+    return client.enqueueBulk(inputs.map(resolveInput));
+}
+// --- Internal ---
+// Compute the unique key from a job function's ZizqOptions + payload.
+//
+// The function form is called with `(jobFn, payload)` so resolvers
+// can read metadata (like the type name) from the job function itself.
+function computeUniqueKey(jobFn, payload) {
+    const uniqueKey = jobFn.zizqOptions?.uniqueKey;
+    if (!uniqueKey)
+        return undefined;
+    if (typeof uniqueKey === "function")
+        return uniqueKey(jobFn, payload);
+    return uniqueKey;
+}
+// Resolve an EnqueueInput into a low-level EnqueueOptions by taking the
+// result of zizqOptions (if provided), optionally transformed, and then
+// merging over the top any overrides present in the input.
+function resolveInput(input) {
+    let jobType;
+    let defaults;
+    if (typeof input.type === "function") {
+        defaults = input.type.zizqOptions;
+        jobType = defaults?.type ?? input.type.name;
+        if (!jobType) {
+            throw new Error("Job function must have a name or zizqOptions.type");
+        }
+    }
+    else {
+        jobType = input.type;
+    }
+    const queue = input.queue ?? defaults?.queue;
+    if (!queue) {
+        throw new Error(`No queue specified for job type "${jobType}"`);
+    }
+    const uniqueKey = input.uniqueKey ??
+        (typeof input.type === "function"
+            ? computeUniqueKey(input.type, input.payload)
+            : undefined);
+    const uniqueWhile = input.uniqueWhile ?? defaults?.uniqueWhile;
+    const opts = {
+        type: jobType,
+        queue,
+        payload: input.payload,
+        priority: input.priority ?? defaults?.priority,
+        readyAt: input.readyAt,
+        retryLimit: input.retryLimit ?? defaults?.retryLimit,
+        backoff: input.backoff ?? defaults?.backoff,
+        retention: input.retention,
+        uniqueKey,
+        uniqueWhile: uniqueKey ? uniqueWhile : undefined,
+    };
+    // 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
+    // a new object to use instead.
+    if (defaults?.transform) {
+        const result = defaults.transform(opts, input.payload);
+        return result ?? opts;
+    }
+    return opts;
+}

package/dist/handler.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Job handler types and configuration.
+ *
+ * These types define how handlers and job functions are structured and
+ * configured. They are used both at enqueue time (to read defaults fro
+ * `zizqOptions`) and when building a handler for the worker (to build the
+ * dispatch table).
+ *
+ * @module
+ */
+import type { BackoffConfig, EnqueueOptions, RetentionConfig, UniqueScope } from "./client.ts";
+import type { Job } from "./resources.ts";
+/**
+ * Configuration that can be attached to a job function via `fn.zizqOptions`.
+ *
+ * These options provide defaults when the function is used with `enqueue()`
+ * or registered with `buildHandler()`. All fields are optional.
+ *
+ * @example
+ * ```ts
+ * async function sendEmail(payload) { ... }
+ *
+ * sendEmail.zizqOptions = {
+ *   queue: "emails",
+ *   priority: 100,
+ *   retryLimit: 5,
+ * };
+ * ```
+ */
+export interface ZizqOptions {
+    /**
+     * Explicit job type name.
+     *
+     * When omitted, the function's `.name` property is used instead. Set this
+     * if the function name could be mangled by minification.
+     */
+    type?: string;
+    /** Default queue for this job. */
+    queue?: string;
+    /** Default priority (lower = higher priority). */
+    priority?: number;
+    /** Default retry limit before the job is killed. */
+    retryLimit?: number;
+    /** Default backoff configuration. */
+    backoff?: BackoffConfig;
+    /** Default retention configuration. */
+    retention?: RetentionConfig;
+    /**
+     * Unique key for deduplication.
+     *
+     * Can be a static string or a function that computes the key from the
+     * job function (for metadata like the type name) and the payload at
+     * enqueue time.
+     *
+     * For common cases, use the `uniqueKey(...fields)` helper from this
+     * module, which returns a resolver that picks fields from the payload
+     * and prefixes the job type automatically.
+     */
+    uniqueKey?: string | ((fn: JobFunction, payload: unknown) => string);
+    /** Uniqueness scope. Only used when `uniqueKey` is set. */
+    uniqueWhile?: UniqueScope;
+    /**
+     * Final transform applied to the resolved enqueue options before it is sent
+     * to the server.
+     *
+     * Receives the fully-resolved `EnqueueOptions` (with defaults and
+     * inline overrides already merged) along with the job payload. The transform
+     * can mutate the options in place, or return a new object.
+     *
+     * Useful for dynamic adjustments that need to see the already-computed
+     * values e.g. lowering priority for "important" payloads relative
+     * to the default priority.
+     *
+     * @example
+     * ```ts
+     * sendEmail.zizqOptions = {
+     *   queue: "emails",
+     *   priority: 100,
+     *   transform: (opts, payload) => {
+     *     if ((payload as any).urgent) {
+     *       opts.priority = Math.floor(opts.priority! / 2);
+     *     }
+     *   },
+     * };
+     * ```
+     *
+     * @example Composing multiple transforms
+     * ```ts
+     * function compose(...transforms: EnqueueTransform[]): EnqueueTransform {
+     *   return (opts, payload) => {
+     *     for (const t of transforms) opts = t(opts, payload);
+     *     return opts;
+     *   };
+     * }
+     *
+     * sendEmail.zizqOptions = {
+     *   transform: compose(doublePriority, tagWithUser),
+     * };
+     * ```
+     */
+    transform?: EnqueueTransform;
+}
+/**
+ * A final transform applied to a resolved enqueue options before it is
+ * sent to the server. May mutate `opts` in place, or return a new optsuest.
+ */
+export type EnqueueTransform = (opts: EnqueueOptions, payload: unknown) => EnqueueOptions | void;
+/**
+ * Top-level function that processes a single job dispatched by the worker.
+ *
+ * Receives the full job, with `job.payload` for the user-supplied payload
+ * and metadata like `job.id`, `job.type`, `job.attempts`, etc.
+ *
+ * This would typically be implemented with an internal lookup table or switch
+ * statement based on the queue/type.
+ *
+ * - Returning (or resolving) normally signals success.
+ * - Throwing (or rejecting) signals failure.
+ */
+export type JobHandler = (job: Job) => Promise<void> | void;
+/**
+ * A user-defined job function.
+ *
+ * Use the `job` argument to access metadata like `id`, `type`, or `attempts`.
+ *
+ * The worker always passes both `payload` and `job`, but most handlers
+ * likely only declare `payload` unless they explicitly need full access to the
+ * job.
+ *
+ * Most handlers only need the payload:
+ *
+ * ```ts
+ * const sendEmail: JobFunction = async (payload) => {
+ *   await mailer.send(payload.to, payload.subject);
+ * };
+ * sendEmail.zizqOptions = { queue: "emails" };
+ * ```
+ *
+ * Handlers that need job metadata can take both:
+ *
+ * ```ts
+ * const retryWithBackoff: JobFunction = async (payload, job) => {
+ *   if (job.attempts > 3) { ... }
+ * };
+ * ```
+ *
+ * Use `buildHandler([...])` to wrap an array of `JobFunction`s
+ * into a single `JobHandler` for the `Worker`.
+ */
+export interface JobFunction {
+    /** Function signature for the handler function. */
+    (payload: unknown, job: Job): Promise<void> | void;
+    /** Optional defaults and configuration for this job */
+    zizqOptions?: ZizqOptions;
+}
+/**
+ * Build a `JobHandler` that dispatches incoming jobs to the matching
+ * function from an array, looking up by `zizqOptions.type` (or `.name`).
+ *
+ * Works with plain JS functions, named functions, and `JobFunction`s with
+ * attached `zizqOptions`. Each function is called with `(payload, job)`.
+ *
+ * @example
+ * ```ts
+ * import { Worker, buildHandler } from "@zizq-labs/zizq";
+ *
+ * async function sendEmail(payload) { ... }
+ * sendEmail.zizqOptions = { queue: "emails" };
+ *
+ * const worker = new Worker({
+ *   client,
+ *   handler: buildHandler([sendEmail, generateReport]),
+ * });
+ * ```
+ *
+ * @throws If any function lacks a name or `zizqOptions.type`, or if two
+ *   functions resolve to the same type.
+ */
+export declare function buildHandler(jobs: JobFunction[]): JobHandler;

package/dist/handler.js

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+/**
+ * Build a `JobHandler` that dispatches incoming jobs to the matching
+ * function from an array, looking up by `zizqOptions.type` (or `.name`).
+ *
+ * Works with plain JS functions, named functions, and `JobFunction`s with
+ * attached `zizqOptions`. Each function is called with `(payload, job)`.
+ *
+ * @example
+ * ```ts
+ * import { Worker, buildHandler } from "@zizq-labs/zizq";
+ *
+ * async function sendEmail(payload) { ... }
+ * sendEmail.zizqOptions = { queue: "emails" };
+ *
+ * const worker = new Worker({
+ *   client,
+ *   handler: buildHandler([sendEmail, generateReport]),
+ * });
+ * ```
+ *
+ * @throws If any function lacks a name or `zizqOptions.type`, or if two
+ *   functions resolve to the same type.
+ */
+export function buildHandler(jobs) {
+    const handlers = new Map();
+    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)) {
+            throw new Error(`Duplicate job type registered: "${typeName}"`);
+        }
+        handlers.set(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);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { Client, Job, JobPage, ErrorRecord, ErrorPage, ZizqError, ConnectionError, ResponseError, ClientError, NotFoundError, ServerError, } from "./client.ts";
+export type { ClientOptions, JobData, EnqueueOptions, ListJobsOptions, JobFilter, DeleteAllJobsOptions, UpdateJobOptions, UpdateAllJobsOptions, ListErrorsOptions, ErrorRecordData, FailureOptions, TakeOptions, BackoffConfig, RetentionConfig, JobStatus, UniqueScope, SortDirection, TlsOptions, Format, } from "./client.ts";
+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 { Lazy, ErrorQuery, JobQuery } from "./query.ts";
+export type { ErrorQueryOptions, JobQueryOptions } from "./query.ts";
+export { enqueue, enqueueBulk } from "./enqueue.ts";
+export type { EnqueueInput } from "./enqueue.ts";
+export { uniqueKey } from "./unique-key.ts";

package/dist/index.js

@@ -0,0 +1,8 @@
+// Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+// Licensed under the MIT License. See LICENSE file for details.
+export { Client, Job, JobPage, ErrorRecord, ErrorPage, ZizqError, ConnectionError, ResponseError, ClientError, NotFoundError, ServerError, } from "./client.js";
+export { Worker } from "./worker.js";
+export { buildHandler } from "./handler.js";
+export { Lazy, ErrorQuery, JobQuery } from "./query.js";
+export { enqueue, enqueueBulk } from "./enqueue.js";
+export { uniqueKey } from "./unique-key.js";