Данные

Файлы

@amxts/core/fs читает и пишет файлы так же, как fs в Node:

import * as 
fs
from "@amxts/core/fs";
const
rulesFile
= `${
server
.
configsDir
}/myplugin/rules.txt`;
server
.
addCommand
("/rules", ({
player
}) => showRules(
player
));
function showRules(
player
: Player) {
const
text
=
fs
.
readFileSync
(
rulesFile
);
if (
text
== null) return; // файла нет
for (const
line
of
text
.
split
("\n"))
console
.
log
(
line
);
fs
.
appendFileSync
(`${
server
.
dataDir
}/myplugin-rules.log`, `${
player
.
name
} прочитал правила\n`);
}

У каждой функции есть синхронная форма и форма с промисом, для await:

СинхроннаяС промисомЧто делает
readFileSync(path) → string | nullreadFile(path) → Promise<string>читает весь файл как текст
readBytesSync(path) → Uint8Array | null с v0.3readBytes(path) → Promise<Uint8Array>читает весь файл как байты
writeFileSync(path, data) → booleanwriteFile(path, data) → Promise<void>записывает в файл текст или байты с v0.3, заменяя то, что там было
appendFileSync(path, data) → booleanappendFile(path, data) → Promise<void>дописывает текст или байты в конец, при необходимости создаёт файл
existsSync(path, options?) → booleanexists(path, options?) → Promise<boolean>есть ли такой файл или папка; { game: true } с v0.3.1 ищет во всех папках, из которых игра читает файлы
readdirSync(path) → string[] | nullreaddir(path) → Promise<string[]>имена в папке, без . и ..
mkdirSync(path, options?) → booleanmkdir(path, options?) → Promise<void>создаёт папку; { recursive: true } создаёт и недостающие папки выше
unlinkSync(path) → boolean с v0.3unlink(path) → Promise<void>удаляет файл
renameSync(from, to) → boolean с v0.3rename(from, to) → Promise<void>перемещает или переименовывает файл
rmdirSync(path) → boolean с v0.3rmdir(path) → Promise<void>удаляет пустую папку
statSync(path) → Stats | null с v0.3stat(path) → Promise<Stats>size, mtime, isFile(), isDirectory()
extractSync(archive) → ArchiveEntry[] с v0.3extract(archive) → Promise<ArchiveEntry[]> с v0.3.1файлы архива
import * as 
fs
from "@amxts/core/fs";
async function saveMap() { await
fs
.
mkdir
(`${
server
.
dataDir
}/myplugin`, {
recursive
: true });
await
fs
.
writeFile
(`${
server
.
dataDir
}/myplugin/last-map.txt`,
server
.
map
);
}
fs
.
readFile
("missing.txt").
catch
((
error
) =>
console
.
log
(
error
.message));
// ENOENT: no such file or directory, open 'missing.txt'

Пути

Путь задаётся относительно папки игры, cstrike/, как у любого плагина AMX Mod X. server.configsDir — папка конфигов (addons/amxmodx/configs), server.dataDir — папка данных (addons/amxmodx/data), где бы сервер их ни держал. Храните файлы плагина в своей папке или под своим именем: configs/myplugin/, data/myplugin-stats.txt.

Текст

Файлы читаются и пишутся как текст в UTF-8. Файл читается целиком, какого бы размера он ни был. Метка порядка байтов (BOM) в начале файла сохраняется, как в Node.

Байты и архивы с v0.3

Файл, который не текст, — карта, звук, архив, — это байты: Uint8Array. readBytesSync читает его, а writeFileSync и appendFileSync принимают, кроме текста, Uint8Array или ArrayBuffer. fs.extract(bytes) даёт файлы архива, каждый — ArchiveEntry с путём path внутри архива и байтами data. Вид архива он узнаёт по первым байтам; читает zip-архивы:

import * as 
fs
from "@amxts/core/fs";
async function downloadMap(
name
: string) {
const
response
= await
fetch
(`https://maps.example.com/${
name
}.zip`);
for (const
entry
of await
fs
.
extract
(await
response
.
arrayBuffer
())) {
const
folder
=
entry
.
path
.
substring
(0,
entry
.
path
.
lastIndexOf
("/"));
if (
folder
.
length
> 0) await
fs
.
mkdir
(
folder
, {
recursive
: true });
await
fs
.
writeFile
(
entry
.
path
,
entry
.
data
);
} }

Большая загрузка может сразу идти в файл — request из @amxts/core/kit с опцией file, — а fs.readBytes прочитает её для extract.

Путь остаётся в папке игры
Байты читаются и пишутся только внутри папки игры: абсолютный путь или путь с .. даёт null или false. extract отклоняется с Error для архива с таким путём, для вида, который он не читает, — rar или 7z, а в сообщении названы виды, которые он читает, — и для зашифрованного или повреждённого архива. Из zip-архива он читает файлы, сохранённые как есть или сжатые deflate, — то, что пишут архиваторы, — и папки не перечисляет.

Не задерживая сервер с v0.3.1

Сервер работает кадр за кадром, и кадр ждёт код плагина. extract, readBytes, а также writeFile и appendFile с байтами делают свою работу в рабочем потоке сервера и выполняются на одном из следующих кадров, так что распаковка карты в мегабайты не задерживает игру. Их синхронные формы, extractSync, readBytesSync и writeFileSync, делают её сразу, внутри кадра: для маленького файла это нормально, для большого — лаг у игроков.

Байты, записанные writeFile и appendFile, ложатся в порядке вызовов. Текст пишется теми же файловыми функциями, что и в writeFileSync, сразу.

Сжатие с v0.3.1

@amxts/core/zlib сжимает и распаковывает байты так же, как zlib в Node, в трёх форматах:

СинхроннаяС промисомФормат
gzipSync(data), gunzipSync(data)gzip(data), gunzip(data)gzip, файл .gz
deflateSync(data), inflateSync(data)deflate(data), inflate(data)zlib: deflate с заголовком и контрольной суммой zlib
deflateRawSync(data), inflateRawSync(data)deflateRaw(data), inflateRaw(data)голый deflate, как файл лежит в zip-архиве

Каждая принимает Uint8Array или ArrayBuffer — сжимающие ещё и текст, в UTF-8, — и даёт Uint8Array. Формы с промисом работают в рабочем потоке сервера, как extract:

import * as 
fs
from "@amxts/core/fs";
import * as
zlib
from "@amxts/core/zlib";
async function saveRun(
name
: string,
recording
: Uint8Array) {
await
fs
.
writeFile
(`${
server
.
dataDir
}/myplugin/${
name
}.rec.gz`, await
zlib
.
gzip
(
recording
));
} async function loadRun(
name
: string): Promise<Uint8Array> {
return
zlib
.
gunzip
(await
fs
.
readBytes
(`${
server
.
dataDir
}/myplugin/${
name
}.rec.gz`));
}
Повреждённые данные
Данные, которые не целые данные своего формата, — обрезанные или другого формата, — бросают Error в синхронном вызове и отклоняют промис, со словами zlib: incorrect header check, unexpected end of file. Распаковка останавливается на 64 МБ: дальше вызов завершается ошибкой, а не сервер остаётся без памяти.

JSON

JSON читает и пишет текст JSON, как в JavaScript. JSON.parse говорят, что он читает, — JSON.parse<Stats>(text) или тип, куда уходит значение, — и он строит этот объект вместе с его массивами, Record и полями:

import * as 
fs
from "@amxts/core/fs";
interface Stats {
kills
: number;
deaths
: number;
lastMap
?: string;
} const
statsFile
= `${
server
.
dataDir
}/myplugin/stats.json`;
function loadStats(): Stats { const
text
=
fs
.
readFileSync
(
statsFile
);
if (
text
== null) return {
kills
: 0,
deaths
: 0 };
return
JSON
.
parse
(
text
);
} function saveStats(
stats
: Stats) {
fs
.
writeFileSync
(
statsFile
,
JSON
.
stringify
(
stats
, null, 2));
}

Текст, который не JSON, — это SyntaxError; значение не того рода, что говорит тип, — текст там, где число, поле, которое должно быть и которого нет, — это TypeError с именем поля. Ловите их через try/catch. JSON.stringify пропускает поле, которое undefined, пишет Date как её текст ISO, а объект с toJSON() — как то, что он отдаёт.

Uint8Array с v0.3.1 в JSON — текст base64 в обе стороны: JSON.stringify пишет его байты так, а не объектом индексов, как JavaScript, а JSON.parse читает текст base64 в поле типа Uint8Array.

Настройки, которые правит владелец сервера, типизированный конфиг config-core читает одинаково из YAML, JSON и INI.

Когда не получилось

Синхронная функция сообщает об ошибке результатом: null у readFileSync и readdirSync, false у writeFileSync, appendFileSync и mkdirSync — например, если нет папки. Функция с промисом отклоняется с Error, чьё сообщение начинается с ENOENT, как в Node (у mkdir — с EEXIST or ENOENT).

В обоих случаях работа делается сразу: к моменту, когда функция с промисом вернулась, промис уже завершён.

Операционная система

import { 
EOL
,
platform
} from "@amxts/core/os";
if (
platform
() == "linux")
console
.
log
("сервер на Linux");
const
lines
= ["first", "second"].
join
(
EOL
); // "\r\n" в Windows, "\n" в Linux

platform() — это "win32" или "linux", а EOL — перевод строки этой системы.

В тесте фейковый сервер держит папку игры в памяти: server.writeFile(path, text) — до того, как плагин читает, server.file(path) — после того, как он записал (Тесты).