SFTP Client
100% Typescript SFTP client
Function Reference
- Class SFTPClient
- connect (credentials)
- createDirectory (directoryPath, recursive = false)
- createReadStream (filePath)
- createWriteStream (filePath)
- deleteDirectory (directoryPath, recursive = false)
- deleteFile (filePath)
- end ()
- exists (path)
- getFile (filePath)
- list (path, detailed = false)
- move (sourcePath, targetPath)
- putFile (filePath, dataBuffer)
- setPermissions (filePath, permissions)
- stat (path)
- Class Permissions
- Class Stats
Class SFTPClient
The SFTPClient class provides all functionality to interact with the SFTP-Server. You may connect to the server using a password or a private key.
Example: get a file from a sftp server using a password
import SFTPClient from '@distributed-systems/sftp-client';
// represents one connection to the server
const client = new SFTPClient();
// conenct using a password
await client.connect({
hostname: 'l.dns.porn',
port: 22,
username: 'linaGirl',
password: 'totally-secure',
});
// get the file as a buffer
const file = await client.getFile('/home/linaGirl/nice-file.dat');
client.end();
SFTPClient.connect (credentials)
The connect method is used to open the connection to the server. It accepts an
options object containing the required credentials.
You can either connect using a password or a private-key. You can use both methods at the same time. The first method that results in success will be used then.
Returns the sftpClient instance.
Connect using a password
await client.connect({
hostname: 'l.dns.porn',
port: 22,
username: 'linaGirl',
password: 'totally-secure',
});
Connect using a private-key
import fs from 'fs';
const privateKey = await fs.promises.readFile('/home/linaGirl/.ssh/id_rsa');
await client.connect({
hostname: 'l.dns.porn',
port: 22,
username: 'linaGirl',
privateKey: privateKey,
});
SFTPClient.createDirectory (directoryPath, recursive = false)
Creates a directory on the server. Can create an entire path if the recursive
parameter is set to true.
Returns the sftpClient instance.
Create a directory
await client.createDirectory('best-directory-ever');
Create an entire path
await client.createDirectory('best-directory-ever/awesome-directory', true);
SFTPClient.createReadStream (filePath)
Downloads a file using a readable stream. The stream has the same API as standard node.js readable streams. This is the method you should use to download files to the file-system.
Returns a readable stream.
Download a file to the file-system
import fs from 'fs';
// create the readable stream for the file you like to download
const readStream = await client.createReadStream('fancy-file.fancy');
// create a write stream for the file the data should be stored in
const writeStream = fs.createWriteStream('/home/linaGirl/fancy-file.fancy');
// pipe the stream
readStream.pipe(writeStream);
// get notified when the stream has finished
writeStream.on('close', () => {
console.log('the file was successfully saved!');
});
Create a SHA1 Checksum of the file
import crypto from 'crypto';
const hash = crypto.createHash('sha1');
// create the readable stream for the file you like to hash
const readStream = await client.createReadStream('fancy-file.fancy');
// feed the data to the hash
readStream.on('data', (buffer) => {
hash.update(buffer);
});
// log the checksum
readStream.on('close', () => {
console.log(hash.digest('hex'));
});
SFTPClient.createWriteStream (filePath)
Uploads a file using a writable stream. The stream has the same API as standard node.js writable streams.
Returns a writable stream.
Download a file from the file-system
import fs from 'fs';
// create the writable stream for the file you like to upload
const writeStream = await client.createReadStream('fancy-file.fancy');
// create a read stream for the file the data should be read from
const readStream = fs.createReadStream('/home/linaGirl/fancy-file.fancy');
// pipe the stream
readStream.pipe(writeStream);
// get notified when the stream has finished
writeStream.on('close', () => {
console.log('the file was successfully uploaded!');
});
SFTPClient.deleteDirectory (directoryPath, recursive = false)
Deletes a directory on the server. Can recursively delete all contained files
and directories if the recursive parameter is set to true.
Returns the sftpClient instance.
Delete a directory
await client.deleteDirectory('best-directory-ever');
Delete a directory recursively
await client.deleteDirectory('best-directory-ever', true);
SFTPClient.deleteFile (filePath)
Deletes one file.
Returns the sftpClient instance.
Delete a file
await client.deleteFile('/path/to/file/that/needs/to.go');
SFTPClient.end ()
Ends the connection to the server.
Returns the sftpClient instance.
End the connection
await client.end();
SFTPClient.exists (path)
checks if a file or directory exists.
Returns a boolean.
Check if a file exists
const fileExists = await client.exists('path/to/file');
Check if a directory exists
const fileExists = await client.exists('path/to/directory');
SFTPClient.getFile (filePath)
Downloads a file into a buffer.
Returns a buffer containing the requested file.
Download a file
const fileBuffer = await client.getFile('/path/to.file');
SFTPClient.list (path, detailed = false)
Lists the path specified. The path may be a file or a directory.
Returns an array containing file-names or an array containing objects containing detailed information about the files.
List files of a directory
const filenames = await client.list('path/to/directory');
console.log(filenames);
// ['a.mjs', 'directory', 'z.jpg']
List files of a directory, return details
const files = await client.list('path/to/directory', true);
console.log(files);
[{filename: 'a.mjs', stats: StatsObject}]
See Class Stats for the contents of the StatsObject
SFTPClient.move (sourcePath, targetPath)
Moves a file or directory from the sourcePath to the targetPath. Can be used
to rename files and directories.
Returns the sftpClient instance.
Rename a file
await client.move('nice-code.mjs', 'legacy-code.mjs');
Move a directory
await client.move('directory', 'some/path/for/the/directory');
SFTPClient.putFile (filePath, dataBuffer)
Uploads a file from a buffer.
Returns the sftpClient instance.
Upload a file
await client.putFile('/path/to.file', buffer);
SFTPClient.setPermissions (filePath, permissions)
Sets the permissions on a file. If you need to get the permissions of a file you can stat it!
Returns the sftpClient instance.
Set the permissions on a file
import { Permissions } from '@distributed-systems/sftp-client';
// give the user read permissions
const permissions = new Permissions();
permissions.user.read = true;
await client.setPermissions('path/to/file', permissions);
See Class Permissions for details about the permissions object.
SFTPClient.stat (path)
Get stats about the file. Reports the type of the file and its permissions.
Returns an instance of the Stats class.
get stats for a file
const stats = await client.stat('path/to/file');
See Class Stats for the contents of the stats object.
Class Permissions
The Permissions class holds information about the permissions of a file-system object. It can be used to get the type of an object. It can also be used to read or write the permissions of an object.
The permissions object is returned as a property of the stats object by the stat and the list calls. It can be passed to the setPermissions call for changing permissions for an object.
The object exposes properties for the permissions for the user, the group an for
other Each of those properties is an object with three writable properties which
indicate the read, write and execute permissions.
Give all permissions to everyone
import { Permissions } from '@distributed-systems/sftp-client';
const permissions = new Permissions();
permissions.user.read = true;
permissions.user.write = true;
permissions.user.execute = true;
permissions.group.read = true;
permissions.group.write = true;
permissions.group.execute = true;
permissions.other.read = true;
permissions.other.write = true;
permissions.other.execute = true;
await client.setPermissions('path/to/file', permissions);
Check if the user has write permissions on a file
const stats = await client.stat('path/to/file');
console.log(stats.permissions.user.write); // true or false
Class Stats
The stats object is returned by the stat and the list calls.
The object has a property containing a permissions object and a bunch of methods that can be used to determine the type of the path the stat call was made on.
Get stats using the stat method
const stats = await client.stat('path/to/file');
Stats.isBlockDevice ()
Returns true if the path is a block device, false otherwise.
check if the path is a block device
const stats = await client.stat('path/to/file/or/directory');
console.log(stats.isBlockDevice()); // true or false
Stats.isCharacterDevice ()
Returns true if the path is a character device, false otherwise.
check if the path is a character device
const stats = await client.stat('path/to/file/or/directory');
console.log(stats.isCharacterDevice()); // true or false
Stats.isDirectory ()
Returns true if the path is a directory, false otherwise.
check if the path is a directory
const stats = await client.stat('path/to/file/or/directory');
console.log(stats.isDirectory()); // true or false
Stats.isFIFO ()
Returns true if the path is a named pipe, false otherwise.
check if the path is a named pipe
const stats = await client.stat('path/to/file/or/directory');
console.log(stats.isFIFO()); // true or false
Stats.isFile ()
Returns true if the path is a regular file, false otherwise.
check if the path is a regular file
const stats = await client.stat('path/to/file/or/directory');
console.log(stats.isFile()); // true or false
Stats.isSocket ()
Returns true if the path is a socket, false otherwise.
check if the path is a socket
const stats = await client.stat('path/to/file/or/directory');
console.log(stats.isSocket()); // true or false
Stats.isSymbolicLink ()
Returns true if the path is a symbolic link, false otherwise.
check if the path is a symbolic link
const stats = await client.stat('path/to/file/or/directory');
console.log(stats.isSymbolicLink()); // true or false