fuse3.one/README.md

FUSE3 N-API bindings for Node.js - Linux native FUSE3 implementation

# 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

```bash
npm install fuse3.one
```

### Prerequisites

On Ubuntu/Debian:
```bash
sudo apt-get install libfuse3-dev fuse3
```

On CentOS/RHEL:
```bash
sudo yum install fuse3-devel fuse3
```

## Quick Start

```typescript
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
```typescript
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

```typescript
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

```typescript
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: support@refinio.net