Работа с файловой системой в ECMAScript 6

Бета

Боты в среде исполнения ECMAScript 6 имеют доступ к файловой системе. Благодаря ему боты могут выполнять ряд задач, которые требуют скачивания файлов на диск и их обработки, например:

• Конвертация между различными форматами данных.
• Самостоятельная генерация файлов и отправка их пользователю.

У каждого бота есть специальные директории, в которых ему разрешены операции на чтение и запись. Для манипуляций над этими директориями используйте встроенный сервис $storage.

подсказка

Само взаимодействие с файловой системой вы можете выстроить с помощью стандартного модуля Node.js node:fs или аналогичных библиотек.

Встроенный сервис $storage

Встроенный сервис $storage предназначен для работы с хранилищем файлов из бота на ECMAScript 6. Все его методы:

• Являются асинхронными — всегда используйте их с ключевым словом await.
• Вызываются без аргументов.

Метод	Что делает
getRequestDir	Возвращает путь до директории для хранения файлов в рамках одного запроса. После завершения запроса такие файлы удаляются.
deleteRequestDir	Очищает директорию для хранения файлов в рамках одного запроса.
getTempDir	Возвращает путь до директории для хранения временных файлов, доступ к которым должен сохраняться в рамках нескольких запросов.
clear	Очищает директорию для хранения временных файлов.
getAvailableSpace	Возвращает объем свободного места, доступного для хранения файлов, в байтах.

Хранилище для файлов в рамках запроса

Метод $storage.getRequestDir возвращает путь до директории, где бот может хранить файлы, нужные во время обработки одного запроса. После обработки запроса директория автоматически очищается.

подсказка

Иногда может потребоваться очистить ее вручную. Например, если в одной точке сценария идет последовательная работа с несколькими файлами и вам нужно динамически освободить место от старых файлов, чтобы загрузить новые. Для этого используйте метод $storage.deleteRequestDir.

Хранилище для временных файлов

Директория, путь до которой возвращает метод $storage.getTempDir, не очищается между запросами. Бот может несколько раз обратиться к файлам, которые он ранее туда сохранил.

предупреждение

Обратите внимание, что эта директория не предназначена для постоянного хранения файлов.

Хранилище для временных файлов автоматически очищается, если:

• Занимаемое место начинает значительно превышать лимит, который возвращает метод $storage.getAvailableSpace. Своевременно очищайте старые файлы с помощью $storage.clear.
• Контейнер с ботом по каким-либо причинам перезапускается. Например, такое может быть при обновлении JAICP до новой версии.

Таким образом, не следует полагаться на то, что нужный файл существует. Всегда проверяйте, так ли это, и если файл был удален, сценарий должен заново генерировать файл или запрашивать его у пользователя.

Пример использования

В следующем фрагменте сценария реализована запись в файл произвольного текста, который отправляет пользователь, и чтение этого текста из файла.

main.sc

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

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

theme: /

    state: SaveNote
        q!: запиши [что] $Text
        scriptEs6:
            await fileSystem.writeFile(`${$request.channelUserId}.txt`, $parseTree._Text);
            $reactions.answer("Записал.");

    state: ReadNote
        q!: напомни что я сказал*
        scriptEs6:
            const answer = await fileSystem.readFile(`${$request.channelUserId}.txt`);
            if (answer !== null) {
                $reactions.answer(`Вы сказали: «${answer}».`);
            } else {
                $reactions.answer("Прошу прощения, я забыл…");
            }

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 };

подсказка

Мы также подготовили более сложный пример бота, который умеет читать содержимое PDF-файлов. Вы можете просмотреть его исходный код на GitHub, а оттуда же сразу создать проект в JAICP.