@wiajs/request 3.0.18 → 3.0.19

package/lib/ZlibTransform.js

@@ -1,10 +1,20 @@
 import stream from 'node:stream';
 let ZlibTransform = class ZlibTransform extends stream.Transform {
-    __transform(chunk, encoding, callback) {
+    /**
+   * 
+   * @param {*} chunk 
+   * @param {*} encoding 
+   * @param {*} callback 
+   */ __transform(chunk, encoding, callback) {
         this.push(chunk);
         callback();
     }
-    _transform(chunk, encoding, callback) {
+    /**
+   * 
+   * @param {*} chunk 
+   * @param {*} encoding 
+   * @param {*} callback 
+   */ _transform(chunk, encoding, callback) {
         if (chunk.length !== 0) {
             this._transform = this.__transform;
             // Add Default Compression headers if no zlib headers are present

package/lib/caseless.js

@@ -61,7 +61,11 @@ export default class Caseless {
         this.dict[name] = this.dict[has];
         delete this.dict[has];
     }
-    del(name) {
+    /**
+   * 
+   * @param {string} name 
+   * @returns 
+   */ del(name) {
         name = String(name).toLowerCase();
         let deleted = false;
         let changed = 0;
@@ -82,17 +86,35 @@ export default class Caseless {
  * @returns
  */ export function httpify(resp, headers) {
     const c = new Caseless(headers);
-    resp.setHeader = (key, value, clobber)=>{
+    /**
+   * 
+   * @param {string} key 
+   * @param {*} value 
+   * @param {*} clobber 
+   * @returns 
+   */ resp.setHeader = (key, value, clobber)=>{
         if (typeof value === 'undefined') return;
         return c.set(key, value, clobber);
     };
-    resp.hasHeader = (key)=>{
+    /**
+   * 
+   * @param {string} key 
+   * @returns {boolean|string}
+   */ resp.hasHeader = (key)=>{
         return c.has(key);
     };
-    resp.getHeader = (key)=>{
+    /**
+   * 
+   * @param {string} key 
+   * @returns {*}
+   */ resp.getHeader = (key)=>{
         return c.get(key);
     };
-    resp.removeHeader = (key)=>{
+    /**
+   * 
+   * @param {string} key 
+   * @returns {boolean}
+   */ resp.removeHeader = (key)=>{
         return c.del(key);
     };
     resp.headers = c.dict;

package/lib/request.js

@@ -17,7 +17,29 @@ const log = Log({
     env: `wia:req:${name(import.meta.url)}`
 }) // __filename
 ;
-const httpModules = {
+/**
+ * @typedef {object} Opts
+ * @prop {Object.<string,string>} headers
+ * @prop {string} host
+ * @prop {string} method
+ * @prop {string} family
+ * @prop {string} path
+ * @prop {'http:' | 'https:'} protocol
+ * @prop {*} agent
+ * @prop {*} agents
+ * @prop {boolean} [stream]
+ * @prop {boolean} [decompress=true]
+ * @prop {*} [transformStream]
+ * @prop {*} [beforeRedirect]
+ * @prop {boolean} [followRedirects]
+ * @prop {number} [maxRedirects=21]
+ * @prop {number} [maxBodyLength = 0]
+ * @prop {*} [trackRedirects]
+ */ /** @typedef {object} ResponseExt
+ * @prop {*[]} [redirects]
+ * @prop {string} [responseUrl]
+ * @prop {number} [responseStartTime]
+ */ /** @typedef { http.IncomingMessage & ResponseExt} Response*/ const httpModules = {
     'http:': http,
     'https:': https
 };
@@ -78,7 +100,7 @@ const writeEvents = [
     'upgrade'
 ];
 const writeEventEmit = Object.create(null);
-for (const ev of writeEvents)writeEventEmit[ev] = function(...args) {
+for (const ev of writeEvents)writeEventEmit[ev] = /** @param  {...any} args */ function(...args) {
     const m = this // 事件回调，this === clientRequest 实例
     ;
     log('req event', {
@@ -98,7 +120,7 @@ const readEvents = [
     'resume'
 ];
 const readEventEmit = Object.create(null);
-for (const ev of readEvents)readEventEmit[ev] = function(...args) {
+for (const ev of readEvents)readEventEmit[ev] = /** @param  {...any} args */ function(...args) {
     const m = this // 事件回调，this === clientRequest 实例
     ;
     log('res event', {
@@ -118,10 +140,10 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
  */ export default class Request extends Duplex {
     /**
    * responseCallback 原消息处理回调
-   * @param {*} opts
+   * @param {Opts} opts
    * @param {*} resCallback
    */ constructor(opts, resCallback){
-        super(), this._timeout = 0, /** @type {*} */ this.socket = null, /** @type {http.ClientRequest} */ this._currentRequest = null, /** @type {stream.Readable} */ this.response = null, /** @type {stream.Readable} */ this.responseStream = null, this.timing = false, this.responseStarted = false, this.responseStartTime = 0, this._destdata = false, this._paused = false, this._respended = false, /** @type {stream.Readable} */ this.pipesrc = null // 被 pipe 时的 src stream
+        super(), /** @type {NodeJS.Timeout} */ this._timeout = null, /** @type {*} */ this.socket = null, /** @type {http.ClientRequest} */ this._currentRequest = null, /** @type {Response} */ this.response = null, /** @type {stream.Readable} */ this.responseStream = null, this.timing = false, this.responseStarted = false, this.responseStartTime = 0, this._destdata = false, this._paused = false, this._respended = false, /** @type {stream.Readable} */ this.pipesrc = null // 被 pipe 时的 src stream
         , /** @type {stream.Writable[]} */ this.pipedests = [] // pipe dest
         , /** @type {*} */ this.startTimer = null;
         const m = this;
@@ -139,9 +161,11 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
         /** @type {any[]} */ m._requestBodyBuffers = [];
         // save the callback if passed
         m.resCallback = resCallback;
-        // React to responses of native requests
-        // 接管 response 事件，非重定向，触发 response 事件
-        m._onResponse = (res)=>{
+        /**
+     * React to responses of native requests
+     * 接管 response 事件，非重定向，触发 response 事件
+     * @param {Response} res
+     */ m._onResponse = (res)=>{
             try {
                 m.processResponse(res);
             } catch (cause) {
@@ -179,24 +203,25 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
         if (opts.stream) {
             // 流模式
             // 被 pipe 作为目标时触发，拷贝 src headers
-            m.on('pipe', /** @type {stream.Readable} */ (src)=>{
+            m.on('pipe', /** @param {stream.Readable & {headers?: Object.<string, string>}} src */ (src)=>{
                 // m.ntick &&
                 if (m._currentRequest) {
                     m.emit('error', new Error('You cannot pipe to this stream after the outbound request has started.'));
                 }
                 m.pipesrc = src;
                 if (utils.isReadStream(src)) {
-                    if (!m.hasHeader('content-type')) {
-                        m.setHeader('content-type', mime.lookup(src.path));
-                    }
+                    // @ts-ignore
+                    if (!m.hasHeader('content-type')) m.setHeader('content-type', mime.lookup(src.path));
                 } else {
+                    // 拷贝请求头
                     if (src.headers) {
-                        for (const h of src.headers){
-                            if (!m.hasHeader(h)) {
-                                m.setHeader(h, src.headers[h]);
+                        for (const k of Object.keys(src.headers)){
+                            if (!m.hasHeader(k)) {
+                                m.setHeader(k, src.headers[k]);
                             }
                         }
                     }
+                    // @ts-ignore
                     if (src.opt.method && !m.opt.method) m.opt.method = src.opt.method;
                 }
             });
@@ -244,8 +269,10 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
                 protocol
             }, 'request');
             // Create the native request and set up its event handlers
+            // @ts-ignore
             const req = httpModule.request(opt, m._onResponse);
             m._currentRequest = req;
+            // @ts-ignore
             req.redirectReq = m;
             // 启动 startTimer
             if (m.startTimer) m._currentRequest.once('socket', m.startTimer);
@@ -262,7 +289,10 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
                 // Write the request entity and end
                 let i = 0;
                 const buffers = m._requestBodyBuffers;
-                (function writeNext(error) {
+                /**
+         *
+         * @param {*} error
+         */ function writeNext(error) {
                     // Only write if this request has not been redirected yet
                     /* istanbul ignore else */ if (req === m._currentRequest) {
                         // Report any write errors
@@ -272,7 +302,8 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
                             /* istanbul ignore else */ if (!req.finished) req.write(buf.data, buf.encoding, writeNext);
                         } else if (m._ended) req.end();
                     }
-                })();
+                }
+                writeNext();
             }
             R = req;
         } catch (e) {
@@ -303,15 +334,16 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
     /**
    * Writes buffered data to the current native request
    * 如 request 不存在，则创建连接，pipe 时可写入 header
-   * @param {*} chunk
-   * @param {BufferEncoding=} encoding
-   * @param {(error: Error) => void} [cb]
-   * @returns {boolean}
-   */ write(chunk, encoding, cb) {
+   * @override -  重写父类方法
+   * @param {*} chunk - The data chunk to write.
+   * @param {BufferEncoding | ((error: Error | null) => void)} [encodingOrCallback] - Encoding for string data, or the callback if no encoding is provided.
+   * @param {(error: Error | null) => void} [cb] - Callback to signal the end of the write operation.
+   * @returns {boolean} True if the write was successful, false otherwise.
+   */ write(chunk, encodingOrCallback, cb) {
         const m = this;
         log({
             data: chunk,
-            encoding,
+            encoding: encodingOrCallback,
             callback: cb
         }, 'write');
         // Writing is not allowed if end has been called
@@ -320,14 +352,15 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
         if (!m._currentRequest) m.request();
         // Validate input and shift parameters if necessary
         if (!utils.isString(chunk) && !utils.isBuffer(chunk)) throw new TypeError('data should be a string, Buffer or Uint8Array');
-        if (utils.isFunction(encoding)) {
-            cb = encoding;
-            encoding = null;
+        if (utils.isFunction(encodingOrCallback)) {
+            // @ts-ignore
+            cb = encodingOrCallback;
+            encodingOrCallback = null;
         }
         // Ignore empty buffers, since writing them doesn't invoke the callback
         // https://github.com/nodejs/node/issues/22066
         if (chunk.length === 0) {
-            if (cb) cb();
+            if (cb) cb(null);
             return;
         }
         // Only write when we don't exceed the maximum body length
@@ -335,9 +368,10 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
             m._requestBodyLength += chunk.length;
             m._requestBodyBuffers.push({
                 data: chunk,
-                encoding
+                encoding: encodingOrCallback
             });
-            m._currentRequest.write(chunk, encoding, cb);
+            // @ts-ignore
+            m._currentRequest.write(chunk, encodingOrCallback, cb);
         } else {
             m.emit('error', new MaxBodyLengthExceededError());
             m.abort();
@@ -345,42 +379,46 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
     }
     /**
    * Ends the current native request
-   * @param {*} data
-   * @param {*} encoding
-   * @param {*} callback
-   */ end(data, encoding, callback) {
+   * @override -  重写父类方法
+   * @param {*} [chunk] - Optional data to write before ending the stream.
+   * @param {BufferEncoding | (() => void)} [encoding] - Encoding for string data, or the callback if no encoding is provided.
+   * @param {() => void} [cb] - Optional callback to signal completion.
+   * @returns {this} The current stream instance, to allow chaining.
+   */ end(chunk, encoding, cb) {
         const m = this;
         // Shift parameters if necessary
-        if (utils.isFunction(data)) {
-            callback = data;
-            data = null;
+        if (utils.isFunction(chunk)) {
+            cb = chunk;
+            chunk = null;
             encoding = null;
         } else if (utils.isFunction(encoding)) {
-            callback = encoding;
+            // @ts-ignore
+            cb = encoding;
             encoding = null;
         }
         // ! 数据写入时连接，pipe 时可设置 header
         if (!m._currentRequest) m.request();
         // Write data if needed and end
-        if (!data) {
+        if (!chunk) {
             m._ended = true;
             m._ending = true;
-            m._currentRequest.end(null, null, callback);
+            m._currentRequest.end(null, null, cb);
         } else {
             const currentRequest = m._currentRequest;
-            m.write(data, encoding, ()=>{
+            m.write(chunk, encoding, ()=>{
                 m._ended = true;
-                currentRequest.end(null, null, callback);
+                currentRequest.end(null, null, cb);
             });
             m._ending = true;
         }
+        return m;
     }
     /**
    *
    * @param {string} name
    * @returns
    */ hasHeader(name) {
-        return this.opt.headers.includes(name);
+        return Object.keys(this.opt.headers).includes(name);
     }
     /**
    *
@@ -392,6 +430,7 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
     /**
    * Sets a header value on the current native request
    * @param {string} name
+   * @param {string} value
    */ setHeader(name, value) {
         this.opt.headers[name] = value;
         this._currentRequest?.setHeader(name, value);
@@ -469,7 +508,10 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
         m.on('close', clearTimer);
         return m;
     }
-    sanitizeOptions(options) {
+    /**
+   *
+   * @param {*} options
+   */ sanitizeOptions(options) {
         // Ensure headers are always present
         if (!options.headers) options.headers = {};
         // Since http.request treats host as an alias of hostname,
@@ -495,14 +537,14 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
     }
     /**
    * Processes a response from the current native request
-   * @param {*} response
+   * @param {Response} response
    * @returns
    */ processResponse(response) {
         const m = this;
         const { opt } = m;
         // Store the redirected response
         const { statusCode } = response;
-        if (m.opt.trackRedirects) {
+        if (opt.trackRedirects) {
             m._redirects.push({
                 url: m._currentUrl,
                 headers: response.headers,
@@ -521,7 +563,7 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
             statusCode,
             headers: response.headers
         }, 'processResponse');
-        if (!location || m.opt.followRedirects === false || statusCode < 300 || statusCode >= 400) {
+        if (!location || opt.followRedirects === false || statusCode < 300 || statusCode >= 400) {
             // 非重定向，返回给原始回调处理
             response.responseUrl = m._currentUrl;
             response.redirects = m._redirects;
@@ -545,7 +587,7 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
             m.emit('response', response, responseStream);
             // Clean up
             m._requestBodyBuffers = [];
-            return;
+            return; // 退出，不继续处理
         }
         // The response is a redirect, so abort the current request
         destroyRequest(m._currentRequest);
@@ -553,34 +595,35 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
         response.destroy();
         // RFC7231§6.4: A client SHOULD detect and intervene
         // in cyclical redirections (i.e., "infinite" redirection loops).
-        if (++m._redirectCount > m.opt.maxRedirects) throw new TooManyRedirectsError();
+        if (++m._redirectCount > opt.maxRedirects) throw new TooManyRedirectsError();
         // Store the request headers if applicable
         let requestHeaders;
-        const { beforeRedirect } = m.opt;
+        const { beforeRedirect } = opt;
         if (beforeRedirect) {
             requestHeaders = {
                 // The Host header was set by nativeProtocol.request
+                // @ts-ignore
                 Host: response.req.getHeader('host'),
-                ...m.opt.headers
+                ...opt.headers
             };
         }
         // RFC7231§6.4: Automatic redirection needs to done with
         // care for methods not known to be safe, […]
         // RFC7231§6.4.2–3: For historical reasons, a user agent MAY change
         // the request method from POST to GET for the subsequent request.
-        const { method } = m.opt;
-        if ((statusCode === 301 || statusCode === 302) && m.opt.method === 'POST' || // RFC7231§6.4.4: The 303 (See Other) status code indicates that
+        const { method } = opt;
+        if ((statusCode === 301 || statusCode === 302) && opt.method === 'POST' || // RFC7231§6.4.4: The 303 (See Other) status code indicates that
         // the server is redirecting the user agent to a different resource […]
         // A user agent can perform a retrieval request targeting that URI
         // (a GET or HEAD request if using HTTP) […]
-        statusCode === 303 && !/^(?:GET|HEAD)$/.test(m.opt.method)) {
+        statusCode === 303 && !/^(?:GET|HEAD)$/.test(opt.method)) {
             m.opt.method = 'GET';
             // Drop a possible entity and headers related to it
             m._requestBodyBuffers = [];
-            removeMatchingHeaders(/^content-/i, m.opt.headers);
+            removeMatchingHeaders(/^content-/i, opt.headers);
         }
         // Drop the Host header, as the redirect might lead to a different host
-        const currentHostHeader = removeMatchingHeaders(/^host$/i, m.opt.headers);
+        const currentHostHeader = removeMatchingHeaders(/^host$/i, opt.headers);
         // If the redirect is relative, carry over the host of the last request
         const currentUrlParts = utils.parseUrl(m._currentUrl);
         const currentHost = currentHostHeader || currentUrlParts.host;
@@ -611,8 +654,8 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
                 method,
                 headers: requestHeaders
             };
-            beforeRedirect(m.opt, responseDetails, requestDetails);
-            m.sanitizeOptions(m.opt);
+            beforeRedirect(opt, responseDetails, requestDetails);
+            m.sanitizeOptions(opt);
         }
         // Perform the redirected request
         m.request() // 重新执行请求
@@ -620,11 +663,11 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
     }
     /**
    * 处理响应stream
-   * 如：解压，透传流，需设置 decompress = false，避免解压数据
+   * 自动解压，透传流，需设置 decompress = false，避免解压数据
    * @param {*} res
    */ processStream(res) {
         const m = this;
-        const { opt: opts } = m;
+        const { opt } = m;
         const streams = [
             res
         ];
@@ -635,13 +678,13 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
             responseLength,
             headers: res.headers
         });
-        if (opts.transformStream) {
-            opts.transformStream.responseLength = responseLength;
-            streams.push(opts.transformStream);
+        if (opt.transformStream) {
+            opt.transformStream.responseLength = responseLength;
+            streams.push(opt.transformStream);
         }
-        const empty = utils.noBody(opts.method, res.statusCode);
+        const empty = utils.noBody(opt.method, res.statusCode);
         // decompress the response body transparently if required
-        if (opts.decompress !== false && res.headers['content-encoding']) {
+        if (opt.decompress !== false && res.headers['content-encoding']) {
             // if decompress disabled we should not decompress
             // 压缩内容，加入 解压 stream，自动解压，axios v1.2 存在bug，不能自动解压
             // if no content, but headers still say that it is encoded,
@@ -675,13 +718,14 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
                 default:
             }
         }
+        // 响应流，用于读
         const responseStream = streams.length > 1 ? stream.pipeline(streams, utils.noop) : streams[0];
         // 将内部 responseStream 可读流 映射到 redirectReq
         m.responseStream = responseStream;
         responseStream.redirectReq = m // 事情触发时引用
         ;
         // stream 模式，事件透传到 请求类
-        if (opts.stream) {
+        if (opt.stream) {
             if (m._paused) responseStream.pause();
             // 写入目的流
             for (const dest of m.pipedests)m.pipeDest(dest);
@@ -708,13 +752,18 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
     }
     // Read Stream API
     /**
+   * 建立读取流管道
    * read stream to write stream
    * pipe 只是建立连接管道，后续自动传输数据
-   * @param {stream.Writable} dest
-   * @param {*} opts
-   * @returns {stream.Writable}
-   */ pipe(dest, opts) {
+   * @override -  重写父类方法
+   * @template T - 需要模板
+   * @param {T & stream.Writable} dest - The writable stream to which data is written.
+   * @param {Object} [opts] - Optional configuration object.
+   * @param {boolean} [opts.end=true] - Whether to end the writable stream when the readable stream ends.
+   * @returns {T} The destination stream.
+   */ pipe(dest, opts = {}) {
         const m = this;
+        // m.pipe()
         // 请求已响应
         if (m.responseStream) {
             // 已有数据，不可pipe
@@ -778,7 +827,7 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
         if (response?.headers && dest.headers && !dest.headersSent) {
             const caseless = new Caseless(response.headers);
             if (caseless.has('content-type')) {
-                const ctname = caseless.has('content-type');
+                const ctname = /** @type {string} */ caseless.has('content-type');
                 if (dest.setHeader) {
                     dest.setHeader(ctname, response.headers[ctname]);
                 } else {
@@ -786,7 +835,7 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
                 }
             }
             if (caseless.has('content-length')) {
-                const clname = caseless.has('content-length');
+                const clname = /** @type {string} */ caseless.has('content-length');
                 if (dest.setHeader) {
                     dest.setHeader(clname, response.headers[clname]);
                 } else {
@@ -795,32 +844,26 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
             }
         }
         if (response?.headers && dest.setHeader && !dest.headersSent) {
-            for (const h of response.headers){
-                dest.setHeader(h, response.headers[h]);
-            }
+            for (const k of Object.keys(response.headers))dest.setHeader(k, response.headers[k]);
             dest.statusCode = response.statusCode;
         }
-        if (m.pipefilter) {
-            m.pipefilter(response, dest);
-        }
+        if (m.pipefilter) m.pipefilter(response, dest);
     }
     /**
    * 暂停read流
-   * @param  {...any} args
-   */ pause(...args) {
+   */ pause() {
         const m = this;
         // 没有流
         if (!m.responseStream) m._paused = true;
-        else m.responseStream.pause(...args);
+        else m.responseStream.pause();
         return m;
     }
     /**
-   * 继续read流
-   * @param  {...any} args
-   */ resume(...args) {
+   * 继续read响应流
+   */ resume() {
         const m = this;
         if (!m.responseStream) m._paused = false;
-        else m.responseStream.resume(...args);
+        else m.responseStream.resume();
         return m;
     }
     isPaused() {
@@ -838,17 +881,27 @@ const WriteAfterEndError = utils.createErrorType('ERR_STREAM_WRITE_AFTER_END', '
     request.on('error', utils.noop);
     request.destroy(error);
 }
-function removeMatchingHeaders(regex, headers) {
+/**
+ *
+ * @param {RegExp} regex
+ * @param {Object.<string, string>} headers
+ * @returns
+ */ function removeMatchingHeaders(regex, headers) {
     let lastValue;
-    Object.keys(headers).forEach((k)=>{
+    for (const k of Object.keys(headers)){
         if (regex.test(k)) {
             lastValue = headers[k];
             delete headers[k];
         }
-    });
+    }
     return lastValue === null || typeof lastValue === 'undefined' ? undefined : String(lastValue).trim();
 }
-function isSubdomain(subdomain, domain) {
+/**
+ *
+ * @param {string} subdomain
+ * @param {string} domain
+ * @returns
+ */ function isSubdomain(subdomain, domain) {
     assert(utils.isString(subdomain) && utils.isString(domain));
     const dot = subdomain.length - domain.length - 1;
     return dot > 0 && subdomain[dot] === '.' && subdomain.endsWith(domain);

package/lib/utils.js

@@ -25,20 +25,28 @@ const preservedUrlFields = [
     'hash'
 ];
 /**
- *
- * @param {*} code
- * @param {*} message
- * @param {*} baseClass
- * @returns
+ * Create a custom error type.
+ * @param {string} code - The error code.
+ * @param {string} message - The error message.
+ * @param {typeof Error} [baseClass] - The base error class to extend from. Defaults to `Error`.
+ * @returns {typeof Error & { new(properties?: object): CustomErrorInstance }} A custom error constructor.
+ * new(properties?: object) 为构造函数语法，返回 CustomErrorInstance 类型
+ * @typedef {object} CustomErrorInstance
+ * @property {string} code - The error code.
+ * @property {string} message - The error message.
+ * @property {Error | undefined} cause - The optional error cause.
  */ function createErrorType(code, message, baseClass) {
-    // Create constructor
-    function CustomError(properties) {
+    /**
+   * Create constructor
+   * @param {*} properties 
+   */ function CustomError(properties) {
         // istanbul ignore else
         if (isFunction(Error.captureStackTrace)) {
             Error.captureStackTrace(this, this.constructor);
         }
         Object.assign(this, properties || {});
         this.code = code;
+        // @ts-ignore
         this.message = this.cause ? `${message}: ${this.cause.message}` : message;
     }
     // Attach constructor and set default properties
@@ -53,6 +61,7 @@ const preservedUrlFields = [
             enumerable: false
         }
     });
+    // @ts-ignore
     return CustomError;
 }
 const InvalidUrlError = createErrorType('ERR_INVALID_URL', 'Invalid URL', TypeError);
@@ -122,7 +131,11 @@ const noop = ()=>{};
  */ function isURL(value) {
     return URL && value instanceof URL;
 }
-function isReadStream(rs) {
+/**
+ * 
+ * @param {*} rs 
+ * @returns 
+ */ function isReadStream(rs) {
     return rs.readable && rs.path && rs.mode;
 }
 /**