djs-extra

Discord.js Extra

This provides a set of utilities for the Discord.js library. You can find a full list of the features below, with examples and documentation.

Installation

The only thing that is required for this to work is the discord.js library. npm i -s discord.js
npm i -s djs-extra

Documentation

This is a step by step walkthrough of the features that djs-extra provides.

Parameter Parsing

CommonJS Import const params = require('djs-extra/params');
ESM Import import params from 'djs-extra/params';

Lexer

Splits some text into a name, list of raw arguments, and the remaining text.

function lex(text: string): {
	name: string,
	items: string[],
	text: string
}

Parser

Executes the parameters with a given set of usages and calls the matching function. If an error occurred, info will be passed to the error handler.

function parse(
	items: string[],
	text: string,
	client: Client,
	guild: Guild,
	usages: Record<string, Function>,
	success: Function,
	error: Function
)

Parameter Object

This is what you get for every flag and parameter that is parsed. Each helper returns null if invalid.

function error(type: string, subtype: string, item: any) {} // Calls the error handler.  
function text(): string {} // Returns the raw text.
function usage(): string {} // Returns the usage text.
function name(): string {} // Returns the parameter name.
function string(): string {} // Returns a parsed string.
function id(): string {} // Returns a Discord snowflake.
function channel(...types: string[]): Channel {} // Returns a channel object.
function message(channel: Channel): Promise<Message> {} // Returns a message object.
function emoji(): Emoji {} // Returns an emoji object.
function member(): Promise<GuildMember> {} // Returns a member object.
function user(): Promise<User> {} // Returns a user object.
function role(): Promise<Role> {} // Returns a role object.
function boolean(): boolean {} // Returns a boolean.
function number(min: number, max: number): number {} // Returns a number.
function integer(min: number, max: number): number {} // Returns an integer.
function exists(): boolean {} // Checks if the parameter is not empty.
function empty(): boolean {} // Checks if the parameter is empty.

Usage Syntax

-flag Optional boolean flag.
[example] Optional item.
[example...] Optional remainder of text.
<example> Required item.
<example...> Required remainder of text.
some|other Specific options.

Example

This is an example usage of the parameter system.

// Dependencies
const { Client, Intents } = require('discord.js');
const { lex, parse } = require('djs-extra/params');
const { token } = require('./config.json');

// Client
const client = new Client({ ws: { intents: Intents.ALL } });

// Ready Message
client.once('ready', () => console.log('The parameter testing bot is now online!'));

// Command Handler
client.on('message', async message => {

	// Validate
	if (message.author.bot || message.guild === null) return;

	// Check Prefix
	let text = message.content;
	if (!text.startsWith('!')) return;
	text = text.slice(1).trimLeft();

	// Apply Lexer
	const result = lex(text);
	if (result === undefined) return;

	// Check Command
	if (result.name === 'help') {

		// Apply Parser
		const output = await parse(result.items, result.text, client, message.guild, {

			// Usage
			'[category]': async category => {

				// Execute Command
				if (category.exists()) {
					category = category.string();
					await message.channel.send(`Category: ${category}`);
				} else {
					await message.channel.send('No category.');
				}

				// Return Something
				return 'Successfully executed command!';

			}

		});

		// Log Result
		console.log(output);

	}
});

// Discord Login
client.login(token);