npm package: @soundworks/plugin-filesystem
Description: soundworks plugin to parse and watch directories
Latest version: 5.1.3

# soundworks | plugin filesystem

[![npm version](https://badge.fury.io/js/@soundworks%2Fplugin-filesystem.svg)](https://badge.fury.io/js/@soundworks%2Fplugin-filesystem)

[`soundworks`](https://soundworks.dev) plugin to watch directories and update their contents from any node.

## Table of Contents

<!-- toc -->

- [Installation](#installation)
- [Usage](#usage)
- [Security Note](#security-note)
- [API](#api)
- [ClientPluginFilesystem](#clientpluginfilesystem)
- [ServerPluginFilesystem](#serverpluginfilesystem)
- [formatTreeAsUrlMap](#formattreeasurlmap)
- [Credits](#credits)
- [License](#license)

<!-- tocstop -->

## 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

<!-- api -->
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

*   [ClientPluginFilesystem][1]
    *   [getTree][2]
    *   [onUpdate][3]
    *   [getTreeAsUrlMap][4]
    *   [findInTree][5]
    *   [readFile][6]
    *   [writeFile][7]
    *   [mkdir][8]
    *   [rename][9]
    *   [rm][10]
*   [ServerPluginFilesystem][11]
    *   [Examples][12]
    *   [switch][13]
    *   [getTree][14]
    *   [getTreeAsUrlMap][15]
    *   [onUpdate][16]
    *   [findInTree][17]
    *   [readFile][18]
    *   [writeFile][19]
    *   [mkdir][20]
    *   [rename][21]
    *   [rm][22]
*   [formatTreeAsUrlMap][23]
    *   [Parameters][24]

## 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][25]**&#x20;

### 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][26]** Callback function to execute
*   `executeListener` **[boolean][27]** If true, execute the given
    callback immediately. (optional, default `false`)

Returns **[Function][26]** Function that unregister the listener when executed.

### getTreeAsUrlMap

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

#### Parameters

*   `filterExt` **[String][28]** File extension to retrieve in the list
*   `keepExtension` **[Boolean][27]** Keep or remove the file extension
    from the keys (optional, default `false`)

Returns **[Object][25]** Map of `<filename, url>`

### findInTree

Return a node from the tree matching the given path.

#### Parameters

*   `pathOrUrl` **[String][28]** Path of the node to be retrieved, relative to
    `options.dirname` or URL of the node.

Returns **[Object][25]**&#x20;

### readFile

Read a file

#### Parameters

*   `pathname` **[String][28]** Pathname, relative to `options.dirname`.

Returns **[Promise][29]<[Blob][30]>**&#x20;

### writeFile

Write a file

#### Parameters

*   `pathname` **[String][28]** Pathname, relative to `options.dirname`.
*   `data` **([String][28] | File | [Blob][30])** Content of the file. (optional, default `''`)

Returns **[Promise][29]**&#x20;

### mkdir

Create a directory

#### Parameters

*   `pathname` **[String][28]** Path of the directory, relative to `options.dirname`.

Returns **[Promise][29]**&#x20;

### rename

Rename a file or directory

#### Parameters

*   `oldPath` **[String][28]** Current pathname, relative to `options.dirname`.
*   `newPath` **[String][28]** New pathname, relative to `options.dirname`.

Returns **[Promise][29]**&#x20;

### rm

Delete a file or directory

#### Parameters

*   `pathname` **[String][28]** Pathname, relative to `options.dirname`.

Returns **[Promise][29]**&#x20;

## 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][25]**&#x20;

    *   `options.dirname` **[String][28]** directory to watch, plugin is idle
        if null (optional, default `null`)
    *   `options.publicPath` **[String][28]** 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][25]**&#x20;

### getTreeAsUrlMap

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

#### Parameters

*   `filterExt` **[String][28]** File extension to retrieve in the list.
    If several extensions, should be seprarated with a `|`, e.g. `'wav|map3'` (optional, default `null`)
*   `keepExtension` **[Boolean][27]** Keep or remove the file extension
    from the keys (optional, default `false`)

Returns **[Object][25]** 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][26]** Callback function to execute
*   `executeListener` **[boolean][27]** If true, execute the given
    callback immediately. (optional, default `false`)

Returns **[Function][26]** Function that unregister the listener when executed.

### findInTree

Return a node from the tree matching the given path.

#### Parameters

*   `pathname` **[String][28]** Pathname, relative to `options.dirname`.

Returns **[Object][25]**&#x20;

### readFile

Read a file.

#### Parameters

*   `pathname` **[String][28]** Pathname, relative to `options.dirname`.

Returns **[Promise][29]<[Blob][30]>**&#x20;

### writeFile

Write a file

#### Parameters

*   `pathname` **[String][28]** Pathname, relative to `options.dirname`.
*   `data` **([String][28] | [Blob][30])** Content of the file.

Returns **[Promise][29]**&#x20;

### mkdir

Create a directory

#### Parameters

*   `pathname` **[String][28]** Path of the directory, relative to `options.dirname`.

Returns **[Promise][29]**&#x20;

### rename

Rename a file or directory

#### Parameters

*   `oldPath` **[String][28]** Current pathname, relative to `options.dirname`.
*   `newPath` **[String][28]** New pathname, relative to `options.dirname`.

Returns **[Promise][29]**&#x20;

### rm

Delete a file or directory

#### Parameters

*   `pathname` **[String][28]** Pathname, relative to `options.dirname`.

Returns **[Promise][29]**&#x20;

## formatTreeAsUrlMap

### Parameters

*   `tree` **any**&#x20;
*   `filterExt` **[String][28]** File extension to retrieve in the list,
    mutliple
*   `keepExtension` **[Boolean][27]** Keep or remove the file extension
    from the keys (optional, default `false`)

[1]: #clientpluginfilesystem

[2]: #gettree

[3]: #onupdate

[4]: #gettreeasurlmap

[5]: #findintree

[6]: #readfile

[7]: #writefile

[8]: #mkdir

[9]: #rename

[10]: #rm

[11]: #serverpluginfilesystem

[12]: #examples

[13]: #switch

[14]: #gettree-1

[15]: #gettreeasurlmap-1

[16]: #onupdate-1

[17]: #findintree-1

[18]: #readfile-1

[19]: #writefile-1

[20]: #mkdir-1

[21]: #rename-1

[22]: #rm-1

[23]: #formattreeasurlmap

[24]: #parameters-17

[25]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[26]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function

[27]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

[28]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[29]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise

[30]: https://developer.mozilla.org/docs/Web/API/Blob

<!-- apistop -->

## Credits

[https://soundworks.dev/credits.html](https://soundworks.dev/credits.html)

## License

[BSD-3-Clause](./LICENSE)