soundworks | plugin scripting

soundworks plugin for runtime distributed scripting.

Table of Contents

• Installation
• Usage
• API
• ClientPluginScripting
• ServerPluginScripting
• Development Notes
• Credits
• License

Installation

npm install @soundworks/plugin-scripting --save

Usage

Server

// 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;

Client

// 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

Notes

Where do the scripts live

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.

Limitations

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. https://github.com/nodejs/help/issues/2751).

Creating / updating / deleting scripts

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);

API

Table of Contents

• ClientPluginScripting
  • Parameters
  • Examples
  • filesystem
  • getList
  • getCollection
  • setGlobalScriptingContext
  • attach
• ServerPluginScripting
  • Examples
  • options
  • filesystem
  • getList
  • getCollection
  • setGlobalScriptingContext
  • onUpdate
  • switch
  • attach

ClientPluginScripting

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

Parameters

• client
• id
• options (optional, default {})

Examples

client.pluginManager.register('scripting', ClientPluginScripting, { dirname });

filesystem

Instance of the underlying filesystem plugin

getList

Returns the list of all available scripts.

Returns Array

getCollection

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>

setGlobalScriptingContext

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.

Parameters

• ctx Object Object to store in global context

attach

Attach to a script.

Parameters

• name string Name of the script

Returns Promise<SharedScript> Promise that resolves on a new Script instance.

ServerPluginScripting

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.

documentation

Examples

server.pluginManager.register('scripting', ServerPluginScripting, { dirname });

options

Type: object

Properties

• dirname (string | null)? Path to the directory in which the script are located
• verbose boolean?

filesystem

Instance of the underlying filesystem plugin.

getList

Returns the list of all available scripts.

Returns Array

getCollection

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>

setGlobalScriptingContext

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.

Parameters

• ctx Object Object to store in global context

onUpdate

Register callback to execute when a script is created or deleted.

Parameters

• callback Function Callback function to execute
• executeListener boolean If true, execute the given callback immediately. (optional, default false)

Returns Function Function that unregister the listener when executed.

switch

Switch the plugin to watch and use another directory

Parameters

• 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

Attach to a script.

Parameters

• name string Name of the script

Returns Promise<SharedScript> Promise that resolves on a new Script instance.

Development Notes

Credits

https://soundworks.dev/credits.html

License

BSD-3-Clause