@soundworks/plugin-scripting

2.0.0-alpha.1 • Public • Published

soundworks | plugin scripting

npm version

soundworks plugin for runtime distributed scripting.

Table of Contents

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)

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

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

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

Readme

Keywords

none

Package Sidebar

Install

npm i @soundworks/plugin-scripting

Weekly Downloads

56

Version

2.0.0-alpha.1

License

BSD-3-Clause

Unpacked Size

43.7 kB

Total Files

7

Last publish

Collaborators

  • jipodine
  • b-ma