mail-time 4.1.0 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +76 -19
  2. package/adapters/redis.d.ts +19 -1
  3. package/adapters/redis.js +337 -8
  4. package/helpers.js +19 -0
  5. package/index.cjs +778 -127
  6. package/index.d.cts +50 -7
  7. package/index.d.ts +50 -7
  8. package/index.js +423 -118
  9. package/package.json +21 -4
  10. package/presets.js +2 -2
  11. package/scripts/migrate-redis-queue-to-cluster.mjs +108 -0
package/index.d.cts CHANGED
@@ -35,6 +35,7 @@ export type MailTimeJoSkOptions = {
35
35
  debug?: boolean;
36
36
  autoClear?: boolean;
37
37
  zombieTime?: number;
38
+ lockLeaseTime?: number;
38
39
  minRevolvingDelay?: number;
39
40
  maxRevolvingDelay?: number;
40
41
  execute?: "batch" | "one";
@@ -44,6 +45,14 @@ export type MailTimeJoSkOptions = {
44
45
  onError?: (title: string, details: object) => void;
45
46
  onExecuted?: (uid: string, details: object) => void;
46
47
  };
48
+ export type MailTimeScheduler = {
49
+ [key: string]: any;
50
+ ping: () => Promise<MailTimePingResult>;
51
+ setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>;
52
+ destroy: () => boolean;
53
+ pause: (timerId?: string) => boolean;
54
+ resume: (timerId?: string) => boolean;
55
+ };
47
56
  export type MailTimeTask = {
48
57
  uuid: string;
49
58
  to?: string | string[];
@@ -95,13 +104,18 @@ export type MailTimeMailOptions = {
95
104
  export type MailTimeConcatEmailsOptions = {
96
105
  subject?: string;
97
106
  };
107
+ export type MailTimeFromDetails = {
108
+ index: number;
109
+ from: string | undefined;
110
+ };
98
111
  export type MailTimeOptions = {
99
112
  queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue;
100
113
  type?: "server" | "client";
101
- from?: string | ((transport: MailTimeTransport) => string);
114
+ from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string);
102
115
  transports?: MailTimeTransport[];
103
116
  strategy?: "backup" | "balancer";
104
117
  failsToNext?: number;
118
+ shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean;
105
119
  retries?: number;
106
120
  maxTries?: number;
107
121
  retryDelay?: number;
@@ -116,6 +130,10 @@ export type MailTimeOptions = {
116
130
  mode?: "one" | "batch";
117
131
  concurrency?: number;
118
132
  sendingTimeout?: number;
133
+ renewClaim?: boolean | number;
134
+ maxRenewals?: number;
135
+ strictPayload?: boolean;
136
+ allowedMailFields?: string[];
119
137
  verifyTransports?: boolean;
120
138
  template?: string;
121
139
  prefix?: string;
@@ -146,7 +164,10 @@ export type MailTimeOptions = {
146
164
  * @typedef {{ [key: string]: any, type?: 'mongo' | 'redis' | 'postgres', client?: MailTimeStorageClient, db?: MailTimeMongoDb, prefix?: string, resetOnInit?: boolean, useHashTags?: boolean }} MailTimeJoSkAdapterOptions
147
165
  */
148
166
  /**
149
- * @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
167
+ * @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
168
+ */
169
+ /**
170
+ * @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
150
171
  */
151
172
  /**
152
173
  * @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
@@ -167,12 +188,28 @@ export type MailTimeOptions = {
167
188
  * @typedef {{ subject?: string }} MailTimeConcatEmailsOptions
168
189
  */
169
190
  /**
170
- * @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
191
+ * @typedef {{ index: number, from: string | undefined }} MailTimeFromDetails
192
+ */
193
+ /**
194
+ * @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
171
195
  */
172
196
  /** Class of MailTime */
173
197
  export class MailTime {
174
198
  static set Template(newVal: string);
175
199
  static get Template(): string;
200
+ /**
201
+ * @static
202
+ * @memberOf MailTime
203
+ * @name transportFrom
204
+ * @description Best-effort sender address for a transport. `nodemailer.createTransport()`
205
+ * only exposes `.options` for *plain-object* configs — for a class-instance transporter
206
+ * (anything with its own `.send()`) nodemailer's internal `Mail.options` is always `{}`,
207
+ * so `transport.options.from` silently reads `undefined`. This walks the places the
208
+ * address can actually live.
209
+ * @param {MailTimeTransport} transport
210
+ * @returns {string | undefined}
211
+ */
212
+ static transportFrom(transport: MailTimeTransport): string | undefined;
176
213
  /**
177
214
  * Create a MailTime instance
178
215
  * @param {MailTimeOptions} opts - configuration object
@@ -192,12 +229,17 @@ export class MailTime {
192
229
  mode: "one" | "batch";
193
230
  concurrency: number;
194
231
  sendingTimeout: number;
232
+ renewClaim: number;
233
+ maxRenewals: number;
234
+ shouldFailOver: ((error: unknown, info: object | undefined, email: MailTimeTask) => boolean) | null;
235
+ strictPayload: boolean;
236
+ allowedMailFields: Set<string>;
195
237
  failsToNext: number;
196
238
  strategy: "backup" | "balancer";
197
239
  transports: MailTimeTransport[];
198
240
  transport: number;
199
241
  verifyTransports: boolean;
200
- from: boolean | ((transport: MailTimeTransport) => string);
242
+ from: boolean | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string);
201
243
  /** @type {string} */
202
244
  concatSubject: string;
203
245
  concatEmails: boolean;
@@ -209,6 +251,7 @@ export class MailTime {
209
251
  debug?: boolean;
210
252
  autoClear?: boolean;
211
253
  zombieTime?: number;
254
+ lockLeaseTime?: number;
212
255
  minRevolvingDelay?: number;
213
256
  maxRevolvingDelay?: number;
214
257
  execute?: "batch" | "one";
@@ -218,7 +261,8 @@ export class MailTime {
218
261
  onError?: (title: string, details: object) => void;
219
262
  onExecuted?: (uid: string, details: object) => void;
220
263
  } | undefined;
221
- scheduler: JoSk | undefined;
264
+ /** @type {MailTimeScheduler | undefined} */
265
+ scheduler: MailTimeScheduler | undefined;
222
266
  /**
223
267
  * @async
224
268
  * @memberOf MailTime
@@ -292,7 +336,7 @@ export class MailTime {
292
336
  * @returns {Promise<string>} uuid of the email
293
337
  * @throws {Error}
294
338
  */
295
- sendMail(opts?: MailTimeMailOptions): Promise<string>;
339
+ sendMail(opts: MailTimeMailOptions): Promise<string>;
296
340
  /**
297
341
  * @async
298
342
  * @memberOf MailTime
@@ -318,5 +362,4 @@ import { PostgresQueue } from './adapters/postgres.js';
318
362
  import { mailTimePreset } from './presets.js';
319
363
  import { presets } from './presets.js';
320
364
  import { presetNames } from './presets.js';
321
- import { JoSk } from 'josk';
322
365
  export { MongoQueue, RedisQueue, PostgresQueue, mailTimePreset, presets, presetNames };
package/index.d.ts CHANGED
@@ -35,6 +35,7 @@ export type MailTimeJoSkOptions = {
35
35
  debug?: boolean;
36
36
  autoClear?: boolean;
37
37
  zombieTime?: number;
38
+ lockLeaseTime?: number;
38
39
  minRevolvingDelay?: number;
39
40
  maxRevolvingDelay?: number;
40
41
  execute?: "batch" | "one";
@@ -44,6 +45,14 @@ export type MailTimeJoSkOptions = {
44
45
  onError?: (title: string, details: object) => void;
45
46
  onExecuted?: (uid: string, details: object) => void;
46
47
  };
48
+ export type MailTimeScheduler = {
49
+ [key: string]: any;
50
+ ping: () => Promise<MailTimePingResult>;
51
+ setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>;
52
+ destroy: () => boolean;
53
+ pause: (timerId?: string) => boolean;
54
+ resume: (timerId?: string) => boolean;
55
+ };
47
56
  export type MailTimeTask = {
48
57
  uuid: string;
49
58
  to?: string | string[];
@@ -95,13 +104,18 @@ export type MailTimeMailOptions = {
95
104
  export type MailTimeConcatEmailsOptions = {
96
105
  subject?: string;
97
106
  };
107
+ export type MailTimeFromDetails = {
108
+ index: number;
109
+ from: string | undefined;
110
+ };
98
111
  export type MailTimeOptions = {
99
112
  queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue;
100
113
  type?: "server" | "client";
101
- from?: string | ((transport: MailTimeTransport) => string);
114
+ from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string);
102
115
  transports?: MailTimeTransport[];
103
116
  strategy?: "backup" | "balancer";
104
117
  failsToNext?: number;
118
+ shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean;
105
119
  retries?: number;
106
120
  maxTries?: number;
107
121
  retryDelay?: number;
@@ -116,6 +130,10 @@ export type MailTimeOptions = {
116
130
  mode?: "one" | "batch";
117
131
  concurrency?: number;
118
132
  sendingTimeout?: number;
133
+ renewClaim?: boolean | number;
134
+ maxRenewals?: number;
135
+ strictPayload?: boolean;
136
+ allowedMailFields?: string[];
119
137
  verifyTransports?: boolean;
120
138
  template?: string;
121
139
  prefix?: string;
@@ -146,7 +164,10 @@ export type MailTimeOptions = {
146
164
  * @typedef {{ [key: string]: any, type?: 'mongo' | 'redis' | 'postgres', client?: MailTimeStorageClient, db?: MailTimeMongoDb, prefix?: string, resetOnInit?: boolean, useHashTags?: boolean }} MailTimeJoSkAdapterOptions
147
165
  */
148
166
  /**
149
- * @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
167
+ * @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
168
+ */
169
+ /**
170
+ * @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
150
171
  */
151
172
  /**
152
173
  * @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
@@ -167,12 +188,28 @@ export type MailTimeOptions = {
167
188
  * @typedef {{ subject?: string }} MailTimeConcatEmailsOptions
168
189
  */
169
190
  /**
170
- * @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
191
+ * @typedef {{ index: number, from: string | undefined }} MailTimeFromDetails
192
+ */
193
+ /**
194
+ * @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
171
195
  */
172
196
  /** Class of MailTime */
173
197
  export class MailTime {
174
198
  static set Template(newVal: string);
175
199
  static get Template(): string;
200
+ /**
201
+ * @static
202
+ * @memberOf MailTime
203
+ * @name transportFrom
204
+ * @description Best-effort sender address for a transport. `nodemailer.createTransport()`
205
+ * only exposes `.options` for *plain-object* configs — for a class-instance transporter
206
+ * (anything with its own `.send()`) nodemailer's internal `Mail.options` is always `{}`,
207
+ * so `transport.options.from` silently reads `undefined`. This walks the places the
208
+ * address can actually live.
209
+ * @param {MailTimeTransport} transport
210
+ * @returns {string | undefined}
211
+ */
212
+ static transportFrom(transport: MailTimeTransport): string | undefined;
176
213
  /**
177
214
  * Create a MailTime instance
178
215
  * @param {MailTimeOptions} opts - configuration object
@@ -192,12 +229,17 @@ export class MailTime {
192
229
  mode: "one" | "batch";
193
230
  concurrency: number;
194
231
  sendingTimeout: number;
232
+ renewClaim: number;
233
+ maxRenewals: number;
234
+ shouldFailOver: ((error: unknown, info: object | undefined, email: MailTimeTask) => boolean) | null;
235
+ strictPayload: boolean;
236
+ allowedMailFields: Set<string>;
195
237
  failsToNext: number;
196
238
  strategy: "backup" | "balancer";
197
239
  transports: MailTimeTransport[];
198
240
  transport: number;
199
241
  verifyTransports: boolean;
200
- from: boolean | ((transport: MailTimeTransport) => string);
242
+ from: boolean | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string);
201
243
  /** @type {string} */
202
244
  concatSubject: string;
203
245
  concatEmails: boolean;
@@ -209,6 +251,7 @@ export class MailTime {
209
251
  debug?: boolean;
210
252
  autoClear?: boolean;
211
253
  zombieTime?: number;
254
+ lockLeaseTime?: number;
212
255
  minRevolvingDelay?: number;
213
256
  maxRevolvingDelay?: number;
214
257
  execute?: "batch" | "one";
@@ -218,7 +261,8 @@ export class MailTime {
218
261
  onError?: (title: string, details: object) => void;
219
262
  onExecuted?: (uid: string, details: object) => void;
220
263
  } | undefined;
221
- scheduler: JoSk | undefined;
264
+ /** @type {MailTimeScheduler | undefined} */
265
+ scheduler: MailTimeScheduler | undefined;
222
266
  /**
223
267
  * @async
224
268
  * @memberOf MailTime
@@ -292,7 +336,7 @@ export class MailTime {
292
336
  * @returns {Promise<string>} uuid of the email
293
337
  * @throws {Error}
294
338
  */
295
- sendMail(opts?: MailTimeMailOptions): Promise<string>;
339
+ sendMail(opts: MailTimeMailOptions): Promise<string>;
296
340
  /**
297
341
  * @async
298
342
  * @memberOf MailTime
@@ -318,5 +362,4 @@ import { PostgresQueue } from './adapters/postgres.js';
318
362
  import { mailTimePreset } from './presets.js';
319
363
  import { presets } from './presets.js';
320
364
  import { presetNames } from './presets.js';
321
- import { JoSk } from 'josk';
322
365
  export { MongoQueue, RedisQueue, PostgresQueue, mailTimePreset, presets, presetNames };