eleith
/
emailjs
mirror of https://github.com/eleith/emailjs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

chore: remove jsdoc bureaucracy

This commit is contained in:
Zack Schuster 2022-05-06 21:18:41 -07:00
parent dd3db098c0
commit a5ff7bd85e
8 changed files with 120 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.eslintrc.json
View File

@ -17,6 +17,12 @@
"error",
"unix"
],
"valid-jsdoc": "error"
"valid-jsdoc": [
"error",
{
"requireParamDescription": false,
"requireReturnDescription": false
}
]
}
}

12
smtp/address.ts
View File

@ -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[] = [];

38
smtp/client.ts
View File

@ -44,7 +44,7 @@ export class SMTPClient {
/**
* @public
* @template {Message | MessageHeaders} T
* @param {T} msg the message to send
* @param {T} msg
* @param {MessageCallback<T>} 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<T>} a promise that resolves to the passed-in message / headers
* @param {T} msg
* @returns {Promise<Message>} a promise that resolves to the message / headers
*/
public sendAsync<T extends Message | MessageHeaders>(msg: T) {
return new Promise<Message>((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) {

108
smtp/connection.ts
View File

@ -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<SMTPConnectionOptions>} options options
* @param {Partial<SMTPConnectionOptions>} 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) {

2
smtp/date.ts
View File

@ -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);

6
smtp/error.ts
View File

@ -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,

56
smtp/message.ts
View File

@ -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<MessageHeaders>} headers Message headers
* @param {Partial<MessageHeaders>} headers
*/
constructor(headers: Partial<MessageHeaders> = {}) {
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<string>} promise that resolves to the read result
* @returns {Promise<string>}
*/
public readAsync() {
return new Promise<string>((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() {

7
smtp/mime.ts
View File

@ -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], // <TAB>
[0x0a], // <LF>
@ -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) {