https://github.com/sheikhaminul/fs-tunnel
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.
https://github.com/sheikhaminul/fs-tunnel
filesystem fs remote-filesystem sftp ssh ssh-tunnel
Last synced: 3 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/sheikhaminul/fs-tunnel
- Owner: SheikhAminul
- License: mit
- Created: 2025-06-22T18:20:20.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-06-22T18:20:26.000Z (12 months ago)
- Last Synced: 2025-08-28T08:16:02.141Z (10 months ago)
- Topics: filesystem, fs, remote-filesystem, sftp, ssh, ssh-tunnel
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/fs-tunnel
- Size: 3.91 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SSH/SFTP File System Client
[](https://www.npmjs.com/package/fs-tunnel)
[](https://packagephobia.now.sh/result?p=fs-tunnel)
[](https://www.npmjs.com/package/fs-tunnel)
[](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
|[](https://github.com/SheikhAminul)|
|:---:|
|[@SheikhAminul](https://github.com/SheikhAminul)|