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

Param	Type	Description
ctx	Object	Object to store in global context

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

Param	Type	Default	Description
name	string		Name of the script, will be used as the actual filename
[value]	string	"''"	Initial value of the script

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

Param	Type	Description
name	string	Name of the script
value	string	New value of the script

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

Param	Type	Description
name	string	Name of the script

pluginScriptingClient.attach(name) ⇒ Promise

Attach to a script.

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

Param	Type	Description
name	string	Name of the script

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

Param	Type	Description
ctx	Object	Object to store in global context

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.

Param	Type	Default	Description
callback	function		Callback function to execute
[executeListener]	boolean	false	If true, execute the given callback immediately.

pluginScriptingServer.switch(dirname)

Switch the plugin to watch and use another directory

Kind: instance method of PluginScriptingServer

Param	Type	Description
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

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

Param	Type	Default	Description
name	string		Name of the script, will be used as the actual filename
[value]	string	"''"	Initial value of the script

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

Param	Type	Description
name	string	Name of the script
value	string	New value of the script

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

Param	Type	Description
name	string	Name of the script

pluginScriptingServer.attach(name) ⇒ Promise

Attach to a script.

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

Param	Type	Description
name	string	Name of the script

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.

Param	Type	Default	Description
callback	function		Callback function
[executeListener]	boolean	false	If true, execute the given callback immediately.

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

Param	Type	Description
callback	function	Callback function

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

Param	Type	Description
value	string	New source code for the script.

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