FUSE3.ONE

Native FUSE3 bindings for Node.js on Linux systems.

Overview

FUSE3.ONE provides high-performance Node.js bindings to the native FUSE3 library, enabling you to create virtual filesystems on Linux systems. This package is specifically designed for Linux environments and provides direct access to FUSE3 functionality.

Features

• Native Performance: Direct bindings to FUSE3 library
• TypeScript Support: Full TypeScript definitions included
• Linux Optimized: Designed specifically for Linux/WSL2 environments
• Event-Driven: Built on Node.js EventEmitter for reactive programming
• Production Ready: Used in production by REFINIO applications

Installation

npm install fuse3.one

Prerequisites

On Ubuntu/Debian:

sudo apt-get install libfuse3-dev fuse3

On CentOS/RHEL:

sudo yum install fuse3-devel fuse3

Quick Start

import { Fuse3, FuseOperations, FuseStats } from 'fuse3.one';

// Define your filesystem operations
const operations: FuseOperations = {
    getattr: (path: string): FuseStats | null => {
        if (path === '/') {
            return {
                mtime: new Date(),
                atime: new Date(),
                ctime: new Date(),
                size: 0,
                mode: 16877, // Directory
                uid: process.getuid(),
                gid: process.getgid()
            };
        }
        
        if (path === '/hello.txt') {
            return {
                mtime: new Date(),
                atime: new Date(),
                ctime: new Date(),
                size: 13,
                mode: 33188, // Regular file
                uid: process.getuid(),
                gid: process.getgid()
            };
        }
        
        return null; // File not found
    },
    
    readdir: (path: string): string[] => {
        if (path === '/') {
            return ['hello.txt'];
        }
        return [];
    },
    
    read: (path: string, size: number, offset: number): Buffer | null => {
        if (path === '/hello.txt') {
            const content = Buffer.from('Hello, World!');
            return content.subarray(offset, offset + size);
        }
        return null;
    }
};

// Create and mount filesystem
const fuse = new Fuse3('/tmp/myfuse', operations);

fuse.on('mount', () => {
    console.log('Filesystem mounted at /tmp/myfuse');
});

fuse.on('unmount', () => {
    console.log('Filesystem unmounted');
});

// Mount the filesystem
await fuse.mount();

// Unmount when done
process.on('SIGINT', async () => {
    await fuse.unmount();
    process.exit(0);
});

API Reference

Class: Fuse3

Constructor

new Fuse3(mountPath: string, operations: FuseOperations, options?: any)

Methods

• mount(): Promise<void> - Mount the filesystem
• unmount(): Promise<void> - Unmount the filesystem
• isMounted(): boolean - Check if filesystem is mounted
• getMountPath(): string - Get the mount path

Events

• mount - Emitted when filesystem is successfully mounted
• unmount - Emitted when filesystem is unmounted
• error - Emitted on errors

Interface: FuseOperations

interface FuseOperations {
    init?(): void;
    getattr?(path: string): FuseStats | null;
    readdir?(path: string): string[];
    read?(path: string, size: number, offset: number): Buffer | null;
    write?(path: string, buffer: Buffer, offset: number): number;
    create?(path: string, mode: number): void;
    unlink?(path: string): void;
    mkdir?(path: string, mode: number): void;
    rmdir?(path: string): void;
    rename?(oldPath: string, newPath: string): void;
    truncate?(path: string, size: number): void;
    open?(path: string, flags: number): number;
    release?(path: string, fd: number): void;
    statfs?(path: string): any;
}

Interface: FuseStats

interface FuseStats {
    mtime: Date;
    atime: Date;
    ctime: Date;
    size: number;
    mode: number;
    uid: number;
    gid: number;
}

Constants: FUSE_ERRORS

Common FUSE error codes:

• EPERM - Operation not permitted
• ENOENT - No such file or directory
• EIO - I/O error
• EACCES - Permission denied
• EEXIST - File exists
• ENOTDIR - Not a directory
• EISDIR - Is a directory
• EINVAL - Invalid argument
• ENOSPC - No space left on device
• EROFS - Read-only file system
• EBUSY - Device or resource busy
• ENOTEMPTY - Directory not empty

Platform Support

• Linux: Full native FUSE3 support
• WSL2: Full support with Windows filesystem bridge
• Windows: Not supported (use projfs-fuse.one instead)
• macOS: Not supported

Performance

FUSE3.ONE is optimized for high-performance scenarios:

• Direct C++ bindings with minimal overhead
• Efficient buffer handling for read/write operations
• Asynchronous operation support
• Memory-efficient string and buffer management

Related Packages

• projfs-fuse.one - FUSE3-compatible API for Windows using ProjFS
• one.filer - High-level virtual filesystem for ONE databases

License

MIT - See LICENSE file for details

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

For support and questions:

• GitHub Issues: https://github.com/refinio/fuse3.one/issues
• Email: [email protected]