soundworks plugin for runtime distributed scripting.
- Installation
- Usage
- API
- ClientPluginScripting
- ServerPluginScripting
- SharedScript
- Development Notes
- Credits
- License
npm install @soundworks/plugin-scripting --save// src/server/index.js
import { Server } from '@soundworks/core/server.js';
import ServerPluginScripting from '@soundworks/plugin-scripting/server.js';
const server = new Server(config);
// register the plugin with an optional dirname
server.pluginManager.register('scripting', ServerPluginScripting, {
dirname: 'my-script',
});
await server.start();
// use the plugin once the server is started
const scripting = await server.pluginManager.get('scripting');Given that there is a file my-constants.js in the watched my-script directory:
// my-script/my-constants.js
export const answer = 42;// src/client/**/index.js
import { Client } from '@soundworks/core/client.js';
import ClientPluginScripting from '@soundworks/plugin-scripting/client.js';
const client = new Client(config);
// register the plugin
client.pluginManager.register('scripting', ClientPluginScripting);
await client.start();
// use the plugin once the client is started
const scripting = await client.pluginManager.get('scripting');
const script = await scripting.attach('my-constants');
const mod = await script.import();
console.log(mod.answer);
// > 42The shared scripts are stored in the file system as raw Javascript files located in the directory defined on the server side configuration of the plugin (cf. dirname option).
This is the responsibility of the code consuming the shared scripts to define the API that the scripts should expose.
The scripts are simple JavaScript modules that are re-bundled using esbuild each time their content is modified. As such, they can import installed dependencies (i.e. node_modules) or import other scripts. However, using such bundle leads to a restriction in Node.js clients, that can't import native addons directly (in such case you should inject the dependency into the script at runtime). This might change in the future as dynamic import/require of ES modules is more stable (cf. nodejs/help#2751).
Internally the scripting plugin relies on the @soundworks/plugin-filesystem plugin, which should be use to make any modifications in the script directory:
// register and get the scripting plugin
server.pluginManager.register('scripting', ServerPluginScripting, { dirname: 'my-script' });
await server.start();
const scripting = await server.pluginManager.get('scripting');
// create a new script in the 'my-script' directory using the scripting related filesystem
const code = `export function add(a, b) { return a + b }`;
await scripting.filesystem.writeFile('add.js', code);Extends ClientPlugin
Client-side representation of the soundworks' scripting plugin.
The constructor should never be called manually. The plugin will be
instantiated automatically when registered in the pluginManager
clientidoptions(optional, default{})
client.pluginManager.register('scripting', ClientPluginScripting, { dirname });Instance of the underlying filesystem plugin
Returns the list of all available scripts.
Returns Array
Return the SharedStateCollection of all the scripts underlying share states. Provided for build and error monitoring purposes. Can also be used to maintain a list of existing script, e.g. in a drop-down menu
If you want a full featured / executable Script instance, use the attach instead.
Returns Promise<SharedStateCollection>
Registers a global context object to be used in scripts. Note that the
context is store globally, so several scripting plugins running in parallel
will share the same underlying object. The global getGlobalScriptingContext
function will allow to retrieve the given object from within scripts.
ctxObject Object to store in global context
Attach to a script.
namestring Name of the script
Returns Promise<SharedScript> Promise that resolves on a new Script instance.
Extends ServerPlugin
Server-side representation of the soundworks' scripting plugin.
The constructor should never be called manually. The plugin will be
instantiated by soundworks when registered in the pluginManager
Available options:
dirname{String} - directory in which the script files are located
If no option is given, for example before a user selects a project, the plugin
will stay idle until switch is called.
server.pluginManager.register('scripting', ServerPluginScripting, { dirname });Type: object
Instance of the underlying filesystem plugin.
Returns the list of all available scripts.
Returns Array
Return the SharedStateCollection of all the scripts underlying share states.
Provided for build and error monitoring purposes.
If you want a full featured Script instance, see attach instead.
Returns Promise<SharedStateCollection>
Registers a global context object to be used in scripts. Note that the
context is store globally, so several scripting plugins running in parallel
will share the same underlying object. The global getGlobalScriptingContext
function will allow to retrieve the given object from within scripts.
ctxObject Object to store in global context
Register callback to execute when a script is created or deleted.
callbackFunction Callback function to executeexecuteListenerboolean If true, execute the given callback immediately. (optional, defaultfalse)
Returns Function Function that unregister the listener when executed.
Switch the plugin to watch and use another directory
dirname(String | Object) Path to the new directory. As a convenience to match the plugin filesystem API, an object containing the 'dirname' key can also be passed
Attach to a script.
namestring Name of the script
Returns Promise<SharedScript> Promise that resolves on a new Script instance.
A SharedScript can be distributed amongst different clients and modified at runtime.
The script source is stored directly in the filesystem, see dirname option
of the server-side plugin.
A Shared script cannot be instantiated manually, it is retrieved by calling
the ClientPluginScripting#attach or ServerPluginScripting#attach methods.
Name of the script (i.e. sanitized relative path)
Type: string
Filename from which the script is created.
Type: string
Error that may have occurred during the transpilation of the script. If no error occurred during transpilation, the attribute is set to null.
Type: string
Runtime error that may have occurred during the execution of the script. Runtime errors must be reported by the consumer code (cf. reportRuntimeError).
Type: string
Dynamically import the bundled module.
Returns Promise<Module> Promise which fulfills to the JS module.
Manually report an error catched in try / catch block.
This can be useful in situations where you want your script to expose a specific API:
const { expectedMethod } = await script.import();
if (!expectedMethod) {
const err = new Error('Invalid script "${script.name}": should export a "expectedMethod" function');
script.reportRuntimeError(err);
}Or when you want your code to continue after the script error, e.g.:
script.onUpdate(async updates => {
if (updates.browserBuild) {
if (mod) {
// we want to manually catch error that might be thrown in `exit()`
// because otherwise `mod`` would never be updated
try {
mod.exit();
} catch (err) {
script.reportRuntimeError(err);
}
}
mod = await script.import();
mod.enter();
}
}, true);errError
Detach the script.
Register a callback to be executed when the script is updated.
callbackFunction Callback functionexecuteListenerboolean If true, execute the given callback immediately. (optional, defaultfalse)
Returns Function Function that unregister the callback when executed.
Register a callback to be executed when the script is detached, i.e. when
detach as been called, or when the script has been deleted
callbackFunction Callback function