Additional breaking changes were included to have better support for multiple shards, especially in multi-cluster environments.

🧷 Nexus Synchronizer

A new breaking change was introduced to the synchronizer to better optimize the synchronizer for multi-cluster environments wherein the server shard may not be in the current cluster. The following changes have been applied:

- CompletableFuture<Void> synchronize(int totalShards)
+ CompletableFuture<Void> synchronize()

- CompletableFuture<Void> batchUpdate(long serverId, DiscordApi shard)
+ CompletableFuture<Void> batchUpdate(long serverId)

- CompletableFuture<Void> batchUpdate(long serverId, int totalShards)

In summary, the changes are as follows:

• synchronize no longer requires the totalShards value.
• batchUpdate no longer requires the DiscordApi value
• a convenience method for batchUpdate was removed because there was no need for it anymore.

Additional changes were implemented onto the command events themselves to make life easier for the developers.

💬 Command Events

More ways to send a response over to Discord has been added for commands which should help sending responses so much easier. The following methods have been added:

fun respondNowWith(contents: String): CompletableFuture<InteractionOriginalResponseUpdater>
fun respondNowWith(vararg embeds: EmbedBuilder): CompletableFuture<InteractionOriginalResponseUpdater>

fun respondNowEphemerallyWith(contents: String): CompletableFuture<InteractionOriginalResponseUpdater>
fun respondNowEphemerallyWith(vararg embeds: EmbedBuilder): CompletableFuture<InteractionOriginalResponseUpdater>

And the following methods were removed since there is no real use for the following:

- fun getOptions(): List<SlashCommandInteractionOption>
- fun getSubcommandOptions(name: String): List<SlashCommandInteractionOption>

You can do now the following:

override fun onEvent(event: NexusCommandEvent) {
    event.respondNowWith("Pong!").exceptionally(ExceptionLogger.get())
}

It looks more verbose and cleaner than the following:

override fun onEvent(event: NexusCommandEvent) {
    event.respondNow().setContent("Pong!").respond().exceptionally(ExceptionLogger.get())
}

As Javacord v3.6.0 is now released, this PR needs to be fast-forwarded a bit more. To outline the final changes we need:

• Kotlin-first
• Support any new changes from Javacord, if any.
• Adds metedata indexing to help with bots that need to get the full information about the indexes such as which server this command belongs to, etc. This will replace the original indexing module by adding a two-parameter object with two fields (server?, command).
• and many others to follow.

An optimistic deadline for this change will be by November when I will be more free.

Nexus has officially transitioned into a Kotlin-first framework with majority of its functionality written in Kotlin. You can read the full changes of the Kotlin-first here.

An additional change that was implemented is Index Stores which is how we operate the Nexus Command Manager's Indexes from hereon as a move to flexibility with the framework. You can now customize the Index Store to collect indexes from the database, etc.

interface IndexStore {

    /**
     * Adds the [NexusMetaIndex] into the store which can be retrieved later on by methods such as
     * [get] when needed.
     * @param metaIndex the index to add into the index store.
     */
    fun add(metaIndex: NexusMetaIndex)

    /**
     * Gets the [NexusMetaIndex] from the store or an in-memory cache by the application command identifier.
     * @param applicationCommandId the application command identifier from Discord's side.
     * @return the [NexusMetaIndex] that was caught otherwise none.
     */
    operator fun get(applicationCommandId: Long): NexusMetaIndex?

    /**
     * Gets the [NexusMetaIndex] from the store or an in-memory cache by the Nexus unique identifier.
     * @param command the unique identifier of the command, tends to be of the same value always unless the name changed or
     * the unique identifier was changed via the [IdentifiableAs] annotation.
     * @return the [NexusMetaIndex] that was caught otherwise none.
     */
    operator fun get(command: String): NexusMetaIndex?

    /**
     * Adds one or more [NexusMetaIndex] into the store, this is used in scenarios such as mass-synchronization which
     * offers more than one indexes at the same time.
     *
     * @param metaIndexes the indexes to add into the store.
     */
    fun addAll(metaIndexes: List<NexusMetaIndex>)

    /**
     * Gets all the [NexusMetaIndex] available in the store, this is used more when the command manager's indexes are
     * exported somewhere.
     *
     * @return all the [NexusMetaIndex] known in the store.
     */
    fun all(): List<NexusMetaIndex>

    /**
     * Clears all the known indexes in the database. This happens when the command manager performs a re-indexing which
     * happens when the developer themselves has called for it.
     */
    fun clear()

}

A meta index is simply a data class that contains the following properties:

data class NexusMetaIndex(val command: String, val applicationCommandId: Long, val server: Long?)

Properties:

• command: the Nexus command's unique identifier
• applicationCommandId: the slash command's identifier in Discord.
• server: the server where the command is assigned. (this should be highly accurate if the indexes came from synchronization).

To understand how persistent indexes work, we have to understand a new key component in indexing and that is the unique identifier of a command. In Discord, there can be commands with the same name (one global, one per server) and that's fine until it is designed in a framework.

Nexus has been designed to assign the command name as the unique identifier of the command, but this has a problem, when two commands have the same name but different scopes, both have an index identifier conflict. It may seem like an issue at first, but there is a simpler fix to this and that is assigning a different unique identifier for the command.

The framework has been designed to identify potential index-identifier conflicts at runtime (when you add commands at Nexus), if Nexus finds that a command has the same unique identifier then it will throw an IndexIdentifierConflictException which tells you the instructions on how to resolve it.

To resolve the issue, all you need to do is add the @IdentifiableAs("...") annotation which overrides the command's unique identifier into another value. For example, let us say that we have two conflicting commands (one global, one server):

class PingCommand {
    val name = "ping"
}

class PingCommandServer {
   val name = "ping"
}

Nexus will complain that the two commands have the same unique identifier which leads to a IndexIdentifierConflictException but this can be easily resolved by changing one of the commands' unique identifier such as it becomes:

class PingCommand {
    val name = "ping"
}

@IdentifiableAs("ping-server")
class PingCommandServer {
   val name = "ping"
   ...
}

And that resolves the conflict, the two commands will operate as usual. (in terms of hierarchy, server commands take more priority than global commands).

Nexus 1.0 is now ready for official release with the following latest changes and breaking changes from the 1.0.0-next.

Breaking Changes

NexusCommandInterceptor

Methods to add interceptors such as middlewares and afterwares in the NexusCommandInterceptor interface has been removed completely in favor of Nexus.interceptors, this is to keep the API more consistent across the board.

Migration:

- NexusCommandInterceptor.addMiddleware("key") { ... }
+ Nexus.interceptors.middleware("key") { ... }

-  NexusCommandInterceptor.middleware { ... }
+ Nexus.interceptors.middleware { ... }

NexusCommandInterceptorRepository

We're removing this altogether because there is no point in bringing this when it simply just does the same thing as the newer style but under a define function.

Migration:

- object SomeRepository: NexusCommandInterceptorRepository {
-    val SOME_MIDDLEWARE: String = "some.middleware"
-    override fun define() {
-        middleware(SOME_MIDDLEWARE) { ... }
-    }
- }

+ object SomeRepository {
+    val SOME_MIDDLEWARE: String = Nexus.interceptors.middleware("some.middleware") { ... }
+ }

cooldown in NexusCommand

We've removed cooldown field as a native field in NexusCommand, this is, in order to keep things more consistent, as we do not offer the Ratelimiter as a Nexus-Native middleware (like OptionValidation is).

Migration:

- val cooldown = Duration.ofSeconds(5)
+ @Share val cooldown = Duration.ofSeconds(5)

NexusCommonInterceptors

We recently changed NexusCommonInterceptors from a interface to an singleton, so this may cause some import issues for some people. Don't worry, just reimport it!

NexusLoggingAdapter

We recently changed the internal methods of Nexus to pass exceptions in the parameters of Nexus.logger without any placeholders (not that we even use placeholders now as we use Kotlin), so you may see exceptions being passed as a parameter even though there are no placeholders.

NexusCommand

We've removed older methods that have long been marked for deprecation, the following functions were moved:

- fun addSupportFor(vararg serverIds: Long): NexusCommand
- fun removeSupportFor(vararg serverIds: Long): NexusCommand
- fun getServerId(): Long

Migration:

val command = ...
command.associate(serverIds)
command.disassociate(serverIds)

# Same behavior as the old `NexusCommand#getServerId`
command.serverIds.first()

Major Changes

Context Menus

First-class support for context menus (user and message) in Nexus is now supported. This will make it so that we don't have to use some sketchy methods to prevent your context menus from being overridden, and this makes it easier to use Nexus with context menus.

object TestUserContextMenu: NexusUserContextMenu() {
    val name = "test"
    override fun onEvent(event: NexusContextMenuEvent<UserContextMenuCommandEvent, UserContextMenuInteraction>) {
        event.respondNowEphemerallyWith("Hello")
    }
}

object TestMessageContextMenu: NexusMessageContextMenu() {
    val name = "test"
    override fun onEvent(event: NexusContextMenuEvent<MessageContextMenuCommandEvent, MessageContextMenuInteraction>) {
        event.respondNowEphemerallyWith("Hello")
    }
}

Nexus.contextMenus(TestUserContextMenu, TestMessageContextMenu)

Failed Dispatch Afterwares

Afterwares can now listen to failed dispatch events which will significantly help with logging and analytical afterwares. Previously, afterwares weren't able to execute after a command failed to dispatch (e.g. a middleware rejecting dispatch), but now, we can listen to these events and even know which middleware caused the problem by using NexusCommandEvent.get(NexusAfterware.BLOCKING_MIDDLEWARE_KEY).

A prime example of this mechanism is the new NexusCommonInterceptors.LOG middleware:

object  SomeAfterware: NexusAfterware {
   override fun onAfterCommandExecution(event: NexusCommandEvent) {}
   override fun onFailedDispatch(event: NexusCommandEvent) {} // optional
}

log common afterware

We now have our first common afterware, and it's the NexusCommonInterceptors.LOG afterware which helps you log commands easily. This uses the Nexus.logger to log.

Minor Changes

1. Some behavioral changes have been done to NexusConsoleLoggingAdapter.
   • We now log to stderr instead of stdout for errors.
   • Exceptions are now handled through the logging adapter.
2. Added more utilities to NexusMessage (Kotlin-only).
   • EmbedBuilder.toNexusMessage()
   • String.toNexusMessage()
3. Added support for inheritance parents with superclass fields, this will make it so parent inheritance can extend upon superclasses (e.g. abstract classes) and still copy the fields from there.
4. Added support for superclasses in commands (e.g extending abstract classes).
5. Nexus will now automatically use NexusConsoleLoggingAdapter when there is no SLF4J logger (as the default logger caused issues wherein exceptions would be ignored as there was no adapter to handle them a.k.a NOP)
6. A new reflection engine has replaced the previous, making things significantantly easier to add and also making things easier to maintain.
7. Added some incomplete support for nsfw field for both context and slash commands.
   • Due to Javacord issues, we cannot update the application command's nsfw field using the SlashCommandUpdater because it's missing on the current stable version of Javacord. This does not affect Nexus.synchronizer.synchronize() and Nexus.synchronizer.batchUpdate(server) as those methods uses bulkOverwrite which overwrites the entire commands altogether, allowing updates for those.
8. You can now include additional ApplicationCommandBuilder to Nexus.synchronizer through Nexus.synchronize.include(server, commands). This is intended when you want to add your own little other stuff e.g. custom context menus that doesn't use Nexus.
9. Added NexusCommandEvent.get(key) that returns an Object (or Any for Kotlin) as there are cases where our little type-casting doesn't really work, so we'd prefer doing it on our own.
10. Fixed wiki links on documentations.
11. A warning is now sent when you try to add @Inherits to an inheritance parent (as that isn't really supported), @Inherits should only be on children.
12. We now use Nexus.launcher to dispatch all events, so you can now use coroutines or related.