From 64378f09444ca5a3a6f42455d4b91483e612e620 Mon Sep 17 00:00:00 2001 From: Amgelo563 Date: Fri, 12 Apr 2024 20:27:25 -0500 Subject: [PATCH] docs: update middleware documentation, removing linked list mentions --- .../features/commands/command-interception.mdx | 11 +++++------ .../docs/features/events/event-dispatcher.mdx | 4 ++-- .../docs/features/events/event-interception.mdx | 15 +++++++-------- .../docs/features/events/event-overview.mdx | 4 ++-- .../schedules/schedule-interception.mdx | 11 +++++------ .../docs/features/sessions/session-executor.mdx | 2 +- .../features/sessions/session-interception.mdx | 17 ++++++++--------- .../docs/features/sessions/session-overview.mdx | 6 +++--- 8 files changed, 33 insertions(+), 37 deletions(-) diff --git a/apps/docs/docs/features/commands/command-interception.mdx b/apps/docs/docs/features/commands/command-interception.mdx index 47a997f1..389831f6 100644 --- a/apps/docs/docs/features/commands/command-interception.mdx +++ b/apps/docs/docs/features/commands/command-interception.mdx @@ -25,10 +25,9 @@ It consists of: When being checked, a middleware is passed the command that is being checked and the arguments that would be used to call it. The middleware then replies with a `MiddlewareResponse`, which can either: -* Allow the execution (`{ allowed: true }`), with either: -* Making the linked list check the next middleware (`{ allowed: true, checkNext: true }`). -* Forcing the chain to end (`{ allowed: true, checkNext: false }`). -* Deny the execution (`{ allowed: false, checkNext: false }`). +* Make the list check the next middleware: `{ allowed: true, checkNext: true }`. +* Forcing the execution to end as with an allowed result: `{ allowed: true, checkNext: false }`. +* Deny the execution: `{ allowed: false, checkNext: false }`. The `AbstractMiddleware`, has `protected` utility methods to generate these responses. Specifically, `this.true()`, `this.false()` and `this.forceTrue()`. @@ -62,7 +61,7 @@ You can create your own middleware by either: import { AbstractCommandMiddleware } from '@nyx-discord/framework'; class MyCommandMiddleware extends AbstractCommandMiddleware { - public check(command: ExecutableCommand, args: CommandExecutionArgs): MiddlewareResponse { + public check(command: ExecutableCommand, ...args: CommandExecutionArgs): MiddlewareResponse { return this.true(); } } @@ -94,7 +93,7 @@ bot.commands.getExecutor().getMiddleware().add(middleware); ``` -By default, the following middleware chain is used: +By default, the following middleware list is used: * `CommandFilterCheckMiddleware` - See [🚧 Command Filters](#-command-filters). diff --git a/apps/docs/docs/features/events/event-dispatcher.mdx b/apps/docs/docs/features/events/event-dispatcher.mdx index 5ca93e92..472be512 100644 --- a/apps/docs/docs/features/events/event-dispatcher.mdx +++ b/apps/docs/docs/features/events/event-dispatcher.mdx @@ -8,7 +8,7 @@ They are used by the `EventBus`, which passes to the dispatcher the subscribers The dispatcher is then responsible that for each subscriber: -* The `EventSubscriberMiddlewareLinkedList` passes the execution. +* The `SubscriberMiddlewareList` passes the execution. * The subscriber is executed with its respective arguments. * Any errors thrown by the subscriber or middleware are caught, wrapped if needed, and redirected to the `ErrorHandler`. @@ -88,7 +88,7 @@ This functionality can be turned off by setting it to `null` via `#setConcurrenc ## 🚦 Middleware -The dispatcher stores an `EventSubscriberMiddlewareLinkedList` that will either allow or deny the call of a given subscriber. +The dispatcher stores an `SubscriberMiddlewareList` that will either allow or deny the call of a given subscriber. This list can be obtained via `EventDispatcher#getMiddleware()`. For information about how to use it, check the [️🛡️ Event Interception](./event-interception) documentation. diff --git a/apps/docs/docs/features/events/event-interception.mdx b/apps/docs/docs/features/events/event-interception.mdx index 3c4397f3..ad2bd8ec 100644 --- a/apps/docs/docs/features/events/event-interception.mdx +++ b/apps/docs/docs/features/events/event-interception.mdx @@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem'; Event interception refers to blocking a subscriber from receiving an event. In nyx, there are two ways to do this: -1. Add an `EventSubscriberMiddleware` to the `EventSubscriberMiddlewareLinkedList` in the `EventDispatcher` that handles +1. Add an `EventSubscriberMiddleware` to the `SubscriberMiddlewareList` in the `EventDispatcher` that handles the event execution. 2. Provide an `EventSubscriberFilter` in the `EventSubscriber` that receives the event. @@ -17,7 +17,7 @@ Let's explore when and how to use each of these methods. ## 🚦 Subscriber Middlewares -`EventSubscriberMiddlewares` are objects stored on a `EventSubscriberMiddlewareLinkedList`, which is held and called by +`EventSubscriberMiddlewares` are objects stored on a `SubscriberMiddlewareList`, which is held and called by the event dispatcher every time an event is about to be notified to a subscriber. It consists of: @@ -27,10 +27,9 @@ It consists of: When being checked, a middleware is passed the subscriber that is being checked and the arguments that would be used to call it. The middleware then replies with a `MiddlewareResponse`, which can either: -* Allow the execution (`{ allowed: true }`), with either: -* Making the linked list check the next middleware (`{ allowed: true, checkNext: true }`). -* Forcing the chain to end (`{ allowed: true, checkNext: false }`). -* Deny the execution (`{ allowed: false, checkNext: false }`). +* Make the list check the next middleware: `{ allowed: true, checkNext: true }`. +* Forcing the execution to end as with an allowed result: `{ allowed: true, checkNext: false }`. +* Deny the execution: `{ allowed: false, checkNext: false }`. The `AbstractMiddleware`, has `protected` utility methods to generate these responses. Specifically, `this.true()`, `this.false()` and `this.forceTrue()`. @@ -77,7 +76,7 @@ import type { import { AbstractEventSubscriberMiddleware } from '@nyx-discord/framework'; class MyFrameworkEventSubscriberMiddleware extends AbstractEventSubscriberMiddleware { - public check(subscriber: EventSubscriber, args: EventDispatchArgs): MiddlewareResponse { + public check(subscriber: EventSubscriber, ...args: EventDispatchArgs): MiddlewareResponse { return this.true(); } } @@ -109,7 +108,7 @@ myBus.getDispatcher().getMiddleware().add(interfaceMiddleware); ``` -By default, the following middleware chain is used: +By default, the following middleware list is used: * `HandleCheckEventMiddleware` - See [✅ Event handling marking](event-subscriber#-event-handling-marking) on the `EventSubscriber` guide. diff --git a/apps/docs/docs/features/events/event-overview.mdx b/apps/docs/docs/features/events/event-overview.mdx index 83fc0116..36f378a8 100644 --- a/apps/docs/docs/features/events/event-overview.mdx +++ b/apps/docs/docs/features/events/event-overview.mdx @@ -21,7 +21,7 @@ Specifically, the event related objects are: of these objects. * `EventBuses`: Store and notify their subscribers when an event happens, using its `EventDispatcher`. * `EventDispatcher`: Stored by a bus, dispatches an event to the subscribers its passed, checking its -`EventSubscriberMiddlewareLinkedList` and passing any errors to its `ErrorHandler`. +`SubscriberMiddlewareList` and passing any errors to its `ErrorHandler`. * `EventSubscribers`: Objects that subscribe to an event emitted by an `EventBus`.
@@ -30,7 +30,7 @@ of these objects. 1. An object executes the `EventBus#emit()` method on an event bus, passing the emitted event and its arguments. 2. The bus gets the currently registered subscribers to said event. 3. The subscribers list and arguments are passed to the bus' `EventDispatcher`. - 4. For every subscriber, the dispatcher checks its `EventSubscriberMiddlewareLinkedList` which will allow or deny its + 4. For every subscriber, the dispatcher checks its `SubscriberMiddlewareList` which will allow or deny its notification to that subscriber. This includes checking the filter on `EventSubscriber#getFilter()`. 5. If allowed, the dispatcher will notify the subscriber, routing any errors to its `EventSubscriberErrorHandler`. diff --git a/apps/docs/docs/features/schedules/schedule-interception.mdx b/apps/docs/docs/features/schedules/schedule-interception.mdx index 1a3d05aa..2a925532 100644 --- a/apps/docs/docs/features/schedules/schedule-interception.mdx +++ b/apps/docs/docs/features/schedules/schedule-interception.mdx @@ -25,10 +25,9 @@ It consists of: When being checked, a middleware is passed the schedule that is being checked and the tick metadata. The schedule then replies with a `MiddlewareResponse`, which can either: -* Allow the execution (`{ allowed: true }`), with either: -* Making the linked list check the next middleware (`{ allowed: true, checkNext: true }`). -* Forcing the chain to end (`{ allowed: true, checkNext: false }`). -* Deny the execution (`{ allowed: false, checkNext: false }`). +* Make the list check the next middleware: `{ allowed: true, checkNext: true }`. +* Forcing the execution to end as with an allowed result: `{ allowed: true, checkNext: false }`. +* Deny the execution: `{ allowed: false, checkNext: false }`. The `AbstractMiddleware`, has `protected` utility methods to generate these responses. Specifically, `this.true()`, `this.false()` and `this.forceTrue()`. @@ -62,7 +61,7 @@ You can create your own middleware by either: import { AbstractScheduleMiddleware } from '@nyx-discord/framework'; class MyScheduleMiddleware extends AbstractScheduleMiddleware { - public check(schedule: Schedule, args: ScheduleTickArgs): MiddlewareResponse { + public check(schedule: Schedule, ...args: ScheduleTickArgs): MiddlewareResponse { return this.true(); } } @@ -94,7 +93,7 @@ bot.schedules.getExecutor().getMiddleware().add(middleware); ``` -By default, the following middleware chain is used: +By default, the following middleware list is used: * `ScheduleFilterCheckMiddleware` - See [🚧 Schedule Filters](#-Schedule-filters). diff --git a/apps/docs/docs/features/sessions/session-executor.mdx b/apps/docs/docs/features/sessions/session-executor.mdx index 5aa1f168..f168a5cd 100644 --- a/apps/docs/docs/features/sessions/session-executor.mdx +++ b/apps/docs/docs/features/sessions/session-executor.mdx @@ -11,7 +11,7 @@ The `SessionExecutor` is the object responsible for executing sessions. It's sto get it via `SessionManager#getExecutor()`. The executor manages that: -* The respective `SessionMiddlewareLinkedList` passes the execution. +* The respective `SessionMiddlewareList` passes the execution. * The session is executed with its respective arguments. * Any errors thrown by the session or middleware are caught, wrapped if needed, and redirected to the `ErrorHandler`. diff --git a/apps/docs/docs/features/sessions/session-interception.mdx b/apps/docs/docs/features/sessions/session-interception.mdx index 2688a755..6e2eea27 100644 --- a/apps/docs/docs/features/sessions/session-interception.mdx +++ b/apps/docs/docs/features/sessions/session-interception.mdx @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; Session interception refers to blocking a session from being executed. In nyx, there are two ways to do this: -1. Add a `SessionMiddleware` to the respective `SessionMiddlewareLinkedList` in the `SessionExecutor` that handles +1. Add a `SessionMiddleware` to the respective `SessionMiddlewareList` in the `SessionExecutor` that handles the session execution. 2. Provide the respective `SessionFilter` in the `Session`. @@ -15,7 +15,7 @@ Let's explore when and how to use each of these methods. ## 🚦 Session Middlewares -`SessionMiddlewares` are objects stored on a `SessionMiddlewareLinkedList`, which is held and called by +`SessionMiddlewares` are objects stored on a `SessionMiddlewareList`, which is held and called by the session executor when a session is about to be executed. Specifically, there are two types of session middlewares: @@ -29,10 +29,9 @@ Each consist of: When being checked, a middleware is passed the session that is being checked and the execution metadata. The session then replies with a `MiddlewareResponse`, which can either: -* Allow the execution (`{ allowed: true }`), with either: -* Making the linked list check the next middleware (`{ allowed: true, checkNext: true }`). -* Forcing the chain to end (`{ allowed: true, checkNext: false }`). -* Deny the execution (`{ allowed: false, checkNext: false }`). +* Make the list check the next middleware: `{ allowed: true, checkNext: true }`. +* Forcing the execution to end as with an allowed result: `{ allowed: true, checkNext: false }`. +* Deny the execution: `{ allowed: false, checkNext: false }`. The `AbstractMiddleware`, has `protected` utility methods to generate these responses. Specifically, `this.true()`, `this.false()` and `this.forceTrue()`. @@ -68,7 +67,7 @@ import { } from '@nyx-discord/framework'; class MySessionStartMiddleware extends AbstractSessionStartMiddleware { - public check(session: Session, args: SessionStartArgs): MiddlewareResponse { + public check(session: Session, ...args: SessionStartArgs): MiddlewareResponse { return this.true(); } } @@ -77,7 +76,7 @@ const startMiddleware = new MySessionStartMiddleware(); bot.sessions.getExecutor().getStartMiddleware().add(startMiddleware); class MySessionUpdateMiddleware extends AbstractSessionUpdateMiddleware { - public check(session: Session, args: SessionUpdateArgs): MiddlewareResponse { + public check(session: Session, ...args: SessionUpdateArgs): MiddlewareResponse { return this.true(); } } @@ -114,7 +113,7 @@ bot.sessions.getExecutor().getUpdateMiddleware().add(updateMiddleware); ``` -By default, the following middleware chain is used: +By default, the following middleware list is used: * `SessionFilterCheckMiddleware` - See [🚧 Session Filters](#-Session-filters). diff --git a/apps/docs/docs/features/sessions/session-overview.mdx b/apps/docs/docs/features/sessions/session-overview.mdx index 4d3d0d54..2c190692 100644 --- a/apps/docs/docs/features/sessions/session-overview.mdx +++ b/apps/docs/docs/features/sessions/session-overview.mdx @@ -34,7 +34,7 @@ Specifically, the session related objects are: * `SessionCustomIdCodec`: De/serializes session ids to/from customId strings, to create session components. This component allows you to create and manipulate `customIds` programatically, with no "magic values". * `SessionRepository`: Temporarily stores sessions until their TTL is over, and notifies the manager when that happens. * `SessionPromiseRepository`: Stores session promises that will be resolved once a given session ends. -* `SessionExecutor`: Executes sessions, checking its `SessionMiddlewareLinkedList` and passing any errors to its `ErrorHandler`. +* `SessionExecutor`: Executes sessions, checking its `SessionMiddlewareList` and passing any errors to its `ErrorHandler`. * `SessionUpdateSubscriber`: An [📩 Event Subscriber](../events/event-subscriber) that listens for interactions that can refer to sessions. * `EventBus`: An [📣 Event Bus](../events/event-bus) that emits session related events. @@ -68,7 +68,7 @@ There are three utility session types that derive from the main `Session` interf `SessionExecutor#handleMissing()`, which will handle the interaction referring to a missing (probably expired) session. If it does exist, it continues. 4. The `SessionManager` calls `SessionExecutor#update()` to handle the update, passing the interaction and session. - 5. The `SessionExecutor` checks its `SessionMiddlewareLinkedList` which will allow or deny the execution. + 5. The `SessionExecutor` checks its `SessionMiddlewareList` which will allow or deny the execution. This includes checking the filter on `Session#getUpdateFilter()`. 6. If the execution is allowed, the session is updated via `Session#update()`, passing any errors to its `SessionUpdateErrorHandler`, and returning what `Session#update()` returns. @@ -141,7 +141,7 @@ participant "SessionCustomIdCodec" as codec participant "SessionRepository" as repository participant "SessionExecutor" as executor participant "Session" as session -participant "SessionMiddlewareLinkedList" as middleware +participant "SessionMiddlewareList" as middleware participant "EventBus" as eventBus component -> subscriber : Emit interactionCreate