Привет, друзья!

Представляю вашему вниманию перевод этой замечательной статьи.

Данная статья включает в себя:

• обзор основных частей интерфейса Node.js для работы с файловой системой (далее — ФС);
• рецепты (сниппеты кода) для выполнения задач с помощью названного интерфейса.

Если вам это интересно, прошу под кат.

Содержание

• 1. Концепции, паттерны и соглашения, используемые в ФС
• 1.2. Стиль функций
  
  • 1.1.1. Синхронные функции
  • 1.1.2. Функции, основанные на промисах
  • 1.1.3. Функции, основанные на колбэках
  • 1.2. Доступ к файлам
  • 1.3. Префиксы названий функций
  • 1.3.1. Префикс "l": символические ссылки
  • 1.3.2. Префикс "f": дескрипторы файлов
  • 1.4. Важные классы
  • 1.4.1. URL: альтернатива строковым путям к файловой системе
  • 1.4.2. Буферы
  • 1.4.3. Потоки
• 2. Чтение и запись файлов
  
  • 2.1. Синхронное чтение файла в строку (опционально: разбиение по строкам)
  • 2.1.1. Разбиение текста без включения разделителей строк
  • 2.1.2. Разбиение текста с включением разделителей строк
  • 2.2. Построчное чтение файла с помощью потока
  • 2.3. Синхронная запись строки в файл
  • 2.4. Синхронное добавление строки в файл
  • 2.5. Запись нескольких строк в файл с помощью потока
  • 2.6. Добавление нескольких строк в файл с помощью потока
• 3. Кроссплатформенная обработка разделителей строк
  
  • 3.1. Чтение разделителей строк
  • 3.2. Запись разделителей строк
• 4. Обход и создание директорий
  
  • 4.1. Обход директории
  • 4.2. Создание директории (mkdir, mkdir -p)
  • 4.3. Определение наличия директории
  • 4.4. Создание временной директории
• 5. Копирование, переименование, перемещение файлов или директорий
  
  • 5.1. Копирование файлов или директорий
  • 5.2. Переименование или перемещение файлов или директорий
• 6. Удаление файлов или директорий
  
  • 6.1. Удаление файлов и директорий (rm, rm -r)
  • 6.2. Удаление пустых директорий (rmdir)
  • 6.3. Создание директорий
  • 6.4. Перемещение файлов или директорий в корзину
• 7. Чтение и изменение записей файловой системы
  
  • 7.1. Определение наличия файла или директории
  • 7.2. Получение статистики файла: является ли файл директорией, когда он был создан и т.д.
  • 7.3. Изменение атрибутов файла: разрешения, владелец, группа, отметки времени
• 8. Работа со ссылками

1. Концепции, паттерны и соглашения, используемые в ФС

В данном разделе предполагаются следующие импорты:

import * as fs from "node:fs";
import * as fsPromises from "node:fs/promises";

1.2. Стиль функций

ФС предоставляет 3 стиля функций:

• синхронный стиль с обычными функциями:
  
  • fs.readFileSync(path, options?): string | Buffer;
• 2 асинхронных стиля:
  
  • с функциями обратного вызова:
  • fs.readFile(path, options?, callback): void;
  • с функциями, возвращающими промисы:
  • fsPromises.readFile(path, options?): Promise<string | Buffer>.

1.1.1. Синхронные функции

Синхронные функции являются самыми простыми — они сразу возвращают значения и выбрасывают ошибки в виде исключений:

import * as fs from "node:fs";

try {
  const result = fs.readFileSync("/etc/passwd", { encoding: "utf-8" });

  console.log(result);
} catch (err) {
  console.error(err);
}

В статье, в основном, используется данный стиль.

1.1.2. Функции, основанные на промисах

Такие функции возвращают промисы, которые разрешаются результатами и отклоняются с ошибками:

import * as fsPromises from "node:fs/promises";

try {
  const result = await fsPromises.readFile(
    "/etc/passwd", { encoding: "utf-8" });

  console.log(result);
} catch (err) {
  console.error(err);
}

Обратите внимание: промисифицированный (promisified) ФС импортируется из другого модуля.

1.1.3. Функции, основанные на колбэках

Такие функции передают результат и ошибки колбэку, передаваемому им в качестве последнего аргумента:

import * as fs from "node:fs";

fs.readFile("/etc/passwd", { encoding: "utf-8" },
  (err, result) => {
    if (err) {
      console.error(err);
      return;
    }

    console.log(result);
  }
);

Данный стиль в статье не используется (он считается устаревшим).

1.2. Доступ к файлам

• все содержимое файла можно читать и записывать в виде строки;
• потоки для чтения и записи позволяют обрабатывать файлы небольшими частями (чанками/chunks), по одной за раз. Потоки разрешают только последовательный доступ;
• для последовательного и произвольного доступа могут использоваться файловые дескрипторы или FileHandles, отдаленно напоминающие потоки:
  
  • файловые дескрипторы — это целые числа, представляющие файлы. Они управляются с помощью следующих функций (у каждой синхронной версии имеется колбэк-эквивалент — fs.open() и т.п.):
  • fs.openSync(path, flags?, mode?): открывает новый дескриптор файла по указанному пути и возвращает его;
  • fs.closeSync(fd): закрывает дескриптор;
  • fs.fchmodSync(fd, mode);
  • fs.fchownSync(fd, uid, gid);
  • fs.fdatasyncSync(fd);
  • fs.fstatSync(fd, options?);
  • fs.fsyncSync(fd);
  • fs.ftruncateSync(fd, len?);
  • fs.futimesSync(fd, atime, mtime);
  • файловые дескрипторы могут использоваться синхронным и колбэк-ФС. Промис-ФС предоставляет абстракцию — класс FileHandle, основанный на дескрипторах. Экземпляры создаются с помощью fsPromises.open(). Операции выполняются с помощью таких методов (не функций), как:
  • fileHandle.close();
  • fileHandle.chmod(mode);
  • fileHandle.chown(uid, gid);
  • и др.

FileHandles в этой статье не рассматриваются.

1.3. Префиксы названий функций

1.3.1. Префикс "l": символические ссылки

Функции, названия которых начинаются с буквы l, как правило, оперируют символическими ссылками:

• fs.lchmodSync(), fs.lchmod(), fsPromises.lchmod();
• fs.lchownSync(), fs.lchown(), fsPromises.lchown();
• fs.lutimesSync(), fs.lutimes(), fsPromises.lutimes();
• и др.

1.3.2. Префикс "f": дескрипторы файлов

Функции, названия которых начинаются с буквы f, как правило, управляют файловыми дескрипторами:

• fs.fchmodSync(), fs.fchmod();
• fs.fchownSync(), fs.fchown();
• fs.fstatSync(), fs.fstat();
• и др.

1.4. Важные классы

1.4.1. URL: альтернатива строковым путям к файловой системе

Функции, принимающие строковые пути (1), как правило, также принимают экземпляры URL (2):

import * as fs from "node:fs";

assert.equal(
  fs.readFileSync(
    "/tmp/data.txt", { encoding: "utf-8" }), // (1)
  "Текст"
);

assert.equal(
  fs.readFileSync(
    new URL("file:///tmp/data.txt"), { encoding: "utf-8" }), // (2)
  "Текст"
);

Ручное преобразование путей в file: кажется простым, но необходимо учитывать большое количество нюансов: процентное кодирование и декодирование, управляющие символы, буквы дисков Windows и т.д. Поэтому лучше применять следующие функции:

• url.pathToFileURL;
• url.fileURLToPath.

URL будет рассмотрен в одной из следующих статей.

1.4.2. Буферы

Класс Buffer представляет последовательность байтов фиксированного размера. Он является подклассом Uint8Array (TypedArray — типизированного массива). Буферы используются, в основном, для работы с файлами, содержащими бинарные данные.

Функции, принимающие Buffer, также принимают Uint8Array. Поскольку Uint8Arrays являются кроссплатформенными, а Buffers нет, предпочтение следует отдавать первым.

Преимущество буферов состоит в возможности кодирования и декодирования текста в разные кодировки. Для кодирования или декодирования UTF-8 в Uint8Array можно использовать TextEncoder или TextDecoder. Эти классы доступны на большинстве JavaScript-платформ:

> new TextEncoder().encode("café")
Uint8Array.of(99, 97, 102, 195, 169)

> new TextDecoder().decode(Uint8Array.of(99, 97, 102, 195, 169))
"café"

1.4.3. Потоки

Некоторые функции принимают или возвращают нативные потоки данных (native streams):

• stream.Readable: класс для создания потоков для чтения. Модуль node:fs использует fs.ReadStream, который является подклассом stream.Readable;
• stream.Writable: класс для создания потоков для записи. Модуль node:fs использует fs.WriteStream, который является подклассом stream.Writable.

Вместо нативных потоков можно использовать кроссплатформенные веб-потоки (web streams), о которых рассказывалось в одной из предыдущих статей.

2. Чтение и запись файлов

2.1. Синхронное чтение файла в строку (опционально: разбиение по строкам)

fs.readFileSync(path, options?) читает файл по указанному пути в строку (результат чтения файла возвращается в виде единой строки):

import * as fs from "node:fs";

assert.equal(
  fs.readFileSync("data.txt", { encoding: "utf-8" }),
  "несколько\r\nстрок\nтекста"
);

Плюсы и минусы данного подхода (по сравнению с использованием потока):

• +: файл читается синхронно, делается это легко. Подходит для многих случаев;
• -: плохой выбор для больших файлов — обработке файла предшествует чтение всего содержимого файла.

2.1.1. Разбиение текста без включения разделителей строк

Следующий код разбивает текст построчно и удаляет разделители строк (line terminators):

const RE_EOL = /\r?\n/;

const splitLines = (str) => str.split(RE_EOL);

assert.deepEqual(
  splitLines("несколько\r\nстрок\nтекста"),
  ["несколько", "строк", "текста"]
);

"EOL" расшифровывается как "end of line" (конец строки).

2.1.2. Разбиение текста с включением разделителей строк

const RE_EOL = /(?<=\r?\n)/; // (1)

const splitLinesWithEols = (str) => str.split(RE_EOL);

assert.deepEqual(
  splitLinesWithEols("несколько\r\nстрок\nтекста"),
  ["несколько\r\n", "строк\n", "текста"]
);
assert.deepEqual(
  splitLinesWithEols("первый\n\nтретий"),
  ["первый\n", "\n", "третий"]
);
assert.deepEqual(
  splitLinesWithEols("EOL в конце\n"),
  ["EOL в конце\n"]
);
assert.deepEqual(
  splitLinesWithEols(""),
  [""]
);

На строке 1 у нас имеется регулярное выражение с ретроспективной проверкой (lookbehind assertion). Оно сопоставляется с тем, что предшествует \r?\n, но ничего не захватывает. Поэтому разделители сохраняются.

На платформах, не поддерживающих ретроспективные проверки, можно использовать такую функцию:

function splitLinesWithEols(str) {
  if (str.length === 0) return [""];

  const lines = [];

  let prevEnd = 0;

  while (prevEnd < str.length) {
    // Поиск "\n" также означает поиск "\r\n"
    const newlineIndex = str.indexOf("\n", prevEnd);

    // Перевод на новую строку включается в строку
    const end = newlineIndex < 0 ? str.length : newlineIndex + 1;

    lines.push(str.slice(prevEnd, end));

    prevEnd = end;
  }

  return lines;
}

2.2. Построчное чтение файла с помощью потока

import * as fs from "node:fs";
import { Readable } from "node:stream";

const nodeReadable = fs.createReadStream(
  "text-file.txt",
  { encoding: "utf-8" }
);

const webReadableStream = Readable.toWeb(nodeReadable);

const lineStream = webReadableStream.pipeThrough(new ChunksToLinesStream());

for await (const line of lineStream) {
  console.log(line);
}
/**
 * несколько\r\n
 * строк\n
 * текста
*/

Вот, что здесь используется:

• fs.createReadStream(path, options?): создает поток (экземпляр stream.Readable);
• stream.Readable.toWeb(nodeReadable): преобразует доступный для чтения поток Node.js в веб-поток (экземпляр ReadableStream);
• класс ChunksToLinesStream представляет поток для преобразования. Чанки — это небольшие части данных, производимые потоками. Если у нас есть поток, чанки которого представляют строки произвольной длины, и мы пропускает эти чанки через ChunksToLinesStream, то получаем поток с построчными чанками.

Веб-потоки являются асинхронно итерируемыми, что позволяет использовать цикл for-await-of для их перебора.

Плюсы и минусы данного подхода (по сравнению с чтением в строку):

• +: хорошо подходит для больших файлов — данные могут обрабатываться инкрементально, не нужно ждать завершения чтения всего содержимого файла;
• -: данные читаются асинхронно, код сложнее и его больше.

2.3. Синхронная запись строки в файл

fs.writeFileSync(path, str, options?) записывает строку в файл по указанному пути. Существующий файл перезаписывается:

import * as fs from "node:fs";

fs.writeFileSync(
  "data.txt",
  "Первая строка\nВторая строка\n",
  { encoding: "utf-8" }
);

Плюсы и минусы (по сравнению с потоком):

• +: файл записывается синхронно, делается это легко. Подходит для многих случаев;
• -: плохой выбор для больших файлов.

2.4. Синхронное добавление строки в файл

import * as fs from "node:fs";

fs.writeFileSync(
  "data.txt",
  "Новая строка\n",
  { encoding: "utf-8", flag: "a" }
);

Настройка flag со значением a означает, что мы добавляем данные. Другие возможные значения этой настройки.

Обратите внимание: в одних функциях настройка называется flag, в других — flags.

2.5. Запись нескольких строк в файл с помощью потока

import * as fs from "node:fs";
import { Writable } from "node:stream";

const nodeWritable = fs.createWriteStream(
  "data.txt",
  { encoding: "utf-8" }
);

const webWritableStream = Writable.toWeb(nodeWritable);

const writer = webWritableStream.getWriter();

try {
  await writer.write("Первая строка\n");
  await writer.write("Вторая строка\n");
  await writer.close();
} finally {
  writer.releaseLock()
}

Вот, что здесь используется:

• fs.createWriteStream(path, options?): создает поток для записи (экземпляр stream.Writable);
• stream.Writable.toWeb(streamWritable): преобразует доступный для записи поток Node.js в веб-поток.

Плюсы и минусы:

• +: хорошо подходит для больших файлов;
• -: запись выполняется асинхронно, код сложнее и его больше.

2.6. Добавление нескольких строк в файл с помощью потока

import * as fs from "node:fs";
import { Writable } from "node:stream";

const nodeWritable = fs.createWriteStream(
  "data.txt",
  // !
  { encoding: "utf-8", flags: "a" }
);

const webWritableStream = Writable.toWeb(nodeWritable);

const writer = webWritableStream.getWriter();

try {
  await writer.write("Первая добавленная строка\n");
  await writer.write("Вторая добавленная строка\n");
  await writer.close();
} finally {
  writer.releaseLock()
}

3. Кроссплатформенная обработка разделителей строк

На разных платформах используются разные разделители строк, отмечающие конец строки:

• на Windows — это \r\n;
• на Unix — \n.

Для кроссплатформенной обработки EOL можно использовать несколько стратегий.

3.1. Чтение разделителей строк

При обработке строк с EOL иногда бывает полезным их удалять:

const RE_EOL_REMOVE = /\r?\n$/;

function removeEol(line) {
  const match = RE_EOL_REMOVE.exec(line);

  if (!match) return line;

  return line.slice(0, match.index);
}

assert.equal(
  removeEol("Windows EOL\r\n"),
  "Windows EOL"
);
assert.equal(
  removeEol("Unix EOL\n"),
  "Unix EOL"
);
assert.equal(
  removeEol("Без EOL"),
  "Без EOL"
);

3.2. Запись разделителей строк

Для записи разделителей строк в нашем распоряжении имеется 2 варианта:

• константа EOL из модуля node:os содержит EOL текущей платформы;
• можно регистрировать формат EOL входного файла и использовать этот формат при дальнейшей модификации данного файла.

4. Обход и создание директорий

4.1. Обход директории

Следующая функция обходит (traverse) директорию и возвращает список всех ее потомков (ее дочерних элементов, потомков дочерних элементов и т.д.):

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

function* traverseDir(dirPath) {
  const dirEntries = fs.readdirSync(dirPath, {withFileTypes: true});

  // Сортируем сущности для обеспечения большей предсказуемости
  dirEntries.sort(
    (a, b) => a.name.localeCompare(b.name, "en")
  );

  for (const dirEntry of dirEntries) {
    const fileName = dirEntry.name;
    const pathName = path.join(dirPath, fileName);
    yield pathName;

    if (dirEntry.isDirectory()) {
      yield* traverseDir(pathName);
    }
  }
}

Здесь:

• fs.readdirSync(path, options?) возвращает потомков директории по указанному пути:
  
  • если настройка withFileTypes имеет значение true, функция возвращает записи каталога (directory entries), экземпляры fs.Dirent. Записи каталога содержат такие свойства, как:
  • dirent.name;
  • dirent.isDirectory();
  • dirent.isFile();
  • dirent.isSymbolicLink();
  • если настройка withFileTypes имеет значение true или не указана, функция возвращает список названий файлов.

Пример использования функции traverseDir:

for (const filePath of traverseDir("dir")) {
  console.log(filePath);
}
/**
 * dir/dir-file.txt
 * dir/subdir
 * dir/subdir/subdir-file1.txt
 * dir/subdir/subdir-file2.csv
*/

4.2. Создание директории (mkdir, mkdir -p)

Для создания директорий можно использовать функцию fs.mkdirSync(path, options?).

options.recursive определяет, как создается директория по указанному пути:

• если recursive имеет значение false или отсутствует, mkdirSync() возвращает undefined. Если директория (или файл) уже существует или отсутствует родительская директория, выбрасывается исключение;
• если recursive имеет значение true, mkdirSync() возвращает путь первой созданной директории. Если директория (или файл) уже существует, ничего не происходит. Если отсутствует родительская директория, она создается.

Пример использования mkdirSync():

import * as fs from "node:fs";

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
  ]
);

fs.mkdirSync("dir/sub/subsub", { recursive: true });

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/sub",
    "dir/sub/subsub",
  ]
);

4.3. Определение наличия директории

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

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

function ensureParentDirectory(filePath) {
  const parentDir = path.dirname(filePath);

  if (!fs.existsSync(parentDir)) {
    fs.mkdirSync(parentDir, { recursive: true });
  }
}

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

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
  ]
);

const filePath = "dir/sub/subsub/new-file.txt";

ensureParentDirectory(filePath);

fs.writeFileSync(filePath, "content", { encoding: "utf-8" });

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/sub",
    "dir/sub/subsub",
    "dir/sub/subsub/new-file.txt",
  ]
);

4.4. Создание временной директории

fs.mkdtemp(pathPrefix, options?) создает временную директорию: она добавляет 6 произвольных символов к pathPrefix, создает директорию и возвращает путь.

Обратите внимание: pathPrefix не должен оканчиваться на заглавную X, поскольку некоторые платформы заменяют X произвольными символами.

Для создания временной директории внутри специфичной для операционной системы глобальной временной директории можно использовать функцию os.tmpdir:

import * as os from "node:os";
import * as path from "node:path";
import * as fs from "node:fs";

const pathPrefix = path.resolve(os.tmpdir(), "my-app");
  // например, "/var/folders/ph/sz0384m11vxf/T/my-app"

const tmpPath = fs.mkdtempSync(pathPrefix);
  // например, "/var/folders/ph/sz0384m11vxf/T/my-app1QXOXP"

Созданные таким способом директории автоматически не удаляются.

5. Копирование, переименование, перемещение файлов или директорий

5.1. Копирование файлов или директорий

fs.cpSync(srcPath, destPath, options?) копирует файл или директорию из srcPath в destPath. Полезные настройки:

• recursive (false по умолчанию): директории (включая пустые) копируются только когда данная настройка имеет значение true;
• force (true): если имеет значение true, существующие файлы перезаписываются:
  
  • если имеет значение false и настройка errorOnExist установлена в true, при наличии файла выбрасывается исключение;
• filter: функция, позволяющая управлять тем, какие файлы копируются;
• preserveTimestamps (false): если имеет значение true, копии в destPath получат отметки времени оригиналов (время создания, последней модификации и т.п.).

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

import * as fs from "node:fs";

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir-orig",
    "dir-orig/some-file.txt",
  ]
);

fs.cpSync("dir-orig", "dir-copy", { recursive: true });

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir-copy",
    "dir-copy/some-file.txt",
    "dir-orig",
    "dir-orig/some-file.txt",
  ]
);

5.2. Переименование или перемещение файлов или директорий

fs.renameSync(oldPath, newPath) переименовывает или перемещает файл или директорию из oldPath в newPath.

Пример использования данной функции для переименования директории:

import * as fs from "node:fs";

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "old-dir-name",
    "old-dir-name/some-file.txt",
  ]
);

fs.renameSync("old-dir-name", "new-dir-name");

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "new-dir-name",
    "new-dir-name/some-file.txt",
  ]
);

Пример перемещения файла:

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/subdir",
    "dir/subdir/some-file.txt",
  ]
);

fs.renameSync("dir/subdir/some-file.txt", "some-file.txt");

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/subdir",
    "some-file.txt",
  ]
);

6. Удаление файлов или директорий

6.1. Удаление файлов и директорий (rm, rm -r)

fs.rmSync(path, options?) удаляет файл или директорию по указанному пути. Полезные настройки:

• recursive (false): директории (включая пустые) удаляются только когда данная настройка имеет значение true;
• force (false): если имеет значение false, при отсутствии файла или директории по указанному пути выбрасывается исключение.

Пример удаления файла:

import * as fs from "node:fs";

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/some-file.txt",
  ]
);

fs.rmSync("dir/some-file.txt");

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
  ]
);

Пример рекурсивного удаления непустой директории:

import * as fs from "node:fs";

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/subdir",
    "dir/subdir/some-file.txt",
  ]
);

fs.rmSync("dir/subdir", {recursive: true});

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
  ]
);

6.2. Удаление пустых директорий (rmdir)

fs.rmdirSync удаляет пустую директорию (если директория не является пустой, выбрасывается исключение):

import * as fs from "node:fs";

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/subdir",
  ]
);

fs.rmdirSync("dir/subdir");

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
  ]
);

6.3. Создание директорий

Следующая функция очищает директорию по указанному пути:

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

function clearDir(dirPath) {
  for (const fileName of fs.readdirSync(dirPath)) {
    const pathName = path.join(dirPath, fileName);

    fs.rmSync(pathName, { recursive: true });
  }
}

Здесь:

• fs.readdirSync(path) возвращает названия всех потомков директории по указанному пути;
• fs.rmSync(path, options?) удаляет файлы и директории.

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

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/dir-file.txt",
    "dir/subdir",
    "dir/subdir/subdir-file.txt"
  ]
);

clearDirectory("dir");

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
  ]
);

6.4. Перемещение файлов или директорий в корзину

Библиотека trash перемещает файлы или директории в корзину. Она работает на macOS, Windows и Linux.

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

import trash from "trash";

await trash(["*.png", "!rainbow.png"]);

trash() принимает строку или массив строк в качестве первого параметра. Любая строка может быть паттерном поиска (glob pattern) (со звездочками и другими метасимволами).

7. Чтение и изменение записей файловой системы

7.1. Определение наличия файла или директории

fs.existsSync(path) возвращает true, если файл или директория по указанному пути существует:

import * as fs from "node:fs";

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/some-file.txt",
  ]
);
assert.equal(
  fs.existsSync("dir"), true
);
assert.equal(
  fs.existsSync("dir/some-file.txt"), true
);
assert.equal(
  fs.existsSync("dir/non-existent-file.txt"), false
);

7.2. Получение статистики файла: является ли файл директорией, когда он был создан и т.д.

fs.statSync(path, options?) возвращает экземпляр fs.Stats с полезной информацией о файле или директории по указанному пути. Основные настройки:

• throwIfNoEntry (true): если true, при отсутствии записи выбрасывается исключение, если false, возвращается undefined;
• bigint (false): если true, функция использует BigInt для числовых значений (таких как отметки времени, см. ниже).

Свойства экземпляров fs.Stats:

• вид записи:
  
  • stats.isFile();
  • stats.isDirectory();
  • stats.isSymbolicLink();
• stats.size: размер в байтах;
• отметки времени:
  
  • 3 вида:
  • stats.atime: время последнего доступа;
  • stats.mtime: время последней модификации;
  • stats.birthtime: время создания;
  • каждый вид может использовать 3 единицы измерения, например, для atime:
  • stats.atime: экземпляр Date;
  • stats.atimeMS: миллисекунды с начала эпохи (POSIX);
  • stats.atimeNs: наносекунды с начала эпохи.

Пример реализации функции isDirectory с помощью fs.statsSync():

import * as fs from "node:fs";

function isDirectory(thePath) {
  const stats = fs.statSync(thePath, { throwIfNoEntry: false });

  return stats && stats.isDirectory();
}

assert.deepEqual(
  Array.from(traverseDir(".")),
  [
    "dir",
    "dir/some-file.txt",
  ]
);
assert.equal(
  isDirectory("dir"), true
);
assert.equal(
  isDirectory("dir/some-file.txt"), false
);
assert.equal(
  isDirectory("non-existent-dir"), false
);

7.3. Изменение атрибутов файла: разрешения, владелец, группа, отметки времени

Функции для модификации атрибутов файла:

• fs.chmodSync(path, mode): обновляет разрешение файла;
• fs.chownSync(path, uid, gid): обновляет владельца или группу файла;
• fs.utimesSync(path, atime, mtime): обновляет отметки времени файла:
  
  • atime: время последнего доступа;
  • mtime: время последней модификации.

8. Работа со ссылками

Функции для работы с жесткими ссылками (hard links):

• fs.linkSync(existingPath, newPath) создает жесткую ссылку;
• fs.unlinkSync(path) удаляет жесткую ссылку на файл и, возможно, сам файл, если удаленная ссылка была последней.

Функции для работы с символическими ссылками (symbolic links):

• fs.symlinkSync(target, path, type?) создает символическую ссылку из path на target;
• fs.readlinkSync(path, options?) возвращает цель символической ссылки по указанному пути.

Следующие функции оперируют символическими ссылками без их разыменования (dereferencing) (обратите внимание на префикс l):

• fs.lchmodSync(path, mode);
• fs.lchownSync(path, uid, gid);
• fs.lutimeSync(path, atime, mtime);
• fs.lstatSync(path, options?).

Еще одна полезная функция — fs.realpathSync(path, options?) вычисляет каноническое название пути посредством разрешения символов . и .., а также символических ссылок.

Настройки функций, влияющие на обработку символических ссылок:

• fs.cpSync(srcPath, destPath, options?):
  
  • dereference (false): если true, копируется файл, на который указывает символическая ссылка, а не сама ссылка;
  • verbatimSymlinks (false): если false, обновляется указатель локации цели скопированной символической ссылки.

Ссылки для дальнейшего изучения материала.

Надеюсь, вы, как и я, узнали что-то новое и не зря потратили время.

Благодарю за внимание и happy coding!

---