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.

Method	Description
getRequestDir	Returns the directory path for storing files within a single request. Once the request is completed, the files are deleted.
deleteRequestDir	Clears the directory for storing files within a single request.
getTempDir	Returns the directory path for storing temporary files, which can be accessed across multiple requests.
clear	Clears the directory for storing temporary files.
getAvailableSpace	Returns 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 JAICP 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.

main.sc

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…");
            }

file-system.js

import fs from "node:fs";
import path from "node:path";

const AVAILABLE_SPACE_LIMIT_BYTES = 500_000; // 500 KB

async function readFile(fileName) {
  const filePath = path.join(await $storage.getTempDir(), fileName);
  try {
    return await fs.promises.readFile(filePath, { encoding: 'utf-8' });
  } catch (e) {
    return null;
  }
}

async function writeFile(fileName, text) {
  if ((await $storage.getAvailableSpace()) < AVAILABLE_SPACE_LIMIT_BYTES) {
    await $storage.clear();
  }

  const filePath = path.join(await $storage.getTempDir(), fileName);
  await fs.promises.writeFile(filePath, text);
}

export default { readFile, writeFile };

tip

We have also prepared a more complex example with a bot that can read PDF file contents. You can view the source code on GitHub, and you can create a project in JAICP directly from there.