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.

Kind: global class

• PluginFilesystemClient
  • .getTree() ⇒ Object
  • .onUpdate(callback, [executeListener]) ⇒ function
  • .getTreeAsUrlMap(filterExt, [keepExtension]) ⇒ Object
  • .findInTree(pathOrUrl) ⇒ Object
  • .readFile(pathname) ⇒ Promise.<Blob>
  • .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.

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

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>

| Param | Type | Default | Description | | --- | --- | --- | --- | | filterExt | String | | File extension to retrieve in the list | | [keepExtension] | Boolean | false | Keep or remove the file extension from the keys |

pluginFilesystemClient.findInTree(pathOrUrl) ⇒ Object

Return a node from the tree matching the given path.

Kind: instance method of PluginFilesystemClient

| Param | Type | Description | | --- | --- | --- | | pathOrUrl | String | Path of the node to be retrieved, relative to options.dirname or URL of the node. |

pluginFilesystemClient.readFile(pathname) ⇒ Promise.<Blob>

Read a file

Kind: instance method of PluginFilesystemClient

| Param | Type | Description | | --- | --- | --- | | pathname | String | Pathname, relative to options.dirname. |

pluginFilesystemClient.writeFile(pathname, [data]) ⇒ Promise

Write a file

Kind: instance method of PluginFilesystemClient

| Param | Type | Default | Description | | --- | --- | --- | --- | | pathname | String | | Pathname, relative to options.dirname. | | [data] | String | File | Blob | '' | Content of the file. |

pluginFilesystemClient.mkdir(pathname) ⇒ Promise

Create a directory

Kind: instance method of PluginFilesystemClient

| Param | Type | Description | | --- | --- | --- | | pathname | String | Path of the directory, relative to options.dirname. |

pluginFilesystemClient.rename(oldPath, newPath) ⇒ Promise

Rename a file or directory

Kind: instance method of PluginFilesystemClient

| Param | Type | Description | | --- | --- | --- | | oldPath | String | Current pathname, relative to options.dirname. | | newPath | String | New pathname, relative to options.dirname. |

pluginFilesystemClient.rm(pathname) ⇒ Promise

Delete a file or directory

Kind: instance method of PluginFilesystemClient

| Param | Type | Description | | --- | --- | --- | | pathname | String | Pathname, relative to options.dirname. |

PluginFilesystemServer

Server-side representation of the soundworks' filesystem plugin.

Kind: global class

• PluginFilesystemServer
  • new PluginFilesystemServer()
  • .switch(options)
  • .getTree() ⇒ Object
  • .onUpdate(callback, [executeListener]) ⇒ function
  • .findInTree(pathname) ⇒ Object
  • .readFile(pathname) ⇒ Promise.<Blob>
  • .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

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | Object | | | | [options.dirname] | String | | directory to watch, plugin is idle if null | | [options.publicPath] | String | | 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. |

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.

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

pluginFilesystemServer.findInTree(pathname) ⇒ Object

Return a node from the tree matching the given path.

Kind: instance method of PluginFilesystemServer

| Param | Type | Description | | --- | --- | --- | | pathname | String | Pathname, relative to options.dirname. |

pluginFilesystemServer.readFile(pathname) ⇒ Promise.<Blob>

Read a file.

Kind: instance method of PluginFilesystemServer

| Param | Type | Description | | --- | --- | --- | | pathname | String | Pathname, relative to options.dirname. |

pluginFilesystemServer.writeFile(pathname, data) ⇒ Promise

Write a file

Kind: instance method of PluginFilesystemServer

| Param | Type | Description | | --- | --- | --- | | pathname | String | Pathname, relative to options.dirname. | | data | String | Blob | Content of the file. |

pluginFilesystemServer.mkdir(pathname) ⇒ Promise

Create a directory

Kind: instance method of PluginFilesystemServer

| Param | Type | Description | | --- | --- | --- | | pathname | String | Path of the directory, relative to options.dirname. |

pluginFilesystemServer.rename(oldPath, newPath) ⇒ Promise

Rename a file or directory

Kind: instance method of PluginFilesystemServer

| Param | Type | Description | | --- | --- | --- | | oldPath | String | Current pathname, relative to options.dirname. | | newPath | String | New pathname, relative to options.dirname. |

pluginFilesystemServer.rm(pathname) ⇒ Promise

Delete a file or directory

Kind: instance method of PluginFilesystemServer

| Param | Type | Description | | --- | --- | --- | | pathname | String | Pathname, relative to options.dirname. |

Credits

https://soundworks.dev/credits.html

License

BSD-3-Clause