smartfile/readme.md

# @push.rocks/smartfile

[@push.rocks/smartfile offers smart ways to work with files in nodejs](https://gitlab.com/push.rocks/smartfile#readme)

## Install

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

```bash
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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.

```typescript
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](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.