soundworks | plugin scripting ​

soundworks plugin for runtime distributed scripting.

Table of Contents ​

• Installation
• Usage
  • Server
  • Client
  • Notes
• API
  • Classes
  • PluginScriptingClient
  • PluginScriptingServer
  • SharedScript
• Credits
• License

Installation ​

npm install @soundworks/plugin-scripting --save

Usage ​

Server ​

// src/server/index.js
import { Server } from '@soundworks/core/server.js';
import pluginScripting from '@soundworks/plugin-scripting/server.js';

const server = new Server(config);
// register the plugin with an optionnal dirname
server.pluginManager.register('scripting', pluginScripting, {
  dirname: 'my-script',
});
await server.start();
// use the plugin once the server is started
const scripting = await server.pluginManager.get('scripting');
scripting.createScript('my-constants', 'export const answer = 42;')

Client ​

// src/client/**/index.js
import { Client } from '@soundworks/core/client.js';
import pluginScripting from '@soundworks/plugin-scripting/client.js';

const client = new Client(config);
// register the plugin
client.pluginManager.register('scripting', pluginScripting);
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);

Notes ​

The shared scripts are stored in the file system as raw Javascript files located in the directory defined on the server side (cf. dirname option).

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.

For now, only named exports are supported. This is the responsibility of the code consuming the shared scripts to define the API that the scripts should expose.

Internally the scripting plugin relies on the @soundworks/plugin-filesystem plugin. As such, it provide the same security restrictions, i.e. in production mode only authentified and trusted clients are allowed to modify the scripts.

API ​

Classes ​

PluginScriptingClient

Client-side representation of the soundworks' scripting plugin.

PluginScriptingServer

Server-side representation of the soundworks' scripting plugin.

SharedScript

A SharedScript can be distributed amongst different clients and modified at runtime. The script source is stored directly in the filestem, see dirname option of the server-side plugin. A Shared script cannot be instatiated manually, it is retrieved by calling the client's or server PluScritping.attach method.

PluginScriptingClient ​

Client-side representation of the soundworks' scripting plugin.

Kind: global class

• PluginScriptingClient
  • .setGlobalScriptingContext(ctx)
  • .getList() ⇒ Array
  • .getTree() ⇒ Object
  • .createScript(name, [value]) ⇒ Promise
  • .updateScript(name, value) ⇒ Promise
  • .deleteScript(name) ⇒ Promise
  • .attach(name) ⇒ Promise

pluginScriptingClient.setGlobalScriptingContext(ctx) ​

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.

Kind: instance method of PluginScriptingClient

pluginScriptingClient.getList() ⇒ Array ​

Returns the list of all available scripts.

Kind: instance method of PluginScriptingClient

pluginScriptingClient.getTree() ⇒ Object ​

Convenience method that return the underlying filesystem tree. Can be usefull to reuse components created for the filesystem (e.g. sc-filesystem)

Kind: instance method of PluginScriptingClient

pluginScriptingClient.createScript(name, [value]) ⇒ Promise ​

Create a new script. The returned promise resolves when all underlyings states, files and script instances are up-to-date.

Kind: instance method of PluginScriptingClient

pluginScriptingClient.updateScript(name, value) ⇒ Promise ​

Update an existing script. The returned promise resolves when all underlyings states, files and script instances are up-to-date.

Kind: instance method of PluginScriptingClient

pluginScriptingClient.deleteScript(name) ⇒ Promise ​

Delete a script. The returned promise resolves when all underlyings states, files and script instances are up-to-date.

Kind: instance method of PluginScriptingClient

pluginScriptingClient.attach(name) ⇒ Promise ​

Attach to a script.

Kind: instance method of PluginScriptingClient
Returns: Promise - Promise that resolves on a new Script instance.

PluginScriptingServer ​

Server-side representation of the soundworks' scripting plugin.

Kind: global class

• PluginScriptingServer
  • new PluginScriptingServer()
  • .setGlobalScriptingContext(ctx)
  • .getList() ⇒ Array
  • .getTree() ⇒ Object
  • .onUpdate(callback, [executeListener]) ⇒ function
  • .switch(dirname)
  • .createScript(name, [value]) ⇒ Promise
  • .updateScript(name, value) ⇒ Promise
  • .deleteScript(name) ⇒ Promise
  • .attach(name) ⇒ Promise

new PluginScriptingServer() ​

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.

Example

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

pluginScriptingServer.setGlobalScriptingContext(ctx) ​

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.

Kind: instance method of PluginScriptingServer

pluginScriptingServer.getList() ⇒ Array ​

Returns the list of all available scripts.

Kind: instance method of PluginScriptingServer

pluginScriptingServer.getTree() ⇒ Object ​

Convenience method that return the underlying filesystem tree. Can be usefull to reuse components created for the filesystem (e.g. sc-filesystem)

Kind: instance method of PluginScriptingServer

pluginScriptingServer.onUpdate(callback, [executeListener]) ⇒ function ​

Register callback to execute when a script is created or deleted. The callback will receive the updated list of script names and the updated file tree.

Kind: instance method of PluginScriptingServer
Returns: function - Function that unregister the listener when executed.

pluginScriptingServer.switch(dirname) ​

Switch the plugin to watch and use another directory

Kind: instance method of PluginScriptingServer

pluginScriptingServer.createScript(name, [value]) ⇒ Promise ​

Create a new script. The returned promise resolves when all underlyings states, files and script instances are up-to-date.

Kind: instance method of PluginScriptingServer

pluginScriptingServer.updateScript(name, value) ⇒ Promise ​

Update an existing script. The returned promise resolves when all underlyings states, files and script instances are up-to-date.

Kind: instance method of PluginScriptingServer

pluginScriptingServer.deleteScript(name) ⇒ Promise ​

Delete a script. The returned promise resolves when all underlyings states, files and script instances are up-to-date.

Kind: instance method of PluginScriptingServer

pluginScriptingServer.attach(name) ⇒ Promise ​

Attach to a script.

Kind: instance method of PluginScriptingServer
Returns: Promise - 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 filestem, see dirname option of the server-side plugin. A Shared script cannot be instatiated manually, it is retrieved by calling the client's or server PluScritping.attach method.

Kind: global class

• SharedScript
  • .source : string
  • .error : string
  • .transpiled : string
  • .import() ⇒ Promise
  • .detach()
  • .onUpdate(callback, [executeListener]) ⇒ function
  • .onDetach(callback)
  • .update(value)
  • .delete()

sharedScript.source : string ​

Kind: instance property of SharedScript
Read only: true

sharedScript.error : string ​

Kind: instance property of SharedScript
Read only: true

sharedScript.transpiled : string ​

Kind: instance property of SharedScript
Read only: true

sharedScript.import() ⇒ Promise ​

Dynamically import the transpiled module. https://caniuse.com/?search=import()

Kind: instance method of SharedScript
Returns: Promise - Promise which fulfills to an object containing all exports the script.

sharedScript.detach() ​

Stop listening for updates

Kind: instance method of SharedScript

sharedScript.onUpdate(callback, [executeListener]) ⇒ function ​

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

Kind: instance method of SharedScript
Returns: function - Function that unregister the callback when executed.

sharedScript.onDetach(callback) ​

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

Kind: instance method of SharedScript

sharedScript.update(value) ​

Alias for plugin.updateScript(name, value), calling this method will update the source of the script. The update will be propagated to all attached scripts

Kind: instance method of SharedScript

sharedScript.delete() ​

Alias for plugin.deleteScript(name), calling this method will entirely delete the script: the file and all associated scripts. If you just want to stop using the current script without deleting it, call detach instead

Kind: instance method of SharedScript

Credits ​

https://soundworks.dev/credits.html

License ​

BSD-3-Clause