soundworks | plugin scripting

soundworks plugin for runtime distributed scripting.

Table of Contents

• Installation
• Usage
• API
• ClientPluginScripting
• ServerPluginScripting
• SharedScript
• 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
• SharedScript
  • name
  • filename
  • buildError
  • runtimeError
  • import
  • reportRuntimeError
  • detach
  • onUpdate
  • onDetach

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.

SharedScript

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

Name of the script (i.e. sanitized relative path)

Type: string

filename

Filename from which the script is created.

Type: string

buildError

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

runtimeError

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

import

Dynamically import the bundled module.

Returns Promise<Module> Promise which fulfills to the JS module.

reportRuntimeError

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

Parameters

• err Error

detach

Detach the script.

onUpdate

Register a callback to be executed when the script is updated.

Parameters

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

Returns Function Function that removes the callback from the listeners when executed.

onDetach

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

Parameters

• callback Function Callback function

Development Notes

Credits

https://soundworks.dev/credits.html

License

BSD-3-Clause