@nitpicker/crawler 0.4.1

package/lib/archive/debug.d.ts

@@ -0,0 +1,8 @@
+/** Debug logger for the archive package. Namespace: `Nitpicker:Utils:Archive`. */
+export declare const log: import("debug").Debugger;
+/** Debug logger for archive save operations. Namespace: `Nitpicker:Utils:Archive:Save`. */
+export declare const saveLog: import("debug").Debugger;
+/** Debug logger for database operations. Namespace: `Nitpicker:Utils:Archive:DB`. */
+export declare const dbLog: import("debug").Debugger;
+/** Debug logger for archive errors. Namespace: `Nitpicker:Utils:Archive:Error`. */
+export declare const errorLog: import("debug").Debugger;

package/lib/archive/debug.js

@@ -0,0 +1,9 @@
+import { log as globalLog } from '../utils/debug.js';
+/** Debug logger for the archive package. Namespace: `Nitpicker:Utils:Archive`. */
+export const log = globalLog.extend('Archive');
+/** Debug logger for archive save operations. Namespace: `Nitpicker:Utils:Archive:Save`. */
+export const saveLog = log.extend('Save');
+/** Debug logger for database operations. Namespace: `Nitpicker:Utils:Archive:DB`. */
+export const dbLog = log.extend('DB');
+/** Debug logger for archive errors. Namespace: `Nitpicker:Utils:Archive:Error`. */
+export const errorLog = log.extend('Error');

package/lib/archive/filesystem/append-text.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Appends text data to a file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * A newline character is prepended to the data before appending.
+ * @param filePath - The absolute or relative path to the file to append to.
+ * @param data - The text content to append to the file.
+ */
+export declare function appendText(filePath: string, data: string): Promise<void>;

package/lib/archive/filesystem/append-text.js

@@ -0,0 +1,14 @@
+import { promises as fs } from 'node:fs';
+import { mkdir } from './mkdir.js';
+/**
+ * Appends text data to a file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * A newline character is prepended to the data before appending.
+ * @param filePath - The absolute or relative path to the file to append to.
+ * @param data - The text content to append to the file.
+ */
+export async function appendText(filePath, data) {
+    mkdir(filePath);
+    await fs.appendFile(filePath, `\n${data}`, { encoding: 'utf8' });
+}

package/lib/archive/filesystem/copy-dir-sync.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Synchronously copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ */
+export declare function copyDirSync(from: string, to: string): void;

package/lib/archive/filesystem/copy-dir-sync.js

@@ -0,0 +1,9 @@
+import fsx from 'fs-extra';
+/**
+ * Synchronously copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ */
+export function copyDirSync(from, to) {
+    fsx.copySync(from, to);
+}

package/lib/archive/filesystem/copy-dir.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Recursively copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ * @returns `true` if the copy succeeded, `false` if an error occurred.
+ */
+export declare function copyDir(from: string, to: string): Promise<boolean>;

package/lib/archive/filesystem/copy-dir.js

@@ -0,0 +1,13 @@
+import fsx from 'fs-extra';
+/**
+ * Recursively copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ * @returns `true` if the copy succeeded, `false` if an error occurred.
+ */
+export async function copyDir(from, to) {
+    return fsx
+        .copy(from, to)
+        .then(() => true)
+        .catch(() => false);
+}

package/lib/archive/filesystem/exists.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks whether a file or directory exists at the given path.
+ * @param filePath - The path to check for existence.
+ * @returns `true` if the path exists, `false` otherwise.
+ */
+export declare function exists(filePath: string): boolean;

package/lib/archive/filesystem/exists.js

@@ -0,0 +1,9 @@
+import { existsSync } from 'node:fs';
+/**
+ * Checks whether a file or directory exists at the given path.
+ * @param filePath - The path to check for existence.
+ * @returns `true` if the path exists, `false` otherwise.
+ */
+export function exists(filePath) {
+    return existsSync(filePath);
+}

package/lib/archive/filesystem/get-file-list.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Lists the file names in a directory, optionally filtered by a pattern.
+ * @param dirPath - The directory path to list files from.
+ * @param filter - An optional RegExp or string pattern to filter file names.
+ *   Only file names matching this pattern are included in the result.
+ * @returns An array of file names in the directory that match the filter (or all if no filter is provided).
+ */
+export declare function getFileList(dirPath: string, filter?: RegExp | string): Promise<string[]>;

package/lib/archive/filesystem/get-file-list.js

@@ -0,0 +1,12 @@
+import fsx from 'fs-extra';
+/**
+ * Lists the file names in a directory, optionally filtered by a pattern.
+ * @param dirPath - The directory path to list files from.
+ * @param filter - An optional RegExp or string pattern to filter file names.
+ *   Only file names matching this pattern are included in the result.
+ * @returns An array of file names in the directory that match the filter (or all if no filter is provided).
+ */
+export async function getFileList(dirPath, filter) {
+    const list = await fsx.readdir(dirPath);
+    return filter ? list.filter((fileName) => fileName.match(filter)) : list;
+}

package/lib/archive/filesystem/index.d.ts

@@ -0,0 +1,17 @@
+export { outputJSON } from './output-json.js';
+export { readJSON } from './read-json.js';
+export { outputText } from './output-text.js';
+export { appendText } from './append-text.js';
+export { readText } from './read-text.js';
+export { copyDir } from './copy-dir.js';
+export { copyDirSync } from './copy-dir-sync.js';
+export { isDir } from './is-dir.js';
+export { remove } from './remove.js';
+export { rename } from './rename.js';
+export { getFileList } from './get-file-list.js';
+export { readline } from './readline.js';
+export { mkdir } from './mkdir.js';
+export { exists } from './exists.js';
+export { tar } from './tar.js';
+export { untar } from './untar.js';
+export { zip, unzip, extractZip } from '@d-zero/fs/zip';

package/lib/archive/filesystem/index.js

@@ -0,0 +1,17 @@
+export { outputJSON } from './output-json.js';
+export { readJSON } from './read-json.js';
+export { outputText } from './output-text.js';
+export { appendText } from './append-text.js';
+export { readText } from './read-text.js';
+export { copyDir } from './copy-dir.js';
+export { copyDirSync } from './copy-dir-sync.js';
+export { isDir } from './is-dir.js';
+export { remove } from './remove.js';
+export { rename } from './rename.js';
+export { getFileList } from './get-file-list.js';
+export { readline } from './readline.js';
+export { mkdir } from './mkdir.js';
+export { exists } from './exists.js';
+export { tar } from './tar.js';
+export { untar } from './untar.js';
+export { zip, unzip, extractZip } from '@d-zero/fs/zip';

package/lib/archive/filesystem/is-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks whether the given path points to a directory.
+ * @param dirPath - The path to check.
+ * @returns `true` if the path is a directory, `false` otherwise.
+ */
+export declare function isDir(dirPath: string): Promise<boolean>;

package/lib/archive/filesystem/is-dir.js

@@ -0,0 +1,10 @@
+import fsx from 'fs-extra';
+/**
+ * Checks whether the given path points to a directory.
+ * @param dirPath - The path to check.
+ * @returns `true` if the path is a directory, `false` otherwise.
+ */
+export async function isDir(dirPath) {
+    const stat = await fsx.stat(dirPath);
+    return stat.isDirectory();
+}

package/lib/archive/filesystem/mkdir.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Ensures the parent directory of the given file path exists.
+ *
+ * If the parent directory does not exist, it is created recursively
+ * with permissions `0o700` (owner-only access).
+ * @param filePath - The file path whose parent directory should be created.
+ */
+export declare function mkdir(filePath: string): void;

package/lib/archive/filesystem/mkdir.js

@@ -0,0 +1,15 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Ensures the parent directory of the given file path exists.
+ *
+ * If the parent directory does not exist, it is created recursively
+ * with permissions `0o700` (owner-only access).
+ * @param filePath - The file path whose parent directory should be created.
+ */
+export function mkdir(filePath) {
+    const { dir } = path.parse(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(path.resolve(dir), { recursive: true, mode: 0o700 });
+    }
+}

package/lib/archive/filesystem/output-json.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Writes data to a JSON file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * The output is formatted with 2-space indentation.
+ * @param filePath - The absolute or relative path to the JSON file to write.
+ * @param data - The data to serialize as JSON and write to the file.
+ */
+export declare function outputJSON(filePath: string, data: unknown): Promise<void>;

package/lib/archive/filesystem/output-json.js

@@ -0,0 +1,14 @@
+import { promises as fs } from 'node:fs';
+import { mkdir } from './mkdir.js';
+/**
+ * Writes data to a JSON file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * The output is formatted with 2-space indentation.
+ * @param filePath - The absolute or relative path to the JSON file to write.
+ * @param data - The data to serialize as JSON and write to the file.
+ */
+export async function outputJSON(filePath, data) {
+    mkdir(filePath);
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2), { encoding: 'utf8' });
+}

package/lib/archive/filesystem/output-text.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Writes text data to a file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * If the file path exceeds the OS limit (ENAMETOOLONG), the file is saved
+ * with an auto-generated short name and an accompanying `.meta.txt` file
+ * that records the original file path.
+ * @param filePath - The absolute or relative path to the text file to write.
+ * @param data - The text content to write to the file.
+ */
+export declare function outputText(filePath: string, data: string): Promise<void>;

package/lib/archive/filesystem/output-text.js

@@ -0,0 +1,32 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { mkdir } from './mkdir.js';
+let filePathTooLongCount = 0;
+/**
+ * Writes text data to a file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * If the file path exceeds the OS limit (ENAMETOOLONG), the file is saved
+ * with an auto-generated short name and an accompanying `.meta.txt` file
+ * that records the original file path.
+ * @param filePath - The absolute or relative path to the text file to write.
+ * @param data - The text content to write to the file.
+ */
+export async function outputText(filePath, data) {
+    mkdir(filePath);
+    await fs.writeFile(filePath, data, { encoding: 'utf8' }).catch(async (error) => {
+        if (error instanceof Error && 'code' in error && error.code === 'ENAMETOOLONG') {
+            // eslint-disable-next-line no-console
+            console.error(`File path too long: ${filePath}`);
+            const dir = path.dirname(filePath);
+            const altFileName = `__file_path_too_long_${(filePathTooLongCount++).toString().padStart(4, '0')}`;
+            const ext = path.extname(filePath);
+            const altFilePath = path.resolve(dir, `${altFileName}${ext}`);
+            // eslint-disable-next-line no-console
+            console.error(`Try to save to: ${altFilePath}`);
+            const altMetaFilePath = path.resolve(dir, `${altFileName}.meta.txt`);
+            await outputText(altFilePath, data);
+            await outputText(altMetaFilePath, `Original file path: ${filePath}`);
+        }
+    });
+}

package/lib/archive/filesystem/read-json.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reads and parses a JSON file from the specified path.
+ * @template T - The expected type of the parsed JSON content. Defaults to `unknown`.
+ * @param filePath - The absolute or relative path to the JSON file to read.
+ * @returns The parsed JSON content, cast to the specified generic type.
+ */
+export declare function readJSON<T = unknown>(filePath: string): Promise<T>;

package/lib/archive/filesystem/read-json.js

@@ -0,0 +1,11 @@
+import { promises as fs } from 'node:fs';
+/**
+ * Reads and parses a JSON file from the specified path.
+ * @template T - The expected type of the parsed JSON content. Defaults to `unknown`.
+ * @param filePath - The absolute or relative path to the JSON file to read.
+ * @returns The parsed JSON content, cast to the specified generic type.
+ */
+export async function readJSON(filePath) {
+    const data = await fs.readFile(filePath, { encoding: 'utf8' });
+    return JSON.parse(data);
+}

package/lib/archive/filesystem/read-text.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads the entire contents of a text file as a UTF-8 string.
+ * @param filePath - The absolute or relative path to the text file to read.
+ * @returns The text content of the file.
+ */
+export declare function readText(filePath: string): Promise<string>;

package/lib/archive/filesystem/read-text.js

@@ -0,0 +1,10 @@
+import { promises as fs } from 'node:fs';
+/**
+ * Reads the entire contents of a text file as a UTF-8 string.
+ * @param filePath - The absolute or relative path to the text file to read.
+ * @returns The text content of the file.
+ */
+export async function readText(filePath) {
+    const data = await fs.readFile(filePath, { encoding: 'utf8' });
+    return data;
+}

package/lib/archive/filesystem/readline.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reads a file line by line and invokes the callback for each line.
+ *
+ * The callback may return a Promise for asynchronous processing.
+ * All callback results are collected and awaited via `Promise.all` before returning.
+ * @param filePath - The path to the file to read line by line.
+ * @param callback - A function invoked for each line of the file.
+ *   May return a Promise for asynchronous operations.
+ * @returns A promise that resolves when all line callbacks have completed.
+ */
+export declare function readline(filePath: string, callback: (line: string) => Promise<void> | void): Promise<void[]>;

package/lib/archive/filesystem/readline.js

@@ -0,0 +1,26 @@
+import { createReadStream } from 'node:fs';
+import Readline from 'node:readline';
+/**
+ * Reads a file line by line and invokes the callback for each line.
+ *
+ * The callback may return a Promise for asynchronous processing.
+ * All callback results are collected and awaited via `Promise.all` before returning.
+ * @param filePath - The path to the file to read line by line.
+ * @param callback - A function invoked for each line of the file.
+ *   May return a Promise for asynchronous operations.
+ * @returns A promise that resolves when all line callbacks have completed.
+ */
+export async function readline(filePath, callback) {
+    const stream = createReadStream(filePath);
+    const rLine = Readline.createInterface(stream);
+    const promiseBuffer = [];
+    await new Promise((resolve) => {
+        rLine.on('line', (line) => {
+            promiseBuffer.push(callback(line));
+        });
+        rLine.on('close', () => {
+            resolve();
+        });
+    });
+    return Promise.all(promiseBuffer);
+}

package/lib/archive/filesystem/remove.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Recursively removes a file or directory at the specified path.
+ * @param dirPath - The path of the file or directory to remove.
+ */
+export declare function remove(dirPath: string): Promise<void>;

package/lib/archive/filesystem/remove.js

@@ -0,0 +1,10 @@
+import { promises as fs } from 'node:fs';
+/**
+ * Recursively removes a file or directory at the specified path.
+ * @param dirPath - The path of the file or directory to remove.
+ */
+export async function remove(dirPath) {
+    await fs.rm(dirPath, {
+        recursive: true,
+    });
+}

package/lib/archive/filesystem/rename.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Renames (moves) a file or directory from one path to another.
+ *
+ * If `override` is `true`, the destination is unconditionally removed
+ * before renaming. This avoids a TOCTOU race condition between
+ * checking existence and performing the removal.
+ * @param oldPath - The current path of the file or directory.
+ * @param newPath - The new path for the file or directory.
+ * @param override - Whether to overwrite the destination if it already exists. Defaults to `false`.
+ */
+export declare function rename(oldPath: string, newPath: string, override?: boolean): Promise<void>;

package/lib/archive/filesystem/rename.js

@@ -0,0 +1,18 @@
+import { promises as fs } from 'node:fs';
+import { remove } from './remove.js';
+/**
+ * Renames (moves) a file or directory from one path to another.
+ *
+ * If `override` is `true`, the destination is unconditionally removed
+ * before renaming. This avoids a TOCTOU race condition between
+ * checking existence and performing the removal.
+ * @param oldPath - The current path of the file or directory.
+ * @param newPath - The new path for the file or directory.
+ * @param override - Whether to overwrite the destination if it already exists. Defaults to `false`.
+ */
+export async function rename(oldPath, newPath, override = false) {
+    if (override) {
+        await remove(newPath).catch(() => { });
+    }
+    await fs.rename(oldPath, newPath);
+}

package/lib/archive/filesystem/tar.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates an uncompressed TAR archive from a directory.
+ *
+ * The archive preserves the relative directory structure.
+ * The `dir` parameter is resolved relative to its parent directory
+ * so only the target directory name appears in the archive.
+ * @param dir - The absolute path of the directory to archive.
+ * @param outputPath - The file path where the TAR archive will be written.
+ * @returns A promise that resolves when the TAR archive has been created.
+ */
+export declare function tar(dir: string, outputPath: string): Promise<void>;

package/lib/archive/filesystem/tar.js

@@ -0,0 +1,22 @@
+import path from 'node:path';
+import { create } from 'tar';
+/**
+ * Creates an uncompressed TAR archive from a directory.
+ *
+ * The archive preserves the relative directory structure.
+ * The `dir` parameter is resolved relative to its parent directory
+ * so only the target directory name appears in the archive.
+ * @param dir - The absolute path of the directory to archive.
+ * @param outputPath - The file path where the TAR archive will be written.
+ * @returns A promise that resolves when the TAR archive has been created.
+ */
+export function tar(dir, outputPath) {
+    const baseDir = path.dirname(dir);
+    const targetDir = path.relative(baseDir, dir);
+    return create({
+        gzip: false,
+        cwd: baseDir,
+        file: outputPath,
+        preservePaths: false,
+    }, [targetDir]);
+}

package/lib/archive/filesystem/untar.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Extracts files from a TAR archive.
+ *
+ * Only files newer than existing files in the target directory are extracted
+ * (uses the `newer` option). Optionally restricts extraction to a specific
+ * working directory and/or a subset of files.
+ * @param tarFilePath - The path to the TAR archive to extract.
+ * @param options - Optional extraction settings.
+ * @param options.cwd - The working directory to extract files into.
+ *   If omitted, the current working directory is used.
+ * @param options.fileList - An array of specific file paths within the archive
+ *   to extract. If omitted, all files in the archive are extracted.
+ * @returns A promise that resolves when extraction is complete.
+ */
+export declare function untar(tarFilePath: string, options?: {
+    /** The working directory to extract files into. */
+    cwd?: string;
+    /** An array of specific file paths within the archive to extract. */
+    fileList?: string[];
+}): Promise<void>;

package/lib/archive/filesystem/untar.js

@@ -0,0 +1,24 @@
+import { extract } from 'tar';
+/**
+ * Extracts files from a TAR archive.
+ *
+ * Only files newer than existing files in the target directory are extracted
+ * (uses the `newer` option). Optionally restricts extraction to a specific
+ * working directory and/or a subset of files.
+ * @param tarFilePath - The path to the TAR archive to extract.
+ * @param options - Optional extraction settings.
+ * @param options.cwd - The working directory to extract files into.
+ *   If omitted, the current working directory is used.
+ * @param options.fileList - An array of specific file paths within the archive
+ *   to extract. If omitted, all files in the archive are extracted.
+ * @returns A promise that resolves when extraction is complete.
+ */
+export function untar(tarFilePath, options) {
+    return extract({
+        file: tarFilePath,
+        newer: true,
+        cwd: options?.cwd,
+        preservePaths: false,
+        noMtime: true,
+    }, options?.fileList ?? []);
+}

package/lib/archive/filesystem/utils.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Writes data to a JSON file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * The output is formatted with 2-space indentation.
+ * @param filePath - The absolute or relative path to the JSON file to write.
+ * @param data - The data to serialize as JSON and write to the file.
+ */
+export declare function outputJSON(filePath: string, data: unknown): Promise<void>;
+/**
+ * Reads and parses a JSON file from the specified path.
+ * @template T - The expected type of the parsed JSON content. Defaults to `unknown`.
+ * @param filePath - The absolute or relative path to the JSON file to read.
+ * @returns The parsed JSON content, cast to the specified generic type.
+ */
+export declare function readJSON<T = unknown>(filePath: string): Promise<T>;
+/**
+ * Writes text data to a file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * If the file path exceeds the OS limit (ENAMETOOLONG), the file is saved
+ * with an auto-generated short name and an accompanying `.meta.txt` file
+ * that records the original file path.
+ * @param filePath - The absolute or relative path to the text file to write.
+ * @param data - The text content to write to the file.
+ */
+export declare function outputText(filePath: string, data: string): Promise<void>;
+/**
+ * Appends text data to a file at the specified path.
+ *
+ * Creates parent directories if they do not exist.
+ * A newline character is prepended to the data before appending.
+ * @param filePath - The absolute or relative path to the file to append to.
+ * @param data - The text content to append to the file.
+ */
+export declare function appendText(filePath: string, data: string): Promise<void>;
+/**
+ * Reads the entire contents of a text file as a UTF-8 string.
+ * @param filePath - The absolute or relative path to the text file to read.
+ * @returns The text content of the file.
+ */
+export declare function readText(filePath: string): Promise<string>;
+/**
+ * Recursively copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ * @returns `true` if the copy succeeded, `false` if an error occurred.
+ */
+export declare function copyDir(from: string, to: string): Promise<boolean>;
+/**
+ * Synchronously copies a directory and its contents from one location to another.
+ * @param from - The source directory path to copy from.
+ * @param to - The destination directory path to copy to.
+ */
+export declare function copyDirSync(from: string, to: string): void;
+/**
+ * Checks whether the given path points to a directory.
+ * @param dirPath - The path to check.
+ * @returns `true` if the path is a directory, `false` otherwise.
+ */
+export declare function isDir(dirPath: string): Promise<boolean>;
+/**
+ * Recursively removes a file or directory at the specified path.
+ * @param dirPath - The path of the file or directory to remove.
+ */
+export declare function remove(dirPath: string): Promise<void>;
+/**
+ * Renames (moves) a file or directory from one path to another.
+ *
+ * If `override` is `true` and the destination already exists,
+ * the destination is removed before renaming.
+ * @param oldPath - The current path of the file or directory.
+ * @param newPath - The new path for the file or directory.
+ * @param override - Whether to overwrite the destination if it already exists. Defaults to `false`.
+ */
+export declare function rename(oldPath: string, newPath: string, override?: boolean): Promise<void>;
+/**
+ * Lists the file names in a directory, optionally filtered by a pattern.
+ * @param dirPath - The directory path to list files from.
+ * @param filter - An optional RegExp or string pattern to filter file names.
+ *   Only file names matching this pattern are included in the result.
+ * @returns An array of file names in the directory that match the filter (or all if no filter is provided).
+ */
+export declare function getFileList(dirPath: string, filter?: RegExp | string): Promise<string[]>;
+/**
+ * Reads a file line by line and invokes the callback for each line.
+ *
+ * The callback may return a Promise for asynchronous processing.
+ * All callback results are collected and awaited via `Promise.all` before returning.
+ * @param filePath - The path to the file to read line by line.
+ * @param callback - A function invoked for each line of the file.
+ *   May return a Promise for asynchronous operations.
+ * @returns A promise that resolves when all line callbacks have completed.
+ */
+export declare function readline(filePath: string, callback: (line: string) => Promise<void> | void): Promise<void[]>;
+/**
+ * Ensures the parent directory of the given file path exists.
+ *
+ * If the parent directory does not exist, it is created recursively
+ * with permissions `0o755`.
+ * @param filePath - The file path whose parent directory should be created.
+ */
+export declare function mkdir(filePath: string): void;
+/**
+ * Checks whether a file or directory exists at the given path.
+ * @param filePath - The path to check for existence.
+ * @returns `true` if the path exists, `false` otherwise.
+ */
+export declare function exists(filePath: string): boolean;