@zizq-labs/zizq 0.3.0 → 0.3.1

package/README.md

@@ -50,11 +50,11 @@ yarn add @zizq-labs/zizq
 Enqueueing a job.
 
 ```ts
-import { Client, enqueue } from "@zizq-labs/zizq";
+import { Client } from "@zizq-labs/zizq";
 
 const client = new Client({ url: "http://localhost:7890" });
 
-await enqueue(client, {
+await client.enqueue({
   type: "send_email",
   queue: "emails",
   payload: { to: "user@example.com" },

package/dist/client.d.ts

@@ -34,8 +34,8 @@ 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, FailureOptions, UpdateJobOptions, Format, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions, } from "./types.ts";
-import type { EnqueueOptions, 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, 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`. */
 interface HealthResponse {
@@ -164,10 +164,14 @@ export declare class Client {
     /**
      * Enqueue a single job.
      *
+     * The `type` field accepts either a string job type name or a function
+     * reference with attached `zizqOptions`. When a function is provided,
+     * its `zizqOptions` supplies defaults for `queue`, `priority`, etc.
+     *
      * @returns The created job, including its server-assigned `id` and `status`.
      * @throws {ZizqError} If the server rejects the request (e.g. invalid queue name).
      *
-     * @example
+     * @example String type
      * ```ts
      * const job = await client.enqueue({
      *   type: "send_email",
@@ -175,22 +179,51 @@ export declare class Client {
      *   payload: { to: "user@example.com" },
      * });
      * ```
+     *
+     * @example Function reference
+     * ```ts
+     * const job = await client.enqueue({
+     *   type: sendEmail,
+     *   payload: { to: "user@example.com" },
+     * });
+     * ```
      */
-    enqueue(options: EnqueueOptions): Promise<Job>;
+    enqueue(input: EnqueueInput): Promise<Job>;
     /**
      * Enqueue multiple jobs in a single request.
      *
+     * Accepts the same input format as {@link enqueue}, including function
+     * references for the `type` field.
+     *
      * @returns An array of created jobs in the same order as the input.
      *
      * @example
      * ```ts
      * const jobs = await client.enqueueBulk([
-     *   { type: "send_email", queue: "emails", payload: { to: "a@b.com" } },
-     *   { type: "send_email", queue: "emails", payload: { to: "c@d.com" } },
+     *   { type: sendEmail, payload: { to: "a@b.com" } },
+     *   { type: "manual_job", queue: "ops", payload: {} },
      * ]);
      * ```
      */
-    enqueueBulk(jobs: EnqueueOptions[]): Promise<Job[]>;
+    enqueueBulk(inputs: EnqueueInput[]): Promise<Job[]>;
+    /**
+     * Enqueue a single job using raw, fully-resolved options.
+     *
+     * Prefer {@link enqueue} for most use cases. This method is useful when
+     * you have already resolved function references or need direct control
+     * over the options object.
+     *
+     * @returns The created job, including its server-assigned `id` and `status`.
+     */
+    enqueueRaw(options: EnqueueOptions): Promise<Job>;
+    /**
+     * Enqueue multiple jobs using raw, fully-resolved options.
+     *
+     * Prefer {@link enqueueBulk} for most use cases.
+     *
+     * @returns An array of created jobs in the same order as the input.
+     */
+    enqueueBulkRaw(jobs: EnqueueOptions[]): Promise<Job[]>;
     /**
      * Acknowledge a job as successfully completed.
      *

package/dist/client.js

@@ -37,6 +37,7 @@ import { encode as msgpackEncode, decode as msgpackDecode } from "@msgpack/msgpa
 import { Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry, } from "./resources.js";
 import { JobQuery } from "./query.js";
 import { CronHandle } from "./cron.js";
+import { resolveInput } from "./enqueue.js";
 // Re-export resource types so consumers can import from client.ts.
 export { Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry, } from "./resources.js";
 /** Base error class for all Zizq errors. */
@@ -179,10 +180,14 @@ export class Client {
     /**
      * Enqueue a single job.
      *
+     * The `type` field accepts either a string job type name or a function
+     * reference with attached `zizqOptions`. When a function is provided,
+     * its `zizqOptions` supplies defaults for `queue`, `priority`, etc.
+     *
      * @returns The created job, including its server-assigned `id` and `status`.
      * @throws {ZizqError} If the server rejects the request (e.g. invalid queue name).
      *
-     * @example
+     * @example String type
      * ```ts
      * const job = await client.enqueue({
      *   type: "send_email",
@@ -190,25 +195,58 @@ export class Client {
      *   payload: { to: "user@example.com" },
      * });
      * ```
+     *
+     * @example Function reference
+     * ```ts
+     * const job = await client.enqueue({
+     *   type: sendEmail,
+     *   payload: { to: "user@example.com" },
+     * });
+     * ```
      */
-    async enqueue(options) {
-        const api = enqueueToApi(options);
-        return this.wrapJob(await this.handleResponse(await this.post("/jobs", api)));
+    async enqueue(input) {
+        return this.enqueueRaw(resolveInput(input));
     }
     /**
      * Enqueue multiple jobs in a single request.
      *
+     * Accepts the same input format as {@link enqueue}, including function
+     * references for the `type` field.
+     *
      * @returns An array of created jobs in the same order as the input.
      *
      * @example
      * ```ts
      * const jobs = await client.enqueueBulk([
-     *   { type: "send_email", queue: "emails", payload: { to: "a@b.com" } },
-     *   { type: "send_email", queue: "emails", payload: { to: "c@d.com" } },
+     *   { type: sendEmail, payload: { to: "a@b.com" } },
+     *   { type: "manual_job", queue: "ops", payload: {} },
      * ]);
      * ```
      */
-    async enqueueBulk(jobs) {
+    async enqueueBulk(inputs) {
+        return this.enqueueBulkRaw(inputs.map(resolveInput));
+    }
+    /**
+     * Enqueue a single job using raw, fully-resolved options.
+     *
+     * Prefer {@link enqueue} for most use cases. This method is useful when
+     * you have already resolved function references or need direct control
+     * over the options object.
+     *
+     * @returns The created job, including its server-assigned `id` and `status`.
+     */
+    async enqueueRaw(options) {
+        const api = enqueueToApi(options);
+        return this.wrapJob(await this.handleResponse(await this.post("/jobs", api)));
+    }
+    /**
+     * Enqueue multiple jobs using raw, fully-resolved options.
+     *
+     * Prefer {@link enqueueBulk} for most use cases.
+     *
+     * @returns An array of created jobs in the same order as the input.
+     */
+    async enqueueBulkRaw(jobs) {
         const api = { jobs: jobs.map(enqueueToApi) };
         const data = await this.handleResponse(await this.post("/jobs/bulk", api));
         return data.jobs.map((j) => this.wrapJob(j));

package/dist/cron.d.ts

@@ -8,8 +8,7 @@
  */
 import type { Client } from "./client.ts";
 import type { CronGroup, CronEntry } from "./resources.ts";
-import type { EnqueueOptions } from "./types.ts";
-import { type EnqueueInput } from "./enqueue.ts";
+import type { EnqueueOptions, EnqueueInput } from "./types.ts";
 /**
  * A cron entry definition that accepts function references for the job type.
  *

package/dist/enqueue.d.ts

@@ -1,120 +1,25 @@
-import { Client, type BackoffConfig, type EnqueueOptions, 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;
-}
+import type { EnqueueOptions, EnqueueInput } from "./types.ts";
+import type { Client } from "./client.ts";
+import type { Job } from "./resources.ts";
+export type { EnqueueInput } from "./types.ts";
 /**
  * Enqueue a single job.
  *
+ * @deprecated Use `client.enqueue()` instead.
+ *
  * @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.
  *
+ * @deprecated Use `client.enqueueBulk()` instead.
+ *
  * @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

@@ -3,51 +3,26 @@
 /**
  * Enqueue a single job.
  *
+ * @deprecated Use `client.enqueue()` instead.
+ *
  * @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));
+    return client.enqueue(input);
 }
 /**
  * Enqueue multiple jobs in a single request.
  *
+ * @deprecated Use `client.enqueueBulk()` instead.
+ *
  * @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));
+    return client.enqueueBulk(inputs);
 }
 // --- Internal ---
 // Compute the unique key from a job function's ZizqOptions + payload.

package/dist/handler.d.ts

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { BackoffConfig, EnqueueOptions, RetentionConfig, UniqueScope } from "./client.ts";
+import type { BackoffConfig, EnqueueOptions, RetentionConfig, UniqueScope } from "./types.ts";
 import type { Job } from "./resources.ts";
 /**
  * Configuration that can be attached to a job function via `fn.zizqOptions`.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Client, Job, JobPage, ErrorRecord, ErrorPage, CronGroup, CronEntry, ZizqError, ConnectionError, ResponseError, ClientError, NotFoundError, ServerError, } from "./client.ts";
 export type { ClientOptions, TlsOptions, } from "./client.ts";
-export type { JobStatus, SortDirection, UniqueScope, Format, BackoffConfig, RetentionConfig, EnqueueOptions, FailureOptions, UpdateJobOptions, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions, } from "./types.ts";
+export type { JobStatus, SortDirection, UniqueScope, Format, BackoffConfig, RetentionConfig, EnqueueOptions, EnqueueInput, FailureOptions, UpdateJobOptions, TakeOptions, ListJobsOptions, ListErrorsOptions, UpdateAllJobsOptions, JobFilter, DeleteAllJobsOptions, CronEntryInput, ReplaceCronGroupOptions, } from "./types.ts";
 export type { JobData, ErrorRecordData, CronEntryData, CronGroupData, } from "./resources.ts";
 export { Worker } from "./worker.ts";
 export type { WorkerOptions, Logger, RequestRetryOptions } from "./worker.ts";
@@ -11,5 +11,4 @@ export type { ErrorQueryOptions, JobQueryOptions } from "./query.ts";
 export { enqueue, enqueueBulk } from "./enqueue.ts";
 export { CronHandle, CronEntryHandle } from "./cron.ts";
 export type { CronEntryDefinition, RegisterCronOptions } from "./cron.ts";
-export type { EnqueueInput } from "./enqueue.ts";
 export { uniqueKey } from "./unique-key.ts";

package/dist/types.d.ts

@@ -6,6 +6,7 @@
  *
  * @module
  */
+import type { JobFunction } from "./handler.ts";
 /** Lifecycle status of a job. */
 export type JobStatus = "ready" | "in_flight" | "scheduled" | "completed" | "dead";
 /** Sort direction for paginated listings. */
@@ -242,3 +243,75 @@ export interface ReplaceCronGroupOptions {
     /** Named collection of entries present in this group. */
     entries: CronEntryInput[];
 }
+/**
+ * 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 client.enqueue({ type: sendEmail, payload: { to: "a@b.com" } });
+ * ```
+ *
+ * @example String type with explicit config
+ * ```ts
+ * await client.enqueue({
+ *   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;
+}

package/package.json

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