soundworks
plugin to watch directories and update their contents from any node.
npm install @soundworks/plugin-filesystem --save
// 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');
// 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');
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).
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
Return the current filesystem tree.
Returns Object
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.
-
callback
Function Callback function to execute -
executeListener
boolean If true, execute the given callback immediately. (optional, defaultfalse
)
Returns Function Function that unregister the listener when executed.
Return the tree as flat map of <filename, url>
-
filterExt
String File extension to retrieve in the list -
keepExtension
Boolean Keep or remove the file extension from the keys (optional, defaultfalse
)
Returns Object Map of <filename, url>
Return a node from the tree matching the given path.
-
pathOrUrl
String Path of the node to be retrieved, relative tooptions.dirname
or URL of the node.
Returns Object
Read a file
-
pathname
String Pathname, relative tooptions.dirname
.
Write a file
-
pathname
String Pathname, relative tooptions.dirname
. -
data
(String | File | Blob) Content of the file. (optional, default''
)
Returns Promise
Create a directory
-
pathname
String Path of the directory, relative tooptions.dirname
.
Returns Promise
Rename a file or directory
-
oldPath
String Current pathname, relative tooptions.dirname
. -
newPath
String New pathname, relative tooptions.dirname
.
Returns Promise
Delete a file or directory
-
pathname
String Pathname, relative tooptions.dirname
.
Returns Promise
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 anurl
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.
server.pluginManager.register('filesystem', filesystemPlugin, {
dirname: 'my-dir',
publicPath: 'assets'
});
Switch the filesystem to a new directory, e.g. to change project while keeping the same plugin and related logic at hand.
-
options
Object
Return the current filesystem tree.
Returns Object
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.
-
callback
Function Callback function to execute -
executeListener
boolean If true, execute the given callback immediately. (optional, defaultfalse
)
Returns Function Function that unregister the listener when executed.
Return a node from the tree matching the given path.
-
pathname
String Pathname, relative tooptions.dirname
.
Returns Object
Read a file.
-
pathname
String Pathname, relative tooptions.dirname
.
Write a file
Returns Promise
Create a directory
-
pathname
String Path of the directory, relative tooptions.dirname
.
Returns Promise
Rename a file or directory
-
oldPath
String Current pathname, relative tooptions.dirname
. -
newPath
String New pathname, relative tooptions.dirname
.
Returns Promise
Delete a file or directory
-
pathname
String Pathname, relative tooptions.dirname
.
Returns Promise