more jsdoc comments

This commit is contained in:
Evert Prants 2022-09-24 12:32:15 +03:00
parent e0b38cb708
commit ad0ed84f7e
Signed by: evert
GPG Key ID: 1688DA83D222D0B5
4 changed files with 85 additions and 24 deletions

View File

@ -9,6 +9,7 @@ export * from './utility/message-formatting';
export * from './utility/mode-from-prefix'; export * from './utility/mode-from-prefix';
export * from './utility/nickserv-validator'; export * from './utility/nickserv-validator';
export * from './utility/parser'; export * from './utility/parser';
export * from './utility/platform-base64';
export * from './utility/typed-event-emitter'; export * from './utility/typed-event-emitter';
export * from './utility/truncate'; export * from './utility/truncate';
export * from './utility/user-mapper'; export * from './utility/user-mapper';

View File

@ -4,7 +4,12 @@ import {
IRCConnector, IRCConnector,
IRCConnectorConstructor, IRCConnectorConstructor,
} from './types/impl.interface'; } from './types/impl.interface';
import { IIRCLine, IIRCOptions, IQueue } from './types/irc.interfaces'; import {
IIRCLine,
IIRCOptions,
IIRCServerData,
IQueue,
} from './types/irc.interfaces';
import { import {
Collector, Collector,
MultiLineCollector, MultiLineCollector,
@ -12,39 +17,36 @@ import {
WhoisCollector, WhoisCollector,
} from './utility/collector'; } from './utility/collector';
import { parse } from './utility/parser'; import { parse } from './utility/parser';
import { encodeBase64 } from './utility/platform-base64';
import { TypedEventEmitter } from './utility/typed-event-emitter'; import { TypedEventEmitter } from './utility/typed-event-emitter';
import { parseWho, WhoResponse } from './utility/who-parser'; import { parseWho, WhoResponse } from './utility/who-parser';
import { parseWhois, WhoisResponse } from './utility/whois-parser'; import { parseWhois, WhoisResponse } from './utility/whois-parser';
const encodeBase64 = (input: string) => {
if (window !== undefined && btoa !== undefined) {
return btoa(input);
} else if (Buffer !== undefined) {
return Buffer.from(input).toString('base64');
}
return input;
};
// TODO: typed emitter
export class IRCConnectionWrapper export class IRCConnectionWrapper
extends TypedEventEmitter<IRCCommunicatorEvents> extends TypedEventEmitter<IRCCommunicatorEvents>
implements IRCCommunicator implements IRCCommunicator
{ {
/**
* Channels the bot is currently in.
*/
public channels: string[] = []; public channels: string[] = [];
/**
* Current collectors waiting for their reply.
*/
public queue: IQueue[] = []; public queue: IQueue[] = [];
/**
* Login success status.
*/
public authenticated = false; public authenticated = false;
public serverData: { [key: string]: any } = {
/** /**
* (true host)Name of this server. * Information about the IRC server gathered during runtime
*/ */
public serverData: IIRCServerData = {
name: '', name: '',
/**
* Supported channel user modes from the server (e.g. `ohv: @%+`)
*/
supportedModes: {}, supportedModes: {},
/**
* Everything this server supports. See IRC documentation for command `005` or `RPL_ISUPPORT` for more info.
*/
serverSupports: {}, serverSupports: {},
}; };
@ -64,6 +66,14 @@ export class IRCConnectionWrapper
this.handlers(); this.handlers();
} }
/**
* Send a raw command to the server.
*
* **WARNING:** Line break characters could have an unintended side-effect!
* Filter user-generated content!
* @param format Command
* @param args Command arguments
*/
write(format: string, ...args: any[]): void { write(format: string, ...args: any[]): void {
this.connection?.write(format, ...args); this.connection?.write(format, ...args);
} }
@ -166,7 +176,7 @@ export class IRCConnectionWrapper
if ( if (
this.options.bot && this.options.bot &&
this.serverData.serverSupports.USERMODES && this.serverData.serverSupports.USERMODES &&
this.serverData.serverSupports.USERMODES.includes('B') (this.serverData.serverSupports.USERMODES as string).includes('B')
) { ) {
this.write('MODE %s +B', this.options.nick); this.write('MODE %s +B', this.options.nick);
} }
@ -302,8 +312,6 @@ export class IRCConnectionWrapper
} }
} else if (t[0] === 'NETWORK') { } else if (t[0] === 'NETWORK') {
this.serverData.network = t[1]; this.serverData.network = t[1];
} else if (t[0] === 'CHANNELLEN') {
this.serverData.maxChannelLength = parseInt(t[1], 10);
} }
let numeral: string | number = t[1]; let numeral: string | number = t[1];
@ -451,6 +459,9 @@ export class IRCConnectionWrapper
} }
} }
/**
* Create a new connection to the configured IRC server.
*/
public async connect(): Promise<void> { public async connect(): Promise<void> {
if (this.connection) { if (this.connection) {
await this.connection.destroy(); await this.connection.destroy();
@ -490,6 +501,10 @@ export class IRCConnectionWrapper
this.authenticate(); this.authenticate();
} }
/**
* Disconnect from the IRC server gracefully, sends `QUIT`.
* @param reason Reason for disconnection
*/
public async disconnect(reason?: string): Promise<void> { public async disconnect(reason?: string): Promise<void> {
if (!this.connected) { if (!this.connected) {
if (this.connection) { if (this.connection) {
@ -511,10 +526,18 @@ export class IRCConnectionWrapper
}); });
} }
/**
* Get connection status. `authenticated` is a more reliable indicator
* of a successful connection.
*/
public get connected() { public get connected() {
return this.connection?.connected ?? false; return this.connection?.connected ?? false;
} }
/**
* Asynchronously ping the server.
* @returns Ping in milliseconds
*/
public async getPing(): Promise<number> { public async getPing(): Promise<number> {
return new Promise<number>((resolve) => { return new Promise<number>((resolve) => {
const sendTime = Date.now(); const sendTime = Date.now();
@ -605,6 +628,14 @@ export class IRCConnectionWrapper
}); });
} }
/**
* Add a collector to the queue.
* This is used to grab lines from the server, wait for them
* and return them in a callback.
* @param collector IRC line collector
* @param line Command to send to the server
* @param args Arguments to the command
*/
public useCollector(collector: IQueue, line: string, ...args: any[]) { public useCollector(collector: IQueue, line: string, ...args: any[]) {
this.queue.push(collector); this.queue.push(collector);
this.write(line, ...args); this.write(line, ...args);

View File

@ -147,3 +147,19 @@ export interface IIRCOptions {
*/ */
connOpts?: Record<string, unknown>; connOpts?: Record<string, unknown>;
} }
export interface IIRCServerData {
/**
* (true host)Name of this server.
*/
name: string;
/**
* Everything this server supports. See IRC documentation for command `005` or `RPL_ISUPPORT` for more info.
*/
serverSupports: Record<string, unknown>;
/**
* Supported channel user modes from the server (e.g. `ohv: @%+`)
*/
supportedModes: Record<string, string>;
network?: string;
}

View File

@ -0,0 +1,13 @@
/**
* Encode a string in Base64, cross-platform (no dependencies)
* @param input String to encode
* @returns Base64-encoded string
*/
export const encodeBase64 = (input: string) => {
if (window !== undefined && btoa !== undefined) {
return btoa(input);
} else if (Buffer !== undefined) {
return Buffer.from(input).toString('base64');
}
return input;
};