soundworks | plugin filesystem

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

Table of Contents

• Installation
• Usage
• Security Note
• API
• ClientPluginFilesystem
• ServerPluginFilesystem
• formatTreeAsUrlMap
• Credits
• License

Installation

npm install @soundworks/plugin-filesystem --save

Usage

Server

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

const server = new Server();
server.pluginManager.register('filesystem', ServerPluginFilesystem, {
  // 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

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

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

await client.start();

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

Security Note

Being able to write and delete files from any connected client can create obvious security issues, 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 Server is set to production. In this case, only authenticated and trusted clients will be able to perform these operations.

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

API

Table of Contents

• ClientPluginFilesystem
  • getTree
  • onUpdate
  • getTreeAsUrlMap
  • findInTree
  • readFile
  • writeFile
  • mkdir
  • rename
  • rm
• ServerPluginFilesystem
  • Examples
  • switch
  • getTree
  • getTreeAsUrlMap
  • onUpdate
  • findInTree
  • readFile
  • writeFile
  • mkdir
  • rename
  • rm
• formatTreeAsUrlMap
  • Parameters

ClientPluginFilesystem

Extends ClientPlugin

Client-side representation of the soundworks' filesystem plugin.

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

getTree

Return the current filesystem tree.

Returns Object

onUpdate

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.

Parameters

• callback Function Callback function to execute
• executeListener boolean If true, execute the given callback immediately. (optional, default false)

Returns Function Function that unregister the listener when executed.

getTreeAsUrlMap

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

Parameters

• filterExt String File extension to retrieve in the list
• keepExtension Boolean Keep or remove the file extension from the keys (optional, default false)

Returns Object Map of <filename, url>

findInTree

Return a node from the tree matching the given path.

Parameters

• pathOrUrl String Path of the node to be retrieved, relative to options.dirname or URL of the node.

Returns Object

readFile

Read a file

Parameters

• pathname String Pathname, relative to options.dirname.

Returns Promise<Blob>

writeFile

Write a file

Parameters

• pathname String Pathname, relative to options.dirname.
• data (String | File | Blob) Content of the file. (optional, default '')

Returns Promise

mkdir

Create a directory

Parameters

• pathname String Path of the directory, relative to options.dirname.

Returns Promise

rename

Rename a file or directory

Parameters

• oldPath String Current pathname, relative to options.dirname.
• newPath String New pathname, relative to options.dirname.

Returns Promise

rm

Delete a file or directory

Parameters

• pathname String Pathname, relative to options.dirname.

Returns Promise

ServerPluginFilesystem

Extends ServerPlugin

Server-side representation of the soundworks' filesystem plugin.

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

Available options:

• dirname {String} - directory to watch into
• publicPath {String} - (optional) optional 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} - (optional) 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.

Examples

server.pluginManager.register('filesystem', filesystemPlugin, {
  dirname: 'my-dir',
  publicPath: 'assets'
});

switch

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

Parameters

• options Object

  • options.dirname String directory to watch, plugin is idle if null (optional, default null)
  • options.publicPath String optional 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. (optional, default null)

getTree

Return the current filesystem tree.

Returns Object

getTreeAsUrlMap

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

Parameters

• filterExt String File extension to retrieve in the list
• keepExtension Boolean Keep or remove the file extension from the keys (optional, default false)

Returns Object Map of <filename, url>

onUpdate

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.

Parameters

• callback Function Callback function to execute
• executeListener boolean If true, execute the given callback immediately. (optional, default false)

Returns Function Function that unregister the listener when executed.

findInTree

Return a node from the tree matching the given path.

Parameters

• pathname String Pathname, relative to options.dirname.

Returns Object

readFile

Read a file.

Parameters

• pathname String Pathname, relative to options.dirname.

Returns Promise<Blob>

writeFile

Write a file

Parameters

• pathname String Pathname, relative to options.dirname.
• data (String | Blob) Content of the file.

Returns Promise

mkdir

Create a directory

Parameters

• pathname String Path of the directory, relative to options.dirname.

Returns Promise

rename

Rename a file or directory

Parameters

• oldPath String Current pathname, relative to options.dirname.
• newPath String New pathname, relative to options.dirname.

Returns Promise

rm

Delete a file or directory

Parameters

• pathname String Pathname, relative to options.dirname.

Returns Promise

formatTreeAsUrlMap

Parameters

• tree any
• filterExt String File extension to retrieve in the list
• keepExtension Boolean Keep or remove the file extension from the keys (optional, default false)

Credits

https://soundworks.dev/credits.html

License

BSD-3-Clause