A cross-platform native Node.js module for retrieving filesystem metadata including mount points, volume information, and space utilization statistics.
Built and supported by PhotoStructure.
- List all mounted volumes/drives on the system
- Get detailed volume metadata including:
- Total size, used space, and available space
- Filesystem type and volume label
- Volume UUID (when available)
- Remote/network share information
- Cross-platform support:
- Windows (x64, arm64)
- macOS (x64, arm64)
- Linux (x64, arm64)
- Written in modern TypeScript with full type definitions for both ESM and CommonJS consumers
- Native async implementation to avoid blocking the event loop
- Promise-based async API
- Comprehensive test coverage
npm install @photostructure/fs-metadataimport { getVolumeMountPoints, getVolumeMetadata } from "@photostructure/fs-metadata";
// List all mounted volumes
const mountPoints = await getVolumeMountPoints();
console.dir({ mountPoints });
// Example output: ['C:\\', 'D:\\'] on Windows
// Example output: ['/', '/home', '/Users'] on Unix-like systems
// Get metadata for a specific volume
const metadata = await getVolumeMetadata("C:\\"); // Windows
// Or for Unix-like systems:
// const metadata = await getVolumeMetadata('/');const { getVolumeMountPoints, getVolumeMetadata } = require("@photostructure/fs-metadata");
// Usage is the same as ESMAPI documentation is available:
-
On GitHub Pages
-
In the repository after running:
npm run docs
This document details the behavior differences between Windows, macOS, and Linux when using the filesystem metadata library.
- Mount points are drive letters with trailing backslash (e.g.,
C:\,D:\) - Network shares appear as mounted drives with UNC paths
- Volume GUIDs are available through Windows API
- Hidden and system volumes may be included
- Uses forward slashes for paths (e.g.,
/,/Users) - Network shares mounted at
/Volumes/ - APFS and HFS+ filesystems supported
- Volume UUIDs available through DiskArbitration framework
- Time Machine volumes detected and handled appropriately
- Uses forward slashes for paths (e.g.,
/,/home) - Network mounts (NFS/CIFS) handled through mount table
- Multiple mount tables supported (
/proc/mounts,/etc/mtab) - UUID detection via libblkid
- Optional GIO support for additional mount detection
- Size information from GetDiskFreeSpaceEx
- Volume information (label, filesystem) from GetVolumeInformation
- Remote status from GetDriveType
- UNC path parsing for network shares
- Size calculations via statvfs
- Volume details through DiskArbitration framework
- Network share detection via volume characteristics
- Time Machine volume detection
- Size information from statvfs
- Filesystem type from mount table
- Block device metadata via libblkid
- Network filesystem detection from mount options
- Optional GIO integration for additional metadata
- NTFS
- FAT32
- exFAT
- ReFS
- Network shares (CIFS/SMB)
- APFS (default since macOS High Sierra)
- HFS+ (legacy)
- FAT32
- exFAT
- Network shares (AFP, SMB, NFS)
- ext2/3/4
- XFS
- Btrfs
- ZFS
- Network filesystems (NFS, CIFS)
- Pseudo filesystems (procfs, sysfs) - excluded by default
- None by default
/dev/dev/fd- System volume internal mounts
/proc/sys/dev/run- Snap mounts
- Other virtual filesystems
- UNC paths parsed for host/share information
- SMB/CIFS protocol support
- Network status via GetDriveType
- AFP and SMB protocol support
- Network status via volume characteristics
- Host/share parsing from mount URLs
- NFS and CIFS support
- Network detection from filesystem type
- Remote info parsed from mount spec
- Default timeout: 15 seconds
- Longer timeouts needed for network operations
- Drive letter enumeration is fast
- Volume metadata queries may block
- Default timeout: 5 seconds
- DiskArbitration queries are generally fast
- Network volume operations may be slow
- Default timeout: 5 seconds
- Mount table parsing is fast
- Block device operations may block
- GIO operations are asynchronous
- Access denied errors for restricted volumes
- Network timeout errors for disconnected shares
- Invalid drive letter errors
- DiskArbitration framework errors
- Network disconnection handling
- Volume unmount detection
- Mount table parsing errors
- Block device access errors
- GIO operation failures
- Network filesystem timeouts
Common options across platforms:
- Timeout duration
- Excluded mount point patterns
- Directory-only filter
Platform-specific options:
- Linux: Mount table path selection
- Linux: GIO support enable/disable
- Windows: Network share handling
- macOS: Time Machine volume handling
- Use default timeout (15s) for network shares
- Handle access denied errors gracefully
- Check drive type before operations
- Monitor volume mount/unmount notifications
- Handle Time Machine volumes appropriately
- Check network status before operations
- Use default mount table when possible
- Enable GIO support if available
- Handle remote filesystem timeouts
Requirements:
- Supported Node.js version
- Python 3
- C++ build tools:
- Windows: Visual Studio Build Tools
- macOS: Xcode Command Line Tools
- Linux: GCC and development headers
# Clone the repository
git clone https://github.com/photostructure/fs-metadata.git
cd fs-metadata
# Install dependencies
npm install
# Run tests
npm testMIT
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests and documentation as appropriate.
This project uses AI-powered tools like GitHub Copilot and Claude to assist with development, but all code is reviewed, tested, and validated by human developers. The core implementation, architecture, and maintenance remain the responsibility of the human development team.
If you discover a security vulnerability, please send an email to [email protected]