# @push.rocks/smartfile 📁 > **A powerful, TypeScript-based file management library for Node.js** ## 🚀 What is smartfile? `@push.rocks/smartfile` is your go-to solution for file operations in Node.js. It offers a clean, promise-based API for handling files, directories, streams, and even virtual filesystems - all while maintaining maximum performance and reliability. Think of it as `fs` on steroids, with TypeScript superpowers! 💪 ## 💾 Installation ```bash npm install @push.rocks/smartfile ``` ## ✨ Features - 🔥 **Streaming Support** - Handle massive files with ease using `StreamFile` - 📦 **Virtual Directories** - Work with in-memory file structures - 🌐 **URL Support** - Directly work with files from URLs - 🎯 **TypeScript First** - Full type safety and IntelliSense support - ⚡ **Promise-based API** - Modern async/await patterns throughout - 🛠️ **Comprehensive Toolset** - From basic CRUD to advanced operations ## 📚 Quick Start ```typescript import * as smartfile from '@push.rocks/smartfile'; // Read a file const content = await smartfile.fs.toStringSync('./my-file.txt'); // Write a file await smartfile.memory.toFs('Hello World!', './output.txt'); // Work with JSON const data = await smartfile.fs.toObjectSync('./data.json'); ``` ## 🎨 Core Components ### SmartFile Class The `SmartFile` class represents a single file with powerful manipulation capabilities: ```typescript import { SmartFile } from '@push.rocks/smartfile'; // Create from file path const fileFromPath = await SmartFile.fromFilePath('./data.json'); // Create from URL const fileFromUrl = await SmartFile.fromUrl('https://example.com/config.json'); // Create from text const fileFromText = await SmartFile.fromString( './my-file.txt', 'This is my content', 'utf8' ); // Create from Buffer const fileFromBuffer = await SmartFile.fromBuffer( './binary.dat', Buffer.from([0x00, 0x01, 0x02]) ); // Edit content await fileFromPath.editContentAsString(async (content) => { return content.replace(/old/g, 'new'); }); // Write to disk await fileFromPath.write(); // Get content const contentString = fileFromPath.parseContentAsString(); const contentBuffer = fileFromPath.parseContentAsBuffer(); ``` ### StreamFile Class 🌊 Perfect for handling large files without memory overhead: ```typescript import { StreamFile } from '@push.rocks/smartfile'; // Create from path const streamFile = await StreamFile.fromPath('./bigfile.zip'); // Create from URL const urlStream = await StreamFile.fromUrl('https://example.com/large.mp4'); // Create from buffer const bufferStream = StreamFile.fromBuffer( Buffer.from('streaming content'), 'stream.txt' ); // Write to disk await streamFile.writeToDisk('./output/bigfile.zip'); // Get as buffer (careful with large files!) const buffer = await streamFile.getContentAsBuffer(); // Get as stream const readStream = await streamFile.createReadStream(); ``` ### VirtualDirectory Class 📂 Manage collections of files as virtual filesystems: ```typescript import { VirtualDirectory } from '@push.rocks/smartfile'; // Create from filesystem const vDir = await VirtualDirectory.fromFsDirPath('./src'); // Create from file array const vDirFromFiles = await VirtualDirectory.fromFileArray([ await SmartFile.fromFilePath('./file1.txt'), await SmartFile.fromFilePath('./file2.txt') ]); // Add files vDir.addSmartfiles([ await SmartFile.fromString('./virtual/new.txt', 'content') ]); // List files const files = vDir.listFiles(); const directories = vDir.listDirectories(); // Get file const file = vDir.getFileByPath('./some/path.txt'); // Save to disk await vDir.saveToDisk('./output'); // Load from disk await vDir.loadFromDisk('./source'); ``` ## 🛠️ File Operations ### Basic Operations ```typescript // Check existence const exists = await smartfile.fs.fileExists('./file.txt'); const existsSync = smartfile.fs.fileExistsSync('./file.txt'); // Read operations const content = await smartfile.fs.toStringSync('./file.txt'); const buffer = await smartfile.fs.toBuffer('./file.txt'); const object = await smartfile.fs.toObjectSync('./data.json'); // Write operations await smartfile.memory.toFs('content', './output.txt'); smartfile.memory.toFsSync('content', './output-sync.txt'); // Copy operations await smartfile.fs.copy('./source.txt', './dest.txt'); await smartfile.fs.copy('./src-dir', './dest-dir'); // Delete operations await smartfile.fs.remove('./file.txt'); await smartfile.fs.removeSync('./file-sync.txt'); await smartfile.fs.removeMany(['./file1.txt', './file2.txt']); // Ensure operations (create if not exists) await smartfile.fs.ensureDir('./my/deep/directory'); await smartfile.fs.ensureFile('./my/file.txt'); await smartfile.fs.ensureEmptyDir('./empty-dir'); ``` ### Directory Operations ```typescript // List contents const files = await smartfile.fs.listFiles('./directory'); const folders = await smartfile.fs.listFolders('./directory'); const items = await smartfile.fs.listAllItems('./directory'); // Get file tree const tree = await smartfile.fs.listFileTree('./src', '**/*.ts'); // Directory checks const isDir = await smartfile.fs.isDirectory('./path'); const isFile = await smartfile.fs.isFile('./path'); ``` ### Advanced Features ```typescript // Wait for file to be ready await smartfile.fs.waitForFileToBeReady('./file.txt'); // Stream operations const readStream = smartfile.fsStream.createReadStream('./input.txt'); const writeStream = smartfile.fsStream.createWriteStream('./output.txt'); // File type detection const fileType = smartfile.interpreter.filetype('./document.pdf'); // Returns: 'pdf' // Smart read stream (with custom processing) const smartStream = new smartfile.fsStream.SmartReadStream('./data.txt'); smartStream.on('data', (chunk) => { // Process chunk console.log(chunk.toString()); }); ``` ## 🔄 Working with Multiple Files ```typescript // Process multiple SmartFiles const files = await smartfile.fs.fileTreeToObject( './src', '**/*.{ts,js}' ); // Write array to disk const smartfiles = [ await SmartFile.fromString('file1.txt', 'content1'), await SmartFile.fromString('file2.txt', 'content2') ]; await smartfile.memory.smartfileArrayToFs(smartfiles, './output'); ``` ## 🎯 Real-World Examples ### Website Bundler ```typescript // Bundle website assets const website = await VirtualDirectory.fromFsDirPath('./website'); const bundle = await website.smartfileArray; // Process all CSS files for (const file of bundle.filter(f => f.path.endsWith('.css'))) { await file.editContentAsString(async (css) => { // Minify CSS here return css.replace(/\s+/g, ' '); }); } // Save processed bundle await website.saveToDisk('./dist'); ``` ### File Watcher & Processor ```typescript // Watch for new files and process them import { SmartFile, StreamFile } from '@push.rocks/smartfile'; async function processLargeFile(filePath: string) { const streamFile = await StreamFile.fromPath(filePath); // Stream to processed location await streamFile.writeToDisk(`./processed/${path.basename(filePath)}`); // Clean up original await smartfile.fs.remove(filePath); } ``` ### Configuration Manager ```typescript // Load and merge config files const defaultConfig = await smartfile.fs.toObjectSync('./config.default.json'); const userConfig = await smartfile.fs.toObjectSync('./config.user.json'); const merged = { ...defaultConfig, ...userConfig }; await smartfile.memory.toFs( JSON.stringify(merged, null, 2), './config.final.json' ); ``` ## 🌟 API Reference ### Core Modules - `fs` - File system operations - `fsStream` - Streaming operations - `memory` - Memory/buffer operations - `interpreter` - File type detection ### Main Classes - `SmartFile` - Single file representation - `StreamFile` - Streaming file operations - `VirtualDirectory` - Virtual filesystem management ## 🏗️ TypeScript Support Full TypeScript support with comprehensive type definitions: ```typescript import type { SmartFile, StreamFile, VirtualDirectory } from '@push.rocks/smartfile'; // All methods are fully typed const processFile = async (file: SmartFile): Promise => { const content = file.parseContentAsString(); // TypeScript knows content is string }; ``` ## 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.