refactor: rename Event to Listener (#218)

BREAKING CHANGE: Renamed `Event` to `Listener`
BREAKING CHANGE: Renamed `EventStore` to `ListenerStore`
BREAKING CHANGE: Changed events directory from `events` to `listeners`
BREAKING CHANGE: Renamed `SapphireClientOptions.loadDefaultErrorEvents` to `loadDefaultErrorListeners`
BREAKING CHANGE: Renamed `StoreRegistryEntries.events` to `StoreRegistryEntries.listeners`
BREAKING CHANGE: Refactored `Events` enum to be an object, so we can use discord.js's constants
BREAKING CHANGE: Renamed `Events.EventError` to `Events.ListenerError`
BREAKING CHANGE: Renamed `EventErrorPayload` to `ListenerErrorPayload`
BREAKING CHANGE: Renamed `Events.Ready` to `Events.ClientReady`
BREAKING CHANGE: Renamed `Events.Message` to `Events.MessageCreate`

Author: kyranet

README.md

@@ -24,7 +24,7 @@ Sapphire is a Discord bot framework built on top of [discord.js] for advanced an
 ## Features
 
 -   Written in TypeScript
--   Command Handler, Arguments, Pre-conditions and Events Store
+-   Command Handler, Arguments, Pre-conditions and Listeners Store
 -   Completely Modular and Extendable
 -   Advanced Plugins Support
 -   Supports many [plugins](https://github.com/sapphiredev/plugins)

guides/getting-started/CreatingEvents.md renamed to guides/getting-started/CreatingListeners.md

@@ -1,21 +1,21 @@
-# Creating events
+# Creating listeners
 
 ## Setting up the file structure
 
-Sapphire loads events the same way as it loads command, by automatically reading files in the `events` folder. You
-should now create such a folder, and add your first event in it.
+Sapphire loads events the same way as it loads command, by automatically reading files in the `listeners` folder. You
+should now create such a folder, and add your first listeners in it.
 
-### Ready event
+### Ready listener
 
-To create an event you simply need to create a file with the name of the event, in our case `ready.js`.
+To create an listener you simply need to create a file with the name of the listener, in our case `ready.js`.
 
-Each event is a class that extends from the base `Event` class from Sapphire. You need to extend it, and add a `run`
-method which works the same way as for commands.
+Each listener is a class that extends from the base `Listener` class from Sapphire. You need to extend it, and add a
+`run` method which works the same way as for commands.
 
 ```javascript
-const { Event } = require('@sapphire/framework');
+const { Listener } = require('@sapphire/framework');
 
-module.exports = class extends Event {
+module.exports = class extends Listener {
 	constructor(context) {
 		super(context, {
 			once: true
@@ -29,14 +29,14 @@ module.exports = class extends Event {
 ```
 
 The first parameter of `super` is the context, that is given in the constructor. You can then specify an
-{@link EventOptions} object, containing properties such as the emitter's, the event's name, and
-whether it should only be run once (`once`). The emitter defaults to the the client, and the event name default to the
-file name.
+{@link ListenerOptions} object, containing properties such as the emitter's, the listener's name, and
+whether it should only be run once (`once`). The emitter defaults to the the client, and the listener name default to
+the file name.
 
 The `run` method is the method that gets called when the event occurs. It takes whatever the events gives as argument.
 In our case, the ready events gives no information so we don't need any parameter.
 
-Every piece (events, commands etc) in sapphire has a `context` which can be accessed via
+Every piece (listeners, commands etc) in sapphire has a `container` which can be accessed via
 `this.container`. It is this container that contains the logger, the client and other properties. Here we access the
 logger via `this.container.logger` and call its `log` method to print a nicely formatted message in the console.
 

guides/getting-started/GettingStarted.md

@@ -56,7 +56,7 @@ You won't have any feedback on your console, and the bot won't respond to any ev
 ## Preparing your file structure
 
 You can now organize your project correctly by grouping files together in folders. This will allow it to scale more
-easily as you add commands, events and other features.
+easily as you add commands, listeners, and other features.
 The main folder, at the root of your project and containing all your code can be named `src` (for "source"). You can put
 your `main.js` file inside this `src` directory and check that your bot still boots when you run
 

src/errorEvents/CoreEventError.ts

@@ -1,8 +1,8 @@
 import type { PieceContext } from '@sapphire/pieces';
-import { Event } from '../lib/structures/Event';
+import { Listener } from '../lib/structures/Listener';
 import { CommandErrorPayload, Events } from '../lib/types/Events';
 
-export class CoreEvent extends Event<Events.CommandError> {
+export class CoreEvent extends Listener<typeof Events.CommandError> {
 	public constructor(context: PieceContext) {
 		super(context, { event: Events.CommandError });
 	}

src/errorEvents/CoreCommandError.ts renamed to src/errorListeners/CoreCommandError.ts

@@ -0,0 +1,14 @@
+import type { PieceContext } from '@sapphire/pieces';
+import { Listener } from '../lib/structures/Listener';
+import { ListenerErrorPayload, Events } from '../lib/types/Events';
+
+export class CoreEvent extends Listener<typeof Events.ListenerError> {
+	public constructor(context: PieceContext) {
+		super(context, { event: Events.ListenerError });
+	}
+
+	public run(error: Error, context: ListenerErrorPayload) {
+		const { name, event, path } = context.piece;
+		this.container.logger.error(`Encountered error on event listener "${name}" for event "${event}" at path "${path}"`, error);
+	}
+}

src/errorListeners/CoreEventError.ts

@@ -27,8 +27,8 @@ export * from './lib/structures/Argument';
 export * from './lib/structures/ArgumentStore';
 export * from './lib/structures/Command';
 export * from './lib/structures/CommandStore';
-export * from './lib/structures/Event';
-export * from './lib/structures/EventStore';
+export * from './lib/structures/Listener';
+export * from './lib/structures/ListenerStore';
 export * from './lib/structures/ExtendedArgument';
 export * from './lib/structures/Precondition';
 export * from './lib/structures/PreconditionStore';

src/index.ts

@@ -6,7 +6,7 @@ import type { Plugin } from './plugins/Plugin';
 import { PluginManager } from './plugins/PluginManager';
 import { ArgumentStore } from './structures/ArgumentStore';
 import { CommandStore } from './structures/CommandStore';
-import { EventStore } from './structures/EventStore';
+import { ListenerStore } from './structures/ListenerStore';
 import { PreconditionStore } from './structures/PreconditionStore';
 import { StoreRegistry } from './structures/StoreRegistry';
 import { PluginHook } from './types/Enums';
@@ -108,7 +108,7 @@ export interface SapphireClientOptions {
 	 * @since 1.0.0
 	 * @default true
 	 */
-	loadDefaultErrorEvents?: boolean;
+	loadDefaultErrorListeners?: boolean;
 }
 
 /**
@@ -237,9 +237,9 @@ export class SapphireClient extends Client {
 		this.stores
 			.register(new ArgumentStore().registerPath(join(__dirname, '..', 'arguments'))) //
 			.register(new CommandStore())
-			.register(new EventStore().registerPath(join(__dirname, '..', 'events')))
+			.register(new ListenerStore().registerPath(join(__dirname, '..', 'listeners')))
 			.register(new PreconditionStore().registerPath(join(__dirname, '..', 'preconditions')));
-		if (options.loadDefaultErrorEvents !== false) this.stores.get('events').registerPath(join(__dirname, '..', 'errorEvents'));
+		if (options.loadDefaultErrorListeners !== false) this.stores.get('listeners').registerPath(join(__dirname, '..', 'errorListeners'));
 
 		for (const plugin of SapphireClient.plugins.values(PluginHook.PostInitialization)) {
 			plugin.hook.call(this, options);

src/lib/SapphireClient.ts

@@ -5,44 +5,44 @@ import { Events } from '../types/Events';
 
 /**
  * The base event class. This class is abstract and is to be extended by subclasses, which should implement the methods. In
- * Sapphire's workflow, events are called when the emitter they listen on emits a new message with the same event name.
+ * Sapphire's workflow, listeners are called when the emitter they listen on emits a new message with the same event name.
  *
  * @example
  * ```typescript
  * // TypeScript:
- * import { Event, Events, PieceContext } from '@sapphire/framework';
+ * import { Events, Listener, PieceContext } from '@sapphire/framework';
  *
- * // Define a class extending `CoreEvent`, then export it.
+ * // Define a class extending `Listener`, then export it.
  * // NOTE: You can use `export default` or `export =` too.
- * export class CoreEvent extends Event<Events.Ready> {
+ * export class CoreListener extends Listener<typeof Events.Ready> {
  *   public constructor(context: PieceContext) {
  *     super(context, { event: Events.Ready, once: true });
  *   }
  *
  *   public run() {
- *     if (!this.container.client.id) this.container.client.id = this.container.client.user?.id ?? null;
+ *     this.container.client.id ??= this.container.client.user?.id ?? null;
  *   }
  * }
  * ```
  *
  * @example
  * ```javascript
  * // JavaScript:
- * const { Event, Events } = require('@sapphire/framework');
+ * const { Events, Listener } = require('@sapphire/framework');
  *
- * // Define a class extending `CoreEvent`, then export it.
- * module.exports = class CoreEvent extends Event {
+ * // Define a class extending `Listener`, then export it.
+ * module.exports = class CoreListener extends Listener {
  *   constructor(context) {
  *     super(context, { event: Events.Ready, once: true });
  *   }
  *
  *   run() {
- *     if (!this.container.client.id) this.container.client.id = this.container.client.user?.id ?? null;
+ *     this.container.client.id ??= this.container.client.user?.id ?? null;
  *   }
  * }
  * ```
  */
-export abstract class Event<E extends keyof ClientEvents | symbol = ''> extends Piece {
+export abstract class Listener<E extends keyof ClientEvents | symbol = ''> extends Piece {
 	public readonly emitter: EventEmitter | null;
 	public readonly event: string;
 	public readonly once: boolean;
@@ -85,7 +85,7 @@ export abstract class Event<E extends keyof ClientEvents | symbol = ''> extends
 		try {
 			await this.run(...args);
 		} catch (error) {
-			this.container.client.emit(Events.EventError, error, { piece: this });
+			this.container.client.emit(Events.ListenerError, error, { piece: this });
 		}
 	}
 

src/lib/structures/EventStore.ts

@@ -0,0 +1,8 @@
+import { Store } from '@sapphire/pieces';
+import { Listener } from './Listener';
+
+export class ListenerStore extends Store<Listener> {
+	public constructor() {
+		super(Listener as any, { name: 'listeners' });
+	}
+}

src/lib/structures/Event.ts renamed to src/lib/structures/Listener.ts

@@ -3,7 +3,7 @@ import { getRootData, Piece, Store } from '@sapphire/pieces';
 import { join } from 'path';
 import type { ArgumentStore } from './ArgumentStore';
 import type { CommandStore } from './CommandStore';
-import type { EventStore } from './EventStore';
+import type { ListenerStore } from './ListenerStore';
 import type { PreconditionStore } from './PreconditionStore';
 
 type Key = keyof StoreRegistryEntries;
@@ -40,14 +40,14 @@ export class StoreRegistry extends Collection<Key, Value> {
 	 * /home/me/my-bot
 	 * ├─ src
 	 * │  ├─ commands
-	 * │  ├─ events
+	 * │  ├─ listeners
 	 * │  └─ main.js
 	 * └─ package.json
 	 * ```
 	 *
-	 * And you run `node src/main.js`, the directories `/home/me/my-bot/src/commands` and `/home/me/my-bot/src/events` will
-	 * be registered for the commands and events stores respectively, since both directories are located in the same
-	 * directory as your main file.
+	 * And you run `node src/main.js`, the directories `/home/me/my-bot/src/commands` and `/home/me/my-bot/src/listeners`
+	 * will be registered for the commands and listeners stores respectively, since both directories are located in the
+	 * same directory as your main file.
 	 *
 	 * **Note**: this also registers directories for all other stores, even if they don't have a folder, this allows you
 	 * to create new pieces and hot-load them later anytime.
@@ -95,6 +95,6 @@ export interface StoreRegistry {
 export interface StoreRegistryEntries {
 	arguments: ArgumentStore;
 	commands: CommandStore;
-	events: EventStore;
+	listeners: ListenerStore;
 	preconditions: PreconditionStore;
 }