mail-time 3.0.0 → 4.0.0

package/package.json

@@ -1,22 +1,64 @@
 {
   "name": "mail-time",
-  "version": "3.0.0",
-  "description": "📮 Email queue extending NodeMailer with multi SMTP transports and horizontally scaled apps support",
+  "version": "4.0.0",
+  "description": "📮 Email queue extending nodemailer with multi-SMTP transports and horizontally scaled apps support",
   "main": "index.js",
+  "types": "./index.d.ts",
   "type": "module",
   "exports": {
-    "import": "./index.js",
-    "require": "./index.cjs"
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.cjs"
+      }
+    },
+    "./presets": {
+      "import": {
+        "types": "./presets.d.ts",
+        "default": "./presets.js"
+      }
+    },
+    "./adapters/mongo": {
+      "import": {
+        "types": "./adapters/mongo.d.ts",
+        "default": "./adapters/mongo.js"
+      }
+    },
+    "./adapters/redis": {
+      "import": {
+        "types": "./adapters/redis.d.ts",
+        "default": "./adapters/redis.js"
+      }
+    },
+    "./adapters/postgres": {
+      "import": {
+        "types": "./adapters/postgres.d.ts",
+        "default": "./adapters/postgres.js"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
-    "prepublishOnly": "rollup --config rollup.config.js",
-    "test": "mocha ./test/npm.js"
+    "prepublishOnly": "rollup --config rollup.config.js && rm -rf ./.types-tmp && tsc --emitDeclarationOnly --declaration --outDir ./.types-tmp --rootDir ./ && node ./scripts/strip-internal-dts.mjs ./.types-tmp/index.d.ts ./.types-tmp/presets.d.ts ./.types-tmp/adapters/mongo.d.ts ./.types-tmp/adapters/redis.d.ts ./.types-tmp/adapters/postgres.d.ts && cp ./.types-tmp/index.d.ts ./index.d.ts && cp ./.types-tmp/index.d.ts ./index.d.cts && cp ./.types-tmp/presets.d.ts ./presets.d.ts && cp ./.types-tmp/adapters/*.d.ts ./adapters/ && rm -rf ./.types-tmp",
+    "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:types": "tsc -p ./tsconfig.types.json",
+    "test:redis": "mocha ./test/npm-redis-redis.js",
+    "test:mongo": "mocha ./test/npm-mongo-mongo.js",
+    "test:postgres": "mocha ./test/npm-postgres.js",
+    "test:bun": "bun test ./test/jest"
   },
   "keywords": [
     "backup",
     "balanced",
     "balancer",
     "bulletproof",
+    "bun",
     "cluster",
     "email",
     "highload",
@@ -29,7 +71,9 @@
     "microservice",
     "micro-service",
     "nodemailer",
+    "postgres",
     "queue",
+    "scheduler",
     "template"
   ],
   "tags": [
@@ -37,6 +81,7 @@
     "balanced",
     "balancer",
     "bulletproof",
+    "bun",
     "cluster",
     "email",
     "highload",
@@ -49,7 +94,9 @@
     "microservice",
     "micro-service",
     "nodemailer",
+    "postgres",
     "queue",
+    "scheduler",
     "template"
   ],
   "repository": {
@@ -63,20 +110,22 @@
   "author": "dr.dimitru (https://veliovgroup.com)",
   "license": "BSD-3-Clause",
   "engines": {
-    "node": ">=14.20.0"
+    "node": ">=20.9.0"
   },
   "dependencies": {
-    "deepmerge": "^4.3.1",
-    "josk": "^5.0.0"
+    "josk": "^6.1.0"
   },
   "devDependencies": {
-    "bson": "^6.6.0",
-    "bson-ext": "^4.0.3",
-    "chai": "^5.1.0",
-    "mocha": "^10.4.0",
-    "mongodb": "^6.5.0",
-    "nodemailer": "^6.9.12",
-    "nodemailer-direct-transport": "^3.3.2",
-    "redis": "^4.6.13"
+    "@jest/globals": "^30.4.1",
+    "@types/node": "^25.9.0",
+    "chai": "^6.2.2",
+    "jest": "^30.4.2",
+    "mocha": "^11.7.5",
+    "mongodb": "^7.2.0",
+    "nodemailer": "^8.0.7",
+    "pg": "^8.21.0",
+    "redis": "^5.12.1",
+    "rollup": "^4.60.4",
+    "typescript": "^6.0.3"
   }
 }

package/presets.d.ts

@@ -0,0 +1,87 @@
+export type MailTimePresetConfig = {
+    concatEmails?: boolean | undefined;
+    concatDelay?: number | undefined;
+    concatSubject?: string | undefined;
+    retries?: number | undefined;
+    retryDelay?: number | undefined;
+    revolvingInterval?: number | undefined;
+    sendingTimeout?: number | undefined;
+    mode?: "one" | "batch" | undefined;
+    concurrency?: number | undefined;
+    onError?: ((error: unknown, email: object, details?: object) => void) | undefined;
+    josk?: object | undefined;
+};
+export type MailTimePresetName = keyof typeof PRESETS;
+/**
+ * Materialize a MailTime constructor config from a built-in preset.
+ * The named preset is deep-cloned (so the result is freely mutable) and
+ * `overrides` is deep-merged on top — overrides win for scalar keys, and
+ * nested objects like `josk` are merged so the preset's defaults compose
+ * with the caller's `adapter`, `lockOwnerId`, `onError`, etc.
+ *
+ * ```js
+ * import { MailTime, RedisQueue, mailTimePreset } from 'mail-time';
+ * const mailTime = new MailTime(mailTimePreset('otp', {
+ *   prefix: 'otp',
+ *   queue: new RedisQueue({ client }),
+ *   transports: [otpTransport],
+ *   josk: { adapter: { type: 'redis', client } },
+ * }));
+ * ```
+ *
+ * @param {MailTimePresetName} name - one of `presetNames`
+ * @param {object} [overrides] - additional MailTime constructor options
+ * @returns {object} fresh, mutable MailTime constructor options
+ * @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;
+/**
+ * Read-only map of preset name → partial MailTime config. Use
+ * `mailTimePreset(name, overrides)` to materialize a merged copy; use
+ * this object directly only when you want to introspect or compose
+ * presets manually.
+ */
+export const presets: Readonly<Record<"transactional" | "otp" | "newsletter" | "marketing" | "notifications" | "alerts", Readonly<MailTimePresetConfig>>>;
+/**
+ * @typedef {keyof typeof PRESETS} MailTimePresetName
+ */
+/**
+ * Names of every built-in preset.
+ * @type {ReadonlyArray<MailTimePresetName>}
+ */
+export const presetNames: ReadonlyArray<MailTimePresetName>;
+/**
+ * @typedef {object} MailTimePresetConfig
+ * @property {boolean} [concatEmails]
+ * @property {number} [concatDelay]
+ * @property {string} [concatSubject]
+ * @property {number} [retries]
+ * @property {number} [retryDelay]
+ * @property {number} [revolvingInterval]
+ * @property {number} [sendingTimeout]
+ * @property {'one' | 'batch'} [mode]
+ * @property {number} [concurrency]
+ * @property {(error: unknown, email: object, details?: object) => void} [onError]
+ * @property {object} [josk]
+ */
+/**
+ * Built-in MailTime presets keyed by use-case. Each value is a partial
+ * MailTime constructor options object — pass it through `mailTimePreset`
+ * (or spread directly) and supply your own `queue` / `transports` /
+ * `josk.adapter` / `prefix`. Presets only set the knobs that differ from
+ * MailTime defaults so the rest of the constructor stays in your hands.
+ *
+ * | Preset          | Shape | Best for |
+ * |-----------------|-------|----------|
+ * | `transactional` | High retries, single SMTP per instance, no concat | Receipts, password resets, account changes, welcome emails. |
+ * | `otp`           | Few retries, fast retryDelay, snappy polling, parallel SMTPs | Sign-in codes, 2FA, verification codes — stale OTPs aren't worth resending forever. |
+ * | `newsletter`    | `concatEmails: true` with 5-min fold window | Scheduled digests / weekly updates / "what's new" emails. |
+ * | `marketing`     | High concurrency, moderate retries, no concat | Promotional / campaign blasts where each letter is unique. |
+ * | `notifications` | `concatEmails: true` with 60-s fold window | App / social activity (likes, mentions) where bursts collapse into one letter. |
+ * | `alerts`        | Many retries, fast retryDelay, modest concurrency | Ops / admin alerts: monitoring, error reports, escalations. |
+ *
+ * @type {Readonly<Record<'transactional' | 'otp' | 'newsletter' | 'marketing' | 'notifications' | 'alerts', Readonly<MailTimePresetConfig>>>}
+ */
+declare const PRESETS: Readonly<Record<"transactional" | "otp" | "newsletter" | "marketing" | "notifications" | "alerts", Readonly<MailTimePresetConfig>>>;
+export {};

package/presets.js

@@ -0,0 +1,193 @@
+import { deepMerge, isPlainObject, logError } from './helpers.js';
+
+/**
+ * Default `onError` hook used by every built-in preset. Logs via the
+ * shared `logError` helper and tags the line with the MailTime instance
+ * `prefix` (or `'default'` when unset) so multi-queue deployments can
+ * tell their streams apart. Defined as a regular function so `this`
+ * resolves to the MailTime instance at call time — `this.onError(...)`
+ * in `index.js` binds the receiver. Users override by passing their own
+ * `onError` through `mailTimePreset(name, { onError })` or the
+ * constructor.
+ */
+function defaultPresetOnError(error, email, info) {
+  logError(`[${this?.prefix || 'default'}] [onError]`, { error, email, info });
+}
+
+/**
+ * @typedef {object} MailTimePresetConfig
+ * @property {boolean} [concatEmails]
+ * @property {number} [concatDelay]
+ * @property {string} [concatSubject]
+ * @property {number} [retries]
+ * @property {number} [retryDelay]
+ * @property {number} [revolvingInterval]
+ * @property {number} [sendingTimeout]
+ * @property {'one' | 'batch'} [mode]
+ * @property {number} [concurrency]
+ * @property {(error: unknown, email: object, details?: object) => void} [onError]
+ * @property {object} [josk]
+ */
+
+/**
+ * Built-in MailTime presets keyed by use-case. Each value is a partial
+ * MailTime constructor options object — pass it through `mailTimePreset`
+ * (or spread directly) and supply your own `queue` / `transports` /
+ * `josk.adapter` / `prefix`. Presets only set the knobs that differ from
+ * MailTime defaults so the rest of the constructor stays in your hands.
+ *
+ * | Preset          | Shape | Best for |
+ * |-----------------|-------|----------|
+ * | `transactional` | High retries, single SMTP per instance, no concat | Receipts, password resets, account changes, welcome emails. |
+ * | `otp`           | Few retries, fast retryDelay, snappy polling, parallel SMTPs | Sign-in codes, 2FA, verification codes — stale OTPs aren't worth resending forever. |
+ * | `newsletter`    | `concatEmails: true` with 5-min fold window | Scheduled digests / weekly updates / "what's new" emails. |
+ * | `marketing`     | High concurrency, moderate retries, no concat | Promotional / campaign blasts where each letter is unique. |
+ * | `notifications` | `concatEmails: true` with 60-s fold window | App / social activity (likes, mentions) where bursts collapse into one letter. |
+ * | `alerts`        | Many retries, fast retryDelay, modest concurrency | Ops / admin alerts: monitoring, error reports, escalations. |
+ *
+ * @type {Readonly<Record<'transactional' | 'otp' | 'newsletter' | 'marketing' | 'notifications' | 'alerts', Readonly<MailTimePresetConfig>>>}
+ */
+// Every preset pins `mode: 'batch'` explicitly. `'one'` would trade per-tick
+// throughput for cluster-wide fairness across pods on the same `prefix`, but:
+// - urgent classes (`otp`, `alerts`, `transactional`) want all due rows claimed
+//   immediately, not spread one-per-tick;
+// - bulk classes (`newsletter`, `marketing`, `notifications`) are bursty and
+//   need fast drains during the send window;
+// - multiple `server` pods on the same `prefix` is already an anti-pattern in
+//   this library (one JoSk lease per prefix), so the fairness payoff is moot.
+// If you do want `'one'`, pass it via `mailTimePreset(name, { mode: 'one' })`.
+const PRESETS = Object.freeze({
+  transactional: Object.freeze({
+    concatEmails: false,
+    retries: 30,
+    retryDelay: 10_000,
+    mode: 'batch',
+    concurrency: 1,
+    onError: defaultPresetOnError,
+    josk: Object.freeze({
+      zombieTime: 120_000,
+    }),
+  }),
+  otp: Object.freeze({
+    concatEmails: false,
+    retries: 5,
+    retryDelay: 2000,
+    revolvingInterval: 1024,
+    sendingTimeout: 60_000,
+    mode: 'batch',
+    concurrency: 4,
+    onError: defaultPresetOnError,
+    josk: Object.freeze({
+      minRevolvingDelay: 256,
+      maxRevolvingDelay: 1024,
+      zombieTime: 60_000,
+    }),
+  }),
+  newsletter: Object.freeze({
+    concatEmails: true,
+    concatDelay: 5 * 60_000,
+    concatSubject: 'Your updates',
+    retries: 5,
+    retryDelay: 60_000,
+    sendingTimeout: 600_000,
+    mode: 'batch',
+    concurrency: 2,
+    onError: defaultPresetOnError,
+    josk: Object.freeze({
+      zombieTime: 300_000,
+    }),
+  }),
+  marketing: Object.freeze({
+    concatEmails: false,
+    retries: 10,
+    retryDelay: 30_000,
+    mode: 'batch',
+    concurrency: 5,
+    onError: defaultPresetOnError,
+    josk: Object.freeze({
+      zombieTime: 180_000,
+    }),
+  }),
+  notifications: Object.freeze({
+    concatEmails: true,
+    concatDelay: 60_000,
+    concatSubject: 'New activity',
+    retries: 8,
+    retryDelay: 30_000,
+    mode: 'batch',
+    concurrency: 3,
+    onError: defaultPresetOnError,
+    josk: Object.freeze({
+      zombieTime: 180_000,
+    }),
+  }),
+  alerts: Object.freeze({
+    concatEmails: false,
+    retries: 20,
+    retryDelay: 5000,
+    revolvingInterval: 1024,
+    sendingTimeout: 60_000,
+    mode: 'batch',
+    concurrency: 2,
+    onError: defaultPresetOnError,
+    josk: Object.freeze({
+      minRevolvingDelay: 256,
+      maxRevolvingDelay: 1024,
+      zombieTime: 60_000,
+    }),
+  }),
+});
+
+/**
+ * Read-only map of preset name → partial MailTime config. Use
+ * `mailTimePreset(name, overrides)` to materialize a merged copy; use
+ * this object directly only when you want to introspect or compose
+ * presets manually.
+ */
+const presets = PRESETS;
+
+/**
+ * @typedef {keyof typeof PRESETS} MailTimePresetName
+ */
+
+/**
+ * Names of every built-in preset.
+ * @type {ReadonlyArray<MailTimePresetName>}
+ */
+const presetNames = Object.freeze(/** @type {MailTimePresetName[]} */ (Object.keys(PRESETS)));
+
+/**
+ * Materialize a MailTime constructor config from a built-in preset.
+ * The named preset is deep-cloned (so the result is freely mutable) and
+ * `overrides` is deep-merged on top — overrides win for scalar keys, and
+ * nested objects like `josk` are merged so the preset's defaults compose
+ * with the caller's `adapter`, `lockOwnerId`, `onError`, etc.
+ *
+ * ```js
+ * import { MailTime, RedisQueue, mailTimePreset } from 'mail-time';
+ * const mailTime = new MailTime(mailTimePreset('otp', {
+ *   prefix: 'otp',
+ *   queue: new RedisQueue({ client }),
+ *   transports: [otpTransport],
+ *   josk: { adapter: { type: 'redis', client } },
+ * }));
+ * ```
+ *
+ * @param {MailTimePresetName} name - one of `presetNames`
+ * @param {object} [overrides] - additional MailTime constructor options
+ * @returns {object} fresh, mutable MailTime constructor options
+ * @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)) {
+    throw new Error(`[mail-time] [mailTimePreset] unknown preset "${name}". Available: ${presetNames.join(', ')}`);
+  }
+  if (overrides !== void 0 && !isPlainObject(overrides)) {
+    throw new TypeError('[mail-time] [mailTimePreset] {overrides} must be a plain object when provided');
+  }
+  const cloned = deepMerge({}, PRESETS[name]);
+  return overrides ? deepMerge(cloned, overrides) : cloned;
+};
+
+export { mailTimePreset, presets, presetNames };

package/adapters/blank-example.js

@@ -1,230 +0,0 @@
-import { logError } from '../helpers.js';
-
-/** Class representing Example Queue for MailTime */
-class BlankQueue {
-  /**
-   * Create a BlankQueue instance
-   * @param {object} opts - configuration object
-   * @param {object} opts.requiredOption - Required option description
-   * @param {string} [opts.prefix] - Optional prefix for scope isolation; use when creating multiple MailTime instances within the single application
-   */
-  constructor (opts) {
-    this.name = 'queue-name';
-    if (!opts || typeof opts !== 'object' || opts === null) {
-      throw new TypeError('[mail-time] Configuration object must be passed into BlankQueue constructor');
-    }
-
-    if (!opts.requiredOption) {
-      throw new Error('[mail-time] [BlankQueue] required {requiredOption} option is missing');
-    }
-
-    this.prefix = (typeof opts.prefix === 'string') ? opts.prefix : 'default';
-    this.uniqueName = `mailtime:${this.prefix}`;
-    this.requiredOption = opts.requiredOption;
-
-    // Stored JSON structure:
-    // uuid        {string}
-    // to          {string|[string]}
-    // tries       {number}  - qty of send attempts
-    // sendAt      {number}  - When letter should be sent
-    // isSent      {boolean} - Email status
-    // isCancelled {boolean} - `true` if email was cancelled before it was sent
-    // isFailed    {boolean} - `true` if email has failed to send
-    // template    {string}  - Template for this email
-    // transport   {number}  - Last used transport
-    // concatSubject {string|boolean} - Email concatenation subject
-    // ---
-    // mailOptions         {[object]}  - Array of nodeMailer's `mailOptions`
-    // mailOptions.to      {string|[string]} - [REQUIRED]
-    // mailOptions.from    {string}
-    // mailOptions.text    {string|boolean}
-    // mailOptions.html    {string}
-    // mailOptions.subject {string}
-    // mailOptions.Other nodeMailer `sendMail` options...
-  }
-
-  /**
-   * @async
-   * @memberOf BlankQueue
-   * @name ping
-   * @description Check connection to Storage
-   * @returns {Promise<object>}
-   */
-  async ping() {
-    // LEAVE THIS if BLOCK UNCHANGED
-    if (!this.mailTimeInstance) {
-      return {
-        status: 'Service Unavailable',
-        code: 503,
-        statusCode: 503,
-        error: new Error('MailTime instance not yet assigned to {mailTimeInstance} of Queue Adapter context'),
-      };
-    }
-
-    try {
-      const ping = await this.requiredOption.ping();
-      if (ping === 'PONG') {
-        return {
-          status: 'OK',
-          code: 200,
-          statusCode: 200,
-        };
-      }
-
-      throw new Error(`Unexpected response from Storage#ping received: ${ping}`);
-    } catch (pingError) {
-      return {
-        status: 'Internal Server Error',
-        code: 500,
-        statusCode: 500,
-        error: pingError
-      };
-    }
-  }
-
-  /**
-   * @memberOf BlankQueue
-   * @name iterate
-   * @description iterate over queued emails passing to `mailTimeInstance.___send` method
-   * @returns {void 0}
-   */
-  async iterate() {
-    // GET EMAILS WITHIN this.uniqueName SCOPE!
-    // AND ONLY WHERE sendAt <= now
-    // RUN ONE BY ONE VIA this.mailTimeInstance.___send() METHOD
-    const cursorWithEmails = this.requiredOption.getEmails({
-      scope: this.uniqueName,
-      isSent: false,
-      isFailed: false,
-      isCancelled: false,
-      sendAt: {
-        $lte: Date.now() // Number (timestamp)
-      }
-    });
-
-    for await (const emailObj of cursorWithEmails) {
-      await this.mailTimeInstance.___send(emailObj);
-    }
-  }
-
-  /**
-   * @async
-   * @memberOf BlankQueue
-   * @name getPendingTo
-   * @description get queued email by `to` field (addressee)
-   * @param to {string} - email address
-   * @param sendAt {number} - timestamp
-   * @returns {Promise<object|null>}
-   */
-  async getPendingTo(to, sendAt) {
-    if (typeof to !== 'string' || typeof sendAt !== 'number') {
-      return null;
-    }
-
-    const email = await this.requiredOption.get({
-      to: to,
-      isSent: false,
-      isFailed: false,
-      isCancelled: false,
-      sendAt: {
-        $lte: sendAt // Number (timestamp)
-      }
-    });
-
-    if (!email || email.isSent === true || email.isCancelled === true || email.isFailed === true) {
-      return null;
-    }
-
-    return email;
-  }
-
-  /**
-   * @async
-   * @memberOf BlankQueue
-   * @name push
-   * @description push email to the queue/storage
-   * @param email {object} - email's object
-   * @returns {Promise<void 0>}
-   */
-  async push(email) {
-    if (typeof email !== 'object') {
-      return;
-    }
-
-    if (email.sendAt instanceof Date) {
-      email.sendAt = +email.sendAt;
-    }
-
-    await this.requiredOption.save(email);
-  }
-
-  /**
-   * @async
-   * @memberOf BlankQueue
-   * @name cancel
-   * @description cancel scheduled email
-   * @param uuid {string} - email's uuid
-   * @returns {Promise<boolean>} returns `true` if cancelled or `false` if not found, was sent, or was cancelled previously
-   */
-  async cancel(uuid) {
-    if (typeof uuid !== 'string') {
-      return false;
-    }
-
-    const email = JSON.parse(await this.requiredOption.get({
-      uuid: uuid
-    }));
-
-    if (!email || email.isSent === true || email.isCancelled === true) {
-      return false;
-    }
-
-    if (!this.mailTimeInstance.keepHistory) {
-      return await this.remove(email);
-    }
-
-    return await this.update(email, {
-      isCancelled: true,
-    });
-  }
-
-  /**
-   * @async
-   * @memberOf BlankQueue
-   * @name remove
-   * @description remove email from queue
-   * @param email {object} - email's object
-   * @returns {Promise<boolean>} returns `true` if removed or `false` if not found
-   */
-  async remove(email) {
-    if (typeof email !== 'object' || typeof email.uuid !== 'string') {
-      return false;
-    }
-
-    return await this.requiredOption.remove({
-      uuid: email.uuid
-    });
-  }
-
-  /**
-   * @async
-   * @memberOf BlankQueue
-   * @name update
-   * @description remove email from queue
-   * @param email {object} - email's object
-   * @param updateObj {object} - fields with new values to update
-   * @returns {Promise<boolean>} returns `true` if updated or `false` if not found or no changes was made
-   */
-  async update(email, updateObj) {
-    if (typeof email !== 'object' || typeof email.uuid !== 'string' || typeof updateObj !== 'object') {
-      return false;
-    }
-
-    const updatedEmail = { ...email, ...updateObj };
-    return await this.requiredOption.update({
-      uuid: email.uuid
-    }, updatedEmail);
-  }
-}
-
-export { BlankQueue };