enqiu 0.1.2 → 0.4.0

package/dist/api.js

@@ -1,519 +1,424 @@
-import { MemoryQueue, JobCancelledError, JobExpiredError, JobFailedError, JobTimeoutError, QueueClosedError, } from "./memory.js";
-import { RedisQueue, } from "./redis.js";
-import { JobSerializationError, cloneJobValue, } from "./codec.js";
-import { MemoryScheduler } from "./memory-scheduler.js";
-const definitionMarker = Symbol("enqiu.job");
-const reservedNames = new Set(["queue", "worker"]);
-export function job(definition) {
-    if (!definition || typeof definition !== "object") {
-        throw new TypeError("job() requires a definition object");
+/**
+ * `enqiu()` — a typed layer over BullMQ.
+ *
+ * Enqiu owns the developer experience: inferred job names, schema-validated
+ * input, and one object per job that you call like a function. BullMQ owns
+ * storage, scheduling and execution. Anything BullMQ's open-source tier cannot
+ * express is absent rather than faked, with two exceptions Enqiu enforces
+ * itself around the handler because they cost nothing to add: `timeout` and
+ * `expiresIn`.
+ *
+ * This file composes; the parts it composes live next to it.
+ */
+import { Queue, Worker } from "bullmq";
+import { normalizeDefinition, validateInput } from "./definition.js";
+import { QueueEventStream } from "./events.js";
+import { CancellationMarkers } from "./markers.js";
+import { JobRunner } from "./runner.js";
+import { assertJobValue } from "./serialize.js";
+import { JobCancelledError, JobFailedError, QueueClosedError, decodeFailure, failureToError, toError, } from "./errors.js";
+import { bullStates, decodeCursor, encodeCursor, everyState, isFinished, mergePage, queueEventMap, toJobsOptions, toSnapshot, toStatus, } from "./mapping.js";
+export { job } from "./definition.js";
+/**
+ * What a handle needs to answer questions about its job.
+ *
+ * Three methods, and everything awkward about them is inside: that a cancelled
+ * job may no longer exist, that BullMQ hands a failure back as a bare string,
+ * and that only the worker holding a running job can abort it.
+ */
+class JobStore {
+    queue;
+    events;
+    markers;
+    worker;
+    constructor(queue, events, markers, worker) {
+        this.queue = queue;
+        this.events = events;
+        this.markers = markers;
+        this.worker = worker;
     }
-    if (!isStandardSchema(definition.input)) {
-        throw new TypeError("job.input must implement Standard Schema");
+    /**
+     * `state` says what an event already proved, so the state need not be re-read.
+     *
+     * The job and its state are fetched together: `getJobState` needs only the id,
+     * so waiting for the job first was a round trip spent for nothing.
+     */
+    async snapshot(id, state) {
+        const [bull, settled] = await Promise.all([
+            this.queue.getJob(id),
+            state ?? this.queue.getJobState(id),
+        ]);
+        // Gone means the marker is all there is — and the marker is a snapshot.
+        if (!bull)
+            return this.markers.read(id);
+        // An aborted job settles as failed; the marker is what distinguishes a
+        // deliberate cancellation from one that simply threw.
+        if (settled === "failed") {
+            const cancelled = await this.markers.read(id);
+            if (cancelled)
+                return cancelled;
+        }
+        return toSnapshot(bull, toStatus(settled));
     }
-    if (typeof definition.run !== "function") {
-        throw new TypeError("job.run must be a function");
+    async result(bull) {
+        const id = String(bull.id);
+        try {
+            return await bull.waitUntilFinished(await this.events.open());
+        }
+        catch (cause) {
+            const error = toError(cause);
+            // The free check first: a stored envelope needs no round trip to read.
+            const failure = decodeFailure(error.message);
+            if (failure)
+                throw failureToError(failure);
+            const cancelled = await this.markers.read(id);
+            if (cancelled)
+                throw new JobCancelledError(id, cancelled.error?.message);
+            throw new JobFailedError(id, error.message, { cause: error });
+        }
     }
-    return Object.freeze({
-        ...definition,
-        [definitionMarker]: true,
-    });
-}
-export class JobValidationError extends TypeError {
-    issues;
-    constructor(name, issues) {
-        super(`Invalid input for job "${name}": ${issues[0]?.message ?? "validation failed"}`);
-        this.name = "JobValidationError";
-        this.issues = issues;
+    async cancel(bull, reason) {
+        const id = String(bull.id);
+        const state = await bull.getState();
+        if (state === "unknown" || isFinished(state))
+            return false;
+        // Taken before anything is destroyed: once the job is removed this is the
+        // only record that it ever existed, let alone what it carried. Finished
+        // here, so a reader has nothing left to reassemble.
+        const snapshot = toSnapshot(bull, "cancelled");
+        snapshot.finishedAt = Date.now();
+        snapshot.error = { name: "JobCancelledError", message: reason };
+        if (state === "active") {
+            // A running job cannot be removed, but this process's worker can abort
+            // it if it is the one holding it. Another worker's job is not ours to
+            // cancel, and BullMQ offers no cross-process signal for that.
+            if (!this.worker?.cancelJob(id, reason))
+                return false;
+        }
+        else {
+            try {
+                await bull.remove();
+            }
+            catch {
+                return false;
+            }
+        }
+        await this.markers.write(id, snapshot);
+        return true;
     }
 }
-class PublicJobHandle {
-    legacy;
+class Handle {
+    bull;
+    store;
+    deduplicated;
     resultPromise;
-    constructor(legacy) {
-        this.legacy = legacy;
+    constructor(bull, store, deduplicated) {
+        this.bull = bull;
+        this.store = store;
+        this.deduplicated = deduplicated;
     }
     get id() {
-        return this.legacy.id;
+        return String(this.bull.id);
     }
     get name() {
-        return this.legacy.name;
+        return this.bull.name;
     }
     get input() {
-        return this.legacy.input;
-    }
-    get status() {
-        return this.legacy.status;
-    }
-    get deduplicated() {
-        return this.legacy.deduplicated;
+        return this.bull.data;
     }
     get result() {
-        this.resultPromise ??= this.legacy.result;
+        this.resultPromise ??= this.store.result(this.bull);
         return this.resultPromise;
     }
-    async cancel(reason) {
-        return this.legacy.cancel(reason);
+    cancel(reason) {
+        return this.store.cancel(this.bull, reason ?? "Job was cancelled");
     }
     async refresh() {
-        if ("refresh" in this.legacy) {
-            return this.legacy.refresh();
-        }
-        return this.legacy.snapshot();
+        const snapshot = await this.store.snapshot(this.id);
+        if (!snapshot)
+            throw new Error(`Job "${this.id}" no longer exists`);
+        return snapshot;
     }
 }
-class EnqiuFacade {
-    options;
-    api;
-    definitions = new Map();
-    memory;
-    redis;
-    memoryScheduler;
-    workerRunning;
-    constructor(definitions, options) {
-        this.options = options;
-        const handlers = {};
-        for (const [name, definition] of Object.entries(definitions)) {
-            if (reservedNames.has(name)) {
-                throw new TypeError(`"${name}" is reserved by enqiu`);
-            }
-            const normalized = normalizeDefinition(definition);
-            this.definitions.set(name, normalized);
-            handlers[name] = async (input, context) => {
-                const output = await normalized.run(input, createContext(context, options.name ?? "default", options.telemetry));
-                return cloneJobValue(output);
-            };
-        }
-        if (this.definitions.size === 0) {
-            throw new TypeError("At least one job definition is required");
+function createJobCallable(name, definition, runtime) {
+    const options = (submit) => toJobsOptions(submit, definition.policy, runtime.defaults);
+    const submit = async (input, submitOptions = {}) => {
+        await runtime.ready();
+        const value = assertJobValue(await validateInput(name, definition.schema, input));
+        // Ask before adding: on a hit BullMQ returns the *existing* job, so
+        // afterwards its id is the deduplication owner and the two are
+        // indistinguishable.
+        let deduplicated = false;
+        if (submitOptions.idempotencyKey !== undefined) {
+            const owner = await runtime.queue.getDeduplicationJobId(submitOptions.idempotencyKey);
+            deduplicated = owner !== undefined && owner !== null;
         }
-        const concurrency = options.worker === false ? 1 : options.worker?.concurrency;
-        const autoStart = options.worker === false
-            ? false
-            : options.worker?.autoStart ?? true;
-        const retry = normalizeLegacyRetry(options.retry);
-        if (options.driver) {
-            this.redis = new RedisQueue(handlers, compact({
-                driver: options.driver,
-                name: options.name,
-                worker: options.worker !== false,
-                concurrency,
-                autoStart,
-                retry: retry,
-                timeout: options.timeout,
-                historyLimit: options.historyLimit,
-                logLimit: options.logLimit,
-            }));
-            this.workerRunning = autoStart && options.worker !== false;
-        }
-        else {
-            this.memory = new MemoryQueue(handlers, compact({
-                name: options.name,
-                concurrency,
-                autoStart,
-                retry,
-                timeout: options.timeout,
-                historyLimit: options.historyLimit,
-                logLimit: options.logLimit,
-            }));
-            this.memoryScheduler = new MemoryScheduler();
-            this.workerRunning = autoStart;
-        }
-        const target = {};
-        for (const name of this.definitions.keys()) {
-            target[name] = this.createCallable(name);
-        }
-        target.queue = this.createQueueApi();
-        target.worker = this.createWorkerApi();
-        this.api = Object.freeze(target);
-        this.connectTelemetry();
-    }
-    get queue() {
-        return this.redis ?? this.memory;
-    }
-    createCallable(name) {
-        const definition = this.definitions.get(name);
-        if (!definition) {
-            throw new TypeError(`Unknown job "${name}"`);
+        const bull = await runtime.queue.add(name, value, options(submitOptions));
+        return new Handle(bull, runtime.store, deduplicated);
+    };
+    const bulk = async (inputs, bulkOptions = {}) => {
+        if (bulkOptions.ids && bulkOptions.ids.length !== inputs.length) {
+            throw new RangeError("bulk ids must match the number of inputs");
         }
-        const callable = async (input, options = {}) => {
-            const value = cloneJobValue(await validateInput(name, definition.schema, input));
-            const legacy = this.addLegacy(name, value, toLegacyOptions(options, definition.policy, name, value));
-            if ("accepted" in legacy) {
-                await legacy.accepted;
+        await runtime.ready();
+        const values = await Promise.all(inputs.map(async (input) => assertJobValue(await validateInput(name, definition.schema, input))));
+        // Only the id varies across the batch, so the rest is resolved once.
+        const shared = options(bulkOptions);
+        const created = await runtime.queue.addBulk(values.map((data, index) => {
+            const id = bulkOptions.ids?.[index];
+            return {
+                name,
+                data,
+                opts: id === undefined ? shared : { ...shared, jobId: id },
+            };
+        }));
+        return created.map((bull) => new Handle(bull, runtime.store, false));
+    };
+    const schedule = async (scheduleOptions) => {
+        runtime.assertOpen();
+        const value = assertJobValue(await validateInput(name, definition.schema, scheduleOptions.input));
+        const id = scheduleOptions.id?.trim() || name;
+        await runtime.queue.upsertJobScheduler(id, {
+            pattern: scheduleOptions.cron,
+            ...(scheduleOptions.timezone === undefined
+                ? {}
+                : { tz: scheduleOptions.timezone }),
+        }, { name, data: value });
+        return scheduleHandle(id, name, runtime.queue);
+    };
+    return Object.assign(submit, { bulk, schedule, input: definition.schema });
+}
+function scheduleHandle(id, jobName, queue) {
+    return {
+        id,
+        remove: async () => {
+            await queue.removeJobScheduler(id);
+        },
+        refresh: async () => {
+            const scheduler = await queue.getJobScheduler(id);
+            if (!scheduler)
+                throw new Error(`Schedule "${id}" does not exist`);
+            return {
+                id,
+                jobName,
+                cron: String(scheduler.pattern ?? ""),
+                timezone: String(scheduler.tz ?? "UTC"),
+                nextRunAt: Number(scheduler.next ?? 0),
+                input: scheduler.template?.data,
+            };
+        },
+    };
+}
+function createQueueApi(runtime) {
+    const { queue, markers, store, events } = runtime;
+    return Object.freeze({
+        get: async (id) => (await store.snapshot(id)),
+        list: async (query) => {
+            const limit = query.limit ?? 100;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+                throw new RangeError("list.limit must be an integer between 1 and 1000");
             }
-            return new PublicJobHandle(legacy);
-        };
-        const bulk = async (inputs, options = {}) => {
-            if (options.ids && options.ids.length !== inputs.length) {
-                throw new RangeError("bulk ids must match the number of inputs");
+            const states = bullStates[query.status];
+            if (states.length === 0)
+                return { jobs: [] };
+            // One range per state, each with its own offset, because BullMQ applies
+            // a range to every state separately.
+            const offsets = decodeCursor(query.cursor, states.length);
+            const pages = await Promise.all(states.map(async (state, index) => {
+                const offset = offsets[index] ?? 0;
+                return {
+                    offset,
+                    items: await queue.getJobs([state], offset, offset + limit - 1),
+                };
+            }));
+            const { items, next } = mergePage(pages, limit);
+            const jobs = items.map((bull) => toSnapshot(bull, query.status));
+            return items.length === limit
+                ? { jobs, cursor: encodeCursor(next) }
+                : { jobs };
+        },
+        stats: async () => {
+            const counts = await queue.getJobCounts(...everyState);
+            const sum = (status) => bullStates[status].reduce((n, state) => n + (counts[state] ?? 0), 0);
+            const stats = {
+                queued: sum("queued"),
+                scheduled: sum("scheduled"),
+                running: sum("running"),
+                succeeded: sum("succeeded"),
+                failed: sum("failed"),
+            };
+            return {
+                ...stats,
+                total: Object.values(stats).reduce((a, b) => a + b, 0),
+            };
+        },
+        redrive: async (id) => {
+            const bull = await queue.getJob(id);
+            if (!bull)
+                throw new Error(`Job "${id}" cannot be redriven`);
+            const state = await bull.getState();
+            if (!isFinished(state))
+                throw new Error(`Job "${id}" cannot be redriven`);
+            await bull.retry(state);
+            return new Handle(bull, store, false);
+        },
+        cleanup: async (query = {}) => {
+            const olderThan = query.olderThan ?? 0;
+            if (!Number.isFinite(olderThan) || olderThan < 0) {
+                throw new RangeError("olderThan must be a non-negative finite number");
             }
-            const values = await Promise.all(inputs.map(async (input) => cloneJobValue(await validateInput(name, definition.schema, input))));
-            const handles = values.map((value, index) => {
-                const id = options.ids?.[index];
-                const submitOptions = compact({
-                    ...options,
-                    ids: undefined,
-                    id,
-                });
-                return this.addLegacy(name, value, toLegacyOptions(submitOptions, definition.policy, name, value));
-            });
-            await Promise.all(handles.map((handle) => "accepted" in handle ? handle.accepted : Promise.resolve()));
-            return handles.map((handle) => new PublicJobHandle(handle));
-        };
-        const schedule = async (options) => {
-            const value = cloneJobValue(await validateInput(name, definition.schema, options.input));
-            if (this.redis) {
-                return this.redis.upsertSchedule({
-                    ...options,
-                    input: value,
-                    jobName: name,
-                    submit: toLegacyOptions({}, definition.policy, name, value),
-                });
+            // Every state the status is made of: cleaning only the first left
+            // prioritized jobs behind and reported success.
+            const limit = query.limit ?? 1000;
+            const removed = await Promise.all(bullStates[query.status ?? "succeeded"].map((state) => queue.clean(olderThan, limit, state)));
+            await markers.prune(Date.now() - olderThan);
+            return removed.flat();
+        },
+        onIdle: async () => {
+            // BullMQ has no idle signal, so poll the counts it already maintains
+            // rather than tracking the same state in parallel. The wait widens so
+            // that draining a long queue does not sit at 50 polls a second.
+            for (let wait = 20;; wait = Math.min(wait * 2, 250)) {
+                const outstanding = await queue.getJobCountByTypes("waiting", "active", "delayed", "prioritized");
+                if (outstanding === 0)
+                    return;
+                await new Promise((resolve) => setTimeout(resolve, wait));
             }
-            const scheduleId = options.id?.trim() || name;
-            return this.memoryScheduler.upsert({
-                ...options,
-                input: value,
-                jobName: name,
-                enqueue: async (scheduledInput, occurrence) => {
-                    const handle = await callable(scheduledInput, {
-                        id: `${this.options.name ?? "default"}:schedule:${scheduleId}:${occurrence}`,
+        },
+        on: (event, listener) => {
+            const { name, state } = queueEventMap[event];
+            const deliver = listener;
+            // `error` carries an Error rather than a job, and which one this is was
+            // settled when on() was called — not on every delivery.
+            const handler = event === "error"
+                ? deliver
+                : ({ jobId }) => {
+                    // The event already says what state the job is in, so only the
+                    // job itself has to be fetched.
+                    void store.snapshot(jobId, state).then((snapshot) => {
+                        if (snapshot)
+                            deliver(snapshot);
                     });
-                    void handle;
-                },
-            });
-        };
-        Object.defineProperties(callable, {
-            bulk: { value: bulk, enumerable: true },
-            schedule: { value: schedule, enumerable: true },
-            input: { value: definition.schema, enumerable: true },
-        });
-        return callable;
-    }
-    createQueueApi() {
-        return Object.freeze({
-            get: async (id) => (await this.queue.get(id)),
-            list: async (query = {}) => {
-                if (this.redis) {
-                    return this.redis.list(query);
-                }
-                let jobs = this.memory?.list(query.status) ?? [];
-                if (query.name) {
-                    jobs = jobs.filter((item) => item.name === query.name);
-                }
-                if (query.after !== undefined) {
-                    jobs = jobs.filter((item) => item.createdAt > query.after);
-                }
-                if (query.before !== undefined) {
-                    jobs = jobs.filter((item) => item.createdAt < query.before);
-                }
-                const limit = query.limit ?? 100;
-                return {
-                    jobs: jobs.slice(0, limit),
                 };
-            },
-            stats: async () => this.redis ? this.redis.stats() : this.memory.stats,
-            pause: async () => {
-                if (this.redis) {
-                    await this.redis.pauseQueue();
-                }
-                else {
-                    this.memory?.pause();
-                }
-            },
-            resume: async () => {
-                if (this.redis) {
-                    await this.redis.resumeQueue();
-                }
-                else {
-                    this.memory?.start();
-                }
-            },
-            setConcurrency: async (limit) => {
-                if (this.redis) {
-                    await this.redis.setGlobalConcurrency(limit);
+            // Attaching has to wait for the stream to open, so unsubscribing before
+            // that has to be remembered rather than applied.
+            let detach;
+            let unsubscribed = false;
+            void events.open().then((stream) => {
+                if (unsubscribed)
                     return;
-                }
-                this.memory.concurrency = limit;
-            },
-            redrive: async (id) => {
-                if (this.redis) {
-                    return new PublicJobHandle((await this.redis.redrive(id)));
-                }
-                const handle = this.memory?.retry(id);
-                if (!handle) {
-                    throw new Error(`Job "${id}" cannot be redriven`);
-                }
-                return new PublicJobHandle(handle);
-            },
-            cleanup: async (query = {}) => {
-                if (this.redis) {
-                    return this.redis.cleanup(query);
-                }
-                return (this.memory?.cleanup(compact({
-                    olderThan: query.olderThan,
-                    limit: query.limit,
-                })) ?? []);
-            },
-            on: (event, listener) => {
-                const events = this.queue;
-                return events.on(event, listener);
-            },
-        });
-    }
-    createWorkerApi() {
-        const facade = this;
-        return Object.freeze({
-            get running() {
-                return facade.workerRunning;
-            },
-            start: async (options = {}) => {
-                if (options.concurrency !== undefined) {
-                    if (facade.redis) {
-                        facade.redis.setWorkerConcurrency(options.concurrency);
-                    }
-                    else {
-                        facade.memory.concurrency =
-                            options.concurrency;
-                    }
-                }
-                facade.queue.start();
-                facade.workerRunning = true;
-            },
-            pause: async () => {
-                facade.queue.pause();
-                facade.workerRunning = false;
-            },
-            resume: async () => {
-                facade.queue.start();
-                facade.workerRunning = true;
-            },
-            onIdle: async () => facade.queue.onIdle(),
-            close: async (options) => {
-                await facade.queue.close(options);
-                facade.memoryScheduler?.close();
-                facade.workerRunning = false;
-            },
-        });
-    }
-    connectTelemetry() {
-        const telemetry = this.options.telemetry;
-        if (!telemetry) {
-            return;
-        }
-        const events = [
-            "added",
-            "started",
-            "retry",
-            "succeeded",
-            "failed",
-            "cancelled",
-            "expired",
-        ];
-        const source = this.queue;
-        for (const event of events) {
-            source.on(event, (payload) => {
-                const snapshot = "job" in Object(payload)
-                    ? payload.job
-                    : payload;
-                telemetry.emit({
-                    type: `job.${event}`,
-                    queue: this.options.name ?? "default",
-                    timestamp: Date.now(),
-                    job: snapshot,
-                });
+                stream.on(name, handler);
+                detach = () => stream.off(name, handler);
             });
-        }
-    }
-    addLegacy(name, value, options) {
-        if (this.redis) {
-            return this.redis.add(name, value, options);
-        }
-        return this.memory.add(name, value, options);
-    }
-}
-export function enqiu(definitions, options = {}) {
-    return new EnqiuFacade(definitions, options).api;
-}
-function normalizeDefinition(definition) {
-    if (typeof definition === "function") {
-        return {
-            schema: undefined,
-            run: definition,
-            policy: {},
-        };
-    }
-    if (!definition ||
-        typeof definition !== "object" ||
-        definition[definitionMarker] !== true) {
-        throw new TypeError("Every job must be a handler or a definition created with job()");
-    }
-    const { input, run, retry, timeout, expiresIn, concurrency, throttle, debounce, } = definition;
-    return {
-        schema: input,
-        run: run,
-        policy: compact({
-            retry,
-            timeout,
-            expiresIn,
-            concurrency,
-            throttle,
-            debounce,
-        }),
-    };
-}
-async function validateInput(name, schema, input) {
-    if (!schema) {
-        return input;
-    }
-    const result = await schema["~standard"].validate(input);
-    if (result.issues) {
-        throw new JobValidationError(name, result.issues);
-    }
-    return result.value;
-}
-function isStandardSchema(value) {
-    if (!value || typeof value !== "object") {
-        return false;
-    }
-    const standard = value["~standard"];
-    return (standard?.version === 1 &&
-        typeof standard.vendor === "string" &&
-        typeof standard.validate === "function");
-}
-function normalizeLegacyRetry(value) {
-    if (typeof value === "number" || value === undefined) {
-        return value;
-    }
-    if (!Number.isInteger(value.attempts) || value.attempts < 1) {
-        throw new RangeError("retry.attempts must be a positive integer");
-    }
-    return compact({
-        retries: value.attempts - 1,
-        backoff: value.backoff,
-        when: value.when,
+            return () => {
+                unsubscribed = true;
+                detach?.();
+            };
+        },
     });
 }
-function toLegacyOptions(options, policy, name, input) {
-    const priority = typeof options.priority === "string"
-        ? { low: -10, normal: 0, high: 10 }[options.priority]
-        : options.priority;
-    const concurrency = policy.concurrency === undefined
-        ? undefined
-        : typeof policy.concurrency === "number"
-            ? {
-                limit: policy.concurrency,
-                key: `${name}:*`,
+function createWorkerApi(worker) {
+    return Object.freeze({
+        /**
+         * Read from BullMQ rather than mirrored here. A caller holding
+         * `bull.worker` can pause it, and a flag maintained alongside would go on
+         * claiming otherwise.
+         */
+        get running() {
+            return worker !== undefined && worker.isRunning() && !worker.isPaused();
+        },
+        start: async (options = {}) => {
+            if (!worker) {
+                throw new TypeError("This queue was created with worker: false and cannot run jobs");
             }
-            : {
-                limit: policy.concurrency.limit,
-                key: `${name}:${resolvePolicyKey("concurrency.by", policy.concurrency.by?.(input) ?? "*")}`,
-            };
-    const throttle = policy.throttle
-        ? {
-            limit: policy.throttle.limit,
-            interval: policy.throttle.per,
-            burst: policy.throttle.burst ?? policy.throttle.limit,
-            key: `${name}:${resolvePolicyKey("throttle.by", policy.throttle.by?.(input) ?? "*")}`,
-        }
-        : undefined;
-    const debounce = policy.debounce
-        ? {
-            wait: policy.debounce.wait,
-            mode: policy.debounce.mode,
-            key: resolvePolicyKey("debounce.by", policy.debounce.by(input)),
-        }
-        : undefined;
-    return compact({
-        id: options.id,
-        key: options.idempotencyKey,
-        keyRetention: options.idempotencyKey
-            ? options.idempotencyTtl ?? 24 * 60 * 60 * 1000
-            : undefined,
-        delay: options.delay,
-        priority,
-        retry: normalizeLegacyRetry(options.retry ?? policy.retry),
-        timeout: options.timeout ?? policy.timeout,
-        expiresIn: options.expiresIn ?? policy.expiresIn,
-        concurrency,
-        throttle,
-        debounce,
-        signal: options.signal,
+            if (options.concurrency !== undefined) {
+                worker.concurrency = options.concurrency;
+            }
+            // Awaited on purpose. BullMQ's resume() restarts the main loop only if it
+            // has *already* exited, and right after a pause the loop is still
+            // unwinding — so checking isRunning() before that settles saw a live loop
+            // about to die, and left the worker resumed but not running.
+            if (worker.isPaused())
+                await worker.resume();
+            if (!worker.isRunning())
+                void worker.run();
+        },
     });
 }
-function resolvePolicyKey(name, value) {
-    if (typeof value !== "string" || !value.trim()) {
-        throw new TypeError(`${name} must return a non-empty string`);
+/** Build a typed job API backed by a BullMQ queue. */
+export function enqiu(definitions, options) {
+    const runtimeDefinitions = new Map();
+    for (const [name, definition] of Object.entries(definitions)) {
+        runtimeDefinitions.set(name, normalizeDefinition(definition));
     }
-    return value;
-}
-function createContext(legacy, queue, telemetry) {
-    const log = createLogger(legacy, queue, telemetry);
-    return {
-        id: legacy.id,
-        name: legacy.name,
-        attempt: legacy.attempt,
-        signal: legacy.signal,
-        reportProgress: async (progress) => {
-            validateProgress(progress);
-            const safeProgress = cloneJobValue(progress);
-            legacy.progress(safeProgress);
-            telemetry?.emit({
-                type: "job.progress",
-                queue,
-                timestamp: Date.now(),
-                fields: {
-                    jobId: legacy.id,
-                    jobName: legacy.name,
-                    progress: safeProgress,
-                },
-            });
-        },
-        log,
+    if (runtimeDefinitions.size === 0) {
+        throw new TypeError("At least one job definition is required");
+    }
+    if (!options.connection) {
+        throw new TypeError("enqiu() requires a BullMQ connection");
+    }
+    const queueName = options.name ?? "default";
+    const base = {
+        connection: options.connection,
+        ...(options.prefix === undefined ? {} : { prefix: options.prefix }),
     };
-}
-function createLogger(context, queue, telemetry) {
-    const write = (level, message, fields) => {
-        if (!message) {
-            throw new TypeError("Job log messages must not be empty");
-        }
-        const entry = cloneJobValue({
-            timestamp: Date.now(),
-            level,
-            message,
-            ...(fields === undefined ? {} : { fields }),
-        });
-        context.log(entry);
-        telemetry?.emit({
-            type: `job.log.${level}`,
-            queue,
-            timestamp: Date.now(),
-            fields: {
-                jobId: context.id,
-                jobName: context.name,
-                message: entry.message,
-                ...(entry.fields ?? {}),
-            },
+    const queue = new Queue(queueName, base);
+    let worker;
+    if (options.worker !== false) {
+        const { concurrency, autoStart = true } = options.worker ?? {};
+        const runner = new JobRunner(runtimeDefinitions, { timeout: options.timeout });
+        worker = new Worker(queueName, 
+        // Three parameters on purpose: BullMQ decides whether to create an
+        // AbortController by reading `processor.length >= 3`. Declaring fewer
+        // means worker.cancelJob() can never abort anything.
+        async (bull, _token, signal) => runner.run(bull, signal), {
+            ...base,
+            ...(concurrency === undefined ? {} : { concurrency }),
+            autorun: false,
         });
+        if (autoStart)
+            void worker.run();
+    }
+    const events = new QueueEventStream(queue, base);
+    const markers = new CancellationMarkers(queue);
+    const store = new JobStore(queue, events, markers, worker);
+    const runtime = {
+        queue,
+        events,
+        markers,
+        store,
+        defaults: {
+            logLimit: options.logLimit ?? 100,
+            retry: options.retry,
+        },
+        // Read from BullMQ, so closing `bull.queue` underneath is seen here too.
+        assertOpen: () => {
+            if (queue.closing !== undefined)
+                throw new QueueClosedError(queueName);
+        },
+        ready: async () => {
+            runtime.assertOpen();
+            await events.settle();
+        },
     };
+    const jobs = {};
+    for (const [name, definition] of runtimeDefinitions) {
+        jobs[name] = createJobCallable(name, definition, runtime);
+    }
+    const queueApi = createQueueApi(runtime);
+    const workerApi = createWorkerApi(worker);
     return Object.freeze({
-        debug: (message, fields) => write("debug", message, fields),
-        info: (message, fields) => write("info", message, fields),
-        warn: (message, fields) => write("warn", message, fields),
-        error: (message, fields) => write("error", message, fields),
+        jobs: Object.freeze(jobs),
+        queue: queueApi,
+        worker: workerApi,
+        bull: Object.freeze({ queue, worker }),
+        close: async (closeOptions) => {
+            if ((closeOptions?.drain ?? true) && workerApi.running) {
+                await queueApi.onIdle();
+            }
+            // Three independent connections: closing the worker waits out the jobs
+            // it holds, which the other two have no reason to wait for.
+            await Promise.all([worker?.close(), events.close(), queue.close()]);
+        },
     });
 }
-function validateProgress(progress) {
-    if (!Number.isFinite(progress.completed) ||
-        !Number.isFinite(progress.total) ||
-        progress.completed < 0 ||
-        progress.total <= 0 ||
-        progress.completed > progress.total) {
-        throw new RangeError("Progress requires 0 <= completed <= total and total > 0");
-    }
-}
-function compact(value) {
-    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
-}
-export { JobCancelledError, JobExpiredError, JobFailedError, JobSerializationError, JobTimeoutError, QueueClosedError, };