umbot/dist/utils/standard/util.d.ts

Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф

/**
 * Модуль вспомогательных утилит
 *
 * Предоставляет набор утилит для:
 * - Работы с файловой системой
 * - Обработки текста
 * - Работы с HTTP-параметрами
 * - Взаимодействия с консолью
 */
import * as fs from 'fs';
import { TLoggerCb } from '../../core/interfaces/ILogger';
import { IDir } from '../../core/interfaces/IAppContext';
/**
 * Интерфейс для GET-параметров
 *
 * @example
 * ```ts
 * const params: IGetParams = {
 *   name: 'John',
 *   age: '25'
 * };
 * ```
 */
export interface IGetParams {
    [key: string]: string;
}
/**
 * Возвращает случайное число из заданного диапазона
 *
 * @param {number} min - Минимальное значение диапазона (включительно)
 * @param {number} max - Максимальное значение диапазона (включительно)
 * @returns {number} Случайное целое число из диапазона [min, max]
 *
 * @example
 * ```ts
 * rand(1, 10); // -> случайное число от 1 до 10
 * rand(0, 1); // -> 0 или 1
 * ```
 */
export declare function rand(min: number, max: number): number;
/**
 * Метод, возвращающий количество ключей в объекте
 * @param obj
 */
export declare function keysCount(obj: object | Record<string, unknown>): number;
/**
 * Вычисляет процент схожести двух текстов
 * Использует алгоритм LCS (Longest Common Subsequence)
 *
 * @param {string} first - Первый текст для сравнения
 * @param {string} second - Второй текст для сравнения
 * @returns {number} Процент схожести от 0 до 100
 *
 * @example
 * ```ts
 * similarText('привет', 'привт'); // -> ~90
 * similarText('hello', 'world'); // -> ~20
 * similarText('same', 'same'); // -> 100
 * ```
 */
export declare function similarText(first: string, second: string): number;
/**
 * Результат выполнения операции с файлом
 *
 * @template T - Тип данных, возвращаемых при успешной операции
 *
 * @example
 * ```ts
 * const result: FileOperationResult<string> = {
 *   success: true,
 *   data: 'file content'
 * };
 *
 * const error: FileOperationResult<void> = {
 *   success: false,
 *   error: new Error('File not found')
 * };
 * ```
 */
export interface FileOperationResult<T> {
    /**
     * Флаг успешности операции
     * true - операция выполнена успешно
     * false - произошла ошибка
     */
    success: boolean;
    /**
     * Данные, полученные в результате операции.
     * Присутствует только при success = true
     */
    data?: T;
    /**
     * Ошибка, возникшая при выполнении операции.
     * Присутствует только при success = false
     */
    error?: Error;
}
/**
 * Синхронно проверяет существование файла
 *
 * @param {string} file - Путь к проверяемому файлу
 * @returns {boolean} true, если файл существует и это файл, иначе false
 *
 * @example
 * ```ts
 * isFile('path/to/file.txt'); // -> true
 * isFile('path/to/directory'); // -> false
 * isFile('nonexistent.txt'); // -> false
 * ```
 */
export declare function isFileSync(file: string): boolean;
/**
 * Синхронно возвращает информацию о файле
 *
 * @param {string} fileName - Путь к файлу
 * @returns {FileOperationResult<fs.Stats>} Результат операции с информацией о файле
 *
 * @example
 * ```ts
 * const result = getFileInfo('file.txt');
 * if (result.success) {
 *   console.log(result.data.size); // размер файла
 *   console.log(result.data.mtime); // время последнего изменения
 * } else {
 *   console.error(result.error);
 * }
 * ```
 */
export declare function getFileInfoSync(fileName: string): FileOperationResult<fs.Stats>;
/**
 * Синхронно читает содержимое файла
 *
 * @param {string} fileName - Путь к файлу
 * @returns {FileOperationResult<string>} Результат операции с содержимым файла
 *
 * @example
 * ```ts
 * const result = fread('file.txt');
 * if (result.success) {
 *   console.log(result.data); // содержимое файла
 * } else {
 *   console.error(result.error);
 * }
 * ```
 */
export declare function freadSync(fileName: string): FileOperationResult<string>;
/**
 * Синхронно записывает данные в файл
 *
 * @param {string} fileName - Путь к файлу
 * @param {string | Uint8Array} fileContent - Содержимое для записи
 * @param {'w' | 'a'} [mode='w'] - Режим записи:
 *   - 'w' - перезапись файла
 *   - 'a' - добавление в конец файла
 * @returns {FileOperationResult<void>} Результат операции записи
 *
 * @example
 * ```ts
 * // Перезапись файла
 * fwrite('file.txt', 'new content');
 *
 * // Добавление в конец файла
 * fwrite('file.txt', 'additional content', 'a');
 * ```
 */
export declare function fwriteSync(fileName: string, fileContent: string | Uint8Array, mode?: 'w' | 'a' | string): FileOperationResult<void>;
/**
 * Синхронно удаляет файл
 *
 * @param {string} fileName - Путь к файлу
 * @returns {FileOperationResult<void>} Результат операции удаления
 *
 * @example
 * ```ts
 * const result = unlink('file.txt');
 * if (result.success) {
 *   console.log('File deleted successfully');
 * } else {
 *   console.error(result.error);
 * }
 * ```
 */
export declare function unlinkSync(fileName: string): FileOperationResult<void>;
/**
 * Синхронно проверяет существование директории
 *
 * @param {string} path - Путь к директории
 * @returns {boolean} true, если директория существует, иначе false
 *
 * @example
 * ```ts
 * isDir('path/to/directory'); // -> true
 * isDir('nonexistent/dir'); // -> false
 * ```
 */
export declare function isDirSync(path: string): boolean;
/**
 * Синхронно создает директорию
 *
 * @param {string} path - Путь к создаваемой директории
 * @param {fs.Mode} [mask='0774'] - Маска прав доступа
 * @returns {FileOperationResult<void>} Результат операции создания директории
 *
 * @example
 * ```ts
 * const result = mkdir('new/directory');
 * if (result.success) {
 *   console.log('Directory created successfully');
 * } else {
 *   console.error(result.error);
 * }
 * ```
 */
export declare function mkdirSync(path: string, mask?: fs.Mode): FileOperationResult<void>;
/**
 * Синхронно сохраняет данные в файл
 * @param {IDir} dir - Объект с путем и названием файла
 * @param {string} data - Сохраняемые данные
 * @param {string} mode - Режим записи
 * @param {TLoggerCb} errorLogger - Функция для логирования ошибок
 * @returns {boolean} true в случае успешного сохранения
 */
export declare function saveDataSync(dir: IDir, data: string, mode?: string, errorLogger?: TLoggerCb): boolean;
/**
 * Синхронно возвращает информацию о файле
 *
 * @param {string} fileName - Путь к файлу
 * @returns {FileOperationResult<fs.Stats>} Результат операции с информацией о файле
 *
 * @example
 * ```ts
 * const result = getFileInfo('file.txt');
 * if (result.success) {
 *   console.log(result.data.size); // размер файла
 *   console.log(result.data.mtime); // время последнего изменения
 * } else {
 *   console.error(result.error);
 * }
 * ```
 */
export declare function getFileInfo(fileName: string): Promise<FileOperationResult<fs.Stats>>;
/**
 * Синхронно проверяет существование файла
 *
 * @param {string} file - Путь к проверяемому файлу
 * @returns {boolean} true, если файл существует и это файл, иначе false
 *
 * @example
 * ```ts
 * isFile('path/to/file.txt'); // -> true
 * isFile('path/to/directory'); // -> false
 * isFile('nonexistent.txt'); // -> false
 * ```
 */
export declare function isFile(file: string): Promise<boolean>;
/**
 * Проверяет существование директории
 * @param path - Путь к директории
 * @returns Promise<boolean> - true если директория существует
 */
export declare function isDir(path: string): Promise<boolean>;
/**
 * Создает директорию
 * @param path - Путь к создаваемой директории
 * @param mask - Маска прав доступа
 * @returns Promise с результатом операции
 */
export declare function mkdir(path: string, mask?: fs.Mode): Promise<FileOperationResult<void>>;
/**
 * Читает файл
 * @param fileName - Путь к файлу
 * @returns Promise с результатом операции
 */
export declare function fread(fileName: string): Promise<FileOperationResult<string | Buffer>>;
/**
 * Записывает данные в файл
 * @param fileName - Путь к файлу
 * @param fileContent - Содержимое для записи
 * @param mode - Режим записи: 'w' - перезапись, 'a' - добавление
 * @returns Promise с результатом операции
 */
export declare function fwrite(fileName: string, fileContent: string | Uint8Array, mode?: 'w' | 'a' | string): Promise<FileOperationResult<void>>;
/**
 * Удаляет файл
 * @param fileName - Путь к файлу
 * @returns Promise с результатом операции
 */
export declare function unlink(fileName: string): Promise<FileOperationResult<void>>;
/**
 * Сохраняет данные в файл
 * @param {IDir} dir - Объект с путем и названием файла
 * @param {string} data - Сохраняемые данные
 * @param {string} mode - Режим записи
 * @param {TLoggerCb} errorLogger - Функция для логирования ошибок
 * @returns {boolean} true в случае успешного сохранения
 */
export declare function saveData(dir: IDir, data: string, mode?: string, errorLogger?: TLoggerCb): Promise<boolean>;
/**
 * Преобразует объект параметров в URL-строку запроса
 *
 * @param {IGetParams} formData - Объект с параметрами
 * @param {string} [separator='&'] - Разделитель параметров
 * @returns {string} URL-строка запроса
 *
 * @example
 * ```ts
 * const params = {
 *   name: 'John Doe',
 *   age: '25'
 * };
 *
 * httpBuildQuery(params);
 * // -> 'name=John+Doe&age=25'
 *
 * httpBuildQuery(params, ';');
 * // -> 'name=John+Doe;age=25'
 * ```
 */
export declare function httpBuildQuery(formData: IGetParams, separator?: string): string;
/**
 * Читает введенные данные из консоли
 *
 * @returns {Promise<string>} Промис с введенной строкой
 *
 * @example
 * ```ts
 * // В консоли:
 * // > Enter your name: John
 * const name = await stdin(); // -> 'John'
 * ```
 */
export declare function stdin(): Promise<string>;