fs-tunnel/README.md

Modern SSH/SFTP file system client for Node.js - provides seamless remote file operations with a clean Promise-based API. Supports secure file transfers, directory management, and streaming for large files.

# SSH/SFTP File System Client

[![NPM Version](https://img.shields.io/npm/v/fs-tunnel.svg?branch=main)](https://www.npmjs.com/package/fs-tunnel)
[![Publish Size](https://badgen.net/packagephobia/publish/fs-tunnel)](https://packagephobia.now.sh/result?p=fs-tunnel)
[![Downloads](https://img.shields.io/npm/dt/fs-tunnel)](https://www.npmjs.com/package/fs-tunnel)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/SheikhAminul/fs-tunnel/blob/main/LICENSE)
================

### Modern SSH/SFTP client for Node.js
A robust TypeScript library providing seamless file system operations over SSH/SFTP with a clean, promise-based API. Perfect for secure file transfers, remote server management, and automation tasks.

## Table of Contents

* [Installation](#Installation)
* [Usage](#usage)
* [API Reference](#api-reference)
* [Contributing](#contributing)
* [License](#license)
* [Author](#author)

## Installation

```bash
npm install fs-tunnel
```

## Usage

### Basic example
```typescript
import { SSHFileSystem } from 'fs-tunnel'

const config = {
  host: 'example.com',
  port: 22,
  username: 'user',
  password: 'password'
}

async function main() {
  const fs = new SSHFileSystem(config)
  
  try {
    await fs.connect()
    
    // List files in directory
    const files = await fs.readdir('/remote/path')
    console.log('Directory contents:', files)
    
    // Get file stats
    const stats = await fs.stat('/remote/file.txt')
    console.log('File stats:', stats)
    
    // Download file
    const readStream = fs.createReadStream('/remote/file.txt')
    readStream.pipe(fs.createWriteStream('./local-file.txt'))
    
  } finally {
    fs.disconnect()
  }
}

main()
```

### Advanced example
```typescript
// Upload directory recursively
async function uploadDirectory(localPath, remotePath) {
  const items = await fs.promises.readdir(localPath, { withFileTypes: true })
  
  await fs.mkdir(remotePath)
  
  for (const item of items) {
    const localItemPath = path.join(localPath, item.name)
    const remoteItemPath = path.posix.join(remotePath, item.name)
    
    if (item.isDirectory()) {
      await uploadDirectory(localItemPath, remoteItemPath)
    } else {
      const readStream = fs.createReadStream(localItemPath)
      const writeStream = fs.createWriteStream(remoteItemPath)
      readStream.pipe(writeStream)
    }
  }
}
```

## API Reference

### Class: SSHFileSystem

#### Constructor
```typescript
new SSHFileSystem(config: SSHConfiguration)
```
- `config`: Connection configuration object
  - `host`: Server hostname (required)
  - `port`: SSH port (required)
  - `username`: Authentication username
  - `password`: Authentication password

#### Methods

| Method | Description |
|--------|-------------|
| `connect()` | Connects using configured credentials |
| `connectWithCredentials(username, password)` | Connects with explicit credentials |
| `readdir(path)` | Lists directory contents |
| `stat(path)` | Gets file/directory stats |
| `mkdir(path)` | Creates a directory |
| `rmdir(path)` | Removes a directory |
| `unlink(path)` | Deletes a file |
| `rename(oldPath, newPath)` | Renames/moves a file |
| `createReadStream(path)` | Creates readable file stream |
| `createWriteStream(path, options)` | Creates writable file stream |
| `disconnect()` | Closes the connection |

### Interfaces

#### `FileInfo`
```typescript
{
  name: string
  isDirectory: boolean
  size: number
  mtime: Date
  mode: number
}
```

#### `StatInfo`
```typescript
{
  isDirectory: boolean
  size: number
  mtime: Date
  mode: number
}
```

#### `SSHConfiguration`
```typescript
{
  host: string
  port: number
  username?: string
  password?: string
}
```

## Contributing

Contributions are welcome! Please open an issue or submit a pull request on the [GitHub repository](https://github.com/SheikhAminul/fs-tunnel).

## License

fs-tunnel is licensed under the [MIT license](https://github.com/SheikhAminul/fs-tunnel/blob/main/LICENSE).


## Author

|[![@SheikhAminul](https://avatars.githubusercontent.com/u/25372039?v=4&s=96)](https://github.com/SheikhAminul)|
|:---:|
|[@SheikhAminul](https://github.com/SheikhAminul)|