Skip to main content

File system access in ECMAScript 6

Beta

Bots in the ECMAScript 6 runtime have access to the file system. It allows bots to perform a number of tasks that require downloading files and processing them, such as:

  • Converting files between different data formats.
  • Generating files and sending them to users.

Each bot has special directories where read and write operations are allowed. Use the built-in $storage service to manage these directories.

tip
You can work with the file system using the standard Node.js module, node:fs, or similar libraries.

Built-in $storage service

The built-in $storage service allows you to manage file storage in ECMAScript 6:

  • All methods are asynchronous. Use them with the await keyword.
  • All methods are called without arguments.
MethodDescription
getRequestDirReturns the directory path for storing files within a single request. Once the request is completed, the files are deleted.
deleteRequestDirClears the directory for storing files within a single request.
getTempDirReturns the directory path for storing temporary files, which can be accessed across multiple requests.
clearClears the directory for storing temporary files.
getAvailableSpaceReturns the amount of free space available for file storage, in bytes.

Storage for files within a single request

The $storage.getRequestDir method returns the path to the directory where the bot can store files while processing a request. Once the request is completed, the directory is automatically cleared.

Sometimes you may need to clear it manually. For example, if at one point in the script there is a sequential processing of multiple files and you need to dynamically free space from old files to load new ones. To do this, use the $storage.deleteRequestDir method.

Storage for temporary files

The directory whose path is returned by the $storage.getTempDir method is not cleared between requests. The bot can repeatedly access files that it previously saved there.

caution
Please note that this directory is not intended for permanent file storage.

The temporary file storage is automatically cleared if:

  • The occupied space starts to significantly exceed the limit that is returned by the $storage.getAvailableSpace method. Clear the old files via $storage.clear when they are no longer needed.
  • The bot container is restarted for some reason. For example, this can happen when Tovie Platform is updated to a new version.

Therefore, you should not assume that a file exists. Always check if it exists, and if the file was deleted, the script should re-generate the file or request it from the user.

How to use

The script fragment below writes an arbitrary text sent by the user to a file and then reads the text from the file.

require: text/text.sc
module = sys.zb-common

require: file-system.js
type = scriptEs6
name = fileSystem

theme: /

state: SaveNote
q!: Make a note [that] $Text
scriptEs6:
await fileSystem.writeFile(`${$request.channelUserId}.txt`, $parseTree._Text);
$reactions.answer("Done.");

state: ReadNote
q!: Remind me what I said
scriptEs6:
const answer = await fileSystem.readFile(`${$request.channelUserId}.txt`);
if (answer !== null) {
$reactions.answer(`You said: “${answer}”.`);
} else {
$reactions.answer("Sorry, I forgot…");
}