Scripts
When it comes to scripts, they are essentially classes that handle interactions within the same process as the main application, but can be called via the @sodacore/cli
package, which provides a simple to use CLI interface for running scripts.
When I built these, I intended originally to use a command line tool, but then I realised that in a lot of cases, sometimes a script may want to interact with the main application, for example, you may want to trigger the same code that a task would run, or potentially you might want to get resource statistics, etc.
So the current implementation is that a script runs within the same process as the main application, so you can access the current running application.
Enabling scripts
To enable scripts within your platform (by default they are disabled), you need to enable them within your initialisation code, for example:
const app = new Application({
enableCli: true, // This enables the CLI.
hostname: 'localhost', // The hostname to bind the application to.
port: 3001, // The port to bind the application to.
password: 'supersecret', // The password to protect the CLI with.
});
Once you add this, the CLI service will be started, and you will be able to connect to it.
Creating a script
To create a script, we simply create a class, and decorate it with the @Script()
decorator, for example:
import { type AsScript, Namespace, Scripts, ScriptContext } from '@sodacore/core';
@Namespace('example')
export class ExampleScript implements AsScript<ExampleScript> {
@Script('hello')
public async sayHello(ctx: ScriptContext) {
// Ask for a name.
const name = await ctx.prompts.text({
message: 'What is your name?',
});
ctx.log.info(`Hello, ${name}!`);
// Return something.
return 'Done!';
}
}
As you can see the types help with coalescing the response, and the ScriptContext
provides a few useful utilities, such as logging, prompts and more.
Running a script
To run a script for the first time there are a few steps we need to follow.
Install the CLI
To run a script, we first suggest installing the CLI package globally, for example:
bun add -g @sodacore/cli
Once you do this, you should be able to access the sodacore
command from anywhere.
Add a connection
To add a connection, you can simply follow the CLI prompts, for example:
Once you have done this, your connection will be saved locally, please note the password you set here is not encrypted, this will be a future feature.
Run the script
To run a script, run the CLI again, but instead of adding a connection, you will notice that there is a new option:
Access: <YourName>
This option will connect to your running application (of course, make sure your application is running first) and then you will be presented with a list of available commands from the core framework, as well as any plugins installed and any scripts you have created.
You can trigger a script by selecting it, and this will then call your script.
Interactive scripts
The scripts are interactive, so this means, the prompts actually create a bidirectional communication between the CLI and the main application, so you can ask for input, and then respond to it, this is actually used by the Discord
plugin, which exposes two mains scripts for registering and unregistering slash commands, either globally or to a specific guild, and it uses the prompts to ask for the relevant information.
Available helpers
As of right now the library uses the @clack/prompts
package to provide the prompts and clean interface, and you can read up the available prompts here.
The implemented features are:
Method | Parameters | Description |
---|---|---|
ctx.log.info | message: string | Log an info message. |
ctx.log.error | message: string | Log an error message. |
ctx.log.success | message: string | Log an success message. |
ctx.log.warning | message: string | Log a warning message. |
ctx.log.message | message: string | Log a message. |
ctx.log.warn | message: string | Log a warning message. |
ctx.log.step | message: string | Log a step message. |
ctx.prompts.text | options: Omit<TextOptions, 'validate'> | Prompt for a text input. |
ctx.prompts.confirm | options: ConfirmOptions | Prompt for a confirm input. |
ctx.prompts.select | options: SelectOptions<T> | Prompt for a select input. |
ctx.prompts.multiselect | options: MultiSelectOptions<T> | Prompt for a multi-select input. |
ctx.prompts.createGroup | void | Create a group of prompts using a class return you can add to. |
ctx.prompts.sendRequest | commands: IScriptPromptItem | A way to access the prompts manually without the wrapper. |
You can see an example of this here.