@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

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

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:

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:

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:

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

// 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

// 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

// 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

// 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

// 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

// 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

// 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:

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

// All methods are fully typed
const processFile = async (file: SmartFile): Promise<void> => {
  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 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.

readme.md

@push.rocks/smartfile 📁

🚀 What is smartfile?