@sqlane/core 0.1.0 → 0.1.2

package/README.md

@@ -52,6 +52,15 @@ process.once('SIGTERM', () => sqlane.close({ deadline: '30s' }));
 
 In tests, run the due jobs without `start()`: `await sqlane.drain()`. More in [`examples/`](examples).
 
+## Performance
+
+On a laptop (M1 Pro, Docker, default config), details in [benchmarks](docs/benchmarks.md):
+
+- 1000 handled job names, 10 with pending jobs: the probe takes under 1 ms. Idle names cost nothing.
+- From commit to handler start: about 25 ms (re-probe or hint), about 5 ms with PostgreSQL NOTIFY.
+- `enqueueMany`: 58,000–110,000 jobs/s. Empty jobs, one process: 1,000–1,800 jobs/s at concurrency 10,
+  3,800–5,800 at concurrency 50.
+
 ## Development
 
 Requires [mise](https://mise.jdx.dev). It installs Node.js, pnpm, hk, betterleaks and typos (`mise.toml`).
@@ -71,6 +80,7 @@ hk install --global --mise   # Git hooks, also for GUI Git clients: lint, format
 | `pnpm lint:package` | Check the package that npm would publish (publint)         |
 | `pnpm typecheck`    | Type-check the JSDoc (`tsc`, no emit)                      |
 | `pnpm check`        | Run all hook checks on all files (`hk check --all`)        |
+| `pnpm bench`        | Run the [benchmarks](docs/benchmarks.md) (Docker)          |
 
 Commit messages follow [Conventional Commits](https://www.conventionalcommits.org). A change of the package adds a
 changeset (`pnpm changeset`); see [releasing](docs/releasing.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqlane/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Transactional SQL job queue for Node.js (MySQL, PostgreSQL)",
   "keywords": [
     "background-jobs",
@@ -22,13 +22,23 @@
   },
   "files": [
     "src",
-    "!src/**/*.test.js"
+    "!src/**/*.test.js",
+    "types"
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.js",
-    "./mysql2": "./src/adapters/mysql2.js",
-    "./pg": "./src/adapters/pg.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./mysql2": {
+      "types": "./types/adapters/mysql2.d.ts",
+      "default": "./src/adapters/mysql2.js"
+    },
+    "./pg": {
+      "types": "./types/adapters/pg.d.ts",
+      "default": "./src/adapters/pg.js"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -38,6 +48,7 @@
     "ulid": "^3.0.2"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
     "@changesets/changelog-github": "1.0.1",
     "@changesets/cli": "3.0.3",
     "@stylistic/eslint-plugin": "5.10.0",
@@ -74,15 +85,19 @@
     "lint": "oxlint --deny-warnings",
     "lint:fix": "oxlint --fix",
     "lint:package": "publint --strict",
+    "lint:types": "attw --pack . --profile esm-only",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
     "typecheck": "tsc -p tsconfig.json",
+    "build:types": "node --eval \"require('node:fs').rmSync('types', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "check:types": "out=$(mktemp -d) && tsc -p tsconfig.build.json --declarationDir \"$out\" && diff -r types \"$out\"; status=$?; rm -rf \"$out\"; exit $status",
     "test": "vitest run",
     "test:unit": "vitest run --project unit",
     "test:integration": "vitest run --project 'integration:*'",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "check": "hk check --all",
+    "bench": "node bench/run.js",
     "changeset": "changeset",
     "changeset:version": "changeset version && oxfmt --no-error-on-unmatched-pattern CHANGELOG.md"
   }

package/src/create_sqlane.js

@@ -147,6 +147,7 @@ export function createSqlane(options) {
         logger: options.logger,
         onEvent: options.onEvent,
         hintChannel,
+        hintsAfterCommit: Boolean(adapter.notify),
         timings: { pollIntervalMs, ...testTimings },
     });
     const enqueuer = createEnqueuer({

package/src/runner.js

@@ -47,11 +47,13 @@ export const DEFAULT_TIMINGS = {
     missingPayloadGraceMs: 60_000,
 };
 
-/** The wakes after an enqueue in this process, until the commit makes the job visible */
+/** The wakes after the last enqueue (or hint), until its commit makes the job visible */
 const REPROBE_DELAYS_MS = [20, 50, 100, 200, 500, 1000, 2000];
 const RELEASE_EXTRA_DELAY_MS = 2000;
 const STALLED = { name: 'StalledError', message: 'The lease of the job ended: its process stopped or blocked' };
 const BATCH = 1000;
+/** The completed jobs of one write */
+const MAX_COMPLETE_BATCH = 100;
 
 /**
  * @typedef {object} RunningJob
@@ -78,6 +80,8 @@ const BATCH = 1000;
  * @property {import('./types.js').Logger | undefined} logger
  * @property {((event: import('./types.js').SqlaneEvent) => void) | undefined} onEvent
  * @property {import('./hint_channel.js').HintChannel} hintChannel
+ * @property {boolean} hintsAfterCommit The hints come after the commit of their enqueue (PostgreSQL NOTIFY): they wake
+ *     at once, with no re-probes.
  * @property {Partial<Timings>} [timings] For tests.
  */
 
@@ -93,6 +97,24 @@ const BATCH = 1000;
  * @property {(name: string) => boolean} canStartNow This process handles the name and has a free slot for it.
  */
 
+/**
+ * Waits for the promise, at most `ms`. The timer ends with the wait: it keeps no process alive after it.
+ * @param {Promise<unknown>} promise
+ * @param {number} ms
+ * @param {{ ref?: boolean }} [options] `ref: false`: the timer alone does not keep the process alive.
+ * @returns {Promise<void>}
+ */
+async function waitAtMost(promise, ms, { ref = true } = {}) {
+    const controller = new AbortController();
+
+    try {
+        // The race handles the rejection of the aborted timer
+        await Promise.race([promise, sleep(Math.max(ms, 0), undefined, { signal: controller.signal, ref })]);
+    } finally {
+        controller.abort();
+    }
+}
+
 /**
  * @param {RunningJob} job
  * @returns {import('./types.js').HandlerContext}
@@ -127,6 +149,7 @@ export function createRunner({
     logger,
     onEvent,
     hintChannel,
+    hintsAfterCommit,
     timings = {},
 }) {
     const t = { ...DEFAULT_TIMINGS, ...timings };
@@ -145,10 +168,15 @@ export function createRunner({
     let closeDone = null;
     /** @type {Set<NodeJS.Timeout>} */
     const timers = new Set();
-    /** @type {Set<string>} The names with a series of re-probes */
-    const reprobing = new Set();
+    /** The time of the last enqueue (or hint): the re-probes follow it */
+    let reprobeFrom = 0;
+    /** @type {{ timer: NodeJS.Timeout, at: number } | null} The next re-probe */
+    let reprobe = null;
     let contentionDelayMs = 0;
     const counts = { completed: 0, retried: 0, failed: 0 };
+    /** @type {{ job: import('./store/store.js').FinishedJob, written: PromiseWithResolvers<void> }[]} */
+    let toComplete = [];
+    let completing = false;
     /** The jobs that finished: their results are written */
     let finishedCount = 0;
 
@@ -175,6 +203,7 @@ export function createRunner({
     /**
      * @param {() => void} func
      * @param {number} delayMs
+     * @returns {NodeJS.Timeout}
      */
     function setTimer(func, delayMs) {
         const timer = setTimeout(() => {
@@ -184,6 +213,8 @@ export function createRunner({
 
         timer.unref();
         timers.add(timer);
+
+        return timer;
     }
 
     /**
@@ -338,6 +369,50 @@ export function createRunner({
         }
     }
 
+    /**
+     * Completes the job in the next write. One write at a time: the jobs that finish during a write go together in the
+     * next one, in one transaction. A lone job waits for no other.
+     * @param {import('./store/store.js').FinishedJob} job
+     * @returns {Promise<void>} Rejects with the error of its write.
+     */
+    function completeJob(job) {
+        const written = Promise.withResolvers();
+
+        toComplete.push({ job, written });
+
+        if (!completing) {
+            void writeCompletions();
+        }
+
+        return written.promise;
+    }
+
+    async function writeCompletions() {
+        completing = true;
+
+        while (toComplete.length) {
+            const batch = toComplete.slice(0, MAX_COMPLETE_BATCH);
+
+            toComplete = toComplete.slice(MAX_COMPLETE_BATCH);
+
+            try {
+                // In the order of the ids: the row locks of two writes come in one order
+                // oxlint-disable-next-line no-await-in-loop -- one write at a time
+                await store.completeJobs(batch.map(entry => entry.job).toSorted((a, b) => (a.id < b.id ? -1 : 1)));
+
+                for (const { written } of batch) {
+                    written.resolve();
+                }
+            } catch (error) {
+                for (const { written } of batch) {
+                    written.reject(error);
+                }
+            }
+        }
+
+        completing = false;
+    }
+
     /**
      * Runs a write of the result until it succeeds; on errors, it retries with a backoff while the lease is renewed.
      * @param {RunningJob} job
@@ -378,7 +453,7 @@ export function createRunner({
         const durationMs = Date.now() - job.startedAt;
 
         if (error === null && !job.timedOut) {
-            await writeResult(job, () => store.completeJob(claimed));
+            await writeResult(job, () => completeJob(claimed));
             counts.completed++;
             emit({ type: 'completed', ...base, durationMs });
 
@@ -505,7 +580,7 @@ export function createRunner({
         }
 
         // The job keeps its keys and its slot until the handler settles, at most one more lease
-        await Promise.race([handlerDone, sleep(t.leaseMs, undefined, { ref: false })]);
+        await waitAtMost(handlerDone, t.leaseMs, { ref: false });
 
         return timeoutError;
     }
@@ -757,22 +832,55 @@ export function createRunner({
             return;
         }
 
-        for (const name of names) {
-            if ((name !== ANY_NAME && !registry.getEntry(name)) || reprobing.has(name)) {
-                continue;
-            }
+        if (!handlesAny(names)) {
+            return;
+        }
 
-            reprobing.add(name);
+        // A wake probes all the names: one series of re-probes, from the last enqueue
+        reprobeFrom = Date.now();
 
-            let elapsedMs = 0;
+        // A re-probe that comes sooner stays: then the series goes on from this enqueue. A burst of enqueues gives a
+        // re-probe at most each first step, not one per enqueue.
+        if (reprobe && reprobe.at <= reprobeFrom + REPROBE_DELAYS_MS[0]) {
+            return;
+        }
 
-            for (const delayMs of REPROBE_DELAYS_MS.filter(delay => delay < t.pollIntervalMs)) {
-                elapsedMs = delayMs;
-                setTimer(wakeUp, delayMs);
-            }
+        if (reprobe) {
+            clearTimeout(reprobe.timer);
+            timers.delete(reprobe.timer);
+        }
 
-            setTimer(() => reprobing.delete(name), elapsedMs);
+        scheduleReprobe();
+    }
+
+    /**
+     * @param {string[]} names
+     * @returns {boolean} This process handles one of the names, or one is `*`.
+     */
+    function handlesAny(names) {
+        return names.some(name => name === ANY_NAME || registry.getEntry(name));
+    }
+
+    /** Sets the timer of the next step of the series, if one is left before the poll. */
+    function scheduleReprobe() {
+        const now = Date.now();
+        const at = REPROBE_DELAYS_MS
+            .filter(delay => delay < t.pollIntervalMs)
+            .map(delay => reprobeFrom + delay)
+            .find(time => time > now);
+
+        if (at === undefined || state !== 'started') {
+            reprobe = null;
+
+            return;
         }
+
+        const timer = setTimer(() => {
+            wakeUp();
+            scheduleReprobe();
+        }, at - now);
+
+        reprobe = { at, timer };
     }
 
     async function start() {
@@ -796,8 +904,15 @@ export function createRunner({
         loopDone = loop();
 
         try {
-            // A hint is sent before the commit of its enqueue: re-probe until the job is visible
-            await hintChannel.listen(name => onEnqueued([name]));
+            // NOTIFY comes after the commit: the job is visible. Another hint is sent before the commit of its enqueue:
+            // re-probe until the job is visible.
+            await hintChannel.listen((name) => {
+                if (!hintsAfterCommit) {
+                    onEnqueued([name]);
+                } else if (state === 'started' && handlesAny([name])) {
+                    wakeUp();
+                }
+            });
         } catch (error) {
             reportError('hint_listen', error);
         }
@@ -916,7 +1031,7 @@ export function createRunner({
         const deadline = startedAt + deadlineMs;
         const allDone = Promise.allSettled([...running.values()].map(job => job.done));
 
-        await Promise.race([allDone, sleep(Math.max(deadline - Date.now(), 0))]);
+        await waitAtMost(allDone, deadline - Date.now());
 
         const unfinished = [...running.values()].filter(job => !job.settled);
 
@@ -944,10 +1059,10 @@ export function createRunner({
         }
 
         // The writes of the finished handlers, until the deadline
-        await Promise.race([
+        await waitAtMost(
             Promise.allSettled([...running.values()].filter(job => job.settled).map(job => job.done)),
-            sleep(Math.max(deadline - Date.now(), 0)),
-        ]);
+            deadline - Date.now(),
+        );
 
         for (const timer of timers) {
             clearTimeout(timer);

package/src/store/mysql_final.js

@@ -95,28 +95,42 @@ async function lingerHolds(executor, p, job, lingerMs) {
 }
 
 /**
- * The job is done: completed until its retention ends, without its payload; its keys are freed.
+ * 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 {OwnedJob} job
- * @returns {Promise<boolean>} False: no change (the lease was lost, or an earlier try committed).
+ * @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 async function completeJob(executor, p, job) {
+export async function completeJobs(executor, p, jobs) {
+    const ids = jobs.map(job => job.id);
+    // `id IN`: the range on the primary key; the pairs check the lock tokens
     const changed = await executor.run(`
         UPDATE ${p}jobs
            SET status = 'completed', finished_at = ${NOW},
                expires_at = ${NOW} + INTERVAL completed_retention_ms * 1000 MICROSECOND, ${CLEAR_LOCK},
                updated_at = ${NOW}
-         WHERE id = ? AND lock_token = ?
-    `, [job.id, job.lockToken]);
+         WHERE id IN (${placeholders(ids.length)}) AND (id, lock_token) IN (${jobs.map(() => '(?, ?)').join(', ')})
+    `, [...ids, ...jobs.flatMap(job => [job.id, job.lockToken])]);
 
     if (changed) {
-        await executor.run(`DELETE FROM ${p}payloads WHERE id = ?`, [job.id]);
+        await executor.run(`
+            DELETE pl FROM ${p}payloads pl JOIN ${p}jobs j ON j.id = pl.id
+             WHERE pl.id IN (${placeholders(ids.length)}) AND j.status = 'completed'
+        `, ids);
     }
 
-    await deleteHolds(executor, p, job);
+    const keyed = jobs.filter(job => job.mutexKeys.length);
 
-    return changed > 0;
+    if (keyed.length) {
+        await executor.run(`
+            DELETE FROM ${p}mutexes
+             WHERE job_id IN (${placeholders(keyed.length)}) AND (job_id, lock_token) IN (${keyed.map(() => '(?, ?)').join(', ')})
+        `, [...keyed.map(job => job.id), ...keyed.flatMap(job => [job.id, job.lockToken])]);
+    }
+
+    return changed;
 }
 
 /**

package/src/store/postgres_final.js

@@ -92,27 +92,37 @@ async function lingerHolds(executor, p, job, lingerMs) {
 }
 
 /**
- * The job is done: completed until its retention ends, without its payload; its keys are freed.
+ * The jobs are done: completed until their retention ends, without their payloads; their keys are freed. One
+ * statement for many jobs.
  * @param {Executor} executor
  * @param {string} p
- * @param {OwnedJob} job
- * @returns {Promise<boolean>} False: no change (the lease was lost, or an earlier try committed).
+ * @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 async function completeJob(executor, p, job) {
-    const changed = await executor.run(`
-        UPDATE ${p}jobs
-           SET status = 'completed', finished_at = ${NOW}, expires_at = ${NOW} + completed_retention_ms * ${MS},
-               ${CLEAR_LOCK}, updated_at = ${NOW}
-         WHERE id = $1 AND lock_token = $2
-    `, [job.id, job.lockToken]);
-
-    if (changed) {
-        await executor.run(`DELETE FROM ${p}payloads WHERE id = $1`, [job.id]);
-    }
-
-    await deleteHolds(executor, p, job);
+export async function completeJobs(executor, p, jobs) {
+    const [row] = await executor.query(`
+        WITH owned AS (
+            SELECT * FROM unnest($1::text[], $2::text[]) AS o(id, lock_token)
+        ),
+        done AS (
+            UPDATE ${p}jobs j
+               SET status = 'completed', finished_at = ${NOW}, expires_at = ${NOW} + completed_retention_ms * ${MS},
+                   ${CLEAR_LOCK}, updated_at = ${NOW}
+              FROM owned
+             WHERE j.id = owned.id AND j.lock_token = owned.lock_token
+            RETURNING j.id
+        ),
+        payloads AS (
+            DELETE FROM ${p}payloads WHERE id IN (SELECT id FROM done)
+        ),
+        holds AS (
+            DELETE FROM ${p}mutexes m USING owned WHERE m.job_id = owned.id AND m.lock_token = owned.lock_token
+        )
+        SELECT count(*)::integer AS changed FROM done
+    `, [jobs.map(job => job.id), jobs.map(job => job.lockToken)]);
 
-    return changed > 0;
+    return Number(row?.changed ?? 0);
 }
 
 /**

package/src/store/store.js

@@ -50,6 +50,11 @@ import * as postgresWorker from './postgres_worker.js';
  * @property {string} lockToken
  */
 
+/**
+ * A job that this process ran, with its keys.
+ * @typedef {OwnedJob & { mutexKeys: readonly string[] }} FinishedJob
+ */
+
 /**
  * The job that fails for good, as the failure job gets it.
  * @typedef {object} FailedJob
@@ -77,7 +82,7 @@ import * as postgresWorker from './postgres_worker.js';
  * @property {(ids: string[]) => Promise<Map<string, unknown>>} readPayloads
  * @property {(jobs: OwnedJob[], leaseMs: number) => Promise<Set<string>>} renewLeases
  * @property {(job: OwnedJob) => Promise<boolean>} markTimedOut
- * @property {(job: OwnedJob) => Promise<boolean>} completeJob
+ * @property {(jobs: FinishedJob[]) => Promise<number>} completeJobs In one transaction: the jobs that it completed.
  * @property {(job: OwnedJob, params: { delayMs: number, error: import('../error_json.js').ErrorJson })
  *     => Promise<boolean>} retryJob
  * @property {(
@@ -122,7 +127,7 @@ export function createStore(adapter, tablePrefix) {
         readPayloads: ids => sql.readPayloads(adapter.queue, tablePrefix, ids),
         renewLeases: (jobs, leaseMs) => inQueue(executor => final.renewLeases(executor, p, jobs, leaseMs)),
         markTimedOut: job => final.markTimedOut(adapter.queue, p, job),
-        completeJob: job => inQueue(executor => final.completeJob(executor, p, job)),
+        completeJobs: jobs => inQueue(executor => final.completeJobs(executor, p, jobs)),
         retryJob: (job, params) => inQueue(executor => final.retryJob(executor, p, job, params)),
         failJob: (job, params) => inQueue(executor => final.failJob(executor, p, job, params)),
         releaseJob: (job, params) => inQueue(executor => final.releaseJob(executor, p, job, params)),

package/types/adapters/mysql2.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @typedef {import('mysql2/promise').Pool
+ *     | import('mysql2/promise').PoolConnection
+ *     | import('mysql2/promise').Connection} Mysql2Connection
+ */
+export type Mysql2Connection = import('mysql2/promise').Pool | import('mysql2/promise').PoolConnection | import('mysql2/promise').Connection;
+/**
+ * The adapter for mysql2 (its promise API). `enqueue` then takes a `Connection`, a `PoolConnection` (in a
+ * transaction) or a `Pool`.
+ * @param {import('mysql2/promise').Pool} pool The queue's own pool: claims, leases, results.
+ * @returns {import('../types.js').Adapter<Mysql2Connection>}
+ */
+export declare function mysql2Adapter(pool: import('mysql2/promise').Pool): import('../types.js').Adapter<Mysql2Connection>;

package/types/adapters/pg.d.ts

@@ -0,0 +1,16 @@
+/** @typedef {import('pg').Pool | import('pg').PoolClient | import('pg').Client} PgConnection */
+export type PgConnection = import('pg').Pool | import('pg').PoolClient | import('pg').Client;
+export type PgAdapterOptions = {
+    /**
+     * Hints by LISTEN/NOTIFY: `pg_notify` in the enqueue transaction, delivered on commit.
+     * Default: false.
+     */
+    notify?: boolean;
+};
+/**
+ * The adapter for pg. `enqueue` then takes a `Client`, a `PoolClient` (in a transaction) or a `Pool`.
+ * @param {import('pg').Pool} pool The queue's own pool: claims, leases, results.
+ * @param {PgAdapterOptions} [options]
+ * @returns {import('../types.js').Adapter<PgConnection>}
+ */
+export declare function pgAdapter(pool: import('pg').Pool, options?: PgAdapterOptions): import('../types.js').Adapter<PgConnection>;

package/types/backoff.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The delay before the next attempt.
+ * @param {import('./types.js').Backoff} backoff Checked.
+ * @param {number} attempt The attempt that failed: 1 for the first.
+ * @param {() => number} [random] For tests. Default: `Math.random`.
+ * @returns {number} Milliseconds.
+ */
+export declare function getBackoffMs(backoff: import('./types.js').Backoff, attempt: number, random?: () => number): number;

package/types/create_sqlane.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Creates a sqlane instance. It connects, migrates and starts nothing.
+ * @template C The connections that `enqueue` accepts, from the adapter.
+ * @template {string} [L=never] The lane names, from `lanes`.
+ * @param {import('./types.js').SqlaneOptions<C, L>} options
+ * @returns {import('./types.js').Sqlane<C, L>}
+ */
+export declare function createSqlane<C, L extends string = never>(options: import('./types.js').SqlaneOptions<C, L>): import('./types.js').Sqlane<C, L>;

package/types/defaults.d.ts

@@ -0,0 +1,18 @@
+export type ResolvedDefaults = {
+    maxAttempts: number;
+    maxStalls: number;
+    backoff: import('./types.js').Backoff;
+    retention: {
+        completedMs: number;
+        failedMs: number;
+    };
+    /**
+     * Null: no timeout.
+     */
+    timeoutMs: number | null;
+};
+/**
+ * @param {import('./types.js').JobDefaults} [defaults]
+ * @returns {ResolvedDefaults}
+ */
+export declare function resolveDefaults(defaults?: import('./types.js').JobDefaults): ResolvedDefaults;

package/types/define_job.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Defines a job name and its options. Producers and workers import the definition.
+ * @param {import('./types.js').JobOptions} options
+ * @returns {import('./types.js').JobDefinition} Frozen.
+ */
+export declare function defineJob(options: import('./types.js').JobOptions): import('./types.js').JobDefinition;

package/types/duration.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parses a duration: milliseconds (a non-negative safe integer), or a string that parse-duration reads, such as
+ * `'500ms'`, `'5s'`, `'1.5h'`, `'4m30s'`, `'2 days'`.
+ * @param {unknown} value
+ * @returns {number | null} The milliseconds, rounded. Null: not a duration, or negative.
+ */
+export declare function parseDuration(value: unknown): number | null;

package/types/enqueue.d.ts

@@ -0,0 +1,50 @@
+export type EnqueuerOptions<C> = {
+    adapter: import('./types.js').Adapter<C>;
+    /**
+     * Checked.
+     */
+    tablePrefix: string;
+    /**
+     * The known definition of
+     * a name.
+     */
+    findDefinition: (name: string) => import('./types.js').JobDefinition | null;
+    unknownJobs: 'allow' | 'reject';
+    defaults: import('./defaults.js').ResolvedDefaults;
+    maxPayloadBytes: number;
+    /**
+     * PostgreSQL NOTIFY: `pg_notify` in the enqueue transaction, delivered on
+     * commit. Null: no NOTIFY.
+     */
+    notifyChannel: string | null;
+};
+export type Enqueuer<C> = {
+    enqueue: import('./types.js').Sqlane<C, never>['enqueue'];
+    enqueueMany: import('./types.js').Sqlane<C, never>['enqueueMany'];
+};
+/**
+ * @template C
+ * @typedef {object} EnqueuerOptions
+ * @property {import('./types.js').Adapter<C>} adapter
+ * @property {string} tablePrefix Checked.
+ * @property {(name: string) => import('./types.js').JobDefinition | null} findDefinition The known definition of
+ *     a name.
+ * @property {'allow' | 'reject'} unknownJobs
+ * @property {import('./defaults.js').ResolvedDefaults} defaults
+ * @property {number} maxPayloadBytes
+ * @property {string | null} notifyChannel PostgreSQL NOTIFY: `pg_notify` in the enqueue transaction, delivered on
+ *     commit. Null: no NOTIFY.
+ */
+/**
+ * @template C
+ * @typedef {object} Enqueuer
+ * @property {import('./types.js').Sqlane<C, never>['enqueue']} enqueue
+ * @property {import('./types.js').Sqlane<C, never>['enqueueMany']} enqueueMany
+ */
+/**
+ * The enqueue side of an instance.
+ * @template C
+ * @param {EnqueuerOptions<C>} options
+ * @returns {Enqueuer<C>}
+ */
+export declare function createEnqueuer<C>({ adapter, tablePrefix, findDefinition, unknownJobs, defaults, maxPayloadBytes, notifyChannel, }: EnqueuerOptions<C>): Enqueuer<C>;

package/types/error_json.d.ts

@@ -0,0 +1,21 @@
+/** The longest stack kept with a job error: the error row and the failure job stay small. */
+export declare const MAX_STACK_LENGTH: number;
+export type ErrorJson = {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+};
+/**
+ * @typedef {object} ErrorJson
+ * @property {string} name
+ * @property {string} message
+ * @property {string} [stack]
+ * @property {string} [code]
+ */
+/**
+ * The JSON of an error, for `last_error` and the failure job. A thrown non-Error becomes its string.
+ * @param {unknown} error
+ * @returns {ErrorJson}
+ */
+export declare function toErrorJson(error: unknown): ErrorJson;