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);
// > 42
The 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
client
id
options
(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.
ctx
Object Object to store in global context
Attach to a script.
name
string 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.
ctx
Object Object to store in global context
Register callback to execute when a script is created or deleted.
callback
Function Callback function to executeexecuteListener
boolean 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.
name
string 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);
err
Error
Detach the script.
Register a callback to be executed when the script is updated.
callback
Function Callback functionexecuteListener
boolean 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
callback
Function Callback function