mail-time 4.0.0 → 4.1.0

package/README.md

@@ -1,11 +1,19 @@
 
 # MailTime
 
-[![npm version](https://img.shields.io/npm/v/mail-time.svg?label=mail-time)](https://www.npmjs.com/package/mail-time)
-[![CI](https://img.shields.io/github/actions/workflow/status/veliovgroup/mail-time/ci.yml?branch=master)](https://github.com/veliovgroup/mail-time/actions)
-[![license](https://img.shields.io/npm/l/mail-time.svg)](LICENSE)
-[![GitHub Sponsors](https://img.shields.io/github/sponsors/dr-dimitru?label=Sponsor)](https://github.com/sponsors/dr-dimitru)
-[![Donate](https://img.shields.io/badge/Donate-PayPal-00457C?logo=paypal&logoColor=white)](https://paypal.me/veliovgroup)
+[![npm version][badge-npm-v]][npm-url]
+[![npm downloads][badge-npm-dm]][npm-url]
+[![CI][badge-ci]][ci-url]
+[![bundle size][badge-size]][size-url]
+[![Coverage][badge-cov]](#testing)
+[![License: BSD-3-Clause][badge-license]][license-url]
+[![Node.js][badge-node]][node-url]
+[![TypeScript][badge-ts]][ts-url]
+[![Bun][badge-bun]][bun-url]
+[![Meteor][badge-meteor]][meteor-url]
+[![dependencies][badge-deps]][deps-url]
+[![Sponsor][badge-sponsor]][sponsor-url]
+[![Donate][badge-donate]][donate-url]
 
 Bulletproof email queue for [horizontally scaled](#sending-emails-from-a-cluster) Node.js & Bun apps. Built on top of [`nodemailer`](https://github.com/nodemailer/nodemailer) and [`josk`](https://github.com/veliovgroup/josk). Single runtime dependency, ESM + CJS, full TypeScript declarations.
 
@@ -28,7 +36,7 @@ Many clients + one or more servers coexist behind the same `prefix` in the same
 - 📦 **Bun ≥ 1.1.0 & Node ≥ 20.9.0** — same code, both runtimes.
 - 🤖 **Ships with AI agent skills** — see [AI agent skills](#ai-agent-skills) below.
 - 📐 **Hand-tuned ESM + CJS + TypeScript declarations**.
-- 🧪 **95%+ Jest coverage** (85% threshold enforced) + Mocha integration tests for every adapter.
+- 🧪 **99%+ Jest line coverage** (85% threshold enforced) + Mocha integration tests for every adapter.
 
 ## How it works
 
@@ -131,7 +139,7 @@ bun add mail-time nodemailer
 > `nodemailer` and adapter drivers are peers (not bundled) so you can pin your own versions.
 
 > [!IMPORTANT]
-> Upgrading from v3? See [Migration from 3.x](#migration-from-3x) and the full [v4.0.0 release notes](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v3-v4.md).
+> Upgrading? See the [Migrations](#migrations) table below for links to the detailed guides.
 
 For Meteor.js usage see [docs/meteor.md](https://github.com/veliovgroup/mail-time/blob/master/docs/meteor.md).
 
@@ -140,16 +148,22 @@ For Meteor.js usage see [docs/meteor.md](https://github.com/veliovgroup/mail-tim
 MailTime ships a Claude / Copilot / Cursor / Codex / Gemini-ready skill bundle. Install it once in your project (or globally) and your AI agent will reach for the right preset, adapter, and pitfall list without you having to paste docs into the chat.
 
 ```sh
-# Install the MailTime skill into the current project:
+# Install the MailTime skill globally:
+npx skills add veliovgroup/mail-time -g
+
+# Or install the MailTime skill into the current project:
 npx skills add veliovgroup/mail-time
 
 # Recommended: also install the JoSk skill — MailTime is built on JoSk,
 # and deep scheduler questions resolve through JoSk's contract.
-npx skills add veliovgroup/josk
+npx skills add veliovgroup/josk -g
 ```
 
 The `npx skills` CLI ([vercel-labs/skills](https://github.com/vercel-labs/skills)) supports 50+ AI coding agents. Pass `-g` to install user-wide, or `-a claude-code` to target a specific agent. The bundled MailTime skill covers the public API, every queue adapter, the preset table, tuning levers, and common pitfalls — it's the same material as the README and `docs/`, structured for an LLM.
 
+> [!NOTE]
+> The skill source is **not** shipped in the npm tarball — it's distributed via GitHub and consumed only by AI tooling.
+
 ## Quick start
 
 Three things every MailTime needs: a connected storage **client**, one or more **nodemailer transports** (server only), and a **`josk.adapter`** that points at the scheduler storage (server only). Past that, reach for a [preset](#settings-presets) instead of hand-tuning every knob.
@@ -261,6 +275,25 @@ Or explicitly: `mailQueue.destroy(); await mailQueue.drain();`
 
 `destroy()` is idempotent and stops the scheduler. Always call it from tests; pair with `drain()` when iterate-driven sends ran.
 
+#### Pause / resume a server (backpressure)
+
+`pause()` stops this **server** instance from competing for the queue-drain lease without tearing it down (unlike `destroy()`). In-flight SMTP sends finish; other `server` instances keep draining. `resume()` resumes and triggers an immediate scan.
+
+```js
+mailQueue.pause();              // stop draining on this pod
+// ...SMTP provider rate-limit clears / maintenance window ends...
+mailQueue.resume();             // resume; an immediate scan kicks off
+
+mailQueue.isPaused;             // boolean
+(await mailQueue.ping()).paused // boolean — observable in health checks
+
+// Stop draining AND wait for in-flight sends to settle:
+mailQueue.pause();
+await mailQueue.drain();
+```
+
+Both return `boolean` and are no-ops (returning `false`) on `client` instances or after `destroy()`. Use for SMTP rate-limit backpressure, rolling deploys, or quota windows.
+
 ## Storage layouts
 
 Queue storage and scheduler storage can be the same store or different ones. Use this matrix:
@@ -443,10 +476,12 @@ For deeper JoSk semantics, install the JoSk skill: **`npx skills add veliovgroup
 - `send(opts)` — alias of `sendMail`.
 - `cancelMail(uuidOrPromise)` → `Promise<boolean>`. Accepts the `uuid` or the `Promise<string>` from `sendMail`.
 - `cancel(uuid)` — alias of `cancelMail`.
-- `ping()` → `Promise<{status, code, statusCode, error?}>`. Pings scheduler then queue.
+- `ping()` → `Promise<{status, code, statusCode, paused?, error?}>`. Pings scheduler then queue; `paused` reflects `isPaused`.
 - `ready()` → `Promise<MailTime>`. Awaits all startup work; rejects with `.cause` on storage failure.
 - `destroy(opts?)` → `boolean` or `Promise<boolean>` when `{ drain: true }`. Stops scheduler. Idempotent. Use `destroy({ drain: true })` or `await drain()` after `destroy()` for graceful shutdown.
 - `drain()` → `Promise<void>`. Resolves once every in-flight SMTP attempt finishes. Useful in tests and graceful-shutdown paths.
+- `pause()` / `resume()` → `boolean`. Server-only reversible backpressure; no-ops on `client` or after `destroy()`. See [Pause / resume](#pause--resume-a-server-backpressure).
+- `isPaused` → `boolean`. Read-only; always `false` on `client`.
 
 ### Queue constructors
 
@@ -468,18 +503,16 @@ For custom adapters see [docs/queue-api.md](https://github.com/veliovgroup/mail-
 
 - `MailTime.Template` — get/set the default HTML envelope template.
 
-## Migration from 3.x
+## Migrations
 
-Full v4 highlights, adapter changes, and type exports live in [docs/migration-v3-v4.md](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v3-v4.md). Quick checklist:
+Upgrade checklists, adapter contract changes, and rollout notes live in the docs (no duplication here):
 
-1. **Node ≥ 20.9.0**, Bun ≥ 1.1.0. Bump your runtime first.
-2. **Swap adapter imports** to the new `MongoQueue` / `RedisQueue` / `PostgresQueue` constructors.
-3. **Pass `josk`** — it's now required for `type: 'server'`.
-4. **`josk.zombieTime` default raised to `60000` ms** (was `32786`). Set it explicitly if you relied on the old value.
-5. **Custom queue adapters** — `update`'s claim guard now triggers on `{ isSending: true, sendingAt, tries }` (was `{ isSent: true, tries }`) and must include the stale-lock-recovery clause `(isSending === false OR sendingAt <= now - sendingTimeout)`. The iterate path must call `await mailTimeInstance.___dispatch(row)` instead of `___send` and honor `opts.limit` / `opts.sendingTimeout`. See [docs/queue-api.md](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md) and [`adapters/blank-example.js`](https://github.com/veliovgroup/mail-time/blob/master/adapters/blank-example.js).
-6. **Default behavior unchanged** — `concurrency: 1` keeps the post-upgrade send rate identical to v3. Opt into parallel sends by raising `concurrency`.
+| From | To  | Full guide |
+|------|-----|------------|
+| 3.x  | 4.1 | [v3 → v4](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v3-v4.md) |
+| 4.0  | 4.1 | [v4.0 → v4.1](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4-v4.1.md) |
 
-New v4 surface to opt into: [`mailTimePreset`](#settings-presets), `concurrency`, `mode`, `sendingTimeout`, `drain()`, per-recipient retries, and the [AI agent skills](#ai-agent-skills) bundle.
+New in v4 (opt-in): `mailTimePreset`, `concurrency`/`mode`, `sendingTimeout`, `drain()`/`pause()`/`resume()`, per-recipient handling, AI skills bundle.
 
 ## Testing
 
@@ -524,3 +557,28 @@ Mixed clusters (some Node, some Bun) share one schedule under the same `prefix`
 - [PayPal](https://paypal.me/veliovgroup).
 - Try [☄️ meteor-files.com](https://meteor-files.com/?ref=github-mail-time-repo-footer).
 - Try [▲ ostr.io](https://ostr.io?ref=github-mail-time-repo-footer) for server monitoring, web analytics, web-CRON, and SEO pre-rendering.
+
+[npm-url]: https://www.npmjs.com/package/mail-time
+[badge-npm-v]: https://img.shields.io/npm/v/mail-time.svg
+[badge-npm-dm]: https://img.shields.io/npm/dm/mail-time.svg
+[badge-ci]: https://github.com/veliovgroup/mail-time/actions/workflows/ci.yml/badge.svg?branch=master
+[ci-url]: https://github.com/veliovgroup/mail-time/actions/workflows/ci.yml
+[badge-size]: https://img.shields.io/bundlephobia/minzip/mail-time
+[size-url]: https://bundlephobia.com/package/mail-time
+[badge-cov]: https://img.shields.io/badge/coverage-~99%25-brightgreen
+[badge-license]: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
+[license-url]: LICENSE
+[badge-node]: https://img.shields.io/node/v/mail-time
+[node-url]: https://nodejs.org/
+[badge-ts]: https://img.shields.io/badge/TypeScript-ready-blue
+[ts-url]: #quick-start
+[badge-bun]: https://img.shields.io/badge/Bun-%3E%3D1.1.0-black?logo=bun
+[bun-url]: #bun
+[badge-meteor]: https://img.shields.io/badge/Meteor-ostrio%3Amailer-DE4F4F
+[meteor-url]: https://packosphere.com/ostrio/mailer
+[badge-deps]: https://img.shields.io/badge/dependencies-1-brightgreen
+[deps-url]: https://www.npmjs.com/package/mail-time?activeTab=dependencies
+[badge-sponsor]: https://img.shields.io/github/sponsors/dr-dimitru?label=Sponsor
+[sponsor-url]: https://github.com/sponsors/dr-dimitru
+[badge-donate]: https://img.shields.io/badge/Donate-PayPal-00457C?logo=paypal&logoColor=white
+[donate-url]: https://paypal.me/veliovgroup

package/adapters/mongo.js

@@ -228,10 +228,13 @@ class MongoQueue {
         cursor.limit(limit);
       }
 
-      while (await cursor.hasNext()) {
-        await this.mailTimeInstance.___dispatch(await cursor.next());
+      try {
+        while (await cursor.hasNext()) {
+          await this.mailTimeInstance.___dispatch(await cursor.next());
+        }
+      } finally {
+        await cursor.close().catch(() => {});
       }
-      await cursor.close();
     } catch (iterateError) {
       logError('[iterate] [while/await] [iterateError]', iterateError);
     }

package/adapters/postgres.js

@@ -1,3 +1,4 @@
+import { createHash } from 'crypto';
 import {
   debug,
   logError,
@@ -26,7 +27,21 @@ import {
  */
 
 const DEFAULT_PREFIX = 'default';
-const setupLockId = 93824519;
+
+// Two-key advisory lock, mirroring josk's PostgresAdapter: a stable MailTime namespace
+// plus a per-prefix hash. `pg_advisory_lock(int4, int4)` lives in its own keyspace, isolated
+// from single-int callers in the same database; distinct prefixes get distinct lock IDs, so
+// co-tenant MailTime queues no longer serialize each other's schema setup.
+const ADVISORY_LOCK_NAMESPACE = 0x4D61696C; // 'Mail' in ASCII as int32
+
+/**
+ * @internal
+ * @param {string} prefix
+ * @returns {number} signed int32 hash of the prefix string
+ */
+const advisoryLockKeyFor = (prefix) => {
+  return createHash('sha256').update(prefix).digest().readInt32BE(0);
+};
 
 const fieldMap = {
   to: 'to_address',
@@ -129,7 +144,8 @@ class PostgresQueue {
 
   /** @internal */
   async __setup() {
-    await this.client.query('SELECT pg_advisory_lock($1)', [setupLockId]);
+    const advisoryLockKey = advisoryLockKeyFor(this.prefix);
+    await this.client.query('SELECT pg_advisory_lock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
 
     try {
       await this.client.query(`CREATE TABLE IF NOT EXISTS mail_time_queue (
@@ -160,7 +176,7 @@ class PostgresQueue {
       await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_pending_to
         ON mail_time_queue (prefix, to_address, is_sent, is_failed, is_cancelled, send_at)`);
     } finally {
-      await this.client.query('SELECT pg_advisory_unlock($1)', [setupLockId]);
+      await this.client.query('SELECT pg_advisory_unlock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
     }
   }
 

package/helpers.js

@@ -1,15 +1,43 @@
 const hasOwn = Object.prototype.hasOwnProperty;
 
+/**
+ * @name hasOwnProp - `Object.hasOwn` (ES2022) polyfill.
+ * @function
+ * @param {object} obj
+ * @param {PropertyKey} key
+ * @returns {boolean} `true` if the object has the property, `false` otherwise.
+ */
+const hasOwnProp = (obj, key) => hasOwn.call(obj, key);
+
+/**
+ * @name debug - Debug logging.
+ * @function
+ * @param {boolean} isDebug
+ * @param {...any} args
+ * @returns {void}
+ */
 const debug = (isDebug, ...args) => {
   if (isDebug) {
     console.info('[DEBUG] [mail-time]', `${new Date()}`, ...args);
   }
 };
 
+/**
+ * @name logError - Error logging.
+ * @function
+ * @param {...any} args
+ * @returns {void}
+ */
 const logError = (...args) => {
   console.error('[ERROR] [mail-time]', `${new Date()}`, ...args);
 };
 
+/**
+ * @name isPlainObject - Check whether a value is a plain object (literal or `Object.create(null)`).
+ * @function
+ * @param {any} value
+ * @returns {boolean} `true` for plain objects, `false` for `null`, arrays, class instances, and primitives.
+ */
 const isPlainObject = (value) => {
   if (value === null || typeof value !== 'object') {
     return false;
@@ -19,11 +47,15 @@ const isPlainObject = (value) => {
 };
 
 /**
- * Minimal deep-merge sufficient for nodemailer-shaped mail options:
+ * @name deepMerge - Minimal deep-merge sufficient for nodemailer-shaped mail options:
  * - plain objects merge key-by-key
  * - arrays concatenate
  * - other values (strings, numbers, Date, Buffer, streams, classes) replace
  * Source values override target values.
+ * @function
+ * @param {any} target - Base value; merged into a shallow clone when a plain object, otherwise ignored.
+ * @param {any} source - Overriding value; returns `target` unchanged when not a plain object.
+ * @returns {any} The merged result (a new object), or `target` when `source` is not a plain object.
  */
 const deepMerge = (target, source) => {
   if (!isPlainObject(source)) {
@@ -49,9 +81,13 @@ const deepMerge = (target, source) => {
 };
 
 /**
- * Order-insensitive deep equality. Treats arrays as multisets and
+ * @name equals - Order-insensitive deep equality. Treats arrays as multisets and
  * objects as unordered maps. Designed for the small `mailOptions`
  * shape used by MailTime's email concatenation dedup.
+ * @function
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean} `true` when `a` and `b` are deeply equal ignoring array/key order.
  */
 const equals = (a, b) => {
   if (a === b) {
@@ -110,9 +146,11 @@ const equals = (a, b) => {
 };
 
 /**
- * Extract the email part of a nodemailer-shaped recipient entry.
+ * @name extractEmail - Extract the email part of a nodemailer-shaped recipient entry.
  * Accepts `'a@x.com'`, `'Name <a@x.com>'`, or `{ name, address }`.
- * Returns the address lowercased, or `null` when none can be parsed.
+ * @function
+ * @param {string|{name?: string, address?: string}|null|undefined} entry
+ * @returns {string|null} The address lowercased and trimmed, or `null` when none can be parsed.
  */
 const extractEmail = (entry) => {
   if (!entry) {
@@ -129,7 +167,10 @@ const extractEmail = (entry) => {
 };
 
 /**
- * Normalize a `to`/`cc`/`bcc` field into a flat list of lowercase addresses.
+ * @name toAddressList - Normalize a `to`/`cc`/`bcc` field into a flat list of lowercase addresses.
+ * @function
+ * @param {string|Array<string|{name?: string, address?: string}>|null|undefined} field
+ * @returns {string[]} Flat list of parsed lowercase addresses; empty when `field` is falsy or unparseable.
  */
 const toAddressList = (field) => {
   if (!field) {
@@ -150,9 +191,13 @@ const toAddressList = (field) => {
 };
 
 /**
- * Remove entries whose extracted address is in `acceptedSet` from a
- * nodemailer `to`/`cc`/`bcc` field. Returns `void 0` when the filtered
- * array would be empty or the single string is dropped.
+ * @name filterAddressField - Remove entries whose extracted address is in `acceptedSet` from a
+ * nodemailer `to`/`cc`/`bcc` field.
+ * @function
+ * @param {string|Array<string|{name?: string, address?: string}>|null|undefined} field
+ * @param {Set<string>} acceptedSet - Lowercase addresses to drop.
+ * @returns {string|Array|undefined} The filtered field, or `void 0` when the filtered array would be
+ * empty or the single string is dropped. Returns `field` unchanged when `acceptedSet` is empty.
  */
 const filterAddressField = (field, acceptedSet) => {
   if (!field || !(acceptedSet instanceof Set) || acceptedSet.size === 0) {
@@ -175,19 +220,43 @@ const filterAddressField = (field, acceptedSet) => {
   return field;
 };
 
+/**
+ * @name isSendClaimUpdate - Detect an atomic send-claim update (`{ isSending: true, tries: N }`).
+ * @function
+ * @param {object} updateObj
+ * @returns {boolean} `true` when `updateObj` claims a row for sending.
+ */
 const isSendClaimUpdate = (updateObj) => {
   return updateObj && updateObj.isSending === true && typeof updateObj.tries === 'number';
 };
 
+/**
+ * @name isSendLeaseGuardedUpdate - Detect an update guarded by a send lease
+ * (carries `leaseTries` and `leaseSendingAt`).
+ * @function
+ * @param {object} updateObj
+ * @returns {boolean} `true` when both lease guard fields are present numbers.
+ */
 const isSendLeaseGuardedUpdate = (updateObj) => {
   return updateObj && typeof updateObj.leaseTries === 'number' && typeof updateObj.leaseSendingAt === 'number';
 };
 
+/**
+ * @name isAppendMailOptionUpdate - Detect an update that appends a mail option (for email concatenation).
+ * @function
+ * @param {object} updateObj
+ * @returns {boolean} `true` when `updateObj.appendMailOption` is set.
+ */
 const isAppendMailOptionUpdate = (updateObj) => {
   return updateObj && updateObj.appendMailOption !== void 0;
 };
 
-/** Strip MailTime-internal update keys before persisting to storage. */
+/**
+ * @name stripInternalUpdateMeta - Strip MailTime-internal update keys before persisting to storage.
+ * @function
+ * @param {object} updateObj
+ * @returns {object} A shallow clone without `leaseTries`, `leaseSendingAt`, and `appendMailOption`.
+ */
 const stripInternalUpdateMeta = (updateObj) => {
   const out = { ...updateObj };
   delete out.leaseTries;
@@ -196,6 +265,13 @@ const stripInternalUpdateMeta = (updateObj) => {
   return out;
 };
 
+/**
+ * @name isSendLeaseRemove - Detect a remove guarded by a send lease
+ * (carries `leaseTries` and `leaseSendingAt`).
+ * @function
+ * @param {object} opts
+ * @returns {boolean} `true` when both lease guard fields are present numbers.
+ */
 const isSendLeaseRemove = (opts) => {
   return opts && typeof opts.leaseTries === 'number' && typeof opts.leaseSendingAt === 'number';
 };
@@ -203,6 +279,7 @@ const isSendLeaseRemove = (opts) => {
 export {
   debug,
   logError,
+  hasOwnProp,
   isPlainObject,
   deepMerge,
   equals,

package/index.cjs

@@ -1,20 +1,48 @@
 'use strict';
 
 const josk = require('josk');
-const node_crypto = require('node:crypto');
+const crypto = require('crypto');
 
 const hasOwn = Object.prototype.hasOwnProperty;
 
+/**
+ * @name hasOwnProp - `Object.hasOwn` (ES2022) polyfill.
+ * @function
+ * @param {object} obj
+ * @param {PropertyKey} key
+ * @returns {boolean} `true` if the object has the property, `false` otherwise.
+ */
+const hasOwnProp = (obj, key) => hasOwn.call(obj, key);
+
+/**
+ * @name debug - Debug logging.
+ * @function
+ * @param {boolean} isDebug
+ * @param {...any} args
+ * @returns {void}
+ */
 const debug = (isDebug, ...args) => {
   if (isDebug) {
     console.info('[DEBUG] [mail-time]', `${new Date()}`, ...args);
   }
 };
 
+/**
+ * @name logError - Error logging.
+ * @function
+ * @param {...any} args
+ * @returns {void}
+ */
 const logError = (...args) => {
   console.error('[ERROR] [mail-time]', `${new Date()}`, ...args);
 };
 
+/**
+ * @name isPlainObject - Check whether a value is a plain object (literal or `Object.create(null)`).
+ * @function
+ * @param {any} value
+ * @returns {boolean} `true` for plain objects, `false` for `null`, arrays, class instances, and primitives.
+ */
 const isPlainObject = (value) => {
   if (value === null || typeof value !== 'object') {
     return false;
@@ -24,11 +52,15 @@ const isPlainObject = (value) => {
 };
 
 /**
- * Minimal deep-merge sufficient for nodemailer-shaped mail options:
+ * @name deepMerge - Minimal deep-merge sufficient for nodemailer-shaped mail options:
  * - plain objects merge key-by-key
  * - arrays concatenate
  * - other values (strings, numbers, Date, Buffer, streams, classes) replace
  * Source values override target values.
+ * @function
+ * @param {any} target - Base value; merged into a shallow clone when a plain object, otherwise ignored.
+ * @param {any} source - Overriding value; returns `target` unchanged when not a plain object.
+ * @returns {any} The merged result (a new object), or `target` when `source` is not a plain object.
  */
 const deepMerge = (target, source) => {
   if (!isPlainObject(source)) {
@@ -54,9 +86,13 @@ const deepMerge = (target, source) => {
 };
 
 /**
- * Order-insensitive deep equality. Treats arrays as multisets and
+ * @name equals - Order-insensitive deep equality. Treats arrays as multisets and
  * objects as unordered maps. Designed for the small `mailOptions`
  * shape used by MailTime's email concatenation dedup.
+ * @function
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean} `true` when `a` and `b` are deeply equal ignoring array/key order.
  */
 const equals = (a, b) => {
   if (a === b) {
@@ -115,9 +151,11 @@ const equals = (a, b) => {
 };
 
 /**
- * Extract the email part of a nodemailer-shaped recipient entry.
+ * @name extractEmail - Extract the email part of a nodemailer-shaped recipient entry.
  * Accepts `'a@x.com'`, `'Name <a@x.com>'`, or `{ name, address }`.
- * Returns the address lowercased, or `null` when none can be parsed.
+ * @function
+ * @param {string|{name?: string, address?: string}|null|undefined} entry
+ * @returns {string|null} The address lowercased and trimmed, or `null` when none can be parsed.
  */
 const extractEmail = (entry) => {
   if (!entry) {
@@ -134,7 +172,10 @@ const extractEmail = (entry) => {
 };
 
 /**
- * Normalize a `to`/`cc`/`bcc` field into a flat list of lowercase addresses.
+ * @name toAddressList - Normalize a `to`/`cc`/`bcc` field into a flat list of lowercase addresses.
+ * @function
+ * @param {string|Array<string|{name?: string, address?: string}>|null|undefined} field
+ * @returns {string[]} Flat list of parsed lowercase addresses; empty when `field` is falsy or unparseable.
  */
 const toAddressList = (field) => {
   if (!field) {
@@ -155,9 +196,13 @@ const toAddressList = (field) => {
 };
 
 /**
- * Remove entries whose extracted address is in `acceptedSet` from a
- * nodemailer `to`/`cc`/`bcc` field. Returns `void 0` when the filtered
- * array would be empty or the single string is dropped.
+ * @name filterAddressField - Remove entries whose extracted address is in `acceptedSet` from a
+ * nodemailer `to`/`cc`/`bcc` field.
+ * @function
+ * @param {string|Array<string|{name?: string, address?: string}>|null|undefined} field
+ * @param {Set<string>} acceptedSet - Lowercase addresses to drop.
+ * @returns {string|Array|undefined} The filtered field, or `void 0` when the filtered array would be
+ * empty or the single string is dropped. Returns `field` unchanged when `acceptedSet` is empty.
  */
 const filterAddressField = (field, acceptedSet) => {
   if (!field || !(acceptedSet instanceof Set) || acceptedSet.size === 0) {
@@ -180,19 +225,43 @@ const filterAddressField = (field, acceptedSet) => {
   return field;
 };
 
+/**
+ * @name isSendClaimUpdate - Detect an atomic send-claim update (`{ isSending: true, tries: N }`).
+ * @function
+ * @param {object} updateObj
+ * @returns {boolean} `true` when `updateObj` claims a row for sending.
+ */
 const isSendClaimUpdate = (updateObj) => {
   return updateObj && updateObj.isSending === true && typeof updateObj.tries === 'number';
 };
 
+/**
+ * @name isSendLeaseGuardedUpdate - Detect an update guarded by a send lease
+ * (carries `leaseTries` and `leaseSendingAt`).
+ * @function
+ * @param {object} updateObj
+ * @returns {boolean} `true` when both lease guard fields are present numbers.
+ */
 const isSendLeaseGuardedUpdate = (updateObj) => {
   return updateObj && typeof updateObj.leaseTries === 'number' && typeof updateObj.leaseSendingAt === 'number';
 };
 
+/**
+ * @name isAppendMailOptionUpdate - Detect an update that appends a mail option (for email concatenation).
+ * @function
+ * @param {object} updateObj
+ * @returns {boolean} `true` when `updateObj.appendMailOption` is set.
+ */
 const isAppendMailOptionUpdate = (updateObj) => {
   return updateObj && updateObj.appendMailOption !== void 0;
 };
 
-/** Strip MailTime-internal update keys before persisting to storage. */
+/**
+ * @name stripInternalUpdateMeta - Strip MailTime-internal update keys before persisting to storage.
+ * @function
+ * @param {object} updateObj
+ * @returns {object} A shallow clone without `leaseTries`, `leaseSendingAt`, and `appendMailOption`.
+ */
 const stripInternalUpdateMeta = (updateObj) => {
   const out = { ...updateObj };
   delete out.leaseTries;
@@ -201,6 +270,13 @@ const stripInternalUpdateMeta = (updateObj) => {
   return out;
 };
 
+/**
+ * @name isSendLeaseRemove - Detect a remove guarded by a send lease
+ * (carries `leaseTries` and `leaseSendingAt`).
+ * @function
+ * @param {object} opts
+ * @returns {boolean} `true` when both lease guard fields are present numbers.
+ */
 const isSendLeaseRemove = (opts) => {
   return opts && typeof opts.leaseTries === 'number' && typeof opts.leaseSendingAt === 'number';
 };
@@ -425,10 +501,13 @@ class MongoQueue {
         cursor.limit(limit);
       }
 
-      while (await cursor.hasNext()) {
-        await this.mailTimeInstance.___dispatch(await cursor.next());
+      try {
+        while (await cursor.hasNext()) {
+          await this.mailTimeInstance.___dispatch(await cursor.next());
+        }
+      } finally {
+        await cursor.close().catch(() => {});
       }
-      await cursor.close();
     } catch (iterateError) {
       logError('[iterate] [while/await] [iterateError]', iterateError);
     }
@@ -1197,7 +1276,21 @@ class RedisQueue {
  */
 
 const DEFAULT_PREFIX = 'default';
-const setupLockId = 93824519;
+
+// Two-key advisory lock, mirroring josk's PostgresAdapter: a stable MailTime namespace
+// plus a per-prefix hash. `pg_advisory_lock(int4, int4)` lives in its own keyspace, isolated
+// from single-int callers in the same database; distinct prefixes get distinct lock IDs, so
+// co-tenant MailTime queues no longer serialize each other's schema setup.
+const ADVISORY_LOCK_NAMESPACE = 0x4D61696C; // 'Mail' in ASCII as int32
+
+/**
+ * @internal
+ * @param {string} prefix
+ * @returns {number} signed int32 hash of the prefix string
+ */
+const advisoryLockKeyFor = (prefix) => {
+  return crypto.createHash('sha256').update(prefix).digest().readInt32BE(0);
+};
 
 const fieldMap = {
   to: 'to_address',
@@ -1300,7 +1393,8 @@ class PostgresQueue {
 
   /** @internal */
   async __setup() {
-    await this.client.query('SELECT pg_advisory_lock($1)', [setupLockId]);
+    const advisoryLockKey = advisoryLockKeyFor(this.prefix);
+    await this.client.query('SELECT pg_advisory_lock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
 
     try {
       await this.client.query(`CREATE TABLE IF NOT EXISTS mail_time_queue (
@@ -1331,7 +1425,7 @@ class PostgresQueue {
       await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_pending_to
         ON mail_time_queue (prefix, to_address, is_sent, is_failed, is_cancelled, send_at)`);
     } finally {
-      await this.client.query('SELECT pg_advisory_unlock($1)', [setupLockId]);
+      await this.client.query('SELECT pg_advisory_unlock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
     }
   }
 
@@ -1713,7 +1807,7 @@ function defaultPresetOnError(error, email, info) {
  * @property {number} [sendingTimeout]
  * @property {'one' | 'batch'} [mode]
  * @property {number} [concurrency]
- * @property {(error: unknown, email: object, details?: object) => void} [onError]
+ * @property {(error: unknown, email: any, details?: object) => void} [onError]
  * @property {object} [josk]
  */
 
@@ -1863,12 +1957,12 @@ const presetNames = Object.freeze(/** @type {MailTimePresetName[]} */ (Object.ke
  *
  * @param {MailTimePresetName} name - one of `presetNames`
  * @param {object} [overrides] - additional MailTime constructor options
- * @returns {object} fresh, mutable MailTime constructor options
+ * @returns {MailTimePresetConfig} fresh, mutable MailTime constructor options (preset deep-cloned + overrides merged)
  * @throws {Error} when `name` is unknown
  * @throws {TypeError} when `overrides` is provided but not a plain object
  */
 const mailTimePreset = (name, overrides) => {
-  if (typeof name !== 'string' || !Object.hasOwn(PRESETS, name)) {
+  if (typeof name !== 'string' || !hasOwnProp(PRESETS, name)) {
     throw new Error(`[mail-time] [mailTimePreset] unknown preset "${name}". Available: ${presetNames.join(', ')}`);
   }
   if (overrides !== void 0 && !isPlainObject(overrides)) {
@@ -2010,7 +2104,7 @@ let DEFAULT_TEMPLATE = '<!DOCTYPE html><html xmlns=http://www.w3.org/1999/xhtml>
  */
 
 /**
- * @typedef {{ status: string, code: number, statusCode: number, error?: unknown }} MailTimePingResult
+ * @typedef {{ status: string, code: number, statusCode: number, paused?: boolean, error?: unknown }} MailTimePingResult
  */
 
 /**
@@ -2121,6 +2215,8 @@ class MailTime {
     this.concurrency = (typeof opts.concurrency === 'number' && opts.concurrency > 0 && Number.isFinite(opts.concurrency)) ? Math.floor(opts.concurrency) : 1;
     this.sendingTimeout = (typeof opts.sendingTimeout === 'number' && opts.sendingTimeout > 0) ? opts.sendingTimeout : 300000;
     this.__isDestroyed = false;
+    this.__abortInFlight = false;
+    this.__isPaused = false;
     this.__readyPromise = null;
     this.__schedulerTimer = null;
     this.__inFlight = new Set();
@@ -2273,10 +2369,11 @@ class MailTime {
     if (this.scheduler) {
       const schedulerPing = await this.scheduler.ping();
       if (schedulerPing.status !== 'OK') {
-        return schedulerPing;
+        return { ...schedulerPing, paused: this.__isPaused };
       }
     }
-    return await this.queue.ping();
+    const queuePing = await this.queue.ping();
+    return { ...queuePing, paused: this.__isPaused };
   }
 
   /**
@@ -2294,7 +2391,7 @@ class MailTime {
   /**
    * @memberOf MailTime
    * @name destroy
-   * @description Stop the scheduler and block future dispatches. Pass `{ drain: true }` to also wait for in-flight SMTP attempts (returns a Promise).
+   * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, any in-flight SMTP attempts are neutralized on completion — they perform no storage writes, no `onSent`/`onError` callbacks, and no logging once `destroy()` returns; their claimed rows are recovered by stale-lock timeout (`sendingTimeout`). Pass `{ drain: true }` to instead let in-flight attempts run to completion (returns a Promise that resolves once they settle).
    * @param {{ drain?: boolean }} [opts]
    * @returns {boolean | Promise<boolean>}
    */
@@ -2305,12 +2402,21 @@ class MailTime {
     }
 
     this.__isDestroyed = true;
+    this.__isPaused = false;
     if (this.scheduler && typeof this.scheduler.destroy === 'function') {
       this.scheduler.destroy();
     }
     if (opts && opts.drain === true && this.__pool) {
       return this.__pool.drain().then(() => true);
     }
+    // No graceful drain requested: neutralize in-flight SMTP completions so a
+    // destroyed instance performs no storage writes, no `onSent`/`onError`
+    // callbacks, and no logging after teardown. Each claimed row keeps its
+    // `isSending` lock, which a peer or a future instance recovers once
+    // `sendingTimeout` elapses — identical to a crash mid-send. Use
+    // `destroy({ drain: true })` (or `await drain()` before `destroy()`) when
+    // in-flight sends must run to completion.
+    this.__abortInFlight = true;
     return true;
   }
 
@@ -2328,6 +2434,52 @@ class MailTime {
     }
   }
 
+  /**
+   * @memberOf MailTime
+   * @name pause
+   * @description Pause this server instance from competing for the queue-drain lease. In-flight SMTP sends finish; peer server instances keep draining. Reversible (unlike `destroy()`). No-op on `client` instances or after `destroy()`. To stop scanning *and* wait for in-flight sends: `mailTime.pause(); await mailTime.drain();`.
+   * @returns {boolean} `true` if newly paused; `false` if already paused, a client instance, or destroyed
+   */
+  pause() {
+    this.__debug('[pause]');
+    if (this.__isDestroyed || !this.scheduler) {
+      return false;
+    }
+    const paused = this.scheduler.pause();
+    if (paused) {
+      this.__isPaused = true;
+    }
+    return paused;
+  }
+
+  /**
+   * @memberOf MailTime
+   * @name resume
+   * @description Resume competing for the queue-drain lease after `pause()`; triggers an immediate scan. No-op on `client` instances, after `destroy()`, or when not paused.
+   * @returns {boolean} `true` if newly resumed; `false` if not paused, a client instance, or destroyed
+   */
+  resume() {
+    this.__debug('[resume]');
+    if (this.__isDestroyed || !this.scheduler) {
+      return false;
+    }
+    const resumed = this.scheduler.resume();
+    if (resumed) {
+      this.__isPaused = false;
+    }
+    return resumed;
+  }
+
+  /**
+   * @memberOf MailTime
+   * @name isPaused
+   * @description Whether this instance is currently paused from draining the queue. Always `false` on `client` instances.
+   * @returns {boolean}
+   */
+  get isPaused() {
+    return this.__isPaused;
+  }
+
   /**
    * @memberOf MailTime
    * @name send
@@ -2445,6 +2597,10 @@ class MailTime {
    */
   async ___handleError(task, error, info) {
     this.__debug('[private handleError]', { task, error, info });
+    if (this.__abortInFlight) {
+      this.__debug('[private handleError] instance destroyed; skipping onError', task?.uuid);
+      return;
+    }
     if (!task) {
       return;
     }
@@ -2521,7 +2677,7 @@ class MailTime {
       this.transport = transportIndex;
     }
     const task = {
-      uuid: node_crypto.randomUUID(),
+      uuid: crypto.randomUUID(),
       tries: 0,
       isSent: false,
       sendAt: opts.sendAt,
@@ -2558,7 +2714,7 @@ class MailTime {
     if (matchHTML) {
       for (let i = 0; i < matchHTML.length; i++) {
         const key = matchHTML[i].slice(3, -3).trim();
-        if (Object.hasOwn(replacements, key) && replacements[key] !== null && replacements[key] !== void 0) {
+        if (hasOwnProp(replacements, key) && replacements[key] !== null && replacements[key] !== void 0) {
           string = string.replace(matchHTML[i], `${replacements[key]}`);
         }
       }
@@ -2568,7 +2724,7 @@ class MailTime {
     if (matchStr) {
       for (let i = 0; i < matchStr.length; i++) {
         const key = matchStr[i].slice(2, -2).trim();
-        if (Object.hasOwn(replacements, key) && replacements[key] !== null && replacements[key] !== void 0) {
+        if (hasOwnProp(replacements, key) && replacements[key] !== null && replacements[key] !== void 0) {
           string = string.replace(matchStr[i], `${replacements[key]}`.replace(/<(?:.|\n)*?>/gm, ''));
         }
       }
@@ -2803,6 +2959,11 @@ class MailTime {
 
       await new Promise((resolve) => {
         transport.sendMail(compiledOpts, async (error, info) => {
+          if (this.__abortInFlight) {
+            this.__debug('[private send] instance destroyed mid-send; leaving claim for stale-lock recovery', task.uuid);
+            resolve();
+            return;
+          }
           this.__debug('[private send] [sending]', { error, info });
           try {
             if (error) {
@@ -2921,6 +3082,10 @@ class MailTime {
         });
       });
     } catch (e) {
+      if (this.__abortInFlight) {
+        this.__debug('[private send] instance destroyed mid-send; suppressing runtime exception', e);
+        return;
+      }
       logError('Exception during runtime:', e);
       await this.___handleError(task, e, {});
     }
@@ -2935,7 +3100,7 @@ class MailTime {
    */
   async ___iterate() {
     this.__debug('[private iterate]');
-    if (this.__isDestroyed) {
+    if (this.__isDestroyed || this.__isPaused) {
       return;
     }
     const limit = this.mode === 'one' ? 1 : Infinity;

package/index.d.cts

@@ -4,6 +4,7 @@ export type MailTimePingResult = {
     status: string;
     code: number;
     statusCode: number;
+    paused?: boolean;
     error?: unknown;
 };
 export type MailTimeStorageClient = {
@@ -130,7 +131,7 @@ export type MailTimeOptions = {
  * @typedef {import('./presets.js').MailTimePresetConfig} MailTimePresetConfig
  */
 /**
- * @typedef {{ status: string, code: number, statusCode: number, error?: unknown }} MailTimePingResult
+ * @typedef {{ status: string, code: number, statusCode: number, paused?: boolean, error?: unknown }} MailTimePingResult
  */
 /**
  * @typedef {{ [key: string]: any, query?: (queryText: string, values?: unknown[]) => Promise<{ rows?: unknown[], rowCount?: number | null }> }} MailTimeStorageClient
@@ -238,7 +239,7 @@ export class MailTime {
     /**
      * @memberOf MailTime
      * @name destroy
-     * @description Stop the scheduler and block future dispatches. Pass `{ drain: true }` to also wait for in-flight SMTP attempts (returns a Promise).
+     * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, any in-flight SMTP attempts are neutralized on completion — they perform no storage writes, no `onSent`/`onError` callbacks, and no logging once `destroy()` returns; their claimed rows are recovered by stale-lock timeout (`sendingTimeout`). Pass `{ drain: true }` to instead let in-flight attempts run to completion (returns a Promise that resolves once they settle).
      * @param {{ drain?: boolean }} [opts]
      * @returns {boolean | Promise<boolean>}
      */
@@ -253,6 +254,27 @@ export class MailTime {
      * @returns {Promise<void>}
      */
     drain(): Promise<void>;
+    /**
+     * @memberOf MailTime
+     * @name pause
+     * @description Pause this server instance from competing for the queue-drain lease. In-flight SMTP sends finish; peer server instances keep draining. Reversible (unlike `destroy()`). No-op on `client` instances or after `destroy()`. To stop scanning *and* wait for in-flight sends: `mailTime.pause(); await mailTime.drain();`.
+     * @returns {boolean} `true` if newly paused; `false` if already paused, a client instance, or destroyed
+     */
+    pause(): boolean;
+    /**
+     * @memberOf MailTime
+     * @name resume
+     * @description Resume competing for the queue-drain lease after `pause()`; triggers an immediate scan. No-op on `client` instances, after `destroy()`, or when not paused.
+     * @returns {boolean} `true` if newly resumed; `false` if not paused, a client instance, or destroyed
+     */
+    resume(): boolean;
+    /**
+     * @memberOf MailTime
+     * @name isPaused
+     * @description Whether this instance is currently paused from draining the queue. Always `false` on `client` instances.
+     * @returns {boolean}
+     */
+    get isPaused(): boolean;
     /**
      * @memberOf MailTime
      * @name send

package/index.d.ts

@@ -4,6 +4,7 @@ export type MailTimePingResult = {
     status: string;
     code: number;
     statusCode: number;
+    paused?: boolean;
     error?: unknown;
 };
 export type MailTimeStorageClient = {
@@ -130,7 +131,7 @@ export type MailTimeOptions = {
  * @typedef {import('./presets.js').MailTimePresetConfig} MailTimePresetConfig
  */
 /**
- * @typedef {{ status: string, code: number, statusCode: number, error?: unknown }} MailTimePingResult
+ * @typedef {{ status: string, code: number, statusCode: number, paused?: boolean, error?: unknown }} MailTimePingResult
  */
 /**
  * @typedef {{ [key: string]: any, query?: (queryText: string, values?: unknown[]) => Promise<{ rows?: unknown[], rowCount?: number | null }> }} MailTimeStorageClient
@@ -238,7 +239,7 @@ export class MailTime {
     /**
      * @memberOf MailTime
      * @name destroy
-     * @description Stop the scheduler and block future dispatches. Pass `{ drain: true }` to also wait for in-flight SMTP attempts (returns a Promise).
+     * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, any in-flight SMTP attempts are neutralized on completion — they perform no storage writes, no `onSent`/`onError` callbacks, and no logging once `destroy()` returns; their claimed rows are recovered by stale-lock timeout (`sendingTimeout`). Pass `{ drain: true }` to instead let in-flight attempts run to completion (returns a Promise that resolves once they settle).
      * @param {{ drain?: boolean }} [opts]
      * @returns {boolean | Promise<boolean>}
      */
@@ -253,6 +254,27 @@ export class MailTime {
      * @returns {Promise<void>}
      */
     drain(): Promise<void>;
+    /**
+     * @memberOf MailTime
+     * @name pause
+     * @description Pause this server instance from competing for the queue-drain lease. In-flight SMTP sends finish; peer server instances keep draining. Reversible (unlike `destroy()`). No-op on `client` instances or after `destroy()`. To stop scanning *and* wait for in-flight sends: `mailTime.pause(); await mailTime.drain();`.
+     * @returns {boolean} `true` if newly paused; `false` if already paused, a client instance, or destroyed
+     */
+    pause(): boolean;
+    /**
+     * @memberOf MailTime
+     * @name resume
+     * @description Resume competing for the queue-drain lease after `pause()`; triggers an immediate scan. No-op on `client` instances, after `destroy()`, or when not paused.
+     * @returns {boolean} `true` if newly resumed; `false` if not paused, a client instance, or destroyed
+     */
+    resume(): boolean;
+    /**
+     * @memberOf MailTime
+     * @name isPaused
+     * @description Whether this instance is currently paused from draining the queue. Always `false` on `client` instances.
+     * @returns {boolean}
+     */
+    get isPaused(): boolean;
     /**
      * @memberOf MailTime
      * @name send

package/index.js

@@ -1,11 +1,11 @@
 import { JoSk, RedisAdapter, MongoAdapter, PostgresAdapter } from 'josk';
-import { randomUUID } from 'node:crypto';
+import { randomUUID } from 'crypto';
 
 import { MongoQueue } from './adapters/mongo.js';
 import { RedisQueue } from './adapters/redis.js';
 import { PostgresQueue } from './adapters/postgres.js';
 import { mailTimePreset, presets, presetNames } from './presets.js';
-import { debug, logError, deepMerge, equals, isPlainObject, extractEmail, toAddressList, filterAddressField } from './helpers.js';
+import { debug, logError, hasOwnProp, deepMerge, equals, isPlainObject, extractEmail, toAddressList, filterAddressField } from './helpers.js';
 
 const noop = () => {};
 const queueMethods = ['ping', 'iterate', 'getPendingTo', 'push', 'remove', 'update', 'cancel'];
@@ -139,7 +139,7 @@ let DEFAULT_TEMPLATE = '<!DOCTYPE html><html xmlns=http://www.w3.org/1999/xhtml>
  */
 
 /**
- * @typedef {{ status: string, code: number, statusCode: number, error?: unknown }} MailTimePingResult
+ * @typedef {{ status: string, code: number, statusCode: number, paused?: boolean, error?: unknown }} MailTimePingResult
  */
 
 /**
@@ -250,6 +250,8 @@ class MailTime {
     this.concurrency = (typeof opts.concurrency === 'number' && opts.concurrency > 0 && Number.isFinite(opts.concurrency)) ? Math.floor(opts.concurrency) : 1;
     this.sendingTimeout = (typeof opts.sendingTimeout === 'number' && opts.sendingTimeout > 0) ? opts.sendingTimeout : 300000;
     this.__isDestroyed = false;
+    this.__abortInFlight = false;
+    this.__isPaused = false;
     this.__readyPromise = null;
     this.__schedulerTimer = null;
     this.__inFlight = new Set();
@@ -402,10 +404,11 @@ class MailTime {
     if (this.scheduler) {
       const schedulerPing = await this.scheduler.ping();
       if (schedulerPing.status !== 'OK') {
-        return schedulerPing;
+        return { ...schedulerPing, paused: this.__isPaused };
       }
     }
-    return await this.queue.ping();
+    const queuePing = await this.queue.ping();
+    return { ...queuePing, paused: this.__isPaused };
   }
 
   /**
@@ -423,7 +426,7 @@ class MailTime {
   /**
    * @memberOf MailTime
    * @name destroy
-   * @description Stop the scheduler and block future dispatches. Pass `{ drain: true }` to also wait for in-flight SMTP attempts (returns a Promise).
+   * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, any in-flight SMTP attempts are neutralized on completion — they perform no storage writes, no `onSent`/`onError` callbacks, and no logging once `destroy()` returns; their claimed rows are recovered by stale-lock timeout (`sendingTimeout`). Pass `{ drain: true }` to instead let in-flight attempts run to completion (returns a Promise that resolves once they settle).
    * @param {{ drain?: boolean }} [opts]
    * @returns {boolean | Promise<boolean>}
    */
@@ -434,12 +437,21 @@ class MailTime {
     }
 
     this.__isDestroyed = true;
+    this.__isPaused = false;
     if (this.scheduler && typeof this.scheduler.destroy === 'function') {
       this.scheduler.destroy();
     }
     if (opts && opts.drain === true && this.__pool) {
       return this.__pool.drain().then(() => true);
     }
+    // No graceful drain requested: neutralize in-flight SMTP completions so a
+    // destroyed instance performs no storage writes, no `onSent`/`onError`
+    // callbacks, and no logging after teardown. Each claimed row keeps its
+    // `isSending` lock, which a peer or a future instance recovers once
+    // `sendingTimeout` elapses — identical to a crash mid-send. Use
+    // `destroy({ drain: true })` (or `await drain()` before `destroy()`) when
+    // in-flight sends must run to completion.
+    this.__abortInFlight = true;
     return true;
   }
 
@@ -457,6 +469,52 @@ class MailTime {
     }
   }
 
+  /**
+   * @memberOf MailTime
+   * @name pause
+   * @description Pause this server instance from competing for the queue-drain lease. In-flight SMTP sends finish; peer server instances keep draining. Reversible (unlike `destroy()`). No-op on `client` instances or after `destroy()`. To stop scanning *and* wait for in-flight sends: `mailTime.pause(); await mailTime.drain();`.
+   * @returns {boolean} `true` if newly paused; `false` if already paused, a client instance, or destroyed
+   */
+  pause() {
+    this.__debug('[pause]');
+    if (this.__isDestroyed || !this.scheduler) {
+      return false;
+    }
+    const paused = this.scheduler.pause();
+    if (paused) {
+      this.__isPaused = true;
+    }
+    return paused;
+  }
+
+  /**
+   * @memberOf MailTime
+   * @name resume
+   * @description Resume competing for the queue-drain lease after `pause()`; triggers an immediate scan. No-op on `client` instances, after `destroy()`, or when not paused.
+   * @returns {boolean} `true` if newly resumed; `false` if not paused, a client instance, or destroyed
+   */
+  resume() {
+    this.__debug('[resume]');
+    if (this.__isDestroyed || !this.scheduler) {
+      return false;
+    }
+    const resumed = this.scheduler.resume();
+    if (resumed) {
+      this.__isPaused = false;
+    }
+    return resumed;
+  }
+
+  /**
+   * @memberOf MailTime
+   * @name isPaused
+   * @description Whether this instance is currently paused from draining the queue. Always `false` on `client` instances.
+   * @returns {boolean}
+   */
+  get isPaused() {
+    return this.__isPaused;
+  }
+
   /**
    * @memberOf MailTime
    * @name send
@@ -574,6 +632,10 @@ class MailTime {
    */
   async ___handleError(task, error, info) {
     this.__debug('[private handleError]', { task, error, info });
+    if (this.__abortInFlight) {
+      this.__debug('[private handleError] instance destroyed; skipping onError', task?.uuid);
+      return;
+    }
     if (!task) {
       return;
     }
@@ -687,7 +749,7 @@ class MailTime {
     if (matchHTML) {
       for (let i = 0; i < matchHTML.length; i++) {
         const key = matchHTML[i].slice(3, -3).trim();
-        if (Object.hasOwn(replacements, key) && replacements[key] !== null && replacements[key] !== void 0) {
+        if (hasOwnProp(replacements, key) && replacements[key] !== null && replacements[key] !== void 0) {
           string = string.replace(matchHTML[i], `${replacements[key]}`);
         }
       }
@@ -697,7 +759,7 @@ class MailTime {
     if (matchStr) {
       for (let i = 0; i < matchStr.length; i++) {
         const key = matchStr[i].slice(2, -2).trim();
-        if (Object.hasOwn(replacements, key) && replacements[key] !== null && replacements[key] !== void 0) {
+        if (hasOwnProp(replacements, key) && replacements[key] !== null && replacements[key] !== void 0) {
           string = string.replace(matchStr[i], `${replacements[key]}`.replace(/<(?:.|\n)*?>/gm, ''));
         }
       }
@@ -932,6 +994,11 @@ class MailTime {
 
       await new Promise((resolve) => {
         transport.sendMail(compiledOpts, async (error, info) => {
+          if (this.__abortInFlight) {
+            this.__debug('[private send] instance destroyed mid-send; leaving claim for stale-lock recovery', task.uuid);
+            resolve();
+            return;
+          }
           this.__debug('[private send] [sending]', { error, info });
           try {
             if (error) {
@@ -1050,6 +1117,10 @@ class MailTime {
         });
       });
     } catch (e) {
+      if (this.__abortInFlight) {
+        this.__debug('[private send] instance destroyed mid-send; suppressing runtime exception', e);
+        return;
+      }
       logError('Exception during runtime:', e);
       await this.___handleError(task, e, {});
     }
@@ -1064,7 +1135,7 @@ class MailTime {
    */
   async ___iterate() {
     this.__debug('[private iterate]');
-    if (this.__isDestroyed) {
+    if (this.__isDestroyed || this.__isPaused) {
       return;
     }
     const limit = this.mode === 'one' ? 1 : Infinity;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mail-time",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "📮 Email queue extending nodemailer with multi-SMTP transports and horizontally scaled apps support",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -47,6 +47,9 @@
     "test": "npm run test:jest && npm run test:mocha && npm run test:types",
     "test:jest": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config jest.config.mjs",
     "test:mocha": "mocha ./test/npm.js",
+    "test:mocha:redis": "mocha ./test/npm-redis-redis.js",
+    "test:mocha:mongo": "mocha ./test/npm-redis-mongo.js ./test/npm-mongo-redis.js ./test/npm-ha-mongo-redis.js",
+    "test:mocha:postgres": "mocha ./test/npm-postgres.js",
     "test:types": "tsc -p ./tsconfig.types.json",
     "test:redis": "mocha ./test/npm-redis-redis.js",
     "test:mongo": "mocha ./test/npm-mongo-mongo.js",
@@ -110,10 +113,19 @@
   "author": "dr.dimitru (https://veliovgroup.com)",
   "license": "BSD-3-Clause",
   "engines": {
-    "node": ">=20.9.0"
+    "node": ">=20.9.0",
+    "bun": ">=1.1.0"
+  },
+  "meteor": {
+    "packageName": "ostrio:mailer",
+    "versionsFrom": ["2.14", "3.2"],
+    "node": {
+      "2.14": ">=14",
+      "3.2": ">=18"
+    }
   },
   "dependencies": {
-    "josk": "^6.1.0"
+    "josk": "^6.2.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/presets.d.ts

@@ -8,7 +8,7 @@ export type MailTimePresetConfig = {
     sendingTimeout?: number | undefined;
     mode?: "one" | "batch" | undefined;
     concurrency?: number | undefined;
-    onError?: ((error: unknown, email: object, details?: object) => void) | undefined;
+    onError?: ((error: unknown, email: any, details?: object) => void) | undefined;
     josk?: object | undefined;
 };
 export type MailTimePresetName = keyof typeof PRESETS;
@@ -31,11 +31,11 @@ export type MailTimePresetName = keyof typeof PRESETS;
  *
  * @param {MailTimePresetName} name - one of `presetNames`
  * @param {object} [overrides] - additional MailTime constructor options
- * @returns {object} fresh, mutable MailTime constructor options
+ * @returns {MailTimePresetConfig} fresh, mutable MailTime constructor options (preset deep-cloned + overrides merged)
  * @throws {Error} when `name` is unknown
  * @throws {TypeError} when `overrides` is provided but not a plain object
  */
-export function mailTimePreset(name: MailTimePresetName, overrides?: object): object;
+export function mailTimePreset(name: MailTimePresetName, overrides?: object): MailTimePresetConfig;
 /**
  * Read-only map of preset name → partial MailTime config. Use
  * `mailTimePreset(name, overrides)` to materialize a merged copy; use
@@ -62,7 +62,7 @@ export const presetNames: ReadonlyArray<MailTimePresetName>;
  * @property {number} [sendingTimeout]
  * @property {'one' | 'batch'} [mode]
  * @property {number} [concurrency]
- * @property {(error: unknown, email: object, details?: object) => void} [onError]
+ * @property {(error: unknown, email: any, details?: object) => void} [onError]
  * @property {object} [josk]
  */
 /**

package/presets.js

@@ -1,4 +1,4 @@
-import { deepMerge, isPlainObject, logError } from './helpers.js';
+import { deepMerge, hasOwnProp, isPlainObject, logError } from './helpers.js';
 
 /**
  * Default `onError` hook used by every built-in preset. Logs via the
@@ -25,7 +25,7 @@ function defaultPresetOnError(error, email, info) {
  * @property {number} [sendingTimeout]
  * @property {'one' | 'batch'} [mode]
  * @property {number} [concurrency]
- * @property {(error: unknown, email: object, details?: object) => void} [onError]
+ * @property {(error: unknown, email: any, details?: object) => void} [onError]
  * @property {object} [josk]
  */
 
@@ -175,12 +175,12 @@ const presetNames = Object.freeze(/** @type {MailTimePresetName[]} */ (Object.ke
  *
  * @param {MailTimePresetName} name - one of `presetNames`
  * @param {object} [overrides] - additional MailTime constructor options
- * @returns {object} fresh, mutable MailTime constructor options
+ * @returns {MailTimePresetConfig} fresh, mutable MailTime constructor options (preset deep-cloned + overrides merged)
  * @throws {Error} when `name` is unknown
  * @throws {TypeError} when `overrides` is provided but not a plain object
  */
 const mailTimePreset = (name, overrides) => {
-  if (typeof name !== 'string' || !Object.hasOwn(PRESETS, name)) {
+  if (typeof name !== 'string' || !hasOwnProp(PRESETS, name)) {
     throw new Error(`[mail-time] [mailTimePreset] unknown preset "${name}". Available: ${presetNames.join(', ')}`);
   }
   if (overrides !== void 0 && !isPlainObject(overrides)) {