@photostructure/fs-metadata

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.

Features

• Cross-platform support:

  • Windows 10+ (x64, arm64)
  • macOS 14+ (x64, arm64)
  • Ubuntu 22+ (x64, arm64) (with Gnome GIO/GVfs mount support when available)

• List all mounted volumes/drives

• Get detailed volume metadata

• File and directory hidden attribute support:

  • Get and set hidden attributes
  • POSIX-style support (macOS and Linux)
  • Filesystem metadata support (macOS and Windows)
  • Recursive hidden checks
  • Hidden metadata queries

• ESM and CJS support

• Full TypeScript type definitions

• Non-blocking async native implementations

• Timeout handling for wedged network volumes

• Compatible with all current Node.js and Electron versions via Node-API v9 and prebuildify

• Comprehensive test coverage

Installation

npm install @photostructure/fs-metadata

Usage

import {
  getVolumeMountPoints,
  getVolumeMetadata,
} from "@photostructure/fs-metadata";

// List all mounted volumes
const mountPoints = await getVolumeMountPoints();
console.dir({ mountPoints });

// Get metadata for a specific volume
const volumeMetadata = await getVolumeMetadata(mountPoints[0]);
console.dir({ volumeMetadata });

If you're using CommonJS:

const {
  getVolumeMountPoints,
  getVolumeMetadata,
} = require("@photostructure/fs-metadata");

// Usage is the same as the ESM example above 
// (except of course no top-level awaits!)

API

Read the API here

Options

Debug Logging

Set NODE_DEBUG=fs-meta or NODE_DEBUG=photostructure:fs-metadata. The native debuglog determines if debug logging is enabled. Debug messages from both JavaScript and native code are sent to stderr.

Timeouts

Operations use a default timeout, which may need adjustment for slower devices like optical drives (which can take 30+ seconds to spin up).

Windows can block system calls when remote filesystems are unhealthy due to host downtime or network issues. To handle this, we use a separate thread per mountpoint to check volume health status. While this approach uses more resources than the async N-API thread, it enables reliable timeouts for operations that would otherwise hang indefinitely.

Timeout duration may apply per-operation or per-system call, depending on the implementation.

System Volumes

Each platform handles system volumes differently:

• Windows provides explicit metadata for "system" or "reserved" devices, though C:\ is both a system volume and typical user storage
• Linux and macOS include various system-only mountpoints: pseudo devices, snap loopback devices, virtual memory partitions, and recovery partitions

This library uses heuristics to identify system volumes. See Options for default values and customization.

Note: getAllVolumeMetadata() returns all volumes on Windows but only non-system volumes elsewhere by default.

License

This project is licensed under the MIT License.

Contributing

We welcome contributions! Please see our Contributing Guide for more details.

Security

For security-related issues, please refer to our Security Policy.