diff --git a/.eslintrc.json b/.eslintrc.json index 9aea436..6b1db35 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -17,6 +17,12 @@ "error", "unix" ], - "valid-jsdoc": "error" + "valid-jsdoc": [ + "error", + { + "requireParamDescription": false, + "requireReturnDescription": false + } + ] } } diff --git a/smtp/address.ts b/smtp/address.ts index 36cca82..ada278e 100644 --- a/smtp/address.ts +++ b/smtp/address.ts @@ -9,7 +9,7 @@ export interface AddressObject { group?: AddressObject[]; } -/* +/** * Operator tokens and which tokens are expected to end the sequence */ const OPERATORS = new Map([ @@ -32,7 +32,7 @@ const OPERATORS = new Map([ * Tokenizes the original input string * * @param {string | string[] | undefined} address string(s) to tokenize - * @return {AddressToken[]} An array of operator|text tokens + * @return {AddressToken[]} An array of operator & text tokens */ function tokenizeAddress(address: string | string[] = '') { const tokens: AddressToken[] = []; @@ -69,8 +69,8 @@ function tokenizeAddress(address: string | string[] = '') { /** * Converts tokens for a single address into an address object * - * @param {AddressToken[]} tokens Tokens object - * @return {AddressObject[]} addresses object array + * @param {AddressToken[]} tokens + * @return {AddressObject[]} */ function convertAddressTokens(tokens: AddressToken[]) { const addressObjects: AddressObject[] = []; @@ -208,8 +208,8 @@ function convertAddressTokens(tokens: AddressToken[]) { * * [{name: "Name", address: "address@domain"}] * - * @param {string | string[] | undefined} address Address field - * @return {AddressObject[]} An array of address objects + * @param {string | string[] | undefined} address + * @return {AddressObject[]} */ export function addressparser(address?: string | string[]) { const addresses: AddressObject[] = []; diff --git a/smtp/client.ts b/smtp/client.ts index 302197d..a54b08a 100644 --- a/smtp/client.ts +++ b/smtp/client.ts @@ -44,7 +44,7 @@ export class SMTPClient { /** * @public * @template {Message | MessageHeaders} T - * @param {T} msg the message to send + * @param {T} msg * @param {MessageCallback} callback receiver for the error (if any) as well as the passed-in message / headers * @returns {void} */ @@ -71,8 +71,8 @@ export class SMTPClient { /** * @public * @template {Message | MessageHeaders} T - * @param {T} msg the message to send - * @returns {Promise} a promise that resolves to the passed-in message / headers + * @param {T} msg + * @returns {Promise} a promise that resolves to the message / headers */ public sendAsync(msg: T) { return new Promise((resolve, reject) => { @@ -176,18 +176,18 @@ export class SMTPClient { /** * @protected - * @param {MessageStack} stack stack + * @param {MessageStack} stack * @returns {void} */ protected _connect(stack: MessageStack) { /** - * @param {Error | null} err callback error + * @param {Error | null} err * @returns {void} */ const connect = (err: Error | null) => { if (!err) { /** - * @param {Error | null} err callback error + * @param {Error | null} err * @returns {void} */ const begin = (err: Error | null) => { @@ -223,8 +223,8 @@ export class SMTPClient { /** * @protected - * @param {MessageAttachment | MessageAttachment[]} attachment attachment - * @returns {boolean} whether the attachment contains inlined html + * @param {MessageAttachment | MessageAttachment[]} attachment + * @returns {boolean} */ protected _containsInlinedHtml( attachment?: MessageAttachment | MessageAttachment[] @@ -240,8 +240,8 @@ export class SMTPClient { /** * @protected - * @param {MessageAttachment} attachment attachment - * @returns {boolean} whether the attachment is inlined html + * @param {MessageAttachment} attachment + * @returns {boolean} */ protected _isAttachmentInlinedHtml(attachment?: MessageAttachment) { return ( @@ -253,9 +253,9 @@ export class SMTPClient { /** * @protected - * @param {MessageStack} stack stack - * @param {function(MessageStack): void} next next - * @returns {function(Error): void} callback + * @param {MessageStack} stack + * @param {function(MessageStack): void} next + * @returns {function(Error): void} */ protected _sendsmtp(stack: MessageStack, next: (msg: MessageStack) => void) { return (err: Error | null) => { @@ -271,7 +271,7 @@ export class SMTPClient { /** * @protected - * @param {MessageStack} stack stack + * @param {MessageStack} stack * @returns {void} */ protected _sendmail(stack: MessageStack) { @@ -282,7 +282,7 @@ export class SMTPClient { /** * @protected - * @param {MessageStack} stack stack + * @param {MessageStack} stack * @returns {void} */ protected _sendrcpt(stack: MessageStack) { @@ -299,7 +299,7 @@ export class SMTPClient { /** * @protected - * @param {MessageStack} stack stack + * @param {MessageStack} stack * @returns {void} */ protected _senddata(stack: MessageStack) { @@ -308,7 +308,7 @@ export class SMTPClient { /** * @protected - * @param {MessageStack} stack stack + * @param {MessageStack} stack * @returns {void} */ protected _sendmessage(stack: MessageStack) { @@ -331,8 +331,8 @@ export class SMTPClient { /** * @protected - * @param {Error | null} err err - * @param {MessageStack} stack stack + * @param {Error | null} err + * @param {MessageStack} stack * @returns {void} */ protected _senddone(err: Error | null, stack: MessageStack) { diff --git a/smtp/connection.ts b/smtp/connection.ts index e82fde3..955b38e 100644 --- a/smtp/connection.ts +++ b/smtp/connection.ts @@ -127,7 +127,7 @@ export class SMTPConnection extends EventEmitter { * * NOTE: `host` is trimmed before being used to establish a connection; however, the original untrimmed value will still be visible in configuration. * - * @param {Partial} options options + * @param {Partial} options */ constructor({ timeout, @@ -193,7 +193,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {0 | 1} level - + * @param {0 | 1} level * @returns {void} */ public debug(level: 0 | 1) { @@ -202,7 +202,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @returns {SMTPState} the current state + * @returns {SMTPState} */ public state() { return this._state; @@ -210,7 +210,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @returns {boolean} whether or not the instance is authorized + * @returns {boolean} */ public authorized() { return this.loggedin; @@ -222,10 +222,10 @@ export class SMTPConnection extends EventEmitter { * NOTE: `host` is trimmed before being used to establish a connection; however, the original untrimmed value will still be visible in configuration. * * @public - * @param {SMTPCommandCallback} callback function to call after response - * @param {number} [port] the port to use for the connection - * @param {string} [host] the hostname to use for the connection - * @param {ConnectOptions} [options={}] the options + * @param {SMTPCommandCallback} callback + * @param {number} [port] + * @param {string} [host] + * @param {ConnectOptions} [options={}] * @returns {void} */ public connect( @@ -269,7 +269,7 @@ export class SMTPConnection extends EventEmitter { }; /** - * @param {Error} err err + * @param {Error} err * @returns {void} */ const connectedErrBack = (err?: Error) => { @@ -343,8 +343,8 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {string} str the string to send - * @param {SMTPCommandCallback} callback function to call after response + * @param {string} str + * @param {SMTPCommandCallback} callback * @returns {void} */ public send(str: string, callback: SMTPCommandCallback) { @@ -376,9 +376,9 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {string} cmd command to issue - * @param {SMTPCommandCallback} callback function to call after response - * @param {(number[] | number)} [codes=[250]] array codes + * @param {string} cmd + * @param {SMTPCommandCallback} callback + * @param {(number[] | number)} [codes=[250]] SMTP response code(s) * @returns {void} */ public command( @@ -448,8 +448,8 @@ export class SMTPConnection extends EventEmitter { * As this command was deprecated by rfc2821, it should only be used for compatibility with non-compliant servers. * @see https://tools.ietf.org/html/rfc2821#appendix-F.3 * - * @param {SMTPCommandCallback} callback function to call after response - * @param {string} [domain] the domain to associate with the 'helo' request + * @param {SMTPCommandCallback} callback + * @param {string} [domain] * @returns {void} */ public helo(callback: SMTPCommandCallback, domain?: string) { @@ -465,7 +465,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {SMTPCommandCallback} callback function to call after response + * @param {SMTPCommandCallback} callback * @returns {void} */ public starttls(callback: SMTPCommandCallback) { @@ -503,7 +503,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {string} data the string to parse for features + * @param {string} data * @returns {void} */ public parse_smtp_features(data: string) { @@ -533,8 +533,8 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {SMTPCommandCallback} callback function to call after response - * @param {string} [domain] the domain to associate with the 'ehlo' request + * @param {SMTPCommandCallback} callback + * @param {string} [domain] * @returns {void} */ public ehlo(callback: SMTPCommandCallback, domain?: string) { @@ -557,7 +557,7 @@ export class SMTPConnection extends EventEmitter { /** * @public * @param {string} opt the features keyname to check - * @returns {boolean} whether the extension exists + * @returns {boolean} */ public has_extn(opt: string) { return (this.features ?? {})[opt.toLowerCase()] === undefined; @@ -566,8 +566,8 @@ export class SMTPConnection extends EventEmitter { /** * @public * @description SMTP 'help' command, returns text from the server - * @param {SMTPCommandCallback} callback function to call after response - * @param {string} domain the domain to associate with the 'help' request + * @param {SMTPCommandCallback} callback + * @param {string} domain * @returns {void} */ public help(callback: SMTPCommandCallback, domain: string) { @@ -576,7 +576,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {SMTPCommandCallback} callback function to call after response + * @param {SMTPCommandCallback} callback * @returns {void} */ public rset(callback: SMTPCommandCallback) { @@ -585,7 +585,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {SMTPCommandCallback} callback function to call after response + * @param {SMTPCommandCallback} callback * @returns {void} */ public noop(callback: SMTPCommandCallback) { @@ -594,7 +594,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {SMTPCommandCallback} callback function to call after response + * @param {SMTPCommandCallback} callback * @param {string} from the sender * @returns {void} */ @@ -604,7 +604,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {SMTPCommandCallback} callback function to call after response + * @param {SMTPCommandCallback} callback * @param {string} to the receiver * @returns {void} */ @@ -614,7 +614,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {SMTPCommandCallback} callback function to call after response + * @param {SMTPCommandCallback} callback * @returns {void} */ public data(callback: SMTPCommandCallback) { @@ -623,7 +623,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {SMTPCommandCallback} callback function to call after response + * @param {SMTPCommandCallback} callback * @returns {void} */ public data_end(callback: SMTPCommandCallback) { @@ -643,8 +643,8 @@ export class SMTPConnection extends EventEmitter { /** * @public * @description SMTP 'verify' command -- checks for address validity. - * @param {string} address the address to validate - * @param {SMTPCommandCallback} callback function to call after response + * @param {string} address + * @param {SMTPCommandCallback} callback * @returns {void} */ public verify(address: string, callback: SMTPCommandCallback) { @@ -654,8 +654,8 @@ export class SMTPConnection extends EventEmitter { /** * @public * @description SMTP 'expn' command -- expands a mailing list. - * @param {string} address the mailing list to expand - * @param {SMTPCommandCallback} callback function to call after response + * @param {string} address + * @param {SMTPCommandCallback} callback * @returns {void} */ public expn(address: string, callback: SMTPCommandCallback) { @@ -669,7 +669,7 @@ export class SMTPConnection extends EventEmitter { * If there has been no previous EHLO or HELO command self session, self * method tries ESMTP EHLO first. * - * @param {SMTPCommandCallback} callback function to call after response + * @param {SMTPCommandCallback} callback * @param {string} [domain] the domain to associate with the command * @returns {void} */ @@ -698,12 +698,12 @@ export class SMTPConnection extends EventEmitter { * * This method will return normally if the authentication was successful. * - * @param {SMTPCommandCallback} callback function to call after response - * @param {string} [user] the username to authenticate with - * @param {string} [password] the password for the authentication - * @param {Object} [options] login options - * @param {string} [options.method] login method - * @param {string} [options.domain] login domain + * @param {SMTPCommandCallback} callback + * @param {string} [user] + * @param {string} [password] + * @param {Object} [options] + * @param {string} [options.method] + * @param {string} [options.domain] * @returns {void} */ public login( @@ -721,8 +721,8 @@ export class SMTPConnection extends EventEmitter { const domain = options?.domain || this.domain; /** - * @param {Error | null} err err - * @param {unknown} data data + * @param {Error | null} err + * @param {unknown} data * @returns {void} */ const initiate = (err: Error | null | undefined, data: unknown) => { @@ -734,7 +734,7 @@ export class SMTPConnection extends EventEmitter { let method: keyof typeof AUTH_METHODS | null = null; /** - * @param {string} challenge challenge + * @param {string} challenge * @returns {string} base64 cram hash */ const encodeCramMd5 = (challenge: string) => { @@ -785,8 +785,8 @@ export class SMTPConnection extends EventEmitter { /** * handle bad responses from command differently - * @param {Error} err err - * @param {unknown} data data + * @param {Error} err + * @param {unknown} data * @returns {void} */ const failed = (err: Error, data: unknown) => { @@ -803,12 +803,12 @@ export class SMTPConnection extends EventEmitter { }; /** - * @param {Error | SMTPError | null} err err + * @param {Error | SMTPError | null} err * @param {( * string | * { code: (string | number), data: string, message: string } | * null - * )} [data] data + * )} [data] * @returns {void} */ const response: SMTPCommandCallback = (err, data) => { @@ -821,13 +821,13 @@ export class SMTPConnection extends EventEmitter { }; /** - * @param {Error | SMTPError | null} err err + * @param {Error | SMTPError | null} err * @param {( * string | * { code: (string | number), data: string, message: string } | * null - * )} data data - * @param {string} msg message + * )} data + * @param {string} msg * @returns {void} */ const attempt: SMTPCommandCallback = (err, data, msg) => { @@ -847,12 +847,12 @@ export class SMTPConnection extends EventEmitter { }; /** - * @param {Error | SMTPError | null} err err + * @param {Error | SMTPError | null} err * @param {( * string | * { code: (string | number), data: string, message: string } | * null - * )} [data] data + * )} [data] * @returns {void} */ const attemptUser: SMTPCommandCallback = (err, data) => { @@ -908,7 +908,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {boolean} [force=false] whether or not to force destroy the connection + * @param {boolean} [force=false] * @returns {void} */ public close(force = false) { @@ -936,7 +936,7 @@ export class SMTPConnection extends EventEmitter { /** * @public - * @param {SMTPCommandCallback} [callback] function to call after response + * @param {SMTPCommandCallback} [callback] * @returns {void} */ public quit(callback?: SMTPCommandCallback) { diff --git a/smtp/date.ts b/smtp/date.ts index 8d62a29..9af607f 100644 --- a/smtp/date.ts +++ b/smtp/date.ts @@ -44,7 +44,7 @@ const rfc2822re = /** * @param {string} date a string to check for conformance to the [rfc2822](https://tools.ietf.org/html/rfc2822#section-3.3) standard - * @returns {boolean} the result of the conformance check + * @returns {boolean} */ export function isRFC2822Date(date: string) { return rfc2822re.test(date); diff --git a/smtp/error.ts b/smtp/error.ts index 5fc9e4b..04ef427 100644 --- a/smtp/error.ts +++ b/smtp/error.ts @@ -22,7 +22,7 @@ export class SMTPError extends Error { /** * @protected - * @param {string} message error message + * @param {string} message */ protected constructor(message: string) { super(message); @@ -30,11 +30,11 @@ export class SMTPError extends Error { /** * - * @param {string} message error message + * @param {string} message * @param {number} code smtp error state * @param {Error | null} [error] previous error * @param {unknown} [smtp] arbitrary data - * @returns {SMTPError} error + * @returns {SMTPError} */ public static create( message: string, diff --git a/smtp/message.ts b/smtp/message.ts index 901d801..5fa2a01 100644 --- a/smtp/message.ts +++ b/smtp/message.ts @@ -135,7 +135,7 @@ export class Message { * - You can also add whatever other headers you want. * * @see https://tools.ietf.org/html/rfc2822 - * @param {Partial} headers Message headers + * @param {Partial} headers */ constructor(headers: Partial = {}) { for (const header in headers) { @@ -175,7 +175,7 @@ export class Message { * Can be called multiple times, each adding a new attachment. * * @public - * @param {MessageAttachment} options attachment options + * @param {MessageAttachment} options * @returns {Message} the current instance for chaining */ public attach(options: MessageAttachment) { @@ -257,7 +257,7 @@ export class Message { /** * @public - * @param {function(Error, string): void} callback the function to call with the error and buffer + * @param {function(Error, string): void} callback * @returns {void} */ public read(callback: (err: Error, buffer: string) => void) { @@ -270,7 +270,7 @@ export class Message { /** * @public - * @returns {Promise} promise that resolves to the read result + * @returns {Promise} */ public readAsync() { return new Promise((resolve, reject) => { @@ -293,13 +293,13 @@ class MessageStream extends Stream { readable = true; /** - * @param {Message} message the message to stream + * @param {Message} message */ constructor(private message: Message) { super(); /** - * @param {string} data the data to output + * @param {string} data * @returns {void} */ const output = (data: string) => { @@ -351,7 +351,7 @@ class MessageStream extends Stream { }; /** - * @param {MessageAttachment} attachment the attachment whose headers you would like to output + * @param {MessageAttachment} attachment * @returns {void} */ const outputAttachmentHeaders = (attachment: MessageAttachment) => { @@ -389,8 +389,8 @@ class MessageStream extends Stream { }; /** - * @param {string} data the data to output as base64 - * @param {function(): void} [callback] the function to call after output is finished + * @param {string} data + * @param {function(): void} [callback] * @returns {void} */ const outputBase64 = (data: string, callback?: () => void) => { @@ -406,8 +406,8 @@ class MessageStream extends Stream { }; /** - * @param {MessageAttachment} attachment attachment - * @param {function((NodeJS.ErrnoException | null)): void} next next + * @param {MessageAttachment} attachment + * @param {function((NodeJS.ErrnoException | null)): void} next * @returns {void} */ const outputFile = ( @@ -427,7 +427,7 @@ class MessageStream extends Stream { : inputEncoding; /** - * @param {NodeJS.ErrnoException | null} err the error to emit + * @param {NodeJS.ErrnoException | null} err * @param {number} fd the file descriptor * @returns {void} */ @@ -467,8 +467,8 @@ class MessageStream extends Stream { }; /** - * @param {MessageAttachment} attachment the metadata to use as headers - * @param {function(): void} callback the function to call after output is finished + * @param {MessageAttachment} attachment + * @param {function(): void} callback * @returns {void} */ const outputStream = ( @@ -516,8 +516,8 @@ class MessageStream extends Stream { }; /** - * @param {MessageAttachment} attachment attachment - * @param {function(): void} callback the function to call + * @param {MessageAttachment} attachment + * @param {function(): void} callback * @returns {void} */ const outputAttachment = ( @@ -585,8 +585,8 @@ class MessageStream extends Stream { }; /** - * @param {MessageAttachment} attachment the metadata to use as headers - * @param {function(): void} callback the function to call after output is finished + * @param {MessageAttachment} attachment + * @param {function(): void} callback * @returns {void} */ const outputData = ( @@ -602,7 +602,7 @@ class MessageStream extends Stream { }; /** - * @param {Message} message the message to output + * @param {Message} message * @returns {void} */ const outputText = (message: Message) => { @@ -622,8 +622,8 @@ class MessageStream extends Stream { }; /** - * @param {MessageAttachment} message the message to output - * @param {function(): void} callback the function to call after output is finished + * @param {MessageAttachment} message + * @param {function(): void} callback * @returns {void} */ const outputRelated = ( @@ -643,8 +643,8 @@ class MessageStream extends Stream { }; /** - * @param {Message} message the message to output - * @param {function(): void} callback the function to call after output is finished + * @param {Message} message + * @param {function(): void} callback * @returns {void} */ const outputAlternative = (message: Message, callback: () => void) => { @@ -678,7 +678,7 @@ class MessageStream extends Stream { }; /** - * @param {Error} [err] err + * @param {Error} [err] * @returns {void} */ const close = (err?: Error) => { @@ -746,7 +746,7 @@ class MessageStream extends Stream { /** * @public - * pause the stream + * @description pause the stream * @returns {void} */ public pause() { @@ -756,7 +756,7 @@ class MessageStream extends Stream { /** * @public - * resume the stream + * @description resume the stream * @returns {void} */ public resume() { @@ -766,7 +766,7 @@ class MessageStream extends Stream { /** * @public - * destroy the stream + * @description destroy the stream * @returns {void} */ public destroy() { @@ -778,7 +778,7 @@ class MessageStream extends Stream { /** * @public - * destroy the stream at first opportunity + * @description destroy the stream at first opportunity * @returns {void} */ public destroySoon() { diff --git a/smtp/mime.ts b/smtp/mime.ts index 5e9d1ef..3df0bb2 100644 --- a/smtp/mime.ts +++ b/smtp/mime.ts @@ -3,9 +3,7 @@ import { TextDecoder, TextEncoder } from 'util'; const encoder = new TextEncoder(); -/** - * @see https://tools.ietf.org/html/rfc2045#section-6.7 - */ +/** @see https://tools.ietf.org/html/rfc2045#section-6.7 */ const RANGES = [ [0x09], // [0x0a], // @@ -114,8 +112,7 @@ function splitMimeEncodedString(str: string, maxlen = 12) { } /** - * - * @param {number} nr number + * @param {number} nr * @returns {boolean} if number is in range */ function checkRanges(nr: number) {