Interface FtpSession

An authenticated FTP session over a single control connection.

Obtain one from connect. It is an AsyncDisposable, so it can be scoped with await using to guarantee a clean QUIT and socket close. Methods issue one command at a time and must not be called concurrently on the same session, since each data transfer opens its own passive connection while the control channel is in use.

Since

1.0.0

interface FtpSession {
    "[asyncDispose]"(): PromiseLike<void>;
    close(): Promise<void>;
    cwd(path: string): Promise<void>;
    delete(path: string): Promise<void>;
    ensureDir(path: string): Promise<void>;
    exists(path: string): Promise<boolean>;
    get(
        path: string,
        opts?: FtpGetOptions,
    ): Promise<Uint8Array<ArrayBufferLike>>;
    getJson<T = unknown>(path: string): Promise<T>;
    getStream(
        path: string,
        opts?: FtpGetOptions,
    ): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
    getText(path: string, opts?: FtpGetOptions): Promise<string>;
    list(path?: string): Promise<FtpEntry[]>;
    mkdir(path: string): Promise<void>;
    mtime(path: string): Promise<Date>;
    nameList(path?: string): Promise<string[]>;
    put(path: string, data: Uint8Array, opts?: FtpPutOptions): Promise<void>;
    putJson(
        path: string,
        value: unknown,
        opts?: { space?: number },
    ): Promise<void>;
    putText(path: string, content: string, opts?: FtpPutOptions): Promise<void>;
    pwd(): Promise<string>;
    removeAll(path: string): Promise<void>;
    rename(from: string, to: string): Promise<void>;
    rmdir(path: string): Promise<void>;
    size(path: string): Promise<number>;
}

Hierarchy

AsyncDisposable
- FtpSession

Index

Methods

[asyncDispose] close cwd delete ensureDir exists get getJson getStream getText list mkdir mtime nameList put putJson putText pwd removeAll rename rmdir size

Methods

[asyncDispose]

"[asyncDispose]"(): PromiseLike<void>
Returns PromiseLike<void>
Inherited from AsyncDisposable.[asyncDispose]
- Defined in node_modules/typescript/lib/lib.esnext.disposable.d.ts:38

close

close(): Promise<void>
Sends QUIT and closes the control connection.

Returns Promise<void>
Resolves once the socket is closed.

Since
1.0.0
- Defined in src/ftp/index.ts:439

cwd

cwd(path: string): Promise<void>
Changes the working directory via CWD.
Parameters
- path: string
  Directory to change into.
Returns Promise<void>
Throws
If the server rejects the command.

Since
1.0.0
Example
```
await session.cwd('/pub');
```
- Defined in src/ftp/index.ts:258

delete

delete(path: string): Promise<void>
Deletes a file via DELE.
Parameters
- path: string
  Path of the file to delete.
Returns Promise<void>
Throws
If the server rejects the command.

Since
1.0.0
Example
```
await session.delete('/incoming/old.csv');
```
- Defined in src/ftp/index.ts:209

ensureDir

ensureDir(path: string): Promise<void>
Creates a directory and all missing parents, like mkdir -p.

FTP MKD is single-level, so this splits path on / and issues MKD for each cumulative segment, ignoring the 550 "already exists" failure on segments that are already present. A leading / is preserved so absolute paths create from the root; a relative path creates under the current working directory. This is a client-side walk: it makes one round trip per segment and is not atomic.
Parameters
- path: string
  Directory path to create, with / separating segments.
Returns Promise<void>
Throws
If the control connection fails.

Throws
If a segment fails for a reason other than already existing.

Since
1.0.2
Example
```
await session.ensureDir('/incoming/2026/reports');
```
- Defined in src/ftp/index.ts:323

exists

exists(path: string): Promise<boolean>
Reports whether a path exists by probing it with SIZE.

Issues SIZE <path> and treats a 213 reply as existence and a 550 (or any other command failure surfaced as ProtocolError) as absence. Because SIZE is a file-oriented probe, some servers reject it for directories even when they exist; for a directory, prefer FtpSession.cwd or FtpSession.list. The path is resolved by the server relative to the current working directory unless it is absolute.
Parameters
- path: string
  Path to probe (absolute, or relative to the working directory).
Returns Promise<boolean>
true if the server reports a size for the path, false if it is missing.
Throws
If the control connection fails.

Since
1.0.2
Example
```
if (await session.exists('/pub/readme.txt')) {
	const bytes = await session.get('/pub/readme.txt');
}
```
- Defined in src/ftp/index.ts:304

get

get(path: string, opts?: FtpGetOptions): Promise<Uint8Array<ArrayBufferLike>>
Retrieves a file's bytes via RETR.

Defaults to binary (TYPE I). Pass { type: 'ascii' } for a text-mode transfer (TYPE A, server line-ending conversion) or { offset } to resume an interrupted download from a byte offset (REST <offset> before RETR), in which case the returned bytes are the tail of the file from that offset.
Parameters
- path: string
  Path of the file to fetch.
- Optionalopts: FtpGetOptions
  Optional transfer type and resume offset.
Returns Promise<Uint8Array<ArrayBufferLike>>
The file's raw bytes (the tail from opts.offset when set).
Throws
If the server rejects the command.

Since
1.0.0
Example
```
const bytes = await session.get('/pub/readme.txt');
const text = await session.get('/pub/readme.txt', { type: 'ascii' });
const tail = await session.get('/pub/big.bin', { offset: 1024 });
```
- Defined in src/ftp/index.ts:159

getJson

getJson<T = unknown>(path: string): Promise<T>
Retrieves a file and parses it as JSON.

A convenience over FtpSession.get that decodes the bytes as UTF-8 and runs JSON.parse. The type parameter T annotates the parsed shape; it is not validated at runtime.
Type Parameters
- T = unknown
  The expected shape of the parsed JSON.
Parameters
- path: string
  Path of the JSON file to fetch.
Returns Promise<T>
The parsed value, typed as T.
Throws
If the server rejects the command.

Throws
If the body is not valid JSON.

Since
1.0.2
Example
```
interface Config { name: string }
const cfg = await session.getJson<Config>('/etc/app/config.json');
```
- Defined in src/ftp/index.ts:377

getStream

getStream(
path: string,
opts?: FtpGetOptions,
): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>
Retrieves a file as a stream via RETR, for payloads too large to buffer.

The returned stream owns the data connection; read it to completion (or cancel it) so the underlying socket closes. Accepts the same type and offset options as FtpSession.get.
Parameters
- path: string
  Path of the file to fetch.
- Optionalopts: FtpGetOptions
  Optional transfer type and resume offset.
Returns Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>
A readable stream of the file's bytes.
Throws
If the server rejects the command.

Since
1.0.0
Example
```
const stream = await session.getStream('/var/log/big.log');
await stream.pipeTo(someWritable);
```
- Defined in src/ftp/index.ts:177

getText

getText(path: string, opts?: FtpGetOptions): Promise<string>
Retrieves a file and decodes its bytes as UTF-8 text.

A convenience over FtpSession.get that runs the same RETR transfer and decodes the result with TextDecoder. Accepts the same transfer options as get.
Parameters
- path: string
  Path of the file to fetch.
- Optionalopts: FtpGetOptions
  Optional transfer type and resume offset (see FtpGetOptions).
Returns Promise<string>
The file contents decoded as UTF-8.
Throws
If the server rejects the command.

Since
1.0.2
Example
```
const text = await session.getText('/pub/readme.txt');
```
- Defined in src/ftp/index.ts:340

list

list(path?: string): Promise<FtpEntry[]>
Lists a directory via LIST, parsing Unix ls -l lines into FtpEntry records.
Parameters
- Optionalpath: string
  Directory to list; omit for the current working directory.
Returns Promise<FtpEntry[]>
One entry per line, with the raw line always preserved.
Throws
If the server rejects the command.

Since
1.0.0
Example
```
for (const entry of await session.list('/pub')) {
	console.log(entry.isDirectory ? 'dir' : 'file', entry.name);
}
```
- Defined in src/ftp/index.ts:125

mkdir

mkdir(path: string): Promise<void>
Creates a directory via MKD.
Parameters
- path: string
  Path of the directory to create.
Returns Promise<void>
Throws
If the server rejects the command.

Since
1.0.0
Example
```
await session.mkdir('/incoming/2026');
```
- Defined in src/ftp/index.ts:221

mtime

mtime(path: string): Promise<Date>
Returns a file's last-modified time via MDTM.

Issues MDTM <path> and parses the 213 YYYYMMDDHHMMSS reply as a UTC timestamp. Per RFC 3659 the MDTM time is always UTC. A fractional-seconds suffix (.sss), when the server sends one, is parsed too. The path is resolved by the server relative to the current working directory unless it is absolute.
Parameters
- path: string
  Path of the file to stat.
Returns Promise<Date>
The modification time as a Date.
Throws
If the server rejects the command or returns a malformed timestamp.

Since
1.0.2
Example
```
const when = await session.mtime('/pub/readme.txt');
```
- Defined in src/ftp/index.ts:432

nameList

nameList(path?: string): Promise<string[]>
Lists bare names via NLST.
Parameters
- Optionalpath: string
  Directory to list; omit for the current working directory.
Returns Promise<string[]>
One name per line.
Throws
If the server rejects the command.

Since
1.0.0
Example
```
const names = await session.nameList('/pub');
```
- Defined in src/ftp/index.ts:138

put

put(path: string, data: Uint8Array, opts?: FtpPutOptions): Promise<void>
Stores bytes to a file via STOR (or APPE).

Defaults to binary (TYPE I). Pass { type: 'ascii' } for a text-mode transfer, or resume an interrupted upload with { append: true } (use APPE, sending only the remaining bytes) or { offset } (issue REST <offset> before STOR, overwriting from that offset).
Parameters
- path: string
  Destination path.
- data: Uint8Array
  The bytes to write.
- Optionalopts: FtpPutOptions
  Optional transfer type and resume mode (append or offset).
Returns Promise<void>
Throws
If the server rejects the command.

Since
1.0.0
Example
```
await session.put('/incoming/report.csv', new TextEncoder().encode('a,b,c\n'));
// resume an upload that died after the first 1024 bytes
await session.put('/incoming/big.bin', rest, { append: true });
```
- Defined in src/ftp/index.ts:197

putJson

putJson(path: string, value: unknown, opts?: { space?: number }): Promise<void>
Serializes a value as JSON and stores it via STOR.

A convenience over FtpSession.put that runs JSON.stringify, encodes the result as UTF-8, and uploads it.
Parameters
- path: string
  Destination path.
- value: unknown
  The value to serialize; must be JSON-serializable.
- Optionalopts: { space?: number }
  Optional formatting; space is forwarded to JSON.stringify for indentation.
Returns Promise<void>
Throws
If the server rejects the command.

Since
1.0.2
Example
```
await session.putJson('/etc/app/config.json', { name: 'edge' }, { space: 2 });
```
- Defined in src/ftp/index.ts:394

putText

putText(path: string, content: string, opts?: FtpPutOptions): Promise<void>
Encodes a string as UTF-8 and stores it via STOR.

A convenience over FtpSession.put that encodes content with TextEncoder and uploads it. Accepts the same transfer options as put.
Parameters
- path: string
  Destination path.
- content: string
  The text to write; encoded as UTF-8.
- Optionalopts: FtpPutOptions
  Optional transfer type and resume mode (see FtpPutOptions).
Returns Promise<void>
Throws
If the server rejects the command.

Since
1.0.2
Example
```
await session.putText('/incoming/note.txt', 'hello world\n');
```
- Defined in src/ftp/index.ts:357

pwd

pwd(): Promise<string>
Returns the current working directory via PWD.

Returns Promise<string>
The absolute working directory reported by the server.
Throws
If the server rejects the command.

Since
1.0.0
Example
```
const dir = await session.pwd();
```
- Defined in src/ftp/index.ts:270

removeAll

removeAll(path: string): Promise<void>
Recursively deletes a directory tree (files then directories, depth-first).

Walks path with LIST, deleting files with DELE and recursing into subdirectories, then removes each emptied directory with RMD. This is a client-side walk: it makes many round trips (O(N) for N entries) and is not atomic, so a failure partway through leaves the tree partly deleted. Rejects when path is empty or / as a guard against wiping the server root. The path is resolved by the server relative to the current working directory unless it is absolute.
Parameters
- path: string
  Directory tree to remove; must not be empty or /.
Returns Promise<void>
Throws
If path is empty or /, or the server rejects a command.

Throws
If the control connection fails.

Since
1.0.2
Example
```
await session.removeAll('/incoming/2025');
```
- Defined in src/ftp/index.ts:414

rename

rename(from: string, to: string): Promise<void>
Renames or moves a path via RNFR/RNTO.
Parameters
- from: string
  Existing path.
- to: string
  New path.
Returns Promise<void>
Throws
If the server rejects either command.

Since
1.0.0
Example
```
await session.rename('/tmp/a.txt', '/tmp/b.txt');
```
- Defined in src/ftp/index.ts:246

rmdir

rmdir(path: string): Promise<void>
Removes a directory via RMD.
Parameters
- path: string
  Path of the directory to remove.
Returns Promise<void>
Throws
If the server rejects the command.

Since
1.0.0
Example
```
await session.rmdir('/incoming/2025');
```
- Defined in src/ftp/index.ts:233

size

size(path: string): Promise<number>
Returns a file's size in bytes via SIZE.
Parameters
- path: string
  Path of the file to measure.
Returns Promise<number>
The size in bytes.
Throws
If the server rejects the command or returns a non-numeric size.

Since
1.0.0
Example
```
const n = await session.size('/pub/readme.txt');
```
- Defined in src/ftp/index.ts:283

Interface FtpSession

Since

Hierarchy

Index

Methods

Methods

[asyncDispose]

Returns PromiseLike<void>

close

Returns Promise<void>

Since

cwd

Parameters

Returns Promise<void>

Throws

Since

Example

delete

Parameters

Returns Promise<void>

Throws

Since

Example

ensureDir

Parameters

Returns Promise<void>

Throws

Throws

Since

Example

exists

Parameters

Returns Promise<boolean>

Throws

Since

Example

get

Parameters

Returns Promise<Uint8Array<ArrayBufferLike>>

Throws

Since

Example

getJson

Type Parameters

Parameters

Returns Promise<T>

Throws

Throws

Since

Example

getStream

Parameters

Returns Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>

Throws

Since

Example

getText

Parameters

Returns Promise<string>

Throws

Since

Example

list

Parameters

Returns Promise<FtpEntry[]>

Throws

Since

Example

mkdir

Parameters

Returns Promise<void>

Throws

Since

Example

mtime

Parameters

Returns Promise<Date>

Throws

Since

Example