Skip to main content

​
Overview

The FTPFileInfo type represents file and directory metadata returned by FTP server operations. It provides comprehensive information about files including timestamps, permissions, type information, and Unix-style file attributes.

​
Type Definition

export type FTPFileInfo = {
  ctime: Date | null;
  ftpperms: string | null;
  lang: string | null;
  mediaType: string | null;
  charset: string | null;
  ftpType: string | null;
} & {
  [key: string]: boolean | string | number | Date | null;
};
This type combines specific known fields with an index signature that allows additional dynamic properties. The FTP client populates these fields based on server responses, particularly from MLST/MLSD commands.

​
Core Fields

​
ctime
Date | null
The file creation time.This value is populated from the create fact in MLST responses. It may be null if the server doesn’t provide creation time information.Example:
const info = await client.stat('document.pdf');
if (info.ctime) {
  console.log(`Created: ${info.ctime.toISOString()}`);
}
​
mtime
Date | null
The file’s last modification time.This is one of the most commonly available timestamps, populated from the modify fact in MLST responses or from the MDTM command.Example:
const info = await client.stat('data.json');
if (info.mtime) {
  console.log(`Last modified: ${info.mtime.toISOString()}`);
}
​
size
number
The file size in bytes.For directories, this is typically 0. For files, it represents the total size in bytes.Example:
const info = await client.stat('archive.zip');
console.log(`File size: ${info.size} bytes`);
​
isFile
boolean
Whether this entry represents a regular file.This is determined from the type=file fact in MLST responses or inferred from SIZE command success.Example:
const info = await client.stat('item');
if (info.isFile) {
  console.log('This is a file');
}
​
isDirectory
boolean
Whether this entry represents a directory.This is determined from type=dir, type=cdir, or type=pdir facts in MLST responses, or inferred when SIZE command fails with a directory error.Example:
const info = await client.stat('folder');
if (info.isDirectory) {
  console.log('This is a directory');
}
​
isSymlink
boolean
Whether this entry is a symbolic link.Defaults to false. May be populated from server-specific MLST facts if the server provides symlink information.Example:
const info = await client.stat('link');
if (info.isSymlink) {
  console.log('This is a symbolic link');
}

​
FTP-Specific Fields

​
ftpType
string | null
The FTP type from MLST responses.Common values include:
  • "file" - Regular file
  • "dir" - Directory
  • "cdir" - Current directory
  • "pdir" - Parent directory
This is the raw type fact from MLST responses.Example:
const info = await client.stat('item');
console.log(`FTP type: ${info.ftpType}`);
​
ftpperms
string | null
FTP permissions string from the server.This represents permissions as defined in RFC 3659, section 7.5.5. The string contains permission codes like:
  • a - Append permission
  • c - Create permission
  • d - Delete permission
  • e - Enter directory permission
  • f - Rename permission
  • l - List permission
  • p - Purge permission
  • r - Read permission
  • w - Write permission
Example:
const info = await client.stat('file.txt');
if (info.ftpperms) {
  console.log(`FTP permissions: ${info.ftpperms}`);
}
​
mediaType
string | null
The MIME media type of the file.Populated from the media-type fact in MLST responses when the server provides this information.Example:
const info = await client.stat('document.pdf');
if (info.mediaType) {
  console.log(`Media type: ${info.mediaType}`);
}
​
charset
string | null
The character encoding of the file.Populated from the charset fact in MLST responses when available.Example:
const info = await client.stat('text.txt');
if (info.charset) {
  console.log(`Character set: ${info.charset}`);
}
​
lang
string | null
The language of the file content.Populated from the lang fact in MLST responses when the server provides language information.Example:
const info = await client.stat('readme.txt');
if (info.lang) {
  console.log(`Language: ${info.lang}`);
}

​
Unix-Style Fields

These fields are populated from Unix-specific facts in MLST responses (e.g., unix.mode, unix.uid, unix.gid).
​
mode
number | null
The Unix file mode/permissions as a numeric value.Parsed from the unix.mode fact when provided by the server.Example:
const info = await client.stat('script.sh');
if (info.mode !== null) {
  console.log(`Unix mode: ${info.mode.toString(8)}`);
}
​
uid
number | null
The Unix user ID of the file owner.Parsed from the unix.uid fact when available.Example:
const info = await client.stat('file.txt');
if (info.uid !== null) {
  console.log(`Owner UID: ${info.uid}`);
}
​
gid
number | null
The Unix group ID of the file.Parsed from the unix.gid fact when available.Example:
const info = await client.stat('file.txt');
if (info.gid !== null) {
  console.log(`Group GID: ${info.gid}`);
}
​
dev
number
Device identifier.Defaults to NaN. This field is included for compatibility with Node.js Stats objects but is rarely populated by FTP servers.
​
ino
number | null
Inode number.This field is included for compatibility with file system stat structures but is typically null for FTP operations.
​
nlink
number | null
Number of hard links.This field is included for compatibility but is typically null for FTP operations.
​
rdev
number | null
Device ID (if special file).This field is included for compatibility but is typically null for FTP operations.
​
blksize
number | null
Block size for file system I/O.This field is included for compatibility but is typically null for FTP operations.
​
blocks
number | null
Number of 512-byte blocks allocated.This field is included for compatibility but is typically null for FTP operations.
​
atime
Date | null
Last access time.This field is included for compatibility but is typically null for FTP operations as most FTP servers don’t provide access time information.
​
birthtime
Date | null
File birth/creation time.This field is included for compatibility but is typically null. Use ctime instead for creation time from FTP servers.

​
Special File Type Flags

​
isBlockDevice
boolean | null
Whether the file is a block device.Typically null for FTP operations as FTP servers rarely expose device files.
​
isCharDevice
boolean | null
Whether the file is a character device.Typically null for FTP operations.
​
isFifo
boolean | null
Whether the file is a FIFO (named pipe).Typically null for FTP operations.
​
isSocket
boolean | null
Whether the file is a socket.Typically null for FTP operations.

​
Usage Examples

​
Check File Type

const info = await client.stat('item');

if (info.isDirectory) {
  console.log('This is a directory');
} else if (info.isFile) {
  console.log(`This is a file of ${info.size} bytes`);
} else if (info.isSymlink) {
  console.log('This is a symbolic link');
}

​
Display File Metadata

const info = await client.stat('document.pdf');

console.log(`File: document.pdf`);
console.log(`Size: ${info.size} bytes`);
console.log(`Type: ${info.isFile ? 'File' : 'Directory'}`);

if (info.mtime) {
  console.log(`Modified: ${info.mtime.toISOString()}`);
}

if (info.ctime) {
  console.log(`Created: ${info.ctime.toISOString()}`);
}

if (info.mediaType) {
  console.log(`Media Type: ${info.mediaType}`);
}

if (info.ftpperms) {
  console.log(`Permissions: ${info.ftpperms}`);
}

​
Filter Files by Size

const entries = await client.extendedList();
const largeFiles = entries
  .filter(([name, info]) => info.isFile && info.size > 1000000)
  .map(([name, info]) => ({ name, size: info.size }));

console.log('Files larger than 1MB:');
largeFiles.forEach(file => {
  console.log(`${file.name}: ${file.size} bytes`);
});

​
Sort Files by Modification Time

const entries = await client.extendedList();
const sortedFiles = entries
  .filter(([name, info]) => info.isFile && info.mtime)
  .sort(([, a], [, b]) => {
    return (b.mtime?.getTime() ?? 0) - (a.mtime?.getTime() ?? 0);
  });

console.log('Files sorted by most recent:');
sortedFiles.forEach(([name, info]) => {
  console.log(`${name}: ${info.mtime?.toISOString()}`);
});

​
Server Compatibility

The availability of specific fields depends on FTP server capabilities:
  • MLST/MLSD support: Servers that support these commands (RFC 3659) provide the most detailed metadata including ftpType, ftpperms, mediaType, and Unix-style attributes.
  • Limited support: Servers without MLST support will have fewer fields populated, typically just size, mtime, isFile, and isDirectory.
  • Field values: Many fields may be null if the server doesn’t provide that specific information.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us