enqiu 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project are documented here. The project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - Unreleased
+
+### Changed
+
+- Renamed the package and primary API to `enqiu`.
+- Replaced the BullMQ wrapper with first-party memory and Redis drivers.
+- Reworked the API around inferred named handlers and direct job calls.
+
+### Added
+
+- Typed heterogeneous job maps.
+- Concurrency control with priority scheduling.
+- Delayed jobs and exact-date scheduling.
+- Per-queue and per-job retries with fixed, exponential, custom, and jittered
+  backoff.
+- Cooperative cancellation and per-attempt timeouts using `AbortSignal`.
+- Strict rolling-window rate limiting and producer backpressure.
+- Single-flight deduplication keys.
+- Bulk enqueueing, progress reporting, typed lifecycle events, history,
+  cleanup, pause/start, inspection, and graceful close.
+- Safe fire-and-forget jobs without implicit unhandled promise rejections.
+- Durable Redis delivery, cron schedules, keyed concurrency, throttling,
+  debouncing, expiration, structured logs, and telemetry hooks.
+
+### Removed
+
+- BullMQ and its transitive runtime dependency tree.
+- The mismatched legacy constructor and undocumented aliases.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Enqiu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# Enqiu
+
+A small, type-safe job queue for Node.js and Bun. Start in memory, move to
+Redis without changing your job API.
+
+```bash
+pnpm add enqiu
+```
+
+Enqiu has no runtime dependencies. Redis, schema, Hono, and telemetry packages
+remain your choice.
+
+## Quick start
+
+Define each job once, then call it like a function. The name, input, and result
+types are inferred.
+
+```ts
+import { enqiu, job } from "enqiu";
+import { z } from "zod";
+
+const jobs = enqiu({
+  sendEmail: job({
+    input: z.object({
+      to: z.email(),
+      subject: z.string(),
+    }),
+    run: async (email, { signal, log }) => {
+      log.info("Sending email", { to: email.to });
+
+      const response = await fetch("https://example.com/email", {
+        method: "POST",
+        body: JSON.stringify(email),
+        signal,
+      });
+
+      return { delivered: response.ok };
+    },
+  }),
+});
+
+const delivery = await jobs.sendEmail({
+  to: "hello@example.com",
+  subject: "Welcome",
+});
+
+const result = await delivery.result;
+console.log(result.delivered);
+```
+
+`await jobs.sendEmail(input)` waits until the queue accepts the job and returns
+a handle. It does not wait for the handler. Await `handle.result` only when the
+caller needs the result. Ignoring a handle is safe and does not create an
+unhandled rejected promise.
+
+Schemas are optional. A plain handler also infers its result:
+
+```ts
+const jobs = enqiu({
+  resizeImage: async (input: { key: string; width: number }) => {
+    return { key: input.key, width: input.width };
+  },
+});
+```
+
+## Redis
+
+Inject an existing client; Enqiu does not create connections or install a Redis
+library. It accepts Bun's `send(command, args)` client shape and node-redis'
+`sendCommand(args)` shape.
+
+```ts
+import { createClient } from "redis";
+import { enqiu, redis } from "enqiu";
+
+const client = createClient({ url: process.env.REDIS_URL });
+await client.connect();
+
+const jobs = enqiu(definitions, {
+  name: "notifications",
+  driver: redis(client),
+  worker: { concurrency: 20 },
+});
+```
+
+Use the same definitions in a producer-only process:
+
+```ts
+const jobs = enqiu(definitions, {
+  name: "notifications",
+  driver: redis(client),
+  worker: false,
+});
+```
+
+Redis jobs use atomic Lua transitions, visibility leases, and deterministic
+recovery so multiple Node.js or Bun workers can safely share a queue.
+
+## Job policies
+
+Policies live beside the handler and keep call sites clean. Durations are
+numbers in milliseconds, so applications may use plain numbers or a helper
+such as `ms("30s")` without making it an Enqiu dependency.
+
+```ts
+const jobs = enqiu({
+  syncAccount: job({
+    input: z.object({
+      tenantId: z.string(),
+      accountId: z.string(),
+    }),
+    retry: {
+      attempts: 5,
+      backoff: { type: "exponential", delay: 250, jitter: 0.2 },
+    },
+    timeout: 30_000,
+    expiresIn: 5 * 60_000,
+    concurrency: {
+      limit: 2,
+      by: (input) => input.tenantId,
+    },
+    throttle: {
+      limit: 100,
+      per: 60_000,
+      burst: 10,
+      by: (input) => input.tenantId,
+    },
+    run: async (input, context) => {
+      return syncAccount(input, { signal: context.signal });
+    },
+  }),
+});
+```
+
+- `concurrency` limits simultaneous work globally or by a key such as tenant.
+- `throttle` limits starts over time; `burst` allows short spikes.
+- `debounce: { mode: "leading" }` keeps the first call in a window.
+- `debounce: { mode: "trailing" }` keeps the most recent call in a window.
+- `expiresIn` prevents stale jobs from starting.
+- `idempotencyKey` makes repeated submissions return the same job.
+
+Per-call delivery options are available when needed:
+
+```ts
+const handle = await jobs.syncAccount(input, {
+  idempotencyKey: `sync:${input.accountId}`,
+  idempotencyTtl: 24 * 60 * 60_000,
+  delay: 5_000,
+  priority: "high",
+});
+```
+
+## Progress and logs
+
+Progress uses real units rather than an ambiguous fraction:
+
+```ts
+const jobs = enqiu({
+  importRows: async (rows: string[], context) => {
+    for (let index = 0; index < rows.length; index += 1) {
+      await importRow(rows[index]);
+      await context.reportProgress({
+        completed: index + 1,
+        total: rows.length,
+        message: "Importing rows",
+      });
+    }
+
+    context.log.info("Import complete", { rows: rows.length });
+  },
+});
+```
+
+Subscribe to lifecycle events with `jobs.queue.on(...)`. Memory events stay
+inside the process; Redis events are shared between producers and workers.
+
+## Cron schedules
+
+Schedules use standard five-field cron expressions and IANA time zones:
+
+```ts
+const schedule = await jobs.sendDigest.schedule({
+  id: "weekday-digest",
+  cron: "0 9 * * 1-5",
+  timezone: "Europe/Nicosia",
+  input: { audience: "daily" },
+  catchUp: true,
+});
+
+await schedule.pause();
+await schedule.resume();
+await schedule.remove();
+```
+
+Memory schedules live for the process lifetime. Redis schedules are durable
+and use deterministic occurrence IDs to avoid duplicate runs.
+
+## Hono
+
+Enqiu uses Standard Schema and exposes each job's input schema, so the same
+schema can validate an HTTP route without redefining a type:
+
+```ts
+import { sValidator } from "@hono/standard-validator";
+
+app.post(
+  "/emails",
+  sValidator("json", jobs.sendEmail.input),
+  async (c) => {
+    const handle = await jobs.sendEmail(c.req.valid("json"));
+    return c.json({ id: handle.id }, 202);
+  },
+);
+```
+
+Hono and `@hono/standard-validator` are optional application dependencies.
+
+## Queue and worker controls
+
+```ts
+await jobs.queue.pause();
+await jobs.queue.resume();
+await jobs.queue.setConcurrency(50);
+
+const page = await jobs.queue.list({ status: "failed", limit: 100 });
+const snapshot = await jobs.queue.get(handle.id);
+await jobs.queue.redrive(handle.id);
+await jobs.queue.cleanup({ olderThan: Date.now() - 7 * 24 * 60 * 60_000 });
+
+await jobs.worker.pause();
+await jobs.worker.resume();
+await jobs.worker.onIdle();
+await jobs.worker.close();
+```
+
+## Runtime support
+
+- Node.js 20 and newer
+- Current stable Bun
+- Memory and Redis drivers
+- ESM and TypeScript declarations
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,236 @@
+import { JobCancelledError, JobExpiredError, JobFailedError, JobTimeoutError, QueueClosedError } from "./memory.js";
+import type { JobSnapshot, JobStatus, MaybePromise, QueueEventMap, QueueStats, RetryOptions } from "./memory.js";
+import { type RedisDriver } from "./redis.js";
+import { JobSerializationError } from "./codec.js";
+declare const definitionMarker: unique symbol;
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => MaybePromise<{
+            readonly value: Output;
+            readonly issues?: undefined;
+        } | {
+            readonly value?: undefined;
+            readonly issues: readonly StandardSchemaIssue[];
+        }>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+export interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }>;
+}
+export type InferSchemaInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+export type InferSchemaOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+export interface Progress {
+    readonly completed: number;
+    readonly total: number;
+    readonly message?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+export interface JobLogger {
+    debug(message: string, fields?: Readonly<Record<string, unknown>>): void;
+    info(message: string, fields?: Readonly<Record<string, unknown>>): void;
+    warn(message: string, fields?: Readonly<Record<string, unknown>>): void;
+    error(message: string, fields?: Readonly<Record<string, unknown>>): void;
+}
+export interface JobContext<Name extends string = string> {
+    readonly id: string;
+    readonly name: Name;
+    readonly attempt: number;
+    readonly signal: AbortSignal;
+    reportProgress(progress: Progress): Promise<void>;
+    readonly log: JobLogger;
+}
+export type JobHandler<Input = unknown, Output = unknown, Name extends string = string> = (input: Input, context: JobContext<Name>) => MaybePromise<Output>;
+export interface RetryPolicy extends Omit<RetryOptions, "retries"> {
+    /** Total number of attempts, including the first. */
+    attempts: number;
+}
+export interface ConcurrencyPolicy<Input> {
+    limit: number;
+    by?: (input: Input) => string;
+}
+export interface ThrottlePolicy<Input> {
+    limit: number;
+    per: number;
+    burst?: number;
+    by?: (input: Input) => string;
+}
+export interface DebouncePolicy<Input> {
+    wait: number;
+    mode: "leading" | "trailing";
+    by: (input: Input) => string;
+}
+export interface JobPolicyOptions<Input> {
+    retry?: number | RetryPolicy;
+    timeout?: number;
+    expiresIn?: number;
+    concurrency?: number | ConcurrencyPolicy<Input>;
+    throttle?: ThrottlePolicy<Input>;
+    debounce?: DebouncePolicy<Input>;
+}
+export interface SchemaJobDefinition<Schema extends StandardSchemaV1 = StandardSchemaV1, Output = unknown> extends JobPolicyOptions<InferSchemaOutput<Schema>> {
+    readonly [definitionMarker]: true;
+    readonly input: Schema;
+    readonly run: JobHandler<InferSchemaOutput<Schema>, Output>;
+}
+export type HandlerJobDefinition<Input = unknown, Output = unknown> = JobHandler<Input, Output>;
+export type JobDefinition = SchemaJobDefinition<StandardSchemaV1<unknown, unknown>, unknown> | HandlerJobDefinition<unknown, unknown>;
+export type JobDefinitions = Record<string, JobDefinition>;
+export declare function job<const Schema extends StandardSchemaV1, Output>(definition: Omit<SchemaJobDefinition<Schema, Output>, typeof definitionMarker>): SchemaJobDefinition<Schema, Output>;
+type DefinitionInput<Definition> = Definition extends SchemaJobDefinition<infer Schema, unknown> ? InferSchemaInput<Schema> : Definition extends JobHandler<infer Input, unknown, string> ? Input : never;
+type DefinitionRunInput<Definition> = Definition extends SchemaJobDefinition<infer Schema, unknown> ? InferSchemaOutput<Schema> : Definition extends JobHandler<infer Input, unknown, string> ? Input : never;
+type DefinitionOutput<Definition> = Definition extends SchemaJobDefinition<StandardSchemaV1, infer Output> ? Awaited<Output> : Definition extends JobHandler<unknown, infer Output, string> ? Awaited<Output> : never;
+export interface SubmitOptions {
+    id?: string;
+    idempotencyKey?: string;
+    /** Keep returning the same completed job for this duration. @default 24h */
+    idempotencyTtl?: number;
+    delay?: number | Date;
+    priority?: number | "low" | "normal" | "high";
+    retry?: number | RetryPolicy;
+    timeout?: number;
+    expiresIn?: number;
+    signal?: AbortSignal;
+}
+export interface BulkOptions extends Omit<SubmitOptions, "id"> {
+    ids?: readonly string[];
+}
+export interface ScheduleOptions<Input> {
+    id?: string;
+    cron: string;
+    timezone?: string;
+    input: Input;
+    catchUp?: boolean;
+}
+export interface ScheduleHandle {
+    readonly id: string;
+    readonly nextRunAt: number;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    remove(): Promise<void>;
+    refresh(): Promise<ScheduleSnapshot>;
+}
+export interface ScheduleSnapshot {
+    id: string;
+    jobName: string;
+    cron: string;
+    timezone: string;
+    status: "active" | "paused";
+    nextRunAt: number;
+    input: unknown;
+    catchUp: boolean;
+}
+export interface JobHandle<Output = unknown, Input = unknown, Name extends string = string> {
+    readonly id: string;
+    readonly name: Name;
+    readonly input: Input;
+    readonly status: JobStatus;
+    readonly deduplicated: boolean;
+    readonly result: Promise<Output>;
+    cancel(reason?: string): Promise<boolean>;
+    refresh(): Promise<JobSnapshot<Input, Output, Name>>;
+}
+export interface JobCallable<Input, RunInput, Output, Name extends string, Schema extends StandardSchemaV1 | undefined = undefined> {
+    (input: Input, options?: SubmitOptions): Promise<JobHandle<Output, RunInput, Name>>;
+    bulk(inputs: readonly Input[], options?: BulkOptions): Promise<Array<JobHandle<Output, RunInput, Name>>>;
+    schedule(options: ScheduleOptions<Input>): Promise<ScheduleHandle>;
+    readonly input: Schema;
+}
+type DefinitionSchema<Definition> = Definition extends SchemaJobDefinition<infer Schema, unknown> ? Schema : undefined;
+export type JobsApi<Definitions extends JobDefinitions> = {
+    readonly [Name in keyof Definitions]: JobCallable<DefinitionInput<Definitions[Name]>, DefinitionRunInput<Definitions[Name]>, DefinitionOutput<Definitions[Name]>, Extract<Name, string>, DefinitionSchema<Definitions[Name]>>;
+} & {
+    readonly queue: QueueApi<Definitions>;
+    readonly worker: WorkerApi;
+};
+export type AnyJobSnapshot<Definitions extends JobDefinitions> = {
+    [Name in keyof Definitions]: JobSnapshot<DefinitionRunInput<Definitions[Name]>, DefinitionOutput<Definitions[Name]>, Extract<Name, string>>;
+}[keyof Definitions];
+export interface JobListQuery {
+    status?: JobStatus;
+    name?: string;
+    before?: number;
+    after?: number;
+    limit?: number;
+    cursor?: string;
+}
+export interface JobListPage<Job = JobSnapshot> {
+    jobs: Job[];
+    cursor?: string;
+}
+export interface CleanupQuery {
+    status?: JobStatus | readonly JobStatus[];
+    olderThan?: number;
+    limit?: number;
+}
+export interface QueueApi<Definitions extends JobDefinitions> {
+    get(id: string): Promise<AnyJobSnapshot<Definitions> | undefined>;
+    list(query?: JobListQuery): Promise<JobListPage<AnyJobSnapshot<Definitions>>>;
+    stats(): Promise<QueueStats>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    setConcurrency(limit: number): Promise<void>;
+    redrive(id: string): Promise<JobHandle>;
+    cleanup(query?: CleanupQuery): Promise<string[]>;
+    on<Event extends keyof QueueEventMap>(event: Event, listener: (payload: QueueEventMap[Event]) => void): () => void;
+}
+export interface WorkerStartOptions {
+    concurrency?: number;
+}
+export interface WorkerApi {
+    readonly running: boolean;
+    start(options?: WorkerStartOptions): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    onIdle(): Promise<void>;
+    close(options?: {
+        drain?: boolean;
+    }): Promise<void>;
+}
+export interface WorkerOptions {
+    concurrency?: number;
+    autoStart?: boolean;
+}
+export interface TelemetryEvent {
+    readonly type: string;
+    readonly queue: string;
+    readonly timestamp: number;
+    readonly job?: JobSnapshot;
+    readonly fields?: Readonly<Record<string, unknown>>;
+}
+export interface Telemetry {
+    emit(event: TelemetryEvent): void;
+}
+export interface SharedEnqiuOptions {
+    name?: string;
+    worker?: false | WorkerOptions;
+    retry?: number | RetryPolicy;
+    timeout?: number;
+    historyLimit?: number;
+    logLimit?: number;
+    telemetry?: Telemetry;
+}
+export interface MemoryEnqiuOptions extends SharedEnqiuOptions {
+    driver?: undefined;
+}
+export interface RedisEnqiuOptions extends SharedEnqiuOptions {
+    driver: RedisDriver;
+    /** Redis processes must explicitly choose producer-only or worker mode. */
+    worker: false | WorkerOptions;
+}
+export type EnqiuOptions = MemoryEnqiuOptions | RedisEnqiuOptions;
+export declare class JobValidationError extends TypeError {
+    readonly issues: readonly StandardSchemaIssue[];
+    constructor(name: string, issues: readonly StandardSchemaIssue[]);
+}
+export declare function enqiu<const Definitions extends JobDefinitions>(definitions: Definitions, options?: MemoryEnqiuOptions): JobsApi<Definitions>;
+export declare function enqiu<const Definitions extends JobDefinitions>(definitions: Definitions, options: RedisEnqiuOptions): JobsApi<Definitions>;
+export { JobCancelledError, JobExpiredError, JobFailedError, JobSerializationError, JobTimeoutError, QueueClosedError, };