JavaScript API for SC

[Taitava]

#217 discusses about an integration between SC and Templater. There might come up some ideas that could be dealt with a more generic JavaScript API for SC, and so I decided to create this new discussion.

I've been thinking about an API for SC for some time now, but I don't have concrete plans yet, and so I actually first thought that I would not write about it yet. For now, I'll keep this quite short and only write about some rough ideas - I'll add more content in the future when the planning proceeds.

I must stress that many of the features planned here will take a lot of time to plan before implementation. Some might come sooner, while others might see daylight as late as in 1.0.0, which is still far in the future.

There will be different topics for the API:

• Call certain SC methods using JavaScript
• Make custom variables support JavaScript code
• Make other plugins able to create new {{variables}}
• Custom output channels
• Make other plugins able to create new output channels
• TODO: Write a plan for custom events, too.

I will create separate messages for each topics in this discussion, so that possible conversation can be easier to follow under each topic. More topics might be added later.

[Taitava]

Call certain SC methods using JavaScript

Not complete list of methods:

• sc.parseVariables(content: string): ParsingResult: Takes a string parameter and replaces all known {{variables}} in it with their current values. I'll describe the returned ParsingResult object later, but one of it's properties is parsed_content which contains the result string.
• sc.getVariableValue(variable_name: string, arguments: string[] = []): string: Gives a single {{variable}}'s value. More efficient than sc.parseVariables() when dealing with just a single variable, because it avoids a string parsing process.
• sc.execute(shell_command_id_or_instance): Promise<boolean>: Executes the given shell command, with all prerequisities taken into account, i.e. displays prompts and asks confirmation if needed. Returns a Promise that can tell if the shell command execution succeeded or not.
• sc.setCustomVariableValue(custom_variable_name_or_id, value: string): void: Changes the value of a custom variable. Use this before calling sc.execute() to pass custom values to a shell command.
• sc.getCustomVariableValue(custom_variable_name_or_id): string: Reads the current value of a custom variable. Might actually be redundant, as sc.getVariableValue() could be used for custom variables, too. Then again, this would have the ability to use id instead of name, while sc.getVariableValue() only supports name. More on the difference of id and name later.
• sc.toOutputChannel(output_streams: OutputStreams, error_code: number): void: Allows to utilize SC's output channels for performing certain actions or inserting content into different places (clipboard, current file, etc). Definition for OutputStreams in this same discussion.

The names and signatures of the methods might change, this is just a draft.

[Taitava]

Make custom variables support JavaScript code

Currently, custom variables can be set via prompts and (in the future) via Shell command URI.

I'd also like to create another type of custom variables, that would not be set via prompts or URI, but instead it would run custom JavaScript code (defined in the settings of the Shell commands plugin) and return the resulting value.

An important design principle with all variables is that their code should only read data without having any sideffects! This means, that a custom variable's JavaScript code should not perform any kind of modifications, including editing/manipulating files, calling other plugins in a way that does something else than reading values, doing automated actions in Obsidian, or or altering the state of Obsidian in any other way. Such program state altering actions can and should be done using other ways provided by this API.

Also, attention should be paid to the fact that variable reading might be cached, meaning that if a variable is used multiple times in the same parsing process (= usually means in a single shell command execution process), its value generator might only be called once. Caching may also be changed/developed further in the future. If a variable would perform side effects, the amount of how many times the side effects would occur might be unexpected.

[Taitava]

Make other plugins able to create new {{variables}}

These would probably be read-only variables, just like e.g. {{title}} is, not like custom variables, that can be set via prompts or Shell commands URI.

Example of how a plugin could define a new variable:

import Variable from ShellCommands;

if (/* A method for ensuring that the Shell commands plugin is installed and enabled. */) {
    class MyPluginVariable extends Variable {
        public variable_name = "my_plugin_variable"; // Becomes {{my_plugin_variable}} in real life.
    
        protected generateValue(): string {
            return "My plugin's value";
        }
    }
    sc.introduceVariable(MyPluginVariable);
}

This is a simplified example. It does not contain parameters for variables, but obviously those will be supported, too. Some other features are also missing from the example, but the main point was to demonstrate that variables are classes.

The design principles mentioned in the message above also apply to these plugin variables.

The variable naming convention

This needs to be still considered. Current naming conventions:

• Built-in variables defined by SC (e.g. {{title}}) start without an underscore _.
• Custom variables (e.g. {{_my_custom_variable}} start with an underscore _.
• This avoids collisions: new built-in variables in SC will never accidentally have the same names as custom variables defined by users.

Variables created by plugins should avoid collisions with both built-in variables and custom variables. One way to solve it would be to require all plugins to use a prefix, e.g. plugin_, so e.g. my_plugin_variable would become {{plugin_my_plugin_variable}}. The only downside is that the prefix makes variable names annoyingly long.

[Taitava]

Custom output channels

Custom JavaScript could be defined in the settings of SC to form a custom output channel. The form of a custom output channel could be something like this:

(output_streams: OutputStreams, error_code: number) => {
    if (undefined !== output_streams.stdout) {
        // Normal output text exists
        // Do something with output_streams.stdout
    }
    if (undefined !== output_streams.stderr) {
        // Error output text exists
        // Do something with output_streams.stderr
    }
    // If wanted, use error_code as an alternative way to determine if a command was executed successfully or not. If error_code is 0, the shell command executed ok - usually in this case stderr is undefined, but in some cases error_code may be 0 even if stderr contains some output. If error_codeis greater than 0, it can be used to identify which specific problem happened with the shell command (depends on what shell command(s) was/were executed).
}

It's an anonymous function that SC would use as a callback when any output is directed to this output channel. SC settings could offer this kind of boilerplate code as a starting point when a user wants to create a new custom output channel, so users don't need to wonder what to write into an empty JS textarea.

The current definition of OutputStreams:

export interface OutputStreams {
    stdout?: string;
    stderr?: string;
    // Later, if support for custom streams is implemented, this could contain variable amount of additional output streams, making it possible to utilize more (than two) different output channels for one shell command. E.g. _open a file_ using one output stream that defines the file name, display an info message using another stream with _Notification balloon_, and use a third output channel to put something into the _clipboard_.
}

[Taitava]

Make other plugins able to create new output channels

Similar to Custom output channels above. The main difference is that plugins could create classes that contain the JS code, no need to define the code in settings.

[Taitava]

Plugin developers could enroll their contact info when they use the API (voluntarily)

This is mostly just a note to myself. When the first version of the API gets released, I could create a discussion where each plugin developer can post a short message telling that they are using the API. Posting the message would not be any kind of requirement for using the API.

The reason for this kind of enrolling is that APIs evolve, and there may come times when I'd like to deprecate some old API methods, and eventually remove them after a grace period during which a newer, better method has been made available. The messages could tell what version of the API each plugin's newest version relies on (if I can, I'd want to make the API to have some kind of versioning mechanism, so that developers could define in the code, what version their code uses).

Having a list of plugins and developers that use the API, helps me to stay informed on what versions of the API are still in use, and if there are deprecated methods that almost nobody don't use anymore. Then I can clean up the API. For plugins that still seem to use deprecated methods, I could contact the authors and ask them to update their plugins to use a newer API version. I could perhaps even do pull requests for them.

A sample message that plugin authors could use when posting:

Developer name or nick name: Joh Doe
Discord user name and id (if the developer is in Discord): Username#1234
Plugins:
  - [Plugin name here](GitHub address for the plugin, pointing to either /issues or discussions/categories/a-category or to a specific issue/discussion (if one exists already) which I can use to ask about updating the plugin): API version `1.2.3` <-- This should indicate what version of SC API the plugin's NEWEST PUBLISHED version uses. So it's good to come back to edit this message whenever the plugin switches to use a newer API version.
  - ...

If the developer does not have any public plugins that would use the SC API, they might still want to post this message in case they are developing some private plugins they want to keep up-and-running regarding this API. Then they can just write to the Plugins: section: Only private plugins, inform me if API version 1.2.3 becomes deprecated.

---

As a recap, this was just a note for myself, but of course it can be commented. So far there's no need for anybody to enroll anywhere, as there's not yet an API to use in the first place.