@soundworks/plugin-filesystem

2.0.0-alpha.6 • Public • Published

soundworks | plugin filesystem

npm version

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

Table of Contents

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

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(path) ⇒ Object

Return a node from the tree matching the given path.

Kind: instance method of PluginFilesystemClient

Param Type Description
path String Path of the node to be retrieved.

pluginFilesystemClient.writeFile(pathname, data) ⇒ Promise

Write a file

Kind: instance method of PluginFilesystemClient

Param Type Description
pathname String Pathname.
data String | 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.

pluginFilesystemClient.rename(oldPath, newPath) ⇒ Promise

Rename a file or directory

Kind: instance method of PluginFilesystemClient

Param Type Description
oldPath String Current pathname.
newPath String New pathname.

pluginFilesystemClient.rm(pathname) ⇒ Promise

Delete a file or directory

Kind: instance method of PluginFilesystemClient

Param Type Description
pathname String Pathname.

PluginFilesystemServer

Server-side representation of the soundworks' filesystem plugin.

Kind: global class

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(path) ⇒ Object

Return a node from the tree matching the given path.

Kind: instance method of PluginFilesystemServer

Param Type Description
path String path of the node to be retrieved

pluginFilesystemServer.writeFile(pathname, data) ⇒ Promise

Write a file

Kind: instance method of PluginFilesystemServer

Param Type Description
pathname String Pathname.
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.

pluginFilesystemServer.rename(oldPath, newPath) ⇒ Promise

Rename a file or directory

Kind: instance method of PluginFilesystemServer

Param Type Description
oldPath String Current pathname.
newPath String New pathname.

pluginFilesystemServer.rm(pathname) ⇒ Promise

Delete a file or directory

Kind: instance method of PluginFilesystemServer

Param Type Description
pathname String Pathname.

Credits

https://soundworks.dev/credits.html

License

BSD-3-Clause

Readme

Keywords

none

Package Sidebar

Install

npm i @soundworks/plugin-filesystem

Weekly Downloads

51

Version

2.0.0-alpha.6

License

BSD-3-Clause

Unpacked Size

54.2 kB

Total Files

10

Last publish

Collaborators

  • jipodine
  • b-ma