mail-time 4.0.0 → 5.0.0

package/index.d.cts

@@ -4,6 +4,7 @@ export type MailTimePingResult = {
     status: string;
     code: number;
     statusCode: number;
+    paused?: boolean;
     error?: unknown;
 };
 export type MailTimeStorageClient = {
@@ -34,6 +35,7 @@ export type MailTimeJoSkOptions = {
     debug?: boolean;
     autoClear?: boolean;
     zombieTime?: number;
+    lockLeaseTime?: number;
     minRevolvingDelay?: number;
     maxRevolvingDelay?: number;
     execute?: "batch" | "one";
@@ -43,6 +45,14 @@ export type MailTimeJoSkOptions = {
     onError?: (title: string, details: object) => void;
     onExecuted?: (uid: string, details: object) => void;
 };
+export type MailTimeScheduler = {
+    [key: string]: any;
+    ping: () => Promise<MailTimePingResult>;
+    setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>;
+    destroy: () => boolean;
+    pause: (timerId?: string) => boolean;
+    resume: (timerId?: string) => boolean;
+};
 export type MailTimeTask = {
     uuid: string;
     to?: string | string[];
@@ -94,13 +104,18 @@ export type MailTimeMailOptions = {
 export type MailTimeConcatEmailsOptions = {
     subject?: string;
 };
+export type MailTimeFromDetails = {
+    index: number;
+    from: string | undefined;
+};
 export type MailTimeOptions = {
     queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue;
     type?: "server" | "client";
-    from?: string | ((transport: MailTimeTransport) => string);
+    from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string);
     transports?: MailTimeTransport[];
     strategy?: "backup" | "balancer";
     failsToNext?: number;
+    shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean;
     retries?: number;
     maxTries?: number;
     retryDelay?: number;
@@ -115,6 +130,10 @@ export type MailTimeOptions = {
     mode?: "one" | "batch";
     concurrency?: number;
     sendingTimeout?: number;
+    renewClaim?: boolean | number;
+    maxRenewals?: number;
+    strictPayload?: boolean;
+    allowedMailFields?: string[];
     verifyTransports?: boolean;
     template?: string;
     prefix?: string;
@@ -130,7 +149,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
@@ -145,7 +164,10 @@ export type MailTimeOptions = {
  * @typedef {{ [key: string]: any, type?: 'mongo' | 'redis' | 'postgres', client?: MailTimeStorageClient, db?: MailTimeMongoDb, prefix?: string, resetOnInit?: boolean, useHashTags?: boolean }} MailTimeJoSkAdapterOptions
  */
 /**
- * @typedef {{ [key: string]: any, adapter: MailTimeJoSkAdapterOptions | object, debug?: boolean, autoClear?: boolean, zombieTime?: number, minRevolvingDelay?: number, maxRevolvingDelay?: number, execute?: 'batch' | 'one', concurrency?: number, lockOwnerId?: string, resetOnInit?: boolean, onError?: (title: string, details: object) => void, onExecuted?: (uid: string, details: object) => void }} MailTimeJoSkOptions
+ * @typedef {{ [key: string]: any, adapter: MailTimeJoSkAdapterOptions | object, debug?: boolean, autoClear?: boolean, zombieTime?: number, lockLeaseTime?: number, minRevolvingDelay?: number, maxRevolvingDelay?: number, execute?: 'batch' | 'one', concurrency?: number, lockOwnerId?: string, resetOnInit?: boolean, onError?: (title: string, details: object) => void, onExecuted?: (uid: string, details: object) => void }} MailTimeJoSkOptions
+ */
+/**
+ * @typedef {{ [key: string]: any, ping: () => Promise<MailTimePingResult>, setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>, destroy: () => boolean, pause: (timerId?: string) => boolean, resume: (timerId?: string) => boolean }} MailTimeScheduler
  */
 /**
  * @typedef {{ uuid: string, to?: string | string[], tries: number, sendAt: number, isSent: boolean, isCancelled: boolean, isFailed: boolean, isSending?: boolean, sendingAt?: number, template?: string | false, transport: number, concatSubject?: string | false, mailOptions: MailTimeMailOptions[] }} MailTimeTask
@@ -166,12 +188,28 @@ export type MailTimeOptions = {
  * @typedef {{ subject?: string }} MailTimeConcatEmailsOptions
  */
 /**
- * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, onError?: (error: unknown, email: MailTimeTask | null, details?: object) => void, onSent?: (email: MailTimeTask, details?: object) => void }} MailTimeOptions
+ * @typedef {{ index: number, from: string | undefined }} MailTimeFromDetails
+ */
+/**
+ * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, renewClaim?: boolean | number, maxRenewals?: number, strictPayload?: boolean, allowedMailFields?: string[], verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, onError?: (error: unknown, email: MailTimeTask | null, details?: object) => void, onSent?: (email: MailTimeTask, details?: object) => void }} MailTimeOptions
  */
 /** Class of MailTime */
 export class MailTime {
     static set Template(newVal: string);
     static get Template(): string;
+    /**
+     * @static
+     * @memberOf MailTime
+     * @name transportFrom
+     * @description Best-effort sender address for a transport. `nodemailer.createTransport()`
+     * only exposes `.options` for *plain-object* configs — for a class-instance transporter
+     * (anything with its own `.send()`) nodemailer's internal `Mail.options` is always `{}`,
+     * so `transport.options.from` silently reads `undefined`. This walks the places the
+     * address can actually live.
+     * @param {MailTimeTransport} transport
+     * @returns {string | undefined}
+     */
+    static transportFrom(transport: MailTimeTransport): string | undefined;
     /**
      * Create a MailTime instance
      * @param {MailTimeOptions} opts - configuration object
@@ -191,12 +229,17 @@ export class MailTime {
     mode: "one" | "batch";
     concurrency: number;
     sendingTimeout: number;
+    renewClaim: number;
+    maxRenewals: number;
+    shouldFailOver: ((error: unknown, info: object | undefined, email: MailTimeTask) => boolean) | null;
+    strictPayload: boolean;
+    allowedMailFields: Set<string>;
     failsToNext: number;
     strategy: "backup" | "balancer";
     transports: MailTimeTransport[];
     transport: number;
     verifyTransports: boolean;
-    from: boolean | ((transport: MailTimeTransport) => string);
+    from: boolean | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string);
     /** @type {string} */
     concatSubject: string;
     concatEmails: boolean;
@@ -208,6 +251,7 @@ export class MailTime {
         debug?: boolean;
         autoClear?: boolean;
         zombieTime?: number;
+        lockLeaseTime?: number;
         minRevolvingDelay?: number;
         maxRevolvingDelay?: number;
         execute?: "batch" | "one";
@@ -217,7 +261,8 @@ export class MailTime {
         onError?: (title: string, details: object) => void;
         onExecuted?: (uid: string, details: object) => void;
     } | undefined;
-    scheduler: JoSk | undefined;
+    /** @type {MailTimeScheduler | undefined} */
+    scheduler: MailTimeScheduler | undefined;
     /**
      * @async
      * @memberOf MailTime
@@ -238,7 +283,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 +298,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
@@ -270,7 +336,7 @@ export class MailTime {
      * @returns {Promise<string>} uuid of the email
      * @throws {Error}
      */
-    sendMail(opts?: MailTimeMailOptions): Promise<string>;
+    sendMail(opts: MailTimeMailOptions): Promise<string>;
     /**
      * @async
      * @memberOf MailTime
@@ -296,5 +362,4 @@ import { PostgresQueue } from './adapters/postgres.js';
 import { mailTimePreset } from './presets.js';
 import { presets } from './presets.js';
 import { presetNames } from './presets.js';
-import { JoSk } from 'josk';
 export { MongoQueue, RedisQueue, PostgresQueue, mailTimePreset, presets, presetNames };

package/index.d.ts

@@ -4,6 +4,7 @@ export type MailTimePingResult = {
     status: string;
     code: number;
     statusCode: number;
+    paused?: boolean;
     error?: unknown;
 };
 export type MailTimeStorageClient = {
@@ -34,6 +35,7 @@ export type MailTimeJoSkOptions = {
     debug?: boolean;
     autoClear?: boolean;
     zombieTime?: number;
+    lockLeaseTime?: number;
     minRevolvingDelay?: number;
     maxRevolvingDelay?: number;
     execute?: "batch" | "one";
@@ -43,6 +45,14 @@ export type MailTimeJoSkOptions = {
     onError?: (title: string, details: object) => void;
     onExecuted?: (uid: string, details: object) => void;
 };
+export type MailTimeScheduler = {
+    [key: string]: any;
+    ping: () => Promise<MailTimePingResult>;
+    setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>;
+    destroy: () => boolean;
+    pause: (timerId?: string) => boolean;
+    resume: (timerId?: string) => boolean;
+};
 export type MailTimeTask = {
     uuid: string;
     to?: string | string[];
@@ -94,13 +104,18 @@ export type MailTimeMailOptions = {
 export type MailTimeConcatEmailsOptions = {
     subject?: string;
 };
+export type MailTimeFromDetails = {
+    index: number;
+    from: string | undefined;
+};
 export type MailTimeOptions = {
     queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue;
     type?: "server" | "client";
-    from?: string | ((transport: MailTimeTransport) => string);
+    from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string);
     transports?: MailTimeTransport[];
     strategy?: "backup" | "balancer";
     failsToNext?: number;
+    shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean;
     retries?: number;
     maxTries?: number;
     retryDelay?: number;
@@ -115,6 +130,10 @@ export type MailTimeOptions = {
     mode?: "one" | "batch";
     concurrency?: number;
     sendingTimeout?: number;
+    renewClaim?: boolean | number;
+    maxRenewals?: number;
+    strictPayload?: boolean;
+    allowedMailFields?: string[];
     verifyTransports?: boolean;
     template?: string;
     prefix?: string;
@@ -130,7 +149,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
@@ -145,7 +164,10 @@ export type MailTimeOptions = {
  * @typedef {{ [key: string]: any, type?: 'mongo' | 'redis' | 'postgres', client?: MailTimeStorageClient, db?: MailTimeMongoDb, prefix?: string, resetOnInit?: boolean, useHashTags?: boolean }} MailTimeJoSkAdapterOptions
  */
 /**
- * @typedef {{ [key: string]: any, adapter: MailTimeJoSkAdapterOptions | object, debug?: boolean, autoClear?: boolean, zombieTime?: number, minRevolvingDelay?: number, maxRevolvingDelay?: number, execute?: 'batch' | 'one', concurrency?: number, lockOwnerId?: string, resetOnInit?: boolean, onError?: (title: string, details: object) => void, onExecuted?: (uid: string, details: object) => void }} MailTimeJoSkOptions
+ * @typedef {{ [key: string]: any, adapter: MailTimeJoSkAdapterOptions | object, debug?: boolean, autoClear?: boolean, zombieTime?: number, lockLeaseTime?: number, minRevolvingDelay?: number, maxRevolvingDelay?: number, execute?: 'batch' | 'one', concurrency?: number, lockOwnerId?: string, resetOnInit?: boolean, onError?: (title: string, details: object) => void, onExecuted?: (uid: string, details: object) => void }} MailTimeJoSkOptions
+ */
+/**
+ * @typedef {{ [key: string]: any, ping: () => Promise<MailTimePingResult>, setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>, destroy: () => boolean, pause: (timerId?: string) => boolean, resume: (timerId?: string) => boolean }} MailTimeScheduler
  */
 /**
  * @typedef {{ uuid: string, to?: string | string[], tries: number, sendAt: number, isSent: boolean, isCancelled: boolean, isFailed: boolean, isSending?: boolean, sendingAt?: number, template?: string | false, transport: number, concatSubject?: string | false, mailOptions: MailTimeMailOptions[] }} MailTimeTask
@@ -166,12 +188,28 @@ export type MailTimeOptions = {
  * @typedef {{ subject?: string }} MailTimeConcatEmailsOptions
  */
 /**
- * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, onError?: (error: unknown, email: MailTimeTask | null, details?: object) => void, onSent?: (email: MailTimeTask, details?: object) => void }} MailTimeOptions
+ * @typedef {{ index: number, from: string | undefined }} MailTimeFromDetails
+ */
+/**
+ * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, renewClaim?: boolean | number, maxRenewals?: number, strictPayload?: boolean, allowedMailFields?: string[], verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, onError?: (error: unknown, email: MailTimeTask | null, details?: object) => void, onSent?: (email: MailTimeTask, details?: object) => void }} MailTimeOptions
  */
 /** Class of MailTime */
 export class MailTime {
     static set Template(newVal: string);
     static get Template(): string;
+    /**
+     * @static
+     * @memberOf MailTime
+     * @name transportFrom
+     * @description Best-effort sender address for a transport. `nodemailer.createTransport()`
+     * only exposes `.options` for *plain-object* configs — for a class-instance transporter
+     * (anything with its own `.send()`) nodemailer's internal `Mail.options` is always `{}`,
+     * so `transport.options.from` silently reads `undefined`. This walks the places the
+     * address can actually live.
+     * @param {MailTimeTransport} transport
+     * @returns {string | undefined}
+     */
+    static transportFrom(transport: MailTimeTransport): string | undefined;
     /**
      * Create a MailTime instance
      * @param {MailTimeOptions} opts - configuration object
@@ -191,12 +229,17 @@ export class MailTime {
     mode: "one" | "batch";
     concurrency: number;
     sendingTimeout: number;
+    renewClaim: number;
+    maxRenewals: number;
+    shouldFailOver: ((error: unknown, info: object | undefined, email: MailTimeTask) => boolean) | null;
+    strictPayload: boolean;
+    allowedMailFields: Set<string>;
     failsToNext: number;
     strategy: "backup" | "balancer";
     transports: MailTimeTransport[];
     transport: number;
     verifyTransports: boolean;
-    from: boolean | ((transport: MailTimeTransport) => string);
+    from: boolean | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string);
     /** @type {string} */
     concatSubject: string;
     concatEmails: boolean;
@@ -208,6 +251,7 @@ export class MailTime {
         debug?: boolean;
         autoClear?: boolean;
         zombieTime?: number;
+        lockLeaseTime?: number;
         minRevolvingDelay?: number;
         maxRevolvingDelay?: number;
         execute?: "batch" | "one";
@@ -217,7 +261,8 @@ export class MailTime {
         onError?: (title: string, details: object) => void;
         onExecuted?: (uid: string, details: object) => void;
     } | undefined;
-    scheduler: JoSk | undefined;
+    /** @type {MailTimeScheduler | undefined} */
+    scheduler: MailTimeScheduler | undefined;
     /**
      * @async
      * @memberOf MailTime
@@ -238,7 +283,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 +298,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
@@ -270,7 +336,7 @@ export class MailTime {
      * @returns {Promise<string>} uuid of the email
      * @throws {Error}
      */
-    sendMail(opts?: MailTimeMailOptions): Promise<string>;
+    sendMail(opts: MailTimeMailOptions): Promise<string>;
     /**
      * @async
      * @memberOf MailTime
@@ -296,5 +362,4 @@ import { PostgresQueue } from './adapters/postgres.js';
 import { mailTimePreset } from './presets.js';
 import { presets } from './presets.js';
 import { presetNames } from './presets.js';
-import { JoSk } from 'josk';
 export { MongoQueue, RedisQueue, PostgresQueue, mailTimePreset, presets, presetNames };