soundworks

Appearance

soundworks | plugin filesystem ​

npm version

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

Table of Contents ​

Installation ​

sh
npm install @soundworks/plugin-filesystem --save

Usage ​

Server ​

js
// 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 ​

js
// 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 ​

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 ​

javascript
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