@sqlane/core 0.1.0 → 0.1.2

package/types/errors.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The base of the errors of sqlane.
+ */
+export declare class SqlaneError extends Error {
+    /** @readonly */
+    code: string;
+    /**
+     * @param {string} code A stable code, e.g. `CONFIG`.
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+/** Bad `createSqlane`, `defineJob` or `handle()` options. */
+export declare class ConfigError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Bad enqueue options: a bad name or `jobId`, `delay` with `runAt`. */
+export declare class InvalidOptionsError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The payload is above `maxPayloadBytes`. */
+export declare class PayloadTooLargeError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** More than 10 mutex keys, or a key that breaks the rules. */
+export declare class InvalidMutexKeyError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Enqueue of an unknown name with `unknownJobs: 'reject'`. */
+export declare class UnknownJobError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** `start`, `handle` or `drain` after `close()`. */
+export declare class ClosedError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** `drain()` did not finish in its `timeout`. */
+export declare class DrainTimeoutError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The `signal.reason` on a timeout; the error of the attempt. */
+export declare class JobTimeoutError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The `signal.reason` at the close deadline. */
+export declare class ShutdownError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The `signal.reason` when the lease could not be renewed in time. */
+export declare class LeaseLostError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The error of a job without its payload. */
+export declare class MissingPayloadError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown by a handler: the job fails at once, without retries; its failure job runs. */
+export declare class FatalJobError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown by a handler: the job is retried after `delay` instead of the backoff. It still uses an attempt. */
+export declare class RetryJobError extends SqlaneError {
+    /** @readonly */
+    delay: import("./types.js").Duration;
+    /**
+     * @param {string} message
+     * @param {ErrorOptions & { delay: import('./types.js').Duration }} options
+     */
+    constructor(message: string, options: ErrorOptions & {
+        delay: import('./types.js').Duration;
+    });
+}
+/** `migrate()` did not get the migration lock in its `lockTimeout`. */
+export declare class MigrationLockTimeoutError extends SqlaneError {
+    /**
+     * @param {string} message
+     * @param {ErrorOptions} [options]
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/types/hint_channel.d.ts

@@ -0,0 +1,31 @@
+/** The message after a release of mutex keys: every process probes all its names */
+export declare const ANY_NAME = "*";
+export type HintChannel = {
+    /**
+     * Fire-and-forget: never throws, never waits.
+     */
+    publish: (name: string) => void;
+    listen: (onMessage: (name: string) => void) => Promise<void>;
+    /**
+     * Stops listening; drops the pending messages.
+     */
+    stop: () => Promise<void>;
+};
+/**
+ * @typedef {object} HintChannel
+ * @property {(name: string) => void} publish Fire-and-forget: never throws, never waits.
+ * @property {(onMessage: (name: string) => void) => Promise<void>} listen
+ * @property {() => Promise<void>} stop Stops listening; drops the pending messages.
+ */
+/**
+ * @param {object} params
+ * @param {import('./types.js').Hint | null} params.hint
+ * @param {string} params.channel
+ * @param {(operation: string, error: unknown) => void} params.reportError
+ * @returns {HintChannel}
+ */
+export declare function createHintChannel({ hint, channel, reportError }: {
+    hint: import('./types.js').Hint | null;
+    channel: string;
+    reportError: (operation: string, error: unknown) => void;
+}): HintChannel;

package/types/index.d.ts

@@ -0,0 +1,72 @@
+export { createSqlane } from './create_sqlane.js';
+export { defineJob } from './define_job.js';
+export { ClosedError, ConfigError, DrainTimeoutError, FatalJobError, InvalidMutexKeyError, InvalidOptionsError, JobTimeoutError, LeaseLostError, MigrationLockTimeoutError, MissingPayloadError, PayloadTooLargeError, RetryJobError, ShutdownError, SqlaneError, UnknownJobError, } from './errors.js';
+export { getMigrations } from './migrations.js';
+export type Adapter<C> = import('./types.js').Adapter<C>;
+export type Sqlane<C, L extends string> = import('./types.js').Sqlane<C, L>;
+export type SqlaneOptions<C, L extends string> = import('./types.js').SqlaneOptions<C, L>;
+export type Jsonable<T> = import('./types.js').Jsonable<T>;
+export type Backoff = import('./types.js').Backoff;
+export type CloseOptions = import('./types.js').CloseOptions;
+export type DrainOptions = import('./types.js').DrainOptions;
+export type DrainResult = import('./types.js').DrainResult;
+export type Duration = import('./types.js').Duration;
+export type EnqueueOptions = import('./types.js').EnqueueOptions;
+export type EnqueueResult = import('./types.js').EnqueueResult;
+export type Executor = import('./types.js').Executor;
+export type FailedJobPayload = import('./types.js').FailedJobPayload;
+export type Handler = import('./types.js').Handler;
+export type HandlerContext = import('./types.js').HandlerContext;
+export type Hint = import('./types.js').Hint;
+export type JobDefaults = import('./types.js').JobDefaults;
+export type JobDefinition = import('./types.js').JobDefinition;
+export type JobInfo = import('./types.js').JobInfo;
+export type JobOptions = import('./types.js').JobOptions;
+export type JobStats = import('./types.js').JobStats;
+export type LaneOptions = import('./types.js').LaneOptions;
+export type Logger = import('./types.js').Logger;
+export type MigrateOptions = import('./types.js').MigrateOptions;
+export type Migration = import('./types.js').Migration;
+export type Retention = import('./types.js').Retention;
+export type SqlaneEvent = import('./types.js').SqlaneEvent;
+/**
+ * @typedef {import('./types.js').Adapter<C>} Adapter
+ * @template C
+ */
+/**
+ * @typedef {import('./types.js').Sqlane<C, L>} Sqlane
+ * @template C
+ * @template {string} L
+ */
+/**
+ * @typedef {import('./types.js').SqlaneOptions<C, L>} SqlaneOptions
+ * @template C
+ * @template {string} L
+ */
+/**
+ * @typedef {import('./types.js').Jsonable<T>} Jsonable
+ * @template T
+ */
+/** @typedef {import('./types.js').Backoff} Backoff */
+/** @typedef {import('./types.js').CloseOptions} CloseOptions */
+/** @typedef {import('./types.js').DrainOptions} DrainOptions */
+/** @typedef {import('./types.js').DrainResult} DrainResult */
+/** @typedef {import('./types.js').Duration} Duration */
+/** @typedef {import('./types.js').EnqueueOptions} EnqueueOptions */
+/** @typedef {import('./types.js').EnqueueResult} EnqueueResult */
+/** @typedef {import('./types.js').Executor} Executor */
+/** @typedef {import('./types.js').FailedJobPayload} FailedJobPayload */
+/** @typedef {import('./types.js').Handler} Handler */
+/** @typedef {import('./types.js').HandlerContext} HandlerContext */
+/** @typedef {import('./types.js').Hint} Hint */
+/** @typedef {import('./types.js').JobDefaults} JobDefaults */
+/** @typedef {import('./types.js').JobDefinition} JobDefinition */
+/** @typedef {import('./types.js').JobInfo} JobInfo */
+/** @typedef {import('./types.js').JobOptions} JobOptions */
+/** @typedef {import('./types.js').JobStats} JobStats */
+/** @typedef {import('./types.js').LaneOptions} LaneOptions */
+/** @typedef {import('./types.js').Logger} Logger */
+/** @typedef {import('./types.js').MigrateOptions} MigrateOptions */
+/** @typedef {import('./types.js').Migration} Migration */
+/** @typedef {import('./types.js').Retention} Retention */
+/** @typedef {import('./types.js').SqlaneEvent} SqlaneEvent */

package/types/migrations.d.ts

@@ -0,0 +1,22 @@
+export type Executor = import('./types.js').Executor;
+/** @typedef {import('./types.js').Executor} Executor */
+/**
+ * The schema of sqlane as versioned SQL, for the app's own migration tool.
+ * @param {object} options
+ * @param {'mysql' | 'postgres'} options.dialect
+ * @param {string} [options.tablePrefix] Default: `'sqlane_'`.
+ * @returns {import('./types.js').Migration[]}
+ */
+export declare function getMigrations({ dialect, tablePrefix }: {
+    dialect: 'mysql' | 'postgres';
+    tablePrefix?: string;
+}): import('./types.js').Migration[];
+/**
+ * Applies the missing migrations under a DB lock, on a connection of its own, without a statement timeout.
+ * @template C
+ * @param {import('./types.js').Adapter<C>} adapter
+ * @param {string} tablePrefix Checked.
+ * @param {import('./types.js').MigrateOptions} [options]
+ * @returns {Promise<string[]>} The ids of the applied migrations.
+ */
+export declare function runMigrations<C>(adapter: import('./types.js').Adapter<C>, tablePrefix: string, options?: import('./types.js').MigrateOptions): Promise<string[]>;

package/types/mutex_keys.d.ts

@@ -0,0 +1,9 @@
+export declare const MAX_MUTEX_KEYS = 10;
+export declare const MAX_MUTEX_KEY_LENGTH = 255;
+/**
+ * Checks the mutex keys of a job.
+ * @param {unknown} keys
+ * @param {string} where For the error message.
+ * @returns {string[]} The keys without duplicates, sorted (the lock order).
+ */
+export declare function normalizeMutexKeys(keys: unknown, where: string): string[];

package/types/new_job.d.ts

@@ -0,0 +1,40 @@
+export type NewJob = {
+    /**
+     * `<name>:<jobId>`, or a ULID.
+     */
+    id: string;
+    hasJobId: boolean;
+    name: string;
+    payloadJson: string;
+    /**
+     * Sorted, without duplicates.
+     */
+    mutexKeys: readonly string[];
+    maxAttempts: number;
+    maxStalls: number;
+    completedRetentionMs: number;
+    failedRetentionMs: number;
+    failureJob: string | null;
+    /**
+     * From the DB clock at insert. 0 with `runAt`.
+     */
+    delayMs: number;
+    runAt: Date | null;
+};
+export type NewJobParams = {
+    name: string;
+    /**
+     * Null: an unknown name, the defaults only.
+     */
+    definition: import('./types.js').JobDefinition | null;
+    defaults: import('./defaults.js').ResolvedDefaults;
+    payload: unknown;
+    options: import('./types.js').EnqueueOptions | undefined;
+    maxPayloadBytes: number;
+};
+/**
+ * Checks an enqueue and computes the job to insert: options, then the definition, then the defaults.
+ * @param {NewJobParams} params
+ * @returns {NewJob}
+ */
+export declare function buildNewJob({ name, definition, defaults, payload, options, maxPayloadBytes }: NewJobParams): NewJob;

package/types/payload.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_MAX_PAYLOAD_BYTES: number;
+/**
+ * Serializes a payload: JSON, well-formed strings (MySQL refuses a lone surrogate), no NUL character (PostgreSQL
+ * refuses it), at most maxBytes.
+ * @param {unknown} payload
+ * @param {number} maxBytes
+ * @param {string} where For the error message.
+ * @returns {string} The JSON.
+ */
+export declare function serializePayload(payload: unknown, maxBytes: number, where: string): string;

package/types/registry.d.ts

@@ -0,0 +1,72 @@
+export type JobDefinition = import('./types.js').JobDefinition;
+export type Lane = {
+    name: string;
+    concurrency: number;
+    running: number;
+};
+export type HandlerEntry = {
+    name: string;
+    definition: JobDefinition | null;
+    handler: import('./types.js').Handler;
+    lane: Lane;
+    /**
+     * Resolved: the handle() options, else the definition, else the defaults.
+     */
+    timeoutMs: number | null;
+};
+export type Registry = {
+    handle: (job: JobDefinition | string, handler: import('./types.js').Handler, options?: object) => void;
+    getEntry: (name: string) => HandlerEntry | undefined;
+    entries: () => HandlerEntry[];
+    /**
+     * In `jobs`, else handled.
+     */
+    findDefinition: (name: string) => JobDefinition | null;
+    /**
+     * The handled names whose definition has mutex keys.
+     */
+    keyedNames: () => string[];
+    /**
+     * Checks the handlers together: each failure job resolves and has none of its own.
+     */
+    validate: () => void;
+};
+/** @typedef {import('./types.js').JobDefinition} JobDefinition */
+/**
+ * A concurrency limit in this process.
+ * @typedef {object} Lane
+ * @property {string} name
+ * @property {number} concurrency
+ * @property {number} running
+ */
+/**
+ * @typedef {object} HandlerEntry
+ * @property {string} name
+ * @property {JobDefinition | null} definition
+ * @property {import('./types.js').Handler} handler
+ * @property {Lane} lane
+ * @property {number | null} timeoutMs Resolved: the handle() options, else the definition, else the defaults.
+ */
+/**
+ * @typedef {object} Registry
+ * @property {(job: JobDefinition | string, handler: import('./types.js').Handler, options?: object) => void} handle
+ * @property {(name: string) => HandlerEntry | undefined} getEntry
+ * @property {() => HandlerEntry[]} entries
+ * @property {(name: string) => JobDefinition | null} findDefinition In `jobs`, else handled.
+ * @property {() => string[]} keyedNames The handled names whose definition has mutex keys.
+ * @property {() => void} validate Checks the handlers together: each failure job resolves and has none of its own.
+ */
+/**
+ * @param {object} params
+ * @param {Map<string, JobDefinition>} params.jobsByName
+ * @param {unknown} params.lanes The `lanes` option.
+ * @param {number} params.concurrency The process concurrency.
+ * @param {number | null} params.defaultTimeoutMs
+ * @returns {Registry}
+ */
+export declare function createRegistry({ jobsByName, lanes, concurrency, defaultTimeoutMs }: {
+    jobsByName: Map<string, JobDefinition>;
+    lanes: unknown;
+    concurrency: number;
+    defaultTimeoutMs: number | null;
+}): Registry;

package/types/runner.d.ts

@@ -0,0 +1,92 @@
+export type ClaimedJob = import('./store/store.js').ClaimedJob;
+export type HandlerEntry = import('./registry.js').HandlerEntry;
+export type Lane = import('./registry.js').Lane;
+export type Timings = {
+    leaseMs: number;
+    renewIntervalMs: number;
+    recoveryIntervalMs: number;
+    cleanupIntervalMs: number;
+    pollIntervalMs: number;
+    /**
+     * How long a failed write of a result is retried.
+     */
+    maxFinalizingMs: number;
+    /**
+     * A job without its payload waits this long for it.
+     */
+    missingPayloadGraceMs: number;
+};
+/** @typedef {import('./store/store.js').ClaimedJob} ClaimedJob */
+/** @typedef {import('./registry.js').HandlerEntry} HandlerEntry */
+/** @typedef {import('./registry.js').Lane} Lane */
+/**
+ * @typedef {object} Timings
+ * @property {number} leaseMs
+ * @property {number} renewIntervalMs
+ * @property {number} recoveryIntervalMs
+ * @property {number} cleanupIntervalMs
+ * @property {number} pollIntervalMs
+ * @property {number} maxFinalizingMs How long a failed write of a result is retried.
+ * @property {number} missingPayloadGraceMs A job without its payload waits this long for it.
+ */
+/** @type {Timings} */
+export declare const DEFAULT_TIMINGS: Timings;
+export type RunningJob = {
+    key: string;
+    claimed: ClaimedJob;
+    entry: HandlerEntry;
+    controller: AbortController;
+    /**
+     * Resolves when the result is written (or given up).
+     */
+    done: Promise<void>;
+    /**
+     * The handler settled.
+     */
+    settled: boolean;
+    /**
+     * Released or abandoned on close: the result is not written.
+     */
+    released: boolean;
+    timedOut: boolean;
+    leaseLost: boolean;
+    leaseEndsAt: number;
+    startedAt: number;
+};
+export type RunnerParams = {
+    store: import('./store/store.js').Store;
+    registry: import('./registry.js').Registry;
+    concurrency: number;
+    defaults: import('./defaults.js').ResolvedDefaults;
+    cleanup: boolean;
+    logger: import('./types.js').Logger | undefined;
+    onEvent: ((event: import('./types.js').SqlaneEvent) => void) | undefined;
+    hintChannel: import('./hint_channel.js').HintChannel;
+    /**
+     * The hints come after the commit of their enqueue (PostgreSQL NOTIFY): they wake
+     * at once, with no re-probes.
+     */
+    hintsAfterCommit: boolean;
+    /**
+     * For tests.
+     */
+    timings?: Partial<Timings>;
+};
+export type Runner = {
+    start: () => Promise<void>;
+    drain: (options?: import('./types.js').DrainOptions) => Promise<import('./types.js').DrainResult>;
+    close: (options?: import('./types.js').CloseOptions) => Promise<void>;
+    wake: (name: string) => void;
+    onEnqueued: (names: string[]) => void;
+    isClosed: () => boolean;
+    isStarted: () => boolean;
+    /**
+     * This process handles the name and has a free slot for it.
+     */
+    canStartNow: (name: string) => boolean;
+};
+/**
+ * @param {RunnerParams} params
+ * @returns {Runner}
+ */
+export declare function createRunner({ store, registry, concurrency, defaults, cleanup, logger, onEvent, hintChannel, hintsAfterCommit, timings, }: RunnerParams): Runner;

package/types/schema/mysql.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @param {string} p The table prefix.
+ * @returns {import('../types.js').Migration[]}
+ */
+export declare function mysqlMigrations(p: string): import('../types.js').Migration[];
+/**
+ * @param {string} p
+ * @returns {string}
+ */
+export declare function mysqlMigrationsTable(p: string): string;

package/types/schema/postgres.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @param {string} p The table prefix.
+ * @returns {import('../types.js').Migration[]}
+ */
+export declare function postgresMigrations(p: string): import('../types.js').Migration[];
+/**
+ * @param {string} p
+ * @returns {string}
+ */
+export declare function postgresMigrationsTable(p: string): string;

package/types/store/mysql_enqueue.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Inserts the jobs and their payloads. Call it in a transaction.
+ * @param {import('../types.js').Executor} executor
+ * @param {string} p The table prefix.
+ * @param {import('../new_job.js').NewJob[]} jobs Their ids are distinct.
+ * @param {string} enqueueToken
+ * @returns {Promise<Set<string>>} The ids that this call created.
+ */
+export declare function insertJobsMysql(executor: import('../types.js').Executor, p: string, jobs: import('../new_job.js').NewJob[], enqueueToken: string): Promise<Set<string>>;

package/types/store/mysql_final.d.ts

@@ -0,0 +1,135 @@
+export type Executor = import('../types.js').Executor;
+export type OwnedJob = import('./store.js').OwnedJob;
+export type FailureJobBuilder = import('./store.js').FailureJobBuilder;
+export type FailureJobResult = import('./store.js').FailureJobResult;
+/**
+ * Renews the leases of the jobs that the process runs. A row locked by another transaction is skipped: it does not
+ * block the others.
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {OwnedJob[]} jobs
+ * @param {number} leaseMs
+ * @returns {Promise<Set<string>>} The ids whose lease was renewed.
+ */
+export declare function renewLeases(executor: Executor, p: string, jobs: OwnedJob[], leaseMs: number): Promise<Set<string>>;
+/**
+ * Marks a timeout: the job stays running until its handler settles (`stuck` in the stats).
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {OwnedJob} job
+ * @returns {Promise<boolean>} False: the lease was lost.
+ */
+export declare function markTimedOut(executor: Executor, p: string, job: OwnedJob): Promise<boolean>;
+/**
+ * The jobs are done: completed until their retention ends, without their payloads; their keys are freed. One
+ * transaction for many jobs: one commit.
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {import('./store.js').FinishedJob[]} jobs
+ * @returns {Promise<number>} The jobs that this call completed: the others lost their lease, or an earlier try
+ *     committed.
+ */
+export declare function completeJobs(executor: Executor, p: string, jobs: import('./store.js').FinishedJob[]): Promise<number>;
+/**
+ * The attempt failed: pending again after the delay, one more attempt used; its keys are freed.
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {OwnedJob} job
+ * @param {{ delayMs: number, error: import('../error_json.js').ErrorJson }} params
+ * @returns {Promise<boolean>} False: no change.
+ */
+export declare function retryJob(executor: Executor, p: string, job: OwnedJob, { delayMs, error }: {
+    delayMs: number;
+    error: import('../error_json.js').ErrorJson;
+}): Promise<boolean>;
+/**
+ * The job fails for good: failed until its retention ends, with its payload; its keys are freed; its failure job is
+ * added in the same transaction.
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {OwnedJob} job
+ * @param {{ error: import('../error_json.js').ErrorJson, buildFailureJob: FailureJobBuilder }} params
+ * @returns {Promise<{ changed: boolean, failureJob: FailureJobResult | null }>}
+ */
+export declare function failJob(executor: Executor, p: string, job: OwnedJob, { error, buildFailureJob }: {
+    error: import('../error_json.js').ErrorJson;
+    buildFailureJob: FailureJobBuilder;
+}): Promise<{
+    changed: boolean;
+    failureJob: FailureJobResult | null;
+}>;
+/**
+ * The job is released, without an attempt used: pending again after the delay.
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {OwnedJob} job
+ * @param {{ delayMs: number, lingerMs: number }} params lingerMs: its keys stay held this long (its handler still
+ *     runs); 0: they are freed.
+ * @returns {Promise<boolean>} False: no change.
+ */
+export declare function releaseJob(executor: Executor, p: string, job: OwnedJob, { delayMs, lingerMs }: {
+    delayMs: number;
+    lingerMs: number;
+}): Promise<boolean>;
+/**
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {number} limit
+ * @returns {Promise<{ id: string, name: string }[]>} The running jobs whose lease ended, the oldest first.
+ */
+export declare function findStaleJobs(executor: Executor, p: string, limit: number): Promise<{
+    id: string;
+    name: string;
+}[]>;
+/**
+ * A running job whose lease ended: one more stall, pending again after 30 s × 2^stalls (at most 1 h); after maxStalls,
+ * it fails for good. Its keys linger for one lease: its old handler may still run.
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {string} id
+ * @param {{ leaseMs: number, buildFailureJob: FailureJobBuilder }} params
+ * @returns {Promise<{ result: 'released' | 'failed' | null, failureJob: FailureJobResult | null }>} null: not stale
+ *     (any more).
+ */
+export declare function recoverStaleJob(executor: Executor, p: string, id: string, { leaseMs, buildFailureJob }: {
+    leaseMs: number;
+    buildFailureJob: FailureJobBuilder;
+}): Promise<{
+    result: 'released' | 'failed' | null;
+    failureJob: FailureJobResult | null;
+}>;
+/**
+ * Deletes the ended lingers, and the holds without their running job (from a manual change, or old code).
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {number} limit
+ * @returns {Promise<{ lingers: number, orphans: number }>}
+ */
+export declare function sweepMutexes(executor: Executor, p: string, limit: number): Promise<{
+    lingers: number;
+    orphans: number;
+}>;
+/**
+ * Deletes a batch of completed and failed jobs whose retention ended, with their payloads. SKIP LOCKED: processes
+ * share the work.
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {number} limit
+ * @returns {Promise<number>} The deleted jobs.
+ */
+export declare function deleteExpiredJobs(executor: Executor, p: string, limit: number): Promise<number>;
+/**
+ * For drain({ includeDelayed }): the pending jobs of the names are due now.
+ * @param {Executor} executor
+ * @param {string} p
+ * @param {string[]} names
+ * @returns {Promise<void>}
+ */
+export declare function makeDue(executor: Executor, p: string, names: string[]): Promise<void>;
+/**
+ * The counts per job name, for alerts such as "queue stuck". Reads the status index only.
+ * @param {Executor} executor
+ * @param {string} p
+ * @returns {Promise<import('../types.js').JobStats[]>}
+ */
+export declare function getStats(executor: Executor, p: string): Promise<import('../types.js').JobStats[]>;