enqiu 0.1.2 → 0.4.0

package/dist/backend.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The one place Enqiu reaches past BullMQ's public API.
+ *
+ * `getBackend().client` is documented by BullMQ as a Redis-specific escape
+ * hatch that is deliberately not part of `IQueueBackend`, so using it ties
+ * Enqiu to the Redis backend. Two features need it — cancellation markers and
+ * reading the tail of the event stream — and confining the cast to this file
+ * keeps the coupling one import wide instead of scattered.
+ *
+ * Going through `RedisClient`, BullMQ's own abstraction, rather than an
+ * ioredis-shaped interface is what keeps those two working on node-redis and
+ * Bun, where `hset` takes a field map instead of positional arguments.
+ * XREVRANGE is genuinely absent from it: nothing in BullMQ reads a stream
+ * backwards.
+ */
+import type { ConnectionOptions, Queue, RedisClient } from "bullmq";
+/** The BullMQ options every object Enqiu constructs is built from. */
+export interface BullBase {
+    readonly connection: ConnectionOptions;
+    readonly prefix?: string;
+}
+export type BackendClient = RedisClient & {
+    xrevrange(key: string, end: string, start: string, count: string, limit: string): Promise<unknown>;
+};
+export declare function backendClient(queue: Queue): Promise<BackendClient>;

package/dist/backend.js

@@ -0,0 +1,18 @@
+/**
+ * The one place Enqiu reaches past BullMQ's public API.
+ *
+ * `getBackend().client` is documented by BullMQ as a Redis-specific escape
+ * hatch that is deliberately not part of `IQueueBackend`, so using it ties
+ * Enqiu to the Redis backend. Two features need it — cancellation markers and
+ * reading the tail of the event stream — and confining the cast to this file
+ * keeps the coupling one import wide instead of scattered.
+ *
+ * Going through `RedisClient`, BullMQ's own abstraction, rather than an
+ * ioredis-shaped interface is what keeps those two working on node-redis and
+ * Bun, where `hset` takes a field map instead of positional arguments.
+ * XREVRANGE is genuinely absent from it: nothing in BullMQ reads a stream
+ * backwards.
+ */
+export async function backendClient(queue) {
+    return (await queue.getBackend().client);
+}

package/dist/definition.d.ts

@@ -0,0 +1,13 @@
+/** Turning what a caller wrote into something the worker can run. */
+import { definitionMarker } from "./types.js";
+import type { JobDefinition, JobHandler, JobPolicyOptions, SchemaJobDefinition, StandardSchemaV1 } from "./types.js";
+/** Declare a job with a Standard Schema input and per-job policies. */
+export declare function job<const Schema extends StandardSchemaV1, Output>(definition: Omit<SchemaJobDefinition<Schema, Output>, typeof definitionMarker>): SchemaJobDefinition<Schema, Output>;
+/** A definition reduced to the three things the runtime actually reads. */
+export interface RuntimeDefinition {
+    readonly schema: StandardSchemaV1 | undefined;
+    readonly run: JobHandler;
+    readonly policy: JobPolicyOptions;
+}
+export declare function normalizeDefinition(definition: JobDefinition): RuntimeDefinition;
+export declare function validateInput(name: string, schema: StandardSchemaV1 | undefined, input: unknown): Promise<unknown>;

package/dist/definition.js

@@ -0,0 +1,51 @@
+/** Turning what a caller wrote into something the worker can run. */
+import { JobValidationError } from "./errors.js";
+import { definitionMarker } from "./types.js";
+/** Declare a job with a Standard Schema input and per-job policies. */
+export function job(definition) {
+    if (!definition || typeof definition !== "object") {
+        throw new TypeError("job() requires a definition object");
+    }
+    if (!isStandardSchema(definition.input)) {
+        throw new TypeError("job.input must implement Standard Schema");
+    }
+    if (typeof definition.run !== "function") {
+        throw new TypeError("job.run must be a function");
+    }
+    return Object.freeze({ ...definition, [definitionMarker]: true });
+}
+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");
+}
+export 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 policy = {};
+    if (definition.retry !== undefined)
+        policy.retry = definition.retry;
+    if (definition.timeout !== undefined)
+        policy.timeout = definition.timeout;
+    if (definition.expiresIn !== undefined) {
+        policy.expiresIn = definition.expiresIn;
+    }
+    return { schema: definition.input, run: definition.run, policy };
+}
+export 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;
+}

package/dist/errors.d.ts

@@ -0,0 +1,57 @@
+/** Errors a job can settle with, and how a reason survives the queue. */
+export interface SerializedError {
+    name: string;
+    message: string;
+}
+export declare class JobFailedError extends Error {
+    readonly jobId: string;
+    constructor(jobId: string, message: string, options?: ErrorOptions);
+}
+export declare class JobCancelledError extends Error {
+    readonly jobId: string;
+    constructor(jobId: string, message?: string);
+}
+export declare class JobTimeoutError extends Error {
+    readonly jobId: string;
+    readonly timeout: number;
+    constructor(jobId: string, timeout: number);
+}
+export declare class JobExpiredError extends Error {
+    readonly jobId: string;
+    constructor(jobId: string);
+}
+export declare class QueueClosedError extends Error {
+    constructor(name: string);
+}
+export declare class JobValidationError extends TypeError {
+    readonly issues: readonly StandardSchemaIssue[];
+    constructor(name: string, issues: readonly StandardSchemaIssue[]);
+}
+export interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+}
+export declare function toError(value: unknown): Error;
+/**
+ * Why a job failed, in a form that survives the trip through Redis.
+ *
+ * BullMQ stores one string per failure, `failedReason`, and hands it to other
+ * processes as a plain `Error`. So the reason has to travel as text — but not
+ * as prose. Reading the kind back out of a human sentence means rewording that
+ * sentence silently changes which class callers catch, with no test to notice;
+ * this codebase has already been bitten by exactly that once. The kind is
+ * therefore written down, and only the message is prose.
+ */
+export type JobFailure = {
+    readonly kind: "timeout";
+    readonly jobId: string;
+    readonly timeout: number;
+} | {
+    readonly kind: "expired";
+    readonly jobId: string;
+};
+export declare function encodeFailure(failure: JobFailure): string;
+export declare function decodeFailure(reason: string): JobFailure | undefined;
+export declare function failureToError(failure: JobFailure): Error;

package/dist/errors.js

@@ -0,0 +1,83 @@
+/** Errors a job can settle with, and how a reason survives the queue. */
+export class JobFailedError extends Error {
+    jobId;
+    constructor(jobId, message, options) {
+        super(message, options);
+        this.name = "JobFailedError";
+        this.jobId = jobId;
+    }
+}
+export class JobCancelledError extends Error {
+    jobId;
+    constructor(jobId, message = "Job was cancelled") {
+        super(message);
+        this.name = "JobCancelledError";
+        this.jobId = jobId;
+    }
+}
+export class JobTimeoutError extends Error {
+    jobId;
+    timeout;
+    constructor(jobId, timeout) {
+        super(`Job "${jobId}" timed out after ${timeout}ms`);
+        this.name = "JobTimeoutError";
+        this.jobId = jobId;
+        this.timeout = timeout;
+    }
+}
+export class JobExpiredError extends Error {
+    jobId;
+    constructor(jobId) {
+        super(`Job "${jobId}" expired before it could start`);
+        this.name = "JobExpiredError";
+        this.jobId = jobId;
+    }
+}
+export class QueueClosedError extends Error {
+    constructor(name) {
+        super(`Queue "${name}" is closed`);
+        this.name = "QueueClosedError";
+    }
+}
+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;
+    }
+}
+export function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+const FAILURE_PREFIX = "enqiu-failure:";
+export function encodeFailure(failure) {
+    return FAILURE_PREFIX + JSON.stringify(failure);
+}
+export function decodeFailure(reason) {
+    if (!reason.startsWith(FAILURE_PREFIX))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(reason.slice(FAILURE_PREFIX.length));
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return undefined;
+    const { kind, jobId, timeout } = parsed;
+    if (typeof jobId !== "string")
+        return undefined;
+    if (kind === "expired")
+        return { kind, jobId };
+    if (kind === "timeout" && typeof timeout === "number") {
+        return { kind, jobId, timeout };
+    }
+    return undefined;
+}
+export function failureToError(failure) {
+    return failure.kind === "timeout"
+        ? new JobTimeoutError(failure.jobId, failure.timeout)
+        : new JobExpiredError(failure.jobId);
+}

package/dist/events.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The queue's event stream, opened only if something asks for it.
+ *
+ * A `QueueEvents` costs a dedicated blocking Redis connection, which a
+ * producer that never subscribes and never awaits a result should not pay for.
+ *
+ * Opening it from a known point matters. BullMQ's QueueEvents defaults to
+ * reading from the present, which it evaluates when its read loop starts
+ * rather than when it is constructed — so a caller that subscribed and
+ * immediately submitted could miss its own `added` event. Capturing the stream
+ * tail first and passing it as `lastEventId` closes that window: nothing
+ * appended after this point can fall between the two.
+ */
+import { QueueEvents, type Queue } from "bullmq";
+import { type BullBase } from "./backend.js";
+export declare class QueueEventStream {
+    private readonly queue;
+    private readonly base;
+    private opened;
+    constructor(queue: Queue, base: BullBase);
+    open(): Promise<QueueEvents>;
+    /**
+     * Waits only if a subscription is already opening.
+     *
+     * Submissions call this so that a caller who subscribed and then submitted
+     * cannot outrun the stream — without it being the thing that opens one.
+     */
+    settle(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/events.js

@@ -0,0 +1,53 @@
+/**
+ * The queue's event stream, opened only if something asks for it.
+ *
+ * A `QueueEvents` costs a dedicated blocking Redis connection, which a
+ * producer that never subscribes and never awaits a result should not pay for.
+ *
+ * Opening it from a known point matters. BullMQ's QueueEvents defaults to
+ * reading from the present, which it evaluates when its read loop starts
+ * rather than when it is constructed — so a caller that subscribed and
+ * immediately submitted could miss its own `added` event. Capturing the stream
+ * tail first and passing it as `lastEventId` closes that window: nothing
+ * appended after this point can fall between the two.
+ */
+import { QueueEvents } from "bullmq";
+import { backendClient } from "./backend.js";
+export class QueueEventStream {
+    queue;
+    base;
+    opened;
+    constructor(queue, base) {
+        this.queue = queue;
+        this.base = base;
+    }
+    open() {
+        this.opened ??= (async () => {
+            const client = await backendClient(this.queue);
+            const tail = await client.xrevrange(this.queue.toKey("events"), "+", "-", "COUNT", "1");
+            const first = Array.isArray(tail) ? tail[0] : undefined;
+            const events = new QueueEvents(this.queue.name, {
+                ...this.base,
+                lastEventId: first ? String(first[0]) : "0-0",
+            });
+            await events.waitUntilReady();
+            return events;
+        })();
+        return this.opened;
+    }
+    /**
+     * Waits only if a subscription is already opening.
+     *
+     * Submissions call this so that a caller who subscribed and then submitted
+     * cannot outrun the stream — without it being the thing that opens one.
+     */
+    async settle() {
+        if (this.opened)
+            await this.opened;
+    }
+    async close() {
+        if (!this.opened)
+            return;
+        await (await this.opened).close();
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-export { JobCancelledError, JobExpiredError, JobFailedError, JobSerializationError, JobTimeoutError, JobValidationError, QueueClosedError, job, enqiu, } from "./api.js";
-export type { AnyJobSnapshot, BulkOptions, CleanupQuery, ConcurrencyPolicy, DebouncePolicy, HandlerJobDefinition, InferSchemaInput, InferSchemaOutput, JobCallable, JobContext, JobDefinition, JobDefinitions, JobHandle, JobHandler, JobListPage, JobListQuery, JobLogger, JobPolicyOptions, JobsApi, MemoryEnqiuOptions, Progress, EnqiuOptions, QueueApi, RedisEnqiuOptions, RetryPolicy, ScheduleHandle, ScheduleOptions, ScheduleSnapshot, SchemaJobDefinition, SharedEnqiuOptions, StandardSchemaIssue, StandardSchemaV1, SubmitOptions, Telemetry, TelemetryEvent, ThrottlePolicy, WorkerApi, WorkerOptions, WorkerStartOptions, } from "./api.js";
-export { redis, type RedisCommandClient, type RedisDriver, type RedisDriverOptions, } from "./redis.js";
-export type { JobSnapshot, JobStatus, JobLogEntry, JobLogLevel, QueueEventMap, QueueStats, SerializedError, } from "./memory.js";
-export { enqiu as default } from "./api.js";
+export { enqiu, enqiu as default, job } from "./api.js";
+export { JobCancelledError, JobExpiredError, JobFailedError, JobTimeoutError, JobValidationError, QueueClosedError, toError, } from "./errors.js";
+export { JobSerializationError } from "./serialize.js";
+export type { AnyJobSnapshot, BackoffOptions, BulkOptions, CleanupQuery, Enqiu, EnqiuOptions, HandlerJobDefinition, InferSchemaInput, InferSchemaOutput, JobCallable, JobContext, JobDefinition, JobDefinitions, JobHandle, JobHandler, JobListPage, JobListQuery, JobLogger, JobPolicyOptions, JobSnapshot, JobStatus, JobsApi, MaybePromise, Progress, QueueApi, QueueEventMap, QueueStats, RetryPolicy, ScheduleHandle, ScheduleOptions, ScheduleSnapshot, SchemaJobDefinition, SerializedError, StandardSchemaIssue, StandardSchemaV1, SubmitOptions, WorkerApi, WorkerOptions, WorkerStartOptions, } from "./types.js";

package/dist/index.js

@@ -1,3 +1,3 @@
-export { JobCancelledError, JobExpiredError, JobFailedError, JobSerializationError, JobTimeoutError, JobValidationError, QueueClosedError, job, enqiu, } from "./api.js";
-export { redis, } from "./redis.js";
-export { enqiu as default } from "./api.js";
+export { enqiu, enqiu as default, job } from "./api.js";
+export { JobCancelledError, JobExpiredError, JobFailedError, JobTimeoutError, JobValidationError, QueueClosedError, toError, } from "./errors.js";
+export { JobSerializationError } from "./serialize.js";

package/dist/mapping.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Everything that translates between BullMQ's vocabulary and Enqiu's.
+ *
+ * Pure, and the one part of the library that can be tested without a Redis:
+ * every other path goes through BullMQ. It lives in one place because the four
+ * directions — reading a state back, listing, cleaning, and counting — used to
+ * be four hand-written mappings, and they disagreed with each other.
+ */
+import type { Job as BullJob, FinishedStatus, JobState, JobsOptions } from "bullmq";
+import type { JobPolicyOptions, JobSnapshot, JobStatus, RetryPolicy, SubmitOptions } from "./types.js";
+/**
+ * Which BullMQ states make up each Enqiu status.
+ *
+ * `cancelled` maps to nothing: BullMQ has no state for it, so it lists and
+ * cleans as empty and the marker hash is the only record.
+ */
+export declare const bullStates: {
+    readonly queued: readonly ["waiting", "prioritized"];
+    readonly scheduled: readonly ["delayed"];
+    readonly running: readonly ["active"];
+    readonly succeeded: readonly ["completed"];
+    readonly failed: readonly ["failed"];
+    readonly cancelled: readonly [];
+};
+export declare const everyState: readonly JobState[];
+/** BullMQ's states, mapped onto Enqiu's vocabulary. */
+export declare function toStatus(state: string): JobStatus;
+/** The two states a job can no longer leave — BullMQ names the pair too. */
+export declare function isFinished(state: string): state is FinishedStatus;
+/**
+ * Enqiu's events, and the BullMQ event that carries each.
+ *
+ * `state` is what the event itself proves about the job, which saves asking
+ * Redis for a state the notification already carried — and is the more
+ * faithful answer besides, since a subscriber wants the state at the time of
+ * the event rather than whatever it has become since. `added` proves only that
+ * the job exists, not whether it was delayed or prioritized.
+ */
+export declare const queueEventMap: {
+    readonly added: {
+        readonly name: "added";
+        readonly state: undefined;
+    };
+    readonly started: {
+        readonly name: "active";
+        readonly state: "active";
+    };
+    readonly progress: {
+        readonly name: "progress";
+        readonly state: "active";
+    };
+    readonly succeeded: {
+        readonly name: "completed";
+        readonly state: "completed";
+    };
+    readonly failed: {
+        readonly name: "failed";
+        readonly state: "failed";
+    };
+    readonly error: {
+        readonly name: "error";
+        readonly state: undefined;
+    };
+};
+export declare function toSnapshot(bull: BullJob, status: JobStatus): JobSnapshot;
+export interface SubmitDefaults {
+    readonly logLimit: number;
+    readonly retry: number | RetryPolicy | undefined;
+}
+/** Options BullMQ can carry across the queue, resolved submit → job → queue. */
+export declare function toJobsOptions(options: SubmitOptions, policy: JobPolicyOptions, defaults: SubmitDefaults): JobsOptions;
+/**
+ * One offset per underlying state, because BullMQ ranges over each separately.
+ *
+ * A single number would mean "position within each state", which skips and
+ * repeats jobs the moment a status spans more than one of them.
+ */
+export declare function decodeCursor(cursor: string | undefined, states: number): number[];
+export declare function encodeCursor(offsets: readonly number[]): string;
+/** What one BullMQ state contributed to a page, and where it was read from. */
+export interface StatePage<T> {
+    readonly offset: number;
+    readonly items: readonly T[];
+}
+/**
+ * Take one page's worth across the states, and say where each got to.
+ *
+ * Pure on purpose. This is the arithmetic a single-number cursor got wrong, and
+ * leaving it inside the async method that fetches the states put it out of
+ * reach of every test that runs without a server.
+ *
+ * Offsets arrive attached to their items rather than as a second array: they
+ * are only ever meaningful in pairs, and two arrays could disagree in length
+ * with nothing to catch it.
+ */
+export declare function mergePage<T>(pages: readonly StatePage<T>[], limit: number): {
+    items: T[];
+    next: number[];
+};

package/dist/mapping.js

@@ -0,0 +1,167 @@
+/**
+ * Everything that translates between BullMQ's vocabulary and Enqiu's.
+ *
+ * Pure, and the one part of the library that can be tested without a Redis:
+ * every other path goes through BullMQ. It lives in one place because the four
+ * directions — reading a state back, listing, cleaning, and counting — used to
+ * be four hand-written mappings, and they disagreed with each other.
+ */
+import { decodeFailure, failureToError } from "./errors.js";
+/**
+ * Which BullMQ states make up each Enqiu status.
+ *
+ * `cancelled` maps to nothing: BullMQ has no state for it, so it lists and
+ * cleans as empty and the marker hash is the only record.
+ */
+export const bullStates = {
+    queued: ["waiting", "prioritized"],
+    scheduled: ["delayed"],
+    running: ["active"],
+    succeeded: ["completed"],
+    failed: ["failed"],
+    cancelled: [],
+};
+export const everyState = Object.values(bullStates).flat();
+const statusByState = new Map(Object.entries(bullStates).flatMap(([status, states]) => states.map((state) => [state, status])));
+/** BullMQ's states, mapped onto Enqiu's vocabulary. */
+export function toStatus(state) {
+    return statusByState.get(state) ?? "queued";
+}
+/** The two states a job can no longer leave — BullMQ names the pair too. */
+export function isFinished(state) {
+    return state === "completed" || state === "failed";
+}
+/**
+ * Enqiu's events, and the BullMQ event that carries each.
+ *
+ * `state` is what the event itself proves about the job, which saves asking
+ * Redis for a state the notification already carried — and is the more
+ * faithful answer besides, since a subscriber wants the state at the time of
+ * the event rather than whatever it has become since. `added` proves only that
+ * the job exists, not whether it was delayed or prioritized.
+ */
+export const queueEventMap = {
+    added: { name: "added", state: undefined },
+    started: { name: "active", state: "active" },
+    progress: { name: "progress", state: "active" },
+    succeeded: { name: "completed", state: "completed" },
+    failed: { name: "failed", state: "failed" },
+    error: { name: "error", state: undefined },
+};
+export function toSnapshot(bull, status) {
+    const snapshot = {
+        id: String(bull.id),
+        name: bull.name,
+        input: bull.data,
+        status,
+        attempt: bull.attemptsMade,
+        createdAt: bull.timestamp,
+    };
+    if (bull.processedOn)
+        snapshot.startedAt = bull.processedOn;
+    if (bull.finishedOn)
+        snapshot.finishedAt = bull.finishedOn;
+    if (bull.progress !== undefined && bull.progress !== 0) {
+        snapshot.progress = bull.progress;
+    }
+    if (bull.returnvalue !== undefined && bull.returnvalue !== null) {
+        snapshot.output = bull.returnvalue;
+    }
+    if (bull.failedReason) {
+        // A timeout or an expiry wrote down which it was, so the snapshot can name
+        // the error rather than calling everything "Error".
+        const failure = decodeFailure(bull.failedReason);
+        const error = failure ? failureToError(failure) : undefined;
+        snapshot.error = error
+            ? { name: error.name, message: error.message }
+            : { name: "Error", message: bull.failedReason };
+    }
+    return snapshot;
+}
+// BullMQ orders ascending: a lower number runs sooner.
+const priorities = { high: 1, normal: 2, low: 3 };
+/** Options BullMQ can carry across the queue, resolved submit → job → queue. */
+export function toJobsOptions(options, policy, defaults) {
+    const jobsOptions = { keepLogs: defaults.logLimit };
+    if (options.id !== undefined)
+        jobsOptions.jobId = options.id;
+    if (options.delay !== undefined) {
+        jobsOptions.delay =
+            options.delay instanceof Date
+                ? Math.max(0, options.delay.getTime() - Date.now())
+                : options.delay;
+    }
+    if (options.priority !== undefined) {
+        jobsOptions.priority =
+            typeof options.priority === "string"
+                ? priorities[options.priority]
+                : options.priority;
+    }
+    if (options.idempotencyKey !== undefined) {
+        jobsOptions.deduplication = { id: options.idempotencyKey };
+        if (options.idempotencyTtl !== undefined) {
+            jobsOptions.deduplication.ttl = options.idempotencyTtl;
+        }
+    }
+    const retry = options.retry ?? policy.retry ?? defaults.retry;
+    if (retry !== undefined) {
+        const attempts = typeof retry === "number" ? retry + 1 : retry.attempts;
+        if (!Number.isInteger(attempts) || attempts < 1) {
+            throw new RangeError("retry.attempts must be a positive integer");
+        }
+        jobsOptions.attempts = attempts;
+        const backoff = typeof retry === "number" ? undefined : retry.backoff;
+        if (backoff !== undefined) {
+            jobsOptions.backoff =
+                typeof backoff === "number"
+                    ? backoff
+                    : { type: backoff.type ?? "fixed", delay: backoff.delay };
+        }
+    }
+    return jobsOptions;
+}
+/**
+ * One offset per underlying state, because BullMQ ranges over each separately.
+ *
+ * A single number would mean "position within each state", which skips and
+ * repeats jobs the moment a status spans more than one of them.
+ */
+export function decodeCursor(cursor, states) {
+    if (cursor === undefined)
+        return new Array(states).fill(0);
+    const offsets = cursor.split(".").map((part) => Number.parseInt(part, 10));
+    const usable = offsets.length === states &&
+        offsets.every((offset) => Number.isInteger(offset) && offset >= 0);
+    if (!usable)
+        throw new TypeError("Invalid list cursor");
+    return offsets;
+}
+export function encodeCursor(offsets) {
+    return offsets.join(".");
+}
+/**
+ * Take one page's worth across the states, and say where each got to.
+ *
+ * Pure on purpose. This is the arithmetic a single-number cursor got wrong, and
+ * leaving it inside the async method that fetches the states put it out of
+ * reach of every test that runs without a server.
+ *
+ * Offsets arrive attached to their items rather than as a second array: they
+ * are only ever meaningful in pairs, and two arrays could disagree in length
+ * with nothing to catch it.
+ */
+export function mergePage(pages, limit) {
+    const items = [];
+    const next = [];
+    for (const page of pages) {
+        let taken = 0;
+        for (const item of page.items) {
+            if (items.length === limit)
+                break;
+            items.push(item);
+            taken += 1;
+        }
+        next.push(page.offset + taken);
+    }
+    return { items, next };
+}

package/dist/markers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where cancellations are recorded.
+ *
+ * BullMQ has no cancelled state, and cancelling a job that has not started
+ * removes it — so without a marker the only evidence is gone and `refresh()`
+ * cannot tell "cancelled" from "never existed". A process-local Set was the
+ * obvious first answer and the wrong one: it made a job's fate depend on which
+ * process asked, and lost it entirely on restart.
+ *
+ * What is stored is the finished snapshot itself, not a reason beside a copy of
+ * one: it is the only record left once the job is gone, and everything a reader
+ * wants is already a field of `JobSnapshot`. Wrapping it meant three records of
+ * one event that had to agree, reassembled differently by each reader.
+ */
+import type { Queue } from "bullmq";
+import type { JobSnapshot } from "./types.js";
+export declare class CancellationMarkers {
+    private readonly queue;
+    private readonly key;
+    constructor(queue: Queue);
+    write(id: string, snapshot: JobSnapshot): Promise<void>;
+    read(id: string): Promise<JobSnapshot | undefined>;
+    /** Markers outlive their jobs otherwise, so the hash grows forever. */
+    prune(threshold: number): Promise<void>;
+}