@sqlane/core 0.0.0 → 0.0.2

package/README.md

@@ -24,16 +24,18 @@ pnpm install
 hk install --global --mise   # Git hooks, also for GUI Git clients: lint, format, type check, secrets, typos, Conventional Commits
 ```
 
-| Command          | Does                                                       |
-| ---------------- | ---------------------------------------------------------- |
-| `pnpm test`      | Run the tests (Vitest)                                     |
-| `pnpm lint`      | Lint, including formatting (oxlint, @stylistic)            |
-| `pnpm lint:fix`  | Fix lint and formatting                                    |
-| `pnpm format`    | Format the other files: JSON, YAML, Markdown, TOML (oxfmt) |
-| `pnpm typecheck` | Type-check the JSDoc (`tsc`, no emit)                      |
-| `pnpm check`     | Run all hook checks on all files (`hk check --all`)        |
-
-Commit messages follow [Conventional Commits](https://www.conventionalcommits.org).
+| Command             | Does                                                       |
+| ------------------- | ---------------------------------------------------------- |
+| `pnpm test`         | Run the tests (Vitest)                                     |
+| `pnpm lint`         | Lint, including formatting (oxlint, @stylistic)            |
+| `pnpm lint:fix`     | Fix lint and formatting                                    |
+| `pnpm format`       | Format the other files: JSON, YAML, Markdown, TOML (oxfmt) |
+| `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`)        |
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org). A change of the package adds a
+changeset (`pnpm changeset`); see [releasing](docs/releasing.md).
 
 ## License
 

package/package.json

@@ -1,58 +1,85 @@
 {
-    "name": "@sqlane/core",
-    "version": "0.0.0",
-    "description": "Transactional SQL job queue for Node.js (MySQL, PostgreSQL)",
-    "keywords": [
-        "background-jobs",
-        "job",
-        "mysql",
-        "outbox",
-        "postgres",
-        "postgresql",
-        "queue",
-        "transactional"
-    ],
-    "homepage": "https://github.com/sqlane/sqlane-node#readme",
-    "bugs": "https://github.com/sqlane/sqlane-node/issues",
-    "license": "MIT",
-    "author": "Klim Pal",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/sqlane/sqlane-node.git"
+  "name": "@sqlane/core",
+  "version": "0.0.2",
+  "description": "Transactional SQL job queue for Node.js (MySQL, PostgreSQL)",
+  "keywords": [
+    "background-jobs",
+    "job",
+    "mysql",
+    "outbox",
+    "postgres",
+    "postgresql",
+    "queue",
+    "transactional"
+  ],
+  "homepage": "https://github.com/sqlane/sqlane-node#readme",
+  "bugs": "https://github.com/sqlane/sqlane-node/issues",
+  "license": "MIT",
+  "author": "Klim Pal",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sqlane/sqlane-node.git"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.js"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./mysql2": "./src/adapters/mysql2.js",
+    "./pg": "./src/adapters/pg.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "1.0.1",
+    "@changesets/cli": "3.0.3",
+    "@stylistic/eslint-plugin": "5.10.0",
+    "@testcontainers/mysql": "12.2.1",
+    "@testcontainers/postgresql": "12.2.1",
+    "@types/node": "22.20.5",
+    "@types/pg": "8.23.1",
+    "@vitest/coverage-v8": "5.0.5",
+    "mysql2": "3.24.6",
+    "oxfmt": "0.75.0",
+    "oxlint": "1.90.0",
+    "pg": "8.23.1",
+    "publint": "0.3.25",
+    "testcontainers": "12.2.1",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "mysql2": "^3.11.0",
+    "pg": "^8.13.0"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
     },
-    "files": [
-        "src",
-        "!src/**/*.test.js"
-    ],
-    "type": "module",
-    "exports": {
-        ".": "./src/index.js"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "scripts": {
-        "lint": "oxlint --deny-warnings",
-        "lint:fix": "oxlint --fix",
-        "format": "oxfmt",
-        "format:check": "oxfmt --check",
-        "typecheck": "tsc -p tsconfig.json",
-        "test": "vitest run",
-        "test:watch": "vitest",
-        "test:coverage": "vitest run --coverage",
-        "check": "hk check --all"
-    },
-    "devDependencies": {
-        "@stylistic/eslint-plugin": "^5.10.0",
-        "@types/node": "^22.20.5",
-        "@vitest/coverage-v8": "^5.0.5",
-        "oxfmt": "^0.75.0",
-        "oxlint": "^1.90.0",
-        "typescript": "^7.0.2",
-        "vitest": "^5.0.5"
-    },
-    "engines": {
-        "node": ">=22.12.0"
-    },
-    "packageManager": "pnpm@12.16.1"
-}
+    "pg": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "lint": "oxlint --deny-warnings",
+    "lint:fix": "oxlint --fix",
+    "lint:package": "publint --strict",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "typecheck": "tsc -p tsconfig.json",
+    "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",
+    "changeset": "changeset",
+    "changeset:version": "changeset version && oxfmt --no-error-on-unmatched-pattern CHANGELOG.md"
+  }
+}

package/src/adapters/mysql2.js

@@ -0,0 +1,35 @@
+/**
+ * @typedef {import('mysql2/promise').Pool
+ *     | import('mysql2/promise').PoolConnection
+ *     | import('mysql2/promise').Connection} Mysql2Connection
+ */
+
+/**
+ * @param {Mysql2Connection} connection
+ * @returns {import('../types.js').Executor}
+ */
+function toExecutor(connection) {
+    return {
+        query: async (sql, params) => {
+            // The three types have the same query(); TS cannot call a method of a union of overloads.
+            const queryable = /** @type {import('mysql2/promise').Connection} */ (connection);
+            const [rows] = await queryable.query(sql, [...params]);
+
+            return Array.isArray(rows) ? /** @type {Record<string, unknown>[]} */ (rows) : [];
+        },
+    };
+}
+
+/**
+ * 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 function mysql2Adapter(pool) {
+    return {
+        dialect: 'mysql',
+        wrap: toExecutor,
+        queue: toExecutor(pool),
+    };
+}

package/src/adapters/pg.js

@@ -0,0 +1,36 @@
+/** @typedef {import('pg').Pool | import('pg').PoolClient | import('pg').Client} PgConnection */
+
+/**
+ * @typedef {object} PgAdapterOptions
+ * @property {boolean} [notify] Hints by LISTEN/NOTIFY: `pg_notify` in the enqueue transaction, delivered on commit.
+ *     Default: false.
+ */
+
+/**
+ * @param {PgConnection} connection
+ * @returns {import('../types.js').Executor}
+ */
+function toExecutor(connection) {
+    return {
+        query: async (sql, params) => {
+            const result = await connection.query(sql, [...params]);
+
+            return result.rows;
+        },
+    };
+}
+
+/**
+ * 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> & { notify: boolean }}
+ */
+export function pgAdapter(pool, options = {}) {
+    return {
+        dialect: 'postgres',
+        wrap: toExecutor,
+        queue: toExecutor(pool),
+        notify: options.notify ?? false,
+    };
+}

package/src/create_sqlane.js

@@ -0,0 +1,34 @@
+import { ConfigError } from './errors.js';
+
+/**
+ * @param {string} method
+ * @returns {never}
+ */
+function notImplemented(method) {
+    throw new Error(`sqlane: ${method}() is not implemented yet`);
+}
+
+/**
+ * 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 function createSqlane(options) {
+    if (!options?.adapter) {
+        throw new ConfigError('createSqlane: "adapter" is required');
+    }
+
+    return {
+        enqueue: () => notImplemented('enqueue'),
+        enqueueMany: () => notImplemented('enqueueMany'),
+        handle: () => notImplemented('handle'),
+        start: () => notImplemented('start'),
+        drain: () => notImplemented('drain'),
+        close: () => notImplemented('close'),
+        migrate: () => notImplemented('migrate'),
+        getStats: () => notImplemented('getStats'),
+        wake: () => notImplemented('wake'),
+    };
+}

package/src/define_job.js

@@ -0,0 +1,9 @@
+/**
+ * Defines a job name and its options. Producers and workers import the definition.
+ * @param {import('./types.js').JobOptions} options
+ * @returns {import('./types.js').JobDefinition}
+ */
+export function defineJob(options) {
+    // The validation of the options comes with the implementation.
+    return Object.freeze({ ...options });
+}

package/src/errors.js

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

package/src/index.js

@@ -1,2 +1,63 @@
-/* oxlint-disable unicorn/no-empty-file -- placeholder until the first module */
-// Public API of sqlane.
+// The public API of sqlane. See docs/design.md.
+
+export { createSqlane } from './create_sqlane.js';
+export { defineJob } from './define_job.js';
+export {
+    ClosedError,
+    ConfigError,
+    DrainTimeoutError,
+    FatalJobError,
+    InvalidMutexKeyError,
+    InvalidOptionsError,
+    JobTimeoutError,
+    LeaseLostError,
+    MissingPayloadError,
+    PayloadTooLargeError,
+    RetryJobError,
+    ShutdownError,
+    SqlaneError,
+    UnknownJobError,
+} from './errors.js';
+export { getMigrations } from './migrations.js';
+
+/**
+ * @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/src/migrations.js

@@ -0,0 +1,10 @@
+/**
+ * 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 function getMigrations(options) {
+    throw new Error(`sqlane: getMigrations(${options.dialect}) is not implemented yet`);
+}

package/src/types.js

@@ -0,0 +1,288 @@
+// The public types of sqlane. See docs/design.md.
+
+/**
+ * A duration: a string (`'500ms'`, `'5s'`, `'10m'`, `'1h'`, `'30d'`) or milliseconds.
+ * @typedef {string | number} Duration
+ */
+
+/**
+ * The JSON form of T: T itself if it is JSON, else a type that T does not match. Optional fields and interfaces pass;
+ * a `Date`, a `Map`, a `Set`, a function, a `bigint` or a class instance with methods does not.
+ * @template T
+ * @typedef {T extends string | number | boolean | null ? T
+ *     : T extends undefined | bigint | symbol | Function | Date | RegExp | Map<any, any> | Set<any> ? never
+ *     : T extends readonly (infer U)[] ? readonly Jsonable<U>[]
+ *     : T extends object ? { [K in keyof T]: Jsonable<T[K]> }
+ *     : never} Jsonable
+ */
+
+/**
+ * @typedef {object} ExponentialBackoff
+ * @property {'exponential'} type `delay × 2^(attempt − 1)`, at most `maxDelay`.
+ * @property {Duration} delay
+ * @property {Duration} [maxDelay]
+ * @property {number} [jitter] 0–1: the delay is `delay × (1 − jitter × random())`. Default: 0.2.
+ */
+
+/**
+ * @typedef {object} FixedBackoff
+ * @property {'fixed'} type
+ * @property {Duration} delay
+ * @property {number} [jitter] 0–1. Default: 0.2.
+ */
+
+/** @typedef {ExponentialBackoff | FixedBackoff} Backoff */
+
+/**
+ * How long a finished job is kept. It is also the dedupe window of its `jobId`.
+ * @typedef {object} Retention
+ * @property {Duration} [completed] Default: `'1h'`.
+ * @property {Duration} [failed] Default: `'30d'`.
+ */
+
+/**
+ * The options of a job name, shared by its producers and workers. A definition overrides the instance `defaults`.
+ * @typedef {object} JobOptions
+ * @property {string} name Matches `^[a-z][a-z0-9_.-]{0,127}$`.
+ * @property {number} [maxAttempts] Default: 3.
+ * @property {number} [maxStalls] Default: 2.
+ * @property {Backoff} [backoff]
+ * @property {Retention} [retention]
+ * @property {Duration} [timeout] No default. A job with mutex keys needs one.
+ * @property {(payload: any) => readonly string[]} [mutexKeys] Sync, from the payload only.
+ * @property {string | JobDefinition} [failureJob] Added when a job fails for good.
+ */
+
+/**
+ * The result of `defineJob()`. Frozen.
+ * @typedef {Readonly<JobOptions>} JobDefinition
+ */
+
+/**
+ * @typedef {object} EnqueueBaseOptions
+ * @property {string} [jobId] 1–120 printable ASCII characters. Dedupe: a job with this id is added once while its row
+ *     exists.
+ * @property {number} [maxAttempts]
+ * @property {number} [maxStalls]
+ * @property {Retention} [retention]
+ * @property {string | JobDefinition} [failureJob]
+ * @property {readonly string[]} [mutexKeys] Replace the keys of the definition; `[]` clears them.
+ */
+
+/**
+ * The options of an enqueue: `delay` or `runAt`, not both.
+ * @typedef {EnqueueBaseOptions & ({ delay?: Duration, runAt?: never } | { runAt: Date, delay?: never })}
+ *     EnqueueOptions
+ */
+
+/**
+ * @typedef {object} EnqueueResult
+ * @property {string} id `<job_name>:<jobId>`, or a new ULID without a `jobId`.
+ * @property {boolean} created False: a job with this `jobId` exists already, nothing was added.
+ */
+
+/**
+ * @template P
+ * @typedef {object} EnqueueItem
+ * @property {P} payload
+ * @property {EnqueueOptions} [options]
+ */
+
+/**
+ * @typedef {object} JobInfo
+ * @property {string} id
+ * @property {string} name
+ * @property {number} attempt 1 for the first run.
+ * @property {number} maxAttempts
+ * @property {Date} enqueuedAt
+ * @property {readonly string[]} mutexKeys
+ */
+
+/**
+ * @typedef {object} HandlerContext
+ * @property {any} payload As JSON gives it back.
+ * @property {JobInfo} job
+ * @property {AbortSignal} signal Aborted with a `JobTimeoutError`, a `LeaseLostError` or a `ShutdownError`.
+ */
+
+/**
+ * Runs a job. Its return value is ignored.
+ * @typedef {(context: HandlerContext) => unknown} Handler
+ */
+
+/**
+ * A private lane (`concurrency`) or a shared lane of `lanes` (`lane`), not both.
+ * @template {string} L
+ * @typedef {{ timeout?: Duration } & (
+ *     { concurrency?: number, lane?: never } | { lane: L, concurrency?: never }
+ * )} HandleOptions
+ */
+
+/**
+ * @typedef {object} LaneOptions
+ * @property {number} concurrency The handlers of the lane that run at the same time in one process.
+ */
+
+/**
+ * The instance defaults; a definition overrides them.
+ * @typedef {object} JobDefaults
+ * @property {number} [maxAttempts]
+ * @property {number} [maxStalls]
+ * @property {Backoff} [backoff]
+ * @property {Retention} [retention]
+ * @property {Duration} [timeout]
+ */
+
+/**
+ * A pub/sub that wakes the other processes. Only an optimization: a lost message delays a job until the next poll.
+ * @typedef {object} Hint
+ * @property {(channel: string, message: string) => Promise<void>} publish
+ * @property {(channel: string, onMessage: (message: string) => void) => Promise<() => Promise<void>>} subscribe
+ *     Resolves to the unsubscribe function.
+ */
+
+/**
+ * @typedef {(object: object, message?: string) => void} LogFn
+ */
+
+/**
+ * A pino-compatible logger.
+ * @typedef {object} Logger
+ * @property {LogFn} debug
+ * @property {LogFn} info
+ * @property {LogFn} warn
+ * @property {LogFn} error
+ */
+
+/**
+ * @typedef {object} JobEventBase
+ * @property {string} jobId
+ * @property {string} jobName
+ * @property {number} attempt
+ */
+
+/**
+ * An event of the job lifecycle, by `type`.
+ * @typedef {(JobEventBase & (
+ *     | { type: 'claimed' }
+ *     | { type: 'completed', durationMs: number }
+ *     | { type: 'retried', durationMs: number, delayMs: number, error: unknown }
+ *     | { type: 'failed', durationMs: number, error: unknown }
+ *     | { type: 'timed_out', durationMs: number }
+ *     | { type: 'stalled' }
+ *     | { type: 'released' }
+ *     | { type: 'lease_lost' }
+ *     | { type: 'failure_job_not_added', failureJob: string, error: unknown }
+ * )) | { type: 'error', operation: string, error: unknown }} SqlaneEvent
+ */
+
+/**
+ * The connections that `enqueue` accepts (C), and the queue's own pool. Made by `mysql2Adapter()` or `pgAdapter()`.
+ * @template C
+ * @typedef {object} Adapter
+ * @property {'mysql' | 'postgres'} dialect
+ * @property {(connection: C) => Executor} wrap Used by sqlane: wraps a connection given to `enqueue`.
+ * @property {Executor} queue Used by sqlane: the queue's own pool.
+ */
+
+/**
+ * Runs SQL. Used by sqlane, through an adapter.
+ * @typedef {object} Executor
+ * @property {(sql: string, params: readonly unknown[]) => Promise<readonly Record<string, unknown>[]>} query
+ */
+
+/**
+ * @template C
+ * @template {string} L
+ * @typedef {object} SqlaneOptions
+ * @property {Adapter<C>} adapter
+ * @property {readonly JobDefinition[]} [jobs] The definitions known by name.
+ * @property {number} [concurrency] The handlers that run at the same time in this process. Default: 10.
+ * @property {Record<L, LaneOptions>} [lanes] Limits shared by several job names.
+ * @property {JobDefaults} [defaults]
+ * @property {'allow' | 'reject'} [unknownJobs] Default: `'allow'`. `'reject'`: `enqueue` of a name that is not in
+ *     `jobs` and not handled throws an `UnknownJobError`.
+ * @property {Hint | null} [hint] Default: null: polling only.
+ * @property {Logger} [logger] Default: no logs.
+ * @property {(event: SqlaneEvent) => void} [onEvent]
+ * @property {string} [tablePrefix] Default: `'sqlane_'`.
+ * @property {Duration} [pollInterval] Default: `'5s'`.
+ * @property {number} [maxPayloadBytes] Default: 256 KiB.
+ * @property {boolean} [cleanup] Built-in deletion of the expired jobs. Default: true.
+ */
+
+/**
+ * @typedef {object} DrainOptions
+ * @property {Duration} [timeout] Default: `'10s'`.
+ * @property {boolean} [includeDelayed] Also runs the delayed jobs and the retries in backoff at once.
+ */
+
+/**
+ * @typedef {object} DrainResult
+ * @property {number} completed
+ * @property {number} retried Failed attempts that were retried.
+ * @property {number} failed Jobs that failed for good.
+ */
+
+/**
+ * @typedef {object} CloseOptions
+ * @property {Duration} [deadline] From the call. Default: `'30s'`.
+ * @property {'release' | 'abandon'} [mode] Default: `'release'`.
+ * @property {Duration} [exitsBy] From the call: the latest time the process exits. Default: the deadline plus one
+ *     lease.
+ */
+
+/**
+ * @typedef {object} MigrateOptions
+ * @property {Duration} [lockTimeout] Default: `'10m'`.
+ */
+
+/**
+ * @typedef {object} JobStats
+ * @property {string} name
+ * @property {number} pending
+ * @property {number} due
+ * @property {number} running
+ * @property {number} stuck Timed out, the handler has not settled.
+ * @property {number} failed
+ * @property {number | null} oldestDueAgeMs
+ */
+
+/**
+ * The payload of a failure job.
+ * @typedef {object} FailedJobPayload
+ * @property {{ id: string, name: string, payload: any, attempt: number, maxAttempts: number }} job
+ * @property {{ name: string, message: string, stack?: string }} error
+ */
+
+/**
+ * @template C The connections that `enqueue` accepts.
+ * @template {string} L The lane names.
+ * @typedef {object} Sqlane
+ * @property {<P>(
+ *     connection: C, job: JobDefinition | string, payload: P & NoInfer<Jsonable<P>>, options?: EnqueueOptions,
+ * ) => Promise<EnqueueResult>} enqueue Adds a job with the caller's connection: it must be in a transaction (or a
+ *     pool: then sqlane opens its own transaction).
+ * @property {<P>(
+ *     connection: C,
+ *     job: JobDefinition | string,
+ *     items: readonly (EnqueueItem<P> & NoInfer<EnqueueItem<Jsonable<P>>>)[],
+ * ) => Promise<EnqueueResult[]>} enqueueMany The results are in the order of the items.
+ * @property {(job: JobDefinition | string, handler: Handler, options?: HandleOptions<L>) => void} handle
+ * @property {() => Promise<void>} start
+ * @property {(options?: DrainOptions) => Promise<DrainResult>} drain For tests: runs the due jobs of the handled
+ *     names until none is left, without `start()`.
+ * @property {(options?: CloseOptions) => Promise<void>} close
+ * @property {(options?: MigrateOptions) => Promise<void>} migrate
+ * @property {() => Promise<JobStats[]>} getStats
+ * @property {(jobName: string) => void} wake Low level: probes this name now.
+ */
+
+/**
+ * @typedef {object} Migration
+ * @property {string} id
+ * @property {readonly string[]} statements
+ */
+
+// oxlint-disable-next-line unicorn/require-module-specifiers -- makes the file a module: its typedefs are exported
+export {};