@xisodev/webfs

A lightweight, high-performance Virtual File System (VFS) for the browser, built on top of IndexedDB. It acts like a Linux-style filesystem, allowing you to manage files, folders, and large binary blobs with ease.

🆕 Updates & Fixes

• EASIER DOCS: Revamped documentation so everyone gets a clear understanding of the library and how to utilize the filesystem functions.
• FileManager: Introduced a simplified class that gives users quick, high-level access to orchestrate their filesystem ecosystem.

🚀 Features

• Persistent Storage: Backed by IndexedDB for long-term storage in the browser.
• Large File Support: Uses a separate blob store to handle large assets without slowing down metadata queries.
• ESM Ready: Built as a native ES Module.
• Metadata Management: Track created/modified dates, tags, and custom MIME types.
• Utility Suite: Includes Base64 converters, HTML escaping, and MIME type guessing.
• Tree Building: Easily convert flat paths into a hierarchical tree structure for UI components.

📦 Installation

npm install @xisodev/webfs

📖 FileManager Documentation

The FileManager class is the high-level API for the WebFS ecosystem. It orchestrates the FileSystem (logic), Storage (IndexedDB), and Encoding (data conversion) to provide an OS-like file management experience.

1. Setup & Initialization

Before performing any operations, you must initialize the manager to sync the in-memory map with the browser's persistent storage.

import { FileManager } from './web-fs.bundle.js';

const drive = new FileManager({  
    uploadDir: "/documents", // Optional: default is "/uploads"  
    onStatus: (msg) => console.log(`[Drive]: ${msg}`)  
});

await drive.init();

2. Core Methods

upload(destinationPath = null)

Opens the native system file picker.

• Arguments: destinationPath (String, optional) – Specific folder to save into.
• Returns: Promise<Array> – A list of the newly created file entries.
• Feature: Automatically handles naming conflicts (e.g., image_1.png).

open(path)

Reads a file and prepares it for the UI.

• Arguments: path (String) – Full path to the file.
• Returns: Object containing:
  • blob: The raw data.
  • text: String content (if it's a text file).
  • url: A temporary blob:// URL for <img>, <video>, or <iframe> sources.

writeFile(path, content, mimeType = null)

Creates or updates a text-based file directly from a string.

• Arguments: path (String), content (String), mimeType (Optional).
• Returns: Promise<Object> – The saved entry.

3. Navigation & Organization

openFolder(path)

Lists the contents of a directory.

• Returns: Array of entries sorted by type (folders first).
• Use Case: Populating a "Desktop" view or a "File Explorer" window.

createNewFolder(path)

Creates a new directory in the virtual system.

• Returns: Promise<Object> – The folder entry.

rename(oldPath, newPath)

Renames or moves a file/folder.

• Feature: If a folder is renamed, all nested children are automatically updated in the database to reflect the new path.

4. Maintenance & Search

delete(path)

Removes an entry and its children.

• Cleanup: Automatically deletes binary data from the Blobs store to prevent "ghost" data from taking up browser space.

search(query)

Finds files/folders across the entire system.

• Arguments: query (String) – Case-insensitive search term.
• Returns: Array of matching entries.

getInfo(path)

Retrieves detailed metadata including file extension, parent path, and timestamps.

5. Implementation Quick-Tips

| Goal | Method to Use | | :---- | :---- | | Show Desktop Icons | drive.openFolder("/") | | Open a Text Editor | const file = await drive.open("/note.txt"); | | Save Code from Editor | await drive.writeFile("/script.js", editorContent); | | Right-Click Delete | await drive.delete(targetPath); |

⚙️ System Constraints

• Inline Storage: Files smaller than 512KB that are identified as text (JSON, JS, CSS, TXT) are stored as "inline strings" for near-instant loading.
• Blob Storage: Larger files and binary data (Images, Videos, PDFs) are stored as Blobs in a separate IndexedDB store to maintain performance.