146 lines
5.4 KiB
Markdown
146 lines
5.4 KiB
Markdown
# @push.rocks/smartfile
|
||
|
||
> Provides a robust suite of tools for managing files in Node.js using TypeScript.
|
||
|
||
## Install
|
||
|
||
To integrate `@push.rocks/smartfile` into your project, run:
|
||
|
||
```bash
|
||
npm install @push.rocks/smartfile
|
||
```
|
||
|
||
## Usage
|
||
|
||
`@push.rocks/smartfile` offers extensive file management utilities, enabling seamless file processing with TypeScript in a Node.js environment. Below are detailed examples showcasing various features of the module.
|
||
|
||
### Quick Start
|
||
|
||
First, ensure you're working in an environment that supports ECMAScript modules (ESM) and TypeScript. Here’s how you’d generally import and use `@push.rocks/smartfile`:
|
||
|
||
```typescript
|
||
import { SmartFile, StreamFile, VirtualDirectory, fs, memory } from '@push.rocks/smartfile';
|
||
```
|
||
|
||
### Working with `SmartFile`
|
||
|
||
#### Reading Files
|
||
|
||
To read from a file and convert it to a `SmartFile` instance:
|
||
|
||
```typescript
|
||
const myJsonSmartFile: SmartFile = await SmartFile.fromFilePath('./somePath/data.json');
|
||
const jsonData = JSON.parse(myJsonSmartFile.contents.toString());
|
||
console.log(jsonData); // Assuming the file contains JSON content
|
||
```
|
||
|
||
#### Writing Files
|
||
|
||
To write data to a file through a `SmartFile`:
|
||
|
||
```typescript
|
||
const filePath: string = './output/outputData.json';
|
||
const content: string = JSON.stringify({ key: 'value' });
|
||
await memory.toFs(content, filePath);
|
||
```
|
||
|
||
### Streaming Large Files with `StreamFile`
|
||
|
||
When dealing with large files, you can use `StreamFile` to handle such files efficiently, minimizing memory usage:
|
||
|
||
```typescript
|
||
const largeFile: StreamFile = await StreamFile.fromPath('./largeInput/largeFile.mp4');
|
||
await largeFile.writeToDisk('./largeOutput/largeFileCopy.mp4');
|
||
```
|
||
|
||
### Managing Virtual Directories
|
||
|
||
Handling multiple files as if they were part of a file system:
|
||
|
||
```typescript
|
||
const virtualDir = new VirtualDirectory();
|
||
await virtualDir.addSmartfiles([smartFile1, smartFile2]);
|
||
await virtualDir.saveToDisk('./virtualDirOutput');
|
||
```
|
||
|
||
### File System Operations
|
||
|
||
`@push.rocks/smartfile` provides a suite of utilities for common file system operations such as copying, deleting, and listing files or directories.
|
||
|
||
#### Copying a File
|
||
|
||
```typescript
|
||
await fs.copy('./sourceFile.txt', './destinationFile.txt');
|
||
```
|
||
|
||
#### Deleting a Directory
|
||
|
||
```typescript
|
||
await fs.remove('./directoryToDelete');
|
||
```
|
||
|
||
#### Listing Files in a Directory
|
||
|
||
```typescript
|
||
const fileList: string[] = await fs.listFiles('./someDirectory');
|
||
console.log(fileList);
|
||
```
|
||
|
||
### Advanced File Management
|
||
|
||
For specialized file operations, such as editing the contents of a file or streaming files from URLs, `@push.rocks/smartfile` includes advanced management features.
|
||
|
||
#### Editing a File’s Contents
|
||
|
||
```typescript
|
||
const smartFileToEdit: SmartFile = await SmartFile.fromFilePath('./editableFile.txt');
|
||
await smartFileToEdit.editContentAsString((content) => content.replace(/originalText/g, 'newText'));
|
||
await smartFileToEdit.write();
|
||
```
|
||
|
||
#### Streaming a File from a URL
|
||
|
||
```typescript
|
||
const streamedFile: StreamFile = await StreamFile.fromUrl('https://example.com/file.pdf');
|
||
await streamedFile.writeToDisk('./downloadedFiles/file.pdf');
|
||
```
|
||
|
||
### Working with File Buffers and Streams
|
||
|
||
`@push.rocks/smartfile` allows you to easily work with files using Buffers and Streams, facilitating operations like file transformations, uploads, and downloads.
|
||
|
||
#### Creating a SmartFile from a Buffer
|
||
|
||
```typescript
|
||
const buffer: Buffer = Buffer.from('Sample data');
|
||
const bufferSmartFile: SmartFile = await SmartFile.fromBuffer('./bufferFile.txt', buffer);
|
||
await bufferSmartFile.write();
|
||
```
|
||
|
||
#### Uploading a File
|
||
|
||
Stream files or buffers can be integrated with web frameworks to handle file uploads efficiently, utilizing streams to reduce memory footprint.
|
||
|
||
### Conclusion
|
||
|
||
With `@push.rocks/smartfile`, managing files in Node.js using TypeScript becomes significantly more straightforward and efficient. Utilizing the provided classes and methods, you can handle a wide range of file operations, from basic read/write tasks to complex operations such as virtual directory management and file streaming, with minimal boilerplate code and maximum efficiency.
|
||
|
||
## 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.
|