Turning to Kotlin-first

[ShindouMihou]

As part of maintainability changes and the major beta change, Nexus will be moving to a Kotlin-first approach (where patterns and designs of the library will be based on what feels natural and better in Kotlin). As this change is massive, a dedicated discussion has been created to discuss the different changes that will be coming to Nexus over time.

Note

As of writing, this change hasn't been applied to the 1.0.0-beta pull request. It will take some time before this change will be applied considering how massive this will be. Stay tuned to the discussion to be notified when the change is pushed.

🥡 One Nexus, One Beauty

Nexus is not simply a command handler, it's a framework laid on top of Javacord to make the development of interaction-based Discord bots much simpler, and as part of this, we'll be removing the ability to create different Nexus instances. Adhering to the belief that a project should contain only that project, Nexus will no longer support multi-bot projects.

As an added benefit of this change, we are now able to access the Nexus instance easily throughout different Nexus modules. Another change with One Nexus is that we define commands in a more functional manner with a simpler configuration, in adherence with the functional approach, we have removed support for simply defining a command (since those were super unused methods). All commands will now be waiting for events immediately after registering.

A sample of how we register commands in the new One Nexus approach would be:

Nexus.commands {
    command { PingCommand }
    command { AvatarCommand }
}

Another sample of how we configure Nexus now would be:

Nexus.configure {
    express.maximumTimeout = Duration.ofMinutes(15)
}

🛒 Express Way

As part of this massive change, we have renamed EngineX into a simpler name called Express (or Express Way). This change doesn't add much other than the entire engine being rewritten to Kotlin, but other than that, the entire Express Way interface is the same as how the original EngineX appeared.

Nexus.express.await(shard = 0)
Nexus.express.queue(shard = 0) { shard -> ... }

🧰 Extensions

Nexus will come with a few extensions built in from the get-go such as a simple embed extension that will allow you to make embeds in a little Kotlin manner.

embed {
     setTitle("Hello World")
     setDescription("Next!")
}

🔍 Sharding Manager

Per the Kotlin change, the entire sharding manager will be changed to a more simpler and beautiful module with the use of operator overloading and more self-representing function names. An example of how we are adding new shards would be as follows:

val shard: DiscordApi = ...
Nexus.sharding[shard.currentShard] = shard

A sample of how we use the new interface:

val shard: DiscordApi? = Nexus.sharding.find { shard -> shard.getServerById(...).isPresent }
val server: Server? = Nexus.sharding.server(id = ...)
val shardOfServer: DiscordApi? = Nexus.sharding.shard(server = ...)

val shardNumberOfServer: Int = Nexus.sharding.calculate(snowflake = ...)

All the methods now no longer use Optional but rather uses the nullable types of Kotlin which feels more native to use in the language.

🔨 Command Manager

Similar to the sharding manager, the command manager has been rewritten once more to be more native to Kotlin users. A sample of how we use the new command manager would be:

// Searching for a single command without a specified server.
val command: NexusCommand? = Nexus.commandManager[name = "ping", server = null]

// Searching for a single command with a specific associated server.
val command: NexusCommand? = Nexus.commandManager[name = "ping", server = ...]

// Searching for a command given their application id (this can be empty when there is no index)
val command: NexusCommand?  =  Nexus.commandManager[applicationId = ...]

// Searching for a command given their unique identifier (this is most used internally rather than externally)
val command: NexusCommand? = Nexus.commandManager[uuid = ...]

There are more changes approaching especially with older features, stay tuned to this discussion to find out what more is coming in the beta release.

[ShindouMihou]

After careful consideration, the concept Contextful Nexus has been abandoned, but, that is not to say that there have no been changes that came from the concept. In fact, a new feature has been introduced that was brought forth from the Contextful Nexus and that is Option Validators.

⚙️ Option Validators

Option Validators is a means of ensuring that all the options provided are proper and of the correct format (you may use it to validate ahead of time that the options exist in the database or API). It's a very simple and basic feature with a simple example of an option validator being (from Amelia-chan):

object FeedsCommand: NexusHandler {

    private const val name = "feeds"
    private const val description = "Views all the feeds that are registered for this server."

    private val options = listOf(
        SlashCommandOption.createLongOption("id", "The id of the feed to look-up.", false)
    )

    val validators = listOf(
        createValidator(
            collector = { event -> event.interaction.getOptionLongValueByName("id") },
            validator = { id -> id <= 9999 },
            error = ValidationError.Companion.create("A feed identifier has at maximum 4 digits of numbers (0-9999).")
        )
    )
    ...
}

You can customize the ValidationError further by adding a function such as this:

ValidationError.Companion.create("A feed identifier has at maximum 4 digits of numbers (0-9999).") {
     ephemeral = true
     allowedMentions = AllowedMentionsBuilder().build()
}

ValidationError can also come in embeds via the ValidationError.Companion.create(EmbedBuilder) method.

You can also customize the validator to also not require non-null options such as in this:

    val validators = listOf(
        createValidator(
            collector = { event -> event.interaction.getOptionLongValueByName("id") },
            validator = { id -> id <= 9999 },
            error = ValidationError.Companion.create("A feed identifier has at maximum 4 digits of numbers (0-9999)."),
            requirements = OptionValidation.createRequirements {
                nonNull = null
            }
        )
    )

You may also customize the "required non-null" error such as the likes of this:

    val validators = listOf(
        createValidator(
            collector = { event -> event.interaction.getOptionLongValueByName("id") },
            validator = { id -> id <= 9999 },
            error = ValidationError.Companion.create("A feed identifier has at maximum 4 digits of numbers (0-9999)."),
            requirements = OptionValidation.createRequirements {
                nonNull = createErrorableRequireSetting(ValidationError.Companion.create("You cannot leave the `feed` option."))
            }
        )
    )

All-in-all, validations are there for when one needs them. It's not required to be used in Nexus and one can always opt to use their own native ways to validate options, but it's still there if anyone neds it.