@push.rocks/smartfile

offers smart ways to work with files in nodejs

Install

To install @push.rocks/smartfile, run the following command in your project directory:

npm install @push.rocks/smartfile

Usage

The @push.rocks/smartfile library offers a comprehensive suite of tools to work with files in Node.js projects, facilitating a variety of file operations such as reading, writing, streaming, and in-memory manipulation. Below, you'll find detailed examples illustrating how to leverage the library's functionality to tackle real-world tasks.

Working with Filesystem

Ensuring File and Directory Existence

import { fs } from '@push.rocks/smartfile';

// Ensure a file exists with initial content (Async)
await fs.ensureFile('./path/to/new/file.txt', 'Initial content');

// Ensure a directory exists (Async)
await fs.ensureDir('./path/to/new/dir');

Getting File Details

import { fs } from '@push.rocks/smartfile';

// Check if a file exists (Async)
const exists: boolean = await fs.fileExists('./path/to/file.txt');

// Check if a path is a directory
const isDir: boolean = fs.isDirectory('./path/to/check');

Reading and Writing Files

Basic Reading and Writing

import { SmartFile, memory } from '@push.rocks/smartfile';

// Read a file to a SmartFile instance (Async)
const smartFile: SmartFile = await SmartFile.fromFilePath('./path/to/read/file.txt');

// Write SmartFile instance to a new path (Async)
await smartFile.writeToDir('./path/to/target/dir');

// Write text content to a file (Async)
await memory.toFs('Hello SmartFile!', './path/to/output/file.txt');

Working with File Contents

import { SmartFile } from '@push.rocks/smartfile';

// Creating SmartFile instance from text
const smartFileFromText: SmartFile = await SmartFile.fromString('./path/to/text/file.txt', 'Text content here', 'utf8');

// Reading content from SmartFile instance
const content: string = smartFileFromText.contents.toString();

// Editing content of SmartFile
await smartFileFromText.editContentAsString(async (currentContent: string) => `Modified: ${currentContent}`);

File Streaming

import { StreamFile } from '@push.rocks/smartfile';

// Creating a StreamFile from a file path (Async)
const streamFile: StreamFile = await StreamFile.fromPath('./path/to/large/file.avi');

// Streaming file content to disk (Async)
await streamFile.writeToDisk('./path/to/target/file.avi');

Utilizing Stream Files from URLs

import { StreamFile } from '@push.rocks/smartfile';

// Creating a StreamFile from URL (Async)
const streamFileFromURL: StreamFile = await StreamFile.fromUrl('https://example.com/data.json');

// Accessing StreamFile content as string (Async, for textual data)
const contentAsString: string = await streamFileFromURL.getContentAsString();

Handling Virtual Directories

import { VirtualDirectory, SmartFile } from '@push.rocks/smartfile';

// Creating a virtual directory from existing directory on disk (Async)
const virtualDirectory: VirtualDirectory = await VirtualDirectory.fromFsDirPath('./path/to/source/dir');

// Adding files to virtual directory
virtualDirectory.addSmartfiles([await SmartFile.fromFilePath('./path/to/extra/file.txt')]);

// Saving virtual directory to disk (Async)
await virtualDirectory.saveToDisk('./path/to/destination/dir');

Manipulating File Paths

import { SmartFile } from '@push.rocks/smartfile';

// Read SmartFile and change its relative path
const smartFile: SmartFile = await SmartFile.fromFilePath('./path/to/original/file.txt');
smartFile.updateFileName('newFilename.txt'); // Retains original directory but changes file name

Security and Hashing

import { SmartFile } from '@push.rocks/smartfile';

// Creating SmartFile instance and getting hash
const smartFileForHash: SmartFile = await SmartFile.fromString('./fileForHashing.txt', 'Content for hashing', 'utf8');
const hash: string = await smartFileForHash.getHash('content'); // 'content', 'path', or 'all'

Advanced Streaming via SmartReadStream

For handling edge cases such as streaming large files that are being written concurrently (e.g., log files), SmartReadStream can be employed to monitor files for new data and stream content as it becomes available.

import { fsStream } from '@push.rocks/smartfile';

const smartReadStream = new fsStream.SmartReadStream('./path/to/live/file.log');
smartReadStream
  .on('data', (chunk) => {
    // Process streamed data
  })
  .on('error', (err) => {
    console.error('Stream encountered an error:', err);
  })
  .on('end', () => {
    console.log('No more data available.');
  });

In conclusion, @push.rocks/smartfile equips developers with a highly versatile API for file manipulation, enhancing productivity in handling file operations within Node.js applications. By leveraging the examples provided, users can efficiently integrate file processing tasks into their projects, streamlining workflows and achieving granular control over file and directory management.

For more details and advanced use cases, please refer to the @push.rocks/smartfile documentation and explore the source code to unlock the full potential of this powerful library in your Node.js applications.

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.