@flun/mailer 2.1.24 → 2.1.25

package/lib/smtp-pool/index.js

@@ -34,16 +34,16 @@ class SmtpPool extends EventEmitter {
     }
 
     /**
-     * 将电子邮件加入队列，使用选定设置发送
+     * 将电子邮件加入队列,使用选定设置发送
      *
      * @param {Object} mail 邮件对象
      * @param {Function} callback 回调函数
      */
     send(mail, callback) {
-        if (this._closed) return false;                            // 如果连接池已关闭，则返回false
+        if (this._closed) return false;                            // 如果连接池已关闭,则返回false
         this._queue.push({ mail, requeueAttempts: 0, callback });  // 将邮件加入队列(包括重试尝试计数)
 
-        // 如果队列长度达到最大连接数且处于空闲状态，则标记为非空闲
+        // 如果队列长度达到最大连接数且处于空闲状态,则标记为非空闲
         if (this.idling && this._queue.length >= this.options.maxConnections) this.idling = false;
         setImmediate(() => this.#processMessages());              // 立即开始处理消息
 
@@ -51,13 +51,13 @@ class SmtpPool extends EventEmitter {
     }
 
     /**
-     * 关闭池中的所有连接。如果有消息正在发送，则稍后关闭连接
+     * 关闭池中的所有连接;如果有消息正在发送,则稍后关闭连接
      */
     close() {
-        this._closed = true, clearTimeout(this._rateLimit.timeout); // 标记为已关闭并清除速率限制定时器（如果存在）
+        this._closed = true, clearTimeout(this._rateLimit.timeout); // 标记为已关闭并清除速率限制定时器(如果存在)
         const conLen = this._connections.length;
         let queLen = this._queue.length;
-        if (!conLen && !queLen) return;         // 如果没有连接和队列，则直接返回
+        if (!conLen && !queLen) return;         // 如果没有连接和队列,则直接返回
 
         // 移除所有可用连接
         for (let i = conLen - 1; i >= 0; i--) {
@@ -75,7 +75,7 @@ class SmtpPool extends EventEmitter {
                 const entry = this._queue.shift();
                 if (entry && typeof entry.callback === 'function') {
                     try {
-                        entry.callback(new Error(`连接池已关闭，队列中还有 ${queLen} 个待处理请求`));
+                        entry.callback(new Error(`连接池已关闭,队列中还有 ${queLen} 个待处理请求`));
                     } catch (E) {
                         this.logger.error({ err: E, tnx: 'callback' }, '回调错误: %s', E.message);
                     }
@@ -88,7 +88,7 @@ class SmtpPool extends EventEmitter {
     }
 
     /**
-     * 检查队列和可用连接。如果有要发送的消息且有可用连接，则使用此连接发送邮件
+     * 检查队列和可用连接;如果有要发送的消息且有可用连接,则使用此连接发送邮件
      */
     #processMessages() {
         let connection;
@@ -97,8 +97,8 @@ class SmtpPool extends EventEmitter {
                 this.idling = true, this.emit('idle'); // 标记为空闲
             };
 
-        if (this._closed) return;                  // 如果已关闭，则不执行任何操作
-        // 如果队列为空，则不执行任何操作
+        if (this._closed) return;                  // 如果已关闭,则不执行任何操作
+        // 如果队列为空,则不执行任何操作
         if (!queLen) {
             if (!this.idling) idlingEmit();
             return;
@@ -111,10 +111,10 @@ class SmtpPool extends EventEmitter {
                 break;
             }
 
-        // 如果没有可用连接且未达到最大连接数，则创建新连接
+        // 如果没有可用连接且未达到最大连接数,则创建新连接
         const { maxConnections } = this.options;
         if (!connection && conLen < maxConnections) connection = this.#createConnection();
-        if (!connection) return this.idling = false;               // 如果没有可用连接，则标记为非空闲并返回
+        if (!connection) return this.idling = false;               // 如果没有可用连接,则标记为非空闲并返回
         if (!this.idling && queLen < maxConnections) idlingEmit(); // 检查处理队列中是否有空闲空间
 
         // 从队列中取出一个条目并分配给连接
@@ -155,12 +155,13 @@ class SmtpPool extends EventEmitter {
         // 监听池资源事件
         connection.on('available', () => {
             this.logger.debug({ tnx: 'connection', cid, action: 'available' }, '连接 #%s 变为可用', cid);
-            this._closed ? this.close() : this.#processMessages(); // 如果已关闭,则从连接列表中移除此连接,否则检查是否还有其它发送
+// 如果已关闭,则从连接列表中移除此连接,否则检查是否还有其它发送
+            this._closed ? this.close() : this.#processMessages();
         }).once('error', err => {
             if (err.code !== 'EMAXLIMIT') this.logger.error({ err, tnx: 'pool', cid }, '池错误 #%s: %s', cid, err.message);
             else this.logger.debug({ tnx: 'pool', cid, action: 'maxlimit' }, '连接 #%s 已达到最大消息限制', cid);
 
-            // 如果连接有队列条目，则调用回调并传递错误
+            // 如果连接有队列条目,则调用回调并传递错误
             if (connection.queueEntry) {
                 try {
                     connection.queueEntry.callback(err);
@@ -176,11 +177,12 @@ class SmtpPool extends EventEmitter {
             this.#removeConnection(connection);
             const { queueEntry } = connection;
             if (queueEntry)
-                // 如果连接在发送时关闭，将消息重新加入队列;如果未达到最大重试次数，则重新排队
+                // 如果连接在发送时关闭,将消息重新加入队列;如果未达到最大重试次数,则重新排队
                 setTimeout(() => {
-                    this.#shouldRequeueOnClose(queueEntry) ? this.#requeueOnClose(connection) : this.#failOnClose(connection);
+                    this.#shouldRequeueOnClose(queueEntry) ? this.#requeueOnClose(connection) 
+                        : this.#failOnClose(connection);
                     this.#continueProcessing();
-                }, 50);  // 必须等待一下，因为"error"处理程序的回调可能在下一个事件循环中调用
+                }, 50);  // 必须等待一下,因为"error"处理程序的回调可能在下一个事件循环中调用
             else {
                 if (!this._closed && this.idling && !this._connections.length) this.emit('clear');
                 this.#continueProcessing();
@@ -209,7 +211,8 @@ class SmtpPool extends EventEmitter {
                 queueEntry.callback(new Error('连接关闭后达到最大重试次数'));
             } catch (E) {
                 this.logger.error(
-                    { err: E, tnx: 'callback', messageId: queueEntry.messageId, cid: id }, '回调错误 #%s: %s', id, E.message);
+                    { err: E, tnx: 'callback', messageId: queueEntry.messageId, cid: id },
+                    '回调错误 #%s: %s', id, E.message);
             }
             connection.queueEntry = false;
         }
@@ -223,12 +226,12 @@ class SmtpPool extends EventEmitter {
         queueEntry.requeueAttempts++;
         const { messageId, requeueAttempts } = queueEntry;
         this.logger.debug({ tnx: 'pool', cid: id, messageId, action: 'requeue' },
-            '为 #%s 重新排队消息 <%s>。尝试次数: #%s', messageId, id, requeueAttempts);
+            '为 #%s 重新排队消息 <%s>;尝试次数: #%s', messageId, id, requeueAttempts);
         this._queue.unshift(queueEntry), connection.queueEntry = false;
     }
 
     /**
-     * 如果池未关闭，则继续处理消息
+     * 如果池未关闭,则继续处理消息
      */
     #continueProcessing() {
         this._closed ? this.close() : setTimeout(() => this.#processMessages(), 100);
@@ -245,7 +248,7 @@ class SmtpPool extends EventEmitter {
     }
 
     /**
-     * 检查连接是否达到当前速率限制，如果是，则将可用性回调加入队列
+     * 检查连接是否达到当前速率限制,如果是,则将可用性回调加入队列
      *
      * @param {Function} callback 速率限制清除后运行的回调函数
      */
@@ -274,7 +277,7 @@ class SmtpPool extends EventEmitter {
     }
 
     /**
-     * 如果队列中有空闲插槽，则返回true
+     * 如果队列中有空闲插槽,则返回true
      */
     isIdle() {
         return this.idling;

package/lib/smtp-pool/pool-resource.js

@@ -16,7 +16,7 @@ class PoolResource extends EventEmitter {
     constructor(pool) {
         super();
         this.pool = pool, this.options = pool.options, this.logger = this.pool.logger; // 所属连接池,连接选项,日志记录器
-        if (this.options.auth) this.auth = this.getAuth({});                           // 如果提供了认证信息，则设置认证
+        if (this.options.auth) this.auth = this.getAuth({});                           // 如果提供了认证信息,则设置认证
 
         this._connection = false, this._connected = false;                             // SMTP连接实例,连接状态标志
         this.messages = 0, this.available = true;                                      // 已发送消息计数,资源可用性标志

package/lib/smtp-transport.js

@@ -17,7 +17,7 @@ class SmtpTransport extends EventEmitter {
         super();
         this.name = 'SMTP';
         initSmtpConstructor(this, options, SmtpConnection, 'smtpTransport');  // 初始化SMTP连接
-        if (this.options.auth) this.auth = this.getAuth({});                  // 如果提供了认证信息，则设置认证
+        if (this.options.auth) this.auth = this.getAuth({});                  // 如果提供了认证信息,则设置认证
     }
 
     /**
@@ -45,7 +45,8 @@ class SmtpTransport extends EventEmitter {
                 state = { returned: false }, cleanC = setupConnectionHandlers(state, connection, callback, this),
                 // 发送消息
                 sendMessage = () => {
-                    const { envelope, readStream, from, to, messageId } = prepareMessageForSending(mail, this.logger);//邮件预处理
+//邮件预处理
+                    const { envelope, readStream, from, to, messageId } = prepareMessageForSending(mail, this.logger);
                     connection.send(envelope, readStream, (err, info) => {
                         state.returned = true, connection.close();
 

package/lib/stream-transport.js

@@ -7,15 +7,15 @@ import { PK, getLogger, prepareMessageForSending, resolveStream } from './shared
  * >查看定义:@see {@link StreamTransport}
  * @param {Object} [options] 配置选项
  * @param {boolean} [options.buffer=false]
- *   - `false`（默认）：**异步流式返回**，邮件内容以可读流 (Readable Stream) 的形式给出。
- *     适合：需要实时推送、管道转发，或邮件体积很大不想一次全装进内存时。
- *   - `true`：**先收完整再返回**，邮件内容会被拼成一个 Buffer 对象一次性给你。
- *     适合：需要加密、签名、保存文件等必须先拿到完整内容的场景。
+ *   - `false`(默认):**异步流式返回**,邮件内容以可读流 (Readable Stream) 的形式给出;
+ *     适合:需要实时推送、管道转发,或邮件体积很大不想一次全装进内存时;
+ *   - `true`:**先收完整再返回**,邮件内容会被拼成一个 Buffer 对象一次性给你;
+ *     适合:需要加密、签名、保存文件等必须先拿到完整内容的场景;
  * @param {string} [options.newline='']
- *   生成的邮件正文使用哪种换行符：
+ *   生成的邮件正文使用哪种换行符:
  *   - `'windows'`, `'win'`, `'dos'` 或 `'\r\n'` → 使用 Windows 风格换行 `\r\n`
  *   - `'unix'`、空字符串或其他值 → 使用 Unix 风格换行 `\n`
- *   通常保持默认即可；只有当你明确知道邮件客户端在 Windows 上有换行问题时才需设置。
+ *   通常保持默认即可;只有当你明确知道邮件客户端在 Windows 上有换行问题时才需设置;
  *
  * @constructor
  */
@@ -25,7 +25,8 @@ class StreamTransport {
 
         const { component = 'streamTransport', newline = '' } = this.options;
         this.logger = getLogger(this.options, { component });                                         // 初始化日志记录器
-        this.winbreak = ['win', 'windows', 'dos', '\r\n'].includes(newline.toString().toLowerCase()); // 根据配置确定换行符类型
+// 根据配置确定换行符类型
+        this.winbreak = ['win', 'windows', 'dos', '\r\n'].includes(newline.toString().toLowerCase());
     }
 
     /**
@@ -44,14 +45,15 @@ class StreamTransport {
                 this.logger.error({ err, tnx: 'send', messageId }, context, messageId, err.message), done(err);
             };
 
-            // 如果不使用缓冲区，直接返回流(流可读时才认为成功)
+            // 如果不使用缓冲区,直接返回流(流可读时才认为成功)
             if (!this.options.buffer) {
                 readStream.once('readable', () => done(null, { envelope, messageId, message: readStream }))
-                    .once('error', err => handleError(err, '为 %s 创建消息流失败。%s'))
+                    .once('error', err => handleError(err, '为 %s 创建消息流失败;%s'))
             }
 
             // 将流数据读取到Buffer中
-            resolveStream(readStream, (err, value) => err ? handleError(err) : done(null, { envelope, messageId, message: value }));
+            resolveStream(readStream,
+                (err, value) => err ? handleError(err) : done(null, { envelope, messageId, message: value }));
         });
     }
 }

package/lib/well-known/index.js

@@ -5,7 +5,7 @@ const normalized = {}, // 储存规范的服务对象
 
     /**
      * 规范化键名
-     * 移除非字母数字、点号和连字符的字符，并转换为小写
+     * 移除非字母数字、点号和连字符的字符,并转换为小写
      * @param {String} key - 需要规范化的键名
      * @returns {String} 规范化后的键名
      */
@@ -16,7 +16,7 @@ const normalized = {}, // 储存规范的服务对象
 
     /**
      * 规范化服务对象
-     * 过滤掉不需要的字段（domains 和 aliases）
+     * 过滤掉不需要的字段(domains 和 aliases)
      * @param {Object} service - 原始服务对象
      * @returns {Object} 规范化后的服务对象
      */
@@ -36,12 +36,13 @@ Object.keys(SERVICES).forEach(key => {
             normalized[normalizeKey(sourceKey)] = normalizeService(service);
         };
     // 处理主键,别名,域名
-    addServiceEntry(key), (service.aliases ?? []).forEach(addServiceEntry), (service.domains ?? []).forEach(addServiceEntry);
+    addServiceEntry(key),
+        (service.aliases ?? []).forEach(addServiceEntry), (service.domains ?? []).forEach(addServiceEntry);
 });
 
 /**
  * 根据提供的键名解析 SMTP 配置;
- * 键名可以是服务名称（如 'Gmail'）、别名（如 'Google Mail'）或邮箱地址（如 'test@googlemail.com'）
+ * 键名可以是服务名称(如 'Gmail')、别名(如 'Google Mail')或邮箱地址(如 'test@googlemail.com')
  * >查看定义:@see {@link wellKnown}
  * @param {String} key - 服务名称、别名或邮箱地址
  * @returns {Object|Boolean} SMTP 配置对象,如果未找到则返回 false

package/lib/xoauth2.js

@@ -8,13 +8,13 @@ import { nmfetch, getLogger, resolveStream } from './shared.js';
  * 有关获取用户所需 refreshToken 的离线访问,请参阅离线访问
  * https://developers.google.com/accounts/docs/OAuth2WebServer#offline
  *
- * 使用 provisionCallback 自定义方法生成访问令牌的用法：
+ * 使用 provisionCallback 自定义方法生成访问令牌的用法:
  * provisionCallback(user, renew, callback);
  *   * user 是要获取令牌的用户名
- *   * renew 是一个布尔值，如果为 true 表示现有令牌失败需要更新
+ *   * renew 是一个布尔值,如果为 true 表示现有令牌失败需要更新
  *   * callback 是带有 (error, accessToken [, expires]) 的回调函数
  *     * accessToken 是一个字符串
- *     * expires 是可选的过期时间（毫秒）
+ *     * expires 是可选的过期时间(毫秒)
  * 如果使用了 provisionCallback,则 @flun/mailer 不会尝试自行生成令牌
  * >查看定义:@see {@link XOAuth2}
  * @constructor
@@ -26,8 +26,8 @@ import { nmfetch, getLogger, resolveStream } from './shared.js';
  * @param {String} options.accessUrl 令牌生成端点,默认为 'https://accounts.google.com/o/oauth2/token'
  * @param {String} options.accessToken 现有的有效访问令牌
  * @param {String} options.privateKey JWT 私钥
- * @param {Number} options.expires 可选的访问令牌过期时间（毫秒）
- * @param {Number} options.timeout 可选的访问令牌 TTL（秒）
+ * @param {Number} options.expires 可选的访问令牌过期时间(毫秒)
+ * @param {Number} options.timeout 可选的访问令牌 TTL(秒)
  * @param {Function} options.provisionCallback 需要新访问令牌时运行的函数
  */
 class XOAuth2 extends Stream {
@@ -39,7 +39,8 @@ class XOAuth2 extends Stream {
             expires, timeout, accessUrl, customHeaders = {}, customParams = {} } = this.options;
         // 服务账户验证
         if (this.options?.serviceClient) {
-            if (!privateKey || !user) return setImmediate(() => this.emit('error', new Error('服务账户需要 "privateKey" 和 "user" 选项！')));
+            if (!privateKey || !user)
+                return setImmediate(() => this.emit('error', new Error('服务账户需要 "privateKey" 和 "user" 选项!')));
             this.options.serviceRequestTimeout = Math.min(Math.max(Number(serviceRequestTimeout) || 0, 0), 3600) || 5 * 60;
         }
 
@@ -55,35 +56,37 @@ class XOAuth2 extends Stream {
     }
 
     /**
-     * 返回或生成（如果之前的已过期）XOAuth2 令牌
+     * 返回或生成(如果之前的已过期)XOAuth2 令牌
      *
-     * @param {Boolean} renew 如果为 false 则使用缓存的访问令牌（如果可用）
+     * @param {Boolean} renew 如果为 false 则使用缓存的访问令牌(如果可用)
      * @param {Function} callback 带有错误对象和令牌字符串的回调函数
      */
     getToken(renew, callback) {
-        const { user, refreshToken, serviceClient } = this.options, { accessToken, expires, provisionCallback, renewing } = this,
+        const { user, refreshToken, serviceClient } = this.options,
+            { accessToken, expires, provisionCallback, renewing } = this,
             // 重用令牌
             reuseToken = message => {
                 this.logger.debug({ tnx: 'OAUTH2', user, action: 'reuse' }, message, user);
                 return callback(null, accessToken);
             };
 
-        // 如果不需要续订且令牌有效，则直接重用
+        // 如果不需要续订且令牌有效,则直接重用
         if (!renew && accessToken && (!expires || expires > Date.now())) return reuseToken('为 %s 重用现有访问令牌');
-        // 检查是否可以续订，如果不能，返回当前令牌或错误
+        // 检查是否可以续订,如果不能,返回当前令牌或错误
         if (!provisionCallback && !refreshToken && !serviceClient) {
-            if (accessToken) return reuseToken('为 %s 重用现有访问令牌（无刷新能力）');
-            this.logger.error({ tnx: 'OAUTH2', user, action: 'renew' }, '无法为 %s 续订访问令牌：无可用刷新机制', user);
+            if (accessToken) return reuseToken('为 %s 重用现有访问令牌(无刷新能力)');
+            this.logger.error({ tnx: 'OAUTH2', user, action: 'renew' }, '无法为 %s 续订访问令牌:无可用刷新机制', user);
             return callback(new Error("无法为用户创建新的访问令牌"));
         }
 
-        // 如果已经在续订中，将此请求加入队列而不是开始另一个
+        // 如果已经在续订中,将此请求加入队列而不是开始另一个
         if (renewing) return this.renewalQueue.push({ renew, callback });
         this.renewing = true;
 
         // 处理令牌续订完成 - 处理队列中的请求并清理
         const generateCallback = (err, accessToken) => {
-            this.renewalQueue.forEach(item => item.callback(err, accessToken)), this.renewalQueue = [], this.renewing = false;
+            this.renewalQueue.forEach(item => item.callback(err, accessToken)),
+            this.renewalQueue = [], this.renewing = false;
 
             if (err) this.logger.error({ err, tnx: 'OAUTH2', user, action: 'renew' }, '为 %s 生成新访问令牌失败', user);
             else this.logger.info({ tnx: 'OAUTH2', user, action: 'renew' }, '为 %s 生成新访问令牌', user);
@@ -102,9 +105,9 @@ class XOAuth2 extends Stream {
      * 更新令牌值
      *
      * @param {String} accessToken 新的访问令牌
-     * @param {Number} timeout 访问令牌生命周期（秒）
+     * @param {Number} timeout 访问令牌生命周期(秒)
      *
-     * 触发 'token' 事件：{ user: 用户电子邮件地址, accessToken: 新的访问令牌, timeout: TTL（秒）}
+     * 触发 'token' 事件:{ user: 用户电子邮件地址, accessToken: 新的访问令牌, timeout: TTL(秒)}
      */
     updateToken(accessToken = '', timeout) {
         this.accessToken = accessToken, timeout = Math.max(Number(timeout) || 0, 0);
@@ -124,7 +127,8 @@ class XOAuth2 extends Stream {
         if (serviceClient) {
             // 服务账户 - https://developers.google.com/identity/protocols/OAuth2ServiceAccount
             const iat = Math.floor(Date.now() / 1000), // unix 时间
-                tokenData = { iss: serviceClient, scope, sub: user, aud: accessUrl, iat, exp: iat + serviceRequestTimeout };
+                tokenData = { iss: serviceClient, scope, sub: user, aud: accessUrl, iat,
+                    exp: iat + serviceRequestTimeout };
             let assertion;
             try {
                 assertion = this.jwtSignRS256(tokenData);
@@ -165,7 +169,7 @@ class XOAuth2 extends Stream {
                 return callback(new Error('无效的身份验证响应'));
             }
 
-            // 记录响应数据（隐藏访问令牌的完整内容）
+            // 记录响应数据(隐藏访问令牌的完整内容)
             const logData = Object.fromEntries(
                 Object.entries(data).map(([k, v = '']) => [k, k === 'access_token' ? `${v.toString().slice(0, 6)}...` : v])
             );
@@ -173,7 +177,7 @@ class XOAuth2 extends Stream {
             this.logger.debug({ tnx, user, action }, '响应: %s', JSON.stringify(logData));
 
             if (data.error) {
-                let errorMessage = data.error; // 错误响应：https://tools.ietf.org/html/rfc6749#section-5.2
+                let errorMessage = data.error; // 错误响应:https://tools.ietf.org/html/rfc6749#section-5.2
 
                 if (data.error_description) errorMessage += `: ${data.error_description}`;
                 if (data.error_uri) errorMessage += ` (${data.error_uri})`;
@@ -202,19 +206,20 @@ class XOAuth2 extends Stream {
     }
 
     /**
-     * 自定义 POST 请求处理程序。
+     * 自定义 POST 请求处理程序;
      * 这仅在需要保持 Windows 中路径短时才需要;通常此模块
-     * 是依赖项的依赖项，如果它尝试 require 某些东西
-     * 比如 request 模块，路径对 Windows 来说会变得太长而无法处理。
-     * 由于只进行简单的 POST 请求，所以实际上不需要复杂的
-     * 逻辑支持（没有重定向，没有其他任何东西）。
+     * 是依赖项的依赖项,如果它尝试 require 某些东西
+     * 比如 request 模块,路径对 Windows 来说会变得太长而无法处理;
+     * 由于只进行简单的 POST 请求,所以实际上不需要复杂的
+     * 逻辑支持(没有重定向,没有其他任何东西);
      *
      * @param {String} url 要 POST 的 URL
      * @param {String|Buffer} payload 要 POST 的有效负载
      * @param {Function} callback 带有 (err, buff) 的回调函数
      */
     postRequest(url, payload, params, callback) {
-        const req = nmfetch(url, { method: 'post', headers: params.customHeaders, body: payload, allowErrorResponse: true });
+        const req = nmfetch(url, { method: 'post', headers: params.customHeaders, body: payload,
+            allowErrorResponse: true });
         resolveStream(req, callback); // 将流数据读取到Buffer中
     }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flun/mailer",
-  "version": "2.1.24",
-  "description": "A powerful and flexible email sending library for Node.js with multiple transport support (SMTP, SMTP Pool, Sendmail, Stream, JSON, SES)",
+  "version": "2.1.25",
+  "description": "Node.js 邮件发送库;支持 SMTP、SMTP Pool、Sendmail、Stream、JSON、SES 多种传输;",
   "type": "module",
   "exports": {
     ".": "./index.js"
@@ -53,10 +53,10 @@
     "npm": ">=10.0.0"
   },
   "dependencies": {
-    "@aws-sdk/client-sesv2": "^3.1146.0"
+    "@aws-sdk/client-sesv2": "^3.1156.0"
   },
   "devDependencies": {
-    "eslint": "^10.11.0",
+    "eslint": "^10.13.0",
     "jest": "^30.5.2"
   },
   "peerDependencies": {