Fylo: A Versatile Library for File and Stream Management in Node.js

Fylo is a powerful library designed to make file system operations in Node.js convenient, fast, and secure. Supporting Node.js versions 8.16.0 and above, Fylo is ideal for developers working with both modern and legacy versions of the platform. If you need to ensure reliable file and directory operations on older systems, Fylo will be your indispensable tool.

Table of Contents

• About the Library
• Working with Files and Directories
  • File Management
    • Checking File Existence
    • Reading a File
    • Writing to a File
    • Renaming a File
    • Deleting a File
  • Directory Management
    • Creating a Directory
    • Deleting a Directory
    • Reading Directory Contents
    • Clearing a Directory
• Reading and Writing Streams
  • Reading Data (ReadStream)
  • Writing Data (WriteStream)
• File and Directory Watchers
  • File Watcher (FileWatcher)
  • Directory Watcher (DirectoryWatcher)
• License
• Author
• Reporting Issues
• Support the Author
• Conclusion

About the Library

The development of Fylo started with a real-world challenge: creating software for IoT controllers running Node.js version 8.16.0. We encountered the problem of many modern libraries being incompatible with this version of the platform. Fylo was created to solve this problem, offering a powerful, convenient, and reliable tool for working with files and streams, even supporting outdated Node.js versions.

Fylo is a library that allows you to effortlessly manage files and directories, as well as work with reading and writing streams, ensuring maximum performance with minimal resource usage. With Fylo, your code becomes cleaner, simpler, and more reliable.

Working with Files and Directories

Fylo offers a complete set of functions for working with files and directories. Whether you need to check file existence, read its contents, or create a new directory, Fylo provides simple and intuitive methods.

File Management

Checking File Existence

The exists method allows you to instantly check whether a file exists at a given path. This is particularly useful for operations that require a preliminary check of file availability.

Fylo provides two versions of this method:

1. Asynchronous version exists.
2. Synchronous version existsSync.

Parameters:

• path (string): The path to the file that needs to be checked.

Return Value:

• boolean: Returns true if the file exists, and false otherwise.

TypeScript

import { exists } from 'fylo';

const exists = await exists('/path/to/file.txt');
console.log(`File exists: ${exists}`);

JavaScript (CommonJS)

const { exists } = require('fylo');

exists('/path/to/file.txt').then((exists) => {
	console.log(`File exists: ${exists}`);
});

TypeScript

import { existsSync } from 'fylo';

const exists = existsSync('/path/to/file.txt');
console.log(`File exists: ${exists}`);

JavaScript (CommonJS)

const { existsSync } = require('fylo');

const exists = existsSync('/path/to/file.txt');
console.log(`File exists: ${exists}`);

Reading a File

The readFile method provides a quick and safe way to read the contents of a file. You can specify the desired encoding or retrieve the data as a buffer.

Fylo provides two versions of this method:

1. Asynchronous version readFile.
2. Synchronous version readFileSync.

Parameters:

• path (string): The path to the file whose contents need to be read.
• encoding (BufferEncoding, optional): The encoding for reading the file. Defaults to utf8.

Return Value:

• string or Buffer: The file contents as a string (if encoding is specified) or a buffer.

TypeScript

import { readFile } from 'fylo';

const content = await readFile('/path/to/file.txt', 'utf8');
console.log(`File content: ${content}`);

JavaScript (CommonJS)

const { readFile } = require('fylo');

readFile('/path/to/file.txt', 'utf8').then((content) => {
	console.log(`File content: ${content}`);
});

TypeScript

import { readFileSync } from 'fylo';

const content = readFileSync('/path/to/file.txt', 'utf8');
console.log(`File content: ${content}`);

JavaScript (CommonJS)

const { readFileSync } = require('fylo');

const content = readFileSync('/path/to/file.txt', 'utf8');
console.log(`File content: ${content}`);

Writing to a File

The writeFile method allows you to easily write data to a file, choosing the appropriate encoding and access mode. This method is perfect for both creating new files and updating existing ones.

Fylo provides two versions of this method:

1. Asynchronous version writeFile.
2. Synchronous version writeFileSync.

Parameters:

• path (string): The path to the file where the data needs to be written.
• data (string | Buffer): The data to be written to the file.
• options (IFileOptions, optional): Additional write options:
  • encoding (BufferEncoding, optional): The encoding of the data. Defaults to utf8.
  • mode (number, optional): Sets the file's permissions. Defaults to 0o666.
  • flag (TFileModeFlag, optional): The mode for opening the file. Defaults to w (write and overwrite).

Return Value:

• void

TypeScript

import { writeFile } from 'fylo';

await writeFile('/path/to/file.txt', 'Hello, World!', { encoding: 'utf8', mode: 0o666, flag: 'w' });
console.log('Data successfully written.');

JavaScript (CommonJS)

const { writeFile } = require('fylo');

writeFile('/path/to/file.txt', 'Hello, World!', { encoding: 'utf8', mode: 0o666, flag: 'w' }).then(() => {
	console.log('Data successfully written.');
});

TypeScript

import { writeFileSync } from 'fylo';

writeFileSync('/path/to/file.txt', 'Hello, World!', { encoding: 'utf8', mode: 0o666, flag: 'w' });
console.log('Data successfully written.');

JavaScript (CommonJS)

const { writeFileSync } = require('fylo');

writeFileSync('/path/to/file.txt', 'Hello, World!', { encoding: 'utf8', mode: 0o666, flag: 'w' });
console.log('Data successfully written.');

Renaming a File

The renameFile method allows you to safely and easily rename or move a file to a new location.

Fylo provides two versions of this method:

1. Asynchronous version renameFile.
2. Synchronous version renameFileSync.

Parameters:

• oldPath (string): The current path to the file.
• newPath (string): The new path where the file will be moved or renamed.

Return Value:

• void

TypeScript

import { renameFile } from 'fylo';

await renameFile('/path/to/file.txt', '/new/path/to/file.txt');
console.log('File renamed.');

JavaScript (CommonJS)

const { renameFile } = require('fylo');

renameFile('/path/to/file.txt', '/new/path/to/file.txt').then(() => {
	console.log('File renamed.');
});

TypeScript

import { renameFileSync } from 'fylo';

renameFileSync('/path/to/file.txt', '/new/path/to/file.txt');
console.log('File renamed.');

JavaScript (CommonJS)

const { renameFileSync } = require('fylo');

renameFileSync('/path/to/file.txt', '/new/path/to/file.txt');
console.log('File renamed.');

Deleting a File

The unlink method allows you to quickly and safely delete an unnecessary file.

Fylo provides two versions of this method:

1. Asynchronous version unlink.
2. Synchronous version unlinkSync.

Parameters:

• path (string): The path to the file that needs to be deleted.

Return Value:

• void

TypeScript

import { unlink } from 'fylo';

await unlink('/path/to/file.txt');
console.log('File deleted.');

JavaScript (CommonJS)

const { unlink } = require('fylo');

unlink('/path/to/file.txt').then(() => {
	console.log('File deleted.');
});

TypeScript

import { unlinkSync } from 'fylo';

unlinkSync('/path/to/file.txt');
console.log('File deleted.');

JavaScript (CommonJS)

const { unlinkSync } = require('fylo');

unlinkSync('/path/to/file.txt');
console.log('File deleted.');

Directory Management

Fylo provides tools for simple and convenient directory management, including creation, deletion, and clearing.

Creating a Directory

The mkdir method helps you quickly create a new directory, including all missing directories in the path.

Fylo provides two versions of this method:

1. Asynchronous version mkdir.
2. Synchronous version mkdirSync.

Parameters:

• path (string): The path where the new directory should be created.
• options (IDirectoryOptions, optional): Options for creating the directory:
  • recursive (boolean, optional): If true, all missing directories in the path are created. Defaults to false.
  • mode (number, optional): Sets the directory's permissions. Defaults to 0o777.

Return Value:

• void

TypeScript

import { mkdir } from 'fylo';

await mkdir('/path/to/directory', { recursive: true, mode: 0o755 });
console.log('Directory created.');

JavaScript (CommonJS)

const { mkdir } = require('fylo');

mkdir('/path/to/directory', { recursive: true, mode: 0o755 }).then(() => {
	console.log('Directory created.');
});

TypeScript

import { mkdirSync } from 'fylo';

mkdirSync('/path/to/directory', { recursive: true, mode: 0o755 });
console.log('Directory created.');

JavaScript (CommonJS)

const { mkdirSync } = require('fylo');

mkdirSync('/path/to/directory', { recursive: true, mode: 0o755 });
console.log('Directory created.');

Deleting a Directory

The rmdir method allows you to delete a directory along with all its contents.

Fylo provides two versions of this method:

1. Asynchronous version rmdir.
2. Synchronous version rmdirSync.

Parameters:

• path (string): The path to the directory that needs to be deleted.

Return Value:

• void

TypeScript

import { rmdir } from 'fylo';

await rmdir('/path/to/directory');
console.log('Directory deleted.');

JavaScript (CommonJS)

const { rmdir } = require('fylo');

rmdir('/path/to/directory').then(() => {
	console.log('Directory deleted.');
});

TypeScript

import { rmdirSync } from 'fylo';

rmdirSync('/path/to/directory');
console.log('Directory deleted.');

JavaScript (CommonJS)

const { rmdirSync } = require('fylo');

rmdirSync('/path/to/directory');
console.log('Directory deleted.');

Reading Directory Contents

The readdir method returns a list of all files and subdirectories in a specified directory, making content management easier.

Fylo provides two versions of this method:

1. Asynchronous version readdir.
2. Synchronous version readdirSync.

Parameters:

• path (string): The path to the directory whose contents need to be read.

Return Value:

• string[]: An array of strings, each representing a file or subdirectory name.

TypeScript

import { readdir } from 'fylo';

const files = await readdir('/path/to/directory');
console.log('Directory contents:', files);

JavaScript (CommonJS)

const { readdir } = require('fylo');

readdir('/path/to/directory').then((files) => {
	console.log('Directory contents:', files);
});

TypeScript

import { readdirSync } from 'fylo';

const files = readdirSync('/path/to/directory');
console.log('Directory contents:', files);

JavaScript (CommonJS)

const { readdirSync } = require('fylo');

const files = readdirSync('/path/to/directory');
console.log('Directory contents:', files);

Clearing a Directory

The cleardir method deletes all contents of a directory, leaving the directory itself intact.

Fylo provides two versions of this method:

1. Asynchronous version cleardir.
2. Synchronous version cleardirSync.

Parameters:

• path (string): The path to the directory that needs to be cleared.

Return Value:

• void

TypeScript

import { cleardir } from 'fylo';

await cleardir('/path/to/directory');
console.log('Directory cleared.');

JavaScript (CommonJS)

const { cleardir } = require('fylo');

cleardir('/path/to/directory').then(() => {
	console.log('Directory cleared.');
});

TypeScript

import { cleardirSync } from 'fylo';

cleardirSync('/path/to/directory');
console.log('Directory cleared.');

JavaScript (CommonJS)

const { cleardirSync } = require('fylo');

cleardirSync('/path/to/directory');
console.log('Directory cleared.');

Reading and Writing Streams

Fylo offers efficient tools for working with streams for reading and writing data to files, which is especially important when working with large files.

Reading Data (ReadStream)

The ReadStream class provides a streaming interface for reading data from a file, allowing you to process large files in parts without loading them entirely into memory.

Creating a ReadStream

Constructor Parameters:

• filePath (string): The path to the file that needs to be read.
• debug (boolean, optional): Enables debug mode. If true, additional logging is activated.

Methods:

• open(options?: { encoding?: BufferEncoding; highWaterMark?: number }, timeout?: number): Promise<void>

  • Opens the stream for reading the file. This method must be called before starting to read.
  • Parameters:
    • options (optional): Options for opening the stream:
      • encoding (BufferEncoding): The encoding for reading the file.
      • highWaterMark (number): The maximum buffer size for reading.
    • timeout (number): The timeout in milliseconds. If the stream does not open within this time, an error is returned.
  • Return Value: Promise<void>

• read(): Promise<Buffer | string | null>

  • Reads data from the stream if it is not in flowing mode.
  • Return Value: Promise<Buffer | string | null>

• pipe(destination: NodeJS.WritableStream | WriteStream, options?: { end?: boolean }): NodeJS.WritableStream | WriteStream

  • Pipes data from the read stream to the specified write stream.
  • Parameters:
    • destination: The write stream to which the data will be piped.
    • options (optional): Options for controlling the piping process:
      • end (boolean): Whether to end the write stream when the read stream finishes. Defaults to true.
  • Return Value: The write stream passed as destination.

• enableFlowingMode(): void

  • Enables flowing mode, where data is automatically read and emitted in data events.

• disableFlowingMode(): void

  • Disables flowing mode.

• close(timeout?: number): Promise<void>

  • Closes the stream.
  • Parameters:
    • timeout (number): The timeout in milliseconds. If the stream does not close within this time, an error is returned.
  • Return Value: Promise<void>

Usage Example

TypeScript

import { ReadStream } from 'fylo';

const stream = new ReadStream('/path/to/file.txt', true);

stream.on('data', (chunk) => {
	console.log('Received data chunk:', chunk);
});

stream
	.open()
	.then(() => {
		console.log('Stream opened.');
	})
	.catch((err) => {
		console.error('Error opening stream:', err);
	});

// Using asynchronous iterator
for await (const chunk of stream) {
	console.log('Reading data chunk:', chunk);
}

stream.close().then(() => {
	console.log('Stream closed.');
});

JavaScript (CommonJS)

const { ReadStream } = require('fylo');

const stream = new ReadStream('/path/to/file.txt', true);

stream.on('data', (chunk) => {
	console.log('Received data chunk:', chunk);
});

stream
	.open()
	.then(() => {
		console.log('Stream opened.');
	})
	.catch((err) => {
		console.error('Error opening stream:', err);
	});

// Using asynchronous iterator
(async () => {
	for await (const chunk of stream) {
		console.log('Reading data chunk:', chunk);
	}
})();

stream.close().then(() => {
	console.log('Stream closed.');
});

Writing Data (WriteStream)

The WriteStream class provides an interface for streaming data to a file. This method is especially useful for writing large amounts of data.

Creating a WriteStream

Constructor Parameters:

• filePath (string): The path to the file where the data needs to be written.
• debug (boolean, optional): Enables debug mode. If true, additional logging is activated.

Methods:

• open(options?: { encoding?: BufferEncoding; highWaterMark?: number }, timeout?: number): Promise<void>

  • Opens the stream for writing data. This method must be called before starting to write.
  • Parameters:
    • options (optional): Options for opening the stream:
      • encoding (BufferEncoding): The encoding for writing data.
      • highWaterMark (number): The maximum buffer size for writing.
    • timeout (number): The timeout in milliseconds. If the stream does not open within this time, an error is returned.
  • Return Value: Promise<void>

• write(chunk: Buffer | string): Promise<void>

  • Writes a chunk of data to the stream.
  • Parameters:
    • chunk (Buffer | string): The data to be written to the stream.
  • Return Value: Promise<void>

• close(timeout?: number): Promise<void>

  • Closes the stream.
  • Parameters:
    • timeout (number): The timeout in milliseconds. If the stream does not close within this time, an error is returned.
  • Return Value: Promise<void>

• destroy(timeout?: number): Promise<void>

  • Destroys the stream, making it unusable for further operations.
  • Parameters:
    • timeout (number): The timeout in milliseconds. If the stream is not destroyed within this time, an error is returned.
  • Return Value: Promise<void>

Usage Example

TypeScript

import { WriteStream } from 'fylo';

const stream = new WriteStream('/path/to/file.txt', true);

stream
	.open()
	.then(() => stream.write('Hello, World!'))
	.then(() => stream.write('More data'))
	.then(() => stream.close())
	.then(() => console.log('Data successfully written and stream closed.'))
	.catch((err) => console.error('Error working with stream:', err));

JavaScript (CommonJS)

const { WriteStream } = require('fylo');

const stream = new WriteStream('/path/to/file.txt', true);

stream
	.open()
	.then(() => stream.write('Hello, World!'))
	.then(() => stream.write('More data'))
	.then(() => stream.close())
	.then(() => console.log('Data successfully written and stream closed.'))
	.catch((err) => console.error('Error working with stream:', err));

File and Directory Watchers

Fylo provides convenient tools for monitoring changes in files and directories, allowing you to automate file processing tasks.

File Watcher (FileWatcher)

The FileWatcher class allows you to monitor changes in a single file. Both event-based monitoring and polling-based monitoring are supported.

Creating a FileWatcher

Constructor Parameters:

• filePath (string): The path to the file that needs to be monitored.
• options (IWatcherOptions, optional): Options for configuring the watcher:
  • usePolling (boolean, optional): If true, polling is used to monitor changes; otherwise, event-based monitoring is used.
  • pollingInterval (number, optional): The polling interval in milliseconds if polling mode is used. Defaults to 500 ms.

Methods:

• start(): void

  • Starts the process of monitoring the file. Depending on the settings, either polling or event-based monitoring may be used.

• stop(): void

  • Stops monitoring the file.

• on(event: 'changed' | 'error', listener: (arg: string | Error) => void): this

  • Adds a handler for the specified events.
  • Parameters:
    • event: The type of event. Possible values: 'changed' (file changed), 'error' (error).
    • listener: The event handler function.

Usage Example

TypeScript

import { FileWatcher } from 'fylo';

const watcher = new FileWatcher('/path/to/file.txt', { usePolling: true, pollingInterval: 1000 });

watcher.on('changed', (path) => {
	console.log(`File changed: ${path}`);
});

watcher.on('error', (error) => {
	console.error(`Error monitoring file: ${error.message}`);
});

watcher.start();

JavaScript (CommonJS)

const { FileWatcher } = require('fylo');

const watcher = new FileWatcher('/path/to/file.txt', { usePolling: true, pollingInterval: 1000 });

watcher.on('changed', (path) => {
	console.log(`File changed: ${path}`);
});

watcher.on('error', (error) => {
	console.error(`Error monitoring file: ${error.message}`);
});

watcher.start();

Directory Watcher (DirectoryWatcher)

The DirectoryWatcher class allows you to monitor changes in a directory. Both polling and event-based monitoring are supported for tracking additions, deletions, and modifications of files in the directory.

Creating a DirectoryWatcher

Constructor Parameters:

• directoryPath (string): The path to the directory that needs to be monitored.
• options (IWatcherOptions, optional): Options for configuring the watcher:
  • usePolling (boolean, optional): If true, polling is used to monitor changes; otherwise, event-based monitoring is used.
  • pollingInterval (number, optional): The polling interval in milliseconds if polling mode is used. Defaults to 500 ms.

Methods:

• start(): void

  • Starts the process of monitoring the directory. Depending on the settings, either polling or event-based monitoring may be used.

• stop(): void

  • Stops monitoring the directory.

• on(event: 'added' | 'removed' | 'changed' | 'error', listener: (arg: string | Error) => void): this

  • Adds a handler for the specified events.
  • Parameters:
    • event: The type of event. Possible values: 'added' (file added), 'removed' (file removed), 'changed' (file changed), 'error' (error).
    • listener: The event handler function.

Usage Example

TypeScript

import { DirectoryWatcher } from 'fylo';

const watcher = new DirectoryWatcher('/path/to/directory', { usePolling: true, pollingInterval: 1000 });

watcher.on('added', (path) => {
	console.log(`File added: ${path}`);
});

watcher.on('removed', (path) => {
	console.log(`File removed: ${path}`);
});

watcher.on('changed', (path) => {
	console.log(`File changed: ${path}`);
});

watcher.on('error', (error) => {
	console.error(`Error monitoring directory: ${error.message}`);
});

watcher.start();

JavaScript (CommonJS)

const { DirectoryWatcher } = require('fylo');

const watcher = new DirectoryWatcher('/path/to/directory', { usePolling: true, pollingInterval: 1000 });

watcher.on('added', (path) => {
	console.log(`File added: ${path}`);
});

watcher.on('removed', (path) => {
	console.log(`File removed: ${path}`);
});

watcher.on('changed', (path) => {
	console.log(`File changed: ${path}`);
});

watcher.on('error', (error) => {
	console.error(`Error monitoring directory: ${error.message}`);
});

watcher.start();

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

The author of the library is David Pobedinskiy.

Reporting Issues

If you encounter unexpected errors, please let me know by email at [email protected] or on Telegram.

Support the Author

If my work has helped you simplify your life, you can support me through:

• Boosty
• Patreon

Search npm for other libraries with the @qpyracuk prefix. You might find something useful for your project.

Conclusion

This is an alpha version of the library; if you encounter any bugs, please submit them to the GitHub Issues.

The library's functionality will not change—only the internal components will be updated in case of bugs or shortcomings. The names and results of the functions and methods will remain unchanged.