soundworks | plugin filesystem ​

soundworks plugin to watch directories and update their contents from any node.

Table of Contents ​

• Installation
• Usage
  • Server
  • Client
• Notes
  • Reading files
  • Security
• API
  • Classes
  • PluginFilesystemClient
  • PluginFilesystemServer
• Credits
• License

Installation ​

npm install @soundworks/plugin-filesystem --save

Usage ​

Server ​

// index.js
import { Server } from '@soundworks/core/server.js';
import pluginFilesystem from '@soundworks/plugin-filesystem/server.js';

const server = new Server();
server.pluginManager.register('filesystem', pluginFilesystem, {
  // path to the watched directory, can be relative to process.cwd()
  // or absolute, in all cases file paths in the tree will be normalized
  // to be relative to `process.cwd()`
  dirname: 'path/to/directory',
  // if defined, add an `url` to each tree node, that defines the
  // route at which the files are publicly accessible.
  publicPath: '',
});

await server.start();

const filesystem = await server.pluginManager.get('filesystem');
await filesystem.writeFile('my-file.txt', 'Hello Server');

Client ​

Registering the plugin ​

// index.js
import { Client } from '@soundworks/core/client.js';
import pluginFilesystem from '@soundworks/plugin-filesystem/client.js';

const client = new Client();
client.pluginManager.register('filesystem', pluginFilesystem, {});

await client.start();

const filesystem = await client.pluginManager.get('filesystem');
await filesystem.writeFile('my-file.txt', 'Hello Client');

Notes ​

Reading files ​

For now, the filesystem plugin does not provide any way to read files due to the impossibility to have consistent file representation between node and the browser, and to the large type of files that would require different handling or processing (e.g. image, sound, text).

According to your specific needs you can rely on other plugins (e.g. audio-buffer-loader) or on the state manager (e.g. for text files) to read and share the files.

Security ​

Being able to write and delete files from any connected client poses evident security questions, moreover if your application aims at running online. To prevent such issues, all sensible operations (i.e. other than listing the files) of the plugin are blocked if the env.type config option passed to the soundworks server is set to production.

In such case, only trusted clients that authentified by a login and password will be able to perform these operations.

See the config/env-**.js files to configure your application (@todo - tutorial).

API ​

Classes ​

PluginFilesystemClient

Client-side representation of the soundworks' filesystem plugin.

PluginFilesystemServer

Server-side representation of the soundworks' filesystem plugin.

PluginFilesystemClient ​

Client-side representation of the soundworks' filesystem plugin.

Kind: global class

• PluginFilesystemClient
  • .getTree() ⇒ Object
  • .onUpdate(callback, [executeListener]) ⇒ function
  • .getTreeAsUrlMap(filterExt, [keepExtension]) ⇒ Object
  • .findInTree(path) ⇒ Object
  • .writeFile(pathname, data) ⇒ Promise
  • .mkdir(pathname) ⇒ Promise
  • .rename(oldPath, newPath) ⇒ Promise
  • .rm(pathname) ⇒ Promise

pluginFilesystemClient.getTree() ⇒ Object ​

Return the current filesystem tree.

Kind: instance method of PluginFilesystemClient

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

Register a callback to execute when a file is created, modified or deleted on the underlying directory. The callback will receive the updated tree and the list of events describing the modifications made on the tree.

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

pluginFilesystemClient.getTreeAsUrlMap(filterExt, [keepExtension]) ⇒ Object ​

Return the tree as flat map of <filename, url>

Kind: instance method of PluginFilesystemClient
Returns: Object - Map of <filename, url>

pluginFilesystemClient.findInTree(path) ⇒ Object ​

Return a node from the tree matching the given path.

Kind: instance method of PluginFilesystemClient

pluginFilesystemClient.writeFile(pathname, data) ⇒ Promise ​

Write a file

Kind: instance method of PluginFilesystemClient

pluginFilesystemClient.mkdir(pathname) ⇒ Promise ​

Create a directory

Kind: instance method of PluginFilesystemClient

pluginFilesystemClient.rename(oldPath, newPath) ⇒ Promise ​

Rename a file or directory

Kind: instance method of PluginFilesystemClient

pluginFilesystemClient.rm(pathname) ⇒ Promise ​

Delete a file or directory

Kind: instance method of PluginFilesystemClient

PluginFilesystemServer ​

Server-side representation of the soundworks' filesystem plugin.

Kind: global class

• PluginFilesystemServer
  • new PluginFilesystemServer()
  • .switch(options)
  • .getTree() ⇒ Object
  • .onUpdate(callback, [executeListener]) ⇒ function
  • .findInTree(path) ⇒ Object
  • .writeFile(pathname, data) ⇒ Promise
  • .mkdir(pathname) ⇒ Promise
  • .rename(oldPath, newPath) ⇒ Promise
  • .rm(pathname) ⇒ Promise

new PluginFilesystemServer() ​

The constructor should never be called manually. The plugin will be instantiated by soundworks when registered in the pluginManager

Available options:

• dirname {String} - directory to watch into
• publicPath {String} - (optionnal) optionnal public path for the assets. If set, a route will be added to the router to serve the assets and an url entry will be added to each node of the tree.
• depth {String} - (optionnal) Maximum depth to watch in the file structure.

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('filesystem', filesystemPlugin, {
  dirname: 'my-dir',
  publicPath: 'assets'
});

pluginFilesystemServer.switch(options) ​

Switch the filesystem to a new directory, e.g. to change project while keeping the same plugin and related logic at hand.

Kind: instance method of PluginFilesystemServer

pluginFilesystemServer.getTree() ⇒ Object ​

Return the current filesystem tree.

Kind: instance method of PluginFilesystemServer

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

Register a callback to execute when a file is created, modified or deleted on the underlying directory. The callback will receive the updated tree and the list of events describing the modifications made on the tree.

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

pluginFilesystemServer.findInTree(path) ⇒ Object ​

Return a node from the tree matching the given path.

Kind: instance method of PluginFilesystemServer

pluginFilesystemServer.writeFile(pathname, data) ⇒ Promise ​

Write a file

Kind: instance method of PluginFilesystemServer

pluginFilesystemServer.mkdir(pathname) ⇒ Promise ​

Create a directory

Kind: instance method of PluginFilesystemServer

pluginFilesystemServer.rename(oldPath, newPath) ⇒ Promise ​

Rename a file or directory

Kind: instance method of PluginFilesystemServer

pluginFilesystemServer.rm(pathname) ⇒ Promise ​

Delete a file or directory

Kind: instance method of PluginFilesystemServer

Credits ​

https://soundworks.dev/credits.html

License ​

BSD-3-Clause